From d8f4f31ea1c9fd391da94d20b415c7741f94a6c7 Mon Sep 17 00:00:00 2001
From: Sam Sung <51686767+samwhosung@users.noreply.github.com>
Date: Fri, 25 Sep 2026 19:06:42 +0700
Subject: [PATCH] Comments in benilla-app, the player, entities, animation and
 targeting: one line of fact each, no history, no record numbers (#328)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Part of #41: the third of five `benilla-app` pieces. This one is the player, the entities, animation and targeting: the mover, the camera, movement on the wire, the body and creature animation drivers, spell visuals, equipment and corpses, and the target, cursor and by-name layers. Their comments are rewritten to the rule in `docs/METHOD.md`, which is what the code does and the reference fact behind it, in a line. 26,066 comment lines become 9,042.

Fixes #104. Fixes #108. Fixes #109.

- **The mechanical strip.** The citations that were only a private record number go first, and each edit is shown to be a pure removal.
- **Wrong facts corrected.** The rewrite corrects the comments that stated wrong facts. Among them:
  - The follow gate's `0x606ba0` is `CanCooperate` (a faction-group-mask test), not `CanAssist` (`0x6066f0`).
  - The facing report is sent from the move-command drain (`0x615fc6`); `0x617100`/`0x617170` are the transport-GUID heartbeat.
  - vmangos turns a corpse into bones under the corpse's own guid (`Map.cpp:3608-3649`), and the bones get new flags and zeroed item slots.
  - Two claims about the item models are refuted by the shipped data: not every helm stem ships all sixteen race and sex files, and some item emitters sit under a keyed billboard chain.
  - Docs sitting on the wrong item, stale function names, and disassembler labels, which become client addresses.
  - vmangos line citations are checked against the pinned vmangos revision.
- **Deviation labels.** "Deviation:" now marks only a choice with a reason. An unbuilt behaviour, or one whose reference side is untraced, says so plainly.
- **Verification.** Every file strips to identical code, and `cargo fmt --check` is clean. Six second readers compared every file old against new, restored the facts the rewrite had dropped, and checked each new citation against the code, the shipped data, vmangos and the reference.

Behaviour differences the rewrite surfaced are filed as their own issues (#293, #294, #301, #308, #316 and #317 among them). The comments here state what the code does. String literals are untouched; they are #92.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 crates/benilla-app/src/aura_visual.rs         |  496 ++----
 crates/benilla-app/src/aura_visual/tests.rs   |  172 +-
 crates/benilla-app/src/creature_anim.rs       | 1003 +++--------
 crates/benilla-app/src/creature_anim/blood.rs |   77 +-
 .../benilla-app/src/creature_anim/breath.rs   |  169 +-
 .../benilla-app/src/creature_anim/driver.rs   |  947 +++-------
 .../src/creature_anim/driver/grip.rs          |   16 +-
 .../src/creature_anim/driver/mode.rs          |  327 +---
 .../src/creature_anim/driver/play.rs          |  244 +--
 .../src/creature_anim/driver/tests.rs         |  877 +++------
 .../src/creature_anim/driver/wound.rs         |   85 +-
 .../src/creature_anim/emote_anim.rs           |  107 +-
 .../src/creature_anim/env_damage.rs           |   62 +-
 .../benilla-app/src/creature_anim/events.rs   |  281 +--
 .../benilla-app/src/creature_anim/gesture.rs  |  105 +-
 .../benilla-app/src/creature_anim/impact.rs   |  196 +--
 crates/benilla-app/src/creature_anim/lod.rs   |  202 +--
 crates/benilla-app/src/creature_anim/net.rs   |  144 +-
 .../benilla-app/src/creature_anim/select.rs   |  878 ++-------
 .../src/creature_anim/select/tests.rs         |  308 ++--
 .../benilla-app/src/creature_anim/sheath.rs   |  245 +--
 .../src/creature_anim/spell_visual.rs         |  953 +++-------
 .../src/creature_anim/spell_visual/tests.rs   |  299 ++--
 crates/benilla-app/src/creature_anim/twist.rs |  123 +-
 crates/benilla-app/src/entities.rs            |  773 +++-----
 .../src/entities/attach/char_skin.rs          |  217 +--
 .../benilla-app/src/entities/attach/dress.rs  |  338 +---
 .../benilla-app/src/entities/attach/merge.rs  |  101 +-
 crates/benilla-app/src/entities/attach/mod.rs |  691 ++------
 .../src/entities/attach/preview.rs            |  486 ++---
 .../src/entities/attach/redress.rs            |  168 +-
 .../benilla-app/src/entities/carried_light.rs |   57 +-
 crates/benilla-app/src/entities/chain_beam.rs |  398 ++---
 .../src/entities/collision_height.rs          |  136 +-
 crates/benilla-app/src/entities/conform.rs    |   95 +-
 crates/benilla-app/src/entities/corpse.rs     |  198 +--
 crates/benilla-app/src/entities/dest_fx.rs    |  139 +-
 crates/benilla-app/src/entities/display.rs    |  453 ++---
 .../benilla-app/src/entities/equipment/mod.rs |  245 +--
 .../src/entities/equipment/resolve.rs         |  461 ++---
 .../src/entities/equipment/spawn.rs           |  616 ++-----
 crates/benilla-app/src/entities/item_glow.rs  |  169 +-
 .../benilla-app/src/entities/live_display.rs  |  145 +-
 crates/benilla-app/src/entities/missile.rs    |  480 ++---
 crates/benilla-app/src/entities/mount.rs      |  183 +-
 .../benilla-app/src/entities/mount/tests.rs   |   60 +-
 .../src/entities/spell_fx/lifecycle.rs        |  166 +-
 .../benilla-app/src/entities/spell_fx/mod.rs  |  622 ++-----
 crates/benilla-app/src/entities/wmo_props.rs  |  271 +--
 crates/benilla-app/src/go_anim.rs             | 1002 +++--------
 crates/benilla-app/src/player.rs              |  365 ++--
 crates/benilla-app/src/player/arc.rs          |  164 +-
 crates/benilla-app/src/player/body_pose.rs    |   91 +-
 crates/benilla-app/src/player/camera.rs       | 1400 ++++-----------
 .../benilla-app/src/player/camera_channel.rs  |  161 +-
 .../benilla-app/src/player/camera_dynamics.rs |  620 ++-----
 crates/benilla-app/src/player/camera_saved.rs |  158 +-
 crates/benilla-app/src/player/camera_view.rs  |  273 +--
 crates/benilla-app/src/player/camera_water.rs |  219 +--
 crates/benilla-app/src/player/controller.rs   |  770 ++------
 crates/benilla-app/src/player/drunk.rs        |   81 +-
 crates/benilla-app/src/player/embody.rs       |  120 +-
 crates/benilla-app/src/player/flags.rs        |  190 +-
 crates/benilla-app/src/player/follow.rs       |  305 +---
 crates/benilla-app/src/player/gait.rs         |   56 +-
 crates/benilla-app/src/player/input.rs        |  188 +-
 crates/benilla-app/src/player/land.rs         |   48 +-
 crates/benilla-app/src/player/move_trace.rs   |  217 +--
 crates/benilla-app/src/player/movement_net.rs |  606 ++-----
 crates/benilla-app/src/player/mover.rs        | 1442 ++++-----------
 crates/benilla-app/src/player/net.rs          |    8 +-
 crates/benilla-app/src/player/posture.rs      |  145 +-
 crates/benilla-app/src/player/ride.rs         |   88 +-
 crates/benilla-app/src/player/scoped_view.rs  |   61 +-
 crates/benilla-app/src/player/server_ride.rs  |  241 +--
 crates/benilla-app/src/player/setup.rs        |  118 +-
 crates/benilla-app/src/player/state.rs        | 1564 ++++-------------
 crates/benilla-app/src/player/step_probe.rs   |  101 +-
 crates/benilla-app/src/player/swim.rs         |  569 ++----
 crates/benilla-app/src/player/view_subject.rs |  100 +-
 crates/benilla-app/src/player/walk.rs         |   78 +-
 crates/benilla-app/src/player/wire_in.rs      |  567 ++----
 crates/benilla-app/src/player/world_focus.rs  |  200 +--
 crates/benilla-app/src/quest_markers/mod.rs   |  353 ++--
 crates/benilla-app/src/quest_markers/query.rs |  441 ++---
 crates/benilla-app/src/target/by_name.rs      |  352 ++--
 crates/benilla-app/src/target/click.rs        | 1162 +++---------
 crates/benilla-app/src/target/cursor_mode.rs  |  769 ++------
 crates/benilla-app/src/target/flash.rs        |   79 +-
 crates/benilla-app/src/target/highlight.rs    |   55 +-
 crates/benilla-app/src/target/hover.rs        |  499 ++----
 crates/benilla-app/src/target/hover_probe.rs  |  111 +-
 crates/benilla-app/src/target/lock.rs         |  326 ++--
 crates/benilla-app/src/target/mod.rs          |  415 ++---
 crates/benilla-app/src/target/relations.rs    |  139 +-
 crates/benilla-app/src/target/reticle.rs      |  120 +-
 crates/benilla-app/src/target/ring.rs         |  666 ++-----
 crates/benilla-app/src/target/scan.rs         |  766 ++------
 98 files changed, 8757 insertions(+), 25796 deletions(-)

diff --git a/crates/benilla-app/src/aura_visual.rs b/crates/benilla-app/src/aura_visual.rs
index 7f4c01f2..177ace8b 100644
--- a/crates/benilla-app/src/aura_visual.rs
+++ b/crates/benilla-app/src/aura_visual.rs
@@ -1,101 +1,21 @@
-//! **The aura-state CharProc layer** — what an aura does to the *body itself*: its translucency, its
-//! tint and its animation clock, for exactly as long as the aura lives. This is the half of a stage-2
-//! "state kit" that
-//! isn't an attach-point emitter (those are `creature_anim::spell_visual`'s
-//! [`arm_aura_state_fx`](crate::creature_anim::arm_aura_state_fx), decision 0393): where that
-//! watcher hangs *models* on the unit, this one changes how the unit's own model **renders**.
+//! The aura-state CharProc layer: what an aura does to its unit's own body (translucency, tint,
+//! animation clock) while it lives; the kit's attach-point models are
+//! [`arm_aura_state_fx`](crate::creature_anim::arm_aura_state_fx)'s.
 //!
-//! B114 ("Stealth shows nothing on the character") was this whole layer missing. Stealth's state
-//! 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.
+//! In the reference an aura slot change (`0x604d00` → `0x6123f0`) reaches `0x5ff350`, which plays
+//! the spell's state kit (`SpellVisual` field 4) at stage 2, and the kit's tail (`0x60f35c`) runs
+//! the CharProc dispatcher `0x60d7c0` over its four proc slots (`SpellVisualKit` fields 15-34).
+//! Three procs act on the body: 14 installs an alpha node (`0x60d972`), 1 a tint node
+//! (`0x60d840`), 11 an animation rate (`0x60db7e`). A node is keyed by spell id and linked at the
+//! head of its list, only the head counts, and the aura's removal drops its spell's nodes
+//! (`0x5ff290`).
 //!
-//! ## The mechanism
+//! `UNIT_FIELD_BYTES_1` byte 3's stealth and ghost bits drive no body render in the reference: its
+//! readers (`0x5ff80d`, `0x607101`, `0x60f62e`) only suppress nameplates and markers. The body
+//! keys on the aura, never on the flag.
 //!
-//! `UNIT_FIELD_AURA` slot change → the aura watcher `0x604d00` → `0x6123f0` → **`0x5ff350`
-//! PlayAuraStateVisual**: the slot's spell → `Spell.dbc` → `SpellVisual` → **field 4 = the state
-//! kit** → `PlaySpellVisualKit(kit, stage 2)`, whose tail (`0x60f358: push esi(kit);
-//! 0x60f35c: call 0x60d7c0`) runs the **CharProc dispatcher** over the kit's four proc slots
-//! (`SpellVisualKit` fields 15–34 — `benilla_formats::CharProc`). Two of the dispatcher's nine cases
-//! act on the body:
-//!
-//! - **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 — `baseAlpha` from the
-//!   vtbl+0x6c getter `0x60d2d0` (`CreatureDisplayInfo+0x14 × 1/255`, the SAME slot in the unit
-//!   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`
-//!   (`0x614baa → 0x710cb0`), which multiplies into the per-batch alpha (`0x707680`).
-//!   The recompute has a second, aura-free caller: the DISPLAYID watcher's refresh (`0x60abe0 →
-//!   0x60ad9f`), which is how a display whose row says `CreatureModelAlpha < 255` — Ghost Wolf's
-//!   4613 = 102 — renders translucent by itself; [`refresh_base_alpha`] is that leg.
-//! - **proc 1 = tint** (`0x60d840`): `round(param)` is a packed `0x00RRGGBB` OR'd with `0xff000000`
-//!   into a tint node (list `unit+0xce0`); per frame the head node goes `×1/255` into
-//!   `model+0x184/188/18c`.
-//!
-//! Removal is the mirror image: the aura leaves the slot → `0x5ff290` drops that spell's nodes and
-//! recomputes, so the alpha **ramps back** to the new target over the same 1000 ms.
-//!
-//! 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 (`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)
-//!
-//! 185 of 1772 kits carry a CharProc, and the **state** stage is far and away their home: 103 state
-//! kits, ~1200 (spell, proc) pairs. Proc 14 covers **11 kits / 135 spells** — kit 312 `0.3` is the
-//! whole sneak family (Stealth 1784-1787, Prowl, Vanish, Shadowmeld, Hide, Sneak, Disguise), kit
-//! 3450 `0.5` is Invisibility/Fade, kit 989 `0.5` the ghost aura, 3129 `0.65` Shadowform, 1286 `0.3`
-//! Banish, 3989 `1.0` Possess, 5129 `0.0` a quest fade-out. Proc 1 covers 73 state kits (~800
-//! spells): Frostbolt's chill blue, Immolate's ember orange, the poison green.
-//!
-//! ## What is built here, and what is not
-//!
-//! **Proc 14 ships whole** — nodes, the `baseAlpha × head node` target, the 1000 ms cubic ramp both ways,
-//! and the render composition below.
-//!
-//! **Proc 1 ships too** (decision 0812): its nodes live here ([`AuraNodes::tint`], head-node-wins as
-//! the reference's `unit+0xce0` list is) and [`apply_aura_tint`] publishes the head to
-//! [`benilla_world::instance_tint`], the per-instance modulate channel keyed on the part's rig slot. Written
-//! on change, never eased — the reference's own asymmetry (`unit+0xd04` change-detection straight to
-//! `0x710cf0`, with none of the alpha's 1000 ms ramp).
-//!
-//! 0806 recorded this as blocked on a render-architecture call between per-unit material clones and a
-//! tag-indexed palette. That framing was wrong on its own terms: the `MeshTag` rig field already IS a
-//! per-instance slot into the shared light buffer, so the tint needed **no** new tag bits (which was
-//! the whole stated blocker — the payload has 5 spare bits outdoors and zero indoors) and no material
-//! churn. What it did need was reading our own renderer properly.
-//!
-//! The tint reaches a unit **whole** — the reference's `0x714000` recursion, where an attached model
-//! composes onto its parent CM2's computed colours — by two routes, because benilla has two kinds of
-//! attached model:
-//!
-//! - the ordinary one **borrows its wearer's slot**: an item's parts, cards and boneless geosets all
-//!   spawn carrying the unit's instance bits (decision 0820), so they read the unit's table entry;
-//! - a **rigged** one carries its OWN slot, because the vertex stage indexes the skin palette with
-//!   that same field and cannot borrow it (a spell-effect instance; since 0841, the seven shoulder
-//!   models that weld geometry to a billboard bone). [`chained_tint`] walks such an instance's
-//!   [`benilla_world::model_fade::ParentModel`] link up to the unit — the recursion itself, and the same walk
-//!   `ModelAlphas` already does for alpha.
-//!
-//! **Proc 11 ships too** (decisions 0889 + 0891): the **freeze**. Its param is a playback *rate*
-//! written onto the unit's own animation clocks (`0x60db7e` → `SetBoneAnimSpeed 0x712910` on the
-//! mount's bone 0, the body's key-bone 4 — the upper-body split — and the body's bone 0), old rates
-//! saved in the node and written back when it expires (`0x6203e0`). Rate 0 is Ice Block: the pose
-//! holds exactly where it was, *including* a cast one-shot that had just been armed, which is why the
-//! caster never gets to raise their hand. [`apply_aura_anim_rate`] is that leg — and it expresses
-//! rate 0 as a **pause**, not as a speed, because the reference's rate belongs to a bone while a speed
-//! here belongs to a clip that other code copies from ([`AnimRateFreeze`] carries the story).
-//!
-//! 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 mechanism is known.
+//! Proc types 2, 7 and 13 also appear on state kits; their mechanism is untraced, so [`node_for`]
+//! ignores them.
 
 use benilla_protocol::EntityKind;
 use bevy::mesh::MeshTag;
@@ -105,75 +25,51 @@ use benilla_assets::materials::WowModelMaterial;
 use benilla_world::interior::InteriorLit;
 use benilla_world::model_fade::{fade_alpha, FadeMaterials, PendingAppearFade, RenderFade};
 
-/// The reference's aura-alpha ramp: `StartAlphaFade(target, **1000 ms**)` (`0x614f80` from
-/// `0x60d180`'s recompute), eased `clamp01(t)³` by `0x614a90` — [`fade_alpha`] is that curve.
-///
-/// It is a **code constant, not a kit column**: proc 14's `params[1..]` are `[2.0, 1000.0, 0.0]` on
-/// the sneak kit but `[0.0, 0.0, 0.0]` on the ghost's, and the ghost's ramp is byte-cited at the same
-/// 1000 ms — so the sneak kit's literal `1000.0` cannot be the source (a data-sourced duration would
-/// snap the ghost instantly). Across the whole shipped table proc 14's `params[2]` is only ever
-/// `0.0`, `2.0` or `1000.0`, which is no duration scale in any unit. Read from `params[0]` only.
+/// The aura-alpha ramp, `StartAlphaFade(target, 1000 ms)` (`0x614f80`) eased `clamp01(t)³` by
+/// [`fade_alpha`] (`0x614a90`). A code constant, not a kit column: the ghost kit's proc 14 carries
+/// no `1000.0` yet ramps over the same second.
 pub(crate) const AURA_ALPHA_FADE_SECS: f32 = 1.0;
 
-/// Settled-ramp epsilon — under half a step of the tag's 6-bit alpha field (1/64), so a ramp that
-/// has visually arrived is treated as arrived.
+/// Under half a step of the tag's 6-bit alpha field (1/64): a ramp this close has arrived.
 const ALPHA_EPS: f32 = 1.0 / 128.0;
 
-/// One CharProc node the dispatcher installed on a unit, keyed by the aura's spell id exactly as the
-/// reference keys `node+0x18`. Held in [`AuraNodes`]; a `Reap` for that spell id removes it.
+/// One CharProc node a kit installs on a unit, keyed by spell id as the reference keys `node+0x18`.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub(crate) enum AuraNode {
-    /// Proc 14: this aura's alpha factor (`node+0x78`) — the target's node term while it is the head.
+    /// Proc 14: the alpha factor (`node+0x78`).
     Alpha(f32),
-    /// Proc 1: this aura's body tint, unpacked from the param's `0x00RRGGBB`. Modelled, not yet
-    /// rendered (module docs).
+    /// Proc 1: the body tint, unpacked from the param's `0x00RRGGBB`.
     Tint([u8; 3]),
-    /// Proc 11: this aura's animation playback **rate** for the unit's own model — `0.0` for every
-    /// member of the freeze family (Ice Block, Freeze, Petrify, Entangle, Stilled).
+    /// Proc 11: the playback rate of the unit's own clocks, `0.0` for the whole freeze family.
     AnimRate(f32),
 }
 
-/// The CharProc node lists of one unit — the ECS twin of the reference's per-unit `unit+0xb50`
-/// (alpha) and `unit+0xce0` (tint) lists, plus the ramp `0x614f80` drives from their heads.
-///
-/// Lives on the **net entity root**, like [`benilla_world::entity_shade::GroundShade`]: the reference has one
-/// of these per CGUnit and every attached model (held item, helm, shoulder) renders off the owner's,
-/// which is also why [`apply_aura_alpha`] walks the root's whole descendant tree rather than its
-/// direct children.
+/// One unit's CharProc node lists (the reference's `unit+0xb50` alpha and `unit+0xce0` tint lists)
+/// and its alpha ramp. On the net entity root: the reference keeps one per CGUnit, and every
+/// attached model renders off its owner's.
 #[derive(Component, Debug, Default)]
 pub(crate) struct AuraNodes {
-    /// `(spell id, factor)` — proc-14 nodes, newest at the front (the reference links a fresh node
-    /// at the list head). The HEAD times [`Self::base`] is the target — never a product.
+    /// Proc-14 `(spell id, factor)` nodes, newest first, as the reference links at the head.
     alpha: Vec<(u32, f32)>,
-    /// `(spell id, rgb)` — proc-1 nodes, newest at the front like the alpha list; the head is what
-    /// the per-frame apply reads.
+    /// Proc-1 `(spell id, rgb)` nodes, newest first.
     tint: Vec<(u32, [u8; 3])>,
-    /// `(spell id, rate)` — proc-11 nodes, head-first like the other two. The head is the rate the
-    /// unit's animation clocks run at ([`apply_aura_anim_rate`]); empty = the clocks are the
-    /// driver's own again.
+    /// Proc-11 `(spell id, rate)` nodes, newest first; the head drives the unit's clocks.
     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.
-    /// 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.
+    /// `baseAlpha`, the display row's `CreatureModelAlpha / 255` for every unit, players included
+    /// (`0x60d2d0`); kept current by [`refresh_base_alpha`].
     base: f32,
-    /// Where the ramp is now — what the parts actually render at.
+    /// The ramp's live value, which the parts render at.
     current: f32,
-    /// The ramp: `from → to` over [`AURA_ALPHA_FADE_SECS`] from `started` (`Time::elapsed_secs`).
+    /// The ramp, `from` to `to` over [`AURA_ALPHA_FADE_SECS`] from `started` (elapsed seconds).
     from: f32,
     to: f32,
     started: f32,
-    /// Whether [`apply_aura_alpha`] still owns this unit's parts. Set while the unit is translucent
-    /// and for the one frame the ramp latches back at opaque — that frame performs the **release**
-    /// (writes the settled alpha and hands the material back to the part's light law), the same
-    /// hand-back protocol the self-avatar feather uses (decision 0213). Without it, a unit whose
-    /// stealth drops stays latched on the blend twin at its last low alpha until something else
-    /// happens to rewrite the channel.
+    /// Whether [`apply_aura_alpha`] owns this unit's parts: while translucent, plus the one frame
+    /// at opaque that writes the settled alpha and hands the material back to its light law.
     authoring: bool,
 }
 
 impl AuraNodes {
-    /// A fresh node set for a unit whose `baseAlpha` is `base`, ramp settled at `base`.
     fn new(base: f32) -> Self {
         Self {
             base,
@@ -184,18 +80,15 @@ 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. Nodes are linked at the head as they install, so the newest one is the term that
-    /// counts.
+    /// `0x60d180`: `baseAlpha` times the head alpha node's factor alone, never a product over the
+    /// list; an empty list leaves `baseAlpha` (`0x60d195`).
     fn target(&self) -> f32 {
         let head = self.alpha.first().map_or(1.0, |(_, f)| *f);
         (self.base * head).clamp(0.0, 1.0)
     }
 
-    /// Point the ramp at the current target, from wherever it is now. A no-op when the target
-    /// hasn't moved, so an aura refresh (or a node whose factor equals the live one) doesn't restart
-    /// the ease.
+    /// Aim the ramp at the target from where it is now; an unmoved target leaves it alone, so an
+    /// aura refresh does not restart the ease.
     fn retarget(&mut self, now: f32) {
         let target = self.target();
         if (target - self.to).abs() <= f32::EPSILON {
@@ -206,34 +99,27 @@ impl AuraNodes {
         self.started = now;
     }
 
-    /// Advance the ramp to `now` and return the live alpha.
     fn tick(&mut self, now: f32) -> f32 {
         let t = (now - self.started) / AURA_ALPHA_FADE_SECS;
         self.current = fade_alpha(self.from, self.to, t);
         self.current
     }
 
-    /// Whether the unit renders translucent right now (the ramp has arrived at, or is heading
-    /// anywhere below, opaque).
     fn translucent(&self) -> bool {
         self.current < 1.0 - ALPHA_EPS
     }
 
-    /// The head tint node's RGB — the reference's `unit+0xce0` head, which its per-frame apply reads
-    /// (`0x60cbd9`). `None` when the unit carries no tint aura. Published to the render channel by
-    /// [`apply_aura_tint`].
+    /// The head tint node's RGB, which the reference's per-frame apply reads (`0x60cbd9`).
     pub(crate) fn head_tint(&self) -> Option<[u8; 3]> {
         self.tint.first().map(|(_, rgb)| *rgb)
     }
 
-    /// The head proc-11 node's rate — what this unit's animation clocks are being held at, or `None`
-    /// when no freeze aura is on it. Head-node-wins like the other two lists.
+    /// The head proc-11 node's rate, the one the unit's clocks run at.
     pub(crate) fn head_anim_rate(&self) -> Option<f32> {
         self.rate.first().map(|(_, r)| *r)
     }
 
-    /// A node list holding one proc-11 rate node — the state a freeze aura leaves on a unit, for
-    /// the driver's wound-refusal tenant (decision 2063) without running the aura-slot watcher.
+    /// A node set holding one proc-11 node, as a freeze aura leaves it, without the slot watcher.
     #[cfg(test)]
     pub(crate) fn with_rate_node_for_tests(spell_id: u32, rate: f32) -> Self {
         Self {
@@ -243,20 +129,9 @@ impl AuraNodes {
     }
 }
 
-/// Publish every rig's body tint to the per-instance channel ([`benilla_world::instance_tint`], decision
-/// 0812): the head node's RGB packed the reference's way, keyed on the unit's rig slot — the slot
-/// each of its skinned parts already carries in its `MeshTag`, and which the fragment stage reads to
-/// index the table.
-///
-/// **On change, not eased** — the reference's own asymmetry between the two node lists: the alpha
-/// gets a 1000 ms cubic ramp (`0x614f80`), the tint goes straight in on change-detection
-/// (`unit+0xd04` → `0x710cf0`). `InstanceTints::set` is idempotent, so the steady state costs one
-/// compare per rig and never touches the upload.
-///
-/// Iterates every **`RigSkin`**, not every `AuraNodes`, deliberately: reasserting the whole table
-/// each frame means no edge can leak a stale colour into a recycled slot — not an `AuraNodes` that
-/// went away, not a unit whose last tint aura dropped. (The despawn/rebuild edge is covered
-/// structurally too, in `RigSkin`'s free hook.)
+/// Publish every rig's head tint to [`benilla_world::instance_tint`], keyed on its rig slot. The
+/// reference writes the tint as it changes, with none of the alpha's ramp (`unit+0xd04` →
+/// `0x710cf0`). Every `RigSkin` is rewritten each frame so a recycled slot never keeps a colour.
 pub(crate) fn apply_aura_tint(
     rigs: Query<(Entity, &benilla_world::rig_palette::RigSkin)>,
     chain: Query<(
@@ -282,15 +157,9 @@ pub(crate) fn apply_aura_tint(
     }
 }
 
-/// The tint a rig instance renders with: its own head node, else the nearest one **up its
-/// [`benilla_world::model_fade::ParentModel`] chain** — the reference's `0x714000` recursion, which composes
-/// an attached model's colours onto its parent's computed ones (the same walk [`ModelAlphas`] does
-/// for alpha, and the same law `mesh_tag` cites for why an item's parts carry their wearer's slot).
-///
-/// It exists because a rigged **item** carries its own instance slot rather than its wearer's
-/// (decision 0841 — the vertex stage indexes the palette with that field, so it cannot be borrowed):
-/// without the walk, a dwarf's Stoneform tint would stop at exactly the pauldrons the rig was added
-/// for. A despawned link ends the walk.
+/// The tint a rig renders with: its own head node, else the nearest up its
+/// [`benilla_world::model_fade::ParentModel`] chain, as the reference composes an attached model's
+/// colours onto its parent's (`0x714000`); only this walk reaches a rigged item's own slot.
 fn chained_tint(
     chain: &Query<(
         Option<&AuraNodes>,
@@ -311,16 +180,9 @@ fn chained_tint(
     None
 }
 
-/// `WOW_TINT_PROBE=RRGGBB` — paint **every live rig slot** that colour, auras ignored.
-///
-/// The one machine check for the GPU half of the channel: the region upload, the fragment stage's
-/// slot lookup, the unpack, and the placement of the multiply. No headless test can reach any of
-/// that, and the capture harness cannot stage a real aura to do it with — it sees no networked
-/// entities at all (0799), so a tinted *unit* is unstageable there. Pointed at a scene with animated
-/// (rigged) doodads it turns each of them the probe colour, which the visual harness then diffs.
-///
-/// It logs the slot count once, so an unchanged capture reads as "nothing in this scene is rigged"
-/// rather than as "the channel is broken" — the two are indistinguishable from the image alone.
+/// `WOW_TINT_PROBE=RRGGBB` paints every live rig slot that colour, auras ignored: the machine check
+/// for the GPU half of the tint channel. It logs the slot count once, since an unchanged capture
+/// cannot tell "nothing is rigged" from "the channel is broken".
 fn tint_probe() -> Option<[u8; 3]> {
     static PROBE: std::sync::OnceLock<Option<[u8; 3]>> = std::sync::OnceLock::new();
     *PROBE.get_or_init(|| {
@@ -335,54 +197,21 @@ fn tint_probe() -> Option<[u8; 3]> {
     })
 }
 
-/// Marker: this rig's clocks are being held by a proc-11 aura, so the release knows to let them go.
-///
-/// It carries **nothing**, and that is the fix for the first shipped version's bug. That one stored
-/// the speed of every clip it took over and wrote the values back on release — the reference's own
-/// `+0x60`/`+0x64`/`+0x68` save/restore, transliterated one level too low. It cannot work here,
-/// because in the reference a rate belongs to a *bone* (one value, saved once, and clips armed later
-/// never carry one) while ours would have to belong to a *clip*, and clips get armed under the freeze
-/// carrying values copied from other, already-frozen clips. `transplant_up` is exactly that: moving a
-/// one-shot to the torso overlay copies the source clip's speed, which under the freeze was `0`, so
-/// the overlay was saved at `0`, restored to `0`, and never advanced again — a cast pose welded to the
-/// upper body for the rest of the session, surviving every later cast (it never *finished*, so the
-/// overlay never released). Pausing owns no value and so cannot poison one.
+/// Marker: a proc-11 aura holds this rig's clocks. It saves no speeds, unlike the reference's
+/// per-bone save and restore (`0x6203e0`): here a rate belongs to a clip, and `transplant_up` arms
+/// clips under the freeze with speeds copied from frozen ones, so a saved speed restores as 0.
 #[derive(Component, Default, Debug)]
 pub(crate) struct AnimRateFreeze;
 
-/// Hold the clocks of every unit whose head proc-11 node says so — its own rig and its mount's
-/// (`[unit+0xd8]` and `[unit+0xdc]`, the two models `0x6201d0` writes) — and let them go when the aura
-/// does.
+/// Pause the clocks of every unit whose head proc-11 rate is 0, its own rig and its mount's (the
+/// two models `0x6201d0` writes), and resume them when the aura goes; effect models and global
+/// sequences keep running. The pause is reasserted every frame, since the reference's rate lives
+/// on the bone (`+0xb0`, read by the clock at `0x71458e`) and arming leaves it alone
+/// (`0x7121a0`), and after the animation driver, so a cast armed this frame freezes too.
 ///
-/// **A rate of 0 is expressed as a PAUSE, not as `set_speed(0.0)`.** They are the same picture on
-/// screen (Bevy evaluates a paused animation at its frozen seek, exactly as `0x712910`'s `bias` rebase
-/// holds the reference's current frame) but not the same object: a pause is a bit the clock reads,
-/// where a speed is a *value* other code copies. `transplant_up` copies a clip's speed when it moves a
-/// one-shot to the torso overlay, and that is how the first version welded a cast pose to the upper
-/// body permanently — see [`AnimRateFreeze`] and decision 0891. Nothing here reads or writes a speed, so nothing can
-/// 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 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
-/// across every re-arm in between, and re-pausing each frame is how a per-clip flag says the same
-/// thing — including for clips armed *under* the freeze, which the reference freezes by construction.
-///
-/// It runs **after the driver**, so this frame's arms are already in — which is the whole Ice Block
-/// observable: the cast one-shot is armed and then frozen at the frame it was on, so the caster never
-/// gets to raise their hand.
-///
-/// **A non-zero rate does nothing** (and only kit 1744's `8947848.0` is one — a packed grey that
-/// landed in the rate column, on Stoned / Petrification / Thadius Spawn). Our clock is f32 seconds
-/// where the reference's is integer milliseconds with a modulo, so a rate that large is noise there
-/// and different noise here; there is no honest transliteration, and inventing one would be worse than
-/// saying so. Recorded, not special-cased.
-///
-/// What it deliberately does **not** touch: attached effect models (the ice block's own
-/// `icebarrier_state.mdx` keeps shimmering — the reference writes the unit's two models only) and
-/// global sequences (a different clock there, and a different writer here).
+/// Deviation: a non-zero rate is ignored, because the only one shipped (`8947848.0` on kit 1744, a
+/// packed grey in the rate column) is noise on the reference's integer-ms clock and has no faithful
+/// form on our f32-second one.
 pub(crate) fn apply_aura_anim_rate(
     units: Query<(
         Entity,
@@ -409,10 +238,7 @@ pub(crate) fn apply_aura_anim_rate(
                     }
                 }
                 (false, true) => {
-                    // Resume everything: the set we paused is "whatever was playing", and it grew
-                    // every frame the freeze held. Nothing else on a unit rig pauses an animation
-                    // (the portrait booth does, on its own rigs), so there is no third party's pause
-                    // to trample.
+                    // Resume every clip: nothing else pauses an animation on a unit rig.
                     for (_, anim) in player.playing_animations_mut() {
                         anim.resume();
                     }
@@ -425,12 +251,8 @@ pub(crate) fn apply_aura_anim_rate(
     }
 }
 
-/// The freeze's own instrument (`WOW_MOVE_TRACE`, tag `aur`): one line per rig at each edge, naming
-/// the clips it took over and the speed each is *left* running at — the difference between "the clocks
-/// stopped" and "nothing was playing anyway", which no count of *absent* anim events can tell apart.
-///
-/// It prints the speeds precisely because the first version's bug was invisible without them: a `@0`
-/// on the thaw line is a clip that will never advance again.
+/// Trace (`WOW_MOVE_TRACE`, tag `aur`) one line per rig at each freeze edge, with each clip's
+/// speed: a `@0` on a thaw line is a clip that will never advance again.
 fn trace_clock_edge(what: &str, rig: Entity, player: &AnimationPlayer) {
     if !benilla_assets::trace::enabled_for("aur") {
         return;
@@ -445,9 +267,7 @@ fn trace_clock_edge(what: &str, rig: Entity, player: &AnimationPlayer) {
     );
 }
 
-/// One aura's CharProc edge, written by the aura-slot watcher
-/// ([`crate::creature_anim::arm_aura_state_fx`], which owns the slot diff and the state-kit resolve
-/// for both halves of a kit) and drained by [`drain_aura_procs`].
+/// One aura's CharProc edge, from [`crate::creature_anim::arm_aura_state_fx`]'s slot watch.
 #[derive(Message, Clone, Debug)]
 pub(crate) enum AuraProc {
     /// The aura landed in a slot: install this kit's body procs, keyed by its spell id.
@@ -461,16 +281,14 @@ pub(crate) enum AuraProc {
     Reap { entity: Entity, spell_id: u32 },
 }
 
-/// Turn one `SpellVisualKit` CharProc into the node it installs, or `None` for a proc type we have
-/// no verified mechanism for (module docs). **The single dispatch point** — the ECS twin of the
-/// client's jump table `0x60dbfc`, and the one place a newly-REd proc type gets an arm.
+/// The node one `SpellVisualKit` CharProc installs (the dispatcher's jump table `0x60dbfc`), or
+/// `None` for a proc type whose mechanism is untraced.
 pub(crate) fn node_for(proc: benilla_formats::CharProc) -> Option<AuraNode> {
     use benilla_formats::char_proc_type as ty;
     match proc.ty {
         ty::ALPHA => Some(AuraNode::Alpha(proc.params[0])),
-        // `round(param)` → `0x00RRGGBB` (`0x60d8cc` then ORs the opaque byte on). The param is a
-        // float column holding an integral colour: the ghost's 9222653.0 is 0x8CB9FD, pale
-        // blue-white; the poison kit's 65280.0 is 0x00FF00.
+        // A float holding an integral `0x00RRGGBB`, rounded (`0x60d8cc`): the ghost's 9222653.0
+        // is 0x8CB9FD.
         ty::TINT => {
             let packed = proc.params[0].round().clamp(0.0, 0xff_ffff as f32) as u32;
             Some(AuraNode::Tint([
@@ -479,22 +297,14 @@ pub(crate) fn node_for(proc: benilla_formats::CharProc) -> Option<AuraNode> {
                 packed as u8,
             ]))
         }
-        // `params[0]` is a playback rate, straight through — `0x60db7e` hands it to
-        // `SetBoneAnimSpeed` unexamined, so the one outlier (kit 1744's `8947848.0`, a packed grey
-        // that landed in the rate column) is passed through rather than special-cased.
+        // A playback rate, passed through: `0x60db7e` hands it to `SetBoneAnimSpeed` (`0x712910`)
+        // unexamined.
         ty::ANIM_RATE => Some(AuraNode::AnimRate(proc.params[0])),
         _ => None,
     }
 }
 
-/// Apply this frame's [`AuraProc`] edges to the units' node lists, then re-aim every live ramp.
-///
-/// `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`, 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).
+/// Apply this frame's [`AuraProc`] edges to the units' node lists.
 pub(crate) fn drain_aura_procs(
     mut edges: MessageReader<AuraProc>,
     time: Res<Time>,
@@ -504,7 +314,6 @@ pub(crate) fn drain_aura_procs(
     creatures: Option<Res<crate::entities::Creatures>>,
 ) {
     let now = time.elapsed_secs();
-    // Node sets for units that don't carry the component yet — see the `Begin` arm.
     let mut fresh: bevy::ecs::entity::EntityHashMap<AuraNodes> = Default::default();
     for edge in edges.read() {
         match edge {
@@ -520,14 +329,8 @@ pub(crate) fn drain_aura_procs(
                     install(&mut n, *spell_id, procs, now);
                     trace_edge("arm", *entity, *spell_id, &n);
                 } else {
-                    // First edge for this unit: stage the node set locally rather than inserting
-                    // straight away. `Commands` are deferred to the end of the system, so a unit
-                    // that streams in already carrying two aura procs (or gets two in one packet
-                    // burst) emits two Begins this frame and the second would `get_mut` the
-                    // still-absent component, build a *fresh* set, and insert over the first —
-                    // silently keeping only the last aura's factor. Staging makes the outcome of a
-                    // same-frame burst come out right, which is the common case for a unit observed
-                    // mid-buff, not a corner.
+                    // Staged, not inserted: `Commands` apply at the end of the system, so a second
+                    // Begin this frame would build a fresh set and overwrite the first.
                     let n = fresh.entry(*entity).or_insert_with(|| {
                         AuraNodes::new(base_alpha(*entity, &units, creatures.as_deref()))
                     });
@@ -540,8 +343,7 @@ pub(crate) fn drain_aura_procs(
                     reap(&mut n, *spell_id, now);
                     trace_edge("reap", *entity, *spell_id, &n);
                 } else if let Some(n) = fresh.get_mut(entity) {
-                    // Armed and reaped inside one frame (a flickering re-apply) — the staged set is
-                    // the live one, so the removal has to land there too.
+                    // Armed and reaped in one frame: the staged set is the live one.
                     reap(n, *spell_id, now);
                     trace_edge("reap", *entity, *spell_id, n);
                 }
@@ -553,8 +355,7 @@ pub(crate) fn drain_aura_procs(
     }
 }
 
-/// Drop every node one spell installed (`0x5ff290`) and re-aim the ramp at the new target
-/// (the next head node down, or the bare base).
+/// Drop every node one spell installed (`0x5ff290`) and re-aim the ramp.
 fn reap(n: &mut AuraNodes, spell_id: u32, now: f32) {
     n.alpha.retain(|(s, _)| *s != spell_id);
     n.tint.retain(|(s, _)| *s != spell_id);
@@ -562,10 +363,8 @@ fn reap(n: &mut AuraNodes, spell_id: u32, now: f32) {
     n.retarget(now);
 }
 
-/// 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** (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()`.
+/// Install one spell's nodes at the head of each list, replacing any it had: nodes are keyed by
+/// spell id, so a second caster's copy of an aura installs one set.
 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);
@@ -580,15 +379,7 @@ fn install(n: &mut AuraNodes, spell_id: u32, procs: &[AuraNode], now: f32) {
     n.retarget(now);
 }
 
-/// The layer's instrument (`WOW_MOVE_TRACE=<path>`, tag `aur`) — one line per node edge, carrying
-/// 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
-/// (`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
-/// exactly that.
+/// Trace (`WOW_MOVE_TRACE=<path>`, tag `aur`) each node edge: the spell, its nodes, the target.
 fn trace_edge(what: &str, entity: Entity, spell_id: u32, n: &AuraNodes) {
     if !benilla_assets::trace::enabled() {
         return;
@@ -611,11 +402,8 @@ 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; 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).
+/// `baseAlpha` (`0x60d2d0`): the current display row's `CreatureModelAlpha / 255`, players
+/// included (Ghost Wolf's display 4613 reads 102); no row reads 1.0 (`0x60d2e4`).
 fn base_alpha(
     entity: Entity,
     units: &Query<&crate::net::NetEntity>,
@@ -641,17 +429,11 @@ fn display_base_alpha(
     }
 }
 
-/// Re-resolve every unit's base alpha when its display changes — the reference's DISPLAYID
-/// 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
-/// display swaps home. The 1000 ms cubic fade is part of the mechanism: a display swap always
-/// eases to the new alpha, never snaps.
-///
-/// `Changed<NetEntity>` is our `0x60ae10`: [`crate::entities`]' live-display refresh writes
-/// `net.display_id` only on an actual swap (and insertion covers the create path). The base
-/// compare keeps a scale-only mutation from restarting anything.
+/// Re-resolve a unit's base alpha when its display changes and ramp to it over the same 1000 ms,
+/// as the reference's DISPLAYID watcher does (`0x604990` → `0x60abe0`, the row cached at
+/// `0x60afb0`, → `0x60ad9f` → `0x60d180`): a display below 255 alpha is translucent with no aura.
+/// `Changed<NetEntity>` stands for its record-change gate (`0x60ae10`); the base compare ignores a
+/// scale-only change.
 pub(crate) fn refresh_base_alpha(
     time: Res<Time>,
     creatures: Option<Res<crate::entities::Creatures>>,
@@ -675,9 +457,7 @@ pub(crate) fn refresh_base_alpha(
                     n.retarget(now);
                 }
             }
-            // A unit that never carried a node set needs one exactly when its display is
-            // authored translucent — created settled at opaque so the retarget rides the same
-            // 1000 ms ramp down a fresh aura node would.
+            // A translucent display gets a node set, created at opaque so it ramps down.
             None if base < 1.0 => {
                 debug!(
                     "aura_visual: e={entity} display {:?} authors base alpha {base:.2} (1 s ramp)",
@@ -693,10 +473,7 @@ pub(crate) fn refresh_base_alpha(
     }
 }
 
-/// The fadeable-part view [`apply_aura_alpha`] authors through: the part's material pair and tag,
-/// plus every other factor of its alpha (its animated colour alpha, its live appear/despawn ramp)
-/// and the light law that decides which material variant it should be on. [`FadeMaterials`] is the
-/// "this is a fadeable mesh" marker every writer of this channel keys on.
+/// The fadeable parts [`apply_aura_alpha`] writes, with every other factor of their alpha.
 type AuraParts<'w, 's> = Query<
     'w,
     's,
@@ -710,34 +487,17 @@ type AuraParts<'w, 's> = Query<
         Has<PendingAppearFade>,
         Has<benilla_world::model_render::FarSideOfWater>,
     ),
-    // Disjointness for the card pass (both want `&mut MeshTag`); a card never carries
-    // `FadeMaterials`, so this filter excludes nothing that would otherwise match — the same
-    // trick `apply_self_model_fade` uses for the same pair of queries.
+    // Disjoint from the card query, as both take `&mut MeshTag`; no card carries `FadeMaterials`.
     Without<benilla_world::billboard::BillboardCard>,
 >;
 
-/// Drive every unit's aura-alpha ramp and author its parts' render alpha + material.
+/// Drive every unit's aura-alpha ramp and write its parts' render alpha and material;
+/// [`AuraNodes::authoring`] latches the release.
 ///
-/// Ordered **after** the three steady-state authors of a unit part's alpha field (the interior
-/// classifier, the visibility authority, `entities::apply_unit_mat_alpha`) and **before** the
-/// self-avatar zoom feather, so it overrides them for exactly the units that carry a live aura
-/// alpha, and the self feather stays the last word on your own body (it folds this factor in
-/// itself — [`crate::player::apply_self_model_fade`]). This is the same override-then-release
-/// protocol the feather uses (decision 0213); [`AuraNodes::authoring`] is its latch.
-///
-/// The product it writes is the reference's own: this unit's `ramped aura alpha × the part's
-/// animated colour alpha × its live appear/despawn ramp`. Reading the fade back out of
-/// [`RenderFade`] rather than the tag keeps every factor a pure function of state, so the write is
-/// idempotent (running it twice can't compound) exactly as `apply_unit_mat_alpha`'s is.
-///
-/// **The material swap is load-bearing, not cosmetic.** A cutout/opaque batch ignores instance
-/// alpha, so writing `0.3` into the tag without moving the part onto its **blend twin** renders no
-/// translucency at all — the same "blend pass while `0 < fade < 1`" the reference runs for its
-/// doodad fade ([`benilla_world::model_fade`]). It goes through [`FadeMaterials::material_for`], the one
-/// place the blend-vs-law axes compose, so this writer and the classifier can never disagree.
-/// Note the swap keys on the *instance* alpha only: a batch whose own animated colour alpha dips is
-/// a per-batch quantity the reference combines separately, and forcing those onto a blend pass would
-/// change every existing unit's look.
+/// Each part gets the reference's product (`0x614baa` → `0x710cb0`, `0x707680`): the ramped aura
+/// alpha × the batch's animated colour alpha × its appear/despawn ramp, recomputed from state so a
+/// rerun cannot compound. A cutout or opaque batch ignores instance alpha, so a translucent unit's
+/// parts move to their blend material, keyed on the instance alpha alone.
 pub(crate) fn apply_aura_alpha(
     time: Res<Time>,
     mut commands: Commands,
@@ -759,14 +519,8 @@ pub(crate) fn apply_aura_alpha(
     let now = time.elapsed_secs();
     for (root, mut n, declared) in &mut roots {
         let alpha = n.tick(now);
-        // Declare it to the engine, which owns the composed model alpha and its chain walk
-        // (`model_fade::ModelFade` — 1164's inversion). This is the whole of the aura's claim on
-        // the channel: a number and a reason, never a write.
-        //
-        // Written **before** the settled-opaque early-out below, and unconditionally on change:
-        // a declaration the engine keeps reading has to be retired by its declarer, and the ramp
-        // arriving at 1.0 is exactly when that matters. (`AuraNodes` itself is never removed — it
-        // parks at 1.0 — so there is no removal hook to hang this on.)
+        // Declared to the engine's composed model alpha (`model_fade::ModelFade`) before the
+        // settled-opaque early-out, so the ramp's arrival at 1.0 is declared too.
         if declared.is_none_or(|d| d.0 != alpha) {
             commands
                 .entity(root)
@@ -776,8 +530,7 @@ pub(crate) fn apply_aura_alpha(
         if !translucent && !n.authoring {
             continue; // settled opaque: not ours, nothing to release
         }
-        // The walked set doubles as "which anchors belong to this unit" for the card pass below —
-        // built only for a unit we're authoring, so a quiet world never pays for it.
+        // The walked set tells the card pass which anchors are this unit's.
         let mut walked = bevy::ecs::entity::EntityHashSet::default();
         author_descendants(
             root,
@@ -790,23 +543,14 @@ pub(crate) fn apply_aura_alpha(
             &mut walked,
         );
         author_cards(alpha, &walked, &mut cards);
-        // The release frame is the one where we authored the settled value and handed the material
-        // back; after it this unit costs a ramp tick and the branch above.
+        // A frame written at opaque was the release; the latch drops after it.
         n.authoring = translucent;
     }
 }
 
-/// Fold the unit's aura alpha into its **billboard cards** — the batches that can't be tree children.
-///
-/// An M2's billboard batches are world ROOT entities that merely *follow* an anchor inside the model
-/// (decision 0153: their mesh is centred on the bone pivot and their transform belongs to the
-/// billboard system), so a descendant walk cannot see them. Skipping them is a burned trap, not a
-/// hypothetical: the night-elf eye glow — two additive `…EYEGLOW.BLP` quads at head height — went on
-/// burning in mid-air after the body it belongs to had faded out (ledger B71), and a stealthed night
-/// elf with full-brightness eyes is the same bug wearing this system's clothes. Cards are picked up
-/// by the same rule the self-avatar feather uses: test the card's follow-anchor against the walked
-/// set. One multiply covers both halves — the card dims with the body, and for an ADD blend the
-/// shader's `out_rgb *= faded_alpha` takes a low alpha toward gone.
+/// Fold the unit's aura alpha into its billboard cards, world-root entities that follow an anchor
+/// in the model and so escape the descendant walk (a stealthed night elf's eye glow would stay
+/// lit). A card is the unit's when its follow anchor is in `walked`.
 fn author_cards(
     alpha: f32,
     walked: &bevy::ecs::entity::EntityHashSet,
@@ -820,9 +564,8 @@ fn author_cards(
         if !card.follows().is_some_and(|a| walked.contains(&a)) {
             continue;
         }
-        // Compose from the animation's own factor rather than from the tag we'd read back, so the
-        // card's per-sequence alpha animation stays alive under the aura — and so the release frame's
-        // `alpha = 1` write lands exactly on the value the card would have had anyway.
+        // From the animation's own factor, not the tag, so the card's alpha animation survives and
+        // the release lands on the card's own value.
         let authored = anim.map_or(1.0, |a| a.current);
         let bits = benilla_world::mesh_tag::with_alpha(tag.0, authored * alpha);
         if tag.0 != bits {
@@ -831,12 +574,8 @@ fn author_cards(
     }
 }
 
-/// Depth-first author for [`apply_aura_alpha`]: apply to `entity` if it is a fadeable part, then
-/// recurse regardless — a joint or an attach-model root carries no [`FadeMaterials`] itself but the
-/// held weapon / helm / shoulder meshes hang beneath it, and the reference's alpha is a per-CGUnit
-/// property that its attached models render off (the same reason
-/// [`benilla_world::model_fade::apply_despawn_fade`] and the self feather both walk descendants, not
-/// children).
+/// Write `entity` if it is a fadeable part, then recurse regardless: held items, helms and
+/// shoulders hang under joints that carry no [`FadeMaterials`].
 fn author_descendants(
     entity: Entity,
     alpha: f32,
@@ -849,14 +588,10 @@ fn author_descendants(
 ) {
     walked.insert(entity);
     if let Ok((fm, mut tag, mut mat, anim, lit, fade, pending, far_side)) = parts.get_mut(entity) {
-        // A part still WAITING on its appear-fade is deliberately invisible until the ramp arms (its
-        // tag alpha is seeded near-zero at spawn), so authoring it would flash a streaming-in unit's
-        // geometry at the aura alpha for the pending window. Every other author of this channel
-        // filters the same way. Skip the write, still recurse — a joint's children can be past it.
+        // A part awaiting its appear-fade stays invisible until the ramp arms; writing it would
+        // flash it at the aura alpha.
         if !pending {
-            // Every live factor on this part, recomputed from state (never read back from the tag),
-            // so the write is idempotent: the unit's ramped aura alpha × the batch's animated colour
-            // alpha × the part's own live appear/despawn ramp.
+            // Recomputed from state, never read back from the tag, so the write is idempotent.
             let ramp = fade.map_or(1.0, |f| {
                 let t = if f.duration > 0.0 {
                     (now - f.started) / f.duration
@@ -870,9 +605,7 @@ fn author_descendants(
             if tag.0 != bits {
                 tag.0 = bits;
             }
-            // The INSTANCE alpha decides the pass; a settled-opaque release hands the law's steady
-            // material back and asks the classifier to re-author, so nothing is left on a stale
-            // one. The water-plane axis composes here like everywhere else (`far_resolved`).
+            // The instance alpha alone picks the pass; the far-side-of-water axis composes on top.
             let want = benilla_world::model_render::far_resolved(
                 fm.material_for(lit, alpha < 1.0),
                 far_side,
@@ -882,8 +615,7 @@ fn author_descendants(
             if mat.0 != want {
                 mat.0 = want;
                 if alpha >= 1.0 && lit.is_some() {
-                    // 0734's queue: let the classifier re-assert this part's full payload (probe
-                    // slot / fog bit) over whatever this episode wrote.
+                    // The released part's probe slot and fog bit are the interior classifier's.
                     reauthor.0.push(entity);
                 }
             }
@@ -905,9 +637,7 @@ fn author_descendants(
     }
 }
 
-/// This unit's live aura alpha, for the writers that compose it into their own product rather than
-/// deferring to [`apply_aura_alpha`] (the self-avatar feather, which runs after it and wins on the
-/// self body). `1.0` when the unit carries no aura nodes.
+/// A unit's live aura alpha, for the self-avatar feather, which composes it into its own product.
 pub(crate) fn root_alpha(nodes: Option<&AuraNodes>) -> f32 {
     nodes.map_or(1.0, |n| n.current)
 }
diff --git a/crates/benilla-app/src/aura_visual/tests.rs b/crates/benilla-app/src/aura_visual/tests.rs
index faca4011..b2132e03 100644
--- a/crates/benilla-app/src/aura_visual/tests.rs
+++ b/crates/benilla-app/src/aura_visual/tests.rs
@@ -1,7 +1,5 @@
-//! Tests for the aura-state CharProc layer. The chains are the **real 5875 rows** (read off
-//! `SpellVisualKit.dbc` this session with `benilla-extract charprocs`), so a schema or column-order
-//! regression in the data layer shows up here as a wrong number rather than as a silent nothing —
-//! which is precisely how B114 hid.
+//! Tests for the aura-state CharProc layer over shipped kit rows (`benilla-extract charprocs`), so
+//! a schema or column-order regression shows as a wrong number, not a silent nothing.
 
 use std::collections::HashMap;
 
@@ -13,20 +11,17 @@ use benilla_protocol::messages::ObjectFields;
 use super::*;
 use crate::creature_anim::SpellVisuals;
 
-// ── The real chains, from the shipped table ───────────────────────────────────────────────────────
+// ── The shipped chains ───────────────────────────────────────────────────────────────────────────
 
-/// Stealth rank 1 → `SpellVisual` 184 → state kit 312: proc 7 (unmodelled) + **proc 14 @ 0.3**, no
-/// effect models, no anim. The whole of B114 in one row.
+/// Stealth rank 1 → `SpellVisual` 184 → state kit 312: proc 7 and proc 14 at 0.3, nothing else.
 const STEALTH: u32 = 1784;
 const STEALTH_VISUAL: u32 = 184;
 const STEALTH_KIT: u32 = 312;
-/// The ghost aura → visual 886 → kit 989: proc 1 tint `9222653.0` (= `0x8CB9FD`) + proc 14 @ 0.5.
+/// The ghost aura → visual 886 → kit 989: proc 1 tint `9222653.0` (`0x8CB9FD`) and proc 14 at 0.5.
 const GHOST: u32 = 8326;
 const GHOST_VISUAL: u32 = 886;
 const GHOST_KIT: u32 = 989;
-/// **Ice Block** → `SpellVisual` 4325 → state kit 3709: proc 1 tint `9074175.0` + **proc 11 @ 0.0**
-/// (plus `icebarrier_state.mdx` at attach 0x13, which this layer doesn't own). The freeze, from the
-/// shipped table — `benilla-extract spellvis 11958`.
+/// Ice Block → `SpellVisual` 4325 → state kit 3709: proc 1 tint `9074175.0` and proc 11 at 0.0.
 const ICE_BLOCK: u32 = 11958;
 const ICE_BLOCK_VISUAL: u32 = 4325;
 const ICE_BLOCK_KIT: u32 = 3709;
@@ -38,7 +33,6 @@ fn proc(ty: i32, param0: f32) -> CharProc {
     }
 }
 
-/// A kit carrying `procs` in slot order and nothing else — the shape of every proc-only state kit.
 fn proc_kit(procs: &[CharProc]) -> VisualKit {
     let mut slots = [None; KIT_CHAR_PROCS];
     for (slot, p) in slots.iter_mut().zip(procs) {
@@ -52,8 +46,7 @@ fn proc_kit(procs: &[CharProc]) -> VisualKit {
 
 // ── The dispatch ─────────────────────────────────────────────────────────────────────────────────
 
-/// [`node_for`] is the twin of the client's proc jump table: 14 → an alpha node carrying `params[0]`,
-/// 1 → a tint node with the packed colour unpacked, everything else → no node (and so no arm).
+/// [`node_for`] follows the client's proc jump table: 14 alpha, 1 tint, 11 rate, else no node.
 #[test]
 fn the_dispatch_names_only_the_verified_procs() {
     assert_eq!(
@@ -66,20 +59,17 @@ 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, 0xFF8CB9FD once the client ORs the opaque
-    // byte on (`0x60d8cc`).
+    // 9222653 is 0x8CB9FD, the ghost's blue-white; the client ORs on the opaque byte (`0x60d8cc`).
     assert_eq!(
         node_for(proc(char_proc_type::TINT, 9_222_653.0)),
         Some(AuraNode::Tint([0x8C, 0xB9, 0xFD])),
     );
-    // 65280 = 0x00FF00 — the poison state kit's pure green.
+    // 65280 is 0x00FF00, the poison state kit's green.
     assert_eq!(
         node_for(proc(char_proc_type::TINT, 65_280.0)),
         Some(AuraNode::Tint([0x00, 0xFF, 0x00])),
     );
-    // Proc 11 is a playback RATE, straight through (`0x60db7e` → `SetBoneAnimSpeed 0x712910`).
-    // Ice Block's 0.0 is the freeze; kit 1744's 8947848.0 goes through unexamined too, exactly as
-    // the reference hands the column on.
+    // Proc 11's rate passes on unexamined (`0x60db7e` → `SetBoneAnimSpeed` `0x712910`).
     assert_eq!(
         node_for(proc(char_proc_type::ANIM_RATE, 0.0)),
         Some(AuraNode::AnimRate(0.0)),
@@ -89,8 +79,7 @@ fn the_dispatch_names_only_the_verified_procs() {
         node_for(proc(char_proc_type::ANIM_RATE, 8_947_848.0)),
         Some(AuraNode::AnimRate(8_947_848.0)),
     );
-    // The four other types that ride real state kits have no verified mechanism yet: no node, so
-    // nothing is invented and the kit doesn't arm on them alone.
+    // Types on shipped state kits whose mechanism is untraced get no node, so none arms a kit.
     for ty in [2, 7, 8, 13] {
         assert_eq!(node_for(proc(ty, 1.0)), None, "type {ty} is unmodelled");
     }
@@ -98,10 +87,7 @@ 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.
-/// 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.
+/// `0x60d180`: the target is `baseAlpha` times the head (newest) node's factor alone.
 #[test]
 fn the_target_is_base_times_the_newest_node() {
     let mut n = AuraNodes::new(1.0);
@@ -116,13 +102,11 @@ fn the_target_is_base_times_the_newest_node() {
         "the newest node is the term"
     );
 
-    // Reaping the head hands the term back to the older node.
     n.alpha.retain(|(s, _)| *s != GHOST);
     n.retarget(0.0);
     assert!((n.target() - 0.3).abs() < 1e-6);
 
-    // A display authored translucent (CreatureModelAlpha 128/255) multiplies the head term —
-    // and stands alone when no node is live (the display-set leg, no aura anywhere).
+    // A translucent display's base (128/255) scales the head term, or stands alone with no node.
     let mut half = AuraNodes::new(1.0);
     half.base = 128.0 / 255.0;
     install(&mut half, STEALTH, &[AuraNode::Alpha(0.3)], 0.0);
@@ -132,9 +116,7 @@ fn the_target_is_base_times_the_newest_node() {
     assert!((half.target() - 128.0 / 255.0).abs() < 1e-6);
 }
 
-/// 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 (the fade, `0x614f80`, is part of the mechanism).
+/// A display swap's base change ([`refresh_base_alpha`]) rides the same ramp (`0x614f80`).
 #[test]
 fn a_base_change_rides_the_same_ramp() {
     let wolf = 102.0 / 255.0;
@@ -148,7 +130,6 @@ fn a_base_change_rides_the_same_ramp() {
     );
     assert!(n.translucent());
 
-    // The swap home: base back to 1.0, eased up from the live value.
     n.base = 1.0;
     n.retarget(AURA_ALPHA_FADE_SECS);
     assert!((n.from - wolf).abs() < 1e-6);
@@ -156,9 +137,7 @@ fn a_base_change_rides_the_same_ramp() {
     assert!(!n.translucent(), "settled opaque again");
 }
 
-/// A re-applied aura installs ONE node set, not a second copy — the reference keys its nodes by spell
-/// id (`node+0x18`) and its own dedup walk returns early on a spell that already has one. Without
-/// this a refresh would square the factor every application.
+/// Nodes are keyed by spell id (`node+0x18`): a re-applied aura replaces its node.
 #[test]
 fn re_arming_the_same_spell_replaces_its_node() {
     let mut n = AuraNodes::new(1.0);
@@ -168,17 +147,14 @@ fn re_arming_the_same_spell_replaces_its_node() {
     assert!((n.target() - 0.3).abs() < 1e-6);
 }
 
-/// The ramp is `StartAlphaFade(target, 1000 ms)` on the `clamp01(t)³` ease, in **both** directions:
-/// arming eases down to the product, reaping eases back up — and a retarget mid-ramp starts from
-/// where the ramp actually is, never from the old endpoint (a stealth dropped 300 ms into the fade
-/// must not jump to 0.3 first).
+/// `StartAlphaFade(target, 1000 ms)` eased `clamp01(t)³` both ways, retargeted from the live value.
 #[test]
 fn the_ramp_eases_over_one_second_both_ways() {
     let mut n = AuraNodes::new(1.0);
     install(&mut n, STEALTH, &[AuraNode::Alpha(0.3)], 0.0);
 
     assert!((n.tick(0.0) - 1.0).abs() < 1e-6, "t=0 is still opaque");
-    // t³ at the halfway mark = 0.125 of the way down.
+    // t³ at the halfway mark is 0.125 of the way down.
     let half = n.tick(0.5);
     assert!(
         (half - (1.0 + (0.3 - 1.0) * 0.125)).abs() < 1e-6,
@@ -191,7 +167,6 @@ fn the_ramp_eases_over_one_second_both_ways() {
     assert!((n.tick(5.0) - 0.3).abs() < 1e-6, "and clamps past the end");
     assert!(n.translucent());
 
-    // The aura drops: ease back to the new product from where we are.
     n.alpha.clear();
     n.retarget(AURA_ALPHA_FADE_SECS);
     assert!((n.from - 0.3).abs() < 1e-6, "ramps from the live value");
@@ -199,7 +174,6 @@ fn the_ramp_eases_over_one_second_both_ways() {
     assert!((n.tick(2.0 * AURA_ALPHA_FADE_SECS) - 1.0).abs() < 1e-6);
     assert!(!n.translucent(), "settled opaque again");
 
-    // A mid-ramp retarget picks up the live value, not the endpoint.
     let mut m = AuraNodes::new(1.0);
     install(&mut m, STEALTH, &[AuraNode::Alpha(0.3)], 0.0);
     let mid = m.tick(0.7);
@@ -208,8 +182,6 @@ fn the_ramp_eases_over_one_second_both_ways() {
     assert!((m.from - mid).abs() < 1e-6);
 }
 
-/// An aura refresh whose factor doesn't change must not restart the ease — otherwise a buff ticking
-/// every few seconds would keep re-easing a settled body.
 #[test]
 fn a_retarget_to_the_same_value_does_not_restart_the_ease() {
     let mut n = AuraNodes::new(1.0);
@@ -221,8 +193,7 @@ fn a_retarget_to_the_same_value_does_not_restart_the_ease() {
     assert!((n.tick(10.0) - 0.3).abs() < 1e-6, "and stays arrived");
 }
 
-/// Proc 1's nodes link at the head like the alpha list's (`unit+0xce0`), so the tint the per-frame
-/// apply reads is the NEWEST aura's — deterministic under stacking.
+/// Proc 1's nodes link at the head of `unit+0xce0`, so the newest aura's tint applies.
 #[test]
 fn the_tint_head_node_is_the_newest_installed() {
     let mut n = AuraNodes::new(1.0);
@@ -230,15 +201,13 @@ fn the_tint_head_node_is_the_newest_installed() {
     install(&mut n, GHOST, &[AuraNode::Tint([0x8C, 0xB9, 0xFD])], 0.0);
     install(&mut n, 12881, &[AuraNode::Tint([0x00, 0xFF, 0x00])], 0.0);
     assert_eq!(n.head_tint(), Some([0x00, 0xFF, 0x00]));
-    // The newest dropping hands the head back.
     n.tint.retain(|(s, _)| *s != 12881);
     assert_eq!(n.head_tint(), Some([0x8C, 0xB9, 0xFD]));
     assert_eq!(n.target(), 1.0, "a tint node is not an alpha term");
 }
 
-// ── The watcher → drain edge, over the real Stealth chain ─────────────────────────────────────────
+// ── The watcher → drain edge ─────────────────────────────────────────────────────────────────────
 
-/// A fixture app carrying the two real chains, the aura watcher and the drain.
 fn app_with_chains() -> App {
     let mut app = App::new();
     app.add_plugins(MinimalPlugins);
@@ -247,7 +216,6 @@ fn app_with_chains() -> App {
     app.add_message::<crate::creature_anim::SpellKitSound>();
     app.add_message::<AuraProc>();
     app.add_message::<crate::creature_anim::BaseAnimRecompute>();
-    // The water-plane twin map the alpha author composes with (empty here — no water in a fixture).
     app.init_resource::<benilla_world::model_render::FarSideTwins>();
     app.insert_resource(SpellVisuals(SpellVisualCatalog::from_tables(
         HashMap::from([
@@ -274,8 +242,7 @@ fn app_with_chains() -> App {
             ),
         ]),
         HashMap::from([
-            // Kit 312's real slots: the unmodelled proc 7 FIRST, then proc 14 — so this also pins
-            // that an unmodelled proc ahead of a modelled one doesn't shadow it.
+            // Kit 312's shipped order: the unmodelled proc 7 must not shadow proc 14 after it.
             (
                 STEALTH_KIT,
                 proc_kit(&[proc(7, 1.0), proc(char_proc_type::ALPHA, 0.3)]),
@@ -333,8 +300,6 @@ fn app_with_chains() -> App {
     app
 }
 
-/// The arming world plus the per-instance tint channel (decision 0812): the table resource, the
-/// palette allocator whose slots index it, and the publish system.
 fn app_with_tint_channel() -> App {
     let mut app = app_with_chains();
     app.init_resource::<benilla_world::instance_tint::InstanceTints>();
@@ -343,14 +308,12 @@ fn app_with_tint_channel() -> App {
     app
 }
 
-/// **B114, end to end at the mechanism.** Stealth's state kit carries no effect models at all, so the
-/// effects-only watcher never armed it and the character showed nothing. Now the same slot edge
-/// installs a proc-14 node and the unit's target alpha is 0.3 — and dropping the aura ramps it back.
+/// Stealth's proc-only state kit (no effect models) still installs its proc-14 node.
 #[test]
 fn a_proc_only_state_kit_arms_stealth_translucency() {
     let mut app = app_with_chains();
 
-    // The aura lands in slot 0 (UNIT_FIELD_AURA[0] = field 47) with an occupied AURAFLAGS nibble.
+    // The aura lands in slot 0 (UNIT_FIELD_AURA[0], field 47) with an occupied AURAFLAGS nibble.
     let stealthed = ObjectFields::from_pairs(&[(47, STEALTH), (95, 0x0E)]);
     let unit = app
         .world_mut()
@@ -369,7 +332,6 @@ fn a_proc_only_state_kit_arms_stealth_translucency() {
     assert!((n.target() - 0.3).abs() < 1e-6);
     assert!(n.head_tint().is_none(), "kit 312 carries no tint");
 
-    // The aura drops: the node goes and the target ramps back to opaque.
     crate::net::apply_fields_for_test(
         app.world_mut(),
         unit,
@@ -382,8 +344,7 @@ fn a_proc_only_state_kit_arms_stealth_translucency() {
     assert!((n.target() - 1.0).abs() < 1e-6);
 }
 
-/// The ghost aura's kit carries both procs: the tint node lands beside the alpha one off a single
-/// slot edge (the dispatcher walks all four slots), and the alpha is the ghost's 0.5.
+/// One slot edge installs both of the ghost kit's nodes: the dispatcher walks all four proc slots.
 #[test]
 fn a_kit_with_both_procs_installs_both_nodes() {
     let mut app = app_with_chains();
@@ -401,8 +362,7 @@ fn a_kit_with_both_procs_installs_both_nodes() {
     assert_eq!(n.head_tint(), Some([0x8C, 0xB9, 0xFD]));
 }
 
-/// Two auras on one unit: the newest node holds the head (the reference's link-at-head list), and
-/// reaping the other leaves it untouched — the body never snaps opaque while any alpha aura lives.
+/// The newest node holds the head; reaping the older aura leaves it.
 #[test]
 fn two_auras_stack_and_unstack_through_the_slots() {
     let mut app = app_with_chains();
@@ -433,8 +393,6 @@ fn two_auras_stack_and_unstack_through_the_slots() {
     assert!((n.target() - 0.5).abs() < 1e-6);
 }
 
-/// A state kit whose every proc is unmodelled (and which carries no effect models either) must not
-/// arm: no node set, so nothing claims the unit's alpha channel on a mechanism we haven't verified.
 #[test]
 fn an_unmodelled_proc_only_kit_arms_nothing() {
     const SAP: u32 = 6770;
@@ -450,7 +408,7 @@ fn an_unmodelled_proc_only_kit_arms_nothing() {
                 ..Default::default()
             },
         )]),
-        // Kit 691's real content: proc 7 @ 2.0 and nothing else.
+        // Kit 691's shipped content: proc 7 at 2.0 and nothing else.
         HashMap::from([(SAP_KIT, proc_kit(&[proc(7, 2.0)]))]),
     )));
     app.insert_resource(crate::ui_action::Spells {
@@ -480,12 +438,8 @@ fn an_unmodelled_proc_only_kit_arms_nothing() {
 
 // ── The render authoring ─────────────────────────────────────────────────────────────────────────
 
-/// The author owns a translucent unit's parts **through the whole descendant tree** (a held weapon
-/// hangs off a joint several levels down, and the reference's alpha is a per-CGUnit property its
-/// attached models render off), writes the product into the tag's alpha field, and moves the part
-/// onto its blend twin — without which a cutout batch ignores the alpha entirely and B114's symptom
-/// survives the fix. On the frame the ramp latches opaque it releases: settled alpha, steady
-/// material, and the part re-queued for the classifier.
+/// The author writes the alpha down the whole tree (the reference's alpha is per CGUnit) and moves
+/// each part to its blend twin, as a cutout batch ignores alpha; at opaque it releases.
 #[test]
 fn the_author_owns_the_tree_then_releases_at_opaque() {
     use benilla_world::model_fade::FadeMaterials;
@@ -499,7 +453,6 @@ fn the_author_owns_the_tree_then_releases_at_opaque() {
     let mut app = App::new();
     app.add_plugins(MinimalPlugins);
     app.init_resource::<benilla_world::interior::InteriorReauthor>();
-    // The water-plane twin map the author composes with (empty — no water in a fixture).
     app.init_resource::<benilla_world::model_render::FarSideTwins>();
     app.add_systems(Update, apply_aura_alpha);
 
@@ -533,8 +486,7 @@ fn the_author_owns_the_tree_then_releases_at_opaque() {
         ))
         .id();
 
-    // Run the ramp out to its end: `MinimalPlugins`' clock advances a hair per update, so drive the
-    // component's own clock instead of guessing frame counts.
+    // `MinimalPlugins`' clock barely advances per update, so the ramp is ended on its own clock.
     app.update();
     {
         let mut root_mut = app.world_mut().entity_mut(root);
@@ -560,8 +512,7 @@ fn the_author_owns_the_tree_then_releases_at_opaque() {
         );
     }
 
-    // The aura drops and the ramp completes: the release frame restores opacity and the steady
-    // material, and stops authoring.
+    // The aura drops and the ramp completes: the release frame restores opacity and material.
     {
         let mut root_mut = app.world_mut().entity_mut(root);
         let mut n = root_mut.get_mut::<AuraNodes>().unwrap();
@@ -593,11 +544,10 @@ fn the_author_owns_the_tree_then_releases_at_opaque() {
     );
 }
 
-// ── The tint's render channel (decision 0812) ─────────────────────────────────────────────────────
+// ── The tint's render channel ─────────────────────────────────────────────────────
 
-/// **The tint end to end**: the ghost aura's CharProc-1 head node lands in the per-instance table at
-/// the unit's own rig slot, packed the way the reference packs it (`param | 0xff000000`) — and the
-/// aura dropping puts the slot back to identity, so the body goes back to its own colours.
+/// The ghost's tint lands at the unit's rig slot packed as `param | 0xff000000`, and clears with
+/// the aura.
 #[test]
 fn the_ghost_tint_reaches_the_instance_table_and_clears_with_the_aura() {
     let mut app = app_with_tint_channel();
@@ -632,8 +582,7 @@ fn the_ghost_tint_reaches_the_instance_table_and_clears_with_the_aura() {
         "the ghost's pale blue-white, alpha byte and all"
     );
 
-    // The aura leaves its slot: the reference drops the tint node (`0x5ff320`) with no ease, and the
-    // channel goes back to identity — which is the shader's no-op word, not a colour.
+    // Dropped with no ease (`0x5ff320`); identity is the shader's no-op word, not a colour.
     crate::net::apply_fields_for_test(
         app.world_mut(),
         unit,
@@ -647,12 +596,8 @@ fn the_ghost_tint_reaches_the_instance_table_and_clears_with_the_aura() {
     assert_eq!(tints.get(slot), benilla_world::instance_tint::IDENTITY);
 }
 
-/// **The chain (decision 0841).** A rigged ATTACHED model — a spell-effect instance, or one of the
-/// seven shoulder models whose welded billboard geometry made the item lane rig — carries its own
-/// instance slot, because the vertex stage indexes the skin palette with that same field and cannot
-/// borrow the wearer's. Its tint therefore has to come up the `ParentModel` link, which is the
-/// reference's own route for an attached model's colours (`0x714000`). Without this walk, adding the
-/// rig would have un-tinted exactly the pauldrons it was added for.
+/// A rigged attached model has its own instance slot, which the vertex stage indexes the palette
+/// by, so its tint comes up the `ParentModel` chain, as the reference composes it (`0x714000`).
 #[test]
 fn a_rigged_attachment_inherits_its_wearers_tint_through_the_model_chain() {
     let mut app = app_with_tint_channel();
@@ -697,7 +642,6 @@ fn a_rigged_attachment_inherits_its_wearers_tint_through_the_model_chain() {
         "and so is the pauldron riding it"
     );
 
-    // The aura drops: both ends of the chain go back to identity, not just the unit's own slot.
     crate::net::apply_fields_for_test(
         app.world_mut(),
         unit,
@@ -715,9 +659,6 @@ fn a_rigged_attachment_inherits_its_wearers_tint_through_the_model_chain() {
     );
 }
 
-/// An unchained rig — a placed doodad, a world effect — has no parent to inherit from and must stay
-/// its own colour. The walk's terminating case, and the guard against a chain lookup that
-/// "helpfully" falls back to some other unit's tint.
 #[test]
 fn an_unchained_rig_inherits_nothing() {
     let mut app = app_with_tint_channel();
@@ -754,9 +695,7 @@ fn an_unchained_rig_inherits_nothing() {
     );
 }
 
-/// A tinted unit going away must not leave its colour on the slot for whoever allocates it next —
-/// the leak that would paint an unrelated creature ghost-blue. Covered structurally by `RigSkin`'s
-/// free hook, so it holds for a despawn AND for a gear/display rebuild that replaces the component.
+/// `RigSkin`'s free hook clears the tint on a despawn or a component swap, before any reuse.
 #[test]
 fn the_rig_free_hook_clears_a_dead_units_tint() {
     let mut app = app_with_tint_channel();
@@ -787,7 +726,7 @@ fn the_rig_free_hook_clears_a_dead_units_tint() {
         0xff8c_b9fd,
     );
 
-    // Despawn without any aura edge — the unit streamed out mid-buff, which is the common case.
+    // Despawn with no aura edge: the unit streamed out mid-buff.
     app.world_mut().entity_mut(unit).despawn();
     assert_eq!(
         app.world()
@@ -800,16 +739,12 @@ fn the_rig_free_hook_clears_a_dead_units_tint() {
 
 // ── The freeze (proc 11) ─────────────────────────────────────────────────────────────────────────
 
-/// The arming world plus the clock-hold leg — the third proc's apply, ordered after the drain the
-/// way the real schedule orders it after the drain *and* the driver.
 fn app_with_freeze() -> App {
     let mut app = app_with_chains();
     app.add_systems(Update, apply_aura_anim_rate.after(drain_aura_procs));
     app
 }
 
-/// A rig mid-animation: two clips playing at the speeds the driver picked for them (a gait scaled to
-/// the mover's speed, and a cast one-shot at 1.0 — the pair Ice Block catches).
 fn rig_playing(speeds: &[(u32, f32)]) -> AnimationPlayer {
     let mut player = AnimationPlayer::default();
     for (node, speed) in speeds {
@@ -820,8 +755,7 @@ fn rig_playing(speeds: &[(u32, f32)]) -> AnimationPlayer {
     player
 }
 
-/// `(paused, speed)` of one armed clip — the two things the freeze is judged on: the clock is held,
-/// and the *value* other code copies is untouched.
+/// `(paused, speed)` of one armed clip: the freeze holds the clock and leaves the speed.
 fn clip(app: &App, rig: Entity, node: u32) -> (bool, f32) {
     let a = app
         .world()
@@ -833,10 +767,7 @@ fn clip(app: &App, rig: Entity, node: u32) -> (bool, f32) {
     (a.is_paused(), a.speed())
 }
 
-/// **The director's retest, at the mechanism.** Ice Block's state kit carries proc 11 at rate 0, so
-/// the unit's clocks stop dead: the run cycle it was mid-stride in and the cast one-shot that had
-/// just been armed both hold the frame they were on — which is why the caster never gets to raise
-/// their hand. Dropping the aura lets both go again, at the speeds the driver gave them.
+/// Ice Block's proc 11 at rate 0 holds the gait and the cast one-shot; the aura's end frees them.
 #[test]
 fn ice_block_holds_the_clocks_and_the_drop_lets_them_go() {
     let mut app = app_with_freeze();
@@ -854,18 +785,16 @@ fn ice_block_holds_the_clocks_and_the_drop_lets_them_go() {
 
     let n = app.world().entity(unit).get::<AuraNodes>().unwrap();
     assert_eq!(n.head_anim_rate(), Some(0.0), "kit 3709's proc 11 is 0");
-    // 9074175 = 0x8A75FF — the ice-blue the same kit tints the body with, beside the freeze.
+    // 9074175 is 0x8A75FF, the same kit's ice-blue tint.
     assert_eq!(n.head_tint(), Some([0x8A, 0x75, 0xFF]), "kit 3709's proc 1");
     assert!(clip(&app, unit, 4).0, "the gait stops mid-stride");
     assert!(clip(&app, unit, 54).0, "so does the cast one-shot");
-    // The SPEEDS are untouched, which is the whole point: nothing that copies a clip's rate
-    // (`transplant_up` does, to move a one-shot onto the torso overlay) can inherit the freeze.
+    // The speeds are untouched, so `transplant_up`, copying a clip's rate, never inherits a freeze.
     assert_eq!(clip(&app, unit, 4).1, 1.35);
     assert_eq!(clip(&app, unit, 54).1, 1.0);
 
     app.update(); // idempotent
 
-    // The aura leaves the slots.
     crate::net::apply_fields_for_test(
         app.world_mut(),
         unit,
@@ -889,12 +818,8 @@ fn ice_block_holds_the_clocks_and_the_drop_lets_them_go() {
     );
 }
 
-/// **The bug the first shipped version had, pinned so it cannot come back.** A one-shot moved to the
-/// torso overlay under the freeze (`transplant_up` copies the source clip's speed and seek) used to
-/// be saved at the frozen `0`, restored to `0`, and left welded to the upper body for the rest of the
-/// session — surviving every later cast, because a clip that never advances never *finishes* and so
-/// never releases the overlay. Pausing carries no value to copy: the transplant inherits the driver's
-/// real speed, and the thaw sets it running.
+/// A one-shot moved to the torso overlay under the freeze copies its source's speed, which the
+/// pause leaves real, so the thaw runs it out; a copied 0 would never finish or free the overlay.
 #[test]
 fn a_clip_armed_under_the_freeze_comes_back_at_its_own_speed() {
     let mut app = app_with_freeze();
@@ -946,8 +871,7 @@ fn a_clip_armed_under_the_freeze_comes_back_at_its_own_speed() {
     );
 }
 
-/// The mount comes with the rider: `0x6201d0` writes `[unit+0xdc]` before it writes `[unit+0xd8]`,
-/// so a frozen rider's mount stops under them rather than running on the spot.
+/// `0x6201d0` writes the mount `[unit+0xdc]` before the body `[unit+0xd8]`: the mount freezes too.
 #[test]
 fn the_freeze_reaches_the_mount_body() {
     let mut app = app_with_freeze();
@@ -982,8 +906,7 @@ fn the_freeze_reaches_the_mount_body() {
     assert_eq!(clip(&app, mount, 5).1, 2.0);
 }
 
-/// An aura with no proc 11 — Stealth — leaves the clocks entirely alone. The freeze is the kit's,
-/// never "any aura", and never the stun flag: nothing in the `0x40000` census touches animation.
+/// The freeze is proc 11's alone, never any aura's and never the stun flag's (`0x40000`).
 #[test]
 fn an_aura_without_the_proc_never_touches_a_clock() {
     let mut app = app_with_freeze();
@@ -1002,9 +925,8 @@ fn an_aura_without_the_proc_never_touches_a_clock() {
     assert!(app.world().entity(unit).get::<AnimRateFreeze>().is_none());
 }
 
-/// Kit 1744's `8947848.0` is a rate our f32-seconds clock cannot express (the reference's is integer
-/// ms with a modulo, where it is noise rather than a freeze). It installs a node — the data is read,
-/// not dropped — and the apply leaves the clocks alone rather than inventing a look for it.
+/// The one shipped non-zero rate, `8947848.0`, installs a node and holds no clock
+/// ([`apply_aura_anim_rate`]).
 #[test]
 fn a_non_zero_rate_installs_a_node_and_holds_nothing() {
     let mut n = AuraNodes::new(1.0);
diff --git a/crates/benilla-app/src/creature_anim.rs b/crates/benilla-app/src/creature_anim.rs
index 06438e09..9b3d5cef 100644
--- a/crates/benilla-app/src/creature_anim.rs
+++ b/crates/benilla-app/src/creature_anim.rs
@@ -1,37 +1,9 @@
-//! Movement-driven character & creature animation (decision 0019, Milestone C; the locomotion controller
-//! of decisions 0047 + 0049). Each animated unit carries a [`ModelAnimations`] component (its clips, by
-//! `AnimationData.dbc` id), an [`AnimationPlayer`], and an
-//! [`AnimationTransitions`][bevy::animation::transition::AnimationTransitions]; this module is a
-//! small per-unit state machine that picks the animation from the unit's movement state, **cross-fades**
-//! into it over the clip's blend-in time, and scales a locomotion clip's playback rate to the unit's
-//! speed.
-//!
-//! 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 (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
-//!   instant a movement flag changes (decisions 0083/0087 — land-then-press runs immediately).
-//! - **One-shots (swings, emotes)** — routed **per play from live state** (decision 0087, the
-//!   byte-verified `0x5fe2f0` route): a standing-idle unit plays them full-body on the base track
-//!   ([`select::Mode::Swing`]); a moving / seated / combat-airborne unit plays them on the SpineLow
-//!   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` (`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.
-//!
-//! The movement view is unified per unit ([`select::unify`]): the self-avatar's [`MovementState`] is
-//! filled by the player controller from input; a **remote player**'s comes from its relayed
-//! `MSG_MOVE_*` stream (live CMovement flags + extrapolation speed, via [`crate::net::RemoteMotion`]),
-//! so its walk/run/ strafe/backpedal/turn animate from the real flags; a **creature**'s is derived from
-//! its server [`crate::net::Spline`] (forward + speed). Stand-state (sit/sleep/kneel/chairs) comes from
-//! the unit's `UNIT_FIELD_BYTES_1` byte for streamed units, and from the controller (echo + in-flight
-//! request) for our own avatar (decision 0080c).
+//! Unit animation: a per-unit state machine that picks an `AnimationData.dbc` clip from movement
+//! state (the gait by speed and flags, reference selector `0x5fd8b0`; the stand-state and jump
+//! Specials; one-shots), cross-fades into it, and plays a locomotion clip at
+//! `speed / sequence.moveSpeed` (`0x5fe2f0`). A one-shot plays full-body on a standing idle unit
+//! and on the SpineLow torso-masked overlay while moving, seated or airborne in combat
+//! (`0x5fe2f0`). Death overrides everything.
 
 use std::time::Instant;
 
@@ -42,121 +14,59 @@ use bevy::prelude::*;
 use benilla_assets::AssetSet;
 use benilla_world::schedule::WorldStage;
 
-/// 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`].
+/// The pure selection logic: the `0x5fd100` tables, the gait, swing and ready picks, the rate math.
 pub(crate) mod select;
 pub(crate) use select::{
     ease_strafe_yaw, move_flags, strafe_body_offset, swim_body_rotation, MovementState,
 };
 use select::{Mode, Special};
 
-/// The display-facing counter-twist (the strafe body pose): the [`BodyTwist`] component + the
-/// post-animation system that composes the SpineLow/Head counter-rotation onto the frame's pose.
+/// The strafe body counter-twist, composed onto SpineLow and Head after animation.
 mod twist;
 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, 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).
+/// Parks an off-frustum rig's pose while its clocks and events run, as the reference does not
+/// tick one (`0x683dd0`). Where they differ: parked rigs here still draw, and every parked unit
+/// stays audible, where the reference keeps only `MORE_AUDIBLE` creatures audible off-screen.
 mod lod;
 
-/// The unit's wielded weapon classes — `(item class, item subclass)` per hand, `None` for an empty
-/// (or non-item) hand. Written by the held-item resolution ([`crate::entities`], decision 0072) from
-/// the same descriptor data that places the weapon models; read by the swing/ready animation
-/// selectors (decision 0073 — the byte-verified `GetWeapon` byte pair `0x605e30`).
-///
-/// **The two readings of a hand** (decision 1863). The reference's accessor takes a `visFlag`:
-/// `GetWeapon(slot, 1)` is what is *worn* there, `GetWeapon(slot, 0)` is what the unit can
-/// *fight* with — and the two differ by exactly one live descriptor bit, [`UNIT_FLAG_DISARMED`].
-/// The fields below are the `visFlag == 1` reading — what the paperdoll and the dress-up model
-/// show, the two surfaces that keep the weapon while disarmed because they read the flag nowhere.
-/// Everything that decides how the unit *behaves* — swing, Ready idle, parry, the sheath machine,
-/// the swing sound, the attached model — goes through [`Wielded::armed_main`] /
-/// [`Wielded::armed_off`], which apply the ladder.
+/// Wielded `(item class, subclass)` per hand as worn (`GetWeapon(slot, 1)`, `0x605e30`, what the
+/// paperdoll shows); behaviour reads `armed_main`/`armed_off`, which apply the disarm ladder.
 #[derive(Component, Clone, Copy, Default, PartialEq, Eq)]
 pub(crate) struct Wielded {
     pub(crate) main: Option<(u8, u8)>,
     pub(crate) off: Option<(u8, u8)>,
-    /// The **ranged-slot** item's `(class, subclass)` — the local auto-repeat idle's selector
-    /// ([`select::ranged_load_anim`], the client's `0x5fd530` LUT; decision 0099 phase 5).
+    /// The ranged-slot item's `(class, subclass)`, the auto-repeat idle's selector (`0x5fd530`).
     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 (`0x611930`:
-    /// `(1 << (rec[+4] & 0x1f)) & 0x88` → HipSheath 90 for types {3, 7},
-    /// Sheath 89 otherwise; the slot's own byte is the *only* input).
+    /// The hand items' sheath types (0 none, 1 back 2H, 2 back staff, 3 hip, 4 shield); each picks
+    /// its arm's draw/stow clip, HipSheath 90 for types 3 and 7, else Sheath 89 (`0x611930`).
     pub(crate) main_sheath: u8,
     pub(crate) off_sheath: u8,
-    /// The ranged item's sheath type, same pick — the ranged **draw** clip reads it
-    /// (`0x6118a0`/`0x611960`/`0x611a20` all run `(1 << (rng[+4] & 0x1f)) & 0x88` on the ranged
-    /// record). Its **stow** clip does not: `0x611b60`'s PREV==2 legs push a literal `0x59`
-    /// (`0x611c8c`/`0x611cd3`), so a bow is always put away with Sheath 89.
+    /// The ranged sheath type: it picks the draw clip (`0x6118a0`), but the stow is always
+    /// Sheath 89 (`0x611b60`).
     pub(crate) ranged_sheath: u8,
-    /// The ranged item's `InventoryType` — the byte-verified **arm** pick: `0x1a`
-    /// (RANGEDRIGHT: gun/crossbow/wand) and `0x19` (THROWN) go to the right arm, everything else
-    /// (`0x0f`, a bow) to the left (`0x611b60` @ `0x611c74`, and the same compare in both
-    /// drawers). `0` when nothing is in the ranged slot.
+    /// The ranged `InventoryType` (0 when empty): `0x1a` and `0x19` draw with the right arm,
+    /// anything else (`0x0f`, a bow) with the left (`0x611b60` @ `0x611c74`).
     pub(crate) ranged_inv: u32,
-    /// Each slot's `Material` id — the **only** key the draw/stow sound pick uses
-    /// (`SheatheSoundLookups`, decision 0882). Not derivable from the weapon class: real 5875 data
-    /// has maces (subclass 4) in both metal and wood, and puts every bow, crossbow and wand in
-    /// wood while guns and thrown are metal. It rides the wire — `SMSG_ITEM_QUERY_SINGLE_RESPONSE`
-    /// for players, the `UNIT_VIRTUAL_ITEM_INFO` byte triple for creatures — so nothing here is a
-    /// guess. Indexed by held slot: 0 mainhand · 1 offhand · 2 ranged.
+    /// Each held slot's `Material` (main, off, ranged), the draw/stow sound's only key; off the
+    /// wire, since the weapon class does not determine it.
     pub(crate) materials: [u8; 3],
-    /// `UNIT_FIELD_FLAGS & `[`UNIT_FLAG_DISARMED`] — a rogue's Disarm, up on the unit's own
-    /// descriptor and therefore replicated for **every** unit, not just ours (CGUnit's ladder is
-    /// byte-identical to CGPlayer's, so a disarmed creature behaves exactly like a disarmed
-    /// player). Resolved beside the hands because that is where the reference reads it: inside
-    /// `GetWeapon` itself (`[[unit+0x110]+0xa0] & 0x200000`), off the same descriptor these pairs
-    /// come from.
+    /// `UNIT_FIELD_FLAGS & UNIT_FLAG_DISARMED`, replicated for every unit; the reference reads it
+    /// inside `GetWeapon` (`[[unit+0x110]+0xa0] & 0x200000`), for creatures as for players.
     pub(crate) disarmed: bool,
 }
 
-/// `UNIT_FIELD_FLAGS` bit 21 — **`UNIT_FLAG_DISARMED`** (vmangos `UnitDefines.h`), read by the
-/// reference inside `GetWeapon` at `0x5ec2b8` (CGPlayer) and `0x605e58`/`0x605e98` (CGUnit):
-/// `test dword ptr [ecx+0xa0], 0x200000`. `0xa0 = 4 × 0x28` pins it to field `UNIT_FIELD_FLAGS`
-/// off the descriptor base `[unit+0x110]`.
+/// `UNIT_FIELD_FLAGS` bit 21 (vmangos `UnitDefines.h:566`), tested inside `GetWeapon` at
+/// `0x5ec2b8` (CGPlayer) and `0x605e58`/`0x605e98` (CGUnit).
 pub(crate) const UNIT_FLAG_DISARMED: u32 = 0x0020_0000;
 
-/// `ItemClass` 2 — **WEAPON**. The class byte the reference's disarm ladder tests, and the whole
-/// of its test: no subclass, no inventory type, nothing else. Disarm takes weapons, so a shield or
-/// a held-in-off-hand trinket is never the hand it hides.
+/// `ItemClass` 2, weapon: the disarm ladder's whole test, so a shield is never the hand it hides.
 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; 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
-/// opposite of the main hand's:
-///
-/// ```text
-/// ; slot 0 (MAIN HAND) — one probe, 0x5ec2ae
-/// 5ec2b8: test dword ptr [ecx+0xa0],0x200000  ; disarmed?
-/// 5ec2cc: call [edx+0x98]                     ; GetWeapon(0, 1) — vis=1 skips the gate
-/// 5ec2d6: cmp byte ptr [eax],2 ; je 0x5ec346  ; class 2 -> RETURN NULL
-///
-/// ; slot 1 (OFF HAND) — two probes, 0x5ec262, MAIN HAND asked FIRST
-/// 5ec280: call [edx+0x98]                     ; GetWeapon(0, 1)   <<< slot 0, not 1
-/// 5ec28a: cmp byte ptr [eax],2 ; je 0x5ec2aa  ; main hand IS a weapon -> PROCEED (keep the off hand)
-/// 5ec297: call [eax+0x98]                     ; GetWeapon(1, 1)
-/// 5ec2a1: cmp byte ptr [eax],2 ; je 0x5ec346  ; off hand IS a weapon -> RETURN NULL
-/// ```
-///
-/// So **exactly one weapon is hidden — the first one found scanning main hand → off hand** — and
-/// a disarmed dual-wielder keeps swinging their off-hand weapon, model and all. vmangos agrees
-/// from the other side: `Unit::CanUseEquippedWeapon` returns `!DISARMED` for `BASE_ATTACK` and an
-/// unconditional `true` for `OFF_ATTACK` and `RANGED_ATTACK`. The **ranged slot is never gated**
-/// (`0x5ec25e` pushes equip index `0x11` and jumps past both tests).
-///
-/// Stated over classes rather than over [`Wielded`] because two layers need the same law from two
-/// different data sources — the animation layer off the resolved hands, the action bar's
-/// equipped-item test off the raw inventory (`0x5ea5d0`'s slot 0/1/2 loop).
+/// The one held slot the disarm hides: the main hand if it holds a weapon, else the off hand if it
+/// does (`GetWeapon(slot, 0)`, `0x5ec2ae`/`0x5ec262`); the ranged slot is never gated
+/// (`0x5ec25e`), as vmangos agrees (`Unit.h:991`). Over classes so the action bar's
+/// equipped-item test (`0x5ea5d0`) can use it on raw inventory.
 pub(crate) fn disarmed_hand(main_class: Option<u8>, off_class: Option<u8>) -> Option<usize> {
     if main_class == Some(ITEM_CLASS_WEAPON) {
         return Some(0);
@@ -168,112 +78,66 @@ pub(crate) fn disarmed_hand(main_class: Option<u8>, off_class: Option<u8>) -> Op
 }
 
 impl Wielded {
-    /// The held slot this unit's disarm hides right now — [`disarmed_hand`] over its own hands,
-    /// `None` while the flag is down. The equipment layer reads it to know which weapon the
-    /// reference's flag reflex takes off the hand ([`crate::entities`]).
+    /// The held slot this unit's disarm hides now, `None` while the flag is down.
     pub(crate) fn disarmed_hand(&self) -> Option<usize> {
         self.disarmed
             .then(|| disarmed_hand(self.main.map(|(c, _)| c), self.off.map(|(c, _)| c)))
             .flatten()
     }
 
-    /// The **mainhand** as `GetWeapon(0, 0)` sees it — the reading the swing (`0x6246a0`), the
-    /// Ready idle (`0x5fcdc0`), the parry LUT, the sheath machine and the swing sound all take.
+    /// The main hand as `GetWeapon(0, 0)` sees it, read by the swing (`0x6246a0`), the Ready idle
+    /// (`0x5fcdc0`), the parry table, the sheath machine and the swing sound.
     pub(crate) fn armed_main(&self) -> Option<(u8, u8)> {
         self.main.filter(|_| self.disarmed_hand() != Some(0))
     }
 
-    /// The **offhand** as `GetWeapon(1, 0)` sees it. Nulled only when the main hand did *not*
-    /// claim the disarm — see [`disarmed_hand`].
+    /// The off hand as `GetWeapon(1, 0)` sees it.
     pub(crate) fn armed_off(&self) -> Option<(u8, u8)> {
         self.off.filter(|_| self.disarmed_hand() != Some(1))
     }
 }
 
-/// The unit is engaged in melee auto-attack (`SMSG_ATTACKSTART` .. `ATTACKSTOP`, decision 0073):
-/// standing still it plays the weapon-class Ready idle — the client's `0x5fd360` arm gates on the
-/// auto-attack-target GUID being set, i.e. engagement, **not** sheath state.
-///
-/// **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. Every animation reader still asks only
-/// `With`/`Has`, which is unchanged by the payload.
+/// Auto-attacking (`SMSG_ATTACKSTART` to `ATTACKSTOP`), holding the target guid, the reference's
+/// `[+0xc48]`: the Ready idle gates on it, not on sheath (`0x5fd360`); `0x6e3480` reads its reach.
 #[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`). 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`], `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::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.
+/// The local player's auto-repeat is armed: the reference's `[+0xd58] & 0x200`, set only by the
+/// local cast-send (`0x6e593b`); with the ranged sheath drawn a standing unit idles on the Load
+/// clip (`0x5fd460`). Cleared only through `cancel_auto_repeat_local`, including on
+/// `SMSG_CANCEL_AUTO_REPEAT`, which vmangos sends when a volley's target dies
+/// (`SpellCaster.cpp:1829`). A remote shooter plays LoadBow once at its `SMSG_SPELL_START`
+/// (`CastHold`, `0x6e7901`), then the fire clip per GO; the reference holds HoldBow (109) from
+/// the end of the Load until the first GO.
 #[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`).
-/// 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`).
-/// 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 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
-/// (`select::ranged_hold_anim`), where the reference re-arms it at each completion while the gate
-/// holds. The two diverge only where `0x400` holds *without* `0x200` — a remote shooter's latent
-/// hold — and a remote shooter never enters the drawn idle at all (`0x5fd460` claims on `0x200`,
-/// which only the local cast-send sets), so the case cannot arise. Reading the bit as a second
-/// *entry* into the drawn idle remains wrong: that is what left a shooter aiming forever after
-/// one Serpent Sting (decision 0991).
+/// The ranged weapon-visual hold, `[+0xd58] & 0x400`, set for any caster whose ranged visual
+/// plays (`0x60d020`); cleared by a non-ranged visual (`0x6ec39e`), the local cancel, melee
+/// attack-start or a spline move (`0x6020e8`), never by a sheath change or volley end. It gates
+/// nothing here: the reference re-arms the Hold at each completion while it holds (`0x5fc3f0`,
+/// via `0x7075af`), ours loops the Hold once armed. It is no entry into the drawn idle: read as
+/// one, it leaves a shooter aiming after a single Serpent Sting.
 #[derive(Component)]
 pub(crate) struct RangedHold;
 
-/// A unit's displayed **nocked ammo** — the client's `[+0xd28]`/`[+0xd2c]` ammo-model pair,
-/// 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
-/// cancel, leaving the ranged sheath stance (`0x60fc72`), or a weapon change.
+/// The displayed nocked ammo, the reference's `[+0xd28]`/`[+0xd2c]` (`UpdateAmmoDisplay`
+/// `0x60ba30`): an `ItemDisplayInfo` model at HandArrow (35), bow only (`0x60bb19`), set per shot
+/// from the `SMSG_SPELL_START` ammo tail. Removed by the un-nock `0x60f530`: the local cancel,
+/// leaving the ranged sheath (`0x60fc72`), or a weapon change.
 #[derive(Component, Clone, Copy, PartialEq, Eq)]
 pub(crate) struct NockedAmmo {
-    /// The ammo's `ItemDisplayInfo` id (never 0 — an id-0 refresh removes the component instead).
+    /// Never 0: an id-0 refresh removes the component.
     pub(crate) display_id: u32,
 }
 
-/// 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
-/// flies) and by the un-nock paths. The equipment attach leg shows the [`NockedAmmo`] model only
-/// while this holds, and the bowstring's middle vertex tracks the draw hand on the same gate.
+/// The nock latch `[+0xd58] & 0x4000`: set at `$BWP` (`0x624b70`, LoadBow ~0.6 s), cleared at
+/// `$BWR` (`0x60016c`, AttackBow ~0.067 s) and on un-nock; the arrow model shows only while set.
 #[derive(Component)]
 pub(crate) struct NockLatch;
 
-/// Drive [`NockLatch`] from the anim-event stream ([`AnimSoundEvent`] — the same `$`-tag
-/// keyframes the sound/impact consumers ride): `$BWP` latches (only a unit with a [`NockedAmmo`]
-/// display cached — the client's handler gates on the cached ranged spell), `$BWR` clears.
-/// Ordered after [`events::fire_anim_events`] so a tag lands the frame it's crossed.
+/// `$BWP` latches a unit with `NockedAmmo` cached, `$BWR` clears; runs after `fire_anim_events`
+/// so a tag lands the frame it is crossed.
 pub(crate) fn drive_nock_latch(
     mut events: MessageReader<AnimSoundEvent>,
     nocked: Query<Has<NockedAmmo>>,
@@ -282,9 +146,7 @@ pub(crate) fn drive_nock_latch(
     for ev in events.read() {
         match &ev.ident {
             b"$BWP" if nocked.get(ev.entity) == Ok(true) => {
-                // `try_insert`, matching the `$BWR` arm's guard below: the tag names a unit that
-                // may be despawned by the time these commands apply (the fade lane is unordered
-                // against this chain — B130's second window, in the same defect class).
+                // `try_insert`: the unit may be despawned by the time the commands apply.
                 commands.entity(ev.entity).try_insert(NockLatch);
             }
             b"$BWR" => {
@@ -297,13 +159,9 @@ pub(crate) fn drive_nock_latch(
     }
 }
 
-/// 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
-/// falls back to the ordinary stand. Every cancel trigger funnels here, like the client's 8
-/// live callers.
+/// The one local auto-repeat cancel, reference `0x6ea080`: clears the key (`[0xceac30]`), both
+/// idle bits and the nock (`0x60f530`) and sends `CMSG_CANCEL_AUTO_REPEAT_SPELL` (`0x6ea0c6`);
+/// the sheath stays drawn.
 pub(crate) fn cancel_auto_repeat_local(
     entity: Option<Entity>,
     auto_repeat: &mut crate::spell::AutoRepeatActive,
@@ -311,7 +169,7 @@ pub(crate) fn cancel_auto_repeat_local(
     net: &crate::net::NetCommands,
 ) {
     if auto_repeat.0.is_none() {
-        // The client's `[0xceac30] == 0` early-out — nothing running, nothing sent.
+        // The reference's `[0xceac30] == 0` early-out: nothing running, nothing sent.
         return;
     }
     auto_repeat.0 = None;
@@ -323,36 +181,18 @@ pub(crate) fn cancel_auto_repeat_local(
     let _ = net.0.send(crate::net::ClientCommand::CancelAutoRepeat);
 }
 
-/// 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::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").
-///
-/// The lock is our server-echoed [`Engaged`] — the ref's `[+0xc48]`, which it sets *locally* at
-/// attack-start and which **StopAttack does not clear** (only the `SMSG_ATTACKSTOP` echo does,
-/// `0x624e40`), so the Attack button's own ring survives this call in both clients. Two ref fields
-/// 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::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.
+/// The local StopAttack, reference `0x5ecac0`: when attacking, `CMSG_ATTACKSTOP` (`0x624370`),
+/// then `CancelQueuedCast` (`0x6e6f30`) cancels a queued on-next-swing spell with
+/// `CMSG_CANCEL_CAST` (`0x6e4940`), which is why Auto Shot (`0x6e5976`) darkens a Raptor Strike
+/// ring. `Engaged` stays until the `SMSG_ATTACKSTOP` echo (`0x624e40`), as in the reference.
 pub(crate) fn stop_attack_local(
     engaged: bool,
     queued_melee: &mut crate::spell::QueuedMeleeSpell,
     net: &crate::net::NetCommands,
 ) {
     if !engaged {
-        // The ref's `!IsAttacking(0x60ecb0) && [+0xc50] == 0` early-out: nothing running,
-        // nothing sent — and the queued strike, which cannot exist without a swing to fire it,
-        // survives untouched.
+        // The reference's `!IsAttacking(0x60ecb0) && [+0xc50] == 0` early-out (`[+0xc50]`, a
+        // locally started attack, is not modelled): nothing sent, a queued strike survives.
         return;
     }
     let _ = net.0.send(crate::net::ClientCommand::AttackStop);
@@ -364,27 +204,11 @@ pub(crate) fn stop_attack_local(
     }
 }
 
-/// 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
-///   stop → select → re-swing re-points at a new target instead of going quiet;
-/// - **the tail** (`0x5ecd78`–`0x5ecd95`) — melee sheath SNAP then the local auto-repeat cancel
-///   `0x6ea080` — runs either way, because the skip's `jmp` lands *inside* it. That is what makes
-///   "start swinging" and "keep auto-shooting" mutually exclusive.
-///
-/// `stop_in_flight` is a **parameter, not stored state**: the ref's `[+0xc54]` is set by
-/// [`stop_attack_local`] and consumed here, and the only caller that spans both is the target
-/// switch, which does them back to back in one call chain. Decision 1036 removed the persistent
-/// latch for exactly this reason — outside that chain it has no reader.
-///
-/// The caller owes the reference's own two entry conditions, which differ per site and are not
-/// re-derived here: a cast press must not call this at all while engaged (`TryCast`'s `6e51cb`/
-/// `6e51d2` gate), and the Attack button forks to [`stop_attack_local`] instead (`0x6131a0` @
-/// `0x6131d9`). `0x5ecb70`'s own validator legs — the target's alive-or-feign + `CanAttack
-/// 0x606980` walk, and the `[0xb4b3e4]` world gate — stay with the callers that already compute
-/// them (`target::scan`'s `new_attackable`, the drain's `attack_actor_refusal`).
+/// The local StartAttack, reference `0x5ecb70`: the swing send (`0x5eccfd`) is skipped while
+/// attacking unless a stop is in flight (`[+0xc54]`, which the target switch passes as
+/// `stop_in_flight`); the tail, melee sheath snap then auto-repeat cancel (`0x5ecd78`), always
+/// runs, so melee and auto-shot are exclusive. Callers own the entry checks: no call from a cast
+/// press while engaged (`0x6e51cb`), the attackability walk (`0x606980`) and `[0xb4b3e4]`.
 pub(crate) fn start_attack_local(
     entity: Entity,
     target: u64,
@@ -395,27 +219,16 @@ pub(crate) fn start_attack_local(
     commands: &mut Commands,
     net: &crate::net::NetCommands,
 ) {
-    // **Starting an attack stands you up** — `0x5ecc9b call 0x5ed430(0)`, inside this function and
-    // ahead of everything else it does (decision 1768).
-    //
-    // Its position is the content. It sits **after** the attackability cluster
-    // (`0x5ecc2e`/`0x5ecc35`, whose not-attackable leg diverts to `0x5ecc37` and never reaches the
-    // stand) — which is why a right-click on a friendly NPC does not stand you — and **before any
-    // range logic**, `CMSG_ATTACKSWING` being all the way down at `0x5eccfd`. So an attackable
-    // target out of reach *does* stand you, and so does re-issuing an attack you are already
-    // making: that skip lands at `0x5ecd78`, 73 bytes past the stand. Hence unconditional here,
-    // above the swing's own `engaged` fork, rather than inside it.
-    //
-    // benilla's callers own the attackability walk (see this function's header), so by the time we
-    // are called the diverting leg has already been taken elsewhere.
+    // Starting an attack stands you up (`0x5ecc9b`), after the attackability check but before
+    // the range logic and the already-attacking skip, so a re-issued or out-of-reach attack
+    // stands you too.
     commands.write_message(crate::player::StandStateRequest { state: 0 });
     if !engaged || stop_in_flight {
         let _ = net
             .0
             .send(crate::net::ClientCommand::AttackSwing { guid: target });
     }
-    // The tail. The sheath setter is idempotent — the client's own "no-op if already melee" — so
-    // re-running it on a re-point costs nothing and matches `0x5ecd80`'s unconditional call.
+    // Idempotent, matching `0x5ecd80`'s unconditional call.
     sheath.write(SheathRequest {
         entity,
         state: 1,
@@ -424,20 +237,9 @@ pub(crate) fn start_attack_local(
     cancel_auto_repeat_local(Some(entity), auto_repeat, commands, net);
 }
 
-/// The **Attack toggle** — benilla's `0x6131a0`, the third of the trio and the one the base Attack
-/// 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`].
-///
-/// 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 —
-/// but only the start arm reaches `0x5ecd8c`, so in the reference toggling melee off leaves Auto
-/// Shot running.
-///
-/// `[0xb4b3e4]` — the reference's second condition on the stop arm, a world/session global also
-/// tested at `0x5ecbc0` — is unmodelled; nothing in benilla can be false there while a press is
-/// being drained.
+/// The Attack toggle, reference `0x6131a0` (the Attack pseudo-spell, `0x6e4c7a`): stop when
+/// attacking, else start. Only the start arm cancels auto-repeat, so toggling melee off leaves
+/// Auto Shot running. The stop arm's `[0xb4b3e4]` world gate is not modelled.
 pub(crate) fn toggle_attack_local(
     entity: Entity,
     target: u64,
@@ -464,15 +266,8 @@ pub(crate) fn toggle_attack_local(
     }
 }
 
-/// **The local attack seams' whole write set, as ONE [`SystemParam`]** — so a caller threading
-/// [`stop_attack_local`]/[`start_attack_local`] through a call chain takes one param instead of
-/// six, and so a new sink in either seam lands in every caller at once.
-///
-/// 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::spell::cast_send::CastLadder`] already carries them field by field for the
-/// cast path and calls the free functions directly.
+/// The attack seams' write set as one param, for the selection writers that run the reference's
+/// stop, select, re-swing (`SetSelection` `0x493540`).
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct AttackSeam<'w, 's> {
     pub(crate) net: Res<'w, crate::net::NetCommands>,
@@ -480,17 +275,17 @@ pub(crate) struct AttackSeam<'w, 's> {
     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.
+    /// Our own entity.
     pub(crate) me: Query<'w, 's, Entity, With<crate::net::SelfPlayer>>,
 }
 
 impl AttackSeam<'_, '_> {
-    /// `0x5ecac0` — see [`stop_attack_local`].
+    /// StopAttack (`0x5ecac0`).
     pub(crate) fn stop(&mut self, engaged: bool) {
         stop_attack_local(engaged, &mut self.queued_melee, &self.net);
     }
 
-    /// `0x5ecb70` — see [`start_attack_local`]. A no-op before our own entity streams in.
+    /// StartAttack (`0x5ecb70`); a no-op before our own entity streams in.
     pub(crate) fn start(&mut self, target: u64, engaged: bool, stop_in_flight: bool) {
         let Ok(e) = self.me.single() else { return };
         start_attack_local(
@@ -506,15 +301,8 @@ impl AttackSeam<'_, '_> {
     }
 }
 
-/// A unit is mid-cast (`SMSG_SPELL_START` .. `GO`/`FAILED_OTHER`, decision 0099 phase 1) — the
-/// wire-truth state seam. Inserted on `SpellStart` only when it carries a nonzero cast time (an
-/// instant cast's `SpellGo` follows with nothing to interrupt, so it never gets one); removed on
-/// the matching-spell-id `SpellGo`/`SpellFailedOther` (the client's reap `0x614150(spellId, 0)` is
-/// keyed — a triggered proc's GO mid-cast never clears a different spell's precast, decision 0107).
-/// The *animation* side rides [`CastEvent`]/[`CastHold`] (the resolved layer,
-/// [`spell_visual::route_cast_visuals`]), not this component. `until` is `Option` rather than a
-/// bare deadline so a later channel (an open-ended cast, no fixed end) can land here without a
-/// sentinel.
+/// Mid-cast (`SMSG_SPELL_START` to GO or failure), inserted only for a nonzero cast time and
+/// removed by the same spell id (the reference's reap `0x614150(spellId, 0)` is keyed).
 #[derive(Component, Clone, Copy)]
 pub(crate) struct Casting {
     pub(crate) spell_id: u32,
@@ -522,16 +310,10 @@ pub(crate) struct Casting {
     pub(crate) until: Option<Instant>,
 }
 
-/// 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
-/// (`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
-/// (a missile arriving, an interact emote) stamp when they fire, which is after that frame's
-/// packets, exactly where the client's scene-update calls sit. [`driver::drive_animations`]
-/// resolves a same-frame collision by the highest stamp.
+/// The reference's PlayAnimation order: handlers run in packet order and the later play wins
+/// bone 0 (`0x5fe2f0`). benilla's swing and cast pipelines are separate streams, so each
+/// animation-bearing message carries a stamp (the wire in packet order, scene-time emitters when
+/// they fire), and the driver resolves a same-frame collision by the highest.
 #[derive(Resource, Default)]
 pub(crate) struct PlaySeq(u64);
 
@@ -542,181 +324,109 @@ impl PlaySeq {
     }
 }
 
-/// A cast lifecycle edge on a streamed unit, straight off the wire (written by the net bridge,
-/// consumed by [`spell_visual::route_cast_visuals`], which resolves spell → `SpellVisual` → kit →
-/// animation/sound — the DBC knowledge stays in the anim layer, decision 0107).
+/// A cast lifecycle edge on a streamed unit, off the wire.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct CastEvent {
     pub(crate) entity: Entity,
     pub(crate) spell_id: u32,
     pub(crate) kind: CastEventKind,
-    /// [`PlaySeq`] stamp at emission — carried through to the kit's [`EmoteAnim`].
+    /// `PlaySeq` stamp, carried to the kit's `EmoteAnim`.
     pub(crate) seq: u64,
 }
 
-/// Which cast edge fired (decision 0107 verdict 2's stage wiring).
+/// Which cast edge fired.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub(crate) enum CastEventKind {
-    /// `SMSG_SPELL_START` — the precast kit persists from here (subliminal for an instant, whose
-    /// GO follows at once).
+    /// `SMSG_SPELL_START`: the precast kit persists from here.
     Start,
-    /// `SMSG_SPELL_GO` — reaps the precast, plays the cast/release kit.
+    /// `SMSG_SPELL_GO`: reaps the precast, plays the cast kit.
     Go,
-    /// The cast died without a release (`SMSG_SPELL_FAILED_OTHER`, or our own failed
-    /// `SMSG_CAST_RESULT`) — reap only, nothing plays.
+    /// Died without release (`SMSG_SPELL_FAILED_OTHER`, or our failed `SMSG_CAST_RESULT`).
     Fail,
-    /// The spell **landed on this unit** (`entity` = the struck target, not the caster — decision
-    /// 0099 phase 4): a missile arrival, written back by `crate::entities::missile`. Plays the
-    /// impact kit (stage 1) + the state kit (stage 2) on the target — the client's unit-impact
-    /// hand-off `0x61dc50`. A speed-0 spell's impacts never come through here: the router plays
-    /// them inline at the GO (same resolve, no round-trip). `weapon_visual` = the caster's
-    /// ranged-weapon substitute `SpellVisual` id, resolved at GO time and carried through the
-    /// flight (the caster may despawn mid-flight; the client's missile carries its kit context)
-    /// — the `0x60d450` fallback a basic shot's impact kit resolves through (decision 0370).
+    /// The spell landed on this unit (a missile arrival, `0x61dc50`): impact kit, then state kit.
+    /// `weapon_visual` is the caster's ranged-weapon `SpellVisual` (`0x60d450`), carried from the
+    /// GO since the caster may despawn.
     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). 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**.
+    /// A projectile with no live target at arrival (`0x61d870`, a despawned target too): the kit
+    /// plays on the caster (`entity`) at `pos` (`0x61d8e7`), `SpellVisual` field 13, stage 3. Sent
+    /// here only for a dest-targeted GO's missile with no hit (`MissileSpawn::ground_aim`).
     GroundImpact { pos: Vec3 },
 }
 
-/// The resolved casting **hold** — the animation a unit sustains while a cast or channel is in
-/// flight (`SpellVisualKit` field 2 of the precast/channel kit, decision 0107). Managed entirely
-/// by [`spell_visual::route_cast_visuals`]; the driver renders it per frame: **standing → the
-/// gait slot, full-body** (the client's stationary-cast pin — the settled `[CGUnit+0xb4]` gate) —
-/// **moving → a looping masked overlay** (the ordinary torso-masked route a moving caster falls
-/// through to). A Special (jump/pose) outranks it — the server interrupts such casts anyway.
-/// `spell_id` keys the reap, like everything in this pipeline (the client's `0x614150(spellId, …)`):
-/// an unrelated spell's GO/fail never drops another cast's hold.
+/// The anim held while a cast is in flight (`SpellVisualKit` field 2): full-body when standing
+/// (`[CGUnit+0xb4]`), a looping masked overlay when moving; reaped by `spell_id`.
 #[derive(Component, Clone, Copy)]
 pub(crate) struct CastHold {
     pub(crate) anim_id: u16,
     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), so while this hold is live the sheath
-    /// reconcile's force-stow never survives the frame ([`driver`]'s bracket override).
+    /// A ranged wind-up (`Attributes & 0x2`): the reference brackets it with ranged snaps
+    /// (`0x60f34c`, `0x6e5930`), so the sheath reconcile's force-stow never survives the frame.
     pub(crate) ranged: bool,
 }
 
-/// 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 (`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.
+/// A hand's fingers close (`HandsClosed`, 15) purely because a weapon occupies its attach point,
+/// not on combat or sheath; a shield or empty hand stays open (`0x60b590`, paperdoll `0x5059a0`).
 #[derive(Component, Default, Clone, Copy, PartialEq, Eq)]
 pub(crate) struct HandGrip {
-    /// A weapon occupies the right-hand attach point (mainhand, id 1).
+    /// A weapon on the right-hand attach point (id 1).
     pub(crate) right: bool,
-    /// A weapon occupies the left-hand attach point (a non-shield offhand, id 2).
+    /// A weapon on the left-hand attach point (id 2), not a shield.
     pub(crate) left: bool,
 }
 
-/// The weight of the per-hand weapon-grip finger overlay ([`benilla_assets::ModelAnimations::hand_close`])
-/// over the base gait on the finger key-bones both drive. The base clip animates the whole skeleton
-/// (fingers at Stand's flat 0°) and isn't masked out of the finger subtree, so grip and base blend there —
-/// this makes the grip dominate ≈ 8:1 (the fingers read closed, not a half-open wash). Same rationale/value
-/// as the sheath ceremony and the upper-body one-shot overlays. Shared by the live driver
-/// ([`driver::drive_hand_grip`]) and the glue-booth spawn ([`crate::portrait`]) so both blend the grip
-/// identically.
+/// The grip overlay's weight over the unmasked base on the fingers, about 8:1 so they read closed.
 pub(crate) const HAND_GRIP_WEIGHT: f32 = 8.0;
 
-/// One completed melee swing for `attacker` (`SMSG_ATTACKERSTATEUPDATE` → the net bridge; decision
-/// 0073: one packet = one swing animation, no client-side timer). `hit_info` bit `0x4` = offhand
-/// swing; bit `0x10000` suppresses the animation. The outcome fields (`victim`, `victim_state`,
-/// `damage`) ride along for the combat-audio consumer (`sound::combat`), which plays the swing's
-/// sounds when the animation's `$CSS`/`$CAH`/`$HIT` events fire. A fully-absorbed swing's
-/// "Absorb" word keys `hit_info & 0x20`, not a magnitude (`0x6243e0` never reads one — decision
-/// 0279), so no absorb field rides here; the full-block synthesis likewise rewrites
-/// `victim_state` in the net bridge before this message is built.
+/// One melee swing (`SMSG_ATTACKERSTATEUPDATE`): one packet, one animation. `hit_info` `0x4` is
+/// off-hand, `0x10000` suppresses the animation, `0x20` is an absorb (`0x6243e0`); the net bridge
+/// rewrites a full block's `victim_state` first.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct SwingMessage {
     pub(crate) attacker: Entity,
-    /// The swing's target, when it's streamed to us.
+    /// The swing's target, when streamed.
     pub(crate) victim: Option<Entity>,
     pub(crate) hit_info: u32,
-    /// vmangos `VictimState`: 1 hit · 2 dodge · 3 parry · 4 interrupt · 5 blocks · 6 evades ·
-    /// 7 immune · 8 deflects (decision 0279's byte-verified consequence table keys off it).
+    /// vmangos `VictimState`: 1 hit, 2 dodge, 3 parry, 4 interrupt, 5 block, 6 evade, 7 immune,
+    /// 8 deflect.
     pub(crate) victim_state: u32,
     pub(crate) damage: u32,
-    /// `0x625e40`'s verdict, carried from the packet because **the floating number is gated by it
-    /// too** ([`benilla_protocol::messages::AttackerState::displayed`]): `0x62440d` is the first
-    /// thing the worldtext builder `0x6243e0` does. Everything else this message drives — the
-    /// animation, the flinch, the blood, the sounds, the timers — runs regardless, which is why
-    /// the verdict rides along instead of suppressing the message.
+    /// `0x625e40`'s display verdict: it gates only the floating number (`0x62440d`); animation,
+    /// flinch, blood, sounds and timers run regardless.
     pub(crate) displayed: bool,
-    /// [`PlaySeq`] stamp at emission (the wire drain, in packet order).
+    /// `PlaySeq` stamp, in packet order.
     pub(crate) seq: u64,
 }
 
-/// Play a one-shot **anim-emote** on a unit: the given `AnimationData.dbc` id, played over the
-/// gait and returning to it when it finishes (the [`select::Mode::Swing`] one-shot pattern). The
-/// gossip/vendor interact route ([`crate::target`], decision 0081) uses it to play EmoteTalk
-/// (id 60) on the self-player: the per-animation sheath reconcile then reads that clip's
-/// WeaponFlags (`0x10`) and stows the drawn weapon — a committed state change that *persists*
-/// after the emote (nothing restores it; weapons stay stowed until re-triggered — decision 0080).
-/// The stow is the emote's flags, not a sheath wire. Also fed by the `SMSG_EMOTE` receive path
-/// ([`emote_anim::emote_to_anim`]), which maps a bridged anim emote's `Emotes.dbc` id to its
-/// `AnimID` — `/wave`, `/bow`, `/laugh`, `/cheer`, … all play through this same one-shot.
+/// A one-shot anim emote over the gait; its clip's WeaponFlags (`0x10`) stow a drawn weapon, and
+/// the stow persists after it.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct EmoteAnim {
     pub(crate) entity: Entity,
     pub(crate) anim_id: u16,
-    /// [`PlaySeq`] stamp — a kit anim inherits its [`CastEvent`]'s; scene-time emitters stamp
-    /// fresh at fire time. The driver's same-frame swing collision resolves by the higher stamp.
+    /// `PlaySeq` stamp; a kit anim inherits its `CastEvent`'s.
     pub(crate) seq: u64,
 }
 
-/// A **state kit's animation id, which is a comparison and never a play** — `PlaySpellVisualKit`'s
-/// 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
-/// stage-2 leg, which compares the unit's currently-armed id (`0x5fdb50` — upper-body key bone
-/// preferred, bone 0 as the fallback) against `kit.AnimID` and either does nothing (`je 0x60f3ca`,
-/// already playing it) or runs `0x5fd9e0(unit, -1)` — a **base-animation recompute** — before
-/// leaving the block for good. Both `SpellVisual` field-4 consumers hardcode stage 2 (the aura
-/// watcher `0x5ff4c6` and the impact hand-off `0x61dced`), so no path in the image ever plays a
-/// state kit's anim.
-///
-/// 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 (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
-/// id and a non-zero flags nibble, which our per-unit armed-id diff reproduces by construction.
+/// A state kit's `AnimID`, compared and never played: both field-4 callers (`0x5ff4c6`,
+/// `0x61dced`) pass stage 2, which `0x60edf0` diverts at `0x60f387`, and a mismatch with the armed
+/// id (`0x5fdb50`) recomputes the base (`0x5fd9e0`). So it only cuts: Charge's
+/// Knockdown (121) falls to Stand, since `0x5fd8b0` never yields its Stun (14). An in-place aura
+/// refresh emits nothing (`0x604d00`).
 #[derive(Message, Clone, Copy)]
 pub(crate) struct BaseAnimRecompute {
     pub(crate) entity: Entity,
-    /// The state kit's `AnimID` — the right-hand side of `0x60f390`'s compare, never played.
+    /// The right side of `0x60f390`'s compare.
     pub(crate) anim_id: u16,
 }
 
-/// 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`] — `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).
-/// A unit with no mount child (a race with dismount) drops silently — nothing to rear.
+/// Rears a rider's mount: MountSpecial (94) on the mount child while the rider holds Mount (91)
+/// (`0x608d50`); dropped when there is no mount child.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct MountFlourish {
     pub(crate) unit: Entity,
 }
 
-/// [`MountFlourish`] → [`EmoteAnim`]: hop unit → its mount child and fire the one-shot there.
-/// The mount child runs the untouched creature machinery (it is not itself "mounted"), so the
-/// general one-shot player takes it from here — full-body 94 over the mount's gait, returning
-/// to it when done.
+/// `MountFlourish` to an `EmoteAnim` on the unit's mount child.
 fn flourish_to_anim(
     mut msgs: MessageReader<MountFlourish>,
     mut out: MessageWriter<EmoteAnim>,
@@ -726,7 +436,7 @@ fn flourish_to_anim(
     for m in msgs.read() {
         let Ok(child) = mounts.get(m.unit) else {
             debug!("flourish: {:?} has no mount child — dropped", m.unit);
-            continue; // dismounted before the flourish landed — nothing to rear
+            continue; // dismounted before the flourish landed
         };
         debug!(
             "flourish: MountSpecial(94) one-shot on {:?} (mount of {:?})",
@@ -740,86 +450,56 @@ fn flourish_to_anim(
     }
 }
 
-/// A **spell-side wound flinch** on `entity` — the client's `0x60ea70(unit, severity = 0)`
-/// reached from three spell paths (decision 2058): the kit player's own branch (`0x60edf0` @
-/// `0x60f3ad`: a kit anim in `[8,10]` goes here instead of `PlayAnimation`), the instant-hit
-/// impact loop (`0x6e8bf0` @ `0x6e8c89` — after the impact kit, iff the spell targets enemies,
-/// [`benilla_formats::SpellDisplay::is_harmful`]), and the missile impact hand-off (`0x61dc50` @
-/// `0x61dc74` — before the impact kit, every living target). All three pass **severity 0**, so
-/// the id is never the kit's own column: the trigger picks CombatWound(9) / StandWound(8) by the
-/// victim's engagement exactly like a non-crit melee hit ([`select::wound_anim`]) and lays it
-/// into the SECONDARY-blend slot — a decaying overlay that never interrupts what plays
-/// underneath (decision 0111). Never the [`EmoteAnim`] one-shot route: that replaces the base
-/// track, the exact routing 0111 falsified. Written by [`spell_visual::route_cast_visuals`];
-/// consumed by [`driver::drive_animations`] into the same per-frame wound slot as a melee hit.
+/// A spell-side wound flinch, the reference's `0x60ea70(unit, 0)` from the kit player
+/// (`0x60f3ad`), the instant-hit loop (`0x6e8c89`, harmful only) and the missile impact
+/// (`0x61dc74`): CombatWound (9) or StandWound (8) by engagement, in the secondary-blend slot.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct WoundAnim {
     pub(crate) entity: Entity,
 }
 
-/// The target lists off one `SMSG_SPELL_GO` (decision 0099 phase 4) — the payload [`CastEvent`]'s
-/// `Copy` shape can't carry. Written by the net bridge alongside the GO's [`CastEvent`]; consumed
-/// by [`spell_visual::route_cast_visuals`], which resolves `Spell.dbc` Speed and either plays the
-/// impacts inline (speed 0) or launches missiles ([`spell_visual::MissileSpawn`]) — the client's
-/// two GO branches (`0x6e8bf0` instant vs `0x6e8a50 → 0x60a3d0` projectile).
+/// One `SMSG_SPELL_GO`'s target lists: impacts inline for `Spell.dbc` Speed 0, else missiles (the
+/// reference's `0x6e8bf0` and `0x6e8a50`).
 #[derive(Message, Clone)]
 pub(crate) struct SpellGoTargets {
     pub(crate) caster: Entity,
     pub(crate) spell_id: u32,
-    /// Units the spell landed on — each gets the impact hand-off (inline or on missile arrival).
+    /// Units the spell landed on; each gets the impact hand-off.
     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).
-    /// No impact kit plays. The deflect
-    /// *flight* visual (the projectile glancing off) stays a named approximation — ours ends
-    /// the flight at the target.
+    /// Missed units with `SpellMissInfo`: the arrival plays Dodge (30) or ShieldBlock (24), never
+    /// Parry (`0x61ceb0`), and no impact kit; the deflect glance-off flight is not built.
     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 still an open question (the persistent area
-    /// effect anchors to the DynamicObject create, not to this packet).
+    /// A dest-targeted cast's ground point, in bevy coords; not read, the reference's
+    /// dest-anchored launch visual is untraced.
     pub(crate) dest: Option<Vec3>,
-    /// The GO's ammo block (`castFlags & 0x20`, a ranged shot): the `ItemDisplayInfo` id of the
-    /// caster's ammo/thrown — the missile's model when the spell's visual chain has none (the
-    /// client's `0x479f40` fallback, decision 0099 phase 5).
+    /// The GO's ammo block (`castFlags & 0x20`): the ammo's `ItemDisplayInfo` id, the missile model
+    /// when the visual chain has none (`0x479f40`).
     pub(crate) ammo_display_id: Option<u32>,
-    /// [`PlaySeq`] stamp — same packet as the GO's [`CastEvent`], same stamp: the inline
-    /// impacts play from the one handler call.
+    /// `PlaySeq` stamp, the GO's `CastEvent`'s.
     pub(crate) seq: u64,
 }
 
-/// The sheath **policy layer**'s types + ceremony mechanics (decision 0080) — the one-setter
-/// request, the ceremony overlays, the `AnimationData.dbc` policy table. The driver below
-/// executes them, so every sheath transition has exactly one author.
+/// The sheath policy: requests, ceremony overlays, the `AnimationData.dbc` table.
 mod sheath;
 use sheath::{load_anim_data, SheathSwap};
 pub(crate) use sheath::{
     toggle_sheath_next, AnimData, SheathRequest, SheathSwapMessage, VisualSheath,
 };
 
-/// The `SMSG_EMOTE` → [`EmoteAnim`] consumer (Part 1 of the emote-animation wiring) — kept
-/// alongside `sheath` as its own small concern.
+/// The `SMSG_EMOTE` to `EmoteAnim` consumer.
 mod emote_anim;
 
-/// The client-local gesture producers (decision 1469): the chat talk/question/exclamation/shout/
-/// laugh, and the NPC-interact talk. The reference's `0x60bb30`, which shares the one-shot player
-/// with `SMSG_EMOTE`.
+/// The client-local gestures (chat, NPC interact), the reference's `0x60bb30`.
 mod gesture;
 use emote_anim::emote_to_anim;
 pub(crate) use gesture::{select_gesture, Gesture, GestureQueue};
 
-/// The Bevy driver systems that execute the state machine [`select`] picks (decision 0049 + 0073,
-/// decision 0087's one-shot routing, decision 0080's sheath execution) — kept in its own file as
-/// it carries the bulk of the per-frame system logic, separate from this module face and from the
-/// pure selector logic in [`select`].
+/// The Bevy systems that execute the state machine `select` picks.
 mod driver;
 pub(crate) use driver::oneshot_is_live;
 use driver::{drive_animations, drive_hand_grip};
 
-/// The model event-keyframe scanner (decision 0070 slice 3) — kept in its own file as its own
-/// small concern, separate from the driver ([`driver`]) that advances the clips it scans.
+/// The model event-keyframe scanner.
 mod events;
 use events::fire_anim_events;
 pub(crate) use events::{
@@ -827,7 +507,7 @@ pub(crate) use events::{
     EventFrame, TrackMemory,
 };
 
-/// The `$BTH` breath puffs — a unit's visible cold vapour in a snow zone (B233, decision 1149).
+/// The `$BTH` breath puffs in a snow zone.
 mod breath;
 use breath::{classify_breath, fire_breath};
 
@@ -835,10 +515,7 @@ mod impact;
 use impact::route_swing_impacts;
 pub(crate) use impact::{DefenseAnim, PendingImpacts, SwingFlush, SwingImpact, SwingSlowdown};
 
-/// The spell-visual data plane + the cast-edge router (decision 0099 phase 2 / 0107):
-/// `SpellVisual.dbc` × `SpellVisualKit.dbc` loaded alongside [`AnimData`], and
-/// [`spell_visual::route_cast_visuals`] resolving wire [`CastEvent`]s into [`CastHold`]s, release
-/// one-shots ([`EmoteAnim`]) and kit sounds ([`spell_visual::SpellKitSound`]).
+/// The melee blood spurt.
 mod blood;
 mod env_damage;
 pub(crate) mod net;
@@ -850,8 +527,7 @@ use spell_visual::{
     arm_aura_state_fx, arm_level_up_fx, arm_loot_fx, arm_morph_latch, arm_mount_poof_fx,
     load_spell_visuals, replay_morph_kit, route_cast_visuals, MorphLatch,
 };
-// The aura-slot watcher is the shared trigger for BOTH halves of a state kit, so the CharProc half's
-// own tests (`crate::aura_visual`) drive it directly rather than re-deriving the slot diff.
+// `crate::aura_visual`'s tests drive the aura-slot watcher directly.
 #[cfg(test)]
 pub(crate) use spell_visual::arm_aura_state_fx as arm_aura_state_fx_for_test;
 pub(crate) use spell_visual::{
@@ -859,153 +535,71 @@ pub(crate) use spell_visual::{
     SpellKitShake, SpellKitSound, SpellVisuals,
 };
 
-/// The per-unit animation state machine.
-///
-/// `Transform` is required, not optional: the driver reads the entity's render scale as the
-/// locomotion rate divisor (decision 0903), so a driver on a transform-less entity would silently
-/// stop being driven at all. Every real unit is spawned with one — the requirement is here so a
-/// hand-assembled entity (a test world, a future harness) can't quietly miss it.
+/// The per-unit animation state machine; `Transform` is required, its scale divides the rate.
 #[derive(Component)]
 #[require(Transform)]
 pub(crate) struct AnimDriver {
     mode: Mode,
-    /// The gait id currently targeted while in [`Mode::Gait`] (so we cross-fade only on a change). `None`
-    /// forces a fresh selection (first eval, or after a Special state exits).
+    /// The targeted gait id, to cross-fade only on a change; `None` forces a fresh pick.
     gait: Option<u16>,
-    /// The movement flags the **base slot** was last armed for — the reference has no per-one-shot
-    /// latch, so "the movement state changed" means *since the base last took a request*, never
-    /// "since this one-shot started" (decision 0894). The distinction is invisible until a one-shot
-    /// and a movement change land on the SAME frame: Ice Block's root wipes the direction bits in
-    /// the very frame the cast one-shot arrives, so an arm-time comparison sees no edge at all and
-    /// the cast keeps bone 0 — where the reference's next base request overwrites it and leaves the
-    /// character neutral.
+    /// The movement flags the base was last armed for: the reference has no per-one-shot latch,
+    /// so a root landing with a cast one-shot (Ice Block) still lets the base overwrite bone 0.
     gait_flags: u32,
-    /// The **base-animation lock** ([`driver::play::BaseAnimLock`]) — the reference's
-    /// `[unit+0xd58] & 0xc0000`. While a `Knockdown`/`LiftOff`/`Land` holds it, every base request
-    /// is refused outright, which is how a stunned victim's knockdown survives the root's own
-    /// `Stand` recompute (decision 2096).
+    /// The reference's `[unit+0xd58] & 0xc0000`: while Knockdown, LiftOff or Land holds it, base
+    /// requests are refused, so a stun's knockdown survives the root's Stand recompute.
     base_lock: driver::play::BaseAnimLock,
-    /// The unit's **client-side sheath state** — the mirror of the client's committed CUR cache
-    /// (`[unit+0xd40]`, decision 0080): what the weapon placement renders (absent a
-    /// [`VisualSheath`] ceremony pin) and what the setter/reconcile test against. Seeded from
-    /// the descriptor byte at first sight; re-adopted whenever the server byte *changes* (the
-    /// `0x604c70` field-apply); overwritten by requests ([`SheathRequest`]) and the
-    /// per-animation reconcile. `None` = not yet seen (arms silently).
+    /// The committed sheath state, the reference's `[unit+0xd40]`: seeded from the descriptor,
+    /// re-adopted when it changes (`0x604c70`), overwritten by requests and the reconcile.
     sheath_cur: Option<u8>,
-    /// The `UNIT_FIELD_BYTES_2` sheath byte last seen, to detect inbound field *changes* (our
-    /// own `CMSG_SETSHEATHED` echo arrives already-committed and adopts as a no-op).
+    /// The last descriptor sheath byte, to detect changes.
     sheath_byte: Option<u8>,
-    /// The pending mid-animation weapon swap, while a draw/stow one-shot is in flight.
+    /// The pending mid-animation weapon swap while a draw/stow one-shot plays.
     sheath_swap: Option<SheathSwap>,
-    /// **Did this unit start an animation THIS frame** — of any kind: a one-shot, a masked
-    /// overlay, a cast/channel hold, or the mode machine's own base/gait play. Rewritten every
-    /// pass by [`driver::drive_animations`], so a reader one system later sees exactly the
-    /// frame's edge.
-    ///
-    /// Its one consumer is the weapon-trail latch ([`crate::weapon_trail`], decision 2076). The
-    /// reference consumes `unit+0xd1c`/`+0xd20` inside `CGUnit::PlayAnimation 0x5fe2f0` itself
-    /// (`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.
-    /// 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.
+    /// Whether any animation started this frame, for the weapon-trail latch: the reference reads
+    /// `unit+0xd1c` in `PlayAnimation` (`0x5fe48e`), its single entry point, locomotion
+    /// included, so starting to run starts Charge's trail.
     started_anim: bool,
-    /// A **masked upper-body one-shot** in flight (decision 0087): a swing/emote the live-state route
-    /// sent to the SpineLow overlay (moving / seated / airborne-in-combat), playing *beside* [`Mode`]
-    /// while the base track keeps driving the legs (run / sit / jump-arc). `None` = no overlay; a
-    /// finished overlay **fades** the subtree back to the base ([`Self::overlay_fade`]) rather than
-    /// dropping it. The full-body route never uses this — it replaces the base via [`Mode::Swing`]
-    /// — until a locomotion request **transplants** that clip up here (decision 0878).
+    /// A masked upper-body one-shot on the SpineLow overlay while the base drives the legs; a
+    /// full-body one lives in `Mode::Swing` until locomotion transplants it here.
     overlay: Option<Overlay>,
-    /// The key-bone slot's **cross-fade in flight** (decision 0878) — the client's per-bone
-    /// SECONDARY as an upper-body arm or release seeds it. Two producers, one curve
-    /// ([`select::blend_lambda`], λ decaying 1 → 0): the **fade-to-rest** that releases a finished
-    /// one-shot over a fixed 150 ms (`0x5fc920` → op4 `param_3 = −1`, `0x7123af`), and a **blended
-    /// re-arm** cross-fading a new masked clip in over the incoming clip's own blendTime
-    /// (`0x7125f2`). A **transplant** arm carries `blendFlag = 0` and seeds nothing — it resumes
-    /// the clip at its live frame with no fade at all.
+    /// The key-bone cross-fade, the reference's per-bone secondary (λ 1 to 0): 150 ms to rest
+    /// after a one-shot (`0x5fc920`, `0x7123af`) or a re-arm over the new clip's blendTime
+    /// (`0x7125f2`); a transplant (`blendFlag = 0`) seeds none.
     overlay_fade: Option<OverlayFade>,
-    /// The victim **wound-flinch** in flight (decision 0111) — the client's per-bone **SECONDARY
-    /// blend slot**: a decaying cross-fade overlay (`λ` smoothstep `0.75 → 0` over the wound
-    /// clip's own span) layered over whatever else plays, then self-releasing. Deliberately a
-    /// separate slot from [`Self::overlay`] — in the client they are two independent per-bone
-    /// slots (primary arm vs secondary blend), so a masked swing and a wound decay **coexist**;
-    /// folding the wound into the one-shot slot is exactly the falsified 0107 routing.
+    /// The wound flinch, the reference's secondary blend slot (λ 0.75 to 0 over the clip), apart
+    /// from `overlay` so a masked swing and a wound coexist.
     wound: Option<Wound>,
-    /// Whether the current airborne arc launched **upward** — a jump (the JumpStart/Jump bracket)
-    /// vs a step-off fall (the gait freeze). Decided from `vertical_speed` on the arc's first
-    /// airborne frame — the MSG_MOVE_JUMP-vs-StartFalling distinction the real client carries as
-    /// an event, read off the launch velocity in our flag-collapsed machine. Stale on the ground.
+    /// Whether this arc launched upward (a jump) or is a step-off fall, from vertical speed on
+    /// its first airborne frame; the reference carries it as `MSG_MOVE_JUMP`.
     jump_arc: bool,
-    /// Vertical speed as of last frame — the **launch** detector behind [`Self::jump_arc`]. A jump
-    /// out of a one-frame micro-detachment never toggles the FALLING bit (land and relaunch inside
-    /// one frame), so the bit's edge cannot be the only place the arc is classified; a rise past
-    /// `JUMP_ARC_MIN_UP` from below is the launch itself, and nothing but a jump produces one.
+    /// Last frame's vertical speed: a jump out of a one-frame detachment never toggles FALLING,
+    /// so a rise past `JUMP_ARC_MIN_UP` from below also classifies the arc.
     last_vertical_speed: f32,
-    /// FALLING was set last frame — marks the arc edges: takeoff (decide [`Self::jump_arc`]) and
-    /// the landing of a bracket-less step-off fall (which must still run the `0x602c60` land pick
-    /// even though no Special drove the arc).
+    /// FALLING last frame: marks takeoff and a step-off fall's landing (`0x602c60` land pick).
     was_falling: bool,
-    /// 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).
+    /// The reference's `CGUnit+0xd60`: a combat clip requested over another doubles the playing
+    /// clip's rate and parks here until no one-shot is live; any normal arm clears it (`0x5fe48e`).
     deferred: Option<u16>,
-    /// 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 —
-    /// completes `R` passes: the fresh weighted pick that alternates a gryphon's flap/glide and
-    /// walks a multi-part dance. `None` = the main arm is a one-shot (its budget is a `Count`
-    /// repeat) or a deliberate freeze (ranged Load / Loot).
+    /// The looping arm's node and rolled budget `R` (`block+0xbc`, `0x7126d8`): the watchdog
+    /// (`0x719370`) re-picks after `R` passes. `None` for a one-shot or a freeze.
     loop_window: Option<(bevy::animation::graph::AnimationNodeIndex, u32)>,
-    /// The playback rate last written to the base slot — `speed / (moveSpeed · |modelScale|)`
-    /// ([`select::playback_rate`], decision 0903); `1.0` for anything that is not a rate-scaled
-    /// locomotion clip. Purely an **instrument**: the hover inspector's anim line reads it, so
-    /// "this creature's walk looks too fast" is answerable by hovering the creature instead of by
-    /// working the divisor out by hand. Recorded rather than re-derived, so the card can never
-    /// disagree with what is actually playing.
+    /// The rate last written to the base slot, recorded for the hover inspector.
     gait_rate: f32,
-    /// `UNIT_FIELD_MOUNTDISPLAYID` as of the last pass — the driver's **mount-transition edge**
-    /// detector, the local twin of the client's own UpdateField change-watcher (`0x604329`:
-    /// TYPEID Unit, descriptor offset `0x1fc`, width 4, thunk `0x604570` → `0x5ffa50`). Any
-    /// change is an edge — 0→N (mount), N→N′ (swap) and N→0 (dismount) alike — because the
-    /// reference's handler is one watcher whose two legs BOTH arm bone 0 of the body: the build
-    /// `0x607b44` op4(bone 0, **91 `Mount`**, cross-fade, PRIMARY), the teardown `0x607ce0` op4
-    /// seq **0 `Stand`**. The arm is a plain last-writer-wins play, so it *displaces a full-body
-    /// one-shot the transition catches in flight* — which our gait-slot mount pin alone never did
-    /// (decision 0927).
+    /// The last mount display id: any change arms bone 0, like the reference's field watcher
+    /// (`0x604329`): Mount 91 (`0x607b44`) or Stand 0 (`0x607ce0`), displacing a one-shot.
     mount_display: u32,
-    /// The Special wanted LAST frame — the driver's Special **edge** detector (decision 0864).
-    /// An edge is a play in the client (the jump/pose entry, the FALLINGFAR latch's Fall, the
-    /// land pick), so it clears the deferred-combat cache like any normal arm (`0x5fe48e`);
-    /// the *level* must not (mid-air the airborne-freeze issues no plays, so a fast-path park
-    /// survives to its clip's end).
+    /// The Special wanted last frame. Its edge is a play in the reference and clears the deferred
+    /// cache (`0x5fe48e`); its level must not, so a fast-path park survives mid-air.
     last_special: Option<Special>,
-    /// The **airborne snapshot** node whose clock [`driver::play::leave_special`] stopped
-    /// (decision 0503, the swim hop's too-short kick — kept as a symptom fix whose mechanism is
-    /// open, because the "blends from a frozen pose" law it was justified by is refuted: the
-    /// client's blend source keeps running, decision **1566**. Scoped to the airborne cut and
-    /// **not** to be generalised). The per-frame rate write
-    /// ([`driver::play::sync_base_rate`](driver::play)) must not restart it, so it is named here
-    /// rather than inferred from a zero speed — a rate-scaled clip legitimately reads 0 when the
-    /// body is standing still, and skipping *that* would strand it frozen forever. Self-clearing:
-    /// the moment anything else is armed the node stops being the main animation and the sync
-    /// drops the name (decision 0906).
+    /// The airborne snapshot node `leave_special` stopped, named so the rate sync does not
+    /// restart it (a standing locomotion clip also reads rate 0). A symptom fix for the swim hop's
+    /// short kick, its mechanism open: the reference's blend source keeps running, so it stays
+    /// scoped to the airborne cut.
     frozen: Option<bevy::animation::graph::AnimationNodeIndex>,
 }
 
 impl AnimDriver {
-    /// The `AnimationData` ids currently driving this unit — `(base, masked overlay)` — the
-    /// inspector card's anim readout. The base is whatever occupies the full-body slot (gait /
-    /// special / landing / swing), as the *requested* ids before any missing-clip substitution
-    /// (the layer the selectors chose — also what the reconcile tests, decision 0125); the
-    /// overlay is a masked upper-body one-shot playing beside it, if any. A `None` base = no
-    /// gait selected yet (first frame).
+    /// The requested `(base, masked overlay)` ids, for the inspector.
     pub(crate) fn playing(&self) -> (Option<u16>, Option<u16>) {
         let base = match self.mode {
             Mode::Gait => self.gait,
@@ -1018,19 +612,14 @@ impl AnimDriver {
         (base, self.overlay.map(|o| o.id))
     }
 
-    /// The playback rate the base slot is running at ([`Self::gait_rate`]) — the inspector card's
-    /// `rate` readout. `1.0` for every clip outside the locomotion whitelist.
+    /// The base slot's playback rate, for the inspector.
     pub(crate) fn rate(&self) -> f32 {
         self.gait_rate
     }
 }
 
-/// A masked upper-body play over the base ([`AnimDriver::overlay`]): the graph node it drives
-/// ([`AnimClip::upper_node`]) and the requested `AnimationData.dbc` id (for the event scan +
-/// the sheath reconcile — both must see this play, decision 0087 (d)). `looping` marks the cast
-/// hold's sustained variant (decision 0107): a one-shot auto-releases when its clip finishes; a
-/// looping hold never finishes and is released only by [`driver::drive_animations`]'s hold logic
-/// (the [`CastHold`] gone, or the unit stopping — the hold then moves to the gait slot).
+/// A masked upper-body play: its node and requested id; `looping` marks a cast hold, released
+/// only by the driver's hold logic.
 #[derive(Clone, Copy)]
 struct Overlay {
     node: bevy::animation::graph::AnimationNodeIndex,
@@ -1038,33 +627,24 @@ struct Overlay {
     looping: bool,
 }
 
-/// 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.
+/// A key-bone cross-fade: `out` holds the outgoing pose (`0x7123af`), `None` over the base;
+/// `left`/`total` span 150 ms or the incoming clip's blendTime.
 #[derive(Clone, Copy)]
 struct OverlayFade {
     out: Option<bevy::animation::graph::AnimationNodeIndex>,
-    /// Seconds still to run — λ = [`select::blend_lambda`]`(left / total)`, decaying 1 → 0.
+    /// Seconds left; λ = `select::blend_lambda(left / total)`.
     left: f32,
     total: f32,
 }
 
-/// A wound-flinch decay in flight ([`AnimDriver::wound`], decision 0111): the graph node the
-/// blend drives (the clip's masked [`AnimClip::upper_node`], or its full-body node when the
-/// bone-selection forces bone 0 — [`select::wound_full_body`]) and the decay window's inputs.
-/// The client seeds `end = clock + span, rate = 1/span, λ₀ = 0.75` (op4 `linkFlag=0`,
-/// `0x712647-0x712682`); the driver's per-frame upkeep replays that decay off the clip's own
-/// playback clock and stops the node when it expires — the kernel's self-release (`0x7147b9`).
+/// A wound-flinch decay: the reference seeds `λ₀ = 0.75`, `rate = 1/span` (`0x712647`) and
+/// self-releases (`0x7147b9`).
 #[derive(Clone, Copy)]
 struct Wound {
     node: bevy::animation::graph::AnimationNodeIndex,
-    /// The wound clip's full length (seconds) — the decay denominator (the client's `1/span`).
+    /// The wound clip's length in seconds.
     span: f32,
-    /// Masked to the upper-body subtree — where the base *and* a live one-shot overlay both
-    /// blend, so the λ-anchoring weight must count them ([`select::wound_weight`]'s `others`).
+    /// Masked to the upper body, where the base and a one-shot overlay also blend.
     masked: bool,
 }
 
@@ -1096,10 +676,7 @@ impl Default for AnimDriver {
 }
 
 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 (`0x7089c0`).
+    /// The requested id playing now; the mouse pick's bounds follow it (`0x7089c0`).
     pub(crate) fn active_anim(&self) -> Option<u16> {
         match self.mode {
             Mode::Gait => self.gait,
@@ -1111,16 +688,8 @@ impl AnimDriver {
         }
     }
 
-    /// The **resolved** id of the clip actually driving playback right now (decision 0082):
-    /// [`Self::active_anim`] (the selector's *requested* semantic id) run through the model's own
-    /// fallback resolution. This is what the real client's per-animation sheath reconcile tests
-    /// (`0x5fdb50` reads the record of the sequence **actually playing**, not the semantic pick that
-    /// was asked for) and what the event-fire path needs (a clip crossed via resolution is the one
-    /// whose timeline is actually advancing). [`Self::active_anim`] itself stays the raw requested id
-    /// — the state machine's `Mode`/`gait` identity comparisons key on the *selector's* choice, which
-    /// resolution must not perturb (two candidates that happen to resolve to the same baked substitute
-    /// are still a different selection). `catalog` absent (a brief window before `AnimationData.dbc`
-    /// loads) degrades to identity, matching [`find_resolved`]'s own degrade.
+    /// `active_anim` through the model's fallback, the sequence actually playing (what the
+    /// reconcile reads, `0x5fdb50`); the mode machine keeps comparing the requested id.
     pub(crate) fn resolved_anim(
         &self,
         anims: &ModelAnimations,
@@ -1129,33 +698,29 @@ impl AnimDriver {
         self.active_anim().map(|id| resolved_id(anims, id, catalog))
     }
 
-    /// The unit's client-side sheath state (0 stowed · 1 melee · 2 ranged) — the committed CUR
-    /// cache the placement renders and the Z toggle flips. `None` until first driven.
+    /// The client-side sheath state (0 stowed, 1 melee, 2 ranged), `None` until driven.
     pub(crate) fn sheath_state(&self) -> Option<u8> {
         self.sheath_cur
     }
 
-    /// Did this unit start an animation this frame — see [`Self::started_anim`].
+    /// Whether this unit started an animation this frame.
     pub(crate) fn started_anim(&self) -> bool {
         self.started_anim
     }
 
-    /// Stand in for the driver's own write, so a consumer's test can raise the edge without
-    /// standing up the whole animation pass to produce it.
+    /// Stands in for the driver's write in a consumer's test.
     #[cfg(test)]
     pub(crate) fn set_started_anim(&mut self, played: bool) {
         self.started_anim = played;
     }
 
-    /// Whether a draw/stow ceremony is in flight — the manual toggle's mid-ceremony debounce
-    /// (guards 11–12 of the client's `ToggleSheath` chain, decision 0080d).
+    /// A draw/stow ceremony is in flight: the toggle's debounce (`ToggleSheath` guards 11, 12).
     pub(crate) fn sheath_ceremony_active(&self) -> bool {
         self.sheath_swap.is_some()
     }
 }
 
-/// Drives unit animation from movement state. Runs after [`WorldStage::Net`] (where the net bridge updates
-/// splines and the controller writes our avatar's state), so what it reads is the current frame's.
+/// Drives unit animation after `WorldStage::Net`, so it reads the current frame's movement.
 pub(crate) struct CreatureAnimPlugin;
 
 impl Plugin for CreatureAnimPlugin {
@@ -1164,9 +729,7 @@ impl Plugin for CreatureAnimPlugin {
         twist::plugin(app);
         lod::plugin(app);
         breath::register(app);
-        // The breath classifier is a per-unit environment resolve, not an animation step: it runs
-        // off the area authority, at its own 10 s cadence, and only publishes the component
-        // `fire_breath` reads inside the chain below.
+        // The breath classifier runs at its own 10 s cadence, outside the chain.
         app.add_systems(
             Update,
             classify_breath.after(benilla_world::terrain_stream::AreaAuthoritySet),
@@ -1192,14 +755,12 @@ impl Plugin for CreatureAnimPlugin {
             .add_message::<SpellKitShake>()
             .add_message::<SpellKitFx>()
             .add_message::<MissileSpawn>()
-            // The kit's beam edge (0955) — `crate::entities` owns what it becomes.
             .add_message::<ChainProcPlay>()
             .add_message::<KitPush>()
-            // The aura CharProc edges the slot watcher emits alongside its effect-model ones —
-            // drained by `crate::aura_visual`, which owns the body's alpha/tint for an aura's life.
+            // The aura CharProc edges, drained by `crate::aura_visual`.
             .add_message::<crate::aura_visual::AuraProc>()
             .add_message::<HardLanding>()
-            // The pending-morph latch — the reference's per-unit `[+0xd54]` SpellRec slot.
+            // The pending-morph latch, the reference's per-unit `[+0xd54]`.
             .init_resource::<MorphLatch>()
             .add_systems(
                 Startup,
@@ -1215,92 +776,51 @@ impl Plugin for CreatureAnimPlugin {
                 Update,
                 (
                     route_cast_visuals,
-                    // The lootable-corpse sparkle's edge watcher — a SpellKitFx writer like the
-                    // router above, consumed by the same entity-visuals chain this set precedes.
                     arm_loot_fx,
-                    // Its level-edge sibling: the ding (decision 0305) — same shape, same home.
                     arm_level_up_fx,
-                    // …and its mount-edge sibling: the poof (decision 0927). Same hardcoded-effect
-                    // spawn shape, one field over.
                     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 (`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
-                    // latch was armed by the same wire burst.
+                    // `0x5ff0c0` arms, `0x60abe0` replays on a display swap; arm first, since the
+                    // swap crosses from last frame's teardown, armed by the same wire burst.
                     (arm_morph_latch, replay_morph_kit).chain(),
                     blood_spurts,
-                    // The landing predictor's dust leg (the vocal leg lives in `sound`).
                     hard_landing_dust,
                     emote_to_anim,
-                    // The client-local gestures (decision 1469) — the chat talk/shout/laugh and
-                    // the NPC-interact talk. The client's second (and only other) producer of a
-                    // one-shot emote; same place in the order as the wire one, for the same reason.
                     gesture::drive_gestures,
-                    // The flourish hop (unit → mount child) — before the driver so the
-                    // one-shot lands the same frame the packet (or space press) arrived.
+                    // Before the driver, so the flourish lands the frame it arrived.
                     flourish_to_anim,
                     drive_animations,
-                    // The weapon-trail latch (decision 2076) — immediately after the driver,
-                    // because the edge it consumes is `AnimDriver::played_anim`, which the driver
-                    // rewrites every pass. The reference reads the latch *inside*
-                    // `PlayAnimation 0x5fe2f0` itself; one system later is as close as a
-                    // batched driver gets, and it is still the same frame.
+                    // Right after the driver, which rewrites `AnimDriver::started_anim` each pass.
                     crate::weapon_trail::fire_weapon_trails,
                     drive_hand_grip,
                     fire_anim_events,
-                    // After the event scan: consume this frame's impact tags; the SwingImpact
-                    // consumers (blood, flinch, floating text) read it next frame — noise against
-                    // the ~300–600 ms deferral itself.
                     route_swing_impacts,
-                    // The `$BWP`/`$BWR` nock latch, same-frame off the same scan — before the
-                    // entity-visuals chain so the arrow appears/vanishes the frame the keyframe
-                    // lands, not one behind.
+                    // Before the entity visuals, so the arrow changes on the keyframe's frame.
                     drive_nock_latch,
-                    // …and, off the same two keys, the RANGED PROP's own clip (decision 2281):
-                    // the bow's limbs bend on `$BWP`, and on `$BWR` a gun fires the muzzle blast
-                    // its BowRelease(161) sequence carries. Beside the latch because the reference
-                    // arms both from one handler each, and ahead of the entity-visuals chain so the
-                    // prop's pose is this frame's before the rider lane reads it.
+                    // The ranged prop's clip off the same keys: the bow bends on `$BWP`, a gun's
+                    // BowRelease (161) blast plays on `$BWR`.
                     crate::ranged_flex::flex_ranged_props
-                        // The per-sequence material samplers (`SeqHosts`) ask an anim host which
-                        // slot it is playing; a prop that armed 161 this frame must be answering
-                        // for 161, not for last frame's Stand. The chain's own `.before(
-                        // EntityVisualsSet)` does not reach them — they hang off `ModelVisSet`.
+                        // The material samplers must see the clip armed this frame.
                         .before(benilla_world::model_render::ModelVisSet),
-                    // …and the un-nock's reset (`0x60f59d`), which the reference reaches from the
-                    // SAME `$BWR` it just armed on. It must run AFTER the arm, or its skip-while-
-                    // releasing guard has nothing to read and a gun's blast is cancelled on the
-                    // frame it starts — the chain gives it that order by construction.
+                    // The un-nock reset (`0x60f59d`), off the same `$BWR`: after the arm, or its
+                    // skip-while-releasing guard cancels a gun's blast on its first frame.
                     crate::ranged_flex::reset_ranged_props_on_unnock
-                        // Same edge as the arm above, and for the same reason: this writes the
-                        // prop's player too, and the per-sequence material samplers must answer
-                        // for the clip it leaves armed.
                         .before(benilla_world::model_render::ModelVisSet),
-                    // …and the `$BTH` puff off the same scan: another SpellKitFx writer, so it
-                    // belongs ahead of the entity-visuals chain like its `arm_*_fx` siblings.
                     fire_breath,
                 )
                     .chain()
                     .after(WorldStage::Net)
-                    // After predicate B's recompute (decision 1477): the loot leg's self trigger
-                    // is that boolean, and the reference has no gap between arming the latch and
-                    // posing — its chest arm force-plays Loot 50 in the same handler. Without
-                    // this edge the kneel lands a frame late at every loot window.
+                    // Same frame as the loot kneel: the reference force-plays Loot 50 in the
+                    // handler that arms the latch.
                     .after(crate::ui_loot::resolve_loot_kneel)
                     // After Input so a sheath request (the Z toggle) executes the same frame.
                     .after(WorldStage::Input)
-                    // Before the entity-visuals chain: [`VisualSheath`] writes must be applied
-                    // before `resolve_equipment` reads them, or a sheath transition double-swaps
-                    // the weapon placement for a frame (the flash).
+                    // `VisualSheath` must land before `resolve_equipment` reads it, or a sheath
+                    // change double-swaps the weapon placement for a frame.
                     .before(crate::entities::EntityVisualsSet),
             )
-            // The freeze (CharProc 11, decision 0889): **after the driver**, so this frame's arms
-            // are already in when the clocks are held — the Ice Block observable is precisely that
-            // the cast one-shot gets armed and then never advances a frame. After the drain too, so
-            // the node it reads is this frame's.
+            // The CharProc 11 freeze, after the driver so this frame's arms are in when it holds
+            // the clocks: Ice Block's cast one-shot is armed, then never advances.
             .add_systems(
                 Update,
                 crate::aura_visual::apply_aura_anim_rate
@@ -1310,18 +830,12 @@ impl Plugin for CreatureAnimPlugin {
     }
 }
 
-/// 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, ..)`
-/// elsewhere in this module).
+/// The id this model plays for `id` (`0x711bf0`); identity until `AnimationData.dbc` loads.
 fn resolved_id(anims: &ModelAnimations, id: u16, catalog: Option<&AnimDataCatalog>) -> u16 {
     catalog.map_or(id, |cat| anims.resolve(id, cat).id)
 }
 
-/// The clip for a *requested* id, resolved through the model's own baked fallback first (decision
-/// 0082) — so a model lacking `id` exactly still plays its baked substitute (e.g. the chicken's
-/// Attack2H request landing on AttackUnarmed) instead of coming back empty.
+/// The clip for a requested id, through the model's baked fallback.
 fn find_resolved<'a>(
     anims: &'a ModelAnimations,
     id: u16,
@@ -1334,22 +848,14 @@ fn find_resolved<'a>(
 mod attack_stand_tests {
     use super::*;
 
-    /// **`StartAttack` stands a seated player** — `0x5ecc9b`, and unconditionally within this
-    /// function (decision 1768).
-    ///
-    /// `engaged = true` is the case worth pinning. It takes `0x5ecb70`'s skip, which jumps to the
-    /// tail at `0x5ecd78` — **73 bytes past the stand** — so re-issuing an attack you are already
-    /// making still stands you, and no `CMSG_ATTACKSWING` goes out. A stand written only on the
-    /// swing's own leg would miss exactly this case.
-    ///
-    /// This is the behaviour that replaces the turn-driven stand 1766 deleted: what stands a
-    /// seated player on a right-click is the *action* the click dispatches, not the gesture.
+    /// StartAttack stands a seated player (`0x5ecc9b`) even on the already-engaged skip, which
+    /// jumps past the stand to `0x5ecd78` and sends no `CMSG_ATTACKSWING`.
     #[test]
     fn starting_an_attack_stands_you_even_when_the_swing_is_skipped() {
         let mut app = App::new();
         app.add_message::<SheathRequest>()
             .add_message::<crate::player::StandStateRequest>();
-        // A dead-letter net channel: the send is `let _ = …` and no packet is under test here.
+        // A dead-letter net channel: no packet is under test.
         let (tx, _rx) = crossbeam_channel::unbounded();
         app.insert_resource(crate::net::NetCommands(tx));
         app.insert_resource(crate::spell::AutoRepeatActive(None));
@@ -1364,7 +870,7 @@ mod attack_stand_tests {
                 start_attack_local(
                     me,
                     0xdead_beef,
-                    true, // already engaged — the skip leg
+                    true, // already engaged: the skip leg
                     false,
                     &mut auto_repeat,
                     &mut sheath,
@@ -1393,9 +899,7 @@ mod attack_stand_tests {
 mod nock_latch_tests {
     use super::*;
 
-    /// 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.
+    /// The `$BWP`/`$BWR` nock cycle (set `0x624b70`, cleared `0x60016c`).
     #[test]
     fn bwp_latches_and_bwr_clears_the_nock() {
         let mut app = App::new();
@@ -1426,8 +930,6 @@ mod nock_latch_tests {
             !app.world().entity(unit).contains::<NockLatch>(),
             "$BWR clears — the arrow leaves with the shot"
         );
-        // No cached ammo display → the pull nocks nothing (the client's handler gates on the
-        // cached ranged spell).
         let bare = app.world_mut().spawn_empty().id();
         app.world_mut().write_message(AnimSoundEvent {
             entity: bare,
@@ -1448,10 +950,8 @@ mod nock_latch_tests {
 mod disarm_tests {
     use super::*;
 
-    /// **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.
+    /// The ladder hides one weapon, main hand first: a disarmed dual-wielder punches with the
+    /// main hand and still swings its off-hand weapon (`0x5ec240`, `0x605e30`).
     #[test]
     fn disarm_hides_one_weapon_main_hand_first() {
         let worn = Wielded {
@@ -1465,14 +965,12 @@ mod disarm_tests {
             ..worn
         };
 
-        // CONTROL — the weapon tables, untouched while the flag is down.
         assert_eq!(worn.disarmed_hand(), None);
         assert_eq!(select::swing_anim_main(worn.armed_main()), 17); // Attack1H
         assert_eq!(select::swing_anim_off(worn.armed_off()), 88); // AttackOffPierce
         assert_eq!(select::ready_anim(worn.armed_main()), 26); // Ready1H
 
-        // Disarmed, both hands full: the MAIN HAND is the one hidden, and its claim CANCELS the
-        // off-hand probe (`5ec28d je 0x5ec2aa`) — the dagger keeps swinging as a dagger.
+        // The main hand's claim skips the off-hand probe (`0x5ec28d je 0x5ec2aa`).
         assert_eq!(disarmed.disarmed_hand(), Some(0));
         assert_eq!(disarmed.armed_main(), None);
         assert_eq!(disarmed.armed_off(), Some((2, 0xf)), "the off hand is KEPT");
@@ -1480,18 +978,15 @@ mod disarm_tests {
         assert_eq!(select::swing_anim_off(disarmed.armed_off()), 88); // still the dagger
         assert_eq!(select::ready_anim(disarmed.armed_main()), 25); // ReadyUnarmed
 
-        // The RANGED slot has no gate at all: `0x5ec25e` pushes equip index `0x11` and jumps
-        // straight past both probes, so a disarmed hunter still nocks.
+        // The ranged slot has no gate (`0x5ec25e`).
         assert_eq!(disarmed.ranged, Some((2, 0x2)));
         assert_eq!(select::ranged_load_anim(disarmed.ranged), 105); // LoadBow
 
-        // …and the WORN reading is untouched throughout — it is what the paperdoll shows.
         assert_eq!(disarmed.main, worn.main);
     }
 
-    /// The off hand is hidden only when the main hand does **not** claim the disarm — an empty or
-    /// non-weapon main hand. That is the one case that reaches AttackUnarmedOff(117), whose
-    /// `AnimationData.dbc` row (id 117, fallback 87) is a clip distinct from AttackUnarmed(16).
+    /// Only a weaponless main hand passes the disarm to the off hand: AttackUnarmedOff (117,
+    /// `AnimationData.dbc` fallback 87).
     #[test]
     fn an_empty_main_hand_hands_the_disarm_to_the_off_hand() {
         let off_only = Wielded {
@@ -1504,7 +999,6 @@ mod disarm_tests {
         assert_eq!(off_only.armed_off(), None);
         assert_eq!(select::swing_anim_off(off_only.armed_off()), 117);
 
-        // A NON-WEAPON main hand does not claim it either — the test is `ItemClass == 2` only.
         let torch = Wielded {
             main: Some((15, 0)), // class 15 = miscellaneous
             off: Some((2, 0xf)),
@@ -1520,7 +1014,7 @@ mod disarm_tests {
         assert_eq!(torch.armed_off(), None);
     }
 
-    /// Neither hand holds a weapon: the flag hides nothing at all, and a shield stays a shield.
+    /// Neither hand holds a weapon: the flag hides nothing.
     #[test]
     fn the_ladder_takes_weapons_and_leaves_the_rest() {
         let shielded = Wielded {
@@ -1533,8 +1027,7 @@ mod disarm_tests {
         assert_eq!(shielded.armed_off(), Some((4, 6)));
     }
 
-    /// The pure ladder, over the classes alone — the form the action bar's equipped-item test
-    /// (`0x5ea5d0`'s slot 0/1/2 loop) reads off the raw inventory.
+    /// The pure ladder over classes, as the action bar's equipped-item test reads it.
     #[test]
     fn the_ladder_over_classes() {
         assert_eq!(disarmed_hand(Some(2), Some(2)), Some(0));
diff --git a/crates/benilla-app/src/creature_anim/blood.rs b/crates/benilla-app/src/creature_anim/blood.rs
index 71281009..c5a164eb 100644
--- a/crates/benilla-app/src/creature_anim/blood.rs
+++ b/crates/benilla-app/src/creature_anim/blood.rs
@@ -1,9 +1,6 @@
-//! The melee **blood spurt** (decision 0137 phase 3) — the fourth element of the victim-feedback
-//! 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
-//! machinery ([`SpellKitFx::Begin`], self-terminating — the spurt runs its clip span and dies).
+//! The melee blood spurt (`0x624530` → `0x625010`): a self-terminating particle model on the
+//! victim, front or back by where the attacker stands, large on a crushing blow, colored by the
+//! victim's blood type.
 
 use bevy::prelude::*;
 
@@ -17,30 +14,21 @@ use super::spell_visual::FxSlot;
 use super::spell_visual::SpellVisuals;
 use super::{SpellKitFx, SwingImpact, SwingMessage};
 
-/// The gore level: the client's `violenceLevel` cvar (0 none · 1 censored green · 2 true colors).
-///
-/// **2 is the reference's own default, not merely ours** (1859; the rule is 1804). The
-/// registration at `0x6c5aa0` *formats* its default out of a per-region **maximum** table at
-/// `0x86c3f8` — `[2, 1, 2, 2, 2, 2, 2, 2]` — and the setter `0x6c5af0` clamps to that same entry,
-/// so a stock client boots at the highest gore its region permits. The locale table at `0x8558a4`
-/// is `{enUS, koKR, frFR, …}` and `[0xc0e080]` is BSS-zero, so **enUS defaults to 2**; the single
-/// capped entry is koKR, which at 1 maps red → *green* through UnitBloodLevels' middle column —
-/// the censored-locale green blood, which this chain produces without being fitted to it.
-/// Hardcoded rather than carried as a CVar row because
-/// `cvars::REGISTERED` takes one row per knob a settings page actually wires (0137 phase 3).
+/// The gore level, the client's `violenceLevel` (0 none, 1 green, 2 true colors). The reference
+/// defaults it to its region's maximum (`0x6c5aa0`, from the table at `0x86c3f8`, which the setter
+/// `0x6c5af0` also clamps to): 2 for enUS, 1 only for koKR, whose blood turns green. Fixed here,
+/// not a CVar row: `cvars::REGISTERED` holds only the knobs a settings page wires.
 const VIOLENCE_LEVEL: usize = 2;
 
-/// 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).
+/// The victim attachments the spurt hangs on, `0xf` front and `0x10` back (`0x625010`).
 const ATTACH_FRONT: u16 = 15;
 const ATTACH_BACK: u16 = 16;
 
-/// The UnitBlood/UnitBloodLevels tables (`None` until the startup load lands; absent = no spurts,
-/// like every optional DBC face).
+/// The `UnitBlood` and `UnitBloodLevels` tables; absent, no spurts.
 #[derive(Resource)]
 pub(super) struct BloodTables(pub(super) BloodCatalog);
 
-/// Load the blood tables off the patch chain at startup (the [`super::spell_visual`] pattern).
+/// Load the blood tables off the patch chain at startup.
 pub(super) fn load_blood_tables(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let Some(assets) = assets else { return };
     let loaded = {
@@ -57,17 +45,8 @@ pub(super) fn load_blood_tables(mut commands: Commands, assets: Option<Res<World
     }
 }
 
-/// Spawn the spurt per landed swing — at the swing clip's **impact keyframe** ([`SwingImpact`],
-/// not the raw packet: the blood flies when the blow lands, ~300–600 ms into the swing). The
-/// client's gate verbatim — `HitInfo & 0x2`, nonzero damage, victimState ∈ {1, 4} — then the DBC
-/// chain (the victim display's two blood candidates → [`BloodCatalog::level_key`]'s three-tier
-/// row resolve → the violence-leveled UnitBloodLevels row → UnitBlood's front/back × small/large
-/// effect), attached self-terminating on the victim. A missing link anywhere (an unknown display,
-/// a censored violence level) drops the spurt — like the client's NULL-record skips, but
-/// *audibly*: every dropped damaging swing logs its reason at
-/// `info` and every fired spurt at `debug`, so "I never see blood" localizes to a link in one
-/// fight instead of a code audit (no drop lines at all ⇒ the break is upstream, in the
-/// [`SwingImpact`] feed itself).
+/// One spurt per landed swing, at the clip's impact key ([`SwingImpact`]). A missing link in the
+/// blood tables drops it, as the client skips a null record, and logs why at `info`.
 pub(super) fn blood_spurts(
     mut swings: MessageReader<SwingImpact>,
     transforms: Query<&Transform>,
@@ -78,7 +57,7 @@ pub(super) fn blood_spurts(
     mut fx: MessageWriter<SpellKitFx>,
 ) {
     let (Some(creatures), Some(blood), Some(visuals)) = (creatures, blood, visuals) else {
-        for _ in swings.read() {} // tables not up yet — drain, don't backlog
+        for _ in swings.read() {} // tables not loaded: drain, do not backlog
         return;
     };
     for SwingImpact {
@@ -86,10 +65,9 @@ pub(super) fn blood_spurts(
     } in swings.read()
     {
         if *text_only {
-            continue; // a supersede/stop flush carries only the floating text
+            continue; // a flush carries only the floating text
         }
-        // The client's spawn gate (`0x624530`): HitInfo&0x2 (damage landed), nonzero damage,
-        // victimState 1 (normal) or 4 (block-ish partial) — dodges/parries/misses spurt nothing.
+        // The client's gate (`0x624530`): `HitInfo & 0x2`, damage, victim state 1 or 4 (interrupt).
         if swing.hit_info & 0x2 == 0 || swing.damage == 0 || !matches!(swing.victim_state, 1 | 4) {
             if swing.damage > 0 {
                 info!(
@@ -111,18 +89,15 @@ pub(super) fn blood_spurts(
             info!("blood: dropped — display {display_id} unknown to the creature catalog");
             continue;
         };
-        // The reference's three-tier row resolve (`0x60afb0`), including the tier-3 records-base
-        // fallback that 595 of the 10534 shipped displays land on — Quilboar, crocolisks, gnolls
-        // and Stranglethorn trolls among them, which is why it cannot mean "no blood" (1859).
+        // The three-tier row resolve (`0x60afb0`). Its tier-3 records-base fallback is real blood,
+        // never "no blood": Quilboar, crocolisks and gnolls land there.
         let Some(blood_id) = blood.0.level_key(disp_blood, model_blood) else {
             info!("blood: dropped — UnitBloodLevels is empty");
             continue;
         };
         let blood_id = blood_id as i32;
-        // Front or back: the client's `sign(victimForward · (attackerPos − victimPos))`, in WoW
-        // space — a unit Transform's Y rotation *is* its WoW yaw (net/motion's pose convention),
-        // so forward = (cos θ, sin θ) against the WoW-mapped position delta. An unresolvable
-        // attacker (despawned mid-flight) defaults to front.
+        // Front or back: the sign of `victimForward · (attackerPos − victimPos)` in WoW space,
+        // where a unit's Y rotation is its WoW yaw. An unresolved attacker counts as front.
         let front = match (transforms.get(victim), swing_attacker(&transforms, swing)) {
             (Ok(vt), Some(at)) => {
                 let yaw = vt.rotation.to_euler(EulerRot::YXZ).0;
@@ -131,7 +106,7 @@ pub(super) fn blood_spurts(
             }
             _ => true,
         };
-        let large = swing.hit_info & 0x2000 != 0; // HITINFO crushing — the Large row, not crit
+        let large = swing.hit_info & 0x2000 != 0; // crushing picks the large row; a crit does not
         let Some((effect, path)) = blood
             .0
             .effect_id(blood_id, VIOLENCE_LEVEL, front, large)
@@ -143,16 +118,13 @@ pub(super) fn blood_spurts(
         debug!("blood: spurt {path} (blood {blood_id}, front {front}, large {large})");
         fx.write(SpellKitFx::Begin {
             entity: victim,
-            spell_id: 0, // no spell — a self-terminating effect is never reaped by id
+            spell_id: 0, // no spell: a self-terminating effect is never reaped by id
             persistent: false,
             class: super::FxClass::Hold,
-            // The blood spurt is `CEffect::AddEffect` off the melee path, not a kit stage — but it
-            // is the same self-terminating shape (one pass, then gone).
+            // Not a kit stage (`CEffect::AddEffect` off the melee path), but it too plays once.
             stage: super::FxStage::OneShot,
-            // One spurt per (record, tag) on a body: five attackers hitting the same flank
-            // REPLACE each other's spurt rather than stacking five copies of it — the
-            // reference's `0x6208e0` walk, which `resolve_spell_fx` runs for every slot
-            // (decision 2057). It is why a busy fight does not brighten without bound there.
+            // One spurt per (record, tag) on a body: a new one replaces the old (`0x6208e0`, which
+            // `resolve_spell_fx` runs for every slot), so a busy fight does not stack them.
             effects: vec![FxSlot {
                 tag: if front { ATTACH_FRONT } else { ATTACH_BACK },
                 effect,
@@ -162,7 +134,6 @@ pub(super) fn blood_spurts(
     }
 }
 
-/// The attacker's transform, if the entity still exists.
 fn swing_attacker<'a>(
     transforms: &'a Query<&Transform>,
     swing: &SwingMessage,
diff --git a/crates/benilla-app/src/creature_anim/breath.rs b/crates/benilla-app/src/creature_anim/breath.rs
index bc6ab111..7b615798 100644
--- a/crates/benilla-app/src/creature_anim/breath.rs
+++ b/crates/benilla-app/src/creature_anim/breath.rs
@@ -1,81 +1,21 @@
-//! **Cold breath** — the visible vapour a unit puffs from its mouth in a cold zone (B233,
-//! decision 1149).
+//! Cold breath: the vapour a unit puffs from its mouth in a cold zone.
 //!
-//! 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
-//! **cold** one — the only one of the three that was reported missing, and the only one whose
-//! every input benilla already has.
+//! The classifier `0x607710` runs on every unit with a loaded model and caches its verdict for
+//! 10 s ([`classify_breath`]). A cold area is `AreaTable.Flags & 0x1`, inherited one hop from the
+//! parent zone unless the leaf sets `0x2` (`0x67e9c0`); weather and indoors play no part. On `$BTH`
+//! the handler `0x5ffbd0` runs `drunk ≥ 50 → underwater → cold → nothing`, exclusively
+//! ([`fire_breath`]), and the cold puff (`SpellVisualEffectName` 107, a 1.5 s one-shot) hangs at
+//! the mouth. `$BTH` is authored across the idle family and nothing latches it, so the puff
+//! recurs with every idle loop.
 //!
-//! ## The mechanism, in the order the client runs it
+//! Not built: the underwater rung, whose bubbles the reference shows once
+//! `5.0 + SCALE_X · boxHeight < liquidSurfaceZ − unitZ`, with `boxHeight` the M2 header's render
+//! box (MD20 `0xb4`, not the collision box) and `unitZ` the feet: about 8.8 yd deep for a
+//! HumanMale, so a diving unit in a cold zone puffs vapour here. Nor are the drunk bubbles (the
+//! drunk rung still gates) or a WMO interior area for any unit but the player.
 //!
-//! 1. **The classifier** `0x607710` — `CGUnit_C` vtable slot 14, run per frame from the
-//!    WorldFrame's visible-object callback, on **every unit with a loaded model** (NPCs and
-//!    creatures too; there is no local-player gate anywhere in it). It **clears both**
-//!    `[unit+0xc58]` bits at entry and then sets **at most one**: `0x20` submerged, `0x40` cold.
-//!    It stamps `[unit+0xc18] = now + 10 s` on every leg, so **the classification is cached for
-//!    ten seconds per unit** — crossing a zone border does not take effect instantly.
-//!    [`classify_breath`].
-//! 2. **The cold test** `0x67e9c0` — `AreaTable.Flags` bit `0x1`, inherited ONE hop from the
-//!    parent zone unless the leaf sets bit `0x2`. That single hop is the whole mechanism: only
-//!    four rows in 5875 author the bit (Dun Morogh, Winterspring, Razorfen Downs, Naxxramas) and
-//!    every sub-area a player actually stands in carries `0x40`, so a leaf-only read finds
-//!    nothing anywhere. [`benilla_formats::AreaTableCatalog::is_cold`].
-//!    It is **independent of the weather** — snowfall and breath share no input — and there is no
-//!    indoor suppression: the Thunderbrew Distillery is as cold as the road outside.
-//! 3. **The handler** `0x5ffbd0` — on the `$BTH` anim event, the ladder
-//!    `drunk ≥ 50 → underwater → cold → nothing`, strictly exclusive. [`fire_breath`].
-//! 4. **The puff** — `SpellVisualEffectName` row 107 `"HARDCODED Breath Cold"` →
-//!    `Particles\ColdBreath.m2`, attached at **M2 AttachmentID `0x11`** (a bone under the head —
-//!    key bone 21, whose pivot is the mouth), inheriting the bone's full orientation. The asset
-//!    is emitter-only (no mesh): one non-looping 1.5 s sequence, one continuous particle emitter,
-//!    zero gravity, a ~1.6° cone — a tight puff, not a spray. It self-terminates at the end of
-//!    its own clip (the `0x5fbf50` one-shot terminator, the same lifetime the mount poof uses).
-//!
-//! **`$BTH` is authored on the whole idle family**, so the cadence is the animation's, not a
-//! timer's: `Stand` and its variants, every `Ready*`, `Stun`, `Sleep`, `KneelLoop`,
-//! `StealthStand`, `SwimIdle`, several emotes and `Drown` — on every player race/gender (HumanMale
-//! `Stand` keys one at 667 ms), and on 148 of the 430 creature models. There is no fire-once
-//! latch, so it re-fires every loop of the carrying clip.
-//!
-//! ## 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 (`0x607710`'s liquid arm). The test is
-//!
-//!   ```text
-//!   underwater ⟺ 5.0 + SCALE_X · boxHeight < liquidSurfaceZ − unitZ
-//!   ```
-//!
-//!   where `boxHeight` is the M2 header's **box A** — `bounding_box_max.z − bounding_box_min.z`,
-//!   the loose all-animation render box at MD20 `0xb4`, raw model space
-//!   (`benilla_m2::M2Header::bounding_box_min`/`_max`). Emphatically **not** the collision box and
-//!   not `CreatureModelData.CollisionHeight`: those are the *other* box (`0xd0`) and agree with
-//!   each other, not with this one. `SCALE_X` is the only multiplier — no DBC scale enters.
-//!   `unitZ` is the unit's **feet** (its movement-block position), and `liquidSurfaceZ` is the
-//!   ordinary liquid query's own cached surface, not a second sample.
-//!
-//!   For a scale-1 HumanMale that threshold is **8.84 yd** of water above the feet (box A `Δz` =
-//!   3.8415); DwarfMale 8.03, GnomeFemale 7.11, TaurenMale 10.21; a unit whose model has not
-//!   loaded uses the ctor default `1.0`, i.e. 6.0. **So it is a diving test, not a swimming one**,
-//!   and that is what bounds the omission: a unit in a cold zone puffs vapour where the reference
-//!   would puff bubbles only once genuinely deep. The bubbles themselves
-//!   (`Particles\Bubbles.m2` — 3.3 s and *looping*, so they need the replace-on-respawn dedup
-//!   this module's one-shot does not) are a separate, unreported feature. Two details for whoever
-//!   builds it: while **mounted** the box is the MOUNT's model, and `SCALE_X` runs through a 2 s
-//!   cosine ease after a scale change (bit-exact at rest, so only that window differs).
-//! - **The drunk rung gates but does not spawn.** `drunk ≥ 50` correctly suppresses cold breath
-//!   (the ladder is exclusive); the inebriated bubbles themselves are unreported and their clip
-//!   semantics are unpinned, so nothing is drawn there.
-//! - **A remote unit's area is the terrain's alone.** The player's area comes from
-//!   [`CurrentArea`], which races a WMO interior claim ahead of the terrain chunk exactly as the
-//!   client's `GetAreaID` does; there is no per-unit equivalent of that claim, so other units
-//!   read [`area_id_under`]. It differs only inside a WMO whose `WMOAreaTable` row names a
-//!   different area than the ground beneath it.
-//! - **Overlap is refused rather than replaced.** The client's `0x6208e0` destroys a still-running
-//!   puff when a new one spawns on the same unit at the same tag; our one-shot instances carry no
-//!   reap key, so [`fire_breath`] declines a new puff while the last one is still inside its clip
-//!   instead. Same observable — never two overlapping puffs — with the running one finishing
-//!   rather than restarting.
+//! Deviation: a new puff inside the last one's clip is declined instead of replacing it
+//! (`0x6208e0`), because one-shot effects carry no reap key; either way two never overlap.
 
 use bevy::ecs::entity::EntityHashMap;
 use bevy::prelude::*;
@@ -87,59 +27,47 @@ use crate::net::{NetEntity, ObjectStore, SelfPlayer};
 use super::events::AnimSoundEvent;
 use super::spell_visual::{FxClass, FxSlot, FxStage, SpellKitFx, SpellVisuals};
 
-/// The event that asks "what does this unit breathe?" — `0x5fffad cmp eax,0x48544224`.
+/// The breath event (`0x5fffad` compares against it).
 const BTH: [u8; 4] = *b"$BTH";
 
-/// Hardcoded-effect index **3**'s baked lookup name (the `0x8617b8` string table, matched by the
-/// boot name-resolve `0x61f5b0`) → `SpellVisualEffectName` row 107 → `Particles\ColdBreath.m2`.
+/// Hardcoded effect 3's name (`0x8617b8`, resolved at boot by `0x61f5b0`): `SpellVisualEffectName`
+/// row 107, `Particles\ColdBreath.m2`.
 const COLD_BREATH_EFFECT: &str = "HARDCODED Breath Cold";
 
-/// The `$BTH` family's attach tag — `DAT_0080c968[2..=3]` and `[7]` are all `0x11`, where the loot
-/// art / ding / mount poof are `0x13`. A **raw M2 `AttachmentID`**, resolved through the model's
-/// own `attachment_lookup` (the index it lands on differs per model: 17 on HumanMale, 13 on
-/// HumanFemale, 8 on GnomeFemale, 2 on Wolf — never use the tag as an array index).
+/// The `$BTH` attach tag (entries 2, 3 and 7 of `0x80c968`), a raw M2 `AttachmentID`: resolve it
+/// through the model's `attachment_lookup`, never use it as an index (17 on HumanMale, 2 on Wolf).
 const BREATH_ATTACH: u16 = 0x11;
 
-/// `[unit+0xc18] = now + 0x2710` — the classifier re-runs at most every 10 s per unit.
+/// `[unit+0xc18] = now + 0x2710`: a unit is reclassified at most every 10 s.
 const RECLASSIFY_SECS: f32 = 10.0;
 
-/// `PLAYER_BYTES_3` byte 1, clamped 100, `×0.01 ≥ 0.5` (`0x5ffbd0`) — i.e. the raw byte at 50.
-/// Read on **players only** (`OBJECT_FIELD_TYPE` bit 4, `0x600018`).
+/// `PLAYER_BYTES_3` byte 1 clamped to 100, `× 0.01 ≥ 0.5` (`0x5ffbd0`); players only (`0x600018`).
 const DRUNK_THRESHOLD: u8 = 50;
 
-/// `Particles\ColdBreath.m2`'s only sequence: 3333 → 4833 ms, `flags = 0x1` (non-looping). The
-/// window inside which a second `$BTH` is declined — see the module docs' overlap divergence.
+/// `ColdBreath.m2`'s one non-looping sequence, 3333 to 4833 ms: no second puff inside it.
 const COLD_BREATH_CLIP: f32 = 1.5;
 
-/// What a unit's environment says it breathes — the client's `[unit+0xc58]` bits `0x20`/`0x40`,
-/// which the classifier clears together and sets at most one of.
+/// The client's `[unit+0xc58]` breath bits, at most one set.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum Breath {
-    /// Bit `0x40` — a cold area. The puff.
+    /// Bit `0x40`: a cold area.
     Cold,
-    /// Neither bit: nothing to see. (Bit `0x20`, submerged, is the unmodelled rung — module docs.)
+    /// Neither bit; `0x20`, submerged, is not built.
     None,
 }
 
-/// A unit's cached breath classification and when it next goes stale — the client's
-/// `[unit+0xc58]` bits behind their `[unit+0xc18]` 10-second stamp.
+/// A unit's cached classification and its `[unit+0xc18]` expiry.
 #[derive(Component)]
 pub(crate) struct BreathEnv {
     kind: Breath,
-    /// `Time::elapsed_secs` at which [`classify_breath`] re-resolves this unit.
     stale_at: f32,
 }
 
-/// When the last cold-breath puff started on this unit — the overlap guard standing in for the
-/// client's `0x6208e0` replace-on-respawn dedup (module docs).
+/// When each unit's last puff started: the overlap guard.
 #[derive(Resource, Default)]
 pub(super) struct LastPuff(EntityHashMap<f32>);
 
-/// Resolve `[unit+0xc58]`'s bits for every unit whose 10-second stamp has expired — the client's
-/// `0x607710`, which runs on every unit with a loaded model and caches for 10 s.
-///
-/// A unit seen for the first time has no [`BreathEnv`] and is classified at once, so a unit that
-/// streams in inside a cold zone breathes on its next idle loop rather than up to 10 s later.
+/// The classifier `0x607710` for each unit whose stamp expired; a new unit classifies at once.
 pub(super) fn classify_breath(
     mut commands: Commands,
     time: Res<Time>,
@@ -149,15 +77,14 @@ pub(super) fn classify_breath(
     world: benilla_world::world_point::WorldPoint,
 ) {
     let Some(areas) = areas else {
-        return; // no client data — the DBC-resource degrade shape, as everywhere else
+        return; // no client data
     };
     let now = time.elapsed_secs();
     for (entity, transform, env) in &units {
         if env.is_some_and(|e| now < e.stale_at) {
             continue;
         }
-        // The player's area is `CurrentArea` — the client's own `GetAreaID`, WMO-interior claim
-        // included. Every other unit gets the outdoor leg alone (module docs).
+        // The player's area includes the WMO interior claim; other units get the terrain's.
         let area = if self_units.contains(entity) {
             world.area()
         } else {
@@ -167,8 +94,7 @@ pub(super) fn classify_breath(
             Some(id) if areas.0.is_cold(id) => Breath::Cold,
             _ => Breath::None,
         };
-        // try_insert: a streamed unit can despawn (teardown, teleport, range-out) between this
-        // system's parallel run and its sync point — a plain insert panics on the dead entity.
+        // try_insert: a streamed unit can despawn before the commands apply.
         commands.entity(entity).try_insert(BreathEnv {
             kind,
             stale_at: now + RECLASSIFY_SECS,
@@ -176,12 +102,8 @@ pub(super) fn classify_breath(
     }
 }
 
-/// The `$BTH` handler `0x5ffbd0`: run the exclusive ladder and puff.
-///
-/// The event fires on the model that authored it, which for a mounted rider is the body hanging
-/// off the mount — so the **puff goes on the event's own entity** (its mouth), while the unit
-/// state the ladder reads (drunk, the environment) comes from the composite's **root**, exactly
-/// as the footfall visuals split them.
+/// The `$BTH` handler `0x5ffbd0`. The puff goes on the model that fired the event (a rider's body,
+/// not the mount), while the ladder reads the composite root's state.
 pub(super) fn fire_breath(
     mut events: MessageReader<AnimSoundEvent>,
     time: Res<Time>,
@@ -200,7 +122,7 @@ pub(super) fn fire_breath(
         return;
     };
     let Some((effect, path)) = visuals.0.hardcoded_effect(COLD_BREATH_EFFECT) else {
-        return; // no such row — no breath (the DBC-resource degrade shape)
+        return; // no such row, no breath
     };
     let path = path.to_string();
     let now = time.elapsed_secs();
@@ -208,9 +130,7 @@ pub(super) fn fire_breath(
         if ev.ident != BTH {
             continue;
         }
-        // `CreatureModelData.Flags & 0x2` suppresses the whole `$BTH` family — skeletons, ghosts,
-        // elementals, golems, slimes, totems: 99 of the 430 shipped rows. Read off the model that
-        // fired the event, which is the model that would wear the puff.
+        // `CreatureModelData.Flags & 0x2` never breathes (skeletons, elementals, totems).
         let breathes = models
             .get(ev.entity)
             .ok()
@@ -226,9 +146,7 @@ pub(super) fn fire_breath(
         let Ok((store, env)) = roots.get(root) else {
             continue;
         };
-        // The ladder, strictly exclusive (`0x5ffbd0`): drunk ≻ underwater ≻ cold ≻ nothing. The
-        // drunk rung reads PLAYER_BYTES_3 byte 1 and is a PLAYER-only field, so a creature never
-        // takes it; the underwater rung is the unmodelled one (module docs).
+        // The ladder: drunk (a player field, so never a creature), underwater (not built), cold.
         if store.is_some_and(|s| {
             s.0.player_drunk_byte()
                 .is_some_and(|b| b >= DRUNK_THRESHOLD)
@@ -238,7 +156,6 @@ pub(super) fn fire_breath(
         if env.map(|e| e.kind) != Some(Breath::Cold) {
             continue;
         }
-        // The overlap guard: one puff at a time on a unit (module docs).
         if last
             .0
             .get(&ev.entity)
@@ -256,7 +173,7 @@ pub(super) fn fire_breath(
             spell_id: 0,
             persistent: false,
             class: FxClass::Hold,
-            // `0x5fbf50` — destroy at the first completion; the shipped clip runs 1.5 s.
+            // `0x5fbf50`: destroyed at its first completion.
             stage: FxStage::OneShot,
             effects: vec![FxSlot {
                 tag: BREATH_ATTACH,
@@ -265,12 +182,11 @@ pub(super) fn fire_breath(
             }],
         });
     }
-    // Streamed units despawn on range-out — drop their puff memory with them.
+    // Forget despawned units.
     last.0.retain(|e, _| models.contains(*e));
 }
 
-/// The resource the overlap guard lives in — the systems themselves are wired into
-/// `creature_anim`'s own chain beside every other `$`-tag consumer.
+/// The overlap guard's resource; the systems run in `creature_anim`'s own chain.
 pub(super) fn register(app: &mut App) {
     app.init_resource::<LastPuff>();
 }
@@ -279,8 +195,6 @@ pub(super) fn register(app: &mut App) {
 mod tests {
     use super::*;
 
-    /// The 10-second stamp: a freshly-seen unit classifies at once, and a classified one is not
-    /// re-resolved until its stamp expires — the client's `[unit+0xc18] = now + 0x2710`.
     #[test]
     fn classification_is_cached_for_ten_seconds() {
         let env = BreathEnv {
@@ -295,8 +209,7 @@ mod tests {
         );
     }
 
-    /// The tag is `0x11`, not the loot/ding/poof `0x13` — the one number that decides whether the
-    /// vapour comes out of the mouth or the unit's base.
+    /// `0x11`, not the loot, ding and mount-poof `0x13`: the mouth, not the unit's base.
     #[test]
     fn breath_attaches_at_the_mouth_tag() {
         assert_eq!(BREATH_ATTACH, 0x11);
diff --git a/crates/benilla-app/src/creature_anim/driver.rs b/crates/benilla-app/src/creature_anim/driver.rs
index 93432bc2..f3fadb08 100644
--- a/crates/benilla-app/src/creature_anim/driver.rs
+++ b/crates/benilla-app/src/creature_anim/driver.rs
@@ -1,18 +1,7 @@
-//! The Bevy driver: [`drive_animations`], which executes the state machine [`super::select`]
-//! picks, reading and writing [`super::AnimDriver`]'s private state. Kept in its own file as it
-//! carries the bulk of the per-frame Bevy system logic, separate from the module face ([`super`])
-//! and the pure selector logic ([`super::select`]). Split into a small family of children — the
-//! playback primitives ([`play`]), the wound-flinch secondary-blend slot logic ([`wound`]), the
-//! per-hand weapon-grip overlay ([`grip`]), and the base track's **mode machine** ([`mode`]) —
-//! with this file the stable face, re-exporting [`grip::drive_hand_grip`] unchanged.
-//!
-//! What is left here is one function, [`drive_animations`], and it is a *sequence of phases* over
-//! one unit, not a set of concerns: the prologue that computes the frame's facts, the death
-//! override, the mount transition edge, the sheath state, the one-shot gather-and-arm, the mode
-//! machine (now [`mode`]), the rate write, the fades, the trace, the wound, the sheath reconcile.
-//! The phases share ~20 live bindings and a handful of frame-local flags, so they do not come
-//! apart on a module boundary the way the four children did — decision 0933 records which cut was
-//! taken, which was not, and why.
+//! The Bevy animation driver: [`drive_animations`] runs the state machine [`super::select`] picks,
+//! as a fixed sequence of phases per unit (death, mount edge, sheath, one-shots, [`mode`], rate,
+//! fades, trace, wound, sheath reconcile). The phases share many frame-local bindings, so they
+//! stay in one function.
 
 use std::time::Duration;
 
@@ -51,42 +40,25 @@ pub(super) use grip::drive_hand_grip;
 use play::{holds_own_clip, oneshot_finished, play_clip, roll_loop, roll_oneshot};
 use wound::{wound_evict, wound_trigger, wound_upkeep, WoundEdge};
 
-/// The weight of a masked upper-body one-shot overlay ([`AnimDriver::overlay`]) over the base clip on
-/// the SpineLow subtree both drive (decision 0087). The base clip is *not* masked out of that subtree
-/// (it animates the whole skeleton), so base and overlay blend there — this makes the overlay
-/// dominate ≈ 8:1 (the torso visibly swings/emotes, not a wash with the run's torso), a small bleed
-/// the cost of Bevy's weighted blend. The legs are excluded by the mask entirely. Same rationale and
-/// value as the per-arm sheath ceremony's overlay weight.
+/// The masked overlay's weight over the base clip on the SpineLow subtree, where the unmasked base
+/// still blends: the overlay dominates about 8:1, the sheath ceremony overlay's value too.
 const ONESHOT_OVERLAY_WEIGHT: f32 = 8.0;
 
-/// 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
-/// **held final frame** into the bone's secondary slot, seeds `+0x100 = clock + 150`,
-/// `+0x104 = 1/150`, `+0x108 = 1.0`, and disarms the primary so the bone inherits bone 0 again.
-/// **Fixed 150 ms** — deliberately NOT the sequence's own blendTime, which is used only on the arm
-/// path.
+/// The key-bone fade-to-rest: a finished one-shot's held final frame fades back to bone 0 over a
+/// fixed 150 ms (`0x5fcacb` → op4 `param_3 = -1`), not the clip's own blendTime.
 const ONESHOT_RELEASE_FADE: f32 = 0.150;
 
-/// The launch vertical speed (yd/s, +up) above which a new airborne arc is a **jump** (the 37/38
-/// bracket) rather than a step-off fall. A jump launches at ≈7.96 up (our own controller's
-/// `JUMP_SPEED`; a remote's `-zspeed - g·t` is still ≳4 after relay latency); a step-off starts
-/// level or already descending — the two never come near this line.
+/// Launch vertical speed (yd/s, up) above which an airborne arc is a jump (the 37/38 bracket), not
+/// a step-off fall; a jump launches near 7.96 up, a step-off at zero or below.
 const JUMP_ARC_MIN_UP: f32 = 0.5;
 
-/// A one-shot play request gathered from this frame's messages, resolved to an anim id inside
-/// the unit loop (a swing's id keys the attacker's own wielded weapon).
+/// A one-shot play request from this frame's messages, resolved to an anim id per unit.
 enum OneShotReq {
     Swing(u32),
     Emote(u16),
 }
 
-/// The currently-armed one-shot the combat fast-path tests — the client's key-bone-else-bone-0
-/// 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.
+/// The live one-shot the combat fast path tests: the key bone's clip, else bone 0's (`0x5fe422`).
 fn live_oneshot(
     drv: &AnimDriver,
     player: &AnimationPlayer,
@@ -107,10 +79,8 @@ fn live_oneshot(
     None
 }
 
-/// Whether **any** one-shot is currently live on the unit — [`live_oneshot`] minus the node. The
-/// missile queue's anim-end flush backstop (the client's `0x5fc920` on-anim-finish → `0x60c9b0`
-/// is a *callback*; ours polls this edge): a queued missile whose release keyframe never fired
-/// launches when the cast one-shot ends.
+/// Whether a one-shot is live on the unit; the missile queue polls it to launch a missile whose
+/// release keyframe never fired when the cast ends (the reference's `0x5fc920` → `0x60c9b0`).
 pub(crate) fn oneshot_is_live(
     drv: &AnimDriver,
     player: &AnimationPlayer,
@@ -121,14 +91,9 @@ pub(crate) fn oneshot_is_live(
     live_oneshot(drv, player, tr, anims, catalog).is_some()
 }
 
-/// Retire whatever holds the key-bone slot into its cross-fade ([`AnimDriver::overlay_fade`]) —
-/// the client's op4 snapshot of the outgoing pose into the bone's SECONDARY (`rep movsd
-/// +0x98 → +0xc4`) plus the window seed (decision 0878). `total` is the window: the incoming
-/// clip's own blendTime on a blended re-arm, [`ONESHOT_RELEASE_FADE`] on a fade-to-rest. Honors
-/// the client's **re-snapshot guard** (`0x7125d4` on the arm path, `0x7123a2` on the release
-/// path, both against `0x7ffa24 = 0.5f`): a fade still running above λ = 0.5 is not re-seeded —
-/// the older pose keeps decaying and the superseded node is simply dropped. Leaves
-/// [`AnimDriver::overlay`] empty; the caller arms the incoming clip (if any) after it.
+/// Retire the key-bone clip into its cross-fade over `total` seconds: op4 snapshots the outgoing
+/// pose into the secondary (`+0x98 → +0xc4`). A fade still above λ = 0.5 (`0x7ffa24`) is not
+/// re-seeded (`0x7125d4` arm, `0x7123a2` release); the superseded node is dropped.
 fn retire_overlay(drv: &mut AnimDriver, player: &mut AnimationPlayer, total: f32) {
     let out = drv.overlay.take().map(|ov| ov.node);
     if drv.overlay_fade.is_some_and(|f| fade_lambda(&f) > 0.5) {
@@ -147,22 +112,14 @@ fn retire_overlay(drv: &mut AnimDriver, player: &mut AnimationPlayer, total: f32
     });
 }
 
-/// The blend weight λ of a key-bone cross-fade this frame — `smoothstep` over the fraction of the
-/// window still to run, so it decays 1 → 0 ([`select::blend_lambda`]).
+/// The cross-fade's λ this frame, decaying 1 → 0 over the window.
 fn fade_lambda(f: &OverlayFade) -> f32 {
     select::blend_lambda(if f.total > 0.0 { f.left / f.total } else { 0.0 })
 }
 
-/// The key-bone cross-fade's per-frame advance (decision 0878) — the kernel's λ decay
-/// (`0x714880`–`0x714923`) and its self-release (`0x7147b9`: `+0xd0 = -1` and λ = 0 the same
-/// frame). Two shapes, decided by whether an incoming clip holds the slot:
-///
-/// - **A release** (no incoming): the retiring node alone fades against the base, so its weight
-///   must land the blended share on `λ · W/(1+W)` — the client's full-override λ, capped by the
-///   standing [`ONESHOT_OVERLAY_WEIGHT`] approximation. `w = W·λ / (1 + W·(1−λ))`.
-/// - **A re-arm** (incoming present): the two clips split the slot's share by λ exactly as the
-///   client's `primary + (secondary − primary)·λ` does, at constant total — `W·λ` out, `W·(1−λ)`
-///   in. (An incoming that arrived by *transplant* seeds no fade at all: `blendFlag = 0`.)
+/// The key-bone cross-fade's advance (λ decay `0x714880`–`0x714923`, release `0x7147b9`). A
+/// release fades the old node alone against the base, `w = W·λ / (1 + W·(1−λ))`; a re-arm splits
+/// the share by λ as `primary + (secondary − primary)·λ` does, `W·λ` out and `W·(1−λ)` in.
 fn overlay_fade_upkeep(drv: &mut AnimDriver, player: &mut AnimationPlayer, dt: f32) {
     let Some(mut f) = drv.overlay_fade else {
         return;
@@ -194,19 +151,11 @@ fn overlay_fade_upkeep(drv: &mut AnimDriver, player: &mut AnimationPlayer, dt: f
     }
 }
 
-/// 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
-/// cast therefore keeps running on the torso *at exactly the frame it was on*, with no cross-fade
-/// and no restart, while the legs take the jump or the run. This is the director's "jump right
-/// after a cast: the legs jump, the arms finish the cast".
-///
-/// A no-op when the key-bone is already armed — `0x5fe912` then jumps straight to `0x5fe930`
-/// (request → bone 0, key-bone untouched), which is exactly what leaving [`AnimDriver::overlay`]
-/// alone already gives us. Named simplification: the moved clip re-arms as a plain `Never` repeat,
-/// dropping any unspent replay budget (`R > 1`); every cast and swing this fires for is authored
-/// `(0, 0)` ⇒ `R = 1`.
+/// The transplant (`0x5fe919`): a locomotion request while bone 0 plays a live cast or combat
+/// one-shot moves that clip, at its id, rate and elapsed position, onto the key bone with
+/// `blendFlag = 0`, so the torso finishes the cast while the legs take the request. A no-op when
+/// the key bone is armed (`0x5fe912` → `0x5fe930`). The moved clip repeats `Never`, dropping any
+/// replay budget; every clip this fires for is authored `(0, 0)`, so `R = 1`.
 fn transplant_up(
     drv: &mut AnimDriver,
     player: &mut AnimationPlayer,
@@ -221,8 +170,7 @@ fn transplant_up(
     let Some(node) = tr.get_main_animation() else {
         return false;
     };
-    // The live position + rate, read off the armed VARIATION node (the play rolled one of them),
-    // which is also how we find the masked twin to resume on.
+    // Read off the armed variation node, which also names the masked twin to resume on.
     let Some((seek, speed)) = player
         .animation(node)
         .filter(|a| !a.is_finished())
@@ -243,7 +191,7 @@ fn transplant_up(
     active.set_repeat(bevy::animation::RepeatAnimation::Never);
     active.seek_to(seek);
     active.set_speed(speed);
-    active.set_weight(ONESHOT_OVERLAY_WEIGHT); // `blendFlag = 0` — no ramp, no cross-fade
+    active.set_weight(ONESHOT_OVERLAY_WEIGHT); // `blendFlag = 0`: no cross-fade
     drv.overlay = Some(Overlay {
         node: upper,
         id,
@@ -258,10 +206,8 @@ fn transplant_up(
     true
 }
 
-/// The animation state machine, per unit (decision 0049 + 0073). Death overrides; otherwise:
-/// enter/loop/exit the Special states (jump, sit/sleep/kneel) as one-shot-bracketed loops, play the
-/// per-packet melee swings as preemptible one-shots, and cross-fade the gaits (the engaged Ready
-/// idle among them).
+/// The per-unit animation state machine: death overrides; otherwise Specials as bracketed loops,
+/// one-shots over or instead of the base, and cross-faded gaits.
 #[allow(clippy::type_complexity)]
 pub(super) fn drive_animations(
     mut commands: Commands,
@@ -285,29 +231,17 @@ pub(super) fn drive_animations(
             Has<SelfPlayer>,
             Option<&crate::entities::mount::MountBody>,
             Has<crate::net::CreatureSwimming>,
-            // Is the in-hand arrow currently latched (the `$BWP`..`$BWR` window)? Read only by
-            // the leaving-the-stance un-nock at the tail of this pass, which is edge-triggered
-            // off it rather than issuing a remove every frame.
+            // The in-hand arrow is latched (the `$BWP`..`$BWR` window).
             Has<NockLatch>,
-            // The rendered model scale — `OBJECT_FIELD_SCALE_X`, baked onto the entity transform by
-            // `entities::attach`. The locomotion playback rate divides by it (decision 0903), so an
-            // ogre at 2.2× cycles its legs 2.2× slower than a same-speed human. Read-only: nothing
-            // in this system moves a unit.
+            // `OBJECT_FIELD_SCALE_X` on the transform; the locomotion rate divides by it.
             &Transform,
-            // The server-granted movement modes (decision 1780) — root, water-walk, feather-fall,
-            // hover, walk-mode, swim. `unify` folds them into the flags word the selector reads, so
-            // a creature the server has rooted or put in walk mode is animated as one.
+            // Server-granted movement modes, folded by `unify` into the selector's flags word.
             Option<&crate::net::UnitMoveModes>,
-            // The unit's aura CharProc nodes — read for ONE thing here: whether a proc-11
-            // animation-rate node (the freeze auras' `0x6201d0` node, decision 0889) is on the
-            // unit, which is the client's `+0x2c & 0x4` wound-flinch refusal (decision 2063).
+            // A proc-11 rate node here (the freeze auras', `0x6201d0`) refuses the wound flinch.
             Option<&crate::aura_visual::AuraNodes>,
         ),
     )>,
-    // A mount child's movement view is its HOST's (decision 0441): the same
-    // MovementState/RemoteMotion/Spline/speeds the rider's `unify` reads, fetched through
-    // `MountBody.host` — so the untouched gait machinery locomotes the mount for self, remote
-    // players, and mounted NPCs alike. Read-only over types `units` also only reads.
+    // A mount child's movement view is its host's, fetched through `MountBody.host`.
     mount_hosts: Query<(
         Option<&Spline>,
         Option<&RemoteMotion>,
@@ -315,14 +249,10 @@ pub(super) fn drive_animations(
         Option<&UnitSpeeds>,
         Option<&FacingStep>,
         Has<crate::net::CreatureSwimming>,
-        // …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
-        // (`0x613ef0`). The rate divisor wants that product
-        // — the mount model's world scale — not the child's local column (decision 0903).
+        // The rider's scale: the mount renders at the rider's scale times its own (`0x613ef0`).
         &Transform,
-        // …and whether the rider is US, which only the debug trace reads (decision 0906).
+        // Read only by the debug trace.
         Has<SelfPlayer>,
     )>,
     mut swings: MessageReader<SwingMessage>,
@@ -335,55 +265,35 @@ pub(super) fn drive_animations(
     mut sheath_swaps: MessageWriter<SheathSwapMessage>,
     anim_data: Option<Res<AnimData>>,
     net: Res<NetCommands>,
-    // The shared emote-audio catalog, promoted here for its `Emotes.dbc` → `AnimID` column: the
-    // looping state-emote idle (`UNIT_NPC_EMOTESTATE`) below resolves through it, same as the
-    // `SMSG_EMOTE` one-shot consumer ([`emote_anim::emote_to_anim`]).
-    // One tuple param (the 16-SystemParam ceiling): the shared emote-audio catalog, the
-    // client-local loot-target latch, and the frame clock.
+    // One tuple: this system is at Bevy's 16-SystemParam ceiling.
     aux: (
+        // Its `Emotes.dbc` → `AnimID` column resolves the `UNIT_NPC_EMOTESTATE` idle.
         Option<Res<EmoteSounds>>,
-        // Predicate B's standing answer (decision 1477): whether the currently latched loot
-        // target is one the SELF unit kneels at — the loot leg's whole self trigger, since it is
-        // false while the latch is cold. `Option` for the headless test worlds that don't build
-        // the loot seam.
+        // Whether the latched loot target is one the self unit kneels at; false while cold.
         Option<Res<crate::ui_loot::LootKneel>>,
-        // The frame clock — the key-bone cross-fade's only time source (decision 0878): its
-        // retiring node is *frozen* on the clip's final frame, so unlike the wound's decay there
-        // is no playback clock to read the λ window off.
+        // The key-bone cross-fade's clock: its retiring node is frozen, so it has no playback
+        // clock of its own.
         Res<Time>,
-        // The creature-template cache — read for ONE bit, the victim's `DO_NOT_PLAY_WOUND_ANIM`
-        // (decision 2068), which is the wound trigger's first entry gate below. `Option` for the
-        // headless test worlds that build no net seam; a missing cache reads exactly like a
-        // template we have not received, which is the reference's own null-record leg.
+        // Read for `DO_NOT_PLAY_WOUND_ANIM`; a missing cache reads as an unreceived template.
         Option<Res<crate::names::NameCache>>,
-        // The **stage-2 base recomputes** ([`BaseAnimRecompute`]) — in the tuple for the same
-        // reason as its neighbours: this system sits on the 16-SystemParam ceiling.
         MessageReader<BaseAnimRecompute>,
     ),
-    // The variation roll's LCG state (decision 0114 — the client's single CRT `_rand` stream,
-    // shared by every play; [`select::msvc_rand`]).
+    // The variation roll's LCG, the reference's single CRT `_rand` stream shared by every play.
     mut rng: ResMut<benilla_assets::AnimRng>,
-    // The SELF unit's last-written anim state line of the `WOW_MOVE_TRACE` debug trace (the
-    // diff-only filter; see the trace block after the mode machine).
+    // The last anim trace line per traced unit; the trace writes only on change.
     mut anim_trace_last: Local<std::collections::HashMap<Entity, String>>,
 ) {
     let (emote_sounds, loot_kneel, time, names, mut recomputes) = aux;
     let dt = time.delta_secs();
-    // This frame's one-shot PLAY CALLS (swings + anim-emotes), gathered per unit and replayed
-    // in the client's call order below ([`PlaySeq`] stamps — the net drain stamps packet order,
-    // scene-time emitters stamp after it). Order matters twice over: the later call overwrites
-    // the earlier on the default path (decision 0399), and the combat FAST-PATH (decision 0406)
-    // keys on what is *currently playing* when each call runs.
+    // This frame's one-shot plays per unit, replayed in the reference's call order (`PlaySeq`
+    // stamps): a later call overwrites an earlier, and the combat fast path keys on what is playing
+    // when each call runs.
     let mut pending: bevy::ecs::entity::EntityHashMap<Vec<(OneShotReq, u64)>> = default();
-    // …and by victim: a landed hit with the flinch bit (`HitInfo & 0x2` — the sole trigger gate,
-    // decision 0111) plays the victim's wound-flinch **decay overlay** below, as does a spell-side
-    // flinch ([`WoundAnim`] — the kit player's 8–10 branch, a harmful instant impact, a missile
-    // impact; severity 0 every time, decision 2058). Last hit wins, matching the client, where a
-    // re-trigger re-seeds the same secondary slot. Independent of the attacker-side 0x10000
-    // suppressor (that bit gates the *swing* animation only).
+    // Wound flinches by victim, melee (`HitInfo & 0x2`) or spell (severity 0); the last wins, as a
+    // re-trigger re-seeds the same secondary slot.
     let mut pending_wound: bevy::ecs::entity::EntityHashMap<WoundEdge> = default();
     for s in swings.read() {
-        // HitInfo bit 0x10000 suppresses the swing anim (decision 0073's verified suppressor).
+        // HitInfo 0x10000 suppresses the swing animation only.
         if s.hit_info & 0x10000 == 0 {
             pending
                 .entry(s.attacker)
@@ -391,8 +301,7 @@ pub(super) fn drive_animations(
                 .push((OneShotReq::Swing(s.hit_info), s.seq));
         }
     }
-    // The victim's wound flinch fires at the swing clip's IMPACT keyframe ([`SwingImpact`],
-    // `impact.rs`), not at packet receive — the blow lands, then the victim recoils.
+    // The flinch fires at the swing clip's impact keyframe, not at packet receive.
     for SwingImpact {
         swing: s,
         text_only,
@@ -408,50 +317,37 @@ pub(super) fn drive_animations(
     for w in spell_wounds.read() {
         pending_wound.insert(w.entity, WoundEdge::Spell);
     }
-    // This frame's victim DEFENSE reactions (`$CPP`, decision 0279), keyed by victim — last wins
-    // (a re-trigger re-arms the same primary). Resolved to an anim id inside the loop: the parry
-    // pick keys the victim's OWN mainhand, and the client's alive gate needs the store.
+    // Defense reactions (`$CPP`) by victim, last wins; resolved per unit, as the parry keys the
+    // victim's own mainhand.
     let mut pending_defense: bevy::ecs::entity::EntityHashMap<u32> = default();
     for d in defenses.read() {
         pending_defense.insert(d.victim, d.victim_state);
     }
-    // This frame's whiff slow-downs (`0x712910`, decision 0279): the attacker's in-flight swing
-    // drops to HALF speed for its remainder.
+    // Whiff slow-downs (`0x712910`): the attacker's in-flight swing drops to half speed.
     let mut pending_slow: bevy::ecs::entity::EntityHashSet = default();
     for s in slows.read() {
         pending_slow.insert(s.0);
     }
-    // This frame's anim-emotes join the same request list (the [`PlaySeq`] sort below puts the
-    // two writer streams in emission order). Played as the same over-the-gait one-shot as a
-    // swing (the talk emote on interact — decision 0081).
     for e in emotes.read() {
         pending
             .entry(e.entity)
             .or_default()
             .push((OneShotReq::Emote(e.anim_id), e.seq));
     }
-    // This frame's **stage-2 base recomputes** — a state kit's anim id, which is never played
-    // ([`BaseAnimRecompute`]). Last wins: the reference makes the comparison per kit play, and two
-    // in one frame leave the second's verdict standing.
+    // Stage-2 base recomputes by unit, last wins: of two in a frame the second's verdict stands.
     let mut pending_recompute: bevy::ecs::entity::EntityHashMap<u16> = default();
     for r in recomputes.read() {
         pending_recompute.insert(r.entity, r.anim_id);
     }
-    // This frame's sheath requests, keyed by unit (a later request replaces an earlier — the
-    // client's last SetSheatheState call wins).
+    // Sheath requests by unit; the last SetSheatheState call wins.
     let mut pending_sheath: bevy::ecs::entity::EntityHashMap<SheathRequest> = default();
     for r in sheath_requests.read() {
         pending_sheath.insert(r.entity, *r);
     }
-    // The missing-clip resolver's DBC source (decision 0082): `None` for the brief window before
-    // `AnimationData.dbc` loads, in which every lookup below degrades to identity.
+    // `None` until `AnimationData.dbc` loads; every lookup then resolves to itself.
     let catalog = anim_data.as_deref().map(|d| &d.0);
-    // `WOW_ANIM_COST=1` — the memo-sizing counter (1370 item 9's bracket): counts the frame's
-    // RESTING rows, the shape an input-memo fast path would skip. Sizing only — no skip is
-    // taken here. (The EVENT scan is 1482's to gate now — a parked unflagged unit's tracks go
-    // unscanned — but the driver still arms clips for every parked rig: the wake pose must be
-    // the absolute-clock pose of the RIGHT clip, and only the state machine knows which clip
-    // that is. The memo remains the only safe skip shape for these rows.)
+    // `WOW_ANIM_COST=1` counts the frame's resting rows, the ones an input memo could skip; no skip
+    // is taken, as a parked rig's wake pose still needs the right clip armed.
     let anim_cost = anim_cost_enabled();
     let (mut cost_rows, mut cost_resting) = (0u32, 0u32);
     for (
@@ -481,17 +377,9 @@ pub(super) fn drive_animations(
         ),
     ) in &mut units
     {
-        // A mount child drives from its HOST's movement view (decision 0441) — same inputs the
-        // rider's own pass reads, so the mount plays exactly the locomotion the rider suppresses.
-        // A vanished host (teardown race) reads as stationary until the child despawns with it.
-        // The host also supplies the missing half of the mount's world scale (see the query docs).
-        //
-        // `ridden_by_self` only feeds the debug trace: while mounted, the animation the director is
-        // *looking at* is the mount child's (the rider is pinned to Mount 91), so a trace that
-        // followed `SelfPlayer` alone went blind on exactly the body in question — which is how a
-        // gallop cadence report had to be diagnosed from asset bytes instead of a run
-        // (decision 0906). It deliberately does NOT feed `is_self`: the sheath reconcile and the
-        // wire echoes below mean the player's OWN unit, and a mount is not it.
+        // A mount child drives from its host's movement view, so it plays the locomotion the
+        // rider suppresses; a vanished host reads as stationary. `ridden_by_self` feeds only the
+        // trace, never `is_self`: the sheath reconcile and wire echoes mean the player's own unit.
         let (
             spline,
             remote,
@@ -521,87 +409,52 @@ pub(super) fn drive_animations(
                 false,
             ),
         };
-        // The rendered world scale of the model playing these clips — the `0x5fe2f0` rate divisor's
-        // `|modelScale|` (decision 0903). A plain unit's transform already IS its world scale; a
-        // mount child's is its display column, which composes under the rider's.
+        // The `0x5fe2f0` rate divisor's `|modelScale|`: a mount child's display column composes
+        // under the rider's scale.
         let model_scale = transform.scale.x * host_scale;
         let traced = is_self || ridden_by_self;
-        // Which body a trace line is about — the rider's own, or the mount it is sitting on.
         let subject = if mount_body.is_some() { "mount " } else { "" };
         let walk = speeds.map_or(DEFAULT_WALK_SPEED, |s| s.0.walk);
-        // Dead ⇒ health 0 with a real max, **or** the dead-looking dynamic flag (`unit_reads_dead`
-        // — the reference's own `0x605f90`, decision 1022): feign death leaves health untouched and
-        // signals purely through `UNIT_DYNFLAG_DEAD`, and the reference runs it through this exact
-        // path — the flag's watcher `0x600440` calls `0x60ea30` (play Death) and the per-frame
-        // chain's top resolver `0x5fcff0` then claims and holds the corpse pose, the same pair the
-        // real death handler `0x625190` runs. So a hunter feigning collapses and lies there, for
-        // himself and for everyone watching, and stands back up when the flag clears.
-        // Absent health counts as ZERO: a create block omits zero fields, so an already-dead corpse
-        // streams in with no HEALTH at all — requiring an explicit `Some(0)` here is exactly the bug
-        // where corpses stood up on relog.
+        // Dead is zero health or `UNIT_DYNFLAG_DEAD` (`0x605f90`): the flag's watcher `0x600440`
+        // plays Death (`0x60ea30`) and `0x5fcff0` holds it, the pair the death handler `0x625190`
+        // runs, so a feign lies down and stands when the flag clears.
+        // Absent health reads as zero: a create block omits zero fields, so a corpse streams in
+        // with no HEALTH.
         let dead = store.is_some_and(|s| s.0.unit_reads_dead());
-        // Mounted (decision 0441): `UNIT_FIELD_MOUNTDISPLAYID` nonzero — the wire's one mounted
-        // signal. The rider's base pins to Mount(91) below, Specials/one-shot full-body routes are
-        // suppressed, and the sheath reconcile force-stows; the locomotion the selector would have
-        // picked plays on the MOUNT child entity instead (its own driver pass, fed the host's own
-        // movement view through `MountBody.host` — the `mount_hosts` fetch at the top of this
-        // loop). A mount child itself has no `ObjectStore`, so it can never read as mounted here.
+        // `UNIT_FIELD_MOUNTDISPLAYID` is the one mounted signal; a mount child has no store, so it
+        // never reads as mounted.
         let mount_display = store.map_or(0, |s| s.0.unit_mount_display_id());
         let mounted = mount_display != 0;
-        // The transition EDGE, consumed after the death override below ([`AnimDriver::mount_display`]
-        // carries the byte-cited why). Latched here, with the other per-frame edge bookkeeping, so
-        // a pass that returns early still consumes it: a unit that mounts and dies in the same
-        // breath must not have the arm fire late, over the death play that owns bone 0.
+        // Latched before the death override so an early return still consumes the edge: a unit
+        // that mounts and dies in one frame must not arm Mount over Death later.
         let mount_edge = std::mem::replace(&mut drv.mount_display, mount_display) != mount_display;
-        // First time we drive this unit (nothing chosen yet) — used to settle a corpse to its end pose.
+        // Nothing chosen yet: a corpse streamed in settles on its end pose.
         let first = drv.gait.is_none() && drv.mode == Mode::Gait;
         let mut mv = unify(movement, remote, spline, creature_swimming, move_modes);
-        // Stand state (decision 0080c): a unit without a controller-fed [`MovementState`] (remote
-        // players, creatures) poses from its `UNIT_FIELD_BYTES_1` stand-state byte — a seated
-        // remote player renders for free. Our own avatar's rides its `MovementState` (the
-        // controller overlays its in-flight request so the pose never waits on the echo).
+        // A unit without a controller poses from its `UNIT_FIELD_BYTES_1` stand-state byte; our own
+        // avatar's controller overlays its in-flight request.
         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`):
-        // no sit/sleep/kneel pose can hold in the saddle.
+        // No sit/sleep/kneel pose holds in the saddle (the standState leg's `[+0xdc]==0` gate,
+        // `0x5fd550`).
         if mounted {
             mv.stand_state = 0;
         }
-        // Stealth — the prowl pose ([`select::STEALTH_WALK`] / [`select::STEALTH_STAND`]): the CREEP
-        // vis flag off the unit's OWN descriptor, read every frame for self and remote alike, which
-        // is where the client reads it (`[[unit+0x110]+0x213] & 2` at select time). Never
-        // controller-fed, unlike the stand state — there is no client-side prediction of stealth, so
-        // the crouch lands with the server's aura. A mount child carries no store and reads `false`:
-        // right by construction, since the rider's body holds Mount(91) regardless and stealth and
-        // mounts are mutually exclusive anyway.
+        // The creep vis flag off the unit's own descriptor (`[[unit+0x110]+0x213] & 2`), never
+        // predicted: the crouch lands with the server's aura.
         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 (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
-        // unlatched landing is a full no-op: the gait keeps rolling — decision 0187).
+        // An arc's launch vertical speed splits a jump (the JumpStart/Jump bracket; jump
+        // `0x60e480`, land `0x602c60`) from a step-off fall, which has no bracket and keeps the
+        // gait frozen while `airborne_frozen` holds.
         let falling = mv.flags & move_flags::FALLING != 0;
         let was_falling = std::mem::replace(&mut drv.was_falling, falling);
-        // **The edge is the LAUNCH, not the FALLING bit** (decision 1137). The bit's rising edge is
-        // the arc's start only when the body was on the ground the frame before, and on broken
-        // ground it often is not: a run across a hillside micro-detaches for a frame or two, and a
-        // jump pressed in that window lands and relaunches inside a single frame, with FALLING set
-        // continuously across the seam. The bit never toggles, the sample never runs, and the arc
-        // inherits `jump_arc = false` from the detachment — so a real jump plays the step-off
-        // freeze and the body sails upward still running. Seven of the nineteen jumps in the
-        // director's hillside capture took exactly that path (`grounded=0 vy=-0.65`, then
-        // `vy=+7.96` the next frame).
-        //
-        // A launch is visible in the quantity itself: nothing but a jump drives vertical speed
-        // *upward* past the threshold. The mover's own arc bookkeeping already agrees — a
-        // same-frame land+relaunch is a new arc there ([`crate::player::Player::advance_airborne_arc`]).
+        // The arc starts at the launch, not only at FALLING's rising edge: on broken ground a jump
+        // can land and relaunch within one frame with FALLING set throughout.
         let prev_vertical = std::mem::replace(&mut drv.last_vertical_speed, mv.vertical_speed);
         let launched = mv.vertical_speed > JUMP_ARC_MIN_UP && prev_vertical <= JUMP_ARC_MIN_UP;
-        // The resting predicate, counted (never acted on — see the counter's note above): mode
-        // Gait with nothing in flight, nothing pending, grounded and motionless. A strict lower
-        // bound on what an input-memo would skip.
+        // Resting: Gait mode, nothing in flight or pending, grounded and still.
         if anim_cost {
             cost_rows += 1;
             if drv.mode == Mode::Gait
@@ -628,20 +481,14 @@ 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`, 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.
-        // Gates the gait slot's mid-air keep-current AND the deferred-cache consumer below
-        // (the `+0xd60` read sits downstream of the freeze: a parked clip never plays mid-air).
+        // The airborne freeze (`0x5fd8e8`): keep the current clip iff
+        // `FALLING && (FALLINGFAR || vz ≠ 0)`; a walk-off's first vz == 0 substep may re-pick. It
+        // also gates the deferred-cache consumer: a parked clip never plays mid-air.
         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`): 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`:
-        // no combat/cast); positive step = counterclockwise WoW yaw = turning left.
+        // A stationary unit easing its yaw reads as turning (`0x607ed0`), so it shuffles, and each
+        // return to Stand re-rolls the fidget. Gated like `0x5fce30`: no combat or cast. A positive
+        // step is counterclockwise, turning left.
         if let Some(step) = facing_step.filter(|_| !moving && !engaged && cast_hold.is_none()) {
             mv.flags |= if step.0 > 0.0 {
                 move_flags::TURN_LEFT
@@ -649,24 +496,17 @@ pub(super) fn drive_animations(
                 move_flags::TURN_RIGHT
             };
         }
-        // Whether a looping base arm this frame may ROLL its variation (the client's base-arm
-        // `variationIdx = −1`, decision 0123) or is forced to the head: decided from the state
-        // *before* this frame's transitions (the client tests the outgoing armed id).
-        // (0880 also gated this on a stun. That gate cited `0x5eb4f2`/`0x5ec219` as "the idle/fidget
-        // selectors bail on UNIT_FLAG_STUNNED" — re-read at the bytes, those two sites are
-        // `ToggleSheath 0x5eb480` and `CanLootNow 0x5ec110`, and NO site in the whole `0x40000`
-        // census touches animation selection. The stun does not quiet the fidget; the freeze does,
-        // by stopping the clock (decision 0889), so the invented gate is gone.)
+        // Whether a looping base arm may roll its variation (`variationIdx = −1`) or takes the
+        // head, decided from the outgoing armed id before this frame's transitions. A stun does
+        // not gate it: no `UNIT_FLAG_STUNNED` reader touches animation selection.
         let outgoing = drv.active_anim().unwrap_or(STAND);
         let relaxed = !select::arm_forces_head(engaged, cast_hold.is_some(), outgoing);
 
         wound_upkeep(entity, &mut drv, &mut player);
 
-        // Death overrides every state (a corpse doesn't transition); play Death and hold.
+        // Death overrides every state: play Death and hold.
         if dead {
             if drv.gait != Some(DEATH) {
-                // One line per collapse, naming WHICH death it is — a body lying down with full
-                // health is a feign, and without this the two are indistinguishable in a log.
                 debug!(
                     "death pose: unit {entity} arms Death ({DEATH}) — {}{}",
                     if store.is_some_and(|s| s.0.unit_is_dead()) {
@@ -679,8 +519,7 @@ pub(super) fn drive_animations(
                 if let Some(c) = find_resolved(anims, DEATH, catalog)
                     .or_else(|| find_resolved(anims, STAND, catalog))
                 {
-                    // A witnessed death rolls its variation like any one-shot (decision 0114); a
-                    // corpse that streamed in dead settles on the deterministic head instead.
+                    // A witnessed death rolls its variation; a streamed-in corpse takes the head.
                     let c = if first {
                         c
                     } else {
@@ -691,76 +530,41 @@ pub(super) fn drive_animations(
                     if c.looping {
                         active.repeat();
                     } else if first {
-                        active.seek_to(c.duration); // streamed in dead → settled corpse, not a replay
+                        active.seek_to(c.duration); // streamed in dead: settled, not replayed
                     }
                 }
-                // The death play arms bone 0 — a blended primary re-arm overwrites that bone's
-                // secondary slot (decision 0114, the shared-slot eviction): a FULL-BODY wound in
-                // flight is evicted; a masked wound rides the key-bone and decays out over the
-                // collapse via the upkeep above.
+                // A blended bone-0 arm overwrites bone 0's secondary slot: it evicts a full-body
+                // wound; a masked wound on the key bone decays out on its own.
                 if let Some(wd) = drv.wound.take_if(|wd| !wd.masked) {
                     player.stop(wd.node);
                 }
                 drv.mode = Mode::Gait;
                 drv.gait = Some(DEATH);
-                drv.deferred = None; // the death play is a normal arm — the cache clears
+                drv.deferred = None; // a normal arm clears the cache
             }
             continue;
         }
 
-        // **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
-        // seven-argument call differing in that one literal, and the difference is visible).
-        // Because that is an ordinary last-writer-wins play, it **displaces a full-body one-shot
-        // the transition catches mid-clip** — and our gait-slot mount pin (below) never could:
-        // `Mode::Swing` holds bone 0 until its clip ends, so the pin waited.
-        //
-        // That is exactly B203. The mount summon's cast-stage kit (1604/1607 → **54
-        // `SpellCastOmni`**) is armed at SPELL_GO, while the caster is still *unmounted*, so it
-        // takes the full-body route; the mount field then lands a beat later and, without this
-        // arm, the caster sat on the horse finishing a standing spellcast. The reference plays
-        // the same clip and then takes bone 0 straight back — which is why the director sees "no
-        // cast animation", only the poof.
-        //
-        // Deliberately NOT touched: the masked overlay. `0x607b44` names bone 0, the key bone is
-        // a different per-bone block, and op4's replace-notice fires only for the bone's own
-        // primary — so an upper-body clip rides the transition untouched. (While mounted every
-        // later one-shot takes the masked route anyway, and the reference's own re-force
-        // `0x5fe803`–`0x5fe816` re-pins 91 on every subsequent play; the gait pin renders that.)
+        // The mount transition arms bone 0's primary through op4 `0x7121a0`: the build `0x607b44`
+        // plays 91 Mount with a cross-fade, the teardown `0x607ce0` plays 0 Stand without one.
+        // Last writer wins, so it displaces a full-body one-shot mid-clip (the mount summon's
+        // SpellCastOmni, armed while still unmounted). The key-bone overlay rides it untouched;
+        // while mounted `0x5fe803`–`0x5fe816` re-pins 91 on every play, rendered by the gait pin.
         if mount_edge {
             if matches!(drv.mode, Mode::Swing { .. }) {
                 drv.mode = Mode::Gait;
             }
             if mounted {
-                // A FULL-BODY wound in flight is evicted by a **blended** primary re-arm — the
-                // same shared-slot eviction the death play does above (decision 0114): op4's
-                // cross-fade path snapshots the outgoing pose *into* the secondary slot
-                // (`rep movsd` at `0x7125d9`). Only the BUILD leg blends (`0x607b35 push 0x1`);
-                // the teardown's `crossFadeFlag = 0` jumps past that memcpy entirely
-                // (`0x71253e`–`0x712543`), so a dismount leaves the secondary alone — decision
-                // 0931. A masked wound rides the key bone and decays out on its own, either way.
+                // Only the build blends (`0x607b35 push 0x1`), and a blended arm snapshots into the
+                // secondary (`0x7125d9`), evicting a full-body wound; the teardown skips that copy
+                // (`0x71253e`–`0x712543`).
                 if let Some(wd) = drv.wound.take_if(|wd| !wd.masked) {
                     player.stop(wd.node);
                 }
             } else {
-                // **The teardown CUTS** (decision 0931 — the director's "the dismount looks like
-                // it's landing after a jump"). `0x607ce0`'s arm is
-                // `op4(bone −1, anim 0 Stand, variation −1, bias 0, rate 1.0, crossFade 0,
-                // PRIMARY)` at `0x607d1a`–`0x607d2b` — byte-for-byte the build leg's call with
-                // **one** literal different: `push 0x0` where `0x607b35` pushes `0x1`. So the
-                // saddle pose does not blend away, it is *gone* on the arm's first frame.
-                //
-                // Blending it away is what the crouch-and-recover was: Mount(91) splays and bends
-                // the legs, and easing that into Stand over the clip's blend time reads as a body
-                // absorbing an impact. There is no landing clip anywhere near this — the shape of
-                // the cross-fade WAS the landing.
-                //
-                // The gait re-pick below is the arm's own successor, `RecomputeBaseAnim(−1)` at
-                // `0x607d30`–`0x607d34` (`0x5fd9e0`: run the base chain `0x5fd8b0`, play the
-                // result through `0x5fe2f0` unless it comes back `0xD0`). It blends normally —
-                // which is right, because it now blends from **Stand**, not from the saddle.
+                // The teardown cuts to Stand: `0x607d1a`–`0x607d2b` pushes crossFade 0 where the
+                // build pushes 1. The gait re-pick that follows, `RecomputeBaseAnim(−1)` at
+                // `0x607d30` (`0x5fd9e0` → `0x5fd8b0`), blends normally, from Stand.
                 play::cut_loop(
                     &mut tr,
                     &mut player,
@@ -771,32 +575,16 @@ pub(super) fn drive_animations(
                     &mut drv.loop_window,
                 );
             }
-            // Force a fresh gait pick even when the selector's answer is unchanged: the id may
-            // still read `Stand` on both sides of a dismount, but the *node* holding bone 0 is
-            // the displaced one-shot's, and only a re-arm takes it back.
+            // Force a fresh pick even for an unchanged id: bone 0 may still hold the displaced
+            // one-shot's node.
             drv.gait = None;
             drv.deferred = None; // a normal arm clears the fast-path cache (`0x5fe48e`)
         }
 
-        // 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
-        // *kind* of target the character kneels at. Only B is read here, because
-        // [`crate::ui_loot::LootKneel`] already folds in A (it is false whenever the latch is
-        // cold). Keeping them apart is the correction 1477 makes to 1471: a fishing bobber arms
-        // the latch exactly like a chest does, and the reference still does not kneel at it —
-        // the difference is entirely B's `GAMEOBJECT_TYPE_ID == 17` test.
-        //
-        // **Remote.** The mirrored descriptor: `UNIT_FLAG_LOOTING` (0x400) set AND the
-        // `0x10000000` bit clear.
-        //
-        // Never mounted (the leg's `[+0xdc]==0` gate). Movement outranks by CHAIN POSITION, not an
-        // in-leg gate — the core ground selector claims first on any direction bit (`[9e8]&0xf`)
-        // — transcribed as the `ANY_MOVE` test here; a stationary *swimmer* with the trigger up
-        // kneels mid-tread, as the bytes order it (locomotion's swim block needs a direction
-        // bit too).
+        // The loot kneel: self reads `LootKneel`, the open-session latch (`0x6126b0`) folded with
+        // the target-class filter (`0x612710`, which refuses a fishing bobber); a remote reads
+        // `UNIT_FLAG_LOOTING` (0x400) set with `0x10000000` clear. Never mounted (`[+0xdc]==0`);
+        // any direction bit (`[9e8]&0xf`) outranks it, so a stationary swimmer kneels mid-tread.
         let looting = !mounted
             && mv.flags & move_flags::ANY_MOVE == 0
             && if is_self {
@@ -808,55 +596,33 @@ pub(super) fn drive_animations(
                 })
             };
 
-        // No Special claims a mounted rider (decision 0441): the jump/fall arc plays on the mount
-        // child (whose synced view carries the same flags), and poses were zeroed above.
+        // No Special claims a mounted rider: the jump arc plays on the mount child.
         let special = if mounted {
             None
         } else {
             current_special(&mv, drv.jump_arc)
         };
-        // 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).
+        // The `0x5fd8b0` chain calls loot before standState, after the airborne freeze: a looting
+        // unit kneels rather than sits, but still jumps.
         let special = special.filter(|s| !(looting && matches!(s, select::Special::Pose(_))));
 
-        // ── Sheath state (decision 0080). The unit's rendered sheath is the **client-side
-        // committed cache** (`drv.sheath_cur`, the client's `[+0xd40]`), not the raw descriptor
-        // byte: seeded from the byte at first sight (silently), re-adopted whenever the byte
-        // *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** — 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).
+        // ── Sheath state: the committed cache (`[+0xd40]`), not the descriptor byte, adopting the
+        // byte whenever it changes (`0x604c70`). Every SetSheatheState (`0x611cf0`) snaps except
+        // the manual toggle's ceremony, which carries the draw/stow 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) {
             drv.sheath_cur = Some(sheath_byte);
             drv.sheath_byte = Some(sheath_byte);
         }
-        // The one setter's queue ([`SheathRequest`] — the Z toggle, the attack-start auto-draw,
-        // the stand-state stow rider): idempotency refusal (the client's `newState == CUR`
-        // abort), commit, the local player's `CMSG_SETSHEATHED` volunteer, and — for the manual
-        // toggle alone — the ceremony: **per-arm masked overlays** (the client's per-slot plays,
-        // `0x60b770`): the mainhand's on the right-arm subtree, the offhand's on the left, each
-        // by that item's stow family (hip → HipSheath 90, back/shield → Sheath 89), composed
-        // over whatever the body is doing and never cancelled; [`VisualSheath`] pins the old
-        // weapon placement until the authored `$SHL`/`$SHR` event (~halfway — the hand at the
-        // stow point). A ceremony without playable clips degrades to the snap.
+        // The setter: a no-op when unchanged (`newState == CUR`), else commit, volunteer
+        // `CMSG_SETSHEATHED` for the local player, and for the manual toggle play the ceremony,
+        // per-arm masked overlays (`0x60b770`) by each item's stow family (hip 90, back 89).
         if let Some(req) = pending_sheath.get(&entity) {
             let cur = drv.sheath_cur.unwrap_or(0);
-            // 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
-            // under the seat pin, so the equivalent is refusing the draw at the setter — no
-            // commit, no volunteered CMSG (named deviation: same observable, earlier site).
+            // Deviation: a mounted draw is refused at the setter, because our rider track never
+            // replays the reference's per-play force-stow (`0x5fdf80`); the result is the same.
             if req.state != cur && !(mounted && req.state != 0) {
-                // The setter's own trace, the twin of the reconcile's below: between them every
-                // sheath transition names itself and its author, so "why is the weapon out"
-                // is one `RUST_LOG=benilla=debug` grep rather than a re-derivation of the
-                // 24-site policy from the symptom.
                 debug!(
                     "sheath: unit {entity} {cur} -> {} (request, ceremony {})",
                     req.state, req.ceremony
@@ -882,13 +648,8 @@ pub(super) fn drive_animations(
                 }
             }
         }
-        // Ceremony upkeep, per arm: move that arm's weapon when its clip crosses the authored
-        // `$SHL`/`$SHR` event (the hand-touches-weapon moment — the draw/stow ring fires there,
-        // `sound::sheathe`, since the sound can't ride the tags themselves: hip clips carry none),
-        // and when a *stow* clip finishes, run the client's **phase 2** — the on-anim-finish
-        // drawer `0x5fc920` @ `0x5fca8c`/`0x5fcaa1`. That deferred second movement is what makes a
-        // melee → ranged toggle read as "put the swords away, come back to neutral, *then* reach
-        // over the shoulder for the bow" instead of one blended swap.
+        // Ceremony upkeep: each arm's weapon moves at its clip's `$SHL`/`$SHR` event, and a
+        // finished stow runs phase 2, the on-finish draw (`0x5fc920` at `0x5fca8c`/`0x5fcaa1`).
         let sheath_now = drv.sheath_cur.unwrap_or(0);
         advance_sheath_ceremony(
             &mut commands,
@@ -902,68 +663,49 @@ pub(super) fn drive_animations(
             &mut sheath_swaps,
         );
 
-        // ── This frame's one-shot: a melee swing (decision 0073 — one per SMSG_ATTACKERSTATEUPDATE)
-        // or an anim-emote (decision 0081). A swing outranks an emote when both land (combat wins).
-        // Its destination is chosen **per play from the unit's live state** (decision 0087,
-        // `route_oneshot`): **masked** onto the SpineLow overlay (moving / seated / airborne-in-combat)
-        // — playing beside `mode`, the base track's legs untouched — or **full-body** on the base
-        // track (standing idle), replacing whatever the base was doing.
+        // ── This frame's one-shots, each routed per play from live state (`route_oneshot`): masked
+        // onto the SpineLow overlay beside `mode`, or full-body on the base track. A wound is a
+        // per-bone secondary that a blended arm on the same bone overwrites (op4 copies over
+        // `+0xc4..`), so plays are tracked per bone; a play on the other bone leaves it
+        // (`0x714260`).
         //
-        // The shared-slot eviction's inputs (decision 0114): a wound-flinch overlay is the client's
-        // per-bone SECONDARY, and a blended primary re-arm on the *same bone* overwrites that slot
-        // (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 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
-        // ([`play::BaseAnimLock`], decision 2096).
+        // The base-animation lock releases on the finished id before anything re-picks the base
+        // (`0x5fc9c6`), so completion and pre-emption both release it.
         drv.base_lock.release_finished(&player, anims, catalog);
 
         let pre_state = (drv.mode, drv.gait);
         let mut base_played = false;
         let mut masked_played = false;
         let mut played_oneshot: Option<u16> = None;
-        // The victim's cached creature template carries `DO_NOT_PLAY_WOUND_ANIM` (`type_flags`
-        // bit `0x8`) — the reference's `0x6125f0`, read at its two consumers below: the parry
-        // pick `0x60ec1f` and the wound flinch `0x60ea9f` (decision 2068). Keyed on the
-        // descriptor's `OBJECT_FIELD_ENTRY`, the way `0x60b160` keys the query record, and false
-        // on a template we have not received — `0x6125f0`'s own null leg.
+        // `DO_NOT_PLAY_WOUND_ANIM` (`type_flags` 0x8, `0x6125f0`) on the template keyed by
+        // `OBJECT_FIELD_ENTRY` (`0x60b160`); false when not received. Read by the parry
+        // (`0x60ec1f`) and the flinch (`0x60ea9f`).
         let no_wound_anim = store
             .and_then(|s| s.0.object_entry())
             .zip(names.as_deref())
             .and_then(|(entry, n)| n.creature_record(entry))
             .is_some_and(|r| r.type_flags & DO_NOT_PLAY_WOUND_ANIM != 0);
-        // Defense outranks a same-frame own swing/emote: the client's `$CPP` arm is the later
-        // PlayAnimation call in that (rare) frame, and the being-hit reaction is the one the
-        // player must read. Gated alive (`0x60ec00` checks IsDead / stand-state 7 before the LUT).
+        // Defense plays after a same-frame own swing or emote: the `$CPP` arm is the later call.
+        // Gated alive (`0x60ec00` checks IsDead and stand-state 7).
         let defense = pending_defense.get(&entity).and_then(|&vs| {
             if dead {
                 return None;
             }
-            // `DO_NOT_PLAY_WOUND_ANIM` takes the **parry** with the flinch (`0x60ec1f`, the bit's
-            // 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
-            // raises its shield, it just never parries.
+            // The flag refuses only the parry (victimState 3, `0x60ec1f`); dodge (30) and block
+            // (24) play straight from `0x624a90`/`0x624a74`, ungated.
             if vs == 3 && no_wound_anim {
                 return None;
             }
-            // The parry LUT `0x60ec00` reads the victim's mainhand through `GetWeapon(0, 0)`
-            // (1863), so a disarmed victim's parry finds no weapon and the client bails — no
-            // clip, which is this function's own empty-hand leg.
+            // The parry reads the mainhand through `GetWeapon(0, 0)`: a disarmed victim gets no
+            // clip.
             let id = defense_anim(vs, wielded.and_then(|w| w.armed_main()));
             if let Some(id) = id {
                 debug!("defense: unit {entity} anim {id} (victimState {vs})");
             }
             id
         });
-        // The frame's play calls, resolved to anim ids in [`PlaySeq`] call order; the defense
-        // reaction runs last (the client plays it from the deferred impact scan, later in the
-        // frame than any message handler — decision 0399's surviving arm).
+        // In `PlaySeq` order, defense last: the reference plays it from the deferred impact scan,
+        // after every message handler.
         let mut requests: Vec<u16> = pending
             .remove(&entity)
             .map(|mut v| {
@@ -972,11 +714,8 @@ pub(super) fn drive_animations(
                     .map(|(req, _)| match req {
                         OneShotReq::Swing(hit_info) => {
                             let w = wielded.copied().unwrap_or_default();
-                            // The COMBAT reading of the hand ([`Wielded::armed_main`]): the
-                            // reference's swing selector `0x6246a0` calls `GetWeapon(slot, 0)`,
-                            // so a disarmed attacker's weapon reads as absent and this lands on
-                            // AttackUnarmed(16) / AttackUnarmedOff(117) — with the weapon model
-                            // still in the fist (decision 1863).
+                            // `0x6246a0` calls `GetWeapon(slot, 0)`: a disarmed attacker swings
+                            // AttackUnarmed(16) / AttackUnarmedOff(117), weapon still in hand.
                             let id = if hit_info & 0x4 != 0 {
                                 swing_anim_off(w.armed_off())
                             } else {
@@ -991,25 +730,17 @@ pub(super) fn drive_animations(
             })
             .unwrap_or_default();
         requests.extend(defense);
-        // The play-time substitution ([`select::unarmed_special`], `0x5fe2f0`): a Special1H/2H
-        // asked for by a unit whose hands both read empty comes out as SpecialUnarmed(118). It
-        // lives at the PLAY seam in the reference, so it is applied to every request here rather
-        // than inside any one selector — a disarmed Eviscerate and a weaponless one are the same
-        // case to it (decision 1863).
+        // At the play seam (`0x5fe2f0`), Special1H/2H with both hands empty becomes
+        // SpecialUnarmed(118), for every request.
         {
             let w = wielded.copied().unwrap_or_default();
             for id in &mut requests {
                 *id = select::unarmed_special(*id, w.armed_main(), w.armed_off());
             }
         }
-        // The deferred-cache consumer (the client's `+0xd60` read at the base recompute,
-        // decision 0406): the moment no one-shot is live, the parked combat clip plays — the
-        // swing the Eviscerate spin deferred fires once the spin ends. A frame with fresh
-        // requests consumes it implicitly instead (a normal arm clears the cache; a fast-path
-        // 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 (decision 0868).
+        // The deferred cache (`+0xd60`): once no one-shot is live, the parked combat clip plays.
+        // Fresh requests supersede it (`0x5fe48e`/`0x5fe480`). Never mid-air: the read
+        // (`0x5fd392`, in `0x5fd360`) is past the airborne freeze, so the landing play clears it.
         if requests.is_empty()
             && drv.deferred.is_some()
             && !airborne_frozen
@@ -1018,19 +749,14 @@ pub(super) fn drive_animations(
             requests.extend(drv.deferred.take());
         }
         for id in requests {
-            // **The lock, first** — `0x5fe2f0`'s head guard returns before any routing, descriptor
-            // build or slot election, so it precedes the fast path and the dedup below and takes
-            // the deferral with it: "no routing, no arm, no deferral" ([`play::BaseAnimLock`]).
-            // This is what keeps a stunned victim knocked flat for the whole clip.
+            // The lock first: `0x5fe2f0`'s head guard returns before routing, the fast path and
+            // the dedup, so a locked unit gets no arm and no deferral.
             if drv.base_lock.refuses() {
                 continue;
             }
-            // 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.
-            // This is why the Eviscerate spin survives the auto-swings its cast triggers —
-            // sped up, never cut — and why consecutive swings don't hard-cut each other.
+            // The combat fast path (`0x5fe43c`–`0x5fe48b`): a combat clip over a live combat clip
+            // is not armed; the current clip's rate doubles (op6 2.0) and the request parks in
+            // `+0xd60`.
             if let Some((cur, node)) = live_oneshot(&drv, &player, &tr, anims, catalog) {
                 if select::is_combat_anim(cur) && select::is_combat_anim(id) {
                     if let Some(active) = player.animation_mut(node) {
@@ -1048,14 +774,10 @@ pub(super) fn drive_animations(
                     continue;
                 }
             }
-            // A normal arm clears the cache (the client's `0x5fe48e` writes −1 on every
-            // non-fast-path PlayAnimation).
+            // A normal arm clears the cache (`0x5fe48e` writes −1).
             drv.deferred = None;
-            // The arm-level same-id dedup (`0x5fdba0`, decision 0280): a requested id that
-            // already occupies its slot and is still playing is NOT re-armed — the mechanism
-            // that lets a looping eat/drink kit clip free-run across the server's ~5 s kit
-            // resends. Combat same-id re-plays never reach it (the fast-path above catches
-            // them first — the client's head-of-function order).
+            // Same-id dedup (`0x5fdba0`): an id still playing in its slot is not re-armed, so an
+            // eat/drink loop free-runs across the server's ~5 s kit resends.
             let overlay_live = drv.overlay.is_some_and(|ov| {
                 ov.id == id && player.animation(ov.node).is_some_and(|a| !a.is_finished())
             });
@@ -1072,29 +794,20 @@ pub(super) fn drive_animations(
                 }
                 continue;
             }
-            // 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.
+            // Mounted forces the masked route (`0x5fe2f0`'s mounted branch).
             let masked =
                 mounted || route_oneshot(id, mv.flags, mv.stand_state) == OneShotRoute::Masked;
-            // The play's two rolls (decisions 0114/0117): resolve to what this model has, then
-            // pick among that id's variations — the alternating swing arcs — and roll the replay
-            // budget (a clamp one-shot authored `(min,max)` plays R times before releasing).
+            // Resolve to a clip this model has, roll its variation and its replay budget (a clamp
+            // one-shot authored `(min,max)` plays R times).
             let picked =
                 find_resolved(anims, id, catalog).map(|h| roll_oneshot(anims, h, &mut rng));
             let upper = masked
                 .then(|| picked.and_then(|(c, r)| c.upper_node.map(|n| (n, r))))
                 .flatten();
             if let Some((node, repeat)) = upper {
-                // Masked route: the SpineLow overlay, beside `mode`. The base machine runs untouched.
-                // The re-arm is **blended** (op4 `blendFlag = 1`, decision 0878): whatever held the
-                // key-bone retires into the fade slot and this clip rises over its own blendTime
-                // (`0x7125f2` — the INCOMING sequence's `M2Sequence+0x20`), so a masked swing never
-                // 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`).
+                // Masked: a blended key-bone re-arm (op4 `blendFlag = 1`) over the incoming clip's
+                // own blendTime (`0x7125f2`, `M2Sequence+0x20`). The full-body route below leaves
+                // the key bone as it is (`0x5fe930`).
                 retire_overlay(
                     &mut drv,
                     &mut player,
@@ -1102,9 +815,9 @@ pub(super) fn drive_animations(
                 );
                 let active = player.play(node);
                 active.replay();
-                active.set_repeat(repeat); // always set — a reused node never keeps a stale count
-                active.set_speed(1.0); // nor a stale rate (a prior whiff slow-down, decision 0279)
-                active.set_weight(0.0); // the fade upkeep raises it from λ = 1 this same frame
+                active.set_repeat(repeat); // a reused node keeps no stale count
+                active.set_speed(1.0); // nor a stale whiff slow-down
+                active.set_weight(0.0); // the fade upkeep raises it this same frame
                 drv.overlay = Some(Overlay {
                     node,
                     id,
@@ -1113,19 +826,12 @@ pub(super) fn drive_animations(
                 masked_played = true;
                 played_oneshot = Some(id);
             } else {
-                // 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 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
-                // [`leave_special`]'s (decision 0503).
+                // Full-body, or a model with no key bone (the −1 sentinel arms bone 0): the clip
+                // replaces the base on bone 0 even over a Special, last writer wins (`0x5fe6c8`).
+                // An airborne arc's own clip freezes first, op4's pose-snapshot decay.
                 if let Some(sp) =
                     special.filter(|sp| matches!(sp, select::Special::Jump | select::Special::Fall))
                 {
-                    // …the ARC's clip, not merely whatever bone 0 holds ([`holds_own_clip`]) —
-                    // the freeze's missing predicate, at its second site (decision 2098).
                     if let Some(active) = tr
                         .get_main_animation()
                         .filter(|&n| holds_own_clip(anims, catalog, sp, n))
@@ -1152,13 +858,10 @@ pub(super) fn drive_animations(
             }
         }
 
-        // The whiff slow-down (decision 0279, `0x712910`): a miss/dodge/evade drops the attacker's
-        // in-flight swing to HALF speed for its remainder — a slowed follow-through (the verified
-        // 0.5 rate write), never a cut. The client writes bone 0's rate blindly; benilla scopes it
-        // to the swing's own node (masked overlay or full-body main), so a moving attacker's gait
-        // keeps its pace — a deliberate deviation, named in 0279. `Mode::Swing` holds ANY
-        // full-body one-shot (a spell kit's Special1H rides it too), so the base arm re-checks
-        // the id — a whiffing auto-attack must not drag a concurrent special to half speed.
+        // The whiff slow-down (`0x712910`): a miss, dodge or evade plays the rest of the swing at
+        // 0.5. Deviation: the reference writes bone 0's rate blindly; we scope it to the swing's
+        // own node, because a moving attacker's gait would otherwise slow too. The id is
+        // re-checked, as `Mode::Swing` also holds non-swing one-shots.
         if pending_slow.contains(&entity) {
             let node = match drv.overlay {
                 Some(ov) if is_swing_id(ov.id) => Some(ov.node),
@@ -1172,42 +875,19 @@ pub(super) fn drive_animations(
             }
         }
 
-        // A Special EDGE is a play (the jump/pose entry, the FALLINGFAR latch's Fall, the land
-        // pick — each a normal PlayAnimation), and every normal arm clears the deferred-combat
-        // cache (the client's `0x5fe48e`): a swing parked behind the spin dies when a jump cuts
-        // the spin. The *level* must not clear (decision 0864 corrects the old per-frame kill):
-        // mid-air the airborne-freeze issues no plays, so a fast-path park made mid-arc
-        // survives to its clip's end, exactly like the ref.
+        // A Special edge is a normal play, so it clears the deferred cache (`0x5fe48e`); the level
+        // does not, as the airborne freeze issues no plays mid-arc.
         let special_edge = special != drv.last_special;
         drv.last_special = special;
         if special_edge {
             drv.deferred = None;
         }
-        // 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
-        // completion callback re-arms the same id with `variationIdx = −1`: a fresh weighted,
-        // MEMORYLESS pick with a fresh window. One id's weighted walk is what alternates a
-        // gryphon's flap/glide (freq 26214/6553) and strings a five-part /dance together; a
-        // single-variation loop just restarts — the wrap it was already playing. Units always
-        // opt in (the client's `model+0x70` callback — every CGUnit controller installs it;
-        // the callback-less map doodads, which loop one variation forever, are `doodad_anim`'s
-        // separate concern). A combat/cast re-arm keeps the deterministic head, like any base
-        // arm. The carried rate keeps the gait's scaling; the per-frame sync re-syncs it anyway.
-        //
-        // **In the GAIT slot the completion is a re-SELECTION, not a re-arm** (decision 1655).
-        // The client's callback is `RecomputeBaseAnim(−1)` — `0x5fc3f0`'s jump-table row
-        // `0x5fc844` is literally `push -1; call 0x5fd9e0`, which runs the whole `0x5fd8b0`
-        // selector chain. For Fly and /dance the chain hands back the id it was already playing,
-        // so a same-id re-arm and a re-selection are indistinguishable and this code read as
-        // right for two years. For the turn-shuffle they are the difference between stepping once
-        // and shuffling for ever: the shuffle's window is the ONLY thing that ends it (the
-        // per-frame tail refuses to — see [`select::SHUFFLE_LEFT`] and `mode`'s hold), so if the
-        // completion re-armed 11 the vendor would never stop. Clearing the target IS the
-        // re-selection — `mode::run` picks fresh a few lines below, rolling the variation exactly
-        // as this arm would have. Outside the gait slot (a Special loop) the id is not the
-        // chain's to choose, so the same-id re-arm stands.
+        // Looping-variation advance (`0x719370`, the unit's `model+0x70` callback): when the main
+        // node completes its `R` passes, a fresh weighted pick with a fresh window follows (a
+        // gryphon's flap/glide, a multi-part /dance). In the gait slot the callback is
+        // `RecomputeBaseAnim(−1)` (`0x5fc3f0` row `0x5fc844` → `0x5fd9e0`), a re-selection:
+        // clearing the target lets `mode::run` re-pick, which is what ends a turn-shuffle. A
+        // Special loop re-arms its id.
         if let Some((node, budget)) = drv.loop_window {
             if tr.get_main_animation() == Some(node)
                 && player
@@ -1238,22 +918,11 @@ pub(super) fn drive_animations(
                 }
             }
         }
-        // ── The **stage-2 base recompute** (`0x60f389`–`0x60f399`, decision 2085): a state kit
-        // that names an animation compares it against the id the unit is already playing
-        // (`0x5fdb50` — the upper-body key bone if it holds one, else bone 0) and, on a
-        // difference, runs `0x5fd9e0(unit, -1)`. It never plays the id, and on a match it does
-        // nothing at all.
-        //
-        // It runs HERE, after this frame's one-shot arms, because that ordering is the whole
-        // observable effect: the impact kit (stage 1) plays first and the state kit (stage 2)
-        // then cuts it. Charge (22911) is the case that names itself — `Knockdown`(121) from kit
-        // 348, cut by kit 349's `Stun`(14) because 121 ≠ 14.
-        //
-        // Expressed as the re-selection, not a re-arm: clearing the gait target IS the recompute
-        // (decision 1655), and dropping `Mode::Swing` is what ends a one-shot. **Named residual:**
-        // a unit inside a Special (a pose, an airborne arc) is left alone — the reference's
-        // recompute re-enters the selector chain, which would land back in the same state, and
-        // forcing `Mode::Gait` here would replay the pose's enter clip instead.
+        // ── Stage-2 base recompute (`0x60f389`–`0x60f399`): a state kit's id that differs from
+        // the one playing (`0x5fdb50`: key bone, else bone 0) runs `0x5fd9e0(unit, -1)`; it never
+        // plays the id. It must run after this frame's one-shot arms, so the state kit cuts the
+        // impact kit (Charge 22911: Knockdown 121, then Stun 14). A unit inside a Special is left
+        // alone: the recompute would land in the same state, and forcing Gait replays its entry.
         if let Some(&want) = pending_recompute.get(&entity) {
             let armed = drv.overlay.map(|ov| ov.id).or_else(|| {
                 tr.get_main_animation()
@@ -1267,10 +936,7 @@ pub(super) fn drive_animations(
             }
         }
 
-        // ── **The mode machine** — the base track's whole decision, lifted into [`mode`]
-        // (decision 0933). It is the one phase of this pass with a clean input boundary: a fixed
-        // set of already-computed facts in, the driver + player + transitions out, and none of
-        // this loop's frame-local flags touched.
+        // ── The mode machine: the base track's decision.
         mode::run(
             mode::Frame {
                 entity,
@@ -1300,45 +966,26 @@ pub(super) fn drive_animations(
             &mut rng,
         );
 
-        // ── The base slot's **playback rate**, written once per frame over whatever the mode
-        // machine settled on — the client's rate write sits OUTSIDE the selector (`0x5fe2f0`), so
-        // it is not the gait's private business (decision 0906). The landing is why it matters:
-        // JumpLandRun 187 resolves to **Run(5)** on every creature model's baked lookup, so a
-        // mount's or a travel form's land clip is its own gallop cycle and must be rate-scaled
-        // like any other locomotion — at the arm's literal 1× it ran ~35% slow for the clip's
-        // whole 0.8 s. It also records the result in `gait_rate` — the number the hover card and
-        // the trace's `rate=` read (decision 0903) — so those stay honest in every mode too. See
-        // [`play::sync_base_rate`].
+        // ── The base slot's playback rate, written over whatever the mode machine settled on: the
+        // rate write sits outside the selector (`0x5fe2f0`). JumpLandRun 187 resolves to Run 5 on
+        // creature models, so a mount's landing is rate-scaled like any locomotion.
         play::sync_base_rate(&mut drv, &tr, &mut player, anims, mv.speed, model_scale);
 
-        // ── Masked one-shot completion — the **fade-to-rest** (decision 0878, correcting 0087 (c)):
-        // a finished overlay is NOT stopped. The client latches the completion in its per-frame
-        // model advance (`0x719370`) and delivers a deferred event the same frame to
-        // `CGUnit::OnAnimationFinished 0x5fc920`, which disarms the key-bone through op4
-        // `param_3 = -1` — snapshotting the clip's **held final frame** into the bone's secondary
-        // slot and cross-fading it back onto the inherited base over a fixed 150 ms. So the torso's
-        // return is a blend out of the follow-through, never the one-frame cut this used to do
-        // (the director's "the end of the cast is cut off and it instantly snaps back"). A looping
-        // cast-hold overlay never completes — the hold block below owns its release.
+        // ── Masked one-shot completion: a finished overlay is not stopped but faded to rest, its
+        // held final frame cross-fading onto the base over 150 ms (`0x719370` → `0x5fc920`).
         if let Some(ov) = drv.overlay {
             let done = if ov.looping {
                 false // a cast-hold loop: the hold block below owns its release
             } else if find_resolved(anims, ov.id, catalog).is_some_and(|c| c.looping) {
-                // A hold-less overlay whose CLIP is authored looping (a pushed kit's seated
-                // eat/drink gesture) has no natural end — release it when the body is claimed by
-                // MOVEMENT. INTERIM (decision 0280): the client's exact release chain for this case
-                // is unpinned; supersede-by-a-later-play already evicts above. A **Special** no
-                // longer counts (decision 0878): a jump is a bone-0 play, and bone-0 plays never
-                // touch the key-bone slot — cutting the torso on takeoff was the same defect the
-                // fade above fixes at the other end.
+                // A hold-less looping clip (a kit's seated eat/drink) releases on movement; the
+                // reference's release for this case is untraced. A Special does not release it:
+                // a jump is a bone-0 play and leaves the key bone alone.
                 moving
             } else {
                 player.animation(ov.node).is_none_or(|a| a.is_finished())
             };
             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 (`0x7123af`).
+                // Freeze on the final frame: the snapshot clamps to `seq.end` (`0x7123af`).
                 if let Some(a) = player.animation_mut(ov.node) {
                     a.set_speed(0.0);
                 }
@@ -1346,18 +993,10 @@ pub(super) fn drive_animations(
             }
         }
 
-        // ── The committed-move cast hold (decision 0107): a casting/channeling unit that
-        // translates or swims loops the hold clip on its torso over the gait — the masked route a
-        // moving caster falls through to (the stationary case pinned the gait slot above; the
-        // split is the same `[9e8] & 0x20000f` gate, [`move_flags::CAST_PIN_MOVE`] — a merely
-        // TURNING caster stays pinned there, decision 0491). A
-        // masked one-shot in the slot (a swing over the run) wins while it plays; the hold
-        // re-takes the subtree the frame after it finishes (the client's last-writer-wins slot).
-        // Its start is a play like any other, so the sheath reconcile below sees it (`hold_played`).
-        // A **Special no longer cancels it** (decision 0878): jumping mid-cast is a bone-0 play
-        // (JumpStart takes the legs) and the client's key-bone slot is untouched by it —
-        // `0x5fe912` routes a locomotion request straight to bone 0 when the key-bone is armed.
-        // Dropping the hold on takeoff was exactly the director's "jump-running cuts the cast".
+        // ── The moving cast hold: a caster that translates or swims (`[9e8] & 0x20000f`) loops the
+        // hold clip on its torso; a merely turning one stays pinned in the gait slot. A masked
+        // one-shot wins while it plays. A jump does not cancel it: `0x5fe912` sends locomotion to
+        // bone 0 while the key bone is armed.
         let mut hold_played: Option<u16> = None;
         let masked_hold = cast_hold
             .filter(|_| mv.flags & move_flags::CAST_PIN_MOVE != 0)
@@ -1371,14 +1010,12 @@ pub(super) fn drive_animations(
             (Some((id, node, blend)), prior)
                 if prior.is_none_or(|ov| ov.looping && ov.id != id) =>
             {
-                // Free slot, or a stale hold loop (the channel switched spells): (re)take it — a
-                // blended key-bone re-arm like any other (decision 0878), so the outgoing pose
-                // retires under the hold's own blendTime instead of vanishing.
+                // Free slot or a stale hold loop: a blended key-bone re-arm.
                 retire_overlay(&mut drv, &mut player, blend);
                 let active = player.play(node);
                 active.replay();
                 active.repeat();
-                active.set_weight(0.0); // the fade upkeep raises it from λ = 1 this same frame
+                active.set_weight(0.0); // the fade upkeep raises it this same frame
                 drv.overlay = Some(Overlay {
                     node,
                     id,
@@ -1387,34 +1024,19 @@ pub(super) fn drive_animations(
                 hold_played = Some(id);
             }
             (None, Some(ov)) if ov.looping => {
-                // The hold ended, or the unit stopped — release the subtree (the standing pin or
-                // the gait takes over). A looping clip never completes, so the client's
-                // completion-driven release never fires for it and its true release chain is
-                // still unpinned (0107/0280 INTERIM); it borrows the verified fade-to-rest shape
-                // rather than snapping, which is right either way.
+                // The hold ended or the unit stopped: fade to rest. The reference's release of a
+                // looping hold is untraced.
                 retire_overlay(&mut drv, &mut player, ONESHOT_RELEASE_FADE);
             }
             _ => {}
         }
-        // The key-bone cross-fade's advance, last — after every arm/release this frame, so the
-        // weights land on the slot's settled state (the client's kernel likewise runs λ after the
-        // frame's PlayAnimation calls).
+        // The cross-fade advances last, after every arm and release, as the reference's kernel
+        // runs λ after the frame's PlayAnimation calls.
         overlay_fade_upkeep(&mut drv, &mut player, dt);
 
-        // The anim half of the `WOW_MOVE_TRACE` debug trace ([`benilla_assets::trace`]): one line per
-        // frame the SELF unit's settled anim state *changes* — mode, gait, Special, flags, the
-        // rate-driving speed, and **both slots** — interleaved with the mover's `move` lines on the
-        // same clock, so a feel report ("the char's frames snap on landing") pins which layer moved
-        // and when. It runs HERE, after every arm/release/fade this frame, so `upper` is the
-        // settled key-bone state: without it a torso report ("the cast got cut") could not be told
-        // from a base one at all (decision 0878). `+fade` marks the 150 ms fade-to-rest running —
-        // a boolean, not a countdown, so a fade doesn't spam a line per frame.
-        //
-        // `base=` is the **resolved** clip the full-body slot actually holds — not the id the
-        // selector *asked* for, which `gait=`/`mode=` already carry. A cadence report ("the run
-        // goes slow when I land") is unreadable without it: the request was JumpLandRun 187, the
-        // clip playing was Run 5, and `rate=` was the wrong number for exactly that clip
-        // (decision 0906). `?` = the slot holds a node this model has no clip record for.
+        // The anim half of the `WOW_MOVE_TRACE` trace: one line whenever the traced unit's settled
+        // state changes, both slots included. `base=` is the resolved clip bone 0 holds (`?` for a
+        // node with no clip record); `+fade` marks a fade running.
         if traced && benilla_assets::trace::enabled() {
             let base = tr
                 .get_main_animation()
@@ -1428,9 +1050,6 @@ pub(super) fn drive_animations(
                 special,
                 mv.flags,
                 mv.speed,
-                // The rate's new input and its result (decision 0903): `speed` alone stopped
-                // predicting the gait's playback the moment the model scale joined the divisor,
-                // so a "the gait looks wrong" trace carrying only speed could no longer answer it.
                 model_scale,
                 drv.gait_rate,
                 drv.overlay.map(|ov| ov.id),
@@ -1448,50 +1067,24 @@ pub(super) fn drive_animations(
 
         let masked_played = masked_played || hold_played.is_some();
 
-        // A mode/gait change is a **proxy** for the mode machine's plays, and the base-anim lock
-        // is the one state where the proxy is wrong for longer than the single frame its own doc
-        // allows: while the lock refuses, the machine still walks its brackets — Gait →
-        // Entering(Jump) → Looping(Jump) → Land — with every play declined, so a change there
-        // means nothing was armed at all. Claiming otherwise evicted the victim's flinch off the
-        // key-bone and latched the weapon trail's edge (2076) on a play that never happened
-        // (decision 2098). Only the PROXY is gated: an arm that reached the player directly says
-        // so on its own.
+        // A mode or gait change stands in for the mode machine's plays, except under the base-anim
+        // lock, where the machine walks its brackets with every play refused.
         let base_played =
             base_played || ((drv.mode, drv.gait) != pre_state && !drv.base_lock.refuses());
-        // The weapon-trail latch's edge (decision 2076) — `0x5fe2f0` is the image's single
-        // animation entry point, so ANY start consumes the arm, the mode machine's gait plays
-        // included. Written every pass (never OR'd) so it is exactly this frame's.
+        // The weapon-trail latch's edge: `0x5fe2f0` is the single animation entry point, so any
+        // start counts. Written every pass, so it is this frame's alone.
         drv.started_anim = masked_played || base_played;
         wound_evict(entity, &mut drv, &mut player, masked_played, base_played);
 
         if let Some(&edge) = pending_wound.get(&entity) {
-            // Both edges pick the wound id by severity + the victim's engagement (decision
-            // 0111's `0x60ea70`); a spell edge is the client's `severity = 0` call (decision
-            // 2058), so it is CombatWound/StandWound by engagement and never the kit's own id.
+            // The id by severity and engagement (`0x60ea70`); a spell edge is severity 0.
             let id = match edge {
                 WoundEdge::Melee(hit_info) => select::wound_anim(hit_info, engaged),
                 WoundEdge::Spell => select::wound_anim(0, engaged),
             };
-            // The trigger's entry gates, in the reference's own order inside `0x60ea70`:
-            //
-            // 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). 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` (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.
+            // The entry gates in `0x60ea70`'s order: `DO_NOT_PLAY_WOUND_ANIM` (`0x60ea9f`), which
+            // gates the animation only (the blood spurt, `0x624530` → `0x625010`, still plays);
+            // then any CharProc-11 rate node (`0x60eaac`–`0x60eac8`), by presence, not rate.
             let refusal = if no_wound_anim {
                 Some("the template carries DO_NOT_PLAY_WOUND_ANIM")
             } else if aura_nodes.is_some_and(|n| n.head_anim_rate().is_some()) {
@@ -1521,45 +1114,15 @@ pub(super) fn drive_animations(
             }
         }
 
-        // ── The per-animation sheath reconcile (decision 0080 structure 3 — the client's
-        // `0x5fdf80`, run after every animation pick). The playing clip's `AnimationData.dbc`
-        // WeaponFlags + engagement force the state, data-driven — swimming/looting/casting stow,
-        // punching stows (fists need empty hands), armed attacks and the Ready idles draw — and
-        // a remote unit with no force pulls back to the server byte. Every force is a SNAP; the
-        // local player's force volunteers `CMSG_SETSHEATHED` (`bFireEvent = 1`), which the
-        // server echoes into the descriptor for observers. This is why a vendor gossip stows:
-        // the talk emote's flags, not a vendor wire (0080's resolved mystery) — future systems
-        // (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 `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.) 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
-        // carrying WeaponFlags `0x10` still stows. So this frame's routed one-shot id (either route)
-        // takes precedence for the reconcile; absent one, the base track's playing id is tested.
-        // And it must see **only plays** (the same byte-fact's other half): `PlayAnimation` is the
-        // reconcile's *sole* trigger, so a frame where nothing played keeps the committed state
-        // untouched. Re-running it every frame against the base track was the caster staff bug: a
-        // masked cast hold stows on its retake play, then the very next frame the base gait
-        // (flags-less Stand/Run) + the engaged/server-byte re-assert yanked the weapon back out —
-        // the client instead holds the stow across the base loop's silent wraps until something
-        // actually plays. The server-byte adopt above needs no play, exactly like the client's
-        // field-change watcher (`0x604c70`).
-        // …and, beyond plays: a mounted unit whose committed state reads drawn anyway (the
-        // descriptor byte-adopt above is the one write the setter gate can't refuse) re-arms
-        // the reconcile directly — the client's recompute would run on the composite's next
-        // mount-gait play, a beat our silent rider track never gets. Forces once (the mounted
-        // branch yields 0, cur becomes 0, the re-arm goes quiet) — no every-frame oscillation
-        // (the caster-staff trap below).
+        // ── The sheath reconcile (`0x5fdf80`, inside every PlayAnimation): the played clip's
+        // `AnimationData.dbc` WeaponFlags and engagement force a snap, and a remote unit with no
+        // force returns to the server byte; the local player volunteers `CMSG_SETSHEATHED`.
+        // It tests the requested id, not the model's substitute: the arm descriptor that
+        // `0x5fdb50` reads carries the id asked for (`0x5fde80`, stored at `+0xf8` by `0x71252f`),
+        // so a model lacking the clip still stows by the requested row.
+        // It runs on plays only, this frame's one-shot first: re-running it on a silent frame
+        // would undo a masked stow against the base gait. A mounted unit still drawn (the byte
+        // adopt bypasses the setter) forces once, as our rider track never plays.
         if played_oneshot.is_some()
             || hold_played.is_some()
             || base_played
@@ -1574,15 +1137,11 @@ 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**: 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
-                // stated directly: while a ranged shot's precast hold is live, a reconcile
-                // stow resolves to the drawn-ranged state instead. (Named deviation: the real
-                // *remote* thrower's wind-up ends CUR=0 until its GO — a derived, unobserved
-                // corollary; we keep every caster at 2, the observable the director verified.)
+                // The reference brackets every ranged kit play with ranged snaps (`0x60f34c`
+                // before, `SetSheatheState(2,1,1)` after), so ReadyThrown 108's stow (outside the
+                // `0x5fe180` exempt set) never renders; a live ranged hold resolves a stow to 2.
+                // That call order implies a remote thrower's wind-up reads 0 until its GO, which
+                // is untraced; every caster here stays at 2.
                 let forced = if forced != 2 && cast_hold.is_some_and(|h| h.ranged) {
                     2
                 } else {
@@ -1602,29 +1161,17 @@ pub(super) fn drive_animations(
                 }
             }
         }
-        // Leaving the ranged sheath stance un-nocks (the client's `0x60fc72` un-nock, gated
-        // `[+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.
+        // Leaving sheath state 2 by any path un-nocks and drops the ammo (`0x60fc72`, gated
+        // `[+0xd40] != 2`) until the next `SMSG_SPELL_START`.
         if sheath_frame_start == Some(2) && drv.sheath_cur != Some(2) {
             commands
                 .entity(entity)
                 .remove::<(super::NockedAmmo, super::NockLatch)>();
         }
-        // …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.
-        // `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** —
-        // they take arm 1, which recomputes only. So the mask is the four translation bits plus
-        // SWIMMING, never the turn bits: [`move_flags::ANY_MOVE`] is exactly the former, and this
-        // is the one place that needs the swim bit with it.
-        //
-        // 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 (`[+0xd40]` has no
-        // movement-path writer: only the ctor's `0x5fafa0` and `0x611cf0` write it).
+        // Translating or swimming un-nocks too, keeping the ammo and the draw: `0x60e480` arm 0
+        // (`0x60e4ac call 0x60f530`) runs on MSG_MOVE_START_{FORWARD, BACKWARD, STRAFE_LEFT,
+        // STRAFE_RIGHT, SWIM} (181/182/184/185/202); turning and stopping do not. A level test
+        // matches the start edge, since only the Load clips' `$BWP` re-latches.
         if mv.flags & (move_flags::ANY_MOVE | move_flags::SWIMMING) != 0 && nock_latched {
             commands.entity(entity).remove::<super::NockLatch>();
         }
@@ -1632,14 +1179,14 @@ pub(super) fn drive_animations(
     if anim_cost && cost_rows > 0 {
         use std::sync::atomic::{AtomicU32, Ordering};
         static FRAME: AtomicU32 = AtomicU32::new(0);
-        // Once a second at 60 fps, not per frame — the counter is a sizing read, not a trace.
+        // About once a second at 60 fps.
         if FRAME.fetch_add(1, Ordering::Relaxed).is_multiple_of(64) {
             eprintln!("[anim-cost] rows={cost_rows} resting={cost_resting}");
         }
     }
 }
 
-/// `WOW_ANIM_COST=1` — arms the memo-sizing counter above. Read once, the meter posture.
+/// `WOW_ANIM_COST=1` arms the resting-row counter; read once.
 fn anim_cost_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var("WOW_ANIM_COST").as_deref() == Ok("1"))
diff --git a/crates/benilla-app/src/creature_anim/driver/grip.rs b/crates/benilla-app/src/creature_anim/driver/grip.rs
index ee3689cf..314356ab 100644
--- a/crates/benilla-app/src/creature_anim/driver/grip.rs
+++ b/crates/benilla-app/src/creature_anim/driver/grip.rs
@@ -1,30 +1,24 @@
-//! The per-hand weapon-grip finger overlay ([`drive_hand_grip`]) — split out of [`super`] as its
-//! own concern; re-exported by [`super`] so `driver::drive_hand_grip` keeps working unchanged.
+//! The per-hand weapon-grip finger overlay.
 
 use benilla_assets::ModelAnimations;
 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 (`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
-/// edge and stops on closed→open, so it rides gait changes untouched (like the sheath/one-shot overlays).
-/// Runs after [`super::drive_animations`], re-asserting over whatever the base machine set this frame.
+/// Curls a hand's fingers (`HandsClosed`, on the finger-mask nodes over the gait) while a weapon
+/// occupies its attach point, as `CloseHand 0x479660` does. Runs after [`super::drive_animations`].
 pub(in super::super) fn drive_hand_grip(
     mut units: Query<(&HandGrip, &ModelAnimations, &mut AnimationPlayer)>,
 ) {
     for (grip, anims, mut player) in &mut units {
         for (hand, want) in [(0usize, grip.right), (1, grip.left)] {
             let Some(node) = anims.hand_close[hand] else {
-                continue; // this model can't grip with this hand (no finger key-bones / no HandsClosed)
+                continue; // no finger key-bones or no HandsClosed
             };
             match (want, player.animation(node).is_some()) {
                 (true, false) => {
                     let active = player.play(node);
-                    active.repeat(); // a single-key clamp pose — hold it, don't let it "finish"
+                    active.repeat(); // a single-key pose: repeat so it never finishes
                     active.set_weight(HAND_GRIP_WEIGHT);
                 }
                 (false, true) => {
diff --git a/crates/benilla-app/src/creature_anim/driver/mode.rs b/crates/benilla-app/src/creature_anim/driver/mode.rs
index e35210ed..0c274a3c 100644
--- a/crates/benilla-app/src/creature_anim/driver/mode.rs
+++ b/crates/benilla-app/src/creature_anim/driver/mode.rs
@@ -1,16 +1,5 @@
-//! The **mode machine** — the `match` over [`AnimDriver::mode`] that decides what the base track
-//! (bone 0) plays this frame, and the largest single phase of [`super::drive_animations`]'s
-//! per-unit pass.
-//!
-//! It is the one phase with a clean input boundary, which is why it is the one that lifted out:
-//! it reads a fixed set of already-computed per-frame facts ([`Frame`]) and writes only the
-//! driver, the animation player and the transition set. In particular it touches **none** of the
-//! frame-local flags the rest of the pass threads through itself (`base_played`, `masked_played`,
-//! `played_oneshot`, `hold_played`, `sheath_frame_start`) — the seam is real, not just a line
-//! count. The phases either side of it are not separable that way today; see decision 0933.
-//!
-//! The five modes and their transitions are documented on [`super::select::Mode`]; this file is
-//! the executor, not the law.
+//! The mode machine: what the base track (bone 0) plays this frame. It reads only [`Frame`], none
+//! of the pass's frame-local flags, and writes the driver, the player and the transitions.
 
 use benilla_assets::ModelAnimations;
 use benilla_formats::AnimDataCatalog;
@@ -28,9 +17,7 @@ use super::super::{find_resolved, move_flags, AnimDriver, CastHold, MovementStat
 use super::play::{enter_special, leave_special, oneshot_finished, play, play_clip, roll_loop};
 use super::transplant_up;
 
-/// Everything the mode machine reads about this unit this frame — the facts
-/// [`super::drive_animations`]'s prologue has already computed. All `Copy`, so the machine
-/// destructures it back into the same names the code was written against.
+/// The per-frame facts the mode machine reads, computed by [`super::drive_animations`] first.
 #[derive(Clone, Copy)]
 pub(super) struct Frame<'a> {
     pub(super) entity: Entity,
@@ -51,8 +38,7 @@ pub(super) struct Frame<'a> {
     pub(super) emote_sounds: Option<&'a EmoteSounds>,
     pub(super) walk: f32,
     pub(super) model_scale: f32,
-    /// Whether this body's plays go to the `WOW_MOVE_TRACE` anim trace, and under which label —
-    /// the rider's own, or the mount it is sitting on (decision 0906).
+    /// Whether this body's plays go to the anim trace; `subject` labels them (rider or mount).
     pub(super) traced: bool,
     pub(super) subject: &'a str,
 }
@@ -89,12 +75,9 @@ pub(super) fn run(
     } = f;
     match drv.mode {
         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 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).
+            // A swim re-latch lets JumpStart play out and the swim gait resume at its end, as the
+            // reference plays it; the byte reading, a cut where `0x5fd8e8` releases, does not
+            // reproduce that. A ground landing, a water exit or a new Special still cuts.
             let swim_relatch_hold = sp == select::Special::Jump
                 && special.is_none()
                 && mv.flags & move_flags::SWIMMING != 0
@@ -102,8 +85,6 @@ pub(super) fn run(
             if swim_relatch_hold {
                 // Hold: the kick keeps playing; the gait recompute waits at its end.
             } else if special != Some(sp) {
-                // What we're entering is no longer wanted before the enter even finished — preempt
-                // to the new Special, to the gait (a pose cut by movement), or to this one's exit.
                 drv.mode = leave_special(
                     &mut drv.base_lock,
                     sp,
@@ -156,9 +137,8 @@ pub(super) fn run(
             }
         }
         Mode::Land { id, flags } => {
-            // The jump landing (39/187) as a freely-overwritten pick (decisions 0083/0087 (d)).
+            // The jump landing (39/187), a freely overwritten pick.
             if let Some(sp) = special {
-                // A new jump or a pose interrupts (a second jump, or sitting right after landing).
                 drv.mode = enter_special(
                     &mut drv.base_lock,
                     sp,
@@ -171,21 +151,17 @@ pub(super) fn run(
                     &mut drv.loop_window,
                 );
             } else if mv.flags != flags {
-                // Any movement-flag change re-picks from live state *immediately* — land-then-press
-                // runs, land-then-release stands, a direction flip drops the stale-direction land.
+                // Any movement-flag change re-picks from live state at once.
                 drv.mode = Mode::Gait;
                 drv.gait = None;
             } else if oneshot_finished(player, anims, id, catalog) {
-                // Input held steady through the whole landing: fall through to a fresh gait pick.
                 drv.mode = Mode::Gait;
                 drv.gait = None;
             }
         }
         Mode::Exiting(sp, exit) => {
-            // Pose stand-ups only now (Jump lands via `Mode::Land`, not this bracket).
+            // Pose stand-ups only; a jump lands through `Mode::Land`.
             if let Some(next) = special {
-                // A new Special interrupts the exit — re-sitting during the stand-up, say. Enter
-                // it straight away instead of waiting the stand-up out.
                 drv.mode = enter_special(
                     &mut drv.base_lock,
                     next,
@@ -198,7 +174,6 @@ pub(super) fn run(
                     &mut drv.loop_window,
                 );
             } else if sp.interruptible_by_move() && moving {
-                // Started moving mid stand-up: drop the rest, let the gait cross-fade take over.
                 drv.mode = Mode::Gait;
                 drv.gait = None;
             } else if oneshot_finished(player, anims, exit, catalog) {
@@ -208,20 +183,9 @@ pub(super) fn run(
         }
         Mode::Swing { id, under } => {
             if special != under {
-                // The state this one-shot replaced CHANGED — the client's next event play
-                // supersedes it: a fresh jump/pose entry (`None → Some`), the FALLINGFAR
-                // latch's Fall (`Jump → Fall`), the `0x602c60` land pick at touchdown
-                // (`Some → None`) — each a plain PlayAnimation over bone 0, never a
-                // "restore". Leaving an airborne/pose `under` routes through
-                // [`leave_special`] exactly like the un-replaced machine: the latch
-                // handoff, the landing pick, and the pose exits all apply unchanged.
-                //
-                // …but FIRST the **transplant** (decision 0878): when what the base is about
-                // to play is a LOCOMOTION clip — a jump entry (37), a land pick (39/187) — and
-                // this one-shot is a live CAST/COMBAT clip, the client moves it up onto the
-                // key-bone rather than letting the request overwrite it. Fall(40) and the pose
-                // enters/exits are NOT locomotion ids, so a FALLINGFAR latch or a sit-down
-                // still replaces the clip on bone 0, exactly as the bytes order it.
+                // The replaced state changed: the next event play (a Special entry, the latch's
+                // Fall, the `0x602c60` land pick) takes bone 0 plainly, but a live cast or combat
+                // clip facing a locomotion request (37, 39/187) first transplants to the key-bone.
                 let incoming_locomotion = match (under, special) {
                     (_, Some(next)) => select::is_locomotion(next.enter()),
                     (Some(select::Special::Jump | select::Special::Fall), None) => {
@@ -264,17 +228,11 @@ pub(super) fn run(
                     Mode::Gait // unreachable: special != under with under None ⇒ special Some
                 };
             } 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 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 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.
+                // The airborne freeze (`0x5fd8e8`): nothing re-picks bone 0 mid-arc and a finished
+                // clip clamps (`0x7145db`). Fall plays once, at its latch (`0x61a9eb`), never per
+                // tick, so a clip armed after the latch holds until landing.
             } else if let Some(sp) = under {
-                // A pose held under the one-shot: on finish, back to the pose LOOP directly
-                // (decision 0083 (c) — the enter never replays after an interruption).
+                // A pose under the one-shot: on finish, straight back to its loop, never the enter.
                 if oneshot_finished(player, anims, id, catalog) {
                     play(
                         &mut drv.base_lock,
@@ -292,56 +250,18 @@ pub(super) fn run(
                     drv.mode = Mode::Looping(sp);
                 }
             } 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 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
-                // dispatcher's slot 22: a bare `RecomputeBaseAnim(-1)`.
-                //
-                // That recompute is the whole mid-volley cycle: for an armed shooter the base
-                // re-picks the Load clip, whose own completion promotes to the Hold. Fire →
-                // re-pull → hold, once per shot — and the re-pull's `$BWP` is what puts the
-                // arrow back on the string, since it is the only clip that authors the tag.
-                // Holding it out left every shot after the first firing from an empty hand
-                // (bug B307).
-                // Finished — or a movement-flag change: the client's base re-arm lands on the
-                // change and blindly overwrites bone 0, one-shot or not (the same re-arm
-                // decision 0280 named for the un-finishable looping kit clip, and
-                // Mode::Land's flag-change re-pick). Holding the clip out instead slides the
-                // post-shot runner over the ground on straight legs (director-observed vs
-                // ref). An EDGE, not a level — the split-boneless masked fallback enters
-                // here already moving, and steady flags must let that clip play out.
-                //
-                // Against `drv.gait_flags` — what the **base** was last armed for — not this
-                // one-shot's own arm-time `flags` (decision 0894). The reference keeps no
-                // per-one-shot latch: a movement-state change requests the base and bone 0
-                // takes it, whenever the one-shot happened to start. Ice Block is the case that
-                // separates them — its root wipes the direction bits in the SAME frame the cast
-                // one-shot arrives, so the arm-time compare sees no edge ever and the cast held
-                // bone 0 for the whole block; against the base's flags the edge is still there,
-                // Stand overwrites the cast, and the character is neutral when the freeze lands.
+                // A finished one-shot recomputes the base, fire clips too: bow ids reach the
+                // dispatcher `0x5fc3f0` through its deferred site (`0x7194f5`, `0x7074b0`), and
+                // 46/49/107 land on slot 22, `RecomputeBaseAnim(-1)`, so a shooter re-pulls.
+                // A movement-flag edge re-arms the base over any one-shot; steady flags let it
+                // play out. The edge is against `gait_flags`, what the base was armed for, as the
+                // reference keeps no per-one-shot latch.
                 if mv.flags != drv.gait_flags {
-                    // The locomotion re-arm is a normal PlayAnimation — the deferred-combat
-                    // cache clears with it (decision 0406; a finished clip instead had its
-                    // cache consumed by the injection above, before this machine ran).
+                    // The re-arm is a normal play, so the deferred-combat cache clears with it.
                     drv.deferred = None;
-                    // …and **if** the re-arm resolves to a LOCOMOTION id, a still-playing
-                    // CAST/COMBAT clip transplants up to the key-bone instead of being
-                    // overwritten (decision 0878; the client's gate is `0x5fee80` on the
-                    // *requested* id, `0x5fe912`). A *finished* clip has nothing to move: the
-                    // client's descriptor probe reports a completed slot as id −1 (`0x5fe1f0`
-                    // reads the completion latch, not the armed record), so the transplant
-                    // predicates never see it.
-                    //
-                    // The gate was missing here, and Ice Block is what it costs (decision
-                    // 0894): a stun's root wipes the direction bits, so the flag change re-arms
-                    // to **Stand(0)** — not locomotion — and the reference *overwrites* the
-                    // cast on bone 0, leaving the character fully neutral for the freeze to
-                    // catch. Transplanting unconditionally moved it to the torso instead and
-                    // froze an arm out.
+                    // Only a locomotion re-arm moves a live cast or combat clip to the key-bone
+                    // (`0x5fee80` on the requested id, `0x5fe912`); Stand overwrites it, and a
+                    // finished clip reads as id −1 (`0x5fe1f0`), so it never moves.
                     if select::gait_is_locomotion(&mv, walk) {
                         transplant_up(drv, player, tr, anims, entity, id);
                     }
@@ -352,7 +272,6 @@ pub(super) fn run(
         }
         Mode::Gait => {
             if let Some(sp) = special {
-                // Enter a Special state.
                 drv.mode = enter_special(
                     &mut drv.base_lock,
                     sp,
@@ -366,49 +285,27 @@ 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 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
-                // pins further down the chain (the stationary cast hold, the loot kneel, the
-                // Ready/ranged idles, the state-emote idle) cannot swap the clip until
-                // touchdown. Rate stays synced — the client's per-frame rate write is outside
-                // the selector, so it is [`play::sync_base_rate`]'s below and this arm does
-                // nothing at all. (DEATH is excluded: the dead-override owns that gait, and a
-                // mid-air revive must re-select, not hold the corpse pose.)
+                // The step-off arc's airborne freeze, `0x5fd8e8` right after the death legs:
+                // `FALLING && (FALLINGFAR || vz ≠ 0)` holds the takeoff gait against every pin
+                // until touchdown. Death is excluded: a mid-air revive must re-select.
             } else {
-                // A bracket-less step-off fall landing needs NO case of its own: the arc never
-                // latched FALLINGFAR, so the `0x602c60` land dispatcher is a verified no-op
-                // (decision 0179) — and a no-op means the gait must keep rolling mid-cycle,
-                // not be re-picked (a re-pick replays the run cycle from its head: the
-                // landing-frame leg pop, decision 0187). Falling through keeps the clip when
-                // the flags still agree and cross-fades normally when they changed mid-air.
-                // Normal gait: select, cross-fade on change, keep the rate synced each frame.
-                // The engaged standing idle: the weapon-class Ready pick (decision 0073).
-                // `GetWeapon(0, 0)` again ([`Wielded::armed_main`]) — `0x5fcdc0` passes
-                // visFlag 0, so a disarmed unit stands in ReadyUnarmed(25) (decision 1863).
+                // The ordinary pick, which a step-off landing also takes: the land dispatcher
+                // (`0x602c60`) plays nothing for an unlatched arc, so an unchanged target keeps its
+                // clip (a re-pick would restart it) and changed keys cross-fade. A fresh walk-off's
+                // vz == 0 substep, which the freeze gate leaves uncovered, takes this pick too.
+                //
+                // Ready pick (`0x5fcdc0`, visFlag 0): a disarmed unit stands in ReadyUnarmed(25).
                 let ready =
                     (engaged && !moving).then(|| ready_anim(wielded.and_then(|w| w.armed_main())));
-                // The ranged standing idle (0099 phase 5): the byte-verified entry gate
-                // ([`select::ranged_idle_gate`]) → the ranged weapon's Load clip, played
-                // ONCE, then promoted to the Hold by its own completion. ENTRY is the local
-                // `0x200` ([`auto_repeat`]) alone — `0x5fd460`'s own and only claim test
-                // besides the sheath. The HOLD twin is real and this is where it comes back
-                // (decision 1544, superseding 0994 §2, which deleted it on a refuted absence
-                // proof): 105 → 109, 106 → 110, 112 → 111, unconditionally at the Load's
-                // completion. Mid-volley the base IS re-picked — every fire clip's completion
-                // recomputes — so the cycle is fire → re-pull → hold, per shot.
+                // The ranged idle (`0x5fd460`), entered on the drawn ranged sheath and the local
+                // auto-repeat bit `0x200` (`select::ranged_idle_gate`): the Load plays once and its
+                // completion arms the Hold, 105/106/112 → 109/110/111.
                 let ranged_load =
                     (!moving && select::ranged_idle_gate(auto_repeat, drv.sheath_cur)).then(|| {
                         let load = select::ranged_load_anim(wielded.and_then(|w| w.ranged));
                         let hold = select::ranged_hold_anim(load);
-                        // The pull's own completion promotes it to the Hold — the dispatcher's
-                        // slot 11/12/15 arm, UNCONDITIONAL ([`select::ranged_hold_anim`] carries
-                        // which gate belongs to whom). Expressed as a CANDIDATE rather than a
-                        // latch: once armed, the Hold re-selects itself every frame, and the
-                        // volley's end drops `ranged_idle_gate` and recomputes straight out of it
-                        // — so there is no second piece of state to keep in step, which is what
-                        // 0409's re-latch was and why 0994 was right to delete that much.
+                        // The Load's completion arms the Hold unconditionally (slots 11/12/15); a
+                        // candidate, not a latch, it re-selects itself until the volley ends.
                         let holding = drv.gait == Some(hold)
                             || (drv.gait == Some(load)
                                 && oneshot_finished(player, anims, load, catalog));
@@ -419,14 +316,9 @@ pub(super) fn run(
                         }
                     });
                 let cands = gait_candidates(&mv, walk, ready, ranged_load);
-                // The stationary cast/channel hold pins its pose **full-body in the gait slot**
-                // (decision 0107 — the client's `[CGUnit+0xb4]` stationary-cast gate),
-                // outranking the Ready idle and the state-emote idle below. "Stationary" is
-                // the client's `[9e8] & 0x20000f` test ([`move_flags::CAST_PIN_MOVE`]:
-                // translation + swim, NEVER the turn bits) — a turning caster keeps the pin,
-                // feet sliding; only a translating/swimming one falls through to the masked
-                // hold overlay (the hold block after the mode machine). Testing the turn bits
-                // here was the frostbolt right-drag jitter (decision 0491).
+                // The stationary cast/channel pin (`[CGUnit+0xb4]`), full-body over the Ready and
+                // state-emote idles; stationary is `[9e8] & 0x20000f`, never the turn bits, so a
+                // turning caster keeps it and a moving one gets the masked hold instead.
                 let hold_cands;
                 let cands: &[u16] = match cast_hold {
                     Some(h) if mv.flags & move_flags::CAST_PIN_MOVE == 0 => {
@@ -435,13 +327,8 @@ pub(super) fn run(
                     }
                     _ => cands,
                 };
-                // The looping state-emote idle (`UNIT_NPC_EMOTESTATE`: `/dance`, NPC
-                // cooking/sweeping flavor loops): fills exactly the bare-Stand slot
-                // (`is_bare_stand`) — everything that already outranks Stand (movement, turn,
-                // swim, the Ready idle, a chair-loop stand-state) has already routed `cands`
-                // elsewhere, and Special is handled entirely above this arm. Cleared field
-                // (`unit_emote_state() == 0`, or the catalog has no `AnimID` for it) falls
-                // straight through to `cands` unchanged — back to Stand.
+                // The looping state-emote idle (`UNIT_NPC_EMOTESTATE`: `/dance`, NPC work loops)
+                // fills only the bare-Stand slot; whatever outranks Stand already routed `cands`.
                 let state_emote_cands;
                 let cands: &[u16] = if is_bare_stand(cands) {
                     let emote_anim = store
@@ -456,13 +343,10 @@ pub(super) fn run(
                 } else {
                     cands
                 };
-                // The loot kneel (see [`select::LOOT`]): while the loot trigger is up
-                // (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: locomotion → LOOT →
-                // standState → combat/channel). The trigger dropping cross-fades back to
-                // whatever the slot picks next.
+                // The loot kneel (Loot 50) of a stationary, unmounted unit with the trigger up,
+                // over the cast pin, the Ready and ranged idles, the chair loops and the state
+                // emote: `0x5fd8b0` tries locomotion, then loot (`0x5fd260`), then the cast/channel
+                // pin (`0x5fd2e0`) and the Ready idle (`0x5fd360`) before the rest.
                 let loot_cands;
                 let cands: &[u16] = if looting {
                     loot_cands = [select::LOOT, STAND];
@@ -470,18 +354,9 @@ pub(super) fn run(
                 } else {
                     cands
                 };
-                // The mounted pin outranks the whole gait slot (decision 0442 confirms 0441's
-                // B1): the rider holds Mount(91) — moving, turning, engaged — while the mount
-                // child's own driver plays the locomotion this selector would have picked. The
-                // real client has no mount leg in this chain at all — it arms 91 once at
-                // attach (`0x607b44`) and re-forces it on every PlayAnimation
-                // (`0x5fe803`–`0x5fe816`) instead of selecting it here. The pin renders that
-                // **steady state** exactly; what it does NOT render is the *attach* arm's
-                // displacement of a full-body one-shot already holding bone 0 (the pin waits
-                // on `Mode::Swing`, the reference's play does not) — which is why the
-                // transition edge above arms separately (decision 0927, B203). 91 is not
-                // rate-scaled, and the resolver's Stand fallback covers a body that doesn't
-                // author it.
+                // The mounted pin: the rider holds Mount(91), the mount plays the locomotion. The
+                // client arms 91 outside this chain, at attach (`0x607b44`) and on every play
+                // (`0x5fe803`–`0x5fe816`); the mount edge arms the attach over a live one-shot.
                 let mount_cands;
                 let cands: &[u16] = if mounted {
                     mount_cands = [select::MOUNT, STAND];
@@ -490,26 +365,11 @@ pub(super) fn run(
                     cands
                 };
                 let target = cands[0];
-                // **The turn-shuffle is released by its own clip window, not by the turn ending**
-                // (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
-                // armed and no turn bit set it computes target 0, sees `0xb != 0`, and calls
-                // `0x5fce30` — whose first gate (`0x5fce33`/`0x5fce42`) needs `moveflags & 0x30`
-                // or `d58 & 0x1800`, precisely what just went false. `0x6084da je` then skips the
-                // recompute. **The tail can only START a shuffle, never stop one.** What stops it
-                // is the animation-completion callback every in-world unit installs
-                // (`0x60781b`), one clip window later — which is why the reference plays a
-                // discrete little step rather than a stub of one: with `replay = (0,0)` on all
-                // 1130 shipped shuffle records the window is exactly one span, 500 ms on 1100 of
-                // them, so the step is `ceil(t_turn / span) · span` long however brief the turn.
-                //
-                // Only against **Stand**. Every other target — a walk, the mount pin, the cast
-                // hold, the Ready idle, a state emote, the loot kneel — arrives in the client
-                // through one of `0x5fd9e0`'s 37 edge-triggered call sites, which fire regardless
-                // of the turn bits and preempt the shuffle at once. The refusal is the tail's
-                // alone, and the tail's target is a hardcoded 0.
+                // A turn shuffle ends at its own clip window, not with the turn: `0x607ed0`'s
+                // per-frame tail can start one but not stop it (`0x5fce30` needs a turn bit, so
+                // `0x6084da je` skips), and the completion callback (`0x60781b`) ends it, so a
+                // step lasts `ceil(t_turn / span) · span`. Only against Stand: other targets
+                // arrive through `0x5fd9e0`'s edge sites at once.
                 let target = match drv.gait {
                     Some(g @ (select::SHUFFLE_LEFT | select::SHUFFLE_RIGHT))
                         if target == STAND && !window_complete(drv, player) =>
@@ -518,52 +378,29 @@ pub(super) fn run(
                     }
                     _ => target,
                 };
-                // 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
-                // through the same call, like every other candidate.
+                // Each candidate in priority order, through the model's baked fallback first.
                 let clip = cands
                     .iter()
                     .find_map(|&id| find_resolved(anims, id, catalog));
-                // Did the base actually take a clip this pass? Only the lock can say no, and
-                // when it does the bookkeeping below must not run ([`play::BaseAnimLock`]).
+                // Whether the base took a clip; only the lock refuses, skipping the bookkeeping.
                 let mut armed = true;
                 if drv.gait == Some(target) {
-                    // The gait is already armed and stays armed — its rate is
-                    // [`play::sync_base_rate`]'s per-frame write below, which finds whichever
-                    // *rolled variation* (decision 0123) is actually the live one rather than
-                    // sweeping every node of the id. A completed ranged Load simply clamps at
-                    // full draw and stays there; nothing promotes it (0994).
+                    // Already armed; the per-frame rate write keeps its rate.
                 } else if let Some(c) = clip {
-                    // **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
-                    // `Knockdown` overrides the clip.
+                    // The death pose (`0x5fc563`) and the mount attach (`0x607b44`) arm past the
+                    // lock in the reference; here they are gait targets, so they drop it first.
                     if target == DEATH || target == select::MOUNT {
                         drv.base_lock.release();
                     }
-                    // Held: the selector does not even roll. The reference re-picks the base on an
-                    // EVENT (`0x5fd9e0(-1)` from a packet handler), never once a frame, so a
-                    // per-frame retry while the lock refuses would burn the shared variation RNG
-                    // (decision 0114's single `_rand` stream) for the clip's whole 2 s and perturb
-                    // every other unit's rolls with it. `drv.gait` stays `None`, so the pick
-                    // happens exactly once — the frame the clip releases the lock.
+                    // Locked: no roll. The reference re-picks on events (`0x5fd9e0(-1)`), so a
+                    // per-frame retry would drain the shared random stream; it picks on release.
                     if drv.base_lock.refuses() {
                         armed = false;
                     } 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, `0x712784`
-                        // — the watchdog window). A re-armed Stand landing on its rare look-around
-                        // variations IS the idle fidget.
+                        // Variation (when relaxed) and budget, the watchdog window (`0x712784`).
                         let (c, budget) = roll_loop(anims, c, relaxed, rng);
                         if traced && benilla_assets::trace::enabled() {
-                            // Every fresh gait play, including a same-clip replay (which the
-                            // settled-state diff below cannot see) — the exact restart-from-head
-                            // event a "frames snap" report is hunting.
+                            // Every fresh gait play, same-clip replays included.
                             benilla_assets::trace::line(
                                 "anim",
                                 &format!(
@@ -574,18 +411,10 @@ pub(super) fn run(
                                 ),
                             );
                         }
-                        // The ranged Load plays ONCE and freezes at full draw: as a Forever
-                        // gait it WRAPPED to its head at completion — the frames + cross-fade
-                        // against the restarted reach-to-quiver were the director's "jumps
-                        // back to the start the moment it gets fully pulled", in every build
-                        // that replayed a pull (trace-caught, decision 2276). The clamp IS the
-                        // drawn pose; nothing follows it (0994).
-                        // Loot 50 is likewise authored clamp — one 0.5 s kneel-down that must
-                        // FREEZE in the rummage pose; as Forever it would wrap back to standing
-                        // and re-kneel every half second.
+                        // The ranged Load and Loot 50 are authored clamp: played once, they hold
+                        // their last frame (full draw, the rummage pose), where a loop would wrap.
                         let repeat = if select::is_ranged_load(target) || target == select::LOOT {
-                            // A deliberate freeze — no window either: a watchdog re-pull is
-                            // exactly what the reference's missing completion dispatch rules out.
+                            // No watchdog window either, so nothing re-arms them.
                             drv.loop_window = None;
                             bevy::animation::RepeatAnimation::Never
                         } else {
@@ -602,13 +431,10 @@ pub(super) fn run(
                         }
                     }
                 } else {
-                    drv.gait = Some(target); // no clip (bind pose) — record the target so we don't churn
+                    drv.gait = Some(target); // no clip (bind pose): record it so it does not churn
                 }
                 if armed {
-                    // The base is now arm-consistent with this movement state — every branch above
-                    // leaves `drv.gait == Some(target)`. A one-shot that displaces it later reads
-                    // this, not its own arm-time flags, to know whether the movement state has
-                    // moved on since (decision 0894).
+                    // What the base was armed for: a later one-shot's flag edge tests against it.
                     drv.gait_flags = mv.flags;
                 }
             }
@@ -616,13 +442,8 @@ pub(super) fn run(
     }
 }
 
-/// Has the base slot's armed looping clip finished its **replay window** — the client's
-/// `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
-/// watchdog reads the same pair one phase earlier and, in the gait slot, answers a completion by
-/// clearing the target — so a `true` here and a re-selection there are the same event.
+/// Whether the base's looping clip has run its replay window, `windowHi = windowLo + span·R`
+/// (`0x712784`); `true` when there is no window to wait on.
 fn window_complete(drv: &AnimDriver, player: &AnimationPlayer) -> bool {
     drv.loop_window.is_none_or(|(node, budget)| {
         player
diff --git a/crates/benilla-app/src/creature_anim/driver/play.rs b/crates/benilla-app/src/creature_anim/driver/play.rs
index 90cd75f0..11a9a236 100644
--- a/crates/benilla-app/src/creature_anim/driver/play.rs
+++ b/crates/benilla-app/src/creature_anim/driver/play.rs
@@ -1,6 +1,4 @@
-//! Playback primitives for [`super::drive_animations`]: resolving and cross-fading into a clip
-//! ([`play_clip`], [`play`]), checking whether a one-shot has finished ([`oneshot_finished`]), and
-//! leaving a Special state ([`leave_special`]) — split out of [`super`] as its own concern.
+//! Base-track playback: arming clips, the base-animation lock, entering and leaving Specials.
 
 use std::time::Duration;
 
@@ -13,59 +11,35 @@ use bevy::prelude::*;
 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 (decision 2096, correcting 2085's §3).
-///
-/// `CGUnit::PlayAnimation 0x5fe2f0` opens with a guard that returns having done nothing at all:
-///
-/// ```text
-/// 5fe396  mov  eax,[ebx+0xd58]
-/// 5fe39c  test eax,0xc0000
-/// 5fe3a1  jne  0x5fec29        ; bare epilogue — no routing, no arm, no deferral
-/// ```
-///
-/// The bits are set by `PlayAnimation`'s **own** arm helper `0x5fdba0`, in a tail keyed on the id
-/// *actually armed* (`0x5fdcf7`'s byte table `0x5fdd90`): **121 `Knockdown` → `0x80000`**, **192
-/// `LiftOff` / 200 `Land` → `0x40000`**. They are cleared in `CGUnit::OnAnimationFinished
-/// `0x5fc9c6`, above that function's reason branch — so on natural completion *and* on pre-emption
-/// — and again on a model rebuild (`0x60adee`).
-///
-/// So a stun's root **does** recompute the base and the selector **does** resolve `Stand(0)`, and
-/// the `0x5fda20 call 0x5fe2f0(0)` that would overwrite the Knockdown is simply **refused**. The
-/// clip runs its full 2000 ms. Order-independent, which is why it holds whatever the packet timing.
-///
-/// The reference carries two independent bits; a unit can only ever hold one, because the second
-/// arm would itself be refused — so this models the holder as the id, which also expresses the
-/// "keyed on the FINISHED id" clearing rule directly. The two weaker relatives (`0x4` on 39
-/// `JumpEnd`, which only makes the fallback idle decline, and `0x8` on 127 `Birth`, which makes the
-/// whole selector return keep-current) are separate mechanisms at their own sites and are not
-/// modelled here.
+/// The base-animation lock, the reference's `[unit+0xd58] & 0xc0000`: while it is held,
+/// `CGUnit::PlayAnimation 0x5fe2f0` returns at once (`0x5fe3a1 jne 0x5fec29`), so a stun's
+/// `Stand(0)` recompute (`0x5fda20`) is refused and a `Knockdown` runs its full 2000 ms. The arm
+/// helper `0x5fdba0` sets it on the id actually armed (table `0x5fdd90`: 121 `Knockdown`, 192
+/// `LiftOff`, 200 `Land`); `OnAnimationFinished 0x5fc9c6` clears it on completion or pre-emption,
+/// as does a model rebuild (`0x60adee`). Held as the id, since a second arm would be refused.
 #[derive(Default, Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) struct BaseAnimLock(Option<u16>);
 
 impl BaseAnimLock {
-    /// The three ids whose arm takes the lock — `0x5fdd90`'s table, `0xc0000` half.
+    /// The ids whose arm takes the lock (`0x5fdd90`).
     fn locking(id: u16) -> bool {
         matches!(id, select::KNOCKDOWN | select::LIFT_OFF | select::LAND)
     }
 
-    /// The guard: is a play refused right now? An **unconditional early return**, not a priority
-    /// comparison and not a dedup (`0x5fe3a1`).
+    /// Whether a play is refused: an unconditional early return, not a priority test (`0x5fe3a1`).
     pub(super) fn refuses(self) -> bool {
         self.0.is_some()
     }
 
-    /// The setter, run on the id **actually armed** and only when the arm happened.
+    /// The setter, run on the id actually armed and only when the arm happened.
     fn took(&mut self, id: u16) {
         if Self::locking(id) {
             self.0 = Some(id);
         }
     }
 
-    /// 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 (`0x607b44`).
+    /// The clearer, keyed on the finished id (`0x5fc9c6`): run once a frame before anything
+    /// re-picks the base, so a clip that completes or is pre-empted releases it.
     pub(super) fn release_finished(
         &mut self,
         player: &AnimationPlayer,
@@ -79,26 +53,17 @@ impl BaseAnimLock {
         }
     }
 
-    /// 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 (`0x5fc563`) and the
-    /// mount attach (`0x607b44`).
+    /// Drops the lock outright, for the arms the reference never gates: the death pose
+    /// (`0x5fc563`) and the mount attach (`0x607b44`). A model rebuild needs no call: it removes
+    /// [`AnimDriver`].
     pub(super) fn release(&mut self) {
         self.0 = None;
     }
 }
 
-/// Cross-fade the player into an **already-resolved** clip over its blend-in time. `repeat` sets its
-/// repetition (`Forever` for a loop, `Count(R)` for a rolled replay budget, `Never` for a plain
-/// one-shot — always set, so a reused graph node never carries a stale count from a prior play);
-/// `rate` sets its playback speed. The primitive [`play`] (and the gait picker, which already has
-/// the resolved [`AnimClip`] in hand) both funnel through this so resolution never runs twice.
-/// Returns whether the clip was actually armed — `false` is the lock's refusal, and a caller whose
-/// bookkeeping says "the base now holds this" must not write it on a `false` (the reference's guard
-/// returns before the arm's own `[bone+0xf8] = animId`, so nothing downstream believes it played).
+/// Cross-fades into an already-resolved clip unless the lock refuses, returning whether it armed;
+/// `repeat` is always set, so a reused node keeps no stale count. On `false` the caller must not
+/// record the clip as held: the reference's guard returns before the arm's `[bone+0xf8] = animId`.
 pub(super) fn play_clip(
     lock: &mut BaseAnimLock,
     tr: &mut AnimationTransitions,
@@ -107,9 +72,8 @@ pub(super) fn play_clip(
     repeat: RepeatAnimation,
     rate: f32,
 ) -> bool {
-    // The guard, at the very top — before any routing, descriptor build or slot election
-    // ([`BaseAnimLock`]). `arm` below is the primitive the reference reaches past this guard from
-    // the dismount, the sheath family and the weapon attach, so it stays ungated.
+    // The guard comes first. `arm` stays ungated: the reference reaches it past the guard from the
+    // dismount, the sheath family and the weapon attach.
     if lock.refuses() {
         return false;
     }
@@ -125,19 +89,10 @@ pub(super) fn play_clip(
     true
 }
 
-/// Arm an already-resolved **looping** clip with the cross-fade SUPPRESSED — op4 `0x7121a0` called
-/// with `crossFadeFlag = 0`, which is a genuinely different arm, not a fast blend:
-///
-/// - the outgoing pose is **not** carried. `0x71253e`–`0x712543` tests arg6 and, when it is zero,
-///   jumps clean past the whole blend block — including the `rep movsd` at `0x7125d9`–`0x7125ea`
-///   that copies the primary block `[bone+0x98..]` into the secondary `[bone+0xc4..]`. So the new
-///   clip's first frame IS the pose, immediately, and a **full-body secondary overlay survives**
-///   (only the blended arm evicts it — decision 0114's shared-slot eviction is a *blend* law).
-/// - the primary's own bookkeeping still runs: `[bone+0xf8] = animId` at `0x71252f` is gated on
-///   arg7 (the slot selector) alone, so bone 0 changes hands either way.
-///
-/// The dismount teardown `0x607ce0` is the call site this exists for (decision 0931); the mount-up
-/// build `0x607b44` passes `1` and takes [`play_clip`]'s ordinary cross-fade.
+/// Arms a looping clip with no cross-fade, as the dismount teardown `0x607ce0` calls op4
+/// `0x7121a0` with `crossFadeFlag = 0`: `0x71253e`–`0x712543` skips the blend block and its
+/// primary-to-secondary copy (`0x7125d9`–`0x7125ea`), so the clip is the pose at once and a
+/// full-body secondary overlay survives, while `[bone+0xf8] = animId` (`0x71252f`) still runs.
 pub(super) fn cut_loop(
     tr: &mut AnimationTransitions,
     player: &mut AnimationPlayer,
@@ -150,8 +105,7 @@ pub(super) fn cut_loop(
     let Some(head) = find_resolved(anims, id, catalog) else {
         return;
     };
-    // op4's arg3 here is a literal `-1` (`0x607d25`), so the variation rolls unconditionally — the
-    // teardown is not one of the arms [`select::arm_forces_head`] pins to the head.
+    // op4's arg3 is a literal `-1` here (`0x607d25`): the variation always rolls.
     let (c, r) = roll_loop(anims, head, true, rng);
     *window = Some((c.node, r));
     arm(tr, player, c, RepeatAnimation::Forever, 1.0, Duration::ZERO);
@@ -170,11 +124,8 @@ fn arm(
     active.set_speed(rate);
 }
 
-/// The one-shot arm's two rolls, in the client's order (op4: variation at `0x71249a`, replay count
-/// at `0x712698` — decision 0117): pick the resolved id's **variation** (the `_rand()`-weighted
-/// walk, alternating the 1H swing arcs), then roll the **replay budget** `R` from the picked
-/// clip's `(minReplay, maxReplay)` — the client multiplies `R` into the play window; benilla
-/// expresses the same window as a `Count(R)` repeat, which `is_finished` honors.
+/// A one-shot arm's rolls in op4's order: the variation (`0x71249a`), then the picked clip's replay
+/// budget `R` (`0x712698`), which multiplies the play window and plays here as `Count(R)`.
 pub(super) fn roll_oneshot<'a>(
     anims: &'a ModelAnimations,
     head: &'a AnimClip,
@@ -190,13 +141,8 @@ pub(super) fn roll_oneshot<'a>(
     (c, repeat)
 }
 
-/// Pick a looping arm's **variation** (decision 0123 — the client's base-arm `variationIdx = −1`,
-/// `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
-/// re-rolls — the advance between variations is the WATCHDOG's re-arm ([`roll_loop`]'s window,
-/// decision 0516), not a kernel cycle.
+/// A looping arm's variation (`variationIdx = −1`, `0x5fe697`): relaxed, the weighted walk (the
+/// idle fidget); combat or cast, the head. Only the watchdog's re-arm re-rolls, never the kernel.
 pub(super) fn pick_loop_variation<'a>(
     anims: &'a ModelAnimations,
     head: &'a AnimClip,
@@ -212,12 +158,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): 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).
+/// A looping arm's rolls in op4's order (`0x71249a`, `0x712692`); the budget `R ∈ [min, max−1]`,
+/// floored to 1, sets the watchdog window `windowHi = arm + span·R`.
 pub(super) fn roll_loop<'a>(
     anims: &'a ModelAnimations,
     head: &'a AnimClip,
@@ -229,14 +171,8 @@ pub(super) fn roll_loop<'a>(
     (c, r)
 }
 
-/// Cross-fade into clip `id`, resolved through the model's own baked fallback first (decision 0082 —
-/// see [`find_resolved`]) so a model lacking `id` plays its baked substitute rather than nothing.
-/// `looping` repeats it; `rate` sets its playback speed. No-op if resolution still comes up empty.
-/// A **one-shot** (`!looping`) rolls the resolved id's **variation and replay budget** per play
-/// ([`roll_oneshot`] — decisions 0114/0117); a looping play rolls its variation (when `relaxed` —
-/// decision 0123) **and its budget** ([`roll_loop`] — decision 0516), publishing the armed
-/// `(node, R)` into `window` for the watchdog's advance; a one-shot arm clears it (its budget is
-/// the `Count` repeat — no window outlives the arm).
+/// Resolves `id` through the model's baked fallback and cross-fades into it with its rolls; a loop
+/// publishes its `(node, R)` to `window` for the watchdog, a one-shot clears it.
 pub(super) fn play(
     lock: &mut BaseAnimLock,
     tr: &mut AnimationTransitions,
@@ -250,12 +186,8 @@ pub(super) fn play(
     rng: &mut benilla_assets::AnimRng,
     window: &mut Option<(bevy::animation::graph::AnimationNodeIndex, u32)>,
 ) {
-    // The lock's guard is `PlayAnimation`'s **front door**, above the arm helper that draws the
-    // rolls (`0x5fe2f0`'s epilogue return is at `0x5fe3a1`; the `_rand()` sites live inside
-    // `0x5fdba0`'s op4 call). So a refused play must not roll either: the variation and replay
-    // draws come off the ONE shared stream (decision 0114), and rolling them for a body that
-    // cannot move would perturb every other unit's picks for the clip's whole 2 s — the same
-    // churn 2096 caught in the gait selector's live trace, at the event-play door instead.
+    // The guard returns (`0x5fe3a1`) before the arm helper `0x5fdba0` rolls, so a refused play
+    // draws nothing from the one shared random stream.
     if lock.refuses() {
         return;
     }
@@ -272,36 +204,12 @@ pub(super) fn play(
     }
 }
 
-/// Write the **playback rate** of whatever the full-body slot currently holds — run once per frame,
-/// after the mode machine has settled, in every mode alike.
-///
-/// The client's rate write lives **outside the selector** (`0x5fe2f0`, per-frame over the armed
-/// clip), so it is not the gait's private business: it applies to a landing, a bracket, a swing —
-/// anything the base slot holds. Ours used to be two loops inside [`Mode::Gait`]'s arms, which left
-/// every other mode playing at its arm-time literal `1.0` — and that is the jump-landing bug
-/// (decision 0906). [`jump_land_pick`] requests JumpLandRun **187**, and **every creature model
-/// resolves 187 → Run(5)** through its own baked PlayableAnimationLookup: Horse, Tiger (the druid
-/// travel form) and Cat all carry `playable[187] = 5`; only character models author 187 itself. So
-/// a mount's landing clip *is* its gallop cycle — a rate-scaled locomotion clip — and playing it at
-/// 1× ran it at ~65% of the cadence a mount's 14 yd/s calls for (Horse Run moveSpeed 9.028) for the
-/// clip's whole 0.8 s, snapping straight only when the gait re-picked after it. On foot the same
-/// defect is invisible: the character's own 187 carries moveSpeed 6.944 against a run speed of 7.0,
-/// so the correct rate *is* 1×.
-///
-/// It writes **only where the scaler applies** ([`select::scaled_rate`]) — a locomotion clip with
-/// an authored design speed. Everything else keeps whatever armed it: the scaler is one rate
-/// producer among several (the combat fast-path's 2×, the whiff's 0.5×, 0503's 0× freeze), and a
-/// blanket `1.0` here stomps all three.
-///
-/// [`AnimDriver::frozen`] names the one node this must leave alone even so — the airborne snapshot
-/// decision 0503 stopped on purpose ([`leave_special`]), whose clip *is* rate-scaled (Jump 38 is in
-/// the locomotion set; it is only the real assets' `moveSpeed = 0` that would spare it) — and is
-/// cleared as soon as anything else is armed.
-///
-/// It also records what the slot ended up running at in [`AnimDriver::gait_rate`] — the hover
-/// card's `rate` readout and the trace's `rate=` (decision 0903). Read back off the node rather
-/// than recomputed, so the instrument reports the swing's 2× or the freeze's 0× as faithfully as
-/// it reports a gait.
+/// Writes the rate of whatever bone 0 holds, once a frame in every mode: the client's per-frame
+/// write over the armed clip sits outside the selector (`0x5fe2f0`), and a creature's JumpLandRun
+/// (187) resolves to its Run (5) through the model's lookup, a gait cycle that needs the rate.
+/// Only a clip the scaler covers is written, so the fast path's 2× and the whiff's 0.5× survive;
+/// the frozen node is skipped even so. [`AnimDriver::gait_rate`] gets the rate read back off the
+/// node.
 pub(super) fn sync_base_rate(
     drv: &mut AnimDriver,
     tr: &AnimationTransitions,
@@ -329,11 +237,8 @@ pub(super) fn sync_base_rate(
     drv.gait_rate = player.animation(node).map_or(1.0, |a| a.speed());
 }
 
-/// Whether the one-shot clip `id` has finished playing (resolved through the model's own baked
-/// fallback first, decision 0082 — matching [`play`], which is what started it) — or the model lacks
-/// even the substitute, so the machine doesn't wait forever. Checked across the id's **variations**
-/// (decision 0114): the play rolled one of them, and whichever it was, "finished" means no variation
-/// of the id is still running.
+/// Whether one-shot `id`, resolved as [`play`] resolved it, has finished in every variation (the
+/// play rolled one); a model with no clip for it counts as finished.
 pub(super) fn oneshot_finished(
     player: &AnimationPlayer,
     anims: &ModelAnimations,
@@ -350,18 +255,9 @@ pub(super) fn oneshot_finished(
     }
 }
 
-/// Whether bone 0 still holds `sp`'s **own** clip — the arc's enter or its loop, resolved through
-/// the model's baked fallback exactly as [`play`] resolved it when it armed (decision 0082) and
-/// compared on the *resolved* id, so a rolled variation counts as the same clip.
-///
-/// This is the predicate the airborne snapshot-freeze (decision 0503, scoped by 1566) never had.
-/// The freeze exists to still **the cut airborne clip** before the landing cross-fades over it;
-/// both its sites took whatever bone 0 happened to hold, on the unstated assumption that the arc's
-/// own clip is what is there. The base-anim lock (2096) is the first thing that ever falsified it,
-/// and it falsified it catastrophically: every play the arc asked for was refused, so bone 0 still
-/// held the `Knockdown` that took the lock — and the landing stopped **that** dead. A clip stopped
-/// dead never finishes, and the lock clears on the finished id, so the body stayed on its back for
-/// the rest of the session with every later play refused (the director's report, decision 2098).
+/// Whether bone 0 holds `sp`'s own enter or loop clip, compared on the resolved id so a rolled
+/// variation counts. The airborne freeze must still only that clip: a refused arc leaves the locked
+/// clip on bone 0, and a stilled clip never finishes, so it would never release the lock.
 pub(super) fn holds_own_clip(
     anims: &ModelAnimations,
     catalog: Option<&AnimDataCatalog>,
@@ -377,10 +273,8 @@ pub(super) fn holds_own_clip(
         .any(|head| head.anim_id == cur.anim_id)
 }
 
-/// Enter the Special `sp`, returning the mode to adopt. A pose or a jump plays its enter one-shot
-/// and settles through [`Mode::Entering`]; **Fall has no enter** — the client plays the Fall(40)
-/// loop directly the tick FALLINGFAR latches (`0x602c40`) — so it goes straight to
-/// [`Mode::Looping`] with a looping play.
+/// Enters Special `sp`, returning the mode to adopt. Fall has no enter: the client loops Fall(40)
+/// from the tick FALLINGFAR latches (`0x602c40`).
 pub(super) fn enter_special(
     lock: &mut BaseAnimLock,
     sp: Special,
@@ -408,7 +302,6 @@ pub(super) fn enter_special(
         );
         Mode::Looping(sp)
     } else {
-        // Enter plays are one-shots — `relaxed` (a looping-arm concern) is moot for them.
         play(
             lock,
             tr,
@@ -426,12 +319,8 @@ pub(super) fn enter_special(
     }
 }
 
-/// Transition out of the Special flow `sp` this frame, given what the unit now wants (`special`,
-/// `moving`). A *different* Special preempts with its own entry (a second jump cutting the first's
-/// landing; a jump handing off to Fall when FALLINGFAR latches); a pose abandoned because the unit
-/// started moving drops straight to the gait, letting the cross-fade carry the half-pose into the
-/// walk; an airborne state landing plays its [`jump_land_pick`]; otherwise `sp` plays its graceful
-/// exit one-shot, which [`super::drive_animations`] then waits out. Returns the mode to adopt.
+/// Leaves Special `sp`, returning the mode to adopt: a new Special's entry, the land pick after an
+/// airborne state, the gait for a pose cut by movement, else `sp`'s exit one-shot.
 pub(super) fn leave_special(
     lock: &mut BaseAnimLock,
     sp: Special,
@@ -447,25 +336,10 @@ pub(super) fn leave_special(
     window: &mut Option<(bevy::animation::graph::AnimationNodeIndex, u32)>,
     frozen: &mut Option<bevy::animation::graph::AnimationNodeIndex>,
 ) -> Mode {
-    // Freeze the cut airborne clip before handing off, so the incoming gait fades in over a
-    // still kick instead of one that actively retracts. On the swim re-latch (~0.24 s into the
-    // 833 ms JumpStart) the clip's remaining frames are the leg RECOVERY, and ours read far
-    // shorter than the reference's lingering mid-kick — the director's report behind 0503.
-    //
-    // **This is a symptom fix whose mechanism is open** (decision 1566). 0503 justified it with
-    // "the client blends from a pose snapshot, universally", which the bytes REFUTE: the blend
-    // source keeps running on its own clock — `0x7125ea` copies the outgoing track's base, rate
-    // and bias, and the kernel re-derives its time every frame (`0x7146b2`–`0x7147a5`). It looks
-    // still only when the source's own window has elapsed AND it is clamp-flagged, which the cut
-    // JumpStart's has not. So do NOT generalise this to other cross-fades — that was 0503's
-    // recorded follow-up and 1566 strikes it; it would freeze every gait and turn transition in
-    // the client. It stays HERE because the director saw the symptom and their eye outranks a
-    // derivation; what produces the reference's lingering kick is not yet known.
-    // …and the frozen node is NAMED (decision 0906), so the per-frame rate write
-    // ([`sync_base_rate`]) skips it instead of restarting the clock a line above just stopped.
-    //
-    // …and it is **the arc's own clip** that is stilled, never merely whatever bone 0 holds
-    // ([`holds_own_clip`]) — the predicate this always meant and never wrote down.
+    // Stills the cut airborne clip, so the gait fades in over a held kick as the reference shows.
+    // How the reference holds it is untraced, and it is no pose snapshot (its blend source keeps
+    // its own clock: `0x7125ea`, `0x7146b2`–`0x7147a5`), so this must not spread to other
+    // cross-fades. Only the arc's own clip is stilled; `frozen` names it for the rate write.
     if matches!(sp, Special::Jump | Special::Fall) {
         if let Some(node) = tr.get_main_animation() {
             if holds_own_clip(anims, catalog, sp, node) {
@@ -474,9 +348,7 @@ pub(super) fn leave_special(
                     *frozen = Some(node);
                 }
             } else if benilla_assets::trace::enabled() {
-                // The declined freeze is TRACED, because the wedge it used to cause was
-                // completely silent: nothing logs a clip being stopped, and a stopped clip that
-                // holds the base-anim lock ends the unit's animation for the session (2098).
+                // Traced, since a declined freeze is otherwise invisible.
                 let held = anims
                     .clips
                     .iter()
@@ -495,10 +367,8 @@ pub(super) fn leave_special(
     if let Some(next) = special {
         enter_special(lock, next, relaxed, tr, player, anims, catalog, rng, window)
     } else if matches!(sp, Special::Jump | Special::Fall) {
-        // The landing is a plain, freely-overwritten pick (decisions 0083/0087 (d)): the clip
-        // is chosen from the input *at touchdown* (`flags`) by the `0x602c60` dispatcher's rule,
-        // and re-picked the instant any movement flag changes — not a non-preemptible bracket.
-        // A backpedal/walk landing picks NO clip: the gait (WalkBackwards) starts the same frame.
+        // The land pick (`0x602c60`) from the flags at touchdown, freely overwritten: any flag
+        // change re-picks. A backpedal or walk landing picks none and the gait starts at once.
         match jump_land_pick(flags) {
             Some(id) => {
                 play(
diff --git a/crates/benilla-app/src/creature_anim/driver/tests.rs b/crates/benilla-app/src/creature_anim/driver/tests.rs
index a626940e..16c3903f 100644
--- a/crates/benilla-app/src/creature_anim/driver/tests.rs
+++ b/crates/benilla-app/src/creature_anim/driver/tests.rs
@@ -1,10 +1,4 @@
-//! Headless integration tests for [`super::drive_animations`] — the full driver system run in a
-//! minimal app on synthetic units, exercising the cross-frame composition the pure-fn tests in
-//! `select::tests` can't reach. First tenant: the caster staff-stow chain (decisions 0080/0107 —
-//! the stationary cast-hold gait pin feeding the per-animation sheath reconcile), pinned because
-//! vmangos hard-sets every creature's sheath byte to melee at spawn ("creatures always have melee
-//! weapon ready", `Creature.cpp`), so the cast-hold clip's WeaponFlags `&4` is the ONLY signal
-//! that ever stows a caster NPC's weapon.
+//! Headless tests of [`super::drive_animations`] on synthetic units, across frames.
 
 use bevy::animation::graph::AnimationNodeIndex;
 use bevy::animation::transition::AnimationTransitions;
@@ -22,15 +16,7 @@ use crate::names::type_flags::{DO_NOT_PLAY_WOUND_ANIM, MORE_AUDIBLE, NO_FACTION_
 use crate::net::NetCommands;
 use benilla_protocol::ObjectFields;
 
-/// A hand holding something that is **not a weapon** — a torch, a held-in-off-hand trinket.
-///
-/// Several fixtures below want a unit whose auto-attack swing is AttackUnarmed(16) *and* whose
-/// spell-kit clip is the armed Special1H(57). Since decision 1863 that combination needs a
-/// non-EMPTY hand: the reference's play-time substitution (`0x5fe2f0` @ `0x5fe3cc`, and our
-/// [`super::super::select::unarmed_special`]) keys on `GetWeapon(slot, 0)` being **NULL**, not on
-/// the item failing to be a weapon — so a held non-weapon keeps the armed special while the swing
-/// table still sends it to 16. An empty-handed unit plays SpecialUnarmed(118), which has its own
-/// test.
+/// A held non-weapon keeps Special1H(57): the substitution (`0x5fe3cc`) keys on an empty hand.
 fn holding_a_non_weapon() -> Wielded {
     Wielded {
         main: Some((15, 0)), // ItemClass 15 = miscellaneous
@@ -60,16 +46,15 @@ fn clip(anim_id: u16, node: u32, looping: bool) -> AnimClip {
     }
 }
 
-/// A staff-caster's model: Stand, Run, the staff Ready idle, and the precast hold clip (with a
-/// masked upper-body variant, so the committed-move route has its overlay destination).
+/// A staff caster: Stand, Run, the staff Ready idle and the precast hold, with a masked variant.
 fn caster_model() -> ModelAnimations {
-    let mut hold = clip(51, 3, true); // ReadySpellDirected — the precast hold
+    let mut hold = clip(51, 3, true); // ReadySpellDirected, the precast hold
     hold.upper_node = Some(AnimationNodeIndex::new(5));
     ModelAnimations {
         graph: Handle::default(),
         clips: vec![
             clip(0, 1, true),  // Stand
-            clip(28, 2, true), // Ready2HL — the staff-class Ready idle
+            clip(28, 2, true), // Ready2HL, the staff Ready idle
             hold,
             clip(5, 4, true), // Run
         ],
@@ -82,9 +67,8 @@ fn caster_model() -> ModelAnimations {
     }
 }
 
-/// The real 5875 rows this chain rests on (decode-verified in `anim_data::tests`):
-/// ReadySpellDirected carries the force-stow WeaponFlags `&4`, Ready2HL and Attack1H the
-/// force-draw `&0x20`.
+/// The real 5875 rows: ReadySpellDirected's WeaponFlags force-stow (`&4`), Ready2HL's and
+/// Attack1H's force-draw (`&0x20`).
 fn catalog() -> AnimData {
     AnimData(AnimDataCatalog::from_rows([
         (
@@ -118,28 +102,19 @@ fn catalog() -> AnimData {
     ]))
 }
 
-/// What a bare `app.update()` advances the harness clock by — small and nonzero, which is the
-/// regime every assertion in this file was written against (a real frame used to land here by
-/// accident). Zero is NOT equivalent: a frame with no delta never ticks a transition at all, so
-/// clips the tests expect to find mid-fade are never started.
+/// A bare `app.update()`'s clock step: nonzero, since a zero delta never ticks a transition.
 const FRAME_STEP: std::time::Duration = std::time::Duration::from_millis(1);
 
-/// The delta [`step_clock`] will use for the next frame, when a test asked for more than
-/// [`FRAME_STEP`]. It has to travel as a resource rather than a plain pre-`update()` call on
-/// `Time`, because `Time::advance_by` *sets* the frame's delta rather than accumulating it — so a
-/// value written before `update()` is simply overwritten by the in-frame step.
+/// The next frame's delta when a test asks for one; a resource, because `Time::advance_by` sets
+/// the delta rather than adding to it.
 #[derive(Resource, Default)]
 struct NextStep(Option<std::time::Duration>);
 
-/// The harness's whole clock, in place of `TimePlugin`'s real one (see [`app`]): one frame of
-/// [`FRAME_STEP`], or of whatever [`advance`] asked for.
 fn step_clock(mut time: ResMut<Time>, mut next: ResMut<NextStep>) {
     time.advance_by(next.0.take().unwrap_or(FRAME_STEP));
 }
 
-/// Run one frame whose delta is exactly `ms` — the only way time moves further than
-/// [`FRAME_STEP`] (see [`app`]). Replaces `thread::sleep` + `update()`: the same intent, but the
-/// delta is the number written here rather than however long the machine happened to take.
+/// Runs one frame whose delta is exactly `ms`.
 fn advance(app: &mut App, ms: u64) {
     app.world_mut().resource_mut::<NextStep>().0 = Some(std::time::Duration::from_millis(ms));
     app.update();
@@ -147,23 +122,10 @@ fn advance(app: &mut App, ms: u64) {
 
 fn app() -> App {
     let mut app = App::new();
-    // The client's ONE `rand()` stream (2301) — the play's variation and replay rolls.
+    // The client's one `rand()` stream: the variation and replay rolls.
     app.init_resource::<benilla_assets::AnimRng>();
-    // Asset + animation plugins so tests with REAL clip assets (the watchdog test) get Bevy's
-    // `advance_animations` ticking completions; units without a graph handle are skipped by it,
-    // so the asset-less tenants are unaffected.
-    //
-    // **`TimePlugin` is deliberately disabled, and the clock is ours** ([`step_clock`]). With it,
-    // `Time`'s delta is the REAL gap between two `app.update()` calls, and this file is full of
-    // assertions that a fade or clip is still mid-flight. A stalled frame — parallel `cargo test`
-    // on a loaded machine, a debugger, a cold page — then runs the whole fade out in one delta and
-    // the clip is gone from the player, which is a coin flip rather than a test: it red-lit main's
-    // gates on 2026-08-06 in `the_swim_relatch_holds_the_kick_but_a_ground_cut_freezes_it`, and
-    // injecting a 400 ms stall before that test's ground cut reproduces the failure exactly. The
-    // tests that DO need time to pass used to buy it with `thread::sleep`, which is the same coin
-    // flip pointed the other way; they now say how far the clock moves, through [`advance`].
-    //
-    // The step is small-but-nonzero rather than zero on purpose — see [`FRAME_STEP`].
+    // Completions tick only for units with a real graph asset. `TimePlugin` is off and the clock
+    // is `step_clock`: a real-time delta lets a stalled frame run a whole fade out.
     app.add_plugins((
         MinimalPlugins.build().disable::<bevy::time::TimePlugin>(),
         AssetPlugin::default(),
@@ -181,8 +143,7 @@ fn app() -> App {
         .add_message::<WoundAnim>()
         .add_message::<SheathRequest>()
         .add_message::<SheathSwapMessage>();
-    // A dead-letter net channel: the driver's `let _ = send(...)` tolerates the dropped receiver,
-    // and no test unit is the self player anyway.
+    // A dead-letter net channel; the driver tolerates the dropped receiver.
     let (tx, _rx) = crossbeam_channel::unbounded();
     app.insert_resource(NetCommands(tx));
     app.init_resource::<crate::names::NameCache>();
@@ -191,10 +152,8 @@ fn app() -> App {
     app
 }
 
-/// The caster-NPC staff chain, end to end through the real system: engaged Ready draws (reconcile
-/// rule 4), the stationary cast hold's gait pin stows (rule 1 — `&4` outranks engaged), the hold's
-/// removal re-draws. The director's report ("caster NPC still holds their staff while casting")
-/// is exactly this middle assertion.
+/// vmangos sets every creature's sheath to melee at spawn (`Creature.cpp:605`), so the hold clip's
+/// force-stow is what stows a caster's staff.
 #[test]
 fn stationary_cast_hold_stows_an_engaged_casters_weapon() {
     let mut app = app();
@@ -224,12 +183,9 @@ fn stationary_cast_hold_stows_an_engaged_casters_weapon() {
             .sheath_state()
     };
 
-    // Engaged, stationary, no cast: the Ready idle forces melee-drawn.
     app.update();
     assert_eq!(sheath(&app), Some(1), "engaged Ready idle draws");
 
-    // SMSG_SPELL_START landed (the router inserted the precast hold): the stationary pin plays
-    // ReadySpellDirected full-body in the gait slot, and its WeaponFlags `&4` force-stows.
     app.world_mut().entity_mut(unit).insert(CastHold {
         ranged: false,
         anim_id: 51,
@@ -238,17 +194,12 @@ fn stationary_cast_hold_stows_an_engaged_casters_weapon() {
     app.update();
     assert_eq!(sheath(&app), Some(0), "the cast hold stows the staff");
 
-    // GO (the router removed the hold): the engaged Ready re-takes the slot and re-draws.
     app.world_mut().entity_mut(unit).remove::<CastHold>();
     app.update();
     assert_eq!(sheath(&app), Some(1), "drawn again once the cast resolves");
 }
 
-/// 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`), 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.
+/// The reconcile runs only inside `PlayAnimation` (`0x5fdf80`), so a playless frame keeps the stow.
 #[test]
 fn moving_cast_hold_keeps_its_stow_between_plays() {
     let mut app = app();
@@ -283,12 +234,9 @@ fn moving_cast_hold_keeps_its_stow_between_plays() {
             .sheath_state()
     };
 
-    // Engaged and running: the flags-less Run gait plays, the engaged re-assert draws.
     app.update();
     assert_eq!(sheath(&app), Some(1), "engaged runner draws");
 
-    // The precast lands mid-move: the hold takes the masked overlay route — its retake is a play,
-    // so the reconcile stows.
     app.world_mut().entity_mut(unit).insert(CastHold {
         ranged: false,
         anim_id: 51,
@@ -297,33 +245,22 @@ fn moving_cast_hold_keeps_its_stow_between_plays() {
     app.update();
     assert_eq!(sheath(&app), Some(0), "the masked hold's retake stows");
 
-    // Frames where nothing plays (the gait loop wraps, the hold loops): the committed state holds.
     for _ in 0..3 {
         app.update();
         assert_eq!(sheath(&app), Some(0), "no play — the stow persists");
     }
 
-    // GO while still running: the hold drops, but the base Run keeps looping — still no play, so
-    // the staff stays stowed (the client re-draws only at the next play).
     app.world_mut().entity_mut(unit).remove::<CastHold>();
     app.update();
     assert_eq!(sheath(&app), Some(0), "released mid-run — no play yet");
 
-    // The creature stops: the engaged Ready idle plays, and that play's reconcile re-draws.
     app.world_mut().entity_mut(unit).remove::<MovementState>();
     app.update();
     assert_eq!(sheath(&app), Some(1), "the stop's Ready play re-draws");
 }
 
-/// A fidgeter's model, on **real Bevy clip assets** (see [`spawn_vendor`] for why: this tenant now
-/// runs to a window completion, and `completions()` only ticks for a real graph): Stand as a
-/// two-variation chain — a zero-frequency head plus a max-frequency "look around" variation, so
-/// the first `_rand` roll (38, from the LCG's zero seed) deterministically lands on the variation —
-/// and a ShuffleLeft for the turn latch. Stand's span is long enough that its own window never
-/// completes inside the test; the shuffle's is short so the test does not have to run a real
-/// half-second to reach the release.
-///
-/// Returns the entity and the graph nodes in clip order: Stand-head, Stand-look, ShuffleLeft.
+/// A fidgeter on real clip assets: Stand's zero-frequency head and max-frequency look-around (the
+/// LCG's first roll, 38, lands on it) and a short ShuffleLeft. Nodes: head, look, shuffle.
 fn spawn_fidgeter(app: &mut App) -> (Entity, Vec<AnimationNodeIndex>) {
     use bevy::animation::graph::{AnimationGraph, AnimationGraphHandle};
     use bevy::animation::AnimationClip;
@@ -356,8 +293,8 @@ fn spawn_fidgeter(app: &mut App) -> (Entity, Vec<AnimationNodeIndex>) {
     let anims = ModelAnimations {
         graph: graph_handle.clone(),
         clips: vec![
-            seq(0, nodes[0], STAND_SPAN, 0),     // Stand — the head variation
-            seq(0, nodes[1], STAND_SPAN, 32767), // Stand — the rare look-around variation
+            seq(0, nodes[0], STAND_SPAN, 0),     // Stand, the head
+            seq(0, nodes[1], STAND_SPAN, 32767), // Stand, the rare look-around
             seq(11, nodes[2], SHUFFLE_SPAN, 0),  // ShuffleLeft
         ],
         hand_close: [None, None],
@@ -380,17 +317,8 @@ fn spawn_fidgeter(app: &mut App) -> (Entity, Vec<AnimationNodeIndex>) {
     (unit, nodes)
 }
 
-/// 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.
-///
-/// **What the return is triggered BY changed in 1655**, and that is the middle of this test. 0123
-/// had the shuffle released the frame the yaw ease settled; the reference cannot do that
-/// (`0x607ed0`'s tail refuses to recompute a shuffle with no turn bit set — `0x5fce30`'s gate),
-/// and releases it a clip window later through the completion callback instead. The churn 0123
-/// describes is intact and the re-roll still rides it; it simply happens at the window boundary,
-/// which is also why the shuffle is long enough to be seen.
+/// A relaxed arm rolls its variation (`variationIdx = −1`), and the shuffle, released at its own
+/// window's end since `0x607ed0`'s tail cannot stop it (`0x5fce30`), re-rolls Stand.
 #[test]
 fn relaxed_base_arms_roll_variations_and_the_shuffle_drives_them() {
     let mut app = app();
@@ -405,20 +333,17 @@ fn relaxed_base_arms_roll_variations_and_the_shuffle_drives_them() {
     };
     let gait = |app: &App| app.world().entity(unit).get::<AnimDriver>().unwrap().gait;
 
-    // The first (relaxed) Stand arm rolls: the weighted walk lands on the look-around variation.
     app.update();
     assert_eq!(gait(&app), Some(0));
     assert!(active(&app, nodes[1]), "the rolled variation is what armed");
     assert!(!active(&app, nodes[0]), "not the head");
 
-    // The idle re-face steps its yaw: the turn latch routes the gait to the foot-shuffle.
     app.world_mut()
         .entity_mut(unit)
         .insert(crate::net::FacingStep(0.3));
     app.update();
     assert_eq!(gait(&app), Some(11), "stepping yaw → ShuffleLeft");
 
-    // The ease settles — and the feet keep going, because the settle is not what releases them.
     app.world_mut()
         .entity_mut(unit)
         .remove::<crate::net::FacingStep>();
@@ -429,8 +354,6 @@ fn relaxed_base_arms_roll_variations_and_the_shuffle_drives_them() {
         "the settle does not release the shuffle (1655)"
     );
 
-    // Its window completes: THAT is the release, and the re-selection it runs re-arms Stand with a
-    // fresh roll — the fidget.
     for _ in 0..6 {
         advance(&mut app, 25);
     }
@@ -441,8 +364,7 @@ fn relaxed_base_arms_roll_variations_and_the_shuffle_drives_them() {
     );
 }
 
-/// The combat carve-out: an engaged unit's base arms keep the deterministic head — fighters
-/// never fidget (the client's `0x5fdba0` re-zero gate).
+/// An engaged unit's base arms keep the head: `0x5fdba0` re-zeroes the variation.
 #[test]
 fn engaged_base_arms_keep_the_head_variation() {
     let mut app = app();
@@ -450,7 +372,7 @@ fn engaged_base_arms_keep_the_head_variation() {
     app.world_mut().entity_mut(unit).insert(Engaged(0));
     app.update();
     let player = app.world().entity(unit).get::<AnimationPlayer>().unwrap();
-    // Engaged with no weapon: the Ready pick resolves down to Stand — armed as the HEAD.
+    // No weapon: the Ready pick resolves down to Stand.
     assert!(player.animation(nodes[0]).is_some(), "the head variation");
     assert!(
         player.animation(nodes[1]).is_none(),
@@ -458,17 +380,11 @@ fn engaged_base_arms_keep_the_head_variation() {
     );
 }
 
-/// The GnollCaster case (decision 0125 — the director's ref falsification of the resolved-id
-/// reading): a model with NO spell animations at all falls back to a flags-less Stand for
-/// *playback*, but the sheath reconcile tests the **requested** id — ReadySpellDirected's own
-/// force-stow row — so the staff still leaves the hand for the whole windup, exactly like the
-/// ref's Redridge Mystic.
+/// The sheath reconcile tests the requested id, so a model that plays Stand for the hold stows.
 #[test]
 fn cast_hold_stows_even_when_the_model_lacks_the_spell_anims() {
     let mut app = app();
-    // A gnoll-shaped model: Stand and a Ready idle only — no 51/53 anywhere — with the real
-    // gnoll's baked lookup shape (row 51 → Stand), so playback of the hold genuinely lands on
-    // the flags-less Stand clip and only the requested id's own row can stow.
+    // A gnoll's shape: Stand and a Ready idle, no 51, and a baked lookup sending 51 to Stand.
     let mut lookup = vec![
         benilla_formats::PlayableAnim {
             resolved_id: 0,
@@ -516,8 +432,6 @@ fn cast_hold_stows_even_when_the_model_lacks_the_spell_anims() {
     app.update();
     assert_eq!(sheath(&app), Some(1), "engaged Ready draws");
 
-    // The precast hold requests 51; playback resolves to Stand (the model has nothing better),
-    // but 51's own WeaponFlags `&4` still force the stow.
     app.world_mut().entity_mut(unit).insert(CastHold {
         ranged: false,
         anim_id: 51,
@@ -535,11 +449,7 @@ fn cast_hold_stows_even_when_the_model_lacks_the_spell_anims() {
     assert_eq!(sheath(&app), Some(1), "re-drawn once the cast resolves");
 }
 
-/// A spell-side flinch rides the wound **secondary slot**, never the one-shot route — the
-/// client's `0x60ea70(severity = 0)` from the kit player's 8–10 branch, the harmful instant
-/// impact, or the missile arrival (decision 2058): the [`WoundAnim`] edge arms the decaying
-/// overlay and the base track keeps playing untouched underneath (routing it as a one-shot would
-/// replace the base — the exact mistake decision 0111 falsified for melee).
+/// A spell flinch is `0x60ea70(severity = 0)`: a decaying overlay, the base left untouched.
 #[test]
 fn spell_impact_wound_rides_the_secondary_slot() {
     let mut app = app();
@@ -547,7 +457,7 @@ fn spell_impact_wound_rides_the_secondary_slot() {
         graph: Handle::default(),
         clips: vec![
             clip(0, 1, true),  // Stand
-            clip(8, 2, false), // StandWound — the unengaged victim's severity-0 pick
+            clip(8, 2, false), // StandWound, the unengaged severity-0 pick
         ],
         hand_close: [None, None],
         playable_animation_lookup: Vec::new(),
@@ -586,9 +496,7 @@ fn spell_impact_wound_rides_the_secondary_slot() {
     );
 }
 
-/// The spell flinch is the client's **severity-0** wound call (decision 2058): it never carries
-/// the kit's own id, so the clip is CombatWound(9) on an engaged victim and StandWound(8) on an
-/// unengaged one — `0x60ea70`'s `(severity, engaged)` pick, the same as a non-crit melee hit.
+/// A spell flinch is severity 0, so `0x60ea70` picks CombatWound(9) engaged, StandWound(8) not.
 #[test]
 fn spell_flinch_picks_the_wound_by_engagement() {
     fn model() -> ModelAnimations {
@@ -598,7 +506,7 @@ fn spell_flinch_picks_the_wound_by_engagement() {
                 clip(0, 1, true),   // Stand
                 clip(8, 2, false),  // StandWound
                 clip(9, 3, false),  // CombatWound
-                clip(10, 4, false), // CombatCritical — a spell flinch must never land here
+                clip(10, 4, false), // CombatCritical, never a spell flinch
             ],
             hand_close: [None, None],
             playable_animation_lookup: Vec::new(),
@@ -644,11 +552,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`; 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.
+/// A CharProc-11 rate-override node refuses every flinch (`0x60eaac`–`0x60eac8`), by its presence:
+/// kit 3071 at rate 1.0 closes the gate like a freeze at 0.0.
 #[test]
 fn a_rate_override_node_refuses_the_wound() {
     fn model() -> ModelAnimations {
@@ -713,10 +618,7 @@ fn a_rate_override_node_refuses_the_wound() {
     assert!(wounded(free), "no node: the flinch lays as before");
 }
 
-/// The whiff slow-down touches SWING anims only (decision 0279's scoping): a spell kit's
-/// full-body special (Special1H 57) rides the same `Mode::Swing` slot, and a concurrent
-/// auto-attack miss must not drag it to half speed — the director's "the Eviscerate spin
-/// drags". A real swing keeps the verified 0.5 write.
+/// The whiff's 0.5× touches swings only, not a kit special in the same `Mode::Swing` slot.
 #[test]
 fn whiff_slowdown_spares_a_non_swing_oneshot() {
     let mut app = app();
@@ -724,8 +626,8 @@ fn whiff_slowdown_spares_a_non_swing_oneshot() {
         graph: Handle::default(),
         clips: vec![
             clip(0, 1, true),   // Stand
-            clip(57, 2, false), // Special1H — Eviscerate's kit anim
-            clip(16, 3, false), // AttackUnarmed — the bare-hands swing
+            clip(57, 2, false), // Special1H, Eviscerate's kit anim
+            clip(16, 3, false), // AttackUnarmed
         ],
         hand_close: [None, None],
         playable_animation_lookup: Vec::new(),
@@ -756,7 +658,6 @@ fn whiff_slowdown_spares_a_non_swing_oneshot() {
         .id();
     app.update(); // settle: Stand holds both gait slots
 
-    // The kit anim plays as a full-body one-shot; the swing as its own.
     app.world_mut().write_message(EmoteAnim {
         entity: spinner,
         anim_id: 57,
@@ -766,13 +667,12 @@ fn whiff_slowdown_spares_a_non_swing_oneshot() {
         attacker: swinger,
         victim: None,
         hit_info: 0,
-        victim_state: 2, // dodge — the whiff class
+        victim_state: 2, // dodge, a whiff
         damage: 0,
         displayed: true,
         seq: 2,
     });
     app.update();
-    // Both whiff the same frame the one-shots are in flight.
     app.world_mut()
         .write_message(crate::creature_anim::SwingSlowdown(spinner));
     app.world_mut()
@@ -800,12 +700,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,
-/// `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
-/// auto-swings its cast triggers — sped up, never cut.
+/// The combat fast path (`0x5fe43c`–`0x5fe48b`): the first in wire order doubles, the second parks.
 #[test]
 fn same_frame_collision_fast_paths_the_second_combat_clip() {
     let mut app = app();
@@ -813,7 +708,7 @@ fn same_frame_collision_fast_paths_the_second_combat_clip() {
         graph: Handle::default(),
         clips: vec![
             clip(0, 1, true),   // Stand
-            clip(57, 2, false), // Special1H — Eviscerate's kit anim
+            clip(57, 2, false), // Special1H, Eviscerate's kit anim
             clip(16, 3, false), // the bare-hands swing
         ],
         hand_close: [None, None],
@@ -838,7 +733,7 @@ fn same_frame_collision_fast_paths_the_second_combat_clip() {
     let swing_last = unit();
     app.update(); // settle: Stand holds both gait slots
 
-    // spin_last: the kit anim arrived after the swing on the wire — the spin must win.
+    // spin_last: the swing arrives first on the wire.
     app.world_mut().write_message(SwingMessage {
         attacker: spin_last,
         victim: None,
@@ -853,7 +748,7 @@ fn same_frame_collision_fast_paths_the_second_combat_clip() {
         anim_id: 57,
         seq: 2,
     });
-    // swing_last: the wire order reversed — the swing must win.
+    // swing_last: the spin arrives first.
     app.world_mut().write_message(EmoteAnim {
         entity: swing_last,
         anim_id: 57,
@@ -882,8 +777,6 @@ fn same_frame_collision_fast_paths_the_second_combat_clip() {
             .expect("armed clip in flight")
             .speed()
     };
-    // Swing first on the wire: the swing arms, the spin fast-paths — the swing doubles and the
-    // spin parks (it plays when the swing ends; the ref's swing-first batch shows exactly this).
     assert_eq!(
         drv(&app, spin_last).mode,
         super::super::select::Mode::Swing {
@@ -894,8 +787,6 @@ fn same_frame_collision_fast_paths_the_second_combat_clip() {
     );
     assert_eq!(drv(&app, spin_last).deferred, Some(57), "the spin parks");
     assert_eq!(speed(&app, spin_last, 3), 2.0, "the armed swing doubles");
-    // Spin first on the wire (the trace's t=106 batch): the spin arms and SURVIVES the swing —
-    // doubled, with the swing parked behind it. The old last-call-wins model ate the spin here.
     assert_eq!(
         drv(&app, swing_last).mode,
         super::super::select::Mode::Swing {
@@ -908,10 +799,8 @@ fn same_frame_collision_fast_paths_the_second_combat_clip() {
     assert_eq!(speed(&app, swing_last, 2), 2.0, "the spin doubles");
 }
 
-/// The deferred-cache consumer (the client's `+0xd60` read at the base recompute): the moment no
-/// one-shot is live, the parked combat clip plays — the swing the spin deferred fires once the
-/// spin ends, at normal rate. Hand-sets the cache with the body idle (the state the instant the
-/// spin finished) because the headless harness never advances clips to completion.
+/// The base recompute's `+0xd60` read plays a parked clip, at normal rate, once no one-shot is
+/// live. The cache is set by hand: these stand-in clips never complete.
 #[test]
 fn deferred_combat_clip_plays_once_the_body_frees() {
     let mut app = app();
@@ -965,12 +854,7 @@ fn deferred_combat_clip_plays_once_the_body_frees() {
     assert_eq!(speed, 1.0, "a consumed clip plays at normal rate");
 }
 
-/// The post-shot leg slide (director-observed vs ref): a one-shot that routed FULL-BODY while
-/// standing must yield to the gait the instant the movement flags change — the client's
-/// locomotion re-arm lands on the change and blindly overwrites bone 0 (the decision 0280
-/// re-arm; `Mode::Land` re-picks on the same edge). Holding the clip out slides the runner
-/// over the ground on straight legs. The edge is the trigger, not the level: with the flags
-/// steady the clip plays out (third assertion, via the boneless masked fallback's moving entry).
+/// A movement-flag change re-arms the base over a full-body one-shot; steady flags let it finish.
 #[test]
 fn a_movement_flag_change_cuts_a_full_body_oneshot_immediately() {
     let mut app = app();
@@ -979,7 +863,7 @@ fn a_movement_flag_change_cuts_a_full_body_oneshot_immediately() {
         clips: vec![
             clip(0, 1, true),   // Stand
             clip(5, 2, true),   // Run
-            clip(16, 3, false), // the bare-hands swing (1.0 s — far from finished)
+            clip(16, 3, false), // the bare-hands swing, 1.0 s
         ],
         hand_close: [None, None],
         playable_animation_lookup: Vec::new(),
@@ -1001,7 +885,6 @@ fn a_movement_flag_change_cuts_a_full_body_oneshot_immediately() {
     app.update(); // settle: Stand
     let mode = |app: &App| app.world().entity(unit).get::<AnimDriver>().unwrap().mode;
 
-    // A standing swing routes full-body onto the base track.
     app.world_mut().write_message(SwingMessage {
         attacker: unit,
         victim: None,
@@ -1021,8 +904,6 @@ fn a_movement_flag_change_cuts_a_full_body_oneshot_immediately() {
         "standing swing holds the base track"
     );
 
-    // The player starts running one frame later: the flag change must re-pick the gait NOW,
-    // not when the 1.0 s clip finishes.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FORWARD,
         ..Default::default()
@@ -1034,7 +915,6 @@ fn a_movement_flag_change_cuts_a_full_body_oneshot_immediately() {
         "the movement-flag change cuts the swing to the gait immediately"
     );
 
-    // Steady flags: a fresh standing swing plays out (still Swing on the very next frame).
     app.world_mut()
         .entity_mut(unit)
         .insert(MovementState::default());
@@ -1056,18 +936,12 @@ 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
-/// (`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).
+/// The cast pin tests `[9e8] & 0x20000f` (`0x5fde80`), never the turn bits.
 #[test]
 fn turning_in_place_never_unpins_the_stationary_cast_hold() {
     let mut app = app();
     let mut model = caster_model();
-    model.clips.push(clip(11, 7, true)); // ShuffleLeft — the churn destination the bug routed to
+    model.clips.push(clip(11, 7, true)); // ShuffleLeft
     let unit = app
         .world_mut()
         .spawn((
@@ -1094,7 +968,6 @@ fn turning_in_place_never_unpins_the_stationary_cast_hold() {
     app.update();
     assert_eq!(playing(&app), (Some(51), None), "stationary: the hold pins");
 
-    // Flap the chase-step TURN flag across frames (mouse delta / quiet / delta …).
     for frame in 0..6u32 {
         let flags = if frame % 2 == 0 {
             move_flags::TURN_LEFT
@@ -1113,7 +986,6 @@ fn turning_in_place_never_unpins_the_stationary_cast_hold() {
         );
     }
 
-    // Real translation still demotes: the gait leaves the pin and the masked hold takes over.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FORWARD,
         speed: 7.0,
@@ -1125,9 +997,7 @@ fn turning_in_place_never_unpins_the_stationary_cast_hold() {
     assert_eq!(overlay, Some(51), "…and loops the hold masked on the torso");
 }
 
-/// The swim re-latch does NOT cut the hop's kick (decision 0517, director-corrected — amends
-/// 0503's swim arm): JumpStart PLAYS OUT over the re-latch, the swim gait waiting at its end.
-/// A GROUND cut (landing on a bank) still cuts immediately with 0503's pose-snapshot freeze.
+/// JumpStart plays out over a swim re-latch; a ground landing still cuts it, stilled.
 #[test]
 fn the_swim_relatch_holds_the_kick_but_a_ground_cut_freezes_it() {
     let mut app = app();
@@ -1137,7 +1007,7 @@ fn the_swim_relatch_holds_the_kick_but_a_ground_cut_freezes_it() {
             clip(0, 1, true),   // Stand
             clip(41, 2, true),  // SwimIdle
             clip(42, 3, true),  // Swim
-            clip(37, 4, false), // JumpStart — the kick (833 ms real; the test never advances it)
+            clip(37, 4, false), // JumpStart, the kick
             clip(38, 5, true),  // Jump hang
             clip(39, 6, false), // JumpEnd
         ],
@@ -1161,7 +1031,6 @@ fn the_swim_relatch_holds_the_kick_but_a_ground_cut_freezes_it() {
     app.update(); // settle: Stand
     let drv = |app: &App| app.world().entity(unit).get::<AnimDriver>().unwrap().mode;
 
-    // The dolphin hop launches: FALLING with an upward seed → the JumpStart bracket enters.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FALLING | move_flags::FORWARD,
         vertical_speed: 9.0,
@@ -1175,8 +1044,7 @@ fn the_swim_relatch_holds_the_kick_but_a_ground_cut_freezes_it() {
         "the upward launch enters the JumpStart bracket"
     );
 
-    // Swim re-latches ~0.24 s later, mid-kick: the kick is HELD — no cut, no gait yet — and
-    // keeps PLAYING (speed 1, not 0503's frozen ground-cut).
+    // Swim re-latches mid-kick.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::SWIMMING | move_flags::FORWARD,
         speed: 4.7,
@@ -1199,8 +1067,7 @@ fn the_swim_relatch_holds_the_kick_but_a_ground_cut_freezes_it() {
         "held, not frozen — the kick keeps playing"
     );
 
-    // A GROUND cut is unchanged: a fresh hop that lands on a bank (flags drop to grounded,
-    // no SWIMMING) cuts immediately — Land pick + the 0503 snapshot-freeze on the kick.
+    // Landing on a bank instead.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: 0,
         ..Default::default()
@@ -1222,11 +1089,7 @@ fn the_swim_relatch_holds_the_kick_but_a_ground_cut_freezes_it() {
     );
 }
 
-/// The loot kneel, REMOTE half (the `0x5fd8b0` chain's loot leg → Loot 50, decision 0515):
-/// `UNIT_FLAG_LOOTING` (`UNIT_FIELD_FLAGS` = field 46, bit 0x400 — up exactly while the unit's
-/// corpse-loot window is open) holds the authored-clamp kneel in a stationary unit's gait slot;
-/// movement suppresses it (the chain's locomotion-first order); the flag dropping (the loot
-/// release's round-trip) hands the slot back to Stand.
+/// A remote unit kneels on `UNIT_FLAG_LOOTING` (field 46); moving outranks it (`0x5fd8b0`).
 #[test]
 fn unit_flag_looting_kneels_stationary_units_only() {
     use benilla_protocol::messages::ObjectFields;
@@ -1254,11 +1117,9 @@ fn unit_flag_looting_kneels_stationary_units_only() {
         .id();
     let gait = |app: &App| app.world().entity(unit).get::<AnimDriver>().unwrap().gait;
 
-    // Stationary with the flag up: the kneel takes the gait slot.
     app.update();
     assert_eq!(gait(&app), Some(50), "looting kneels");
 
-    // Movement outranks the kneel.
     app.world_mut().entity_mut(unit).insert(MovementState {
         speed: 7.0,
         flags: move_flags::FORWARD,
@@ -1267,7 +1128,6 @@ fn unit_flag_looting_kneels_stationary_units_only() {
     app.update();
     assert_eq!(gait(&app), Some(5), "a moving looter runs");
 
-    // Stopped again with the flag down (the release landed): back to Stand.
     app.world_mut().entity_mut(unit).remove::<MovementState>();
     app.world_mut()
         .entity_mut(unit)
@@ -1278,14 +1138,7 @@ fn unit_flag_looting_kneels_stationary_units_only() {
     assert_eq!(gait(&app), Some(0), "released — back to Stand");
 }
 
-/// The loot kneel, SELF half (decision 0515 — the byte predicate `0x6126b0` splits on
-/// IsActivePlayer): the local player's kneel rides the client-local loot-target latch
-/// (predicate B's standing answer over the `[player+0x1d28]` latch — [`crate::ui_loot::LootKneel`],
-/// decision 1477) — NOT its descriptor flag — so it starts the frame the arm lands
-/// (client-predicted, before any server response reaches the descriptor) and ends the frame it
-/// drops. *Which* latched objects set that boolean is predicate B's own table, tested where it
-/// lives (`ui_loot::tests::predicate_b_decides_which_loot_targets_are_knelt_at`); this test is
-/// about the leg reading self and remote from two different places.
+/// The self unit kneels off its loot latch (`[player+0x1d28]`, `0x6126b0`), not the flag.
 #[test]
 fn the_self_kneel_rides_the_loot_latch_not_the_flag() {
     use benilla_protocol::messages::ObjectFields;
@@ -1302,8 +1155,7 @@ fn the_self_kneel_rides_the_loot_latch_not_the_flag() {
         first_seq: None,
         pose: Default::default(),
     };
-    // A SELF unit whose descriptor carries UNIT_FLAG_LOOTING but whose latch is empty: no kneel —
-    // the flag is the REMOTE trigger only.
+    // The descriptor flag is set, the latch empty.
     let unit = app
         .world_mut()
         .spawn((
@@ -1325,14 +1177,12 @@ fn the_self_kneel_rides_the_loot_latch_not_the_flag() {
         "the self unit ignores its own descriptor flag"
     );
 
-    // The arm lands on a kneelable target: the kneel is client-predicted the same frame cycle.
     app.world_mut()
         .resource_mut::<crate::ui_loot::LootKneel>()
         .0 = true;
     app.update();
     assert_eq!(gait(&app), Some(50), "the armed latch kneels the self unit");
 
-    // The release/refusal drops the latch: straight back to Stand, no wire round-trip needed.
     app.world_mut()
         .resource_mut::<crate::ui_loot::LootKneel>()
         .0 = false;
@@ -1344,12 +1194,8 @@ fn the_self_kneel_rides_the_loot_latch_not_the_flag() {
     );
 }
 
-/// **B114's second half, end to end**: the prowl pose off the descriptor, through the real driver.
-/// The CREEP vis flag (`UNIT_FIELD_BYTES_1` byte 3 bit 1 — field 138, `0x0200_0000`) is the whole
-/// gate, and it is read from the unit's own descriptor for the SELF unit too (unlike the loot kneel
-/// above, which splits self/remote): there is no client-side prediction of stealth, so the crouch
-/// arrives with the server's aura. Stand ⇄ StealthStand and Run ⇄ StealthWalk both flip on the bit
-/// alone, with no other state changing.
+/// The CREEP vis flag (`UNIT_FIELD_BYTES_1` byte 3 bit 1, field 138) alone flips the prowl pose,
+/// read off the self unit's own descriptor too.
 #[test]
 fn the_creep_vis_flag_prowls_the_body() {
     use benilla_protocol::messages::ObjectFields;
@@ -1395,12 +1241,10 @@ fn the_creep_vis_flag_prowls_the_body() {
     app.update();
     assert_eq!(gait(&app), Some(0), "unstealthed idle stands");
 
-    // The stealth aura landed: the same standing unit drops into the crouch.
     set_flag(&mut app, CREEP);
     app.update();
     assert_eq!(gait(&app), Some(120), "the CREEP bit crouches the idle");
 
-    // Moving while stealthed creeps — at a speed that would otherwise be a flat-out Run.
     app.world_mut().entity_mut(unit).insert(MovementState {
         speed: 7.0,
         flags: move_flags::FORWARD,
@@ -1409,18 +1253,12 @@ fn the_creep_vis_flag_prowls_the_body() {
     app.update();
     assert_eq!(gait(&app), Some(119), "the prowl outranks the speed tail");
 
-    // Stealth broke mid-run: straight back to the ordinary gait, nothing else touched.
     set_flag(&mut app, 0);
     app.update();
     assert_eq!(gait(&app), Some(5), "broken stealth runs again");
 }
 
-/// 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
-/// gryphon's flap/glide alternation and the multi-part /dance in miniature. (The pre-0516 driver
-/// armed once and wrapped forever: one variation on screen, the other never.)
+/// The watchdog (`0x719370`) re-arms a loop at each window's end through the variation walk.
 #[test]
 fn a_looping_arm_advances_through_its_variations_at_window_end() {
     use bevy::animation::graph::{AnimationGraph, AnimationGraphHandle};
@@ -1492,11 +1330,9 @@ fn a_looping_arm_advances_through_its_variations_at_window_end() {
     );
 }
 
-/// A jumper's model for the decision 0864 suite: the airborne bracket (JumpStart/Jump hang/
-/// JumpEnd/Fall), the gaits, a spell-kit cast anim (SpellCastOmni 54, with a masked variant),
-/// and the combat pair (Special1H 57 / AttackUnarmed 16) for the mid-air fast-path tenant.
+/// A jumper: the airborne clips, Stand and Run, a kit cast with a masked variant, a combat pair.
 fn jumper_model() -> ModelAnimations {
-    let mut cast = clip(54, 7, false); // SpellCastOmni — the kit release anim
+    let mut cast = clip(54, 7, false); // SpellCastOmni, a kit's release anim
     cast.upper_node = Some(AnimationNodeIndex::new(8));
     ModelAnimations {
         graph: Handle::default(),
@@ -1508,8 +1344,8 @@ fn jumper_model() -> ModelAnimations {
             clip(39, 5, false), // JumpEnd
             clip(40, 6, true),  // Fall
             cast,
-            clip(57, 9, false),  // Special1H — a spell kit's combat one-shot
-            clip(16, 10, false), // AttackUnarmed — the bare-hands swing
+            clip(57, 9, false),  // Special1H, a kit's combat one-shot
+            clip(16, 10, false), // AttackUnarmed
         ],
         hand_close: [None, None],
         playable_animation_lookup: Vec::new(),
@@ -1533,18 +1369,14 @@ fn jumper(app: &mut App) -> Entity {
         .id()
 }
 
-/// **The director's hillside jump** (decision 1137): a run across broken ground micro-detaches for
-/// a frame, and the jump pressed in that window lands and relaunches inside one frame — FALLING
-/// never drops, so the old FALLING-edge sample never re-ran and the arc kept the detachment's
-/// `jump_arc = false`. The body sailed upward playing the run gait.
+/// A jump that relaunches inside a one-frame detachment, FALLING never dropping, is a jump.
 #[test]
 fn a_jump_out_of_a_micro_detachment_still_enters_the_jump_bracket() {
     let mut app = app();
     let unit = jumper(&mut app);
     app.update(); // settle: Stand
     let mode = |app: &App| app.world().entity(unit).get::<AnimDriver>().unwrap().mode;
-    // One frame of detachment while running: FALLING with a *downward* speed is a step-off arc —
-    // no bracket, the gait freezes, which is correct on its own (decision 0868).
+    // A one-frame detachment: FALLING with a downward speed is a step-off arc.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FALLING | move_flags::FORWARD,
         speed: 7.0,
@@ -1557,8 +1389,7 @@ fn a_jump_out_of_a_micro_detachment_still_enters_the_jump_bracket() {
         super::super::select::Mode::Gait,
         "a downward launch is a step-off: the gait holds"
     );
-    // The jump fires out of that frame: the body lands and relaunches within the frame, so FALLING
-    // is set on this frame too and the bit never toggled. The launch is still a launch.
+    // The jump lands and relaunches within the frame, so FALLING never toggles.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FALLING | move_flags::FORWARD,
         speed: 7.0,
@@ -1573,10 +1404,7 @@ 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 (`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.
+/// Only a rise past the threshold launches, so a step-off keeps its freeze (`0x5fd8e8`).
 #[test]
 fn a_deepening_step_off_fall_never_becomes_a_jump() {
     let mut app = app();
@@ -1599,13 +1427,8 @@ fn a_deepening_step_off_fall_never_becomes_a_jump() {
     }
 }
 
-/// The ref's jump-in-place cast (decision 0864 — the report this pins): a cast id is CLASS_A
-/// but NOT COMBAT, so the airborne route test doesn't mask it — with no move bits it routes
-/// FULL-BODY and REPLACES the jump hang on bone 0 (the client's one-slot last-writer-wins; the
-/// old machine dropped it, which is why the cast only showed on *walking* jumps). The clip then
-/// rides the airborne-freeze: the continuing Jump level must NOT re-preempt it — the client
-/// issues no plays mid-arc, so the clip plays out (and a finished one clamps and holds) until
-/// an edge.
+/// A cast id is CLASS_A but not COMBAT, so a jump in place routes it full-body over the hang, and
+/// with no plays mid-arc the airborne freeze holds it until an edge.
 #[test]
 fn a_jump_in_place_cast_replaces_the_hang_and_survives_the_arc() {
     let mut app = app();
@@ -1623,7 +1446,6 @@ fn a_jump_in_place_cast_replaces_the_hang_and_survives_the_arc() {
         super::super::select::Mode::Entering(super::super::select::Special::Jump),
         "airborne: the jump bracket enters"
     );
-    // The instant AoE releases mid-air: the kit anim arrives.
     app.world_mut().write_message(EmoteAnim {
         entity: unit,
         anim_id: 54,
@@ -1645,7 +1467,6 @@ fn a_jump_in_place_cast_replaces_the_hang_and_survives_the_arc() {
         drv(&app, unit).overlay.is_none(),
         "no move bits, non-combat id: not the overlay route"
     );
-    // The arc continues: the Jump *level* must not preempt the clip back to the bracket.
     app.update();
     app.update();
     assert!(
@@ -1657,9 +1478,7 @@ fn a_jump_in_place_cast_replaces_the_hang_and_survives_the_arc() {
     );
 }
 
-/// Touchdown while a mid-air one-shot holds bone 0: the Special edge (`Some → None`) routes
-/// through `leave_special` — the `0x602c60` land dispatcher's pick replaces the clip like any
-/// plain play (a stationary landing picks JumpEnd 39).
+/// At touchdown the land pick (`0x602c60`) replaces a mid-air one-shot like any plain play.
 #[test]
 fn landing_mid_cast_plays_the_land_pick() {
     let mut app = app();
@@ -1689,10 +1508,8 @@ 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
-/// 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.
+/// Fall(40) plays once, on the substep FALLINGFAR latches (`0x61a820`), so a cast armed after it
+/// holds bone 0 until the landing pick.
 #[test]
 fn a_cast_over_the_fall_loop_holds_until_landing() {
     let mut app = app();
@@ -1722,7 +1539,6 @@ fn a_cast_over_the_fall_loop_holds_until_landing() {
         super::super::select::Mode::Looping(super::super::select::Special::Fall),
         "the latch's Fall play replaces the held cast"
     );
-    // A second cast while falling far arms (last-writer-wins) …
     app.world_mut().write_message(EmoteAnim {
         entity: unit,
         anim_id: 54,
@@ -1740,8 +1556,6 @@ fn a_cast_over_the_fall_loop_holds_until_landing() {
         ),
         "the cast arms over the Fall loop"
     );
-    // … and HOLDS through the rest of the fall: no per-tick re-assert exists (0868), and the
-    // Fall level is not an edge.
     app.update();
     app.update();
     assert!(
@@ -1755,7 +1569,6 @@ fn a_cast_over_the_fall_loop_holds_until_landing() {
         ),
         "the cast holds bone 0 through the fall — Fall plays only at its latch edge"
     );
-    // Touchdown cuts it with the land pick, as every airborne one-shot.
     app.world_mut()
         .entity_mut(unit)
         .insert(MovementState::default());
@@ -1767,9 +1580,7 @@ fn a_cast_over_the_fall_loop_holds_until_landing() {
     );
 }
 
-/// The walking jump keeps the masked route (the already-working half, now pinned): the
-/// takeoff-frozen FORWARD bit routes the cast to the SpineLow overlay — the torso casts, the
-/// legs keep the arc, and the base machine is untouched.
+/// A moving jump's takeoff-frozen FORWARD bit routes a cast to the masked overlay.
 #[test]
 fn a_moving_jump_cast_masks_onto_the_overlay() {
     let mut app = app();
@@ -1800,11 +1611,8 @@ fn a_moving_jump_cast_masks_onto_the_overlay() {
     );
 }
 
-/// **The transplant** (decision 0878 — the director's "jump right after a cast should only play
-/// the lower body animation and finish the upper body one"). A standing cast routes full-body to
-/// bone 0; the jump that follows is a LOCOMOTION request, so the client does **not** overwrite it
-/// — `0x5fe919` copies the bone-0 descriptor (id, rate, and its **live play position**) onto the
-/// key-bone and hands bone 0 the jump. The legs jump; the arms finish the cast.
+/// A jump is a locomotion request, so a live full-body cast moves to the key-bone with its id, rate
+/// and play position (`0x5fe919`) and bone 0 takes the jump.
 #[test]
 fn a_jump_over_a_live_cast_transplants_it_to_the_torso() {
     let mut app = app();
@@ -1848,10 +1656,8 @@ fn a_jump_over_a_live_cast_transplants_it_to_the_torso() {
     );
 }
 
-/// A **Special is a bone-0 play, so it cannot cut the torso** (decision 0878 — the jump-running
-/// half of the director's report). A moving caster's hold rides the key-bone; taking off routes
-/// JumpStart to bone 0 (`0x5fe912`: with the key-bone armed the locomotion request goes straight
-/// there) and leaves the hold running. The old `special.is_none()` filter dropped it on takeoff.
+/// With the key-bone armed, a locomotion request goes to bone 0 (`0x5fe912`), so a moving
+/// caster's jump leaves the torso's hold running.
 #[test]
 fn a_jump_does_not_cut_the_moving_cast_hold() {
     let mut app = app();
@@ -1903,11 +1709,8 @@ fn a_jump_does_not_cut_the_moving_cast_hold() {
     );
 }
 
-/// **The fade-to-rest** (decision 0878 — "the end of the cast animation is cut off and it
-/// instantly snaps back"). A finished key-bone one-shot is never stopped: the client's completion
-/// event disarms the bone through op4 `param_3 = -1`, which holds the clip's final frame in the
-/// secondary slot and cross-fades it back onto the base over a fixed 150 ms. Real clip assets, so
-/// Bevy actually completes the overlay.
+/// A finished key-bone one-shot is not stopped: op4 `param_3 = -1` holds its last frame in the
+/// secondary slot and fades it to the base over 150 ms.
 #[test]
 fn a_finished_masked_cast_fades_out_instead_of_snapping() {
     use bevy::animation::graph::{AnimationGraph, AnimationGraphHandle};
@@ -1990,8 +1793,7 @@ fn a_finished_masked_cast_fades_out_instead_of_snapping() {
             "…so it starts below full weight, not snapped on"
         );
     }
-    // Step in small frames until the clip completes (a big frame would run the whole 150 ms fade
-    // out in one go — right behaviour, useless assertion).
+    // Small frames, so the 150 ms fade is still running when the clip completes.
     for _ in 0..60 {
         advance(&mut app, 20);
         if app
@@ -2026,7 +1828,7 @@ fn a_finished_masked_cast_fades_out_instead_of_snapping() {
         );
         assert!(active.weight() > 0.0, "still blended in as λ decays");
     }
-    // Past the 150 ms window: the slot self-releases, exactly like the kernel's `+0xd0 = -1`.
+    // Past 150 ms the slot self-releases, the kernel's `+0xd0 = -1`.
     advance(&mut app, 200);
     let e = app.world().entity(unit);
     assert!(
@@ -2042,9 +1844,7 @@ fn a_finished_masked_cast_fades_out_instead_of_snapping() {
     );
 }
 
-/// The airborne-freeze in the GAIT slot (the step-off arc, decision 0864): live pins — here
-/// the stationary cast hold — cannot swap the clip mid-air; the takeoff gait keeps rolling and
-/// the pin applies at touchdown.
+/// On a step-off arc no pin swaps the gait mid-air; the cast pin applies at touchdown.
 #[test]
 fn the_step_off_arc_freezes_the_gait_against_live_pins() {
     let mut app = app();
@@ -2061,14 +1861,12 @@ 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 freeze gate
-    // `0x5fd8e8`, `FALLING && (FALLINGFAR || vz ≠ 0)`, decision 0868) …
+    // A step-off, no jump arc, with vz ≠ 0: the `0x5fd8e8` freeze holds.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FALLING,
         vertical_speed: -3.0,
         ..Default::default()
     });
-    // … and the precast lands mid-fall: the stationary pin must NOT re-pick mid-air.
     app.world_mut().entity_mut(unit).insert(CastHold {
         ranged: false,
         anim_id: 51,
@@ -2081,7 +1879,6 @@ fn the_step_off_arc_freezes_the_gait_against_live_pins() {
         Some(0),
         "the selector never re-picks mid-air — the takeoff gait holds"
     );
-    // Touchdown: the freeze lifts and the pin applies immediately.
     app.world_mut()
         .entity_mut(unit)
         .insert(MovementState::default());
@@ -2089,9 +1886,7 @@ fn the_step_off_arc_freezes_the_gait_against_live_pins() {
     assert_eq!(gait(&app), Some(51), "the pin lands with the unit");
 }
 
-/// A mid-air fast-path park survives the arc's LEVEL (decision 0864's edge-clear): the old
-/// per-frame kill cleared the deferred cache on every airborne frame; the client clears only
-/// at plays (state EDGES) — and the landing's pick, a play, still kills it.
+/// The client clears the deferred cache only at plays, so a mid-air park lives until the land pick.
 #[test]
 fn a_midair_deferred_park_survives_the_level_and_dies_at_the_landing_play() {
     let mut app = app();
@@ -2103,8 +1898,7 @@ fn a_midair_deferred_park_survives_the_level_and_dies_at_the_landing_play() {
         ..Default::default()
     });
     app.update(); // Entering(Jump)
-                  // A kit combat one-shot replaces the bracket (57 is forced-full-body), then a swing lands
-                  // the same wire batch: combat-over-combat fast-paths — the swing parks.
+                  // A kit combat clip (57) replaces the bracket; a swing in the same batch parks.
     app.world_mut().write_message(EmoteAnim {
         entity: unit,
         anim_id: 57,
@@ -2128,7 +1922,6 @@ fn a_midair_deferred_park_survives_the_level_and_dies_at_the_landing_play() {
         Some(16),
         "the swing parks behind the kit clip"
     );
-    // The arc's level must not kill the park (the old per-frame clear did).
     app.update();
     app.update();
     assert_eq!(
@@ -2136,7 +1929,7 @@ fn a_midair_deferred_park_survives_the_level_and_dies_at_the_landing_play() {
         Some(16),
         "no play mid-arc — the park survives"
     );
-    // Touchdown: the land pick is a play — the park dies with it (`0x5fe48e`).
+    // Touchdown's land pick is a play, which clears the park (`0x5fe48e`).
     app.world_mut()
         .entity_mut(unit)
         .insert(MovementState::default());
@@ -2148,10 +1941,8 @@ 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; 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.
+/// The cache's consuming read (`0x5fd392`, in `0x5fd360`) sits below the airborne freeze, so a
+/// mid-air park never plays mid-air, and the landing's play clears it.
 #[test]
 fn a_midair_park_is_not_consumed_before_landing() {
     let mut app = app();
@@ -2182,7 +1973,7 @@ fn a_midair_park_is_not_consumed_before_landing() {
         drv(&app, unit).overlay.is_none(),
         "the parked swing never played mid-air"
     );
-    // Touchdown: the landing play clears the cache (`0x5fe48e`) — the park dies unplayed.
+    // Touchdown's play clears the cache unplayed (`0x5fe48e`).
     app.world_mut()
         .entity_mut(unit)
         .insert(MovementState::default());
@@ -2194,13 +1985,8 @@ fn a_midair_park_is_not_consumed_before_landing() {
     );
 }
 
-/// **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
-/// stable under any number of swings), and the FIX (the packet arm's own snap moves it, and the
-/// reconcile then holds it there).
+/// A landed swing snaps its attacker to melee (`0x625829` in `0x6255b0`); the reconcile alone never
+/// leaves the ranged stance, its melee force being gated on `CUR != 2` (`0x5fe0f9`, `0x5fe13b`).
 #[test]
 fn a_landed_swing_snaps_its_attacker_out_of_the_ranged_stance() {
     let mut app = app();
@@ -2214,7 +2000,6 @@ fn a_landed_swing_snaps_its_attacker_out_of_the_ranged_stance() {
         first_seq: None,
         pose: Default::default(),
     };
-    // A warrior wearing a 1H sword and a bow: the exact loadout of the report.
     let unit = app
         .world_mut()
         .spawn((
@@ -2253,7 +2038,7 @@ fn a_landed_swing_snaps_its_attacker_out_of_the_ranged_stance() {
         app.update();
     };
 
-    // The shot's draw (`SetSheatheState(2, SNAP)` — the cast-send arm).
+    // The shot's draw: `SetSheatheState(2, SNAP)`.
     app.world_mut().write_message(SheathRequest {
         entity: unit,
         state: 2,
@@ -2262,8 +2047,6 @@ fn a_landed_swing_snaps_its_attacker_out_of_the_ranged_stance() {
     app.update();
     assert_eq!(sheath(&app), Some(2), "the shot draws the bow");
 
-    // CONTROL: swings alone. Attack1H's WeaponFlags `&0x20` is a force-DRAW-MELEE the client only
-    // consults on the `CUR != 2` path, so nothing in the reconcile can leave the ranged stance.
     swing(&mut app);
     swing(&mut app);
     assert_eq!(
@@ -2272,8 +2055,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 `creature_anim::net::attacker_state` now writes beside the
-    // swing): the sword comes out on the first landed blow.
+    // The packet arm's snap, which `creature_anim::net::attacker_state` writes beside the swing.
     app.world_mut().write_message(SheathRequest {
         entity: unit,
         state: 1,
@@ -2282,18 +2064,12 @@ fn a_landed_swing_snaps_its_attacker_out_of_the_ranged_stance() {
     swing(&mut app);
     assert_eq!(sheath(&app), Some(1), "the landed swing draws melee");
 
-    // …and holds: every later swing re-requests 1, which the setter refuses as idempotent, and
-    // Attack1H's `&0x20` re-asserts melee on the `CUR != 2` path.
     swing(&mut app);
     assert_eq!(sheath(&app), Some(1), "melee holds across the volley");
 }
 
-/// **The ceremony's two movements, end to end** (decision 0872) — the director's report: pressing
-/// Z with both hands full puts the weapons away, lets the arms come back to neutral, and only
-/// *then* reaches over the shoulder for the bow. Phase 1 is the setter's own play (`0x611b60`);
-/// phase 2 is the on-anim-finish drawer (`0x5fc920` @ `0x5fca8c`/`0x5fcaa1`), which is the half
-/// benilla never had — before it, the ceremony ended when the stow clips did and the bow simply
-/// appeared. Real clip assets, so Bevy's `advance_animations` actually completes them.
+/// The Z toggle stows both hands with the setter's play (`0x611b60`), and only then does the
+/// finish drawer (`0x5fc920` at `0x5fca8c`, `0x5fcaa1`) reach for the bow.
 #[test]
 fn a_melee_to_ranged_toggle_stows_both_hands_before_it_reaches_for_the_bow() {
     use bevy::animation::graph::{AnimationGraph, AnimationGraphHandle};
@@ -2315,8 +2091,7 @@ fn a_melee_to_ranged_toggle_stows_both_hands_before_it_reaches_for_the_bow() {
         .world_mut()
         .resource_mut::<Assets<AnimationGraph>>()
         .add(graph);
-    // The two stow/draw families, each with its per-arm masked pair. No `$SHL`/`$SHR` events, so
-    // each arm's weapon moves at the authored-event fallback: halfway.
+    // Per-arm masked pairs; with no `$SHL`/`$SHR` a weapon moves at the halfway fallback.
     let family = |id: u16, right: usize, left: usize| {
         let mut c = clip(id, 0, false);
         c.node = nodes[right];
@@ -2338,8 +2113,8 @@ fn a_melee_to_ranged_toggle_stows_both_hands_before_it_reaches_for_the_bow() {
         first_seq: None,
         pose: Default::default(),
     };
-    // Sword-and-board plus a bow — the director's warrior. Hip sword (3 ⇒ HipSheath 90), back
-    // shield (4 ⇒ Sheath 89), back bow (1 ⇒ 89, and INVTYPE_RANGED ⇒ the LEFT arm).
+    // Hip sword (3: HipSheath 90), back shield (4: Sheath 89), back bow (1: 89, and
+    // INVTYPE_RANGED puts it on the left arm).
     let unit = app
         .world_mut()
         .spawn((
@@ -2348,8 +2123,7 @@ fn a_melee_to_ranged_toggle_stows_both_hands_before_it_reaches_for_the_bow() {
             AnimationTransitions::new(),
             AnimationGraphHandle(graph_handle),
             AnimDriver::default(),
-            // The Z toggle is the local player's alone; a remote unit's committed state is pulled
-            // back to the server byte by the reconcile's rule 5 before any ceremony could run.
+            // The Z toggle is the local player's alone.
             crate::net::SelfPlayer,
             Wielded {
                 main: Some((2, 0x7)),
@@ -2371,7 +2145,7 @@ fn a_melee_to_ranged_toggle_stows_both_hands_before_it_reaches_for_the_bow() {
             .map(|v| v.0)
     };
 
-    // Get to melee-drawn without a ceremony (a snap, as every reactive trigger does), then press Z.
+    // Snap to melee-drawn, then press Z.
     for (state, ceremony) in [(1u8, false), (2, true)] {
         app.world_mut().write_message(SheathRequest {
             entity: unit,
@@ -2400,9 +2174,8 @@ fn a_melee_to_ranged_toggle_stows_both_hands_before_it_reaches_for_the_bow() {
         }
     }
 
-    // The smoking gun: a state where the RIGHT arm has settled into the ranged stance (sword on
-    // the back, nothing left to do) while the LEFT is still empty-handed — the bow on its way but
-    // not yet arrived. That can only exist if a second clip started after the stows finished.
+    // [2, 0], the right arm settled and the left still empty, exists only if a second clip
+    // started after the stows finished.
     assert!(
         seen.contains(&[2, 0]),
         "phase 2 never ran: the bow must be drawn by a SECOND clip, after both stows finished \
@@ -2420,13 +2193,8 @@ fn a_melee_to_ranged_toggle_stows_both_hands_before_it_reaches_for_the_bow() {
     );
 }
 
-/// **Ice Block, at the mechanism (decision 0894).** The stun's root wipes the direction bits in the
-/// SAME frame the cast one-shot arrives, so the one-shot's own arm-time flags already read ROOT and
-/// an arm-time comparison sees no movement edge — ever. The base's flags still hold the run it was
-/// armed for, so the edge is there, the re-arm resolves to **Stand(0)** (not locomotion → no
-/// transplant), and Stand overwrites the cast on bone 0: the character is fully neutral, with
-/// nothing on the torso, by the time the freeze catches it. Before this the cast held bone 0 for the
-/// whole block, or rode up to the torso and froze an arm out.
+/// A root that wipes the direction bits the frame a cast arrives: against the base's flags the edge
+/// re-arms Stand(0), not locomotion, so Stand overwrites the cast with no transplant.
 #[test]
 fn a_root_landing_with_the_cast_returns_the_body_to_neutral() {
     let mut app = app();
@@ -2449,7 +2217,7 @@ fn a_root_landing_with_the_cast_returns_the_body_to_neutral() {
     };
     assert_eq!(gait(&app), Some(5), "running");
 
-    // One frame: the root lands (direction bits wiped) AND the cast one-shot arrives.
+    // One frame: the root lands and the cast arrives.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::ROOT,
         ..Default::default()
@@ -2460,8 +2228,6 @@ fn a_root_landing_with_the_cast_returns_the_body_to_neutral() {
         seq: 1,
     });
     app.update();
-    // The cast takes bone 0 and the base re-arm displaces it inside the same frame — the reference's
-    // one-slot last-writer-wins, which is exactly what the base's flags (still FORWARD) unlock.
     assert_eq!(
         mode(&app),
         super::super::select::Mode::Gait,
@@ -2476,9 +2242,7 @@ fn a_root_landing_with_the_cast_returns_the_body_to_neutral() {
     assert!(overlay(&app).is_none(), "and nothing left on the torso");
 }
 
-/// The control that keeps 0878 honest: the transplant still fires when the re-arm really *is*
-/// locomotion. A cast fired standing, then the player runs — the legs take Run and the cast keeps
-/// going on the torso, which is the whole of R-B.
+/// The control: a locomotion re-arm still transplants the cast to the torso.
 #[test]
 fn a_run_starting_under_a_cast_still_transplants_it_up() {
     let mut app = app();
@@ -2517,9 +2281,7 @@ fn a_run_starting_under_a_cast_still_transplants_it_up() {
     );
 }
 
-/// A walker's model: Stand plus a Walk(4) authored at the 2.5 yd/s design speed every 1.12.1
-/// creature and character rig shares (byte-read from `ogremage.m2` and `humanmale.m2` with
-/// `benilla-extract m2seq`).
+/// Stand and a Walk(4) at the 2.5 yd/s design speed of `ogremage.m2` and `humanmale.m2`.
 fn walker_model() -> ModelAnimations {
     let mut walk = clip(4, 2, true);
     walk.move_speed = 2.5;
@@ -2535,10 +2297,8 @@ fn walker_model() -> ModelAnimations {
     }
 }
 
-/// A **mount's** model, as the real assets are shaped (decision 0906): Horse.m2 authors no
-/// JumpLandRun 187 at all, and its baked PlayableAnimationLookup answers a 187 request with
-/// **Run(5)** — `playable[187] = 5`, the same row Tiger.m2 (the druid travel form) and Cat.m2
-/// carry. The Run clip's authored design speed is the horse's real 9.028 yd/s.
+/// A mount shaped like Horse.m2: it authors neither Sprint 143 nor JumpLandRun 187 and its baked
+/// lookup sends both to Run(5); Tiger.m2 and Cat.m2 carry the same 187 row.
 fn mount_model() -> ModelAnimations {
     let mut run = clip(5, 2, true);
     run.move_speed = 9.028; // Horse.m2 sequence 16's ModelAnimation::move_speed
@@ -2552,9 +2312,6 @@ fn mount_model() -> ModelAnimations {
     for id in [0u16, 5, 37, 38, 39] {
         table[id as usize].resolved_id = id;
     }
-    // A mount authors neither Sprint 143 (what the selector picks at mount speed) nor
-    // JumpLandRun 187 (what the landing picks): its baked table answers BOTH with the gallop
-    // cycle, so the whole galloping-jump-landing sequence is one clip at three rates.
     table[143].resolved_id = 5;
     table[187].resolved_id = 5;
     ModelAnimations {
@@ -2575,8 +2332,6 @@ fn mount_model() -> ModelAnimations {
     }
 }
 
-/// The rate the driver actually wrote onto the walk node — the number the fix is about, read back
-/// off the live `AnimationPlayer` rather than off the driver's own bookkeeping.
 fn walk_rate(app: &App, unit: Entity) -> f32 {
     app.world()
         .entity(unit)
@@ -2587,11 +2342,8 @@ fn walk_rate(app: &App, unit: Entity) -> f32 {
         .speed()
 }
 
-/// The director's ogre, end to end through the real system (decision 0903): a Gordok Ogre-Mage
-/// (`CreatureDisplayInfo.CreatureModelScale` 2.2, so `OBJECT_FIELD_SCALE_X` 2.2) walking at
-/// vmangos' `speed_walk` 1.6 × 2.5 = 4.0 yd/s must cycle its legs at 4.0 / (2.5 × 2.2) = 0.73×.
-/// Scale-blind it read 1.60× — the "too fast walk" report. The control is the same unit at scale
-/// 1.0, which must still read the un-divided 1.60×: the fix may not touch ordinary-size creatures.
+/// A Gordok Ogre-Mage (scale 2.2) walking at vmangos' `speed_walk` 1.6 × 2.5 = 4.0 yd/s cycles at
+/// 4.0 / (2.5 × 2.2) = 0.73×; the same unit at scale 1.0 reads 1.60×.
 #[test]
 fn a_scaled_creatures_walk_cycles_slower_than_an_unscaled_ones() {
     let walking = MovementState {
@@ -2635,11 +2387,8 @@ 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 (`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.
+/// The divisor reads the mount model (`[unit+0xdc] ?: [unit+0xd8]`), scaled by the rider's
+/// `OBJECT_FIELD_SCALE_X` times its own display column (`0x613ef0`): 1.5 under 2.0 divides by 3.0.
 #[test]
 fn a_mounts_gait_rate_composes_the_riders_scale_with_the_mounts() {
     let mut app = app();
@@ -2666,8 +2415,7 @@ fn a_mounts_gait_rate_composes_the_riders_scale_with_the_mounts() {
         ))
         .id();
     app.update();
-    // 4.0 / (2.5 · 1.5 · 2.0) = 0.533… — the mount also inherits the rider's movement view, so the
-    // speed feeding the divide is the rider's, exactly as the client's per-unit call reads it.
+    // 4.0 / (2.5 · 1.5 · 2.0) = 0.533…, at the rider's speed.
     assert!(
         (walk_rate(&app, mount) - 0.533_33).abs() < 1e-3,
         "the mount divides by rider x mount scale: got {}",
@@ -2675,15 +2423,8 @@ fn a_mounts_gait_rate_composes_the_riders_scale_with_the_mounts() {
     );
 }
 
-/// The director's report (decision 0906): "jumping while running forward, mounted or in druid
-/// travel form, slows the running animation on landing and it takes ~1-2 s to snap back".
-///
-/// The landing request is JumpLandRun 187; on every creature model that resolves to **Run(5)**,
-/// a rate-scaled locomotion clip — so the land clip IS the gallop cycle and must run at
-/// `speed / moveSpeed` like the gait it continues. It used to be armed at the call site's literal
-/// `1.0` and nothing rewrote it until `Mode::Land` ended, which is the clip's whole length of
-/// visibly-slow legs. The rate write is per-frame and mode-independent now (`sync_base_rate`), so
-/// the landing runs at the same rate the airborne gait did.
+/// A mount's JumpLandRun 187 resolves to Run(5), a rate-scaled clip, so the landing runs at
+/// `speed / moveSpeed` like the gait: the rate write covers every mode.
 #[test]
 fn a_mounted_landing_runs_at_the_gaits_rate_not_at_one_times() {
     let mut app = app();
@@ -2721,7 +2462,6 @@ fn a_mounted_landing_runs_at_the_gaits_rate_not_at_one_times() {
         rate(&app)
     );
 
-    // Up: the jump bracket takes the body (JumpStart, then the hang).
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FORWARD | move_flags::FALLING,
         speed: 14.0,
@@ -2737,7 +2477,7 @@ fn a_mounted_landing_runs_at_the_gaits_rate_not_at_one_times() {
         "an upward launch enters the jump bracket"
     );
 
-    // Touchdown, still holding forward: the land pick is 187 → the model plays Run for it.
+    // Touchdown, still holding forward.
     app.world_mut().entity_mut(unit).insert(running);
     app.update();
     assert_eq!(
@@ -2759,19 +2499,13 @@ fn drv_of(app: &App, unit: Entity) -> &AnimDriver {
     app.world().entity(unit).get::<AnimDriver>().unwrap()
 }
 
-/// **B203 — the mount transition's own bone-0 arm.** The mount summon's cast-stage kit plays
-/// `SpellCastOmni` (54) at SPELL_GO, while the caster is still *unmounted*, so it takes the
-/// full-body route and `Mode::Swing` owns bone 0 for the clip's whole span. The mount field then
-/// lands a beat later — and the gait slot's mounted pin cannot help, because it only picks when
-/// the mode is already `Mode::Gait`. The reference has no such wait: `0x607a00`'s tail
-/// (`0x607b44`) is an ordinary op4 PRIMARY play of **91 `Mount`** on bone 0 of the body, so the
-/// cast clip is displaced the moment the mount arrives — which is why the director sees no cast
-/// animation at mount-up, only the poof.
+/// The mount arm (`0x607a00`'s tail, `0x607b44`) is an ordinary primary play of 91 `Mount` on
+/// bone 0, so it displaces the summon's full-body cast clip at once.
 #[test]
 fn the_mount_transition_takes_bone_0_back_from_a_full_body_one_shot() {
     use benilla_protocol::ObjectFields;
 
-    /// `UNIT_FIELD_MOUNTDISPLAYID` (index 133, decision 0441).
+    /// `UNIT_FIELD_MOUNTDISPLAYID` (index 133).
     const FIELD_MOUNTDISPLAYID: u16 = 133;
     const SPELL_CAST_OMNI: u16 = 54;
     const MOUNT: u16 = 91;
@@ -2781,8 +2515,8 @@ fn the_mount_transition_takes_bone_0_back_from_a_full_body_one_shot() {
         graph: Handle::default(),
         clips: vec![
             clip(0, 1, true),                // Stand
-            clip(MOUNT, 2, true),            // Mount — the seat pose
-            clip(SPELL_CAST_OMNI, 3, false), // the cast release, FULL BODY (no upper_node)
+            clip(MOUNT, 2, true),            // Mount, the seat pose
+            clip(SPELL_CAST_OMNI, 3, false), // the cast release, full body
         ],
         hand_close: [None, None],
         playable_animation_lookup: Vec::new(),
@@ -2815,7 +2549,6 @@ fn the_mount_transition_takes_bone_0_back_from_a_full_body_one_shot() {
     app.update();
     assert_eq!(playing(&app), Some(0), "standing, unmounted");
 
-    // SPELL_GO: the cast-stage kit's release clip, full-body over bone 0.
     app.world_mut().write_message(EmoteAnim {
         entity: unit,
         anim_id: SPELL_CAST_OMNI,
@@ -2828,7 +2561,6 @@ fn the_mount_transition_takes_bone_0_back_from_a_full_body_one_shot() {
         "the release clip takes bone 0 while the caster is still on foot"
     );
 
-    // …and the mount field lands, mid-clip. The transition's own arm reclaims bone 0.
     mount_field(&mut app, 2404);
     app.update();
     assert_eq!(
@@ -2837,27 +2569,17 @@ fn the_mount_transition_takes_bone_0_back_from_a_full_body_one_shot() {
         "B203: the mount arm displaces the cast clip — it does not wait for it to finish"
     );
 
-    // The edge is a CHANGE, not a level: a steady mounted frame re-picks nothing new, and the
-    // seat pose simply holds (the reference's per-play re-force, rendered by the gait pin).
     app.update();
     assert_eq!(playing(&app), Some(MOUNT));
 
-    // Dismount is the same watcher's other leg (`0x607ce0` arms seq 0 Stand on the same bone).
+    // Dismount, the watcher's other leg: `0x607ce0` arms Stand on the same bone.
     mount_field(&mut app, 0);
     app.update();
     assert_eq!(playing(&app), Some(0), "back on its own feet, standing");
 }
 
-/// **B204 — the dismount CUTS the saddle pose; the mount-up blends into it** (decision 0931).
-/// The two legs of the `UNIT_FIELD_MOUNTDISPLAYID` watcher issue the same seven-argument op4
-/// `0x7121a0` call and differ in exactly one literal: `0x607b35 push 0x1` (build, cross-fade) vs
-/// `0x607d1c push 0x0` (teardown, no cross-fade). Fading Mount(91) out instead of cutting it is
-/// what read as a landing — 91 splays and bends the legs, and easing that into Stand over the
-/// clip's blend is a body absorbing an impact.
-///
-/// The assertion is on the OUTGOING clip's weight, because that is the whole difference: after
-/// the build frame the old pose is still weighted in (a blend in progress), after the teardown
-/// frame the saddle pose contributes nothing at all.
+/// The mount watcher's two op4 `0x7121a0` calls differ in one literal: the build cross-fades
+/// (`0x607b35 push 0x1`), the teardown cuts (`0x607d1c push 0x0`), seen in the outgoing weight.
 #[test]
 fn the_dismount_cuts_the_saddle_pose_where_the_mount_up_blends_into_it() {
     use benilla_protocol::ObjectFields;
@@ -2868,10 +2590,7 @@ fn the_dismount_cuts_the_saddle_pose_where_the_mount_up_blends_into_it() {
     let mount_node = AnimationNodeIndex::new(2);
 
     let mut app = app();
-    // A deliberately LONG blend on both clips, so "did it fade or did it cut" cannot come down to
-    // how long a headless frame happened to take: at the harness's real-time `dt` the shipped
-    // 0.15 s blend is all but finished after a single update, and the difference the test is
-    // about would sit inside the noise.
+    // A long blend, so a fade cannot pass for a cut.
     let mut stand = clip(0, 1, true);
     let mut mount = clip(MOUNT, 2, true);
     stand.blend_time = 2.0;
@@ -2917,7 +2636,6 @@ fn the_dismount_cuts_the_saddle_pose_where_the_mount_up_blends_into_it() {
     app.update();
     assert_eq!(drv_of(&app, unit).active_anim(), Some(0));
 
-    // Build leg — `0x607b35 push 0x1`: Stand is still fading out under the seat pose.
     mount_field(&mut app, 2404);
     app.update();
     assert_eq!(drv_of(&app, unit).active_anim(), Some(MOUNT));
@@ -2926,8 +2644,6 @@ fn the_dismount_cuts_the_saddle_pose_where_the_mount_up_blends_into_it() {
         "the mount-up cross-fades: the outgoing pose is still weighted in"
     );
 
-    // Teardown leg — `0x607d1c push 0x0`: the saddle pose is gone on the arm's own frame, not
-    // eased away over the clip's blend time.
     mount_field(&mut app, 0);
     app.update();
     assert_eq!(drv_of(&app, unit).active_anim(), Some(0));
@@ -2945,8 +2661,8 @@ fn archer_model() -> ModelAnimations {
         clips: vec![
             clip(0, 1, true),    // Stand
             clip(5, 2, true),    // Run
-            clip(105, 3, false), // LoadBow — the pull
-            clip(109, 4, true),  // HoldBow — the drawn hold
+            clip(105, 3, false), // LoadBow, the pull
+            clip(109, 4, true),  // HoldBow, the drawn hold
         ],
         hand_close: [None, None],
         playable_animation_lookup: Vec::new(),
@@ -2957,14 +2673,8 @@ fn archer_model() -> ModelAnimations {
     }
 }
 
-/// The bow-and-arrow half of the director's 2026-08-05 report — the screenshot is a warrior
-/// **sprinting** with the arrow still nocked and the bowstring still drawn.
-///
-/// The nock latch has exactly two authored writers: `$BWP` sets it, `$BWR` clears it, and both
-/// tags live only in clips a STANDING unit plays (the Load pull and the fire clip; a real
-/// character M2's Run authors neither — verified by dumping every playable model's event tracks).
-/// So a latch carried into locomotion could never be cleared by anything, and the gait arm's
-/// hold-pick re-latch (0409's INTERIM) re-arms it on every volley — the leak was guaranteed.
+/// `$BWP` sets the nock latch and `$BWR` clears it, and only standing clips carry either tag, so
+/// moving drops the latch; the ammo display cache survives.
 #[test]
 fn a_running_shooter_drops_the_nocked_arrow_and_keeps_its_ammo_cache() {
     let mut app = app();
@@ -2984,7 +2694,6 @@ fn a_running_shooter_drops_the_nocked_arrow_and_keeps_its_ammo_cache() {
             crate::creature_anim::NockLatch,
         ))
         .id();
-    // The bow is drawn and the arrow is on the string: the steady state of a standing shooter.
     app.world_mut().write_message(SheathRequest {
         entity: unit,
         state: 2,
@@ -2999,7 +2708,6 @@ fn a_running_shooter_drops_the_nocked_arrow_and_keeps_its_ammo_cache() {
     };
     assert!(latched(&app), "standing drawn: the arrow stays nocked");
 
-    // They run.
     app.world_mut().entity_mut(unit).insert(MovementState {
         speed: 7.0,
         flags: move_flags::FORWARD,
@@ -3020,10 +2728,7 @@ fn a_running_shooter_drops_the_nocked_arrow_and_keeps_its_ammo_cache() {
     );
 }
 
-/// The aiming half of the same report ("they keep aiming like they are going to shoot at
-/// something"): the drawn Load/Hold idle is entered by the LOCAL auto-repeat bit `0x200` alone
-/// (`0x5fd460`'s only claim test). The any-caster weapon-visual hold `0x400` — which every
-/// ranged-slot spell's visual sets and nothing ever clears on volley end — must not admit it.
+/// The drawn idle enters on the local auto-repeat bit `0x200` alone (`0x5fd460`), never `0x400`.
 #[test]
 fn the_weapon_visual_hold_alone_never_puts_a_shooter_in_the_drawn_idle() {
     let spawn = |app: &mut App, auto_repeat: bool| {
@@ -3037,8 +2742,7 @@ fn the_weapon_visual_hold_alone_never_puts_a_shooter_in_the_drawn_idle() {
                 ranged: Some((2, 0x2)),
                 ..Default::default()
             },
-            // Set by ANY ranged spell's visual play — one Multi-Shot is enough, and it is still
-            // set an hour later.
+            // Set by any ranged spell's visual, and not cleared at volley end.
             crate::creature_anim::RangedHold,
         ));
         if auto_repeat {
@@ -3072,30 +2776,15 @@ 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 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); 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**.
-///
-/// So the mid-volley cycle is **fire → re-pull → hold**, once per shot. That re-pull is the
-/// "reload" of bug B307: `$BWP` lives only in the Load clips (verified on five shipped character
-/// models), so it is the only thing that can put the arrow back on the string — and holding it
-/// out left every shot after the first firing from an empty hand.
-///
-/// What 0994 got right and this keeps: the director's original complaint was about a *moving*
-/// shooter, and locomotion still outranks the drawn idle, so nothing here re-pulls mid-run.
+/// A fire clip's completion reaches the dispatcher `0x5fc3f0` via its deferred site (`0x719370`,
+/// `0x7074b0`): slot 22 recomputes to a re-pull, whose `$BWP` re-nocks, and a finished Load arms
+/// the Hold (slots 11/12/15).
 #[test]
 fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
     use bevy::animation::graph::{AnimationGraph, AnimationGraphHandle};
     use bevy::animation::AnimationClip;
 
-    // Stand-in spans; only the ORDER of completions is load-bearing, not the numbers.
+    // Stand-in spans; only the order of completions matters.
     const PULL: f32 = 0.7;
     const FIRE: f32 = 0.5;
 
@@ -3119,8 +2808,7 @@ fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
         .resource_mut::<Assets<AnimationGraph>>()
         .add(graph);
 
-    // A real shooter's model authors all four (HumanMale: 0, 105, 46, 109 — `benilla-extract
-    // … m2seq`), and 109 is the only one of them authored as a LOOP.
+    // HumanMale authors all four; only 109 is a loop.
     let mut stand_clip = clip(0, 0, true);
     stand_clip.node = nodes[0];
     let mut pull_clip = clip(105, 0, false);
@@ -3170,10 +2858,8 @@ fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
 
     assert_eq!(gait(&app), Some(105), "the volley opens with the pull");
 
-    // …which promotes to the HOLD on its own completion — slot 11, unconditional. The extra
-    // frame is the schedule, not a fudge: the driver runs in `Update` and Bevy advances the
-    // clips in `PostUpdate`, so a completion is visible to the machine on the frame AFTER the
-    // one that finished it.
+    // The extra frame: clips advance in `PostUpdate`, after the driver, which sees a completion
+    // one frame late.
     advance(&mut app, 1000);
     app.update();
     assert_eq!(
@@ -3182,7 +2868,6 @@ fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
         "a finished LoadBow yields HoldBow — the drawn pose the shooter sits in between shots"
     );
 
-    // Shot 1: the fire clip takes the body as a one-shot, through the real message lane.
     app.world_mut().write_message(EmoteAnim {
         entity: unit,
         anim_id: 46,
@@ -3198,8 +2883,6 @@ fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
         "AttackBow takes bone 0"
     );
 
-    // Its completion recomputes — and for an armed shooter the base re-picks the pull. THIS is
-    // the reload the report was missing.
     advance(&mut app, 1000);
     app.update();
     assert_eq!(
@@ -3207,7 +2890,7 @@ fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
         super::super::select::Mode::Gait,
         "the fire clip's completion recomputes the base (slot 22's bare RecomputeBaseAnim(-1))"
     );
-    // The recompute clears the gait and re-picks it on the following frame (`drv.gait = None`).
+    // The recompute clears the gait and re-picks it the next frame.
     app.update();
     assert_eq!(
         gait(&app),
@@ -3215,7 +2898,6 @@ fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
         "…and the shooter RE-PULLS: the per-shot reload, whose $BWP re-nocks the arrow"
     );
 
-    // …and settles back into the hold, closing the cycle.
     advance(&mut app, 1000);
     app.update();
     assert_eq!(
@@ -3224,7 +2906,7 @@ fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
         "fire → re-pull → hold, once per shot"
     );
 
-    // The volley ends — the cancel's `RecomputeBaseAnim(-1)`.
+    // The volley ends: the cancel's `RecomputeBaseAnim(-1)`.
     app.world_mut()
         .entity_mut(unit)
         .remove::<crate::creature_anim::AutoRepeatArmed>();
@@ -3237,35 +2919,14 @@ fn a_mid_volley_fire_clip_re_pulls_and_the_pull_promotes_to_the_hold() {
     );
 }
 
-/// **B307's driver half** — the link after the router: does an `EmoteAnim { anim_id: 46 }`
-/// arriving on a self-player who is [`crate::creature_anim::AutoRepeatArmed`], drawn
-/// (`sheath_cur == 2`) and standing in the pull (gait 105) actually ARM clip 46 on the body,
-/// **shot after shot**?
-///
-/// Two guards sit on that path and each could silently eat shots 2 and 3 of a volley — leaving
-/// exactly the reported symptom, a shooter that fires from a still pose:
-///
-/// 1. the **combat fast-path** (`0x5fe43c`): a combat clip requested while another combat clip
-///    plays is not armed at all — the live clip doubles rate and the request parks. AttackBow is
-///    NOT in the client's combat set (`0x5fcc10`: `10 | 16..=24 | 30 | 36 | 57..=59 | 85..=88 |
-///    95 | 117 | 118`), so it must never take this road;
-/// 2. the **arm-level same-id dedup** (`0x5fdba0`): a requested id already occupying its slot
-///    *and still playing* is not re-armed. Written when 0994's law held the base out of the
-///    recompute, so shot 2 would find `Mode::Swing { id: 46 }` still set; decision 1544 restored
-///    the recompute, so the mode is back in `Gait` by then. The dedup is checked here either way
-///    — it is the guard that would swallow a shot if a fire clip ever were still live.
-///
-/// Driven through the real `EmoteAnim` lane (no poking `drv.mode`), with real clip assets so
-/// Bevy completes them, and 3 s of clock between shots — a bow's cadence.
+/// Every shot of a volley arms AttackBow(46): it is not in the combat set (`0x5fcc10`), so the
+/// fast path (`0x5fe43c`) never parks it, and the same-id dedup (`0x5fdba0`) finds it finished.
 #[test]
 fn every_shot_of_a_volley_re_arms_the_fire_clip_through_the_emote_lane() {
     use bevy::animation::graph::{AnimationGraph, AnimationGraphHandle};
     use bevy::animation::AnimationClip;
 
-    /// Stand-in spans for LoadBow and AttackBow. The exact numbers are not load-bearing and
-    /// are not claimed to be the real M2's; what matters is only that a fire clip is far
-    /// shorter than the ~3 s a bow puts between Auto Shots, so the dedup's "still playing"
-    /// test must read false by the next shot.
+    /// Stand-in spans; a fire clip only has to be far shorter than a bow's ~3 s between shots.
     const PULL: f32 = 0.7;
     const FIRE: f32 = 0.5;
 
@@ -3288,9 +2949,7 @@ fn every_shot_of_a_volley_re_arms_the_fire_clip_through_the_emote_lane() {
         .resource_mut::<Assets<AnimationGraph>>()
         .add(graph);
 
-    // The shooter's model. `archer_model` deliberately authors no 46; a real HumanMale.m2 does
-    // (sequences 46/49/105/106, `benilla-extract … m2seq`), and 46 has to exist for "was it
-    // armed?" to be an observable question at all.
+    // Unlike `archer_model`, this authors 46, as HumanMale.m2 does.
     let mut stand_clip = clip(0, 0, true);
     stand_clip.node = nodes[0];
     let mut pull_clip = clip(105, 0, false);
@@ -3326,8 +2985,7 @@ fn every_shot_of_a_volley_re_arms_the_fire_clip_through_the_emote_lane() {
         ))
         .id();
 
-    // The volley opens: the stance snaps drawn (`SMSG_SPELL_START`'s ranged snap) and the
-    // shooter pulls.
+    // `SMSG_SPELL_START`'s ranged snap draws, and the shooter pulls.
     app.world_mut().write_message(SheathRequest {
         entity: unit,
         state: 2,
@@ -3359,7 +3017,7 @@ fn every_shot_of_a_volley_re_arms_the_fire_clip_through_the_emote_lane() {
         under: None,
     };
     for shot in 1..=3u64 {
-        // `SMSG_SPELL_GO` → the router's cast kit → this message. Nothing else changes.
+        // `SMSG_SPELL_GO`'s cast kit, through the router.
         app.world_mut().write_message(EmoteAnim {
             entity: unit,
             anim_id: 46,
@@ -3379,8 +3037,8 @@ fn every_shot_of_a_volley_re_arms_the_fire_clip_through_the_emote_lane() {
             "shot {shot} was a normal arm, not a fast-path park"
         );
 
-        // The ~3 s to the next shot. The clip plays out and CLAMPS on its authored tail: no
-        // recompute for a bow id under auto-repeat, so no second pull is armed between shots.
+        // The ~3 s to the next shot as one frame: the clip finishes in `PostUpdate`, after the
+        // driver has run, so the driver has not yet seen the completion.
         advance(&mut app, 3000);
         assert_eq!(
             fire_running(&app),
@@ -3401,7 +3059,7 @@ fn every_shot_of_a_volley_re_arms_the_fire_clip_through_the_emote_lane() {
         );
     }
 
-    // The volley ends — the cancel's `RecomputeBaseAnim(-1)`: the shooter stands up.
+    // The volley ends: the cancel's `RecomputeBaseAnim(-1)`.
     app.world_mut()
         .entity_mut(unit)
         .remove::<crate::creature_anim::AutoRepeatArmed>();
@@ -3414,15 +3072,9 @@ fn every_shot_of_a_volley_re_arms_the_fire_clip_through_the_emote_lane() {
     );
 }
 
-/// A vendor built on **real Bevy clip assets**, not the stand-in `clip()` handles the rest of this
-/// file uses: this tenant is about a window *completing*, and `completions()` only ticks for an
-/// entity whose graph is a real asset (`advance_animations` skips the others — see [`app`]). The
-/// timings are the shipped HumanMale's (`benilla-extract m2seq`): Stand 2.667 s / blend 0.500 s,
-/// ShuffleLeft & ShuffleRight 0.500 s / blend 0.250 s, and `replay = (0,0)` on both shuffles —
-/// which is what every one of the 1130 shipped shuffle records carries, so `R` is a deterministic
-/// 1 and the window is exactly one span.
-///
-/// Returns the entity plus the three graph nodes, in id order: Stand, ShuffleLeft, ShuffleRight.
+/// A vendor on real clip assets with HumanMale's timings: Stand 2.667 s (blend 0.5 s), the shuffles
+/// 0.5 s (blend 0.25 s) with `replay = (0,0)`, as all 1130 shipped shuffle records carry, so a
+/// window is one span. Nodes: Stand, ShuffleLeft, ShuffleRight.
 fn spawn_vendor(app: &mut App) -> (Entity, Vec<AnimationNodeIndex>) {
     use benilla_protocol::EntityKind;
     use bevy::animation::graph::{AnimationGraph, AnimationGraphHandle};
@@ -3464,8 +3116,7 @@ fn spawn_vendor(app: &mut App) -> (Entity, Vec<AnimationNodeIndex>) {
         first_seq: None,
         pose: Default::default(),
     };
-    // The vendor five yards east of the world origin, authored facing +x — its back to a player
-    // standing north-west of it, which is the reporter's own screenshot in B110.
+    // Five yards east of the origin, facing +x: its back to a player north-west of it.
     let npc = app
         .world_mut()
         .spawn((
@@ -3490,23 +3141,8 @@ fn spawn_vendor(app: &mut App) -> (Entity, Vec<AnimationNodeIndex>) {
     (npc, nodes)
 }
 
-/// The **cross-seam** test for the turn-shuffle (decision 1655): `net::motion::facing` produces the
-/// [`crate::net::FacingStep`] latch and this driver consumes it, and until this test the two had
-/// only ever been exercised apart — the producer's tests read the transform, the consumer's tests
-/// inserted the component by hand. Neither could see the seam, which is how a mechanism that was
-/// all present and firing produced nothing anyone could see: "when interacting with a vendor the
-/// NPC doesn't shuffle its feet, it turns frozen" (director, 2026-08-27).
-///
-/// Two laws meet here, and the test is written so that failing either one is legible:
-///
-/// - **the latch runs the ease out** — the client tests the yaw its pump APPLIED against ±1e-5,
-///   not the gap remaining against an eyeballed 3°, so the shuffle blends in properly instead of
-///   being handed back at 0.32 weight;
-/// - **the shuffle is released by its own clip window, never by the turn ending** — `0x607ed0`'s
-///   tail can only start one (`0x5fce30`'s gate needs a turn bit, which is exactly what going
-///   still clears), so what ends it is the completion callback one span later. That is why the
-///   reference plays a discrete little step and not a stub of one, and it is why the middle
-///   assertion here is that the feet are STILL moving long after the body has stopped.
+/// The facing producer and this driver together: the latch holds while the yaw the pump applies
+/// exceeds 1e-5, and the shuffle ends at its own window, since `0x607ed0`'s tail cannot stop one.
 #[test]
 fn the_interaction_face_me_shuffles_its_feet_for_the_whole_turn() {
     let mut app = app();
@@ -3516,10 +3152,7 @@ fn the_interaction_face_me_shuffles_its_feet_for_the_whole_turn() {
         Update,
         crate::net::drive_display_facing.before(drive_animations),
     );
-    // Us off the vendor's axis — a bearing of ~2.60 rad, the representative case. (A goal at
-    // exactly ±pi sits on the yaw wrap, where the client's own unfolded-delta dead-band never
-    // snaps and the ease runs to float underflow instead; `net::motion::facing`'s tests say the
-    // same thing about the same corner.)
+    // Off the vendor's axis at a bearing of ~2.60 rad; exactly ±pi would sit on the yaw wrap.
     app.world_mut().spawn((
         crate::net::SelfPlayer,
         crate::net::ActiveMover,
@@ -3529,7 +3162,6 @@ fn the_interaction_face_me_shuffles_its_feet_for_the_whole_turn() {
 
     let gait = |app: &App| app.world().entity(npc).get::<AnimDriver>().unwrap().gait;
     let turning = |app: &App| app.world().entity(npc).contains::<crate::net::FacingStep>();
-    // How heavily either shuffle is being blended in — the "is it actually on screen" number.
     let shuffle_weight = |app: &App| {
         let p = app.world().entity(npc).get::<AnimationPlayer>().unwrap();
         nodes[1..]
@@ -3537,8 +3169,7 @@ fn the_interaction_face_me_shuffles_its_feet_for_the_whole_turn() {
             .filter_map(|n| p.animation(*n).map(|a| a.weight()))
             .fold(0.0f32, f32::max)
     };
-    // Run `ms` of 16 ms frames, reporting the heaviest the shuffle got and whether it held the
-    // gait slot throughout.
+    // `ms` of 16 ms frames: the peak shuffle weight, and whether `want` held the gait slot.
     let run = |app: &mut App, ms: u64, want: u16| {
         let (mut peak, mut held) = (0.0f32, true);
         for _ in 0..(ms / 16) {
@@ -3549,13 +3180,11 @@ fn the_interaction_face_me_shuffles_its_feet_for_the_whole_turn() {
         (peak, held)
     };
 
-    // The control: nothing open, nothing turning — the vendor stands, and keeps standing.
     let (peak, _) = run(&mut app, 128, 0);
     assert_eq!(gait(&app), Some(0), "no window, no turn");
     assert_eq!(peak, 0.0, "and no shuffle to be seen");
 
-    // Open its window. It turns to us — and its feet move while it does. 256 ms is past the ease
-    // (this bearing closes in ten pumps ~= 160 ms) and past the shuffle's own 250 ms blend-in.
+    // Open its window. 256 ms covers the ease (ten pumps, ~160 ms) and the 250 ms blend-in.
     app.world_mut()
         .resource_mut::<crate::ui_session::InteractNpc>()
         .0 = Some(npc);
@@ -3566,10 +3195,7 @@ fn the_interaction_face_me_shuffles_its_feet_for_the_whole_turn() {
         "the shuffle blends the whole way in; the frozen-feet defect peaked at 0.32, got {peak}"
     );
 
-    // **The body has stopped and the feet have not.** The ease settled ~100 ms ago; the shuffle is
-    // held to its 500 ms window, which is what makes it a step rather than a twitch. A driver that
-    // released on the settle fails here — and so does one that released on the latch, one frame
-    // after the yaw went quiet.
+    // The ease has settled; the shuffle holds to its 500 ms window.
     assert!(!turning(&app), "the ease has settled");
     let (_, held) = run(&mut app, 192, 11);
     assert!(
@@ -3578,26 +3204,18 @@ fn the_interaction_face_me_shuffles_its_feet_for_the_whole_turn() {
         gait(&app)
     );
 
-    // …and released AT that window, not never. `0x5fc3f0`'s completion row is a
-    // `RecomputeBaseAnim(-1)`, so the chain now answers Stand — with a freshly rolled variation,
-    // which is the idle fidget of 0123.
+    // Released at the window: `0x5fc3f0`'s completion row recomputes, and the chain answers Stand.
     run(&mut app, 160, 0);
     assert_eq!(
         gait(&app),
         Some(0),
         "the completed window returns it to Stand"
     );
-    // Let the idle finish arriving before the next half — Stand's own blend is 500 ms, and a
-    // window closed mid-fade would put THREE tracks on the slot at once (the retiring shuffle,
-    // the half-arrived Stand, the new shuffle) and split the weight three ways. That is a real
-    // divergence we carry knowingly — the reference's `0x7125d4` refuses to re-seed a blend that
-    // has not passed half weight (1565 §6, 1570) — but it is not what this test is about, and a
-    // player browsing a vendor's stock is well past it either way.
+    // Let Stand's 500 ms blend finish: a turn mid-fade would stack three tracks here, where the
+    // reference refuses to re-seed a blend short of half weight (`0x7125d4`).
     run(&mut app, 640, 0);
 
-    // Close it. The goal falls back to the untouched wire facing and it swings home — "and again
-    // when it turns back" (the report's second half), so the feet move for that turn too, on the
-    // other side.
+    // Closing it swings the vendor back to its wire facing, shuffling the other way.
     app.world_mut()
         .resource_mut::<crate::ui_session::InteractNpc>()
         .0 = None;
@@ -3606,12 +3224,8 @@ fn the_interaction_face_me_shuffles_its_feet_for_the_whole_turn() {
     assert!(peak > 0.95, "and blends the whole way in: {peak}");
 }
 
-/// **A disarmed attacker fights bare-handed** (decision 1863) — the whole of `UNIT_FLAG_DISARMED`
-/// on the animation side, run through the real driver against an armed control on the same frame.
-/// The reference gets here with no disarm case in any selector: `GetWeapon(slot, 0)` hands the
-/// swing (`0x6246a0`) and the Ready idle (`0x5fcdc0`) a NULL hand, and their existing unarmed legs
-/// do the rest. So the pass is *unarmed clips*, and the failure this pins is the sword's Attack1H
-/// coming out of a hand the server says is empty.
+/// Disarm has no selector case: `GetWeapon(slot, 0)` hands the swing (`0x6246a0`) and the Ready
+/// idle (`0x5fcdc0`) a null hand, and their unarmed legs do the rest.
 #[test]
 fn a_disarmed_attacker_swings_and_stands_unarmed() {
     fn model() -> ModelAnimations {
@@ -3619,12 +3233,12 @@ fn a_disarmed_attacker_swings_and_stands_unarmed() {
             graph: Handle::default(),
             clips: vec![
                 clip(0, 1, true),    // Stand
-                clip(17, 2, false),  // Attack1H — the sword swing
-                clip(16, 3, false),  // AttackUnarmed — the fist
-                clip(26, 4, true),   // Ready1H — the sword stance
-                clip(25, 5, true),   // ReadyUnarmed — the bare-handed stance
-                clip(88, 6, false),  // AttackOffPierce — the offhand dagger
-                clip(117, 7, false), // AttackUnarmedOff — the offhand fist
+                clip(17, 2, false),  // Attack1H, the sword swing
+                clip(16, 3, false),  // AttackUnarmed, the fist
+                clip(26, 4, true),   // Ready1H
+                clip(25, 5, true),   // ReadyUnarmed
+                clip(88, 6, false),  // AttackOffPierce, the off-hand dagger
+                clip(117, 7, false), // AttackUnarmedOff, the off-hand fist
             ],
             hand_close: [None, None],
             playable_animation_lookup: Vec::new(),
@@ -3634,7 +3248,7 @@ fn a_disarmed_attacker_swings_and_stands_unarmed() {
             pose: Default::default(),
         }
     }
-    // Sword and dagger, engaged: the same loadout twice, differing only in the descriptor bit.
+    // Sword and dagger, engaged; only the disarm bit differs.
     fn fighter(app: &mut App, disarmed: bool) -> Entity {
         app.world_mut()
             .spawn((
@@ -3664,8 +3278,6 @@ fn a_disarmed_attacker_swings_and_stands_unarmed() {
             .is_some()
     };
 
-    // The engaged standing idle: `0x5fcdc0`'s weapon-class Ready, or ReadyUnarmed for the hand
-    // the disarm emptied.
     let mut stand = app();
     let armed = fighter(&mut stand, false);
     let disarmed = fighter(&mut stand, true);
@@ -3677,8 +3289,7 @@ fn a_disarmed_attacker_swings_and_stands_unarmed() {
         "the disarmed hand stands ReadyUnarmed, sword or no sword"
     );
 
-    // One swing per hand, each on its own pair — a second swing over a live one is the combat
-    // fast-path's deferral (`0x5fcc10`), which has nothing to say about disarm.
+    // A fresh pair per hand: a second swing over a live one would park (`0x5fcc10`).
     let swings = |hit_info: u32| {
         let mut app = app();
         let armed = fighter(&mut app, false);
@@ -3704,7 +3315,7 @@ fn a_disarmed_attacker_swings_and_stands_unarmed() {
         (nodes(armed), nodes(disarmed))
     };
 
-    // The MAINHAND swing (`0x6246a0`, HitInfo bit 0x4 clear): Attack1H(17) vs AttackUnarmed(16).
+    // The main-hand swing, HitInfo bit 0x4 clear.
     let (armed_nodes, disarmed_nodes) = swings(0);
     assert!(
         armed_nodes.contains(&2),
@@ -3715,10 +3326,8 @@ fn a_disarmed_attacker_swings_and_stands_unarmed() {
         "the disarmed attacker swings AttackUnarmed(16), never the sword's clip: {disarmed_nodes:?}"
     );
 
-    // …and the OFFHAND swing (HitInfo bit 0x4). This is the half the ladder decides: the
-    // off-hand gate's FIRST probe asks about the MAIN hand, and a main hand holding a weapon
-    // CANCELS it (`5ec28d je 0x5ec2aa`). A disarmed dual-wielder therefore keeps stabbing with
-    // the dagger — disarm hides exactly one weapon.
+    // The off-hand swing (bit 0x4): the gate's first probe is the main hand, and a weapon there
+    // cancels it (`0x5ec28d je 0x5ec2aa`), so a disarmed dual-wielder keeps its dagger.
     let (armed_nodes, disarmed_nodes) = swings(0x4);
     assert!(
         armed_nodes.contains(&6),
@@ -3730,9 +3339,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; the swing selector `0x6246a0`).
+/// With no main-hand weapon the disarm falls to the off hand: AttackUnarmedOff(117) (`0x6246a0`).
 #[test]
 fn an_off_hand_only_fighter_is_the_case_that_punches_off_hand() {
     let mut app = app();
@@ -3758,8 +3365,8 @@ fn an_off_hand_only_fighter_is_the_case_that_punches_off_hand() {
             AnimationTransitions::new(),
             AnimDriver::default(),
             Wielded {
-                main: None,          // nothing in the main hand to claim the disarm
-                off: Some((2, 0xf)), // …so the dagger is the weapon it hides
+                main: None,          // nothing here to take the disarm
+                off: Some((2, 0xf)), // so the dagger is what it hides
                 disarmed: true,
                 ..Default::default()
             },
@@ -3788,16 +3395,14 @@ fn an_off_hand_only_fighter_is_the_case_that_punches_off_hand() {
     assert!(!playing(6), "not the dagger's own clip");
 }
 
-/// The **play-time** substitution ([`super::super::select::unarmed_special`], `0x5fe2f0`): a
-/// spell kit's Special1H(57) becomes SpecialUnarmed(118) when both hands read empty — which a
-/// disarmed dual-wielder is NOT (it keeps its off hand), and a disarmed single-wielder is.
+/// At play time (`0x5fe2f0`) Special1H(57) turns SpecialUnarmed(118) only with both hands empty.
 #[test]
 fn a_special_goes_unarmed_only_when_both_hands_are_empty() {
     let model = || ModelAnimations {
         graph: Handle::default(),
         clips: vec![
             clip(0, 1, true),
-            clip(57, 2, false),  // Special1H — the kit's weapon spin
+            clip(57, 2, false),  // Special1H, the kit's weapon spin
             clip(118, 3, false), // SpecialUnarmed
         ],
         hand_close: [None, None],
@@ -3871,15 +3476,8 @@ fn a_special_goes_unarmed_only_when_both_hands_are_empty() {
     );
 }
 
-/// A creature whose template carries **DO_NOT_PLAY_WOUND_ANIM** (`type_flags & 0x8`) takes no
-/// wound flinch at all — the reference's `0x60ea9f` gate inside the flinch itself, so it covers
-/// every trigger: the melee hit, the `$HIT` echo and the spell-side severity-0 call alike
-/// (decision 2068). This is the skeleton case: no flesh, no recoil.
-///
-/// The control beside it is the whole point — the gate must key on bit `0x8` and nothing else,
-/// and benilla read the *neighbouring* bit for months. So the unflagged victim here carries
-/// `NO_FACTION_TOOLTIP | MORE_AUDIBLE` (`0x30`, the two bits we already consume) and must still
-/// flinch: a gate on either neighbour, or on "any flag at all", fails right here.
+/// `DO_NOT_PLAY_WOUND_ANIM` (`type_flags & 0x8`) refuses every flinch inside the flinch itself
+/// (`0x60ea9f`); the control carries the neighbouring bits `0x30` and must still flinch.
 #[test]
 fn a_no_wound_creature_takes_no_flinch() {
     fn model() -> ModelAnimations {
@@ -3887,7 +3485,7 @@ fn a_no_wound_creature_takes_no_flinch() {
             graph: Handle::default(),
             clips: vec![
                 clip(0, 1, true),  // Stand
-                clip(8, 2, false), // StandWound — the unengaged victim's severity-0 pick
+                clip(8, 2, false), // StandWound
             ],
             hand_close: [None, None],
             playable_animation_lookup: Vec::new(),
@@ -3897,7 +3495,6 @@ fn a_no_wound_creature_takes_no_flinch() {
             pose: Default::default(),
         }
     }
-    // The victim's descriptor, carrying the one field the gate keys on.
     fn streamed(entry: u32) -> crate::net::ObjectStore {
         crate::net::ObjectStore(ObjectFields::from_pairs(&[(OBJECT_FIELD_ENTRY, entry)]))
     }
@@ -3920,7 +3517,6 @@ fn a_no_wound_creature_takes_no_flinch() {
     {
         let mut names = app.world_mut().resource_mut::<crate::names::NameCache>();
         names.insert_creature(SKELETON, Some(record(DO_NOT_PLAY_WOUND_ANIM)));
-        // The control's flags are the two NEIGHBOURS, both set.
         names.insert_creature(WOLF, Some(record(NO_FACTION_TOOLTIP | MORE_AUDIBLE)));
     }
 
@@ -3937,8 +3533,7 @@ fn a_no_wound_creature_takes_no_flinch() {
     };
     let skeleton = spawn(&mut app, SKELETON);
     let wolf = spawn(&mut app, WOLF);
-    // A creature whose query has not answered yet: the reference's null-record leg passes, so it
-    // flinches like anything else.
+    // Not yet queried: the null-record leg passes (`0x6125f0`).
     let unqueried = spawn(&mut app, 4242);
     app.update(); // settle every base on Stand
 
@@ -3969,12 +3564,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` — 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.
+/// The flag also refuses the parry (`0x60ec1f` in the parry pick `0x60ec00`), which the `$CPP`
+/// ladder enters only on victimState 3, so a flagged creature still dodges.
 #[test]
 fn the_no_wound_flag_takes_the_parry_but_not_the_dodge() {
     fn model() -> ModelAnimations {
@@ -3982,7 +3573,7 @@ fn the_no_wound_flag_takes_the_parry_but_not_the_dodge() {
             graph: Handle::default(),
             clips: vec![
                 clip(0, 1, true),   // Stand
-                clip(21, 2, false), // Parry1H — a 1H sword's parry pick
+                clip(21, 2, false), // Parry1H, a 1H sword's parry
                 clip(30, 3, false), // Dodge
             ],
             hand_close: [None, None],
@@ -3994,7 +3585,7 @@ fn the_no_wound_flag_takes_the_parry_but_not_the_dodge() {
         }
     }
     const OBJECT_FIELD_ENTRY: u16 = 3;
-    const FLAGGED: u32 = 3870; // Stone Sleeper — really carries the bit on our world DB
+    const FLAGGED: u32 = 3870; // Stone Sleeper, which carries the bit in the world DB
     const PLAIN: u32 = 69;
 
     let mut app = app();
@@ -4021,8 +3612,7 @@ fn the_no_wound_flag_takes_the_parry_but_not_the_dodge() {
                 AnimationPlayer::default(),
                 AnimationTransitions::new(),
                 AnimDriver::default(),
-                // A 1H sword in the mainhand: `defense_anim` sends class 2 subclass 7 to
-                // Parry1H(21).
+                // A 1H sword: `defense_anim` sends class 2 subclass 7 to Parry1H(21).
                 Wielded {
                     main: Some((2, 7)),
                     ..Default::default()
@@ -4066,19 +3656,9 @@ fn the_no_wound_flag_takes_the_parry_but_not_the_dodge() {
     );
 }
 
-/// **The weapon-trail latch's edge** (decision 2076): `AnimDriver::started_anim` must be raised by
-/// a plain gait change, not only by a one-shot.
-///
-/// `0x5fe2f0` is the image's single animation entry point — locomotion reaches it through
-/// `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. 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
-/// still must NOT keep raising the edge and eating arms.
+/// Locomotion reaches the one entry point `0x5fe2f0` too (`0x602c60` → `0x5fd9e0` → `0x5fd8b0` →
+/// `0x5fd100`), so a gait change raises the trail edge; Charge's kit has anim id −1 (`0x60f366 jl`)
+/// and waits on it. With no per-frame recompute, a steady unit raises nothing.
 #[test]
 fn a_gait_change_raises_the_anim_edge_and_a_steady_frame_does_not() {
     let mut app = app();
@@ -4099,10 +3679,9 @@ fn a_gait_change_raises_the_anim_edge_and_a_steady_frame_does_not() {
             .unwrap()
             .started_anim()
     };
-    app.update(); // settle: Stand — itself a play
+    app.update(); // settle: Stand, itself a play
     app.update();
     assert!(!edge(&app), "a settled, motionless unit plays nothing");
-    // Start running: the gait changes, so the base track takes a play.
     app.world_mut().entity_mut(unit).insert(MovementState {
         flags: move_flags::FORWARD,
         speed: 7.0,
@@ -4115,7 +3694,6 @@ fn a_gait_change_raises_the_anim_edge_and_a_steady_frame_does_not() {
         !edge(&app),
         "…and holding that run is not — the reference has no per-frame recompute"
     );
-    // A one-shot raises it too, which is the ordinary case.
     app.world_mut().write_message(EmoteAnim {
         entity: unit,
         anim_id: 57,
@@ -4125,19 +3703,8 @@ 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).
-///
-/// `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
-/// trail arm survives that play. It matters because `0x60d835` arms a **one-slot** field with a
-/// plain `mov`: a second proc overwrites the first before it ever fires, and a client that fired
-/// on every request would draw trails from arms the reference superseded — with the superseded
-/// colours and durations, on 23 of the 34 type-8 kits.
-///
-/// benilla does not need to build that gate: the driver's request loop already fast-paths
-/// combat-over-combat (decision 0406) and `continue`s without playing, so the edge never rises.
-/// This pins the connection between the two, which is otherwise invisible — they live in different
-/// modules and neither mentions the other's mechanism.
+/// The combat fast path returns at `0x5fe48b`, before the trail latch's only read at `0x5fe48e`,
+/// so a pending trail arm (one slot, `0x60d835`) survives it: no anim edge rises.
 #[test]
 fn a_combat_over_combat_fast_path_does_not_raise_the_anim_edge() {
     let mut app = app();
@@ -4157,7 +3724,7 @@ fn a_combat_over_combat_fast_path_does_not_raise_the_anim_edge() {
             .deferred
     };
     app.update(); // settle: Stand
-                  // A combat one-shot — Special1H(57) is in `0x5fcc10`'s set, and the model has it.
+                  // Special1H(57) is in the combat set (`0x5fcc10`).
     app.world_mut().write_message(EmoteAnim {
         entity: unit,
         anim_id: 57,
@@ -4165,8 +3732,7 @@ fn a_combat_over_combat_fast_path_does_not_raise_the_anim_edge() {
     });
     app.update();
     assert!(edge(&app), "the first combat play arms normally");
-    // A SECOND combat request while the first still runs — AttackUnarmed(16), also in the set.
-    // The fast path re-times the live clip and parks the request; nothing is armed.
+    // A second combat request, AttackUnarmed(16), while the first runs.
     app.world_mut().write_message(SwingMessage {
         attacker: unit,
         victim: None,
@@ -4189,24 +3755,13 @@ fn a_combat_over_combat_fast_path_does_not_raise_the_anim_edge() {
     );
 }
 
-/// 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
-/// stops that overwriting the victim's `Knockdown` is `0x5fe2f0`'s head guard on
-/// `[unit+0xd58] & 0xc0000`, a bit the arm helper set keyed on the id it actually armed. So the
-/// recompute is not skipped — **the play it asks for is refused**, and the clip runs its full
-/// 2000 ms. The director watched exactly this on the reference client, fighting the Silithus worm
-/// whose Lash (6607) puts nothing on its victim but that one clip.
-///
-/// The same guard scopes 2085's claim that a state kit's anim is an animation *cutter*: it cannot
-/// cut a clip that took the lock, so Charge does **not** cut its own Knockdown.
+/// The base-animation lock: a stun root's recompute asks for `Stand(0)` and `0x5fe2f0`'s guard on
+/// `[unit+0xd58] & 0xc0000` refuses it, so a `Knockdown` (Lash, spell 6607) runs its 2000 ms.
 mod base_anim_lock {
     use super::*;
     use crate::creature_anim::{BaseAnimRecompute, Mode};
 
-    /// Stand, Knockdown (the locking id), and SpecialUnarmed (an ordinary one-shot that does not
-    /// lock) — the pair that separates the guard from a plain re-pick.
+    /// Nodes of Stand and the locking Knockdown; SpecialUnarmed, which takes no lock, is node 3.
     const STAND_NODE: u32 = 1;
     const KNOCKDOWN_NODE: u32 = 2;
 
@@ -4215,8 +3770,8 @@ mod base_anim_lock {
             graph: Handle::default(),
             clips: vec![
                 clip(0, STAND_NODE, true),        // Stand
-                clip(121, KNOCKDOWN_NODE, false), // Knockdown — takes the lock
-                clip(118, 3, false),              // SpecialUnarmed — takes nothing
+                clip(121, KNOCKDOWN_NODE, false), // Knockdown, takes the lock
+                clip(118, 3, false),              // SpecialUnarmed, takes none
             ],
             hand_close: [None, None],
             playable_animation_lookup: Vec::new(),
@@ -4263,8 +3818,7 @@ mod base_anim_lock {
         app.update();
     }
 
-    /// The whole report, in one assertion: a `Knockdown` on the base survives the recompute the
-    /// stun's own root triggers, because the `Stand` it asks for is refused.
+    /// A base `Knockdown` survives the stun root's recompute: the `Stand` it asks for is refused.
     #[test]
     fn a_knockdown_survives_the_base_recompute() {
         let mut app = app();
@@ -4291,8 +3845,7 @@ mod base_anim_lock {
         );
     }
 
-    /// …and the guard is the id's, not a blanket refusal: an ordinary one-shot takes no lock, so
-    /// the same recompute ends it. This is 2085's mechanism, correctly scoped.
+    /// An ordinary one-shot takes no lock, so the same recompute ends it.
     #[test]
     fn a_non_locking_one_shot_is_cut_by_the_same_recompute() {
         let mut app = app();
@@ -4331,15 +3884,13 @@ mod base_anim_lock {
         );
     }
 
-    /// The airborne clips, on the same victim — the director's follow-up report: *"there is some
-    /// bug it seems, I ended up stuck laying down after a knock, might be because I was jumping
-    /// or running at the same time"*.
+    /// The locking Knockdown and the airborne clips.
     fn airborne_model() -> ModelAnimations {
         ModelAnimations {
             graph: Handle::default(),
             clips: vec![
                 clip(0, STAND_NODE, true),        // Stand
-                clip(121, KNOCKDOWN_NODE, false), // Knockdown — takes the lock
+                clip(121, KNOCKDOWN_NODE, false), // Knockdown, takes the lock
                 clip(37, 3, false),               // JumpStart
                 clip(38, 4, true),                // Jump hang
                 clip(39, 5, false),               // JumpEnd
@@ -4366,15 +3917,8 @@ mod base_anim_lock {
             .id()
     }
 
-    /// **The wedge**: jumping while the lock is held used to stop the locked clip DEAD, and a clip
-    /// that never finishes never releases the lock — so the body lay on its back for the rest of
-    /// the session, every subsequent play refused.
-    ///
-    /// The mechanism is 0503's snapshot-freeze in [`super::play::leave_special`], which stills the
-    /// cut airborne clip before the landing cross-fades over it. It took whatever bone 0 held, on
-    /// the assumption that the arc's own clip is what it armed — and the lock is the first thing
-    /// ever to falsify that: every play the arc asked for was refused, so bone 0 still held the
-    /// `Knockdown`, and the landing froze *that*.
+    /// The landing freeze stills only the arc's own clip, never the locked `Knockdown`, which must
+    /// finish to release the lock.
     #[test]
     fn a_jump_taken_while_locked_never_freezes_the_locked_clip() {
         let mut app = app();
@@ -4388,8 +3932,7 @@ mod base_anim_lock {
             "the impact kit's Knockdown holds the base"
         );
 
-        // Space, flat on their back: the launch enters the bracket, and every clip in the bracket
-        // is refused — so bone 0 still holds the Knockdown for the whole arc.
+        // A jump while knocked down: every clip of the bracket is refused.
         app.world_mut().entity_mut(unit).insert(MovementState {
             flags: move_flags::FALLING,
             vertical_speed: 7.96,
diff --git a/crates/benilla-app/src/creature_anim/driver/wound.rs b/crates/benilla-app/src/creature_anim/driver/wound.rs
index 086ab0fb..d885b14c 100644
--- a/crates/benilla-app/src/creature_anim/driver/wound.rs
+++ b/crates/benilla-app/src/creature_anim/driver/wound.rs
@@ -1,6 +1,4 @@
-//! The wound-flinch secondary-blend slot logic for [`super::drive_animations`]: the per-frame decay
-//! upkeep ([`wound_upkeep`]), the same-bone re-arm eviction ([`wound_evict`]), and the victim trigger
-//! that arms the slot ([`wound_trigger`]) — split out of [`super`] as its own concern.
+//! The wound flinch: a decaying blend in the struck bone's secondary slot (`0x60ea70`).
 
 use benilla_assets::ModelAnimations;
 use benilla_formats::AnimDataCatalog;
@@ -9,33 +7,21 @@ use bevy::prelude::*;
 use super::super::{find_resolved, AnimDriver, MovementState, Wound};
 use super::select::{self, STAND};
 
-/// One frame's wound edge for a victim — the client's trigger paths into the same secondary
-/// slot (`0x60ea70`): a landed melee hit (`SMSG_ATTACKERSTATEUPDATE`, its `HitInfo` — severity
-/// is the crit bit) or a spell-side flinch ([`super::super::WoundAnim`]: the kit player's 8–10
-/// branch, the harmful instant impact, the missile impact — every one `severity = 0`, decision
-/// 2058). Both resolve to an id by severity + engagement at trigger time.
+/// A wound trigger into `0x60ea70`: a melee hit, severity its crit bit, or a spell, severity 0.
 #[derive(Clone, Copy)]
 pub(super) enum WoundEdge {
     Melee(u32),
     Spell,
 }
 
-/// Wound-flinch decay upkeep (decision 0111): the client's kernel advances every armed
-/// SECONDARY slot per bone per frame **unconditionally** — before any state logic, through
-/// death itself — and the slot self-releases at the decay's end (`0x7147b9`: `+0xd0 = -1`
-/// and λ = 0 the same frame). So this runs above the death override and touches nothing
-/// but its own node: λ = smoothstep(remaining)·0.75 over the clip's own span, blended out
-/// and gone — never a snap, never a stop of what plays underneath.
+/// Decays the wound every frame, above the death override: the kernel advances every armed
+/// secondary slot unconditionally, and the slot self-releases at λ = 0 (`0x7147b9`).
 pub(super) fn wound_upkeep(entity: Entity, drv: &mut AnimDriver, player: &mut AnimationPlayer) {
     if let Some(wd) = drv.wound {
         let finished = match player.animation_mut(wd.node) {
             Some(a) if !a.is_finished() => {
                 let remaining = 1.0 - a.seek_time() / wd.span;
-                // The λ-anchor: on the masked subtree the base (1.0) and a live one-shot
-                // overlay (8.0) both blend; the full-body route sits over the base alone.
-                // (During a base cross-fade the transition's fading clip briefly raises the
-                // real total past 1.0 — a sub-blend-time wobble we accept, the client's own
-                // transitions run through this very secondary slot instead.)
+                // The base, plus a live one-shot overlay when masked; a fading clip is not counted.
                 let others = if wd.masked && drv.overlay.is_some() {
                     1.0 + super::ONESHOT_OVERLAY_WEIGHT
                 } else {
@@ -59,18 +45,9 @@ pub(super) fn wound_upkeep(entity: Entity, drv: &mut AnimDriver, player: &mut An
     }
 }
 
-/// Wound-flinch eviction (decision 0114): the wound occupies its bone's SECONDARY slot,
-/// and a **blended primary re-arm on the same bone overwrites it** (op4 `blendFlag≠0`
-/// copies the outgoing pose over `+0xc4..` — the standard 150 ms transition fade takes
-/// 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 (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
-/// that follows it.
+/// Evicts the wound on a blended primary re-arm of its bone: op4 with `blendFlag≠0` copies the
+/// outgoing pose over the secondary slot (`+0xc4..`). The other bone's plays leave it decaying
+/// (`0x714260`); a mode or gait change counts as a bone-0 play.
 pub(super) fn wound_evict(
     entity: Entity,
     drv: &mut AnimDriver,
@@ -100,22 +77,11 @@ pub(super) fn wound_evict(
     }
 }
 
-/// 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), 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
-/// `DO_NOT_PLAY_WOUND_ANIM` template flag (decision 2068) and the CharProc-11 rate-override node
-/// (2063), in the reference's own order. The one client gate still without a benilla counterpart
-/// is the attached-spell-effect marker (no CEffect system until the VFX phases). The client
-/// calls op4 directly — not PlayAnimation — so the flinch is faithfully invisible to the
-/// sheath reconcile and the event scan. `id` is the wound anim to lay (8–10), already resolved
-/// by the caller — melee by severity/engagement ([`select::wound_anim`]), a spell impact by its
-/// kit's own column ([`WoundEdge`]).
+/// Lays wound clip `id` (8–10) into the secondary slot as a decaying 0.75-amplitude blend over
+/// whatever plays (`0x60ea70`, op4 `linkFlag=0`), with no mid-swing gate: the base track and the
+/// one-shot slot run on underneath. It calls op4, not `PlayAnimation`, so the sheath reconcile and
+/// event scan never see it; it is the frame's last write, as in the packet order.
+/// The caller holds the entry gates; the reference's attached-spell-effect gate is not built.
 pub(super) fn wound_trigger(
     entity: Entity,
     drv: &mut AnimDriver,
@@ -127,15 +93,12 @@ pub(super) fn wound_trigger(
     mv: &MovementState,
     mounted: bool,
 ) {
-    // Alive only (the `0x605f90` IsDead gate): the dead branch already `continue`d on
-    // health/dyn-flags; stand-state 7 (lying dead) is its third clause.
+    // `0x605f90`'s third IsDead clause, stand state 7; the dead branch took the other two.
     if mv.stand_state != 7 {
         let base = drv.resolved_anim(anims, catalog).unwrap_or(STAND);
         let full = select::wound_full_body(id, base, mv.flags, mounted);
-        // The wound rolls its variation like any one-shot (op4 is called with
-        // variationIdx −1 — decision 0114); span 0 = the client's degenerate seed
-        // (`end = clock`, expired on arrival) — skip. No resolvable clip at all is the
-        // `0x711a20` asset-presence abort.
+        // Rolls its variation (op4's `variationIdx −1`). A zero span expires on arrival
+        // (`end = clock`) and no clip at all is the `0x711a20` asset-presence abort: both skip.
         let clip = find_resolved(anims, id, catalog)
             .and_then(|h| anims.pick_variation(h.anim_id, rng.draw()))
             .filter(|c| c.duration > 0.0);
@@ -143,20 +106,18 @@ pub(super) fn wound_trigger(
             if full {
                 Some((c, c.node, false))
             } else {
-                // A model without the split bone degrades to the full-body node — still
-                // a decaying blend over the base, never a replace.
+                // No split bone: the full-body node, still a blend, never a replace.
                 c.upper_node
                     .map(|n| (c, n, true))
                     .or(Some((c, c.node, false)))
             }
         });
         if let Some((c, node, masked)) = node {
-            // A re-trigger re-seeds the slot (the client overwrites the secondary).
+            // A re-trigger re-seeds the slot: the client overwrites the secondary.
             if let Some(prev) = drv.wound.take() {
                 player.stop(prev.node);
             }
-            // If the node is still active after that stop, the base track owns it (a
-            // fallback chain degenerating to the playing clip) — nothing to layer.
+            // Still active after that stop: the base track owns the node, so nothing to layer.
             if player.animation(node).is_none() {
                 let others = if masked && drv.overlay.is_some() {
                     1.0 + super::ONESHOT_OVERLAY_WEIGHT
@@ -165,10 +126,7 @@ pub(super) fn wound_trigger(
                 };
                 let active = player.play(node);
                 active.replay();
-                // One pass only, and never a stale repeat from a prior play of this node: the
-                // client does roll a replay budget on this arm too, but the flinch's decay window
-                // is seeded from a single span (`+0x100 = clock + span`, decision 0111) — λ hits 0
-                // and the slot self-releases at first span-end, so R is moot for the wound.
+                // One pass: the decay window is one span (`+0x100 = clock + span`), whatever R.
                 active.set_repeat(bevy::animation::RepeatAnimation::Never);
                 active.set_weight(select::wound_weight(1.0, others));
                 drv.wound = Some(Wound {
@@ -176,9 +134,6 @@ pub(super) fn wound_trigger(
                     span: c.duration,
                     masked,
                 });
-                // The `WOW_MOVE_TRACE` line a flinch report is read against: which id, which
-                // bone, over what span, and what it lays over (`others` = the subtree's other
-                // weight, so the peak share is always 75% — decision 0111).
                 if benilla_assets::trace::enabled() {
                     benilla_assets::trace::line(
                         "fct",
diff --git a/crates/benilla-app/src/creature_anim/emote_anim.rs b/crates/benilla-app/src/creature_anim/emote_anim.rs
index 6824f2fc..251bca99 100644
--- a/crates/benilla-app/src/creature_anim/emote_anim.rs
+++ b/crates/benilla-app/src/creature_anim/emote_anim.rs
@@ -1,30 +1,12 @@
-//! Bridge a bridged **anim** emote (`SMSG_EMOTE`) into the general one-shot player
-//! ([`super::EmoteAnim`]): resolve its `Emotes.dbc` id to an `AnimID` through the shared sound
-//! catalog ([`EmoteSounds`], promoted from `crate::sound`, decision 0070 slice 4) and hand off —
-//! after the **receive-side posture gate** ([`receive_eligible`]).
+//! Plays a bridged `SMSG_EMOTE` through the one-shot player ([`super::EmoteAnim`]), its
+//! `Emotes.dbc` id resolved through the shared catalog ([`EmoteSounds`]). A one-shot `/`-emote
+//! (`EmoteType` 0) sends `SMSG_TEXT_EMOTE` and `SMSG_EMOTE` from one handler for the same id
+//! (vmangos `ChatHandler.cpp:738`, `Unit.cpp:1789-1792`), so only `SMSG_EMOTE` animates; a state
+//! emote sets `UNIT_NPC_EMOTESTATE` instead and plays as the gait layer's idle.
 //!
-//! **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`
-//! (`HandleEmoteCommand` — `EmoteKind::Anim`) from the *same* handler, keyed on the *same*
-//! `Emotes.dbc` id (`EmotesTextEntry::textid` **is** the `Emotes.dbc` foreign key
-//! `EmotesText.EmoteID` — the id `SMSG_EMOTE` then carries). So consuming only `EmoteKind::Anim`
-//! here is complete for `/wave`-style emotes (no need to also key animation off
-//! `SMSG_TEXT_EMOTE`) and never double-fires: one player action yields exactly one `SMSG_EMOTE`,
-//! hence exactly one [`EmoteAnim`]. The looping state emotes (sit/sleep/kneel, `EmoteType != 0`)
-//! instead go through `Unit::HandleEmoteState` — a `UNIT_NPC_EMOTESTATE` field write, no
-//! `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**: 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
-//! test here.
+//! The reference's `SMSG_EMOTE` handler (`0x5e66b0`) never reads `Emotes.dbc`: it suppresses only
+//! a sleeping (stand state 3) or swimming performer ([`receive_eligible`]). The send-side gate in
+//! `crate::ui_chat` is a separate test, so do not add an `EmoteFlags` check here.
 
 use bevy::prelude::*;
 
@@ -33,11 +15,8 @@ use crate::sound::EmoteSounds;
 
 use super::{move_flags, EmoteAnim, Engaged, MovementState};
 
-/// The performer's live gate inputs, as both producers query them: stand-state (`ObjectStore`,
-/// any streamed unit incl. self), the movement flags (`MovementState` on our own avatar,
-/// `RemoteMotion` on a remote player — see `creature_anim`'s `unify`; a creature's spline carries
-/// no swim bit, so it defaults false), and the [`Engaged`] marker (the client's auto-attack
-/// target, decision 2067).
+/// The performer's gate inputs: stand state, move flags (`MovementState` for us, `RemoteMotion`
+/// for a remote player; a creature's spline carries no swim bit) and the [`Engaged`] marker.
 pub(super) type PerformerQuery<'w, 's> = Query<
     'w,
     's,
@@ -49,11 +28,7 @@ pub(super) type PerformerQuery<'w, 's> = Query<
     ),
 >;
 
-/// Route a bridged `SMSG_EMOTE` (an anim emote) to the general one-shot player: resolve its
-/// `Emotes.dbc` id through the shared catalog, gate on the performer's live posture
-/// ([`receive_eligible`] — module doc), and write [`EmoteAnim`]. A text emote (`EmoteKind::Text`)
-/// carries no anim id of its own here — see the module doc for why that's complete rather than a
-/// gap.
+/// Route a bridged `SMSG_EMOTE` to the one-shot player, gated on the performer's live state.
 pub(super) fn emote_to_anim(
     mut msgs: MessageReader<EmoteMessage>,
     mut out: MessageWriter<EmoteAnim>,
@@ -82,33 +57,22 @@ pub(super) fn emote_to_anim(
     }
 }
 
-/// The **posture** half of the gate (module doc — `EmoteFlags`-BLIND, unlike the send-side gate in
-/// `crate::ui_chat::emote_send_eligible`): suppress only at stand-state 3 (SLEEP) or while swimming.
-/// A merely-seated performer (SIT=1 / SIT_CHAIR=2 / KNEEL=8 / chair 4-6) is **not** suppressed —
-/// its anim plays and the composition layer masks it to waist-up.
-///
-/// Both producers apply this identically — `SMSG_EMOTE`'s handler at `0x5e6706`/`0x5e66f7`, and the
-/// client-local gesture dispatcher at `0x60bb52`/`0x60bb61` — which is why it is a free function and
-/// not a step of either.
+/// The posture half of the gate, which both producers apply (`SMSG_EMOTE` at
+/// `0x5e6706`/`0x5e66f7`, the gesture dispatcher at `0x60bb52`/`0x60bb61`): only sleep (stand
+/// state 3) or swimming suppresses; a seated performer plays, masked to waist-up downstream.
 pub(super) fn receive_eligible(stand_state: u8, swimming: bool) -> bool {
     stand_state != 3 && !swimming
 }
 
-/// The **shared player's** half of the gate — the client's `0x5fcd20`, the single function both
-/// 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 (`0x5fcd5d`) is the anim driver's
-/// same-id dedup, and `[+0xd58] & 0x400` (`0x5fcd8e`) is an internal anim-state bit with no
-/// benilla equivalent.
+/// The shared player's half, `0x5fcd20`: no play while channeling (`0x5fcd83`) or in combat
+/// (`0x5fcd9d`). Its already-armed test (`0x5fcd5d`) is the driver's same-id dedup, and its
+/// `[+0xd58] & 0x400` test (`0x5fcd8e`) reads an anim-state bit with no counterpart here.
 fn player_eligible(channeling: bool, in_combat: bool) -> bool {
     !channeling && !in_combat
 }
 
-/// The whole gate for one unit, from its live components — the predicate both producers call.
-/// `engaged` is the unit's [`super::Engaged`] marker: the client's auto-attack-target GUID
-/// `[unit+0xc48]`, the half of the in-combat test that actually fires (below).
+/// The whole gate for one unit, as both producers call it; `engaged` stands for the client's
+/// auto-attack target `[unit+0xc48]`.
 pub(super) fn play_eligible(
     store: Option<&ObjectStore>,
     movement: Option<&MovementState>,
@@ -128,19 +92,12 @@ pub(super) fn play_eligible(
     receive_eligible(stand_state, swimming) && player_eligible(channeling, in_combat)
 }
 
-/// The flag half of the client's in-combat predicate `0x60ecd0` (`shr edx,0xb; test dl,1` on
-/// `UNIT_FIELD_FLAGS` — bit 11, `0x800`; the other half is `0x60ecb0`, the auto-attack target).
-/// **vmangos never sets this bit on a fighting player or creature**: its in-combat flag is
-/// `UNIT_FLAG_IN_COMBAT = 0x80000`, and `0x800` is `UNIT_FLAG_PET_IN_COMBAT`, a pet-only bit. So
-/// on our server the flag half is dormant and the attack-target half carries the whole gate — which
-/// is why checking the wire flag alone (decision 1469) let every crit's `EMOTE_ONESHOT_WOUNDCRITICAL`
-/// play as a full CombatCritical one-shot on a fighting unit, cutting or fast-pathing its own swing
-/// (decision 2067). The bit is kept for fidelity to the byte, not because it fires here.
+/// The flag half of the in-combat test `0x60ecd0` (`UNIT_FIELD_FLAGS` bit 11); the other half is
+/// the auto-attack target (`0x60ecb0`). vmangos marks combat with `0x80000` and sets `0x800` only
+/// on a pet or charmed unit (`Unit.cpp:6170-6173`), so there the attack target carries the gate.
 const UNIT_FLAGS_COMBAT_BIT: u32 = 0x800;
 
-/// The pure mapping: an `Anim` emote resolves through `lookup` (the catalog's `Emotes.dbc` →
-/// `AnimID`); a `Text` emote never carries an anim id through this path — its animation, when it
-/// has one, arrives separately as the *same action's* `SMSG_EMOTE` (see the module doc).
+/// A `Text` emote's animation arrives as its own `SMSG_EMOTE`.
 fn resolve_anim_emote(kind: EmoteKind, lookup: impl Fn(u32) -> Option<u32>) -> Option<u32> {
     match kind {
         EmoteKind::Anim(id) => lookup(id),
@@ -156,16 +113,12 @@ mod tests {
     fn only_anim_kind_resolves_and_only_through_the_catalog() {
         let lookup = |id: u32| if id == 3 { Some(66) } else { None };
         assert_eq!(resolve_anim_emote(EmoteKind::Anim(3), lookup), Some(66));
-        // A text emote never maps to an anim through this path — its SMSG_EMOTE sibling does.
         assert_eq!(resolve_anim_emote(EmoteKind::Text(101), lookup), None);
-        // An anim emote absent from the catalog (or AnimID 0, already filtered by the catalog)
-        // stays None rather than defaulting to something.
+        // An id the catalog lacks (AnimID 0 included) stays `None`.
         assert_eq!(resolve_anim_emote(EmoteKind::Anim(999), lookup), None);
     }
 
-    // ── The receive-side posture gate (`receive_eligible`) — EmoteFlags-BLIND (module doc):
-    // stand-state 3 (SLEEP) or swimming suppresses; every other stand-state, including seated,
-    // plays (the composer masks a seated performer's anim to waist-up downstream).
+    // ── The receive-side posture gate ──
     #[test]
     fn sleep_suppresses_the_receive_side_anim() {
         assert!(!receive_eligible(3, false));
@@ -176,8 +129,6 @@ mod tests {
         assert!(!receive_eligible(0, true));
     }
 
-    /// The shared player refuses while channeling or in combat — the two `0x5fcd20` tests benilla
-    /// was missing on BOTH producers, not just the new one.
     #[test]
     fn channeling_or_combat_suppresses_the_play() {
         assert!(
@@ -188,10 +139,8 @@ mod tests {
         assert!(!player_eligible(false, true), "in combat suppresses");
     }
 
-    /// The attack-target half of `0x60ecd0` (decision 2067): a unit with the [`super::super::Engaged`]
-    /// marker — ATTACKSTART..ATTACKSTOP, the client's `[+0xc48]` — refuses the play even with no
-    /// store at all (vmangos's `0x80000` in-combat flag is not the bit the client tests, so the
-    /// marker is what makes a brawl's crit emote silent, exactly like the reference).
+    /// The attack-target half of `0x60ecd0` (`[+0xc48]`, from ATTACKSTART to ATTACKSTOP) refuses
+    /// on its own: on vmangos the flag half never fires for a fighting player or creature.
     #[test]
     fn an_engaged_unit_refuses_the_play_without_the_flag_bit() {
         assert!(
@@ -203,7 +152,7 @@ mod tests {
 
     #[test]
     fn merely_seated_is_not_suppressed_on_receive() {
-        // Unlike the send-side gate, sit/sit-chair/chair/kneel all pass here — only SLEEP does not.
+        // Unlike the send-side gate, every seated state passes; only sleep does not.
         for stand_state in [0u8, 1, 2, 4, 5, 6, 8] {
             assert!(
                 receive_eligible(stand_state, false),
diff --git a/crates/benilla-app/src/creature_anim/env_damage.rs b/crates/benilla-app/src/creature_anim/env_damage.rs
index eab176a1..a5cd74ec 100644
--- a/crates/benilla-app/src/creature_anim/env_damage.rs
+++ b/crates/benilla-app/src/creature_anim/env_damage.rs
@@ -1,40 +1,18 @@
-//! 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
-//!    `SpellVisualKit` id, played on the victim through the ordinary discrete kit play
-//!    ([`super::KitPush`] → `PlaySpellVisualKit` `0x60edf0`). This is the *unconditional tail* of
-//!    the reference's 0x1FC consequence method `0x624f30` (fires for any resolved unit; the
-//!    floating damage number + self-only chat line are the method's other two legs, not modeled).
-//!    The server sends no sound with it — `0x624f30` plays no vocal at all.
-//!
-//! 2. **The client-side landing predictor** (`0x602d00`, the movement tick's *other* caller of
-//!    `0x624f30`): on a hard landing the client plays the unit's wound vocal (class 2 →
-//!    CreatureSoundData) AND re-fires the *same* fall kit locally with damage 0 — without waiting
-//!    for the server. So a damaging local fall shows the puff twice (predicted, then echoed an
-//!    RTT later) and the grunt is heard immediately. The metric is **fall height in yards**
-//!    (`0x7c60c0`), gated at [`HARD_LANDING_DESCENT`]. The vocal leg lives in [`crate::sound`]
-//!    (it owns the voice catalog); the dust leg is [`hard_landing_dust`] here; both gate on the
-//!    same descent.
-//!
-//! **Deliberate scope (decision 0412):** benilla drives the predictor from the *self* controller's
-//! landing edge only — remote movers' landings aren't detected yet, though the reference fires it
-//! for any mover (its call graph reaches `0x602d00` from the networked movement handler). And the
-//! HARD gate's immunity modifier (feather-fall / safe-fall auras force SOFT in the `13 < h < 70`
-//! band; `h ≥ 70` bypasses it) isn't modeled — those auras aren't tracked, so every fall past the
-//! floor reads HARD, which is the common case.
+//! Environmental-damage feedback: the fall dust puff, fired by two independent sources as in the
+//! reference. `SMSG_ENVIRONMENTALDAMAGELOG` plays its damage type's kit on the victim and no sound
+//! (`0x624f30`, through `0x60edf0`); the landing predictor `0x602d00`, run for every mover, plays
+//! the wound vocal ([`crate::sound`]) and re-fires the fall kit at once ([`hard_landing_dust`]), so
+//! a damaging fall puffs twice.
 
 use bevy::prelude::*;
 
 use benilla_assets::{LockRecover, WorldAssets};
 
-/// The loaded 6-slot table (`None` until the startup load lands; absent = no environmental
-/// feedback kits, like every optional DBC face).
+/// `EnvironmentalDamage.dbc`'s six damage-type kits; absent, no environmental kit plays.
 #[derive(Resource)]
 pub(crate) struct EnvDamageTable(pub(crate) benilla_formats::EnvironmentalDamageTable);
 
-/// Load the table off the patch chain at startup (the [`super::blood`] pattern).
+/// Load the table off the patch chain at startup.
 pub(super) fn load_env_damage_table(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let Some(assets) = assets else { return };
     let loaded = {
@@ -49,30 +27,22 @@ pub(super) fn load_env_damage_table(mut commands: Commands, assets: Option<Res<W
     }
 }
 
-/// The landing predictor's HARD-landing gate — the client's `[0x80c414]` = **13.0** yd of fall
-/// height (`0x602d00`'s `fcomp 13.0`, byte-verified). Below it the client plays only its
-/// jump-end/land sound (SOFT — class 0xc, not modeled here); above it comes the wound grunt + the
-/// dust puff. The sibling constant `[0x80c418]` = 70.0 yd is the *unconditional* tier that bypasses
-/// the immunity check (feather/safe-fall) — moot for us until those auras are tracked, so every
-/// fall past this floor reads HARD. Note the client grunts from 13.0 yd but the *server* only
-/// damages from ≈14.57 yd, so a 13–14.57 yd fall grunts and puffs with zero damage and no packet —
-/// faithful (decision 0412).
+/// The hard-landing floor, `[0x80c414]` = 13.0 yd of fall height (`0x602d00`); below it only the
+/// land sound plays. Below `[0x80c418]` = 70.0 yd a dead or ghost mover lands soft (`0x605f30`),
+/// which is not built. The server damages only from 14.57 yd (vmangos `Player.cpp:20968`), so a
+/// shorter hard landing grunts and puffs with no damage packet.
 pub(crate) const HARD_LANDING_DESCENT: f32 = 13.0;
 
-/// The controller's landing report, written on **every** landing (ungated — consumers apply
-/// [`HARD_LANDING_DESCENT`], keeping the predictor's threshold law in this byte-cited module).
+/// A mover's landing, reported on every landing; consumers apply [`HARD_LANDING_DESCENT`].
 #[derive(Message, Clone, Copy)]
 pub(crate) struct HardLanding {
     pub(crate) entity: Entity,
-    /// Fall height in yd: the arc's launch height − the landing height. The reference's metric is
-    /// apex−current (`0x7c60c0`), which equals this for a step-off (launch *is* the apex) and
-    /// overcounts ours by at most the jump rise (~1.6 yd) for a jump *off* a ledge — negligible
-    /// against the 13-yd floor, and only near the boundary.
+    /// Fall height in yd, launch height minus landing height. The reference's `0x7c60c0` measures
+    /// from the apex, which a jump off a ledge puts up to about 1.6 yd above the launch.
     pub(crate) descent: f32,
 }
 
-/// The dust leg of the landing predictor: `0x602d00`'s tail re-fires `0x624f30(type 2, damage 0)`
-/// — the same fall kit the wire arm plays — locally, at the landing frame.
+/// The predictor's dust leg: `0x602d00` re-fires `0x624f30(type 2, damage 0)` at the landing frame.
 pub(super) fn hard_landing_dust(
     mut landings: MessageReader<HardLanding>,
     table: Option<Res<EnvDamageTable>>,
@@ -83,7 +53,7 @@ pub(super) fn hard_landing_dust(
         if l.descent <= HARD_LANDING_DESCENT {
             continue;
         }
-        // Damage type 2 = fall (the predictor is fall-only; the other five types are wire-only).
+        // Type 2, fall: the predictor's only type.
         if let Some(kit_id) = table.as_ref().and_then(|t| t.0.kit_id(2)) {
             debug!(
                 "anim: hard landing ({:.1} yd) → predicted dust kit {kit_id}",
diff --git a/crates/benilla-app/src/creature_anim/events.rs b/crates/benilla-app/src/creature_anim/events.rs
index ecb6256d..e20bf8f3 100644
--- a/crates/benilla-app/src/creature_anim/events.rs
+++ b/crates/benilla-app/src/creature_anim/events.rs
@@ -1,7 +1,5 @@
-//! The model event-keyframe scanner: [`fire_anim_events`] and its helpers, plus the
-//! [`AnimSoundEvent`] message it emits — the animation timeline's outbound trigger surface
-//! (decision 0070 slice 3). Kept in its own file as its own small concern, separate from the
-//! driver ([`super::driver`]) that advances the clips it scans.
+//! The model event-keyframe scanner: [`fire_anim_events`] fires the M2 `$xxx` keys each playing
+//! clip crossed this frame as [`AnimSoundEvent`]s.
 
 use benilla_assets::{AnimClip, ModelAnimations};
 use bevy::animation::graph::AnimationNodeIndex;
@@ -10,10 +8,7 @@ use bevy::prelude::*;
 use super::{resolved_id, AnimData, AnimDriver};
 use crate::names::type_flags::MORE_AUDIBLE;
 
-/// A model **event keyframe** crossed during playback this frame (the M2 `$xxx` tags — decision
-/// 0070 slice 3): the animation timeline's outbound trigger surface. The sound subsystem routes
-/// the audio tags (`$SND` kits, footsteps, `$CSS` swings, fidgets); future consumers (camera
-/// shake `$SHK`, footprints) read the same stream.
+/// A model event keyframe (an M2 `$xxx` tag) crossed during playback this frame.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct AnimSoundEvent {
     pub(crate) entity: Entity,
@@ -21,39 +16,22 @@ pub(crate) struct AnimSoundEvent {
     pub(crate) ident: [u8; 4],
     /// The tag payload (a SoundEntries id for `$SND`/`$DSL`/`$DSO`; 0 otherwise).
     pub(crate) data: u32,
-    /// The `AnimationData.dbc` id of the **clip that fired the key**.
-    ///
-    /// This is the reference's `0x5fdb50` answer at the instant a handler runs: that helper reads
-    /// the model's currently-playing animation id, and a key fires from a clip the model is
-    /// playing, at that key's own time in it. Two dispatch arms branch on it — the `$BWR` weapon
-    /// family fork (`0x5fcfb0` bow {46,105,109} vs `0x5fcfd0` rifle {49,106,110}, decision 2281) —
-    /// and carrying it here is what lets them ask without re-deriving "what is this unit playing"
-    /// from a player whose one-shot overlays outrank its base clip in weight.
+    /// The `AnimationData.dbc` id of the clip that fired the key: the reference's `0x5fdb50`
+    /// answer when a handler runs, which the `$BWR` bow/rifle fork reads (`0x5fcfb0` bow
+    /// {46,105,109}, `0x5fcfd0` rifle {49,106,110}).
     pub(crate) anim_id: u16,
-    /// **Where the key fired** — the reference's own `placementMatrix · (boneMatrix[event.bone] ·
-    /// 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).
-    ///
-    /// 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
-    /// player model authors ride the head. `None` only when the model carries no rig *and* no
-    /// world frame to place it in — the consumer then falls back to the object's own transform,
-    /// which is what all of them used to do unconditionally.
+    /// Where the key fired, `placementMatrix · (boneMatrix[bone] · position)`, snapshotted at the
+    /// fire as the event kernel `0x719370` does for every dispatcher (`0x5ffbd0` units,
+    /// `0x5f3e20` GameObjects, `0x6951e0` placed models). Not the object's origin: 149 of 244
+    /// shipped `$DSL` keys sit off it, up to 67.6 yd. `None` uses the object's own transform.
     pub(crate) pos: Option<Vec3>,
 }
 
-/// The frame a scanner resolves a fired key's world point in — the two exact cases, named.
-///
-/// A **rigged** model composes the record's bone-local offset through that bone's live joint
-/// global, which is the kernel's `boneMatrix[bone] · position` and then the placement. A model
-/// with **no rig** has no bone matrices at all, and with no keys every bone composes to the
-/// identity — so `placement · position` is not an approximation of the kernel's quantity, it *is*
-/// it. That second case is the whole placed-doodad population: 0 of 244 `$DSL` records ride a bone
-/// any sequence keys (`benilla-extract eventmarkerscan`).
+/// The frame a fired key's world point resolves in: a rigged model composes the key's bone-local
+/// offset through that bone's live joint; a rig-less one has only identity bones, so
+/// `placement · point` is the kernel's value exactly.
 pub(crate) struct EventFrame<'a> {
-    /// The model's own world frame — the reference's placement matrix.
+    /// The model's world frame, the reference's placement matrix.
     pub(crate) world: &'a GlobalTransform,
     /// The composed pose and its joints root, for a model that has a rig.
     pub(crate) rig: Option<(&'a benilla_world::rig_anim::RigPose, &'a GlobalTransform)>,
@@ -68,75 +46,35 @@ 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:
-///
-/// - **`$FSD` → `0x623390`: the footstep SOUND**, and nothing else — it never reaches the decal
-///   path ([`is_footstep_sound`]).
-/// - **the per-foot side tags → `0x5fbf70`: the VISUAL footfall** — the footprint decal and the
-///   spray/splash particle, and no sound at all ([`footfall_side`]).
-///
-/// So a gait that authors both fires **one** sound per `$FSD` key, not one per key of either
-/// family: HumanMale's Walk keys `$FR0 · $FSD · $FL0 · $FSD` over 1 s and the real client plays
-/// **two** steps there, while its turn-in-place ShuffleLeft/Right key only `$SL0 $SR0` at
-/// `t = 0.000` and are **silent** (decision 1080).
-///
-/// The **sound** channel: the dispatch tag `$FSD` alone.
+/// The footstep sound channel: `$FSD` alone, which the dispatcher `0x5ffbd0` routes to
+/// `0x623390`; the per-foot side tags go to the visual handler `0x5fbf70` and never sound.
 pub(crate) fn is_footstep_sound(ident: &[u8; 4]) -> bool {
     ident == b"$FSD"
 }
 
-/// **The footfall handler's own radius**, `2500 yd²` (50 yd) — `[0x80c5b4]`, read at `0x5fc00a`
-/// inside `0x5fbf70`. This gate stands *above* everything that handler goes on to spawn: the
-/// footprint decal ([`crate::footprints`]), the footstep camera shake
-/// ([`crate::camera_shake`]) and the 25 yd spray branch below it all live under it, so it is one
-/// constant and not one per consumer — they held a copy each until they disagreed about its
-/// 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.
-///
-/// **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
-/// **ring-pool select**, not an early bypass.
+/// The footfall handler's radius, 2500 yd² (50 yd, `[0x80c5b4]` read at `0x5fc00a` in
+/// `0x5fbf70`), measured from the active camera's eye (`0x4818f0`, `[[0xb4b2bc]+0x65b8]`). It
+/// gates all the handler spawns (decal, camera shake, spray), the local player's feet included:
+/// the `GUID == local player` compare (`0x5fc042`–`0x5fc06b`) only picks the decal's ring pool.
 const FOOTFALL_RADIUS_SQ: f32 = 2500.0;
 
-/// **Is this footfall out of range?** The handler's distance gate, whole: the kernel, the
-/// threshold and the compare, because all three are load-bearing and splitting them is what
-/// let two consumers disagree.
-///
-/// The kernel rounds **once, at the end**. The reference is x87: it loads the two `C3Vector`s as f32, and keeps every difference, square
-/// and sum in 80-bit extended, then `fstp`s the sum to a **single f32** (`0x5fbffe` store,
-/// `0x5fc007` reload) before the compare. A plain `Vec3::distance_squared` rounds six times
-/// instead of once and can land on the other side of the branch for a footfall sitting on the
-/// 50 yd edge.
-///
-/// f64 reproduces it exactly and needs no x87: an `f32 − f32` widened first is exact, a 24×24→48
-/// 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.
-///
-/// 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
-/// `>` reproduces for free. It lives here rather than at the call sites so the strictness and the
-/// NaN edge are stated once instead of re-spelled per consumer.
+/// Whether a footfall is out of the handler's range. The reference sums in x87 extended and
+/// rounds once to f32 (`0x5fbffe` store, `0x5fc007` reload); f64 holds every difference, square
+/// and sum exactly, so this matches bit for bit where `Vec3::distance_squared` can round across
+/// the 50 yd edge. The compare is strict and keeps a NaN (`test ah,0x41; je`), as `>` does.
 pub(crate) fn footfall_culls(a: Vec3, b: Vec3) -> bool {
     footfall_dist2(a, b) > FOOTFALL_RADIUS_SQ
 }
 
-/// The gate's `dist²`, split out so the tests can see the number the compare is handed.
+/// The gate's `dist²`, rounded to f32 once.
 fn footfall_dist2(a: Vec3, b: Vec3) -> f32 {
     let d = |p: f32, q: f32| p as f64 - q as f64;
     let (dx, dy, dz) = (d(a.x, b.x), d(a.y, b.y), d(a.z, b.z));
     (dx * dx + dy * dy + dz * dz) as f32
 }
 
-/// The **visual** channel: the foot side a per-foot plant tag names (`$FL0` → `L`), or `None` for
-/// every other tag — the trigger for footfall-driven *visuals* ([`crate::footprints`]). The ten
-/// families the dispatcher tables, each with its `0/1/2/3` variants: `$FL/$FR` (front),
-/// `$RL/$RR` (rear), `$SL/$SR` (shuffle), `$BL/$BR` (backwards), `$WL/$WR` — call sites
-/// `0x5ffe32` (`push 1`, LEFT) and `0x5ffc82` (`push 0`, RIGHT).
+/// The visual footfall channel: the foot side a per-foot tag names (`$FL0` gives `L`), over the
+/// ten families the dispatcher tables (`0x5ffe32` left, `0x5ffc82` right).
 pub(crate) fn footfall_side(ident: &[u8; 4]) -> Option<u8> {
     matches!(
         &ident[..3],
@@ -145,15 +83,11 @@ pub(crate) fn footfall_side(ident: &[u8; 4]) -> Option<u8> {
     .then_some(ident[2])
 }
 
-/// How far (seconds) into a just-armed clip the playhead may have been *at the arm* for
-/// [`advance_track`] to open the next frame's window at the clip's head (`t = 0` keyframes
-/// included). Comfortably above a frame (even a hitchy one), comfortably below the corpse
-/// settle's `seek_to(duration)` (every Death clip is > 1 s).
+/// How far (s) into its clip an arm may land and still open the next window at the head: above
+/// a hitchy frame, below the corpse settle's `seek_to(duration)` (every Death clip is over 1 s).
 const FRESH_CLIP_HEAD: f32 = 0.25;
 
-/// One scanned track's memory: the graph node playing, the seek last seen on it, and whether that
-/// seek is an **arm stamp** — the frame the clip was armed, which fires nothing (see
-/// [`advance_track`]).
+/// One scanned track's memory: the playing node, its last seek, and whether that seek is the arm.
 #[derive(Clone, Copy)]
 pub(crate) struct TrackSeek {
     node: AnimationNodeIndex,
@@ -161,20 +95,13 @@ pub(crate) struct TrackSeek {
     armed: bool,
 }
 
-/// A scanner's per-entity track memory — the `Local` every [`advance_track`] caller owns.
+/// A scanner's per-entity track memory, the `Local` each [`advance_track`] caller owns.
 pub(crate) type TrackMemory = bevy::ecs::entity::EntityHashMap<TrackSeek>;
 
-/// Fire the event keyframes the current clip crossed since last frame. Runs after
-/// [`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 (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
-/// head window (so `t = 0` keyframes are real), and a clip that doesn't survive its arm frame
-/// fires nothing at all — the reference's own walker rule, byte-cited there.
-#[allow(clippy::type_complexity)] // one Bevy query tuple — the house convention
+/// Fire the event keys each unit's base and overlay clips crossed since last frame; runs after
+/// [`super::driver::drive_animations`]. A `t = 0` key re-fires on every loop wrap, as in the
+/// reference's walker `0x719370`.
+#[allow(clippy::type_complexity)] // one Bevy query tuple, the house convention
 pub(super) fn fire_anim_events(
     units: Query<(
         Entity,
@@ -182,19 +109,16 @@ pub(super) fn fire_anim_events(
         &AnimationPlayer,
         &AnimDriver,
         Has<benilla_world::rig_anim::AnimParked>,
-        // The unit's descriptor — read for ONE field, `OBJECT_FIELD_ENTRY`, the key its cached
-        // creature template hangs off (see the `MORE_AUDIBLE` read below).
+        // Read only for `OBJECT_FIELD_ENTRY`, the key of the cached creature template.
         Option<&crate::net::ObjectStore>,
         &GlobalTransform,
         Option<&benilla_world::rig_anim::RigPose>,
     )>,
-    // The joint roots the composed poses hang off — read, never spawned (decision 1355's pure
-    // position read).
+    // The joint roots the composed poses hang off.
     globals: Query<&GlobalTransform>,
     mut last: Local<TrackMemory>,
-    // The **masked overlay** track's own memory (decision 0087): a swing/emote routed to the
-    // SpineLow overlay plays *beside* the base, so its events (a swing's `$CSS`, an emote's `$CSD`)
-    // are scanned on their own node — the base scan above never sees them.
+    // The masked overlay's own memory: a swing or emote there plays beside the base, so its keys
+    // are scanned on their own node.
     mut last_overlay: Local<TrackMemory>,
     mut out: MessageWriter<AnimSoundEvent>,
     anim_data: Option<Res<AnimData>>,
@@ -202,15 +126,10 @@ pub(super) fn fire_anim_events(
 ) {
     let catalog = anim_data.as_deref().map(|d| &d.0);
     for (entity, anims, player, drv, parked, store, world, pose) in &units {
-        // The election's TICK half (decision 1482): a parked unit's event tracks are not
-        // scanned — the reference's pass-2 walk never inserts the model into the tick worklist
-        // (`0x683dd0` walk 2 skips `0x710b90`) — unless its cached template carries
-        // `MORE_AUDIBLE`, the `0x607da0` re-link arm that keeps an off-screen flagged
-        // creature's combat audible. A missing template record reads NOT audible (the
-        // reference's `0x623b70` null leg — fail closed; the record lands within a second of
-        // streaming anyway). The track memories are dropped so a waking track re-ARMS — firing
-        // nothing on the wake frame — instead of scanning the whole parked gap as one
-        // crossing; the reference's re-admission is likewise a fresh record.
+        // A parked unit's tracks are not scanned, as the reference's second walk never ticks it
+        // (`0x683dd0` skips `0x710b90`), unless its template carries `MORE_AUDIBLE` (the
+        // `0x607da0` re-link); a missing template reads not audible (`0x623b70`). Dropping the
+        // memories makes a waking track re-arm rather than scan the whole parked gap.
         if parked
             && !store
                 .and_then(|s| s.0.object_entry())
@@ -221,12 +140,8 @@ pub(super) fn fire_anim_events(
             last_overlay.remove(&entity);
             continue;
         }
-        // Base track: the **resolved** id (decision 0082) — the clip whose timeline is actually
-        // advancing, which can differ from the requested `active_anim()` when this model falls back —
-        // then the id's **playing variation** (decision 0114: a one-shot rolled one of the id's
-        // variation clips, each its own node with its own event track). During a same-id cross-fade
-        // (swing variation A fading under fresh variation B) the newest play — the smallest seek —
-        // is the track; the node-keyed memory then treats the switch as a clip change.
+        // Base track: the resolved id's playing variation, each variation its own node and event
+        // track; in a same-id cross-fade the newest play (the smallest seek) is scanned.
         let frame = EventFrame {
             world,
             rig: pose.and_then(|p| Some((p, globals.get(p.joints_root).ok()?))),
@@ -244,11 +159,7 @@ pub(super) fn fire_anim_events(
                 }
             }
         }
-        // Masked overlay track: events fire from whichever track plays the clip. The overlay knows
-        // its exact node — match it back to its clip (a variation's `upper_node`, decision 0114).
-        // A freshly-started overlay fires its head window one frame after the arm via
-        // [`advance_track`], so an emote's `t = 0` `$CSD` voice still rings; a swing's mid-clip
-        // `$CSS` fires as normal.
+        // Masked overlay track: its node matched back to the variation whose `upper_node` it is.
         if let Some(ov) = drv.overlay {
             let id = resolved_id(anims, ov.id, catalog);
             let clip = anims
@@ -268,27 +179,11 @@ pub(super) fn fire_anim_events(
     }
 }
 
-/// Advance a per-track memory and return the `prev` seek to scan events from, or `None` to only
-/// arm this frame. Keyed by the playing **graph node** (not the semantic id): two variations of
-/// the same id are different timelines with different event tracks (decision 0114), and a node
-/// switch is a clip change like any other.
-///
-/// **The arm frame fires nothing** — the reference's own rule, and the reason this is not simply
-/// "fire the head window when you see a new clip" (decision 1273). The client's animation arm
-/// `0x7121a0` bakes the block's window start `+0xa8 = now` (`0x712758`), so on that frame the
-/// walker computes `prev == cur` and `0x719518 jae` abandons the block before reading a single
-/// key. The window only opens on the **next** frame, and it opens at the arm stamp — local
-/// `t = 0` — with the fire test `prevL <= t < curL` (`0x7196d5`–`0x7196d9`), so `t = 0` keyframes
-/// are real (the emote voices carry `$CSD` at `0.000`) but only for a clip that is **still armed a
-/// frame later**. A clip armed and abandoned inside one frame fires nothing at all, which is what
-/// keeps a flickering Shuffle↔Stand churn silent in the reference — and is exactly what our
-/// fire-on-the-arm-frame rule turned into a footprint carpet under a stuttering mouse-turn.
-///
-/// So: a clip change (and first sight of a unit — it may have streamed in mid-clip) records the
-/// arm and returns `None`; the frame after an arm returns `-1.0`, opening the head window
-/// `[0, cur]`. An arm that *starts* deep in its timeline (the corpse settle's `seek_to(duration)`,
-/// past [`FRESH_CLIP_HEAD`]) opens at its own stamp instead, so a settled corpse never replays its
-/// collapse's keys.
+/// Advance a track's memory, keyed by graph node, and return the seek to scan from, or `None` on
+/// an arm frame. The reference's arm `0x7121a0` stamps the window start at now (`0x712758`), so
+/// the walker skips that frame (`0x719518`) and opens the next at the stamp, lower-inclusive
+/// (`0x7196d5`–`0x7196d9`): `t = 0` keys fire only for a clip still armed a frame later. An arm
+/// deep in its timeline (past [`FRESH_CLIP_HEAD`]) opens at its own stamp, not the head.
 pub(crate) fn advance_track(
     last: &mut TrackMemory,
     entity: Entity,
@@ -312,17 +207,9 @@ pub(crate) fn advance_track(
     })
 }
 
-/// Fire the event keyframes `clip` crossed on `(prev, cur]`. A loop wrap (`cur < prev`) fires the
-/// tail `(prev, duration]` of the last cycle then the head `[0, cur]` of the new one.
-///
-/// **Every fired key is traced under `aev`** (`WOW_MOVE_TRACE`, `WOW_MOVE_TRACE_TAGS=aev`). This is
-/// the *asking* half of the sound instrument, and it was the half we did not have: the play log
-/// (`RUST_LOG=benilla_app::sound=debug`) says what sounded, but a report of the shape "this
-/// creature vocalises far too often" needs to separate *the tag fired too often* from *the tag
-/// fired as authored and the gate above it is missing*. Those are different bugs with different
-/// fixes — decision 1399 had to answer exactly that question for a pet owl and could only do it by
-/// reading the M2 by hand. One line per key, on the same clock as the mover and wire traces, so a
-/// vocal can be read against the clip that asked for it.
+/// Fire the keys `clip` crossed on `(prev, cur]`; a loop wrap (`cur < prev`) fires the tail
+/// `(prev, duration]` then the head `[0, cur]`. Every fired key is traced under the `aev` tag
+/// (`WOW_MOVE_TRACE`, `WOW_MOVE_TRACE_TAGS=aev`), on the clock of the mover and wire traces.
 pub(crate) fn scan_events(
     clip: &AnimClip,
     entity: Entity,
@@ -355,10 +242,7 @@ pub(crate) fn scan_events(
                             pos.x,
                             pos.y,
                             pos.z,
-                            // How far the key fired from the model's own origin — the whole
-                            // question this line was extended to answer (decision 1904). A
-                            // non-zero `off` is the marker being honoured; all-zero across a run
-                            // is the model-root fallback, which is what it used to be everywhere.
+                            // Distance from the model's origin; 0 is the model-root fallback.
                             pos.distance(frame.world.translation()),
                         ),
                     );
@@ -385,9 +269,6 @@ pub(crate) fn scan_events(
 mod tests {
     use super::*;
 
-    /// The gate's edge behaviour, which is the whole reason the kernel is not
-    /// `Vec3::distance_squared`: exactly 50 yd **passes** (the compare is strict), a NaN passes
-    /// with it, and the sum is rounded to f32 exactly once.
     #[test]
     fn the_footfall_gate_edge_and_nan_both_pass() {
         let at = |d: f32| Vec3::new(d, 0.0, 0.0);
@@ -407,15 +288,8 @@ mod tests {
         );
     }
 
-    /// **Rounding once is not cosmetic** — this pair flips the branch.
-    ///
-    /// Two points 50 yd apart out at the map's edge, where the coordinates are large enough that
-    /// f32 differences and squares stop being exact. Rounding six times (each difference, each
-    /// square, each partial sum — what a plain f32 `distance_squared` does) lands on **exactly**
-    /// `2500.0`, which the strict compare *keeps*; the reference's single rounding lands one ulp
-    /// above, which it *culls*. Same two points, opposite answers, and ours has to be the second.
-    ///
-    /// The literals are the shortest decimals that round-trip to the intended f32s.
+    /// Two points 50 yd apart at the map's edge: six f32 roundings land exactly on 2500, one
+    /// lands an ulp above. The literals round-trip to the intended f32s.
     #[test]
     fn a_six_rounding_kernel_lands_on_the_wrong_side_of_the_branch() {
         let a = Vec3::new(-6157.2476, 16978.16, -14441.062);
@@ -438,9 +312,7 @@ mod tests {
         );
     }
 
-    /// The two channels are disjoint (decision 1080): `$FSD` is the whole sound channel, the
-    /// per-foot side tags the whole visual one. HumanMale's Walk keys one of each family per
-    /// footfall — routing both to sound is exactly the doubled step rate.
+    /// The channels are disjoint: HumanMale's Walk keys one tag of each per footfall.
     #[test]
     fn the_sound_channel_is_fsd_alone() {
         assert!(is_footstep_sound(b"$FSD"));
@@ -453,7 +325,6 @@ mod tests {
         assert_eq!(footfall_side(b"$FSD"), None);
     }
 
-    /// The side letter a per-foot tag names; every other tag is `None`.
     #[test]
     fn footfall_side_reads_the_side_letter() {
         assert_eq!(footfall_side(b"$FL0"), Some(b'L'));
@@ -478,11 +349,6 @@ mod tests {
         )
     }
 
-    /// **The arm frame scans nothing, and the frame after it opens the clip's head.** The
-    /// reference's arm (`0x7121a0`) stamps the block's window start at `now`, so the walker's
-    /// `prev == cur` abandons the block that frame (`0x719518`); the next frame's window opens at
-    /// that stamp — local `t = 0`, lower-inclusive — which is what makes an emote's `t = 0.000`
-    /// `$CSD` real without making it fire a frame early.
     #[test]
     fn an_arm_frame_is_silent_and_the_next_frame_opens_the_head() {
         let (mut last, unit, shuffle, _) = track();
@@ -503,10 +369,7 @@ mod tests {
         );
     }
 
-    /// **A clip armed and abandoned inside one frame fires nothing** — the report this rule was
-    /// written for (decision 1273). A stuttering mouse-turn flickers the gait Shuffle↔Stand at
-    /// input cadence, and HumanMale's ShuffleLeft keys `$SL0`+`$SR0` at `t = 0.000`: firing on the
-    /// arm frame laid a footprint pair per flicker, where the reference lays none.
+    /// Shuffle and Stand alternating every frame, as under a stuttering mouse-turn.
     #[test]
     fn a_clip_armed_for_one_frame_never_fires() {
         let (mut last, unit, shuffle, stand) = track();
@@ -516,9 +379,7 @@ mod tests {
         }
     }
 
-    /// An arm that *starts* deep in its timeline — the corpse settle's `seek_to(duration)` —
-    /// opens at its own stamp, never at the head: a body that streamed in dead must not replay
-    /// the collapse's `$DTH` keys.
+    /// The corpse settle's `seek_to(duration)`: a body streamed in dead replays no collapse keys.
     #[test]
     fn an_arm_deep_in_the_timeline_never_opens_the_head() {
         let (mut last, unit, death, _) = track();
@@ -530,11 +391,7 @@ 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** (the walker
-    /// `0x719370`) — so a held turn lays a print pair twice a
-    /// second in the real client too.
+    /// A held turn lays a print pair on every 0.5 s wrap, as the reference's walker does.
     #[test]
     fn a_loop_wrap_refires_the_head_keys() {
         let clip = shuffle_clip();
@@ -550,8 +407,7 @@ mod tests {
         );
     }
 
-    /// HumanMale ShuffleLeft's real shape (`benilla-extract m2events`): 0.500 s, looping, keys
-    /// `$SL0` and `$SR0` both at 0.000.
+    /// HumanMale ShuffleLeft (`benilla-extract m2events`): 0.5 s, looping, `$SL0` and `$SR0` at 0.
     fn shuffle_clip() -> AnimClip {
         AnimClip {
             anim_id: 11,
@@ -604,8 +460,7 @@ mod tests {
             .run_system_once(
                 |win: bevy::prelude::Res<Window>, mut out: MessageWriter<_>| {
                     let unit = Entity::from_raw_u32(1).expect("valid entity id");
-                    // Identity placement, no rig: the fired point is the key's own model-space
-                    // one, which is what this test's zero-offset keys make `Vec3::ZERO`.
+                    // Identity placement, no rig: the fired point is the key's own, zero here.
                     let world = GlobalTransform::IDENTITY;
                     let frame = EventFrame {
                         world: &world,
@@ -619,14 +474,6 @@ mod tests {
         msgs.drain().map(|m| m.ident).collect()
     }
 
-    /// **A rig-less model's event point is the placement times the key's own model-space point** —
-    /// and that is not an approximation of the kernel's `placementMatrix · (boneMatrix[bone] ·
-    /// position)`: with no keys every bone matrix composes to the identity, so the two are equal.
-    ///
-    /// This is the whole placed-doodad population, where the offsets are largest (149 of 244
-    /// shipped `$DSL` records sit off their origin, out to 67.6 yd) and **none** rides a bone any
-    /// sequence keys. A model *placed* somewhere and *scaled* must carry its marker with it, which
-    /// is what the transform below checks and what a bare `translation()` read could not do.
     #[test]
     fn a_rigless_models_key_fires_at_its_placed_and_scaled_point() {
         use bevy::ecs::system::RunSystemOnce;
@@ -637,7 +484,7 @@ mod tests {
             ident: *b"$DSL",
             data: 1,
             bone: 3,
-            offset: Vec3::new(1.0, 2.0, 3.0), // ignored on this leg — there is no rig to compose
+            offset: Vec3::new(1.0, 2.0, 3.0), // ignored: there is no rig to compose
             point: Vec3::new(10.0, 0.0, 0.0),
         }]
         .into();
diff --git a/crates/benilla-app/src/creature_anim/gesture.rs b/crates/benilla-app/src/creature_anim/gesture.rs
index a417f4fa..b14979b9 100644
--- a/crates/benilla-app/src/creature_anim/gesture.rs
+++ b/crates/benilla-app/src/creature_anim/gesture.rs
@@ -1,16 +1,7 @@
-//! The **client-local gesture** — the second producer of a one-shot emote, and the one benilla was
-//! missing (bug B157, decision 1469).
-//!
-//! Nothing on the wire announces it. The real client's chat *display* path picks a gesture code from
-//! the message itself and calls `0x60bb30(unit, code)`; that resolves the code through a five-slot
-//! table of `Emotes.dbc` rows and hands the emote id to `0x5fcd20` — the **same** function
-//! `SMSG_EMOTE`'s handler calls, and the only one in the whole client that turns an `Emotes.dbc` id
-//! into a played animation. So the gesture is not a new animation path: it is a new *producer* for
-//! the one benilla already has ([`super::EmoteAnim`]). A client that only reacts to `SMSG_EMOTE`
-//! plays nothing at all, which is exactly what was reported.
-//!
-//! 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.
+//! The client-local gesture, which no packet announces: the chat display path picks a code from
+//! the message and calls `0x60bb30(unit, code)`, which resolves it through five `Emotes.dbc` flag
+//! slots and plays it through `0x5fcd20`, the player `SMSG_EMOTE` uses. Its other caller is the
+//! NPC-interact path, always with code 0 (talk), so [`crate::target::click`] pushes through here.
 
 use bevy::prelude::*;
 
@@ -18,27 +9,25 @@ use crate::net::GuidIndex;
 
 use super::{EmoteAnim, PlaySeq};
 
-/// A gesture code — an index into `Emotes.dbc`'s five hard-coded `EmoteFlags` slots
-/// (`benilla_formats::emotes::GESTURE_FLAG_BITS`), which is literally the integer the client's
-/// `0x60bb30` takes. **The ids and AnimIDs behind these are content, not code**: the client scans
-/// the DBC for the flag bit, and so do we ([`benilla_formats::EmoteSoundCatalog::gesture`]).
+/// A gesture code, the integer `0x60bb30` takes: one of five `EmoteFlags` bits, resolved by
+/// scanning `Emotes.dbc` for it ([`benilla_formats::EmoteSoundCatalog::gesture`]).
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum Gesture {
-    /// `EmoteFlags 0x08` — a plain say, and every NPC interaction.
+    /// `EmoteFlags 0x08`: a plain say, and every NPC interaction.
     Talk,
-    /// `EmoteFlags 0x10` — a say whose last byte is `?`.
+    /// `EmoteFlags 0x10`: a say whose last byte is `?`.
     Question,
-    /// `EmoteFlags 0x20` — a say whose last byte is `!`.
+    /// `EmoteFlags 0x20`: a say whose last byte is `!`.
     Exclamation,
-    /// `EmoteFlags 0x40` — any yell, whatever its text.
+    /// `EmoteFlags 0x40`: any yell, whatever its text.
     Shout,
-    /// `EmoteFlags 0x100` — a message that IS one of the `LAUGH_WORDn` globals, whole and
+    /// `EmoteFlags 0x100`: a message that is one of the `LAUGH_WORDn` globals, whole and
     /// case-insensitively.
     Laugh,
 }
 
 impl Gesture {
-    /// The slot index — the client's `code`.
+    /// The client's `code`.
     pub(crate) fn slot(self) -> usize {
         match self {
             Self::Talk => 0,
@@ -50,17 +39,13 @@ impl Gesture {
     }
 }
 
-/// Gestures asked for this frame and not yet played: `(speaker guid, code)`. Filled by the chat
-/// display path and the interact click — the client's two callers of `0x60bb30` — and drained by
-/// [`drive_gestures`]. A queue rather than a direct write because the producers sit in the UI lane
-/// and the consumer needs the world's object index; the chat bubble is queued the same way and for
-/// the same reason.
+/// Gestures asked for and not yet played, `(speaker guid, code)`, from the chat display path and
+/// the interact click, the two callers of `0x60bb30`.
 #[derive(Resource, Default)]
 pub(crate) struct GestureQueue(Vec<(u64, Gesture)>);
 
 impl GestureQueue {
-    /// Ask for `gesture` on the unit with `guid`. A zero guid (a system line, a channel notice) has
-    /// no speaker and is dropped here rather than failing the lookup later.
+    /// A zero guid (a system line, a channel notice) has no speaker and is dropped.
     pub(crate) fn push(&mut self, guid: u64, gesture: Gesture) {
         if guid != 0 {
             self.0.push((guid, gesture));
@@ -68,25 +53,12 @@ impl GestureQueue {
     }
 }
 
-/// Pick the gesture a chat line plays, from the **raw wire chat type** and the message text — the
-/// client's selector at `0x49d7d0`–`0x49d8ae`, in its exact order.
-///
-/// 1. Only `SAY`, `YELL` and `PARTY` are eligible at all. Note this is the *wire* type, so
-///    `MONSTER_SAY`/`MONSTER_YELL` — what a creature's ambient barks arrive as — are **not**
-///    eligible: a shouting vendor does not gesture.
-/// 2. The message is compared **whole and case-insensitively** against `LAUGH_WORD1`, `2`, …,
-///    stopping at the first global that is missing or empty. A match is [`Gesture::Laugh`] — and
-///    this is the one branch `PARTY` can reach, so a party line that IS a laugh word laughs, while `/p hello!` does nothing.
-/// 3. Otherwise `PARTY` stops here.
-/// 4. `YELL` is always [`Gesture::Shout`] — its text is never inspected, so a yell ending in `!`
-///    still shouts rather than exclaiming.
-/// 5. `SAY` looks at the **last byte only** — `?` → [`Gesture::Question`], `!` →
-///    [`Gesture::Exclamation`], anything else (including an empty message) → [`Gesture::Talk`].
-///    Not "ends with `!!`", not a punctuation count, no trailing-whitespace trim.
-///
-/// `laugh_word(n)` returns the `LAUGH_WORDn` global — `None` ends the list. It is a callback so the
-/// words come off the player's own FrameXML at call time, which is where they belong: the
-/// *enumeration* is the mechanism, the word list is content.
+/// The gesture a chat line plays, by wire chat type and text (`0x49d7d0` to `0x49d8ae`). Only
+/// `SAY`, `YELL` and `PARTY` gesture, never a creature's `MONSTER_SAY`/`MONSTER_YELL`. A text
+/// equal, case-insensitively, to a `LAUGH_WORDn` global laughs (the scan stops at the first
+/// missing or empty one); otherwise `PARTY` does nothing, `YELL` shouts whatever its text, and
+/// `SAY` reads its last byte only: `?` asks, `!` exclaims, anything else talks. `laugh_word(n)`
+/// reads the global off the player's own FrameXML; `None` ends the list.
 pub(crate) fn select_gesture(
     chat_type: u8,
     text: &str,
@@ -118,9 +90,7 @@ pub(crate) fn select_gesture(
     }
 }
 
-/// Drain [`GestureQueue`] into the one-shot player: resolve the speaker, resolve the code to an
-/// `Emotes.dbc` id through the DBC's own flag-bit scan, gate, and write [`EmoteAnim`] — the client's
-/// `0x60bb30` and its tail-call into the shared `0x5fcd20`.
+/// Drain [`GestureQueue`]: the client's `0x60bb30` and its tail call into `0x5fcd20`.
 pub(super) fn drive_gestures(
     mut queue: ResMut<GestureQueue>,
     mut out: MessageWriter<EmoteAnim>,
@@ -133,10 +103,9 @@ pub(super) fn drive_gestures(
     let Some(emotes) = emotes else { return };
     for (guid, gesture) in asked {
         let Some(&entity) = index.0.get(&guid) else {
-            continue; // the speaker is not streamed to us — nothing to animate
+            continue; // the speaker is not streamed
         };
-        // The slot may be empty if a patch ever ships without a row carrying the bit; the client
-        // bails the same way (`0x60bb43`).
+        // A slot no row carries: the client bails too (`0x60bb43`).
         let Some(emote_id) = emotes.gesture(gesture.slot()) else {
             continue;
         };
@@ -162,10 +131,7 @@ mod tests {
     use super::*;
     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 (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.
+    /// Invented words: the shipped `LAUGH_WORDn` are install content, which never enters the repo.
     fn words(n: u32) -> Option<String> {
         ["snrk", "guffaw", "tehe"]
             .get(n as usize - 1)
@@ -175,8 +141,6 @@ mod tests {
         None
     }
 
-    /// The reporter's own message: `fdfdf!!` said aloud is an EXCLAMATION, because only the last
-    /// byte is read. This is the case the screenshot shows.
     #[test]
     fn the_last_byte_alone_picks_the_say_gesture() {
         let say = |t: &str| select_gesture(m::CHAT_MSG_SAY, t, no_words);
@@ -192,7 +156,6 @@ mod tests {
         assert_eq!(say(""), Some(Gesture::Talk), "an empty say still talks");
     }
 
-    /// A yell never reads its text — punctuation and all.
     #[test]
     fn a_yell_always_shouts() {
         assert_eq!(
@@ -205,8 +168,6 @@ mod tests {
         );
     }
 
-    /// The laugh scan is whole-string and case-insensitive, and it runs BEFORE the say/yell split —
-    /// so it is the only gesture a party line can reach, and it beats a yell's shout.
     #[test]
     fn the_laugh_scan_is_whole_string_and_outranks_the_rest() {
         assert_eq!(
@@ -236,7 +197,6 @@ mod tests {
         );
     }
 
-    /// The list ends at the first missing OR empty global, so a hole hides everything after it.
     #[test]
     fn an_empty_global_ends_the_laugh_list() {
         let holed = |n: u32| match n {
@@ -256,8 +216,7 @@ mod tests {
         );
     }
 
-    /// Everything else on the wire is ineligible — including a creature's ambient bark, which
-    /// arrives as MONSTER_SAY/MONSTER_YELL, not SAY/YELL.
+    /// A creature's bark arrives as `MONSTER_SAY`/`MONSTER_YELL`, not `SAY`/`YELL`.
     #[test]
     fn only_say_yell_and_party_are_eligible() {
         for ty in [
@@ -277,12 +236,7 @@ mod tests {
         }
     }
 
-    /// Drive the real system over the real `Emotes.dbc`: a queued gesture on a streamed unit must
-    /// come out as an [`EmoteAnim`] carrying the shipped AnimID — and a unit **in combat** must come
-    /// out with nothing (the shared player's gate).
-    ///
-    /// This is the test that catches the mechanism being built and never firing: it exercises the
-    /// queue, the guid resolve, the DBC scan and the gate, not just the selector.
+    /// The real system over the real `Emotes.dbc`; a unit in combat plays nothing.
     #[test]
     fn a_queued_gesture_reaches_the_one_shot_player() {
         use crate::net::{GuidIndex, ObjectStore};
@@ -300,7 +254,7 @@ mod tests {
             .add_message::<EmoteAnim>()
             .add_systems(Update, drive_gestures);
 
-        // A plain streamed unit, and a second one flagged IN_COMBAT (UNIT_FIELD_FLAGS = field 46).
+        // A plain unit and one flagged in combat (`UNIT_FIELD_FLAGS` is field 46).
         let speaker = app.world_mut().spawn(ObjectStore::default()).id();
         let fighter = app
             .world_mut()
@@ -317,7 +271,7 @@ mod tests {
         app.world_mut()
             .resource_mut::<GestureQueue>()
             .push(22, Gesture::Talk);
-        // A speaker we have never streamed must not panic or produce anything.
+        // A speaker never streamed produces nothing.
         app.world_mut()
             .resource_mut::<GestureQueue>()
             .push(999, Gesture::Talk);
@@ -340,7 +294,6 @@ mod tests {
         );
     }
 
-    /// A zero guid has no speaker and never reaches the lookup.
     #[test]
     fn a_speakerless_line_is_dropped_at_the_queue() {
         let mut q = GestureQueue::default();
diff --git a/crates/benilla-app/src/creature_anim/impact.rs b/crates/benilla-app/src/creature_anim/impact.rs
index a8612080..93524271 100644
--- a/crates/benilla-app/src/creature_anim/impact.rs
+++ b/crates/benilla-app/src/creature_anim/impact.rs
@@ -1,37 +1,12 @@
-//! 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
-//! sound column only), the event kernel fires `0x6247d0 → 0x624530(victim, attacker+0xd70)` — all
-//! four victim elements at the impact frame — and clears the record (fires once). **`$HIT` never
-//! reaches the dispatcher** — it is a CEffect-model tag that re-fires only the wound flinch, and
-//! it also rides hit-REACTION clips, so matching it would fire pending swings at wrong moments.
-//!
-//! Two more consequences ride the same event router (decision 0279):
-//!
-//! - **`$CPP` — the victim DEFENSE animation** (`0x624a01`): a defended outcome (dodge/parry/
-//!   block/deflect) plays a dedicated primary clip on the victim ([`DefenseAnim`]) and **clears
-//!   `HitInfo & 0x2` in the cached record** (`and [esi+0xd80],-3`), suppressing the wound
-//!   flinch + blood for that hit. The record itself survives `$CPP` — so `$CPP` before the
-//!   impact tag defends and then texts/sounds, while an impact tag first **consumes** the record
-//!   and a late `$CPP` finds nothing: the two are mutually exclusive per authored event order,
-//!   exactly the client's shape.
-//! - **The whiff slow-down** (`0x624ca0` → `0x712910(bone 0, 0.5f)`): a swing that contacted
-//!   nothing (victimState ∈ {0 miss, 2 dodge, 6 evade}) drops the attacker's own swing to HALF
-//!   speed for its remainder ([`SwingSlowdown`]) — a slowed follow-through, not a cut.
-//!
-//! The record law (byte-verified): **one slot per attacker, overwrite** — a second swing before
-//! the first impact supersede-flushes the old record as **floating text only** (blood/flinch/sound
-//! drop); `SMSG_ATTACKSTOP` (also how death/stun arrive) flushes the same way; a resolved attacker
-//! whose clip has **no** impact tag never fires the full set — the client drops, it does not fall
-//! back to a timer. The only receive-time victim dispatch is an attacker that doesn't resolve at
-//! all (`net/apply`'s direct [`SwingImpact`] write).
-//!
-//! benilla's twin: [`route_swing_impacts`] caches each [`SwingMessage`], consumes the first
-//! matching tag from the [`AnimSoundEvent`] stream, and emits [`SwingImpact`] — full on the tag,
-//! `text_only` on supersede/attack-stop. Consumers: blood + flinch + the contact sounds
-//! (`sound::combat`, decision 0529) skip `text_only`; the floating number takes all.
+//! The melee impact frame. At receive a resolved attacker caches the swing record
+//! (`attacker+0xd70`, one slot, overwritten) and plays its clip (`0x5fe2f0`); the victim's
+//! feedback fires once, when the clip crosses a `$AH0`-`$AH3` or `$CAH` key (`0x6247d0` →
+//! `0x624530`). `$HIT` is no impact key: it re-fires only the flinch and rides hit-reaction clips.
+//! `$CPP` (`0x624a01`) plays the victim's defense clip and clears `HitInfo & 0x2` in the record,
+//! so no flinch or blood, unless an impact key consumed the record first. A whiff plays the rest
+//! of the attacker's swing at half speed (`0x624ca0` → `0x712910(bone 0, 0.5)`). A superseding
+//! swing or `SMSG_ATTACKSTOP` flushes the old record as floating text only, a `text_only`
+//! [`SwingImpact`]. A clip with no impact key never fires: there is no timer fallback.
 
 use bevy::prelude::*;
 
@@ -39,89 +14,59 @@ use super::events::AnimSoundEvent;
 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`).
-///
-/// `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
-/// `0x624566` sits after the gate). A corpse you can loot takes no visible hits: swinging at it
-/// shows nothing at all.
-///
-/// **It does NOT cover the flushes, and that asymmetry is the whole reason this is a function
-/// rather than one `if` at the top.** An image-wide census of the floating-number emitter
-/// `0x6243e0` finds exactly three call sites — `0x624566` *inside* the gated dispatcher, plus
-/// `0x624ea7` (`SMSG_ATTACKSTOP`, `0x624e40`) and `0x625893` (the `0x14a` supersede arm) which
-/// call it **directly**, bypassing `0x624530` and its gate. So a superseded or attack-stopped
-/// record still floats its number over a lootable victim. Our single [`SwingImpact`] message
-/// carries both occasions, so gating it uniformly — the obvious implementation — would be wrong
-/// on the flush: only a **full** dispatch (`text_only == false`) is suppressed.
-///
-/// Nor does it cover the whiff slow-down: `0x624ca0` is its own function past the dispatcher's
-/// `0x624694` end, reached from the impact router, so a swing that whiffs a lootable corpse still
-/// drops to half speed.
+/// The victim dispatcher's lootable gate (`0x624552`, `UNIT_DYNAMIC_FLAGS` bit `0x1`): `0x624530`
+/// bails before every consequence it owns, the floating number (`0x624566`) included, so a corpse
+/// you can loot shows no hits. The supersede and attack-stop flushes call the number emitter
+/// `0x6243e0` directly (`0x625893`, `0x624ea7`) and the whiff slow-down (`0x624ca0`) is outside
+/// the dispatcher, so only a full dispatch is gated.
 pub(crate) fn lootable_victim(stores: &Query<&ObjectStore>, victim: Option<Entity>) -> bool {
     victim.is_some_and(|v| stores.get(v).is_ok_and(|s| s.0.unit_lootable()))
 }
 
-/// A melee swing's **impact moment** — the victim-feedback trigger, re-emitted from
-/// [`route_swing_impacts`] at the swing clip's attack-hit keyframe (or a flush).
+/// A melee swing's impact moment, at the clip's attack-hit key or a flush.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct SwingImpact {
     pub(crate) swing: SwingMessage,
-    /// A supersede/attack-stop flush (`0x624e40` / the 0x14a overwrite): the client fires ONLY
-    /// the floating text for the displaced record — blood, flinch, and impact sounds drop.
+    /// A supersede or attack-stop flush (`0x624e40`, the `0x14a` overwrite): floating text only.
     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`, decision
-    /// 0525). `None` for `$CAH` (character attack-hit), the receive-time unresolved-attacker
-    /// fallback, and flushes.
+    /// The `$AH0`-`$AH3` digit: picks the attacker's `CreatureSoundData.CustomAttack` column and
+    /// latches `SWINGNOHITSOUND` in place of the weapon-impact sound (`0x6247d0`). `None` for
+    /// `$CAH`, the receive-time 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`. `None` for a flush and for
-    /// the receive-time fallback, where no tag fired at all and the reference has only the unit.
+    /// The firing tag's world point, which the reference carries from `0x624862` into both
+    /// weapon-sound legs (`0x6248ef`, `0x624950`); `None` when no tag fired.
     pub(crate) pos: Option<Vec3>,
 }
 
-/// A flush signal for an attacker's pending swing record — `SMSG_ATTACKSTOP`'s `0x624e40`
-/// (death and stun arrive as the same packet). Written by `net/apply`; text-only flush + clear.
+/// `SMSG_ATTACKSTOP`'s flush of a pending record (`0x624e40`); death and stun arrive as it.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct SwingFlush(pub(crate) Entity);
 
-/// The victim plays its defense reaction (decision 0279 — the `$CPP` dispatch `0x624a01`):
-/// dodge/deflect → Dodge, block → ShieldBlock, parry → by the victim's own weapon
-/// ([`super::select::defense_anim`] resolves in the driver, which holds the victim's `Wielded`
-/// and death state — the client gates on alive there too).
+/// The victim's defense clip (`$CPP`, `0x624a01`), resolved in the driver by
+/// [`super::select::defense_anim`], which requires the victim alive, as the client does.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct DefenseAnim {
     pub(crate) victim: Entity,
     pub(crate) victim_state: u32,
 }
 
-/// The attacker's in-flight swing drops to half speed for its remainder (decision 0279 — the
-/// whiff slow-down `0x712910`, fired at the impact tag when victimState ∈ {0, 2, 6}).
+/// The whiff slow-down: the attacker's swing runs at half speed for its remainder (`0x712910`).
 #[derive(Message, Clone, Copy)]
 pub(crate) struct SwingSlowdown(pub(crate) Entity);
 
-/// A cached swing awaiting its clip's event keyframes (the client's `attacker+0xd70` slot):
-/// `defended` latches the one `$CPP` dispatch (the shipped clips author it once; a variation
-/// wrap must not re-defend the same record).
+/// A swing awaiting its clip's keys (`attacker+0xd70`); `defended` latches the one `$CPP`, so a
+/// variation wrap cannot defend it twice.
 pub(crate) struct PendingSwing {
     pub(crate) swing: SwingMessage,
     defended: bool,
 }
 
-/// Pending swing records keyed by attacker (the client's `attacker+0xd70` cache, one slot each):
-/// the swing waiting for its clip's impact keyframe.
+/// Pending swing records, one per attacker (`attacker+0xd70`).
 #[derive(Resource, Default)]
 pub(crate) struct PendingImpacts(pub(crate) bevy::ecs::entity::EntityHashMap<PendingSwing>);
 
-/// An attack-hit tag (`0x6247d0`'s matching set, byte-verified): `$AH0`–`$AH3` (the digit selects
-/// the attacker's natural-weapon sound column — [`SwingImpact::natural`]) or `$CAH` (the
-/// character-model attack-hit — every shipped character attack clip authors it; asset-verified
-/// on HumanMale, co-authored with the inert `$HIT` at the same timestamp). NOT `$HIT`.
-/// Outer `Some` = "fires the dispatch"; the inner value is [`SwingImpact::natural`].
+/// `0x6247d0`'s attack-hit tags: `$AH0`-`$AH3`, or `$CAH`, which every character attack clip
+/// authors beside an inert `$HIT`; never `$HIT`. The inner value is [`SwingImpact::natural`].
 fn impact_tag(ident: &[u8; 4]) -> Option<Option<u8>> {
     match ident {
         b"$AH0" => Some(Some(0)),
@@ -133,15 +78,13 @@ fn impact_tag(ident: &[u8; 4]) -> Option<Option<u8>> {
     }
 }
 
-/// The whiff gate `0x624ca0`: the outcomes where the swing contacted nothing — miss, dodge,
-/// evade. Parry/block still contact (steel meets steel/shield), so they never slow the swing.
+/// The whiff gate `0x624ca0`: miss, dodge or evade; a parry or block still makes contact.
 fn is_whiff(victim_state: u32) -> bool {
     matches!(victim_state, 0 | 2 | 6)
 }
 
-/// Cache swings, consume impact tags, dispatch `$CPP` defenses, flush on supersede/attack-stop,
-/// silently drop records whose attacker despawned (the client's dtor clears without flushing).
-/// Ordered after [`super::events::fire_anim_events`] so a tag fires the same frame it's crossed.
+/// Cache swings, fire them on their impact keys and flush them. Runs after
+/// [`super::events::fire_anim_events`] so a key fires the frame it is crossed.
 pub(super) fn route_swing_impacts(
     mut swings: MessageReader<SwingMessage>,
     mut events: MessageReader<AnimSoundEvent>,
@@ -154,8 +97,7 @@ pub(super) fn route_swing_impacts(
     mut slows: MessageWriter<SwingSlowdown>,
 ) {
     for s in swings.read() {
-        // One slot per attacker, overwrite: the superseded record flushes TEXT ONLY (the client's
-        // 0x14a supersede-flush fires 0x6243e0 alone; the old swing's blood/flinch/sound drop).
+        // One slot per attacker: a superseded record flushes as text only (`0x6243e0` alone).
         if let Some(old) = pending.0.insert(
             s.attacker,
             PendingSwing {
@@ -176,14 +118,13 @@ pub(super) fn route_swing_impacts(
                 swing: old.swing,
                 text_only: true,
                 natural: None,
-                pos: None, // a flush: no tag fired, so there is no point to carry
+                pos: None,
             });
         }
     }
     for ev in events.read() {
         if let Some(natural) = impact_tag(&ev.ident) {
-            // Fires once: the tag consumes the record (`0x6247d0` clears the GUIDs after
-            // dispatch) — a `$CPP` authored after this frame finds nothing (mutual exclusion).
+            // The key consumes the record (`0x6247d0` clears it after the dispatch).
             if let Some(p) = pending.0.remove(&ev.entity) {
                 if benilla_assets::trace::enabled() {
                     benilla_assets::trace::line(
@@ -197,15 +138,11 @@ pub(super) fn route_swing_impacts(
                     );
                 }
                 if is_whiff(p.swing.victim_state) {
-                    // The whiff slow-down rides the same crossing (`0x624ca0` gate) — and it is
-                    // NOT behind the LOOTABLE gate below: its function sits past the victim
-                    // dispatcher's end, so a swing that whiffs a lootable corpse still slows.
+                    // Not behind the lootable gate: the slow-down is outside the dispatcher.
                     slows.write(SwingSlowdown(ev.entity));
                 }
-                // The victim dispatcher's front gate ([`lootable_victim`]): a lootable victim
-                // takes no feedback at all — no blood, no flinch, no impact sound, not even the
-                // number. The record is still consumed above, exactly as the reference's
-                // `0x6247d0` clears the GUIDs before it calls the dispatcher at all.
+                // A lootable victim takes nothing, not even the number; the record is consumed
+                // all the same, as `0x6247d0` clears it whatever the dispatcher does.
                 if lootable_victim(&stores, p.swing.victim) {
                     continue;
                 }
@@ -226,8 +163,7 @@ pub(super) fn route_swing_impacts(
                 );
             }
         } else if &ev.ident == b"$CPP" {
-            // The victim defense dispatch: mutates the cached record (clears the flinch bit),
-            // never consumes it — the impact tag still texts/sounds afterwards.
+            // The defense edits the cached record and never consumes it.
             if let Some(p) = pending.0.get_mut(&ev.entity) {
                 if !p.defended {
                     p.defended = true;
@@ -246,7 +182,7 @@ pub(super) fn route_swing_impacts(
         }
     }
     for SwingFlush(attacker) in flushes.read() {
-        // SMSG_ATTACKSTOP → 0x624e40: text-only flush + clear (death/stun arrive as this packet).
+        // `0x624e40`: flush as text only and clear.
         if let Some(p) = pending.0.remove(attacker) {
             if benilla_assets::trace::enabled() {
                 benilla_assets::trace::line(
@@ -262,9 +198,7 @@ pub(super) fn route_swing_impacts(
             });
         }
     }
-    // A record whose attacker despawned mid-swing drops silently (the client's unit dtor clears
-    // the cache without flushing). A resolved-but-untagged clip's record likewise just sits until
-    // superseded or stopped — the client has NO timer fallback.
+    // A despawned attacker's record drops without a flush, as the client's destructor clears it.
     if !pending.0.is_empty() {
         pending.0.retain(|e, _| entities.contains(*e));
     }
@@ -322,8 +256,8 @@ mod tests {
         app.update();
     }
 
-    /// Read the impacts emitted since the last call — one persistent cursor per test (a fresh
-    /// cursor would re-read the double buffer's previous frame).
+    /// The impacts since the last call; one cursor per test, as a fresh one would re-read the
+    /// previous frame.
     #[allow(clippy::type_complexity)]
     fn drain(
         app: &mut App,
@@ -353,7 +287,7 @@ mod tests {
         cursor.read(msgs).count()
     }
 
-    /// `UNIT_DYNAMIC_FLAGS`, absolute UpdateField index — bit `0x1` is LOOTABLE.
+    /// `UNIT_DYNAMIC_FLAGS`'s UpdateField index; bit `0x1` is LOOTABLE.
     const FIELD_DYNAMIC_FLAGS: u16 = 143;
 
     /// Give `entity` a store carrying `flags` in `UNIT_DYNAMIC_FLAGS`.
@@ -368,10 +302,7 @@ mod tests {
             ));
     }
 
-    /// **The LOOTABLE front gate** (`0x624552`): a victim you can loot takes no visible hit at
-    /// all — the dispatcher `0x624530` bails past blood, flinch, sounds AND the floating number.
-    /// The tag still consumes the record, exactly as `0x6247d0` clears the GUIDs before calling
-    /// the dispatcher.
+    /// The lootable gate (`0x624552`) drops the whole dispatch; the tag still consumes the record.
     #[test]
     fn a_lootable_victim_takes_no_full_dispatch() {
         let mut app = app();
@@ -397,13 +328,11 @@ mod tests {
         );
     }
 
-    /// The control the gate would be meaningless without: clear the bit and the same swing
-    /// dispatches in full.
     #[test]
     fn a_non_lootable_victim_still_takes_the_full_dispatch() {
         let mut app = app();
         let (attacker, victim) = (unit(&mut app), unit(&mut app));
-        dynamic_flags(&mut app, victim, 0x20); // dead-looking, NOT lootable
+        dynamic_flags(&mut app, victim, 0x20); // dead-looking, not lootable
         let mut cursor = MessageCursor::<SwingImpact>::default();
         app.world_mut()
             .write_message(swing(attacker, Some(victim), 1));
@@ -414,11 +343,7 @@ mod tests {
         assert_eq!(drain(&mut app, &mut cursor), vec![(0x2, 1, false, None)]);
     }
 
-    /// **The asymmetry that makes this a per-occasion gate.** The floating-number emitter
-    /// `0x6243e0` has exactly three call sites: one INSIDE the gated dispatcher (`0x624566`) and
-    /// two that call it directly — `0x624ea7` (`SMSG_ATTACKSTOP`) and `0x625893` (the `0x14a`
-    /// supersede arm). So a superseded record still floats its number over a lootable victim, and
-    /// suppressing our one message uniformly would be wrong.
+    /// The flushes call the number emitter `0x6243e0` directly (`0x624ea7`, `0x625893`).
     #[test]
     fn a_lootable_victim_still_gets_the_supersede_and_stop_flushes() {
         let mut app = app();
@@ -426,7 +351,7 @@ mod tests {
         dynamic_flags(&mut app, victim, 0x1);
         let mut cursor = MessageCursor::<SwingImpact>::default();
 
-        // Two swings in a row: the second supersedes the first, which flushes text-only.
+        // The second swing supersedes the first, which flushes as text only.
         app.world_mut()
             .write_message(swing(attacker, Some(victim), 1));
         app.update();
@@ -440,14 +365,13 @@ mod tests {
             "the superseded record still texts, gate or no gate",
         );
 
-        // And SMSG_ATTACKSTOP flushes the survivor the same way.
+        // `SMSG_ATTACKSTOP` flushes the survivor the same way.
         app.world_mut().write_message(SwingFlush(attacker));
         app.update();
         assert_eq!(drain(&mut app, &mut cursor), vec![(0x2, 1, true, None)]);
     }
 
-    /// The whiff slow-down is NOT the dispatcher's: `0x624ca0` is its own function past
-    /// `0x624694`, so a swing that whiffs a lootable corpse still drops to half speed.
+    /// The whiff slow-down (`0x624ca0`) is not the dispatcher's, so the gate does not stop it.
     #[test]
     fn the_whiff_slowdown_survives_the_lootable_gate() {
         let mut app = app();
@@ -473,9 +397,7 @@ mod tests {
         );
     }
 
-    /// A swing waits for its tag; the first `$AH`/`$CAH` fires it FULL exactly once; `$HIT` and
-    /// `$CSS` never consume it (the byte-verified matching set — `$HIT` is flinch-only and rides
-    /// hit-REACTION clips too).
+    /// The first `$AH`/`$CAH` fires a swing in full, once; `$HIT` and `$CSS` never do.
     #[test]
     fn impact_fires_full_on_ah_or_cah_never_on_hit() {
         let mut app = app();
@@ -496,9 +418,7 @@ mod tests {
         assert!(drain(&mut app, &mut cursor).is_empty(), "fires once");
     }
 
-    /// `$CPP` before the impact tag: the defense fires once (latched), the cached record's
-    /// flinch bit is cleared, and the impact still texts — with `0x2` gone (decision 0279's
-    /// mutual exclusion, `$CPP`-first direction).
+    /// `$CPP` first: the defense fires once, the record loses `0x2`, and the impact still fires.
     #[test]
     fn cpp_defends_clears_flinch_then_impact_texts() {
         let mut app = app();
@@ -524,8 +444,6 @@ mod tests {
         );
     }
 
-    /// The impact tag first CONSUMES the record: a late `$CPP` finds nothing (the client's
-    /// event-order mutual exclusion, impact-first direction).
     #[test]
     fn impact_first_consumes_no_late_defense() {
         let mut app = app();
@@ -545,8 +463,6 @@ mod tests {
         );
     }
 
-    /// The whiff slow-down rides the impact crossing for miss/dodge/evade only — a landed hit
-    /// (or a parry/block, which still contact) never slows.
     #[test]
     fn whiff_slows_on_impact_tag() {
         let mut app = app();
@@ -563,8 +479,7 @@ mod tests {
         assert_eq!(drain_slows(&mut app, &mut s_cursor), 0, "a hit never slows");
     }
 
-    /// A second swing supersedes the first: the displaced record flushes TEXT ONLY; the new one
-    /// still waits for its own tag and fires full.
+    /// The superseding swing still waits for its own key and fires in full.
     #[test]
     fn superseded_swing_flushes_text_only() {
         let mut app = app();
@@ -579,8 +494,7 @@ mod tests {
         assert_eq!(drain(&mut app, &mut cursor), vec![(0x2, 5, false, Some(1))]);
     }
 
-    /// SMSG_ATTACKSTOP (death/stun arrive as it) flushes the pending record text-only; an
-    /// untagged record with no stop just sits (the client has no timer fallback).
+    /// An untagged record with no stop waits: there is no timer fallback.
     #[test]
     fn attack_stop_flushes_text_only() {
         let mut app = app();
diff --git a/crates/benilla-app/src/creature_anim/lod.rs b/crates/benilla-app/src/creature_anim/lod.rs
index 56d4cf2d..2c8be1bc 100644
--- a/crates/benilla-app/src/creature_anim/lod.rs
+++ b/crates/benilla-app/src/creature_anim/lod.rs
@@ -1,57 +1,15 @@
-//! The animation-LOD gate (decision 0448): park an off-frustum — or, since decision 0739,
-//! portal-invisible — rig's **per-bone pose evaluation**, keep **every clock** running. Since
-//! 0739 it governs the whole [`RigPose`] population — units, players, AND GameObject rigs (see
-//! the query's comment for why the old `With<AnimDriver>` filter left every animated GO
-//! sampling off-view).
+//! The animation-LOD gate: a rig off the frustum, or in a room the portal PVS does not reach,
+//! parks its pose evaluation ([`AnimParked`]) while its clocks run on; every [`RigPose`] is
+//! covered, GameObject rigs included. The reference elects every scene object each frame
+//! (`0x683dd0`): a pass-2 unit is neither drawn, animated nor event-ticked, except a
+//! `MORE_AUDIBLE` creature, re-linked for the tick (`0x607da0`). So a parked rig fires no event
+//! keys unless flagged, and wakes to the pose its absolute clock dictates (`0x714260` samples the
+//! world clock). Unlike the doodad gate ([`benilla_world::doodad_anim`]) this never stops the
+//! [`AnimationPlayer`], whose clock the driver and the event scan still use.
 //!
-//! 0448 shipped this as a modernization against a reference that "has NO view cull on unit
-//! 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
-//! departure; what still diverges is decision 1473's ledger — parked rigs keep DRAWING (the
-//! election never reached draw submission), and observable (ii) keeps every unit audible where
-//! the reference keeps only the flagged ones. The two observables preserved here:
-//!
-//! - **(i) the absolute-clock snap** — faithful (`0x714260` samples the world clock): a
-//!   re-appearing unit shows the pose "now" dictates. Nothing here pauses an [`AnimationPlayer`]:
-//!   Bevy's `advance_animations` keeps ticking every seek clock, so waking is just sampling
-//!   again — there is no frozen state to resume from.
-//! - **(ii) off-screen combat is audible for `MORE_AUDIBLE` creatures — and only them**
-//!   (decision 1482, the tick half of the election): a parked rig's event tracks are not
-//!   scanned ([`super::events::fire_anim_events`] skips it, memory and all), except when its
-//!   cached creature template carries the `0x20` flag — the reference's `0x607da0` re-link arm.
-//!   The driver state machine still arms clips for every parked rig (pose correctness on wake —
-//!   the memo design of 1370 item 9 is the only safe skip there), so a flagged creature's
-//!   `$CSS`/`$CAH`/`$HIT` (0075), `$BWP`/`$BWR`, and `$CSL` (0430) fire off-screen exactly as
-//!   the reference's do.
-//!
-//! The park mechanism is the [`AnimParked`] marker alone (decision 0712 — the evaluator took over
-//! from `animate_targets`, and the old per-joint `AnimatedBy` repoint died with the targets): the
-//! pose evaluator ([`super::pose`]) skips a parked rig, so its bone `Transform`s stop changing,
-//! which quiets transform propagation and `extract_skins`' changed-joint upload by change
-//! detection. The pose post-passes (body twist, global-sequence writes, billboard joint palette)
-//! gate on the same marker. Contrast the DOODAD gate ([`benilla_world::doodad_anim`]), which faithfully
-//! stops the player and re-arms on the shared clock — correct there (no one consumes a doodad's
-//! events off-screen), the exact 0075 trap here.
-//!
-//! **The room leg (decision 0739).** The frustum is the wrong instrument indoors: a dungeon
-//! camera's view cone passes through walls, so most of an instance's population stays "in
-//! frustum" while only the current room chain is drawable. The portal PVS
-//! ([`benilla_world::wmo_portal`], the faithful WMO group cull) already knows which rooms the camera can
-//! reach, and [`UnitWmoRoom`] already names each unit's room — so a unit whose room (and every
-//! room one portal hop from it) is outside this frame's PVS parks too. Soundness: a unit is
-//! room-parked exactly when the geometry *around* it — its room's walls, floor, furniture — is
-//! portal-culled by the same bits, and a body can poke only through a portal, never a wall, so
-//! the one-hop guard bounds the doorway straddle. Reveals carry no artifact by construction: a
-//! mob can only become visible through a portal, and the moment that portal's screen window is
-//! non-zero the flood marks its room visible (`compute_wmo_pvs` runs in `Update`, this gate in
-//! `PostUpdate` before the evaluator — same-frame wake, absolute-clock pose). Fail-open at every
-//! seam: no claim (outdoors, EXTERIOR groups), a despawned placement, a still-loading model, an
-//! out-of-range index — all read visible, the [`benilla_world::wmo_portal::WmoGroupVis::drawn_by`]
-//! convention.
-//! `WOW_NO_ROOM_LOD=1` disables just this leg (the A/B lever); `WOW_RIG_COST=1` prints the
-//! per-frame `[rig-gate]` counters.
+//! The room leg parks a rig whose WMO room ([`UnitWmoRoom`]) and every room one portal hop away
+//! are outside the PVS: a body pokes out of its room only through a portal. The PVS is built in
+//! `Update`, before this gate, so a reveal wakes the same frame; every lookup seam fails open.
 
 use bevy::app::AnimationSystems;
 use bevy::camera::primitives::{Frustum, Sphere as CullSphere};
@@ -70,26 +28,20 @@ use benilla_world::rig_anim::{AnimParked, RigPose};
 
 use crate::portrait::StageRig;
 
-/// Park only after the rig has been continuously out of frustum this long — a camera swing
-/// across the pack doesn't churn bone repoints. Waking is always instant.
+/// Time out of view before a rig parks, so a camera swing does not churn; waking is instant.
 const PARK_AFTER_SECS: f32 = 0.5;
 
-/// The frustum sphere: `SelectionRadius × root scale × RADIUS_SCALE + RADIUS_PAD`. The selection
-/// radius is the Stand-box *footprint* (tighter than the animated body) — the scale and pad buy
-/// the invariant that a rig with a pixel on screen always intersects, with margin for swing/
-/// attachment overhang and the one-frame frustum staleness. Model-less (cube) units take
-/// [`FALLBACK_RADIUS`]. Over-generous only costs a few more live rigs; under is the only failure.
+/// The frustum sphere, `SelectionRadius × root scale × RADIUS_SCALE + RADIUS_PAD`, keeps any rig
+/// with a pixel on screen inside, past swings, attachments and the one-frame-old frustum; a
+/// model-less unit takes [`FALLBACK_RADIUS`]. Too large only keeps more rigs live.
 const RADIUS_SCALE: f32 = 2.0;
 const RADIUS_PAD: f32 = 4.0;
 const FALLBACK_RADIUS: f32 = 6.0;
 
-/// Park/wake streamed rigs by the padded sphere-vs-frustum test (decision 0448) ANDed with the
-/// portal-PVS room test (decision 0739 — see the module doc's "room leg"). PostUpdate,
-/// before [`AnimationSystems`] — a wake drops the marker in time for the same frame's pose
-/// evaluation, so the re-appearing unit samples the absolute-clock pose with no stale
-/// frame. Exempt: the body we drive (the camera rides its attachment-17 pivot, and it must keep
-/// animating faded-out in first person) and its mount child. `WOW_NO_ANIM_LOD=1` disables
-/// parking — the live-probe A/B lever; `WOW_NO_ROOM_LOD=1` disables only the room leg.
+/// Park or wake each rig by its padded frustum sphere and its room, before [`AnimationSystems`] so
+/// a wake samples the same frame. The body we drive and its mount never park: the camera rides its
+/// attachment 17 and it animates faded out in first person. `WOW_NO_ANIM_LOD=1` never parks and
+/// `WOW_NO_ROOM_LOD=1` drops the room leg.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 pub(super) fn gate_rig_animation(
     time: Res<Time>,
@@ -104,24 +56,9 @@ pub(super) fn gate_rig_animation(
             Option<&MountBody>,
             Option<&UnitWmoRoom>,
         ),
-        // The whole collapsed-rig population (decision 0739), not `With<AnimDriver>`: GameObject
-        // rigs deliberately carry no driver (their looping player IS the animation — attach's GO
-        // arm), and gating on the driver left every animated GO sampling and refreshing off-view
-        // — at the LBRS pin, ~350 of the ~620 per-frame refreshes. Parking preserves their whole
-        // observable surface: the event scanner requires `AnimDriver` (GOs never fired anim
-        // events), `go_anim`'s state machine arms the player regardless of the marker, and the
-        // wake samples the absolute clock.
-        //
-        // `Without<DoodadAnimHost>` (decision 1365): placed doodads joined the collapsed lane,
-        // and their draw gate (`doodad_anim::gate_doodad_anim`) owns their `AnimParked` marker —
-        // it parks on the composed draw verdict + fade sphere, the doodad lane's own law, and
-        // two writers to one marker would fight every frame the two policies disagree.
-        //
-        // `Without<StageRig>` (decision 1447): booth rigs joined the collapsed lane too (1443),
-        // and a booth stage sits outside every world frustum by construction — unfiltered, this
-        // gate froze every pane and glue scene `PARK_AFTER_SECS` after its bake, a marker the
-        // booth camera gate (tracking only its own park edges) could not heal. Same one-writer
-        // law as the doodads': the booth gate owns a staged rig's marker.
+        // Every rig, driver or not: a GameObject rig's looping player is its whole animation.
+        // Doodads and booth stages are left out: their own gates own their `AnimParked`, and two
+        // writers to one marker would fight (a booth stage is outside every world frustum).
         (
             With<RigPose>,
             Without<benilla_world::doodad_anim::DoodadAnimHost>,
@@ -138,17 +75,12 @@ pub(super) fn gate_rig_animation(
     mut commands: Commands,
 ) {
     let disabled = *disabled.get_or_insert_with(|| std::env::var_os("WOW_NO_ANIM_LOD").is_some());
-    // The measurement twin of `WOW_NO_ANIM_LOD`: park EVERY streamed rig regardless of view. The
-    // two levers bracket the pose-evaluation lane's cost at any pin — "never park" is its ceiling,
-    // "always park" its floor — which is the only way to attribute a frame budget without a
-    // profiler build (the chrome-trace feature costs a 5-minute rebuild and a GB-scale file).
-    // Not a shipping mode: it freezes visible rigs on purpose.
+    // `WOW_ANIM_PARK_ALL` parks every rig, visible ones too: the pose lane's cost floor, as
+    // `WOW_NO_ANIM_LOD` is its ceiling. A measuring lever only.
     let park_all = *park_all.get_or_insert_with(|| std::env::var_os("WOW_ANIM_PARK_ALL").is_some());
     let no_room = *no_room.get_or_insert_with(|| std::env::var_os("WOW_NO_ROOM_LOD").is_some());
-    // `[rig-gate]` counters (`WOW_RIG_COST`): `room_out` is the room leg's *marginal* park set —
-    // rigs the frustum keeps that the PVS rejects — so a `WOW_NO_ROOM_LOD=1` leg reads the
-    // premise number without applying the leg (counted either way, applied only when the lever
-    // is off).
+    // The `[rig-gate]` counters (`WOW_RIG_COST`): `room_out` counts the rigs the frustum keeps and
+    // the PVS rejects, even under `WOW_NO_ROOM_LOD`.
     let cost_on = benilla_world::rig_palette::rig_cost_enabled();
     let (mut n_rigs, mut n_parked, mut room_out) = (0u32, 0u32, 0u32);
     let Ok(frustum) = cam.single() else {
@@ -203,11 +135,7 @@ pub(super) fn gate_rig_animation(
     out_since.retain(|e, _| rigs.contains(*e));
 }
 
-/// Register the gate: [`gate_rig_animation`] before the frame's pose evaluation.
-///
-/// The room predicate itself lives in [`benilla_world::wmo_portal::room_pvs_visible`] since 1475:
-/// the body draw election asks the identical question of the identical claim, and two private
-/// copies of one election term is exactly the drift 1473 catalogued.
+/// Register [`gate_rig_animation`] before the frame's pose evaluation.
 pub(super) fn plugin(app: &mut App) {
     app.add_systems(PostUpdate, gate_rig_animation.before(AnimationSystems));
 }
@@ -227,12 +155,11 @@ mod tests {
     use super::super::{events::fire_anim_events, AnimDriver, AnimSoundEvent};
     use super::*;
 
-    /// The test clip's loop length (seconds) — short so real-dt frames wrap it several times.
+    /// The test clip's loop length in seconds, short so real frames wrap it several times.
     const DUR: f32 = 0.4;
 
-    /// A one-joint rig whose looping clip translates the bone `0 → +X` over [`DUR`] and carries a
-    /// `$TST` event keyframe mid-loop: enough to observe all three gate laws — clocks, bones,
-    /// events. Returns `(root, joint)`.
+    /// A one-joint rig looping bone 0 from the origin to `+X` over [`DUR`], with a `$TST` key
+    /// mid-loop. Returns `(root, joint)`.
     fn spawn_rig(app: &mut App, at: Vec3) -> (Entity, Entity) {
         let mut pose = PoseSource {
             bone_masks: vec![0],
@@ -304,9 +231,7 @@ mod tests {
             first_seq: None,
             pose: std::sync::Arc::new(pose),
         };
-        // The driver's requested base = the gait slot: point it at the clip so the event
-        // scanner's `resolved_anim` finds the advancing timeline (its live writer is
-        // `drive_animations`, out of scope here).
+        // The gait slot points at the clip, so the event scanner finds its timeline.
         let driver = AnimDriver {
             gait: Some(0),
             ..Default::default()
@@ -322,7 +247,7 @@ mod tests {
                 driver,
             ))
             .id();
-        // The evaluator's pose buffer (0712 -> 0724); no joint entities at all.
+        // The evaluator's pose buffer; no joint entities.
         let skeleton = benilla_assets::ModelSkeleton {
             joints: vec![benilla_assets::ModelJoint {
                 parent: -1,
@@ -356,19 +281,16 @@ mod tests {
         ));
         app.init_asset::<WmoModel>();
         app.add_message::<AnimSoundEvent>();
-        // The event scanner's MORE_AUDIBLE read (decision 1482) — empty ⇒ every parked rig
-        // reads unflagged, the fail-closed default.
+        // Empty: every parked rig reads unflagged.
         app.init_resource::<crate::names::NameCache>();
-        // The live schedule's shape: the gate ahead of the frame's pose evaluation; the event
-        // scanner reading the advanced seek after it.
+        // The live order: the gate, the pose evaluation, then the event scan.
         app.add_systems(PostUpdate, gate_rig_animation.before(AnimationSystems));
         benilla_world::rig_anim::plugin(&mut app);
         app.add_systems(PostUpdate, fire_anim_events.after(AnimationSystems));
         app
     }
 
-    /// Step real time forward by ~`secs` across `steps` updates (Time under MinimalPlugins
-    /// advances by wall clock, the same basis the global-seq tests use).
+    /// Step about `secs` of wall-clock time across `steps` updates.
     fn advance(app: &mut App, secs: f32, steps: u32) {
         for _ in 0..steps {
             std::thread::sleep(std::time::Duration::from_secs_f32(secs / steps as f32));
@@ -391,12 +313,8 @@ mod tests {
             .translation
     }
 
-    /// 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 (`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.
+    /// An off-frustum rig parks with its bone frozen, its clock running and its keys silent, as
+    /// pass 2 never ticks an unflagged model (`0x683dd0`); woken, it matches a never-parked twin.
     #[test]
     fn parked_rig_keeps_its_clock_falls_silent_and_wakes_to_the_absolute_pose() {
         let mut app = app();
@@ -406,7 +324,7 @@ mod tests {
         let (twin, twin_joint) = spawn_rig(&mut app, -Vec3::Z * 20.0);
         app.update();
 
-        // Past the hysteresis window: parked, joints repointed.
+        // Past the hysteresis window: parked.
         advance(&mut app, PARK_AFTER_SECS + 0.2, 4);
         assert!(
             app.world().entity(behind).contains::<AnimParked>(),
@@ -416,7 +334,7 @@ mod tests {
             !app.world().entity(twin).contains::<AnimParked>(),
             "the in-frame twin stays live"
         );
-        // While parked: the bone holds, the clock runs — and the event track is not scanned.
+        // While parked the bone holds, the clock runs and the event track is not scanned.
         let frozen = bone(&app, behind_joint);
         let seek_at_park = seek(&app, behind);
         let mut cursor = app
@@ -425,7 +343,7 @@ mod tests {
             .get_cursor_current();
         let (mut fired_parked, mut fired_twin) = (0usize, 0usize);
         for _ in 0..6 {
-            // > one full loop in total, so the keyframe is crossed whatever the phase.
+            // More than one loop in total, so the key is crossed whatever the phase.
             std::thread::sleep(std::time::Duration::from_secs_f32(DUR * 0.3));
             app.update();
             let messages = app.world().resource::<Messages<AnimSoundEvent>>();
@@ -450,9 +368,8 @@ mod tests {
             "the parked rig's seek clock keeps advancing"
         );
 
-        // Wake: move the rig in front of the camera. The same frame, it samples the
-        // absolute-clock pose — seek and bone equal to the never-parked twin's (both players
-        // armed the same frame and tick the same delta).
+        // Wake in front of the camera: the same frame, seek and bone equal the twin's (both
+        // players were armed the same frame and tick the same deltas).
         app.world_mut()
             .entity_mut(behind)
             .insert(GlobalTransform::from_translation(-Vec3::Z * 20.0));
@@ -473,17 +390,15 @@ mod tests {
         );
     }
 
-    /// The exception the silence is built around (1482): a parked creature whose cached template
-    /// carries `MORE_AUDIBLE` (`0x20`) keeps firing — the reference's `0x607da0` pass-2 re-link,
-    /// the arm that keeps an off-screen flagged creature's combat audible.
+    /// A parked creature whose template carries `MORE_AUDIBLE` (`0x20`) keeps firing: the
+    /// reference's pass-2 re-link (`0x607da0`).
     #[test]
     fn a_more_audible_parked_rig_keeps_firing() {
         let mut app = app();
         spawn_camera(&mut app);
         let (behind, _) = spawn_rig(&mut app, Vec3::Z * 50.0);
-        // A streamed creature whose descriptor names an entry the cache answers with the flag
-        // set. The gate keys on `OBJECT_FIELD_ENTRY` (field 3), the way the reference keys its
-        // creature-query record (decision 2068) — not on the entry inside the guid.
+        // The gate keys on `OBJECT_FIELD_ENTRY` (field 3), as the reference keys its
+        // creature-query record, not on the guid's entry.
         const ENTRY: u32 = 69;
         app.world_mut()
             .entity_mut(behind)
@@ -532,10 +447,8 @@ mod tests {
         );
     }
 
-    /// The 1447 regression: a staged rig (a booth doll — off every world frustum by
-    /// construction) is never this gate's to park. Its `AnimParked` belongs to the booth camera
-    /// gate alone; the night the 1443 collapse put `RigPose` on booth roots, this gate froze
-    /// every paper doll and glue scene half a second after its bake.
+    /// A staged rig (a booth doll, outside every world frustum) is never this gate's to park: the
+    /// booth camera gate owns its `AnimParked`.
     #[test]
     fn a_stage_rig_is_never_world_parked() {
         let mut app = app();
@@ -552,8 +465,7 @@ mod tests {
         );
     }
 
-    /// A [`WmoGroupNav`] whose only meaningful fields are its portal-ref slice — the room-leg
-    /// tests never touch flags/bounds.
+    /// A [`WmoGroupNav`] with only its portal-ref slice set.
     fn nav(ref_start: u16, ref_count: u16) -> WmoGroupNav {
         WmoGroupNav {
             flags: 0,
@@ -575,14 +487,12 @@ mod tests {
         }
     }
 
-    /// The room leg end to end: an IN-FRUSTUM rig whose claimed room (and its one hop) is
-    /// outside the PVS parks past the hysteresis window; setting the room's bit wakes it and its
-    /// bones sample again — the same instant-wake law as the frustum leg.
+    /// An in-frustum rig whose room and its one hop are dark parks; the room's bit wakes it.
     #[test]
     fn a_room_dark_rig_parks_and_wakes_when_the_pvs_reaches_it() {
         let mut app = app();
         spawn_camera(&mut app);
-        // In front of the camera — only the room leg can park this rig.
+        // In front of the camera: only the room leg can park it.
         let (rig, joint) = spawn_rig(&mut app, -Vec3::Z * 20.0);
         let model = WmoModel {
             wmo_id: 1,
@@ -618,7 +528,7 @@ mod tests {
             "in-frustum but room-dark past the hysteresis window ⇒ parked"
         );
         let frozen = bone(&app, joint);
-        // The flood reaches the room (a doorway's screen window opened): wake and sample.
+        // The flood reaches the room: wake and sample.
         app.world_mut()
             .entity_mut(inst)
             .get_mut::<WmoPortalInstance>()
@@ -636,9 +546,7 @@ mod tests {
         );
     }
 
-    /// The coverage law (decision 0739): a driverless rig — a GameObject's, whose looping
-    /// player is its whole animation — parks by the same gate. `With<RigPose>`, not
-    /// `With<AnimDriver>`.
+    /// A driverless rig (a GameObject's) parks too: the gate keys on `RigPose`, not `AnimDriver`.
     #[test]
     fn a_driverless_go_rig_parks_too() {
         let mut app = app();
@@ -655,8 +563,6 @@ mod tests {
         assert_eq!(frozen, bone(&app, joint), "the parked GO rig's bones hold");
     }
 
-    /// The self-avatar never parks (the camera rides its attachment pivot; first-person fades it
-    /// while its swings still drive combat audio and the camera seat).
     #[test]
     fn the_self_avatar_is_exempt() {
         let mut app = app();
@@ -668,7 +574,7 @@ mod tests {
             !app.world().entity(behind).contains::<AnimParked>(),
             "the active mover never parks, wherever the camera points"
         );
-        // And its bones keep animating — the exemption is live evaluation, not just the marker.
+        // Its bones keep animating: the exemption is live evaluation, not just the marker.
         let before = bone(&app, behind_joint);
         advance(&mut app, DUR * 0.35, 2);
         assert_ne!(before, bone(&app, behind_joint), "its joints stay live");
diff --git a/crates/benilla-app/src/creature_anim/net.rs b/crates/benilla-app/src/creature_anim/net.rs
index 4734d960..dcd1173e 100644
--- a/crates/benilla-app/src/creature_anim/net.rs
+++ b/crates/benilla-app/src/creature_anim/net.rs
@@ -1,12 +1,6 @@
-//! 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.
+//! The animation layer's packet handlers: each resolves a guid and writes one message to play on a
+//! streamed unit. The swing record and the environmental-damage log also feed
+//! [`crate::combat_log`], whose handlers are registered first and so run first.
 
 use benilla_protocol::messages::{AttackSwingError, AttackerState, EnvironmentalDamageLog};
 use benilla_protocol::{SessionEvent, SessionEventKind};
@@ -21,7 +15,7 @@ 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`].
+/// Register the layer's handlers, from [`super::CreatureAnimPlugin`].
 pub(super) fn register(app: &mut App) {
     use SessionEventKind as K;
     app.net_handler(K::AttackStart, on_attack_start)
@@ -172,14 +166,11 @@ fn on_play_spell_visual(
 
 /// 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).
+    // The Ready idle rides this window: the client's gate is the auto-attack target being set.
     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.
+        // Melee start drops the `0x400` weapon-visual hold (`0x60fc50`): a shooter closing to
+        // melee leaves the drawn idle.
         commands
             .entity(e)
             .insert(Engaged(victim))
@@ -198,37 +189,25 @@ fn attack_stop(
     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.
+        // `0x624e40`: a pending swing flushes as text only; death and stun arrive as this packet.
         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.
+/// The server refused our swing (`SMSG_ATTACKSWING_*`); [`crate::swing_refusal`] owns the rest.
 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.
+/// `SMSG_CANCEL_COMBAT`: the server stopped our attack. The reference's handler `0x5e7dd0` is the
+/// refusal family's fourth arm 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.
+/// `SMSG_FEIGN_DEATH_RESISTED`: one red "Resisted" line and nothing else. The reference's handler
+/// `0x6e9800` is a bare `DisplayError(421)` (`0x496720`), with no latch and no state. vmangos sends
+/// it together with `SMSG_CANCEL_COMBAT` (`Unit.cpp:9469-9470`).
 fn feign_death_resisted(errors: &mut UiErrorKeys) {
     debug!("net: feign death resisted");
     errors.0.push(UiError::key("ERR_FEIGN_DEATH_RESISTED"));
@@ -241,9 +220,7 @@ fn ai_reaction(
     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`.
+    // Audio only (`0x6056e0`): 2 hostile and 0 alert flare; any other value does nothing.
     debug!("net: ai reaction {reaction} on {unit:#x}");
     if matches!(reaction, 0 | 2) {
         if let Some(&e) = index.0.get(&unit) {
@@ -255,11 +232,9 @@ fn ai_reaction(
     }
 }
 
-/// 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).
+/// One melee swing (`SMSG_ATTACKERSTATEUPDATE`): the attacker's swing plays now and the victim's
+/// feedback waits for the clip's attack-hit key (`0x6247d0`), except the center combat text, which
+/// the client shows at parse (`0x6255b0` → `0x629d30` → `0x703f50`).
 fn attacker_state(
     mut s: AttackerState,
     index: &GuidIndex,
@@ -273,11 +248,8 @@ fn attacker_state(
     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`).
+    // Our landed swing clears the refusal latch (`0x6259b6` → `0x5ea800` → `0x5ecdb0(0)`) when we
+    // are the attacker (`0x5fa6d0`) and the victim resolves; sent from here to keep packet order.
     if self_guid.0 == Some(s.attacker) && victim.is_some() {
         edges.write(SwingRefusalEdge::Landed);
     }
@@ -290,16 +262,12 @@ fn attacker_state(
             ),
         );
     }
-    // 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).
+    // The full-block synthesis (`0x625e20`): a resolved victim, no damage and a blocked amount
+    // read as state 5, BLOCK, before any consumer; a partial block stays state 1.
     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.
+    // The center text for a hit on us, after the synthesis so a full block reads BLOCK, not MISS.
     if self_guid.0 == Some(s.victim) {
         if let Some((message_type, data, extra)) = crate::combat_log::text::melee_center_text(
             s.hit_info,
@@ -326,17 +294,9 @@ fn attacker_state(
         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.
+        // A resolved attacker draws melee (`0x625829` → `SetSheatheState(1)` at `0x62583a`) before
+        // any hit-info handling, even when `HitInfo & 0x10000` suppresses the swing's animation;
+        // the per-animation reconcile never forces melee over a drawn bow (`0x5fe0f9`/`0x5fe13b`).
         sheaths.write(SheathRequest {
             entity: e,
             state: 1,
@@ -347,35 +307,23 @@ fn attacker_state(
             ..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.
+        // The unresolved-attacker leg (`0x625823` → `0x625a3e`) calls the gated dispatcher
+        // (`0x625a6d` → `0x624530`), so the lootable gate applies here too.
         !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).
+        // An attacker we cannot resolve cannot swing, so the victim's feedback fires now, in
+        // full. The placeholder attacker resolves nowhere (blood defaults to the 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.
+/// `SMSG_TEXT_EMOTE`: the animation needs the performer streamed, the chat line only needs their
+/// name, so an off-screen emote still prints (reference: `0x49dbe0`).
 fn text_emote(
     guid: u64,
     text_emote: u32,
@@ -391,8 +339,7 @@ fn 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).
+/// `SMSG_EMOTE`: an `Emotes.dbc` id to play on a unit (NPC scripts, a `/`-emote's animation).
 fn emote(guid: u64, emote_id: u32, index: &GuidIndex, out: &mut MessageWriter<EmoteMessage>) {
     out.write(EmoteMessage {
         source: index.0.get(&guid).copied(),
@@ -400,10 +347,8 @@ fn emote(guid: u64, emote_id: u32, index: &GuidIndex, out: &mut MessageWriter<Em
     });
 }
 
-/// `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.
+/// `SMSG_PLAY_SPELL_VISUAL`: a stage-0 kit play on the unit (eating, drinking, mid-channel
+/// swaps). Only a streamed unit takes a [`PlaySeq`] stamp.
 fn play_spell_visual(
     unit: u64,
     kit_id: u32,
@@ -420,11 +365,9 @@ fn play_spell_visual(
     }
 }
 
-/// `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.
+/// `SMSG_ENVIRONMENTALDAMAGELOG`'s visual (`0x624fcc` in `0x624f30`): the damage type's kit plays
+/// on the victim like any kit push (`0x60edf0`). The packet plays no sound: a fall's pain grunt
+/// is the client's own landing predictor (`0x602d00`, `creature_anim::env_damage`).
 fn environmental_damage_log(
     e: EnvironmentalDamageLog,
     index: &GuidIndex,
@@ -447,14 +390,9 @@ fn environmental_damage_log(
     }
 }
 
-/// `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.
+/// `SMSG_MOUNTSPECIAL_ANIM`: a nearby rider rears their mount (MountSpecial, 94). Our own guid is
+/// dropped, as we played it at send: vmangos asks for no echo (`MovementHandler.cpp:972`) but
+/// delivers one anyway unless its per-player broadcaster is on (`Object.cpp:2274`).
 fn mount_special(
     guid: u64,
     self_guid: &SelfGuid,
diff --git a/crates/benilla-app/src/creature_anim/select.rs b/crates/benilla-app/src/creature_anim/select.rs
index a7d3e051..80bc35ae 100644
--- a/crates/benilla-app/src/creature_anim/select.rs
+++ b/crates/benilla-app/src/creature_anim/select.rs
@@ -1,285 +1,147 @@
-//! 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`].
+//! The pure animation selection: `0x5fd8b0`'s gait picks, the one-shot tables, the rate math.
 
 use benilla_assets::AnimClip;
 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`, the `0x5fd224` compare).
+/// Walk speed (yd/s) for a unit whose movement block has none; Run starts above 2× (`0x5fd224`).
 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).
+/// At or above this speed (yd/s) a unit plays Sprint (143) over Run (`[0x80c484]`, `0x5fd202`).
 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.
+/// Below this ground speed (yd/s) a streamed mover counts as standing still.
 const MOVING_EPSILON: f32 = 0.1;
 
 pub(super) const STAND: u16 = 0;
 
 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; the clip-end watchdog `0x719370`), and the driver has to be able to say so.
+/// ShuffleLeft (11): once armed it plays out its clip, not ending with the turn (`0x719370`).
 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*. 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, 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}` and 119 is absent — the creep cycle plays at
-/// 1× whatever the live speed, so [`playback_rate`] leaves it alone.
+/// StealthWalk (119), gated with [`STEALTH_STAND`] on `UNIT_FIELD_BYTES_1` byte 3's CREEP bit
+/// (`0x5fd1d3`), ahead of the whole speed tail and not rate-scaled. Translucency is the stealth
+/// aura's own kit (CharProc 14); this flag is only the pose.
 pub(super) const STEALTH_WALK: u16 = 119;
 
-/// StealthStand (120) — the prowl idle, from the **last** resolver in the chain (the fallback idle
-/// `0x5fd830`: swim-idle → `[110]+0x213&2` → jump/float → plain Stand). Being last is its
-/// precedence: every other resolver — the sit/sleep/kneel and chair stand-states, the turn-in-place
-/// shuffle, the combat Ready idle, loot — outranks it. See [`STEALTH_WALK`] for the shared gate.
+/// StealthStand (120), from the chain's last resolver `0x5fd830`, so every other one outranks it.
 pub(super) const STEALTH_STAND: u16 = 120;
 
-/// 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).
+/// Mount (91), the rider's seat whatever the unit does: the client arms it outside the selector
+/// (`0x607a00`, `0x5fe2f0`); benilla pins the gait slot, and the locomotion plays on the mount.
 pub(super) const MOUNT: u16 = 91;
 
-/// 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.
-///
-/// The leg needs **two** predicates, and both split on IsActivePlayer:
-/// - **A `0x6126b0` — is a session open.** Self: the client-local loot-target latch
-///   (`[player+0x1d28]`, ours [`crate::ui_loot::LootLatch`]) — armed at the `CMSG_LOOT` send for a
-///   corpse, at `SMSG_SPELL_GO` for a chest, and at an admitted `SMSG_LOOT_RESPONSE` otherwise.
-///   Remote: [`UNIT_FLAG_LOOTING`] set and [`UNIT_FLAG_LOOT_SUPPRESS`] clear.
-/// - **B `0x612710` — is that KIND of target knelt at.** Self: a per-object-class filter, ours
-///   [`crate::ui_loot::LootKneel`]. It is why a fishing bobber arms the latch and still does not
-///   kneel, and 1471 shipped without it.
-///
-/// One consequence worth stating plainly, because it looks like a bug: on vmangos, other players
-/// never see us kneel at a chest. `Player::SendLoot` sets `UNIT_FLAG_LOOTING` only for
-/// `LOOT_CORPSE`, and the remote half has nothing else to read. The clip is authored
-/// **clamp** (HumanMale: one 0.5 s sequence, no variations): kneel down, freeze in the rummage
-/// pose; the rise back is the ordinary cross-fade to Stand when the trigger drops. Weapons stow
-/// for free — row 50 carries the `WeaponFlags & 4` force-stow the per-animation sheath
-/// reconcile already applies.
+/// Loot (50), the kneel while a loot window is open: the loot leg `0x5fd260`, after locomotion
+/// and ahead of the cast pin (`0x5fd2e0`) and the Ready idle (`0x5fd360`), declining when mounted
+/// or without the `[+0xd58] & 0x40` enable. It needs a session (`0x6126b0`: self, the loot latch;
+/// remote, [`UNIT_FLAG_LOOTING`]) and a kneelable target (`0x612710`: self, the target's kind;
+/// remote, [`UNIT_FLAG_LOOT_SUPPRESS`] clear).
 pub(super) const LOOT: u16 = 50;
 
-/// `UNIT_FIELD_FLAGS` bit `0x400` — `UNIT_FLAG_LOOTING` (vmangos `UnitDefines.h`: "Displays loot
-/// animation", set by `Player::SendLoot` for corpse loot, removed at `DoLootRelease`): the
-/// **remote** half of the loot-kneel predicate (`0x6126db shr 0xa; and 1` — see [`LOOT`]); the
-/// self unit reads its latch instead.
+/// `UNIT_FLAG_LOOTING` (`0x400`), a remote unit's loot-kneel predicate (`0x6126db`). vmangos sets
+/// it for corpse loot only (`Player.cpp:8148`), so others never see a chest kneel.
 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`; 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.
+/// `UNIT_FIELD_FLAGS` bit `0x1000_0000`, which must be clear for a remote unit's loot kneel
+/// (`0x612710`); its name and role are inferred. vmangos never sets it (`UNIT_FLAG_UNK_28`).
 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 (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).
+/// MountSpecial (94), the mount rearing: a one-shot on the mount model (`0x5fe2f0` routes it).
 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`. 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.
+/// Knockdown (121), with [`LIFT_OFF`] and [`LAND`] the ids whose arm takes the base-animation lock
+/// (`0x5fdba0`, table `0x5fdd90`): `PlayAnimation` refuses every base request while one holds.
 pub(crate) const KNOCKDOWN: u16 = 121;
-/// See [`KNOCKDOWN`] — the taxi/lift pair, which take the same lock under the reference's other bit.
+/// See [`KNOCKDOWN`]: the taxi pair takes the same lock under the reference's other bit.
 pub(crate) const LIFT_OFF: u16 = 192;
 /// See [`KNOCKDOWN`].
 pub(crate) const LAND: u16 = 200;
 
-/// Movement direction/mode flag bits, matching the client's CMovement `MOVEMENTFLAGS` (cached at
-/// `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.
+/// The client's `MOVEMENTFLAGS` bits (cached at `unit+0x9e8`), tested as the binary tests them.
 pub(crate) mod move_flags {
     pub const FORWARD: u32 = 0x1;
     pub const BACKWARD: u32 = 0x2;
     pub const STRAFE_LEFT: u32 = 0x4;
     pub const STRAFE_RIGHT: u32 = 0x8;
-    /// TURN-left / TURN-right — the keyboard turn keys (vanilla A/D when not mouse-looking). The client
-    /// rotates the facing while these are set (`0x7c4f30` heading integrate) and plays the turn-in-place
-    /// foot-shuffle (11/12) when turning with no translation. Strafe (above) slides without turning.
+    /// The keyboard turn keys (with `TURN_RIGHT`), which rotate the facing (`0x7c4f30`).
     pub const TURN_LEFT: u32 = 0x10;
     pub const TURN_RIGHT: u32 = 0x20;
-    /// WALK-mode (vs run). In the client this only scales the rate numerator (walk vs run speed), never
-    /// the id choice. The net bridge reads it to extrapolate a `/walk`-toggled remote mover at walk speed.
+    /// Walk mode: it scales only the rate numerator, never the id choice.
     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`): 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
-    /// 3-D floating regime (gravity bypassed, vertical from the aim pitch), and `LEVITATING` stops
-    /// the dry-land depth test from clearing it again the very next frame. `MOVED` (`0x800000`) and
-    /// `FLYING` (`0x1000000`) carry no behaviour on this build — vmangos's own header marks both
-    /// doubtful — and we model neither. Decision 0726.
+    /// `MOVEFLAG_LEVITATING`: the swim decision `0x6030c0` bails on it first (`0x6030d2`), so
+    /// liquid can neither latch nor clear [`SWIMMING`]; GM flight sets both (`Player.cpp:4595`).
     pub const LEVITATING: u32 = 0x400;
-    /// JUMPING/FALLING — set for the whole airborne arc; drives the jump Special state.
+    /// JUMPING/FALLING: set for the whole airborne arc.
     pub const FALLING: u32 = 0x2000;
-    /// 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).
+    /// `MOVEFLAG_FALLINGFAR` (`0x633220`/`0x633240`): a jump latches it 1/9 yd below its launch
+    /// height, a step-off fall after 500 ms airborne; only StopFalling (`0x7c6290`) clears it.
     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
-    /// root-apply ack without it — live-verified 2026-07-11, `Movement.log`), and moving bits
-    /// must never accompany it (they freeze the real client).
+    /// `MOVEFLAG_ROOT`: vmangos kicks a root-apply ack without it unless the ack still falls
+    /// (`MovementHandler.cpp:715-722`); a moving bit beside it freezes the 1.12 client.
     pub const ROOT: u32 = 0x1000;
     pub const SWIMMING: u32 = 0x20_0000;
-    /// MOVEFLAG_ONTRANSPORT — standing on a boat/zepp (1.12 bit 25, vmangos `MovementInfo.h:56`
-    /// `0x02000000`; NOT the TBC-era 0x200). Set while the mover rides a transport's platform
-    /// frame; every packet carrying it also carries the local-pose tail (decision 0438 phase 2).
+    /// `MOVEFLAG_ONTRANSPORT` (`MovementInfo.h:56`, not TBC's 0x200): every packet carrying it
+    /// also carries the transport-local pose.
     pub const ON_TRANSPORT: u32 = 0x0200_0000;
-    /// MOVEFLAG_WATERWALKING — the liquid surface counts as walkable ground (Water Walking,
-    /// Levitate, and the ghost form; decisions 0308/0866). Reference consumers: the liquid-mask
-    /// selector `0x6315f0` (`0x63160d test eax,0x10000000`, taken *only* when not swimming) and the
-    /// opcode-0x22 apply `0x61a430`.
+    /// `MOVEFLAG_WATERWALKING`: liquid is walkable ground; read by the liquid-mask selector
+    /// `0x6315f0` (`0x63160d`, only when not swimming) and the opcode 0x22 apply `0x61a430`.
     pub const WATER_WALKING: u32 = 0x1000_0000;
-    /// 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]`. 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).
+    /// `MOVEFLAG_SAFE_FALL`, feather fall: its one effect is the terminal fall speed (`0x7c5d23`),
+    /// 7.0 yd/s (`[0x87d898]`) instead of 60.148 (`[0x87d894]`).
     pub const SAFE_FALL: u32 = 0x2000_0000;
-    /// 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`).
+    /// `MOVEFLAG_HOVER`: the body rests 1.0 yd above the ground (Levitate): the walk resolver
+    /// `0x6367b0` adds the `[0x7ff9d8]` offset and the step-down reach widens by it (`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, 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
-    /// passes zero and takes this one).
-    ///
-    /// Two of ours land outside it and the omissions are the point. **[`ON_TRANSPORT`]** (bit 25)
-    /// is client-owned: a server-authored pose relocates you, it never boards or deboards you —
-    /// which is why the self-move arm re-anchors the ride rather than dropping it. Bit 27 (the
-    /// reference's free-advance selector) and bit 31 (its clock baseline) are CMovement internals
-    /// with no benilla analog. Every bit we *do* model besides `ON_TRANSPORT` — the direction and
-    /// turn bits, walk mode, root, [`FALLING`]/[`FALLING_FAR`], swim, water-walk — is inside.
+    /// The bits a server-authored move packet owns, the reference's merge mask (`0x618c30` @
+    /// `0x618deb`). [`ON_TRANSPORT`] is outside it: a server pose relocates a rider but never
+    /// boards or deboards them.
     pub const SERVER_AUTHORED: u32 = 0x75a0_7dff;
 
-    /// Merge a server-authored packet's `MOVEMENTFLAGS` into a mover's own — the reference's masked
-    /// merge (`0x618c30 @0x618de7-df3`: `new = old ^ ((old ^ wire) & 0x75a07dff)`), **not** an
-    /// 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 (`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.
+    /// Merge a server-authored packet's flags under [`SERVER_AUTHORED`] (`0x618de7`), for our mover
+    /// and every watched one: all thirty relay opcodes take this mask (`0x618f20`).
     pub const fn merge_server_authored(local: u32, wire: u32) -> u32 {
         (local & !SERVER_AUTHORED) | (wire & SERVER_AUTHORED)
     }
 
-    /// Any horizontal-movement direction bit (forward/back/strafe) — the client's `[9e8] & 0xf` gate.
+    /// Any horizontal direction bit: the client's `[9e8] & 0xf` gate.
     pub const ANY_MOVE: u32 = FORWARD | BACKWARD | STRAFE_LEFT | STRAFE_RIGHT;
 
-    /// **Whether this mover is integrated at all** — the client's `0x20ff`, and the gate a mover
-    /// 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. 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
-    /// direction bits, the two keyboard turn bits, and the two pitch bits benilla does not model
-    /// (together `0xff`), plus [`FALLING`] (`0x2000`). Note what is **absent**: [`SWIMMING`]
-    /// (`0x200000`) and every mode bit — a floating swimmer holding no direction is not integrated
-    /// either.
+    /// The bits that get a mover integrated at all, the client's `0x20ff` (`0x616e20`, `0x6166f5`):
+    /// without one a mover keeps its last packet's pose, and a flag-less unit is not even in the
+    /// mover list (`0x618940`). Swim and the mode bits are not among them.
     pub const INTEGRATED: u32 = 0xff | FALLING;
 
-    /// The **committed-lower-body** move mask that routes a one-shot to the masked overlay (decision
-    /// 0087): the client's `[9e8] & 0x20003f` test at `0x5fe6dc` — every direction bit (`0x3f`,
-    /// which folds in the keyboard turn keys) plus swim (`0x200000`). Any of these set ⇒ the legs are
-    /// committed, so a swing/emote plays masked over them rather than full-body. (The client's
-    /// *separate* facing-delta turn test `d58 & 0x1800` — a mouse turn-in-place with no move flag —
-    /// is a field benilla does not model; keyboard turning is already covered here via `0x30`.)
+    /// The committed-lower-body test routing a one-shot to the masked overlay (`0x5fe6dc`); the
+    /// client's separate mouse-turn test (`d58 & 0x1800`) reads a field benilla does not model.
     pub const ROUTE_COMMITTED_MOVE: u32 =
         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: 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).
+    /// The stationary-cast pin's moving test (`0x5fde80`): no turn bits, so a caster turning in
+    /// place keeps the pin, where [`ROUTE_COMMITTED_MOVE`]'s turn bits would flap it.
     pub const CAST_PIN_MOVE: u32 = ANY_MOVE | SWIMMING;
 }
 
-/// How fast a strafing unit's rendered root yaw eases toward its offset heading — the client blends
-/// the display facing a **quarter of the remaining gap per frame** (`0x607ed0` tail, `×0.25`
-/// `[0x8029b0]`); at the reference 60 fps that is the continuous exponential rate
-/// `−ln(0.75) × 60 ≈ 17.3 /s` (we take the time-based form rather than aping the frame-rate
-/// dependence). Applied by [`ease_strafe_yaw`], the pose owners' one blend.
+/// The rate (/s) the strafing yaw eases at: the reference closes a quarter of the gap per frame
+/// (`0x607ed0`, `[0x8029b0]`), 17.3/s at 60 fps. Deviation: a time-based rate, because the
+/// reference's per-frame step changes with the frame rate.
 const STRAFE_BLEND_RATE: f32 = 17.26;
 
-/// Advance a unit's rendered yaw toward `aim + offset` by easing the **aim-relative offset** as a
-/// plain scalar ([`STRAFE_BLEND_RATE`] exponential). For a stationary aim this is the same curve as
-/// easing the absolute yaw — EXCEPT at the strafe flip (±90° → ∓90°), where the absolute
-/// shortest-arc is an exact 180° tie that float noise resolves to either side ("sometimes it spins
-/// around the back" — director). Offset space has no tie: the swing always passes through the aim,
-/// i.e. around the front, and the spine/head twist gap unwinds through 0 instead of snap-flipping
-/// at ±180°.
+/// Ease the rendered yaw toward `aim + offset` through the aim-relative offset, which swings round
+/// the front where the absolute shortest arc ties at the ±90° strafe flip.
 pub(crate) fn ease_strafe_yaw(current_yaw: f32, aim: f32, offset: f32, dt: f32) -> f32 {
     let cur = super::wrap_pi(current_yaw - aim);
     let eased = cur + (offset - cur) * (1.0 - (-STRAFE_BLEND_RATE * dt).exp());
     super::wrap_pi(aim + eased)
 }
 
-/// The strafe **body-heading offset** (radians) a unit's rendered root yaw sits from its aim — the
-/// 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.
+/// The strafe body heading's offset from the aim (`0x607ed0`): ±π/2, ±π/4 with forward or back,
+/// left positive, mirrored while backpedaling. Both strafe bits give 0, as they cancel to no
+/// lateral motion, where the client's fold keys on the left bit alone: an unobservable edge.
 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;
@@ -297,34 +159,9 @@ 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
-/// (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
-/// rather than assumed — WoW +Z → Bevy +Y (so `Rz(facing)` is `Quat::from_rotation_y`, the mapping
-/// `net::motion::wire_yaw` already rests on, no 180° offset) and WoW +Y → Bevy **−X**
-/// (`coords::wow_bevy_basis_is_golden`), so `Ry(2π − pitch)` = `Ry(−pitch)` about −X is `+pitch`
-/// about Bevy +X. Same multiplication order, so the pitch stays body-local; and `Rx(+θ)` carries
-/// Bevy forward (−Z) to `(0, sin θ, −cos θ)`, i.e. up — nose-up positive on both sides.
-///
-/// 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]` 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
-/// 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::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.
+/// The swim body pitch for every mover with a reported pitch (`0x60a110` to `0x710620`): the
+/// reference's `Rz(facing)·Ry(2π − pitch)` is `Ry(yaw)·Rx(pitch)` here, nose up positive, and
+/// only SWIMMING with forward or back pitches (`CMovement+0x40 & 3` at `0x60857d`).
 pub(crate) fn swim_body_rotation(yaw: f32, flags: u32, pitch: f32) -> Quat {
     if flags & move_flags::SWIMMING != 0
         && flags & (move_flags::FORWARD | move_flags::BACKWARD) != 0
@@ -335,66 +172,38 @@ pub(crate) fn swim_body_rotation(yaw: f32, flags: u32, pitch: f32) -> Quat {
     }
 }
 
-/// 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`].
+/// The per-frame movement state the selector `0x5fd8b0` reads.
 #[derive(Component, Clone, Copy, Default)]
 pub(crate) struct MovementState {
-    /// Live movement speed (yd/s) — `0` while standing. The rate-scaler's numerator and the
-    /// walk/run threshold read this; it is already the *directional* speed (runBack when
-    /// backpedaling). On the ground it's the horizontal speed; for a swimmer it's the flag-scalar
-    /// 3D travel speed (swim/swimBack regardless of pitch — a vertical stroke plays at full rate).
+    /// Live directional speed (yd/s); for a swimmer the flag-scalar swim speed whatever its pitch.
     pub(crate) speed: f32,
-    /// Vertical speed (yd/s, +up); non-zero while airborne. Its sign on the arc's FIRST airborne
-    /// frame splits a **jump** (upward — the JumpStart/Jump bracket) from a **step-off fall** (the
-    /// gait freeze) — the information the real client carries as the MSG_MOVE_JUMP event vs a bare
-    /// StartFalling, which our flag-collapsed machine reads from the launch velocity instead.
+    /// Vertical speed (yd/s, up); its sign on the first airborne frame tells a jump from a fall.
     pub(crate) vertical_speed: f32,
-    /// CMovement `MOVEMENTFLAGS` subset (see [`move_flags`]).
+    /// `MOVEMENTFLAGS` ([`move_flags`]).
     pub(crate) flags: u32,
-    /// Stand-state (`UNIT_FIELD_BYTES_1` byte 0): 0 Stand · 1 Sit · 3 Sleep · 4/5/6 chair low/med/high ·
-    /// 8 Kneel — drives the idle pose / the sit-sleep-kneel transition while standing.
+    /// `UNIT_FIELD_BYTES_1` byte 0: 0 Stand, 1 Sit, 3 Sleep, 4/5/6 chair low/medium/high, 8 Kneel.
     pub(crate) stand_state: u8,
-    /// **Stealthed** — `UNIT_FIELD_BYTES_1` byte 3's CREEP bit, the gate on [`STEALTH_WALK`] /
-    /// [`STEALTH_STAND`]. Stamped by the driver from the unit's OWN descriptor every frame, self
-    /// and remote alike (the client reads `[[unit+0x110]+0x213]` at select time), so [`unify`]'s
-    /// legs never touch it: unlike the stand state there is nothing to predict controller-side —
-    /// the crouch waits on the server's aura, exactly as the reference does.
+    /// The CREEP bit, stamped from the unit's own descriptor every frame, self included.
     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 — `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`.
+    /// On a flying server spline (a taxi): the selector plays Fly 135 on its Flying bit 0x200
+    /// (`0x5fd19c`); [`unify`] stamps it from the live [`Spline`].
     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 reference selector + the
-/// HumanMale.m2 sequence table (decisions 0047/0049).
+/// A bracketed animation state: an enter one-shot, a loop, an exit one-shot.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum Special {
-    /// Airborne from a **jump** (the arc launched upward): JumpStart(37) → Jump(38) hang.
-    /// `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.
+    /// JumpStart (37), armed directly by `MSG_MOVE_JUMP` (`0x60e480` case 0xbb), then the Jump (38)
+    /// hang once 37's clip ends; a step-off fall never enters here.
     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
-    /// `enter_special` skips [`Mode::Entering`] for it. Lands like Jump, via [`jump_land_pick`].
+    /// The Fall (40) loop from the tick FALLINGFAR latches (`0x602c40`), with no enter one-shot.
     Fall,
-    /// A stand-state pose keyed on the standState value (1 Sit · 3 Sleep · 8 Kneel): down → loop → up.
+    /// A stand-state pose (1 Sit, 3 Sleep, 8 Kneel): down, loop, up.
     Pose(u8),
 }
 
 impl Special {
-    /// The one-shot played on entry (JumpStart / SitDown / SleepDown / KneelDown). Fall has no
-    /// enter — `enter_special` sends it straight to its loop; its arm here is unreachable, kept
-    /// for the exhaustive match.
+    /// The entry one-shot; Fall has none, so its arm here is unreachable.
     pub(super) fn enter(self) -> u16 {
         match self {
             Special::Jump => 37,
@@ -405,7 +214,7 @@ impl Special {
             Special::Pose(_) => STAND,
         }
     }
-    /// The looping middle (Jump hang / Fall / Sit / Sleep / Kneel).
+    /// The looping middle.
     pub(super) fn loop_id(self) -> u16 {
         match self {
             Special::Jump => 38,
@@ -416,9 +225,7 @@ impl Special {
             Special::Pose(_) => STAND,
         }
     }
-    /// The one-shot played on a *pose's* exit (SitUp / SleepUp / KneelUp). An airborne state's
-    /// landing never routes here — it is [`jump_land_pick`] (the `0x602c60` dispatcher) via
-    /// `Mode::Land`; the Jump/Fall arms are unreachable by flow, kept for the exhaustive match.
+    /// A pose's exit one-shot; a landing is [`jump_land_pick`]'s, so the airborne arm is unused.
     pub(super) fn exit(self) -> u16 {
         match self {
             Special::Jump | Special::Fall => STAND,
@@ -429,31 +236,16 @@ impl Special {
         }
     }
 
-    /// Whether starting to move cuts this state's exit short. A pose's stand-up (SitUp / …) is abandoned
-    /// the instant the unit moves — you don't watch yourself stand up when you walk off; the gait
-    /// cross-fade carries the half-pose into the walk. Jump/Fall never reach [`Mode::Exiting`] any
-    /// more — their landing is [`Mode::Land`], a freely-overwritten pick (decisions 0083/0087) — so
-    /// their `false` here is vestigial, kept for the exhaustive match.
+    /// Whether moving cuts the exit short: a pose's stand-up yields to the gait cross-fade at once.
     pub(super) fn interruptible_by_move(self) -> bool {
         matches!(self, Special::Pose(_))
     }
 }
 
-/// 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
-/// involved — and the reference suppresses the land packet on exactly that state
-/// (`0x602df3 test ah,0x10` gating opcode `0xc9`). This dispatcher *is* that packet's consumer
-/// (`0x602c60` runs on the FALL_LAND apply, local and observed alike), so no packet means no pick:
-/// the pose starves to Stand instead of playing JumpEnd in mid-air. Same suppression, same byte
-/// site, as the wire half in [`crate::player`]'s arc bookkeeping.
+/// The landing one-shot from the flags at touchdown (`0x602c60`): JumpEnd 39 stopped, none
+/// swimming, backpedaling or walking, else JumpLandRun 187. A rooted arc end is no landing:
+/// `SetRoot` (`0x7c7340`) stops the fall in mid-air and the reference sends no land packet
+/// (`0x602df3` gating opcode `0xc9`), the packet this dispatcher runs on.
 pub(super) fn jump_land_pick(flags: u32) -> Option<u16> {
     use move_flags::*;
     if flags & (SWIMMING | ROOT) != 0 {
@@ -475,46 +267,20 @@ pub(super) enum Mode {
     Entering(Special),
     /// Looping a Special; plays the exit one-shot when its condition clears.
     Looping(Special),
-    /// Playing a *pose's* exit one-shot (SitUp/SleepUp/KneelUp — the `Special` being left + the exit
-    /// clip id). Returns to Gait when it finishes — unless a new Special, or movement, interrupts it
-    /// first. (Jump's landing is [`Mode::Land`], not this — its bracket was killed per decision 0083.)
+    /// A pose's exit one-shot; back to Gait when done unless a Special or movement interrupts.
     Exiting(Special, u16),
-    /// The jump **landing** as a plain, freely-overwritten pick (decisions 0083/0087 (d)):
-    /// [`jump_land_pick`] chooses from the input *at touchdown* (`flags`) — JumpEnd 39 stopped,
-    /// JumpLandRun 187 moving forward; a backpedal/walk landing plays no clip and never enters this
-    /// mode — and re-picks the instant any movement flag changes, so land-then-press runs
-    /// immediately, land-then-release stands immediately, and a direction flip at landing shows no
-    /// stale-direction flash. Plays through to Gait only if the input holds steady. Not a
-    /// non-preemptible bracket.
+    /// The jump landing ([`jump_land_pick`]), re-picked the instant a movement flag changes; it
+    /// plays through to Gait only if they hold.
     Land { id: u16, flags: u32 },
-    /// Playing an action one-shot **full-body on the base track** (the bone-0 route of decision
-    /// 0087): a standing melee swing (decision 0073), a standing `/cheer`-class emote — or a
-    /// **mid-air cast/emote** (decision 0864: the airborne route test masks only COMBAT ids, so a
-    /// jump-in-place cast replaces the hang on bone 0, exactly the ref's full-body mid-air cast).
-    /// `under` is the Special whose base clip this play replaced (`None`: it replaced a gait).
-    /// 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 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
-    /// ([`AnimDriver::gait_flags`](crate::creature_anim::AnimDriver)) re-picks immediately: the
-    /// client's base re-arm overwrites bone 0 blindly on the change (the same re-arm decision 0280
-    /// named), so a shot fired standing yields to the run the instant the player moves instead of
-    /// sliding the clip out. It carried its own arm-time flags until 0894, which made the edge
-    /// invisible whenever the one-shot and the movement change landed on the same frame. The
-    /// *masked* route never enters here — it plays as an overlay beside `Mode`, leaving the base
-    /// machine (this enum) running underneath.
+    /// An action one-shot full-body on bone 0 (standing, or a mid-air cast or emote); `under` is
+    /// the Special it replaced. Airborne, a finished clip holds and only a Special edge exits (the
+    /// FALLINGFAR Fall, once at `0x61a820`, or the landing); grounded, any movement-flag change
+    /// since the base was armed re-picks at once, as the client's base re-arm overwrites bone 0.
     Swing { id: u16, under: Option<Special> },
 }
 
-/// 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 (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).
+/// The ids a unit in [`Mode::Gait`] tries, most specific first: the `0x5fd8b0` chain without its
+/// Special states. `ready` is the engaged idle, which locomotion outranks.
 pub(super) fn gait_candidates(
     state: &MovementState,
     walk_speed: f32,
@@ -523,11 +289,7 @@ pub(super) fn gait_candidates(
 ) -> &'static [u16] {
     use move_flags::*;
     let f = state.flags;
-    // 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.
+    // Swimming (`0x5fd100`): turn, then strafe, then backward, then forward.
     if f & SWIMMING != 0 {
         return if f & (TURN_LEFT | TURN_RIGHT) != 0 {
             &[41, 0]
@@ -543,11 +305,7 @@ pub(super) fn gait_candidates(
             &[41, 0]
         };
     }
-    // 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
-    // real Fly clips (the gryphon carries two variations).
+    // A flying spline, the taxi (`0x5fd19c`): Fly 135 ahead of backward and speed.
     if state.flying {
         return &[135, 0];
     }
@@ -555,18 +313,12 @@ pub(super) fn gait_candidates(
     if f & BACKWARD != 0 {
         return &[13, 4, 0];
     }
-    // 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
-    // what the baked PlayableAnimationLookup resolves 119 to on a model lacking the clip: HumanMale
-    // and NightElfFemale author both stealth clips, `druidcat.m2` authors NEITHER (119→4, 120→0), so
-    // a prowling cat shows its ordinary walk — in the reference too, through the same resolver.
+    // Stealthed and moving, the prowl (`0x5fd1d3`); Walk is row 119's AnimationData fallback.
     if state.stealthed && f & ANY_MOVE != 0 {
         return &[STEALTH_WALK, 4, 0];
     }
-    // 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.)
+    // Ground gaits by live speed (`0x5fd202`/`0x5fd224`): Sprint at 11 and above, Run above twice
+    // walk, else Walk. Strafe takes these too: the reference has no ground strafe branch.
     if f & ANY_MOVE != 0 {
         let s = state.speed;
         return if s >= FAST_RUN_SPEED {
@@ -577,17 +329,14 @@ pub(super) fn gait_candidates(
             &[4, 0]
         };
     }
-    // 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.
+    // Turning in place: the shuffle (`0x5fd3f0`, 11 left, 12 right).
     if f & TURN_LEFT != 0 {
         return &[SHUFFLE_LEFT, STAND];
     }
     if f & TURN_RIGHT != 0 {
         return &[SHUFFLE_RIGHT, STAND];
     }
-    // Standing + engaged in melee: the weapon-class Ready idle (decision 0073 — gated on engagement,
-    // not sheath state; outranks the chair poses, since a fighting unit isn't seated).
+    // Standing and engaged: the Ready idle (`0x5fd360`), gated on engagement, not the sheath.
     if let Some(r) = ready {
         return match r {
             26 => &[26, 25, 0],
@@ -596,19 +345,10 @@ pub(super) fn gait_candidates(
             _ => &[25, 0],
         };
     }
-    // Standing in the ranged stance with auto-repeat armed (the client's `0x5fd460`, gate
-    // `sheath CUR == 2 && [+0xd58] & 0x200` — local player only, decision 0099 phase 5): the
-    // ranged weapon's Load/Hold idle ([`ranged_load_anim`]). Placed after the engaged Ready
-    // (they can't co-occur — auto-shot never sets the engaged GUID) and before the chair loops
-    // (OUR ordering; the client's call-site order vs the chair resolver isn't pinned).
+    // Auto-repeat in the ranged stance (`0x5fd460`), ahead of the chair loops (`0x5fd550`).
     if let Some(l) = ranged_load {
-        // 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 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.
+        // A finished Load becomes its Hold through the completion dispatch (`0x5fc3f0`, fired at
+        // `0x7075af`); each Hold falls back to its Load, so a model without it holds full draw.
         return match l {
             105 => &[105, 25, 0],
             106 => &[106, 25, 0],
@@ -619,13 +359,8 @@ pub(super) fn gait_candidates(
             _ => &[25, 0],
         };
     }
-    // Standing: a chair-sit loop (server stand-states 4/5/6 — no down/up triple) else Stand. The
-    // transition-bracketed poses (1 Sit / 3 Sleep / 8 Kneel) are Special, handled before this is called.
-    // State 2 (generic SIT_CHAIR) is verified VESTIGIAL (decision 0280): the client's resolver row
-    // for 2 writes no override (`0x5fd644` returns a bool; the 0xd0 sentinel stands), so falling to
-    // plain Stand here is the faithful render, not a gap.
-    // Standing stealthed: the prowl idle ([`STEALTH_STAND`]) — placed *after* the chair loops, since
-    // its resolver (`0x5fd830`) is the last in the chain and the stand-state resolver precedes it.
+    // Standing: a chair loop (4/5/6), else the prowl idle, else Stand; state 2 (`SIT_CHAIR`)
+    // writes no override in the reference (its row declines, `0x5fd644`), so it stands.
     match state.stand_state {
         4 => &[102, 0],
         5 => &[103, 0],
@@ -635,17 +370,7 @@ pub(super) fn gait_candidates(
     }
 }
 
-/// 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 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.)
+/// The local auto-repeat standing idle by the ranged item's subclass (`0x5fd460`, LUT `0x5fd530`).
 pub(super) fn ranged_load_anim(ranged: Option<(u8, u8)>) -> u16 {
     match ranged {
         Some((2, 2)) => 105,           // Bow → LoadBow
@@ -656,26 +381,14 @@ pub(super) fn ranged_load_anim(ranged: Option<(u8, u8)>) -> u16 {
     }
 }
 
-/// Whether `id` is one of the ranged Load clips the drawn idle arms — the clips that must play
-/// **once and freeze at full draw** rather than looping ([`ranged_load_anim`]'s outputs, minus
-/// the wand's HoldThrown 111, which is already a hold pose).
+/// Whether `id` is a ranged Load clip, played once to full draw rather than looped.
 pub(super) fn is_ranged_load(id: u16) -> bool {
     matches!(id, 105 | 106 | 112)
 }
 
-/// The **Hold** clip a finished ranged Load promotes to — the completion dispatch `0x5fc3f0`'s
-/// slot 11/12/15 arms: LoadBow 105 → HoldBow 109 · LoadRifle 106 → HoldRifle 110 · LoadThrown 112
-/// → 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** (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.
-///
-/// The Hold is the only clip in the ranged cycle authored as a **loop** (asset flag, verified on
-/// five shipped character models); the fire and Load clips are clamp. That is why it can sit
-/// between shots at all, and why nothing needs to re-arm it per frame.
+/// The Hold a finished ranged Load becomes, unconditionally (`0x5fc3f0` slot 11, a bare call at
+/// `0x5fc5e9`); the `[+0xd24]` and `[+0xd58] & 0x600` test at `0x5fc5bc` is the Hold's own
+/// re-arm (slot 13). The Hold alone in the cycle is authored as a loop.
 pub(super) fn ranged_hold_anim(load: u16) -> u16 {
     match load {
         105 => 109,       // LoadBow → HoldBow
@@ -685,43 +398,16 @@ pub(super) fn ranged_hold_anim(load: u16) -> u16 {
     }
 }
 
-/// 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:
-///
-/// ```text
-/// 5fd463: cmp dword [ecx+0xd40], 2   ; sheath CUR == RANGED
-/// 5fd476: test ah, 0x2               ; [+0xd58] & 0x200 = auto-repeat active
-/// ```
-///
-/// `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 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: 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.
+/// Whether the drawn ranged idle owns the standing pose: `0x5fd460` claims on sheath CUR == 2
+/// (`0x5fd463`) and the auto-repeat bit `[+0xd58] & 0x200` (`0x5fd476`) alone, a bit only the
+/// local cast-send sets (`0x6e593b`). `0x400` ([`super::RangedHold`]) is not tested here, only by
+/// `0x5fc3f0`'s Hold sustain.
 pub(super) fn ranged_idle_gate(auto_repeat: bool, sheath_cur: Option<u8>) -> bool {
     sheath_cur == Some(2) && auto_repeat
 }
 
-/// The victim **defense-reaction** id (decision 0279 — the `$CPP` dispatch, byte-verified
-/// `0x624a01` → `0x60ec00`): DODGE/DEFLECTS → Dodge(30) · BLOCKS → ShieldBlock(24) · PARRY keys
-/// the victim's own **mainhand** through the `0x60ec98` LUT (read off `WoW.exe` `.text`, its
-/// third distinct weapon bucketing after the swing and Ready tables): 1H axes/maces/swords/
-/// exotic1H/misc **and dagger** → Parry1H(21) · 2H axes/maces/swords/exotic2H → Parry2H(22) ·
-/// polearm/staff/spear → Parry2HL(23) · **fist → ParryUnarmed(20)** · ranged/obsolete/
-/// subclass>0x11/non-weapon/empty → the client bails, no clip (`0x60ec3a`/bucket 4 → ret).
-/// Every other victimState plays nothing.
+/// The victim's defense reaction (`$CPP`, `0x624a01` to `0x60ec00`); a parry picks by the mainhand
+/// through the LUT `0x60ec98` and bails with no clip for anything else (`0x60ec3a`).
 pub(super) fn defense_anim(victim_state: u32, main: Option<(u8, u8)>) -> Option<u16> {
     match victim_state {
         2 | 8 => Some(30), // DODGE / DEFLECTS → Dodge
@@ -740,17 +426,8 @@ 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`).
-/// 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.
-/// `SpecialUnarmed`'s own `AnimationData.dbc` fallback column is 57, closing the ring.
-///
-/// The test is emptiness, not weapon-ness: a hand holding a non-weapon is non-NULL and keeps the
-/// armed clip. Because it sits at the play seam it covers every requester — a genuinely
-/// weaponless rogue and a disarmed one reach it by the same route (decision 1863).
+/// `PlayAnimation`'s substitution (`0x5fe2f0` @ `0x5fe3cc`–`0x5fe3e9`): Special1H/2H (57/58)
+/// becomes SpecialUnarmed (118) when both hands are empty; a non-weapon in hand keeps the clip.
 pub(super) fn unarmed_special(id: u16, main: Option<(u8, u8)>, off: Option<(u8, u8)>) -> u16 {
     if matches!(id, 57 | 58) && main.is_none() && off.is_none() {
         118
@@ -759,63 +436,36 @@ pub(super) fn unarmed_special(id: u16, main: Option<(u8, u8)>, off: Option<(u8,
     }
 }
 
-/// The per-packet melee swing one-shot ids (decision 0073's tables) — what the whiff slow-down
-/// (decision 0279) is allowed to touch when it finds them on the masked overlay.
+/// The melee swing one-shot ids, the only clips the whiff slow-down touches on the overlay.
 pub(super) fn is_swing_id(id: u16) -> bool {
     matches!(id, 16..=19 | 85 | 87 | 88 | 117)
 }
 
-/// 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 —
-/// Eviscerate's weapon-remapped spin among them — and 59), the defenses (20–23 parry, 24
-/// shield-block, 30 dodge), 10, 36, and Kick 95. The Ready idles (25–28) are NOT combat — a
-/// swing over a ready idle arms normally.
+/// The client's COMBAT classifier (`0x5fcc10`): a combat clip requested over another is not
+/// armed; the playing one's rate doubles and the request defers.
 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`): 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`); with [`is_combat_anim`] it is the transplant test
+/// (`0x5feae0`): a locomotion request lifts such a bone-0 clip to the key bone, not replacing it.
 pub(super) fn is_cast_anim(id: u16) -> bool {
     matches!(id, 2 | 32 | 33 | 53 | 54)
 }
 
-/// Whether `cands` (this frame's [`gait_candidates`] pick) is bare `[STAND]` — the one precedence
-/// slot the looping **state-emote idle** (`UNIT_NPC_EMOTESTATE`: `/dance`, NPC cooking/sweeping
-/// flavor loops) is allowed to fill instead, exactly where Stand itself would otherwise sit.
-/// Everything that already outranks plain Stand keeps outranking it: swim/backward/moving/turning
-/// return their own arrays above, the Ready idle requires `ready.is_some()` (i.e. engaged), and a
-/// chair-loop stand-state (4/5/6) has its own arm before the default. `current_special` (jump, the
-/// sit/sleep/kneel poses) is checked by the caller *before* [`gait_candidates`] is even invoked, so
-/// this predicate never has to account for Specials itself — they simply never reach here. Movement
-/// starting again drops straight out of the state-emote idle for the same reason Stand does: the
-/// very next frame's `cands` is no longer bare.
-///
-/// The **prowl idle** counts as bare too: [`STEALTH_STAND`] comes from `0x5fd830`, the *last*
-/// resolver in the client's chain, so anything with a resolver of its own outranks it. (OUR
-/// ordering, on that structural argument — where the emote-state idle sits in the real chain is
-/// unpinned; a stealthed unit holding an emote state is degenerate either way.)
+/// Whether `cands` is bare Stand, the one slot the state-emote idle (`UNIT_NPC_EMOTESTATE`) may
+/// fill. The prowl idle counts as bare: the reference's emote-state resolver (`0x5fd770`) runs
+/// before the fallback idle (`0x5fd830`) that picks it.
 pub(super) fn is_bare_stand(cands: &[u16]) -> bool {
     cands == [STAND] || cands == [STEALTH_STAND, STAND]
 }
 
-/// The candidate array for a state-emote idle occupying the bare-Stand slot: the resolved anim id
-/// first, `STAND` as the fallback should the model lack it — resolved through the same
-/// [`super::find_resolved`] path as every other gait candidate (decision 0082). Call only when
-/// [`is_bare_stand`] held for this frame's `cands`.
+/// The state-emote idle's candidates, Stand as the fallback; only for a bare-Stand frame.
 pub(super) fn state_emote_gait(emote_anim: u16) -> [u16; 2] {
     [emote_anim, STAND]
 }
 
-/// The mainhand swing animation id (decision 0073 — byte-verified `0x6246a0`): keyed on the wielded
-/// item's `(class, subclass)`. Anything that isn't an equipped melee weapon — empty hand, non-weapon
-/// item, fist weapon, every ranged/wand, obsolete(9), unknown subclasses — swings AttackUnarmed(16).
+/// The mainhand swing id (`0x6246a0`); anything but an equipped melee weapon swings unarmed (16).
 pub(super) fn swing_anim_main(wielded: Option<(u8, u8)>) -> u16 {
     match wielded {
         Some((2, sub)) => match sub {
@@ -829,9 +479,7 @@ pub(super) fn swing_anim_main(wielded: Option<(u8, u8)>) -> u16 {
     }
 }
 
-/// The offhand swing animation id (decision 0073, HitInfo bit `0x4`): a dagger stabs (88
-/// AttackOffPierce), any other equipped weapon swings 87 (AttackOff), an empty/non-weapon offhand
-/// punches (117 AttackUnarmedOff).
+/// The offhand swing id (HitInfo bit `0x4`): dagger 88, any other weapon 87, otherwise 117.
 pub(super) fn swing_anim_off(wielded: Option<(u8, u8)>) -> u16 {
     match wielded {
         Some((2, 0xf)) => 88,
@@ -840,11 +488,7 @@ 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 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.
+/// The draw/stow clip by sheath type (`0x611930`–`0x611cc6`): HipSheath 90 for 3 and 7, else 89.
 pub(super) fn sheath_clip(sheath_type: u8) -> u16 {
     if (1u32 << (sheath_type & 0x1f)) & 0x88 != 0 {
         90
@@ -853,30 +497,16 @@ pub(super) fn sheath_clip(sheath_type: u8) -> u16 {
     }
 }
 
-/// 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;
-/// the real thrown wind-up survives by the snap **bracket** around every ranged kit play
-/// (`driver`'s CastHold-ranged override), not by an exemption. The explicit trio compare at
-/// `0x5fe037`–`0x5fe04a` (105/106/112) is a fast-path subset.
+/// The ranged anims exempt from the `& 0x10` stow while ranged-drawn (`0x5fe180`, called only on
+/// that path, `0x5fe04c`). ReadyThrown 108 is not one: it stows, and the driver's snap bracket
+/// keeps the thrown wind-up.
 const SHEATH_RANGED_EXEMPT: [u16; 9] = [46, 49, 105, 106, 107, 109, 110, 111, 112];
 
-/// The per-animation sheath reconcile (decision 0080 — the client's `0x5fdf80`, run after every
-/// animation pick): given the unit's current sheath state and the playing clip's
-/// `AnimationData.dbc` WeaponFlags, the state the policy *forces*, or `None` to leave it alone.
-/// Priority-ordered, first match wins, every force is a SNAP:
-///
-/// 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; 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
-///    while not ranged-drawn;
-/// 5. a remote unit with no force pulls back to the server's descriptor byte (`0x5fe16e`; the
-///    local player's committed state is never server-reconciled).
+/// The per-animation sheath reconcile (`0x5fdf80`): the state the clip's WeaponFlags force, first
+/// match winning, each a snap. `& 4` stows; mounted stows on every recompute (`0x5fdfd9`) and
+/// dismount restores nothing (inferred); `& 0x10` stows, bar the ranged exemptions while
+/// ranged-drawn; engaged or `& 0x20` draws melee unless ranged-drawn; else a remote unit takes
+/// the server's byte (`0x5fe16e`).
 pub(super) fn reconcile_sheath(
     cur: u8,
     anim: u16,
@@ -910,22 +540,15 @@ pub(super) fn reconcile_sheath(
     None
 }
 
-/// 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`): 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).
+/// Whether a looping base arm keeps the head variation rather than rolling (`0x5fdba0`): with an
+/// auto-attack target, a cast or channel held, or a combat, cast or ready clip leaving. The ids
+/// here approximate the client's four classifiers (`0x5fcc10`, `0x5fcbb0`, `0x5fde40`, `0x5fde60`).
 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 — 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.
+/// The victim's wound flinch (`0x60ea70`), by severity and engagement alone: a crit (`HitInfo &
+/// 0x80`) CombatCritical, an engaged victim (`[unit+0xc48]` set) CombatWound, else StandWound.
 pub(super) fn wound_anim(hit_info: u32, engaged: bool) -> u16 {
     if hit_info & 0x80 != 0 {
         10 // CombatCritical
@@ -936,21 +559,10 @@ 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, `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
-///   **resolved** id actually driving the base track (the client reads the armed record,
-///   `[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** (`[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.
+/// Whether the wound overlay takes the full body rather than the upper body: any id over a ready
+/// stance (25–29) on bone 0 (`0x60eae8`; `base_anim` is the armed id, so mid-swing it masks), or
+/// StandWound (8) stationary and unmounted (`0x60eb9a` to `0x60ebea`); the reference's
+/// transport-substate test is not modelled.
 pub(super) fn wound_full_body(id: u16, base_anim: u16, flags: u32, mounted: bool) -> bool {
     matches!(base_anim, 25..=29)
         || (id == 8
@@ -958,38 +570,27 @@ pub(super) fn wound_full_body(id: u16, base_anim: u16, flags: u32, mounted: bool
             && flags & (move_flags::ANY_MOVE | move_flags::FALLING | move_flags::SWIMMING) == 0)
 }
 
-/// The wound overlay's decay amplitude λ₀ — the client seeds `+0x108 = 0.75f` on the op4
-/// `linkFlag=0` path (`0x712682`, decision 0111): the flinch peaks at 75% wound, never fully
-/// replacing the pose underneath. (A normal clip transition's outgoing-pose fade uses 1.0.)
+/// The wound overlay's amplitude λ₀, `+0x108 = 0.75` on op4's `linkFlag = 0` path (`0x712682`):
+/// the flinch peaks at 75%, never fully replacing the pose.
 pub(super) const WOUND_AMPLITUDE: f32 = 0.75;
 
-/// The wound overlay's Bevy graph weight this frame (decision 0111): the client's kernel computes
-/// `λ = smoothstep(t) · λ₀` with `smoothstep(t) = (3 − 2t)·t²` and `t` the remaining fraction of
-/// the decay window (`0x714880`: t runs 1 → 0 over the clip's span, so λ **decays** λ₀ → 0 — then
-/// the slot self-releases), and blends `out = primary + (secondary − primary)·λ`. Bevy's
-/// normalized weighted blend gives `out = others·base/(others+w) + w·wound/(others+w)`, so the
-/// weight that lands the blend exactly on λ is `w = others · λ/(1−λ)` — `others` being the total
-/// weight of the other animations driving the same subtree. Bounded: λ ≤ 0.75 ⇒ `w ≤ 3·others`.
+/// The wound overlay's graph weight: the client blends by `λ = (3 − 2t)·t² · λ₀`, `t` the
+/// fraction of the window left (`0x714880`), and Bevy's normalized blend lands on λ at
+/// `w = others · λ/(1 − λ)`, `others` the weight of the rest of the subtree (so `w ≤ 3·others`).
 pub(super) fn wound_weight(remaining_frac: f32, others: f32) -> f32 {
     let t = remaining_frac.clamp(0.0, 1.0);
     let lambda = (3.0 - 2.0 * t) * t * t * WOUND_AMPLITUDE;
     others * lambda / (1.0 - lambda)
 }
 
-/// The client's per-bone blend weight λ at amplitude 1.0 (`0x714880`–`0x714921`): `smoothstep(t)`
-/// with `smoothstep(t) = (3 − 2t)·t²` and `t` the fraction of the blend window **still to run**,
-/// so λ **decays 1 → 0** across it. Shared by the key-bone slot's two cross-fades (decision 0878):
-/// the fade-to-rest that releases a finished one-shot over a fixed 150 ms (op4 `param_3 = −1`,
-/// `0x7123af`: `+0x104 = 1/150`, amplitude `+0x108 = 1.0`) and the blended re-arm that cross-fades
-/// a new masked clip in over the *incoming* sequence's own blendTime (`0x7125f2`). The wound's
-/// twin ([`wound_weight`]) is the same curve at amplitude 0.75.
+/// The client's per-bone blend weight at amplitude 1 (`0x714880`–`0x714921`), `t` the fraction
+/// left: the 150 ms fade-to-rest (`0x7123af`) and the blended re-arm (`0x7125f2`).
 pub(crate) fn blend_lambda(remaining_frac: f32) -> f32 {
     let t = remaining_frac.clamp(0.0, 1.0);
     (3.0 - 2.0 * t) * t * t
 }
 
-/// The engaged standing idle (decision 0073 — the `0x5fd360` arm's weapon-class Ready pick,
-/// `0x5fcdc0`). Note the buckets differ from the swing table: fist **and** dagger ready as 1H.
+/// The engaged idle, `0x5fd360`'s Ready pick (`0x5fcdc0`); fist and dagger ready as 1H.
 pub(super) fn ready_anim(main: Option<(u8, u8)>) -> u16 {
     match main {
         Some((2, sub)) => match sub {
@@ -1002,12 +603,8 @@ 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: 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.
+/// The unit's Special: airborne, Fall once FALLINGFAR latches, else Jump for an upward launch (a
+/// step-off fall keeps its gait, `0x5fd8e8`); still and sitting, sleeping or kneeling, 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 {
@@ -1024,53 +621,37 @@ 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; the route
-/// flag `esi`, `0x5fe6c8..0x5fe74d`).
+/// Where a requested one-shot is routed this play (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
-    /// clip while the legs keep whatever the base is doing (run / sit / jump-arc). `Mode` is untouched.
+    /// The SpineLow overlay ([`AnimClip::upper_node`]): the torso plays it, the legs keep the base.
     Masked,
-    /// **Full-body on the base track** (bone 0): the clip replaces the base, legs included. Standing
-    /// idle only — the clip's authored leg keys then read as-is (a swing lunges, a `/cheer` is
-    /// full-body, a `/clap`/`/bow` reads waist-up because the *asset* barely keys the legs).
+    /// The base track (bone 0): the clip replaces the base, legs included, as authored.
     FullBody,
 }
 
-/// 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 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.
+/// The CLASS_A set (`0x5fed90`), the only ids that may mask; its ranges' interior is inferred,
+/// but only swings, emotes and casts reach [`route_oneshot`].
 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 (`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
-/// (decision 0864), while the same cast over a moving jump masks via the frozen-in move bits.
+/// The COMBAT set (`0x5fcc10`), the ids an airborne unit masks: every swing, no emote and no
+/// cast, so a jump-in-place cast replaces the hang full-body.
 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: 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.
+/// The ids forced full-body whatever the state: the Death class {1, 6, 131, 132} (`0x5fda90`)
+/// and the special attacks {57, 58, 118} (`0x5fec60`).
 fn is_forced_full_body(id: u16) -> bool {
     matches!(id, 1 | 6 | 131 | 132 | 57 | 58 | 118)
 }
 
-/// 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): 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
-/// id gates only *which* tests apply (CLASS_A gates the block; COMBAT gates the airborne test); it
-/// never decides maskability by itself — the same Attack1H is full-body standing and masked running.
+/// Route a one-shot by live state (`0x5fe6c8`..`0x5fe74d`): masked while the lower body is
+/// committed (moving, turning, swimming, a non-zero stand state, or a COMBAT id airborne), else
+/// full-body, so one Attack1H is full-body standing and masked running.
 pub(super) fn route_oneshot(id: u16, flags: u32, stand_state: u8) -> OneShotRoute {
     if is_forced_full_body(id) || !is_class_a(id) {
         return OneShotRoute::FullBody;
@@ -1085,120 +666,45 @@ pub(super) fn route_oneshot(id: u16, flags: u32, stand_state: u8) -> OneShotRout
     }
 }
 
-/// `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`]).
+/// The ids whose rate the client scales by speed (`0x5fee80`), also its LOCOMOTION set.
 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`). 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.
+/// Whether a requested clip is locomotion to the transplant tests (`0x5feae0`, `0x5fe912`). Fall
+/// (40) and SwimIdle (41) are not: a FALLINGFAR latch mid-cast replaces the cast on bone 0.
 pub(super) fn is_locomotion(id: u16) -> bool {
     RATE_SCALED.contains(&id)
 }
 
-/// Whether the gait this movement state resolves to is a **locomotion** id — i.e. whether a
-/// movement-flag re-arm is the transplant's `0x5fee80` request or an ordinary bone-0 overwrite.
-///
-/// The re-arm at a flag change has no id in hand yet (the gait is recomputed the following frame),
-/// so this asks [`gait_candidates`] what it *will* pick. `ready`/`ranged_load` are passed `None`
-/// deliberately and it changes no answer: both are **standing** idles that locomotion outranks in
-/// the cascade, so a moving unit picks its locomotion id whether or not they are set, and a still
-/// one picks something that is not locomotion either way.
-///
-/// This is the gate Ice Block turns on. A stun's root wipes the direction bits, the flag change
-/// re-arms, and the pick is **Stand(0)** — *not* locomotion — so the cast one-shot on bone 0 is
-/// **overwritten** rather than transplanted onto the torso: the character goes fully neutral before
-/// the freeze catches it (decision 0894, the director's reading of the reference client).
+/// Whether this state's gait pick is locomotion, deciding if a flag-change re-arm transplants the
+/// bone-0 clip or overwrites it; the standing idles cannot change the answer. A root wipes the
+/// direction bits, the pick is Stand, and a cast on bone 0 is overwritten.
 pub(super) fn gait_is_locomotion(state: &MovementState, walk_speed: f32) -> bool {
     gait_candidates(state, walk_speed, None, None)
         .first()
         .is_some_and(|id| is_locomotion(*id))
 }
 
-/// The playback rate for a clip given the unit's live speed and its rendered model scale — the
-/// client's `0x5fe2f0` divide (`0x5fe4be..0x5fe550`):
-///
-/// ```text
-/// 5fe508  call 0x711a20   ; DIVISOR = ‖row0(M+0xbc)‖ · M2Sequence[reqId].moveSpeed
-/// 5fe515  fcomp 0.0 ; jne ; GUARD A: divisor > 0     (else stay 1×)
-/// 5fe528  call 0x5fee80   ; GUARD B: the locomotion id whitelist (else stay 1×)
-/// 5fe53c  call 0x7c4c90   ; NUMERATOR = the flag-scalar current speed
-/// 5fe541  fdiv            ; rate = speed / (moveSpeed · scale)
-///
-/// M      = CGUnit+0xdc (the mount) if nonzero, else CGUnit+0xd8 (the body)
-/// ‖row0‖ = (mounted ? CGUnit+0x9c : 1.0) · CGUnit+0x94 · CGUnit+0x90
-/// ```
-///
-/// **`model_scale` is the half we were missing** (decision 0903). A sequence's `moveSpeed` is the
-/// ground speed its authored cycle covers *at the model's authored size*; render that model at `s×`
-/// and one cycle covers `s×` the ground, so the legs must cycle `s×` slower to hold the same speed.
-/// Without the divisor every off-1.0-scale creature ran its gait exactly `s×` too fast — a Gordok
-/// Ogre-Mage (`CreatureDisplayInfo.CreatureModelScale` 2.2) scurried its walk at 2.2× rate, and a
-/// 1.5× riding sabre its run at 1.5×.
-///
-/// The scale to pass is the **rendered world scale of the model actually playing the clip** — which
-/// is what the two terms above are: `CGUnit+0x90` is `OBJECT_FIELD_SCALE_X` (the server has already
-/// 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:
-///
-/// - 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
-///   rotation, since row 0 is `s · (a unit row)`. `abs()` is the cheaper spelling of the same
-///   number, and is only a distinction if unit scale ever stops being uniform.
-/// - `CGUnit+0x94`, a spell-visual scale multiplier clamped to `[0.75, 2.0]` (1.0 when idle), is a
-///   **third** factor we do not carry — because we have no producer for it: the aura CharProc
-///   dispatch (`crate::aura_visual::node_for`) implements Alpha/Tint/AnimRate and nothing that
-///   scales a unit. Whoever builds that layer must multiply it in here, or a scaling spell visual
-///   will re-time the gait wrongly for its duration. (`CGUnit+0x98`, the fourth slot, is a literal
-///   constant 1.0 in the binary — its constructor is its only writer.)
+/// A clip's rate, `0x5fe2f0`'s `speed / (moveSpeed · ‖row0‖)` (`0x5fe4be`..`0x5fe550`), 1× unless
+/// the divisor is positive and the id rate-scaled. `‖row0‖` is the rendered scale of the model
+/// playing it (`CGUnit+0x90`, `OBJECT_FIELD_SCALE_X`, times a mount's display scale `+0x9c`),
+/// the mount's model when mounted; the spell-visual factor `+0x94`
+/// (`[0.75, 2.0]`) has no producer yet and must join here.
 pub(super) fn playback_rate(clip: &AnimClip, speed: f32, model_scale: f32) -> f32 {
     scaled_rate(clip, speed, model_scale).unwrap_or(1.0)
 }
 
-/// [`playback_rate`] as the scaler's own question — **`Some` only where the scaler applies at
-/// all**: both of `0x5fe2f0`'s guards passed (a positive divisor, a locomotion id).
-///
-/// The distinction is what the per-frame rate write
-/// ([`sync_base_rate`](super::driver::play::sync_base_rate)) needs, and it is not pedantry: the
-/// scaler is one rate producer among several. The combat fast-path doubles an already-playing
-/// swing to 2× (decision 0406, op6 `2.0f`), the whiff slows a missed one to 0.5×, decision 0503
-/// freezes an airborne snapshot to 0×. Each owns the clip it wrote, and a per-frame write that
-/// returned a blanket `1.0` for "the guards failed" would silently stomp all three (it did — the
-/// suite caught it, decision 0906).
-/// The `abs()` is on the **scale only** — deliberately, and the asymmetry is the client's (decision
-/// 0912). `‖row0‖` is a matrix-row length, so it is never negative; `moveSpeed` is *signed*, and a
-/// backwards gait is authored negative (`RidingKodo.m2` WalkBackwards, `-2.5`). Guard A's strict
-/// `> 0` therefore leaves an authored backwards clip at a flat 1× while a model that falls back to
-/// forward Walk (`+2.5`) gets speed-scaled. Do not "tidy" this into `move_speed.abs()`.
+/// [`playback_rate`], `Some` only where both guards pass, so the per-frame write spares clips
+/// other producers own (the combat 2×, the whiff 0.5×, an airborne 0×). Only the scale takes
+/// `abs()`: `moveSpeed` is signed, and a backwards gait (-2.5) must stay at 1×.
 pub(super) fn scaled_rate(clip: &AnimClip, speed: f32, model_scale: f32) -> Option<f32> {
     let divisor = clip.move_speed * model_scale.abs();
     (divisor > 0.0 && RATE_SCALED.contains(&clip.anim_id)).then(|| speed / divisor)
 }
 
-/// Build the unified movement view, in precedence order: a populated [`MovementState`] (our avatar,
-/// driven by the controller) wins; else a remote player's live `moveFlags` + extrapolation speed
-/// ([`RemoteMotion`], from the relayed `MSG_MOVE_*` stream); else a creature's server spline (it moves
-/// forward at the path speed); else stationary. The remote flags are raw CMovement bits, which already
-/// match [`move_flags`], so the same selector animates a remote player's walk/run/strafe/backpedal/turn.
-///
-/// `creature_swimming` is the creature legs' swim state ([`crate::net::CreatureSwimming`] — the wire
-/// never carries `SWIMMING` for a creature, so it's derived from the water over its feet): it folds
-/// the flag into the spline/stationary views, so a pathing water creature plays Swim 42 and an idle
-/// one treads water (SwimIdle 41) instead of running/standing on the lakebed. Ignored for the
-/// self/remote legs — their flag arrives properly.
-///
-/// `modes` is the unit's **server-granted** movement modes ([`crate::net::UnitMoveModes`], decision
-/// 1780) — the `SMSG_SPLINE_MOVE_*` family. They are OR'd into the flags word on the remote and
-/// creature legs, because in the reference they are bits of the *same* `CMovement+0x40` word the
-/// selector already tests; a creature the server has put in walk mode or rooted has those bits set
-/// exactly like a player who arrived carrying them in a pose. The self leg deliberately skips them:
-/// our own mover's modes are the ack'd family's, held on [`crate::player::state::MoveModes`] and
-/// already folded into the controller's own `MovementState`.
+/// The unified movement view, first present winning: the controller's [`MovementState`], a
+/// remote's relayed flags ([`RemoteMotion`]), a creature's spline, else still.
+/// `creature_swimming` supplies the `SWIMMING` the wire never sends for a creature; `modes`, the
+/// `SMSG_SPLINE_MOVE_*` grants, join the remote and creature flags (one word in the reference).
 pub(super) fn unify(
     movement: Option<&MovementState>,
     remote: Option<&RemoteMotion>,
@@ -1206,9 +712,7 @@ pub(super) fn unify(
     creature_swimming: bool,
     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 (`0x5fd19c`),
-    // so a self ride (MovementState leg) and a remote taxi (spline leg) both fly.
+    // Every leg reads the flying spline live, as the selector does at select time (`0x5fd19c`).
     let flying = spline.is_some_and(|s| !s.grounded);
     if let Some(m) = movement {
         return MovementState { flying, ..*m };
diff --git a/crates/benilla-app/src/creature_anim/select/tests.rs b/crates/benilla-app/src/creature_anim/select/tests.rs
index e0179fc5..fbe71543 100644
--- a/crates/benilla-app/src/creature_anim/select/tests.rs
+++ b/crates/benilla-app/src/creature_anim/select/tests.rs
@@ -1,6 +1,4 @@
-//! Unit tests for the pure selection logic in [`super`] — moved to its own file as it carries the
-//! bulk of [`super`]'s line count; the production code + this file together are the same single
-//! `select` concern.
+//! Tests for the pure animation selection in [`super`].
 
 use super::*;
 use bevy::animation::graph::AnimationNodeIndex;
@@ -50,14 +48,9 @@ fn walk_run_boundary_is_twice_walk_speed() {
     assert_eq!(gait_candidates(&moving_forward(5.1), 2.5, None, None)[0], 5);
 }
 
-/// **The walk gait, composed end to end** (decision 1752) — the one assertion that says the
-/// feature actually works rather than that each half does.
-///
-/// The selector never reads `MOVEFLAG_WALK_MODE`; it reads the *speed*. So the walk gait is real
-/// only if the speed cascade and the gait cascade agree, and they agree only because the reference
-/// chose `2 × walkSpeed` as the boundary and `min(walk, run)` as the walk speed — at any vanilla
-/// speed set the walk lands strictly under its own boundary. Feed one into the other, with no
-/// hand-picked number in between, and see which clip comes out.
+/// The selector reads the speed, never `MOVEFLAG_WALK_MODE`: walk mode's speed, `min(walk, run)`,
+/// lands under the `2 × walkSpeed` Run boundary at any 1.12 speed set, so the speed cascade feeds
+/// the gait cascade here with no number in between.
 #[test]
 fn the_walk_bit_reaches_the_clip_through_the_speed_and_nothing_else() {
     use crate::creature_anim::move_flags as f;
@@ -79,11 +72,9 @@ fn the_walk_bit_reaches_the_clip_through_the_speed_and_nothing_else() {
     };
     assert_eq!(gait(f::FORWARD), 5, "no walk bit: Run");
     assert_eq!(gait(f::FORWARD | f::WALK_MODE), 4, "walk bit: Walk");
-    // Backwards is WalkBackwards(13) either way — the *speed* is what the walk bit changes there,
-    // and the clip's rate scaling is what makes it read as a walk rather than a fast reverse.
+    // Backward is WalkBackwards (13) either way: the walk bit changes only its speed and rate.
     assert_eq!(gait(f::BACKWARD), 13);
     assert_eq!(gait(f::BACKWARD | f::WALK_MODE), 13);
-    // …and a mount at 11.2 yd/s is not dragged under the boundary by anything above.
     let mounted = benilla_protocol::MoveSpeeds {
         run: 11.2,
         ..speeds
@@ -126,9 +117,7 @@ fn backward_is_walkbackwards() {
 
 #[test]
 fn swimming_back_forward_strafe_and_idle() {
-    // 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
-    // `0x5fd100` order.
+    // The swim row (`0x5fd137`): forward 42, back 45, turn 41, strafe SwimLeft 43 / SwimRight 44.
     let back = MovementState {
         speed: 4.0,
         flags: move_flags::SWIMMING | move_flags::BACKWARD,
@@ -153,8 +142,7 @@ fn swimming_back_forward_strafe_and_idle() {
         ..Default::default()
     };
     assert_eq!(gait_candidates(&right, 2.5, None, None), &[44, 42, 41, 0]);
-    // The `0x5fd100` cascade: TURN > STRAFE > BACKWARD > FORWARD. A strafe
-    // diagonal plays the side-stroke — strafe outranks both fwd and back…
+    // The `0x5fd100` cascade is turn, strafe, backward, forward: a strafe diagonal side-strokes.
     let diag = MovementState {
         speed: 4.0,
         flags: move_flags::SWIMMING | move_flags::FORWARD | move_flags::STRAFE_LEFT,
@@ -170,14 +158,12 @@ fn swimming_back_forward_strafe_and_idle() {
         gait_candidates(&back_diag, 2.5, None, None),
         &[44, 42, 41, 0]
     );
-    // …fwd+back together resolve backward…
     let fwd_back = MovementState {
         speed: 4.0,
         flags: move_flags::SWIMMING | move_flags::FORWARD | move_flags::BACKWARD,
         ..Default::default()
     };
     assert_eq!(gait_candidates(&fwd_back, 2.5, None, None), &[45, 41, 0]);
-    // …and a TURNING swimmer treads water whatever its travel bits (turn outranks all).
     let turn_moving = MovementState {
         speed: 4.0,
         flags: move_flags::SWIMMING | move_flags::FORWARD | move_flags::TURN_LEFT,
@@ -198,9 +184,8 @@ fn swimming_back_forward_strafe_and_idle() {
 
 #[test]
 fn airborne_splits_jump_fall_and_gait_freeze() {
-    // 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).
+    // A jump arc plays the 37/38 bracket, a FALLINGFAR latch the Fall (40) loop (`0x602c40`), and a
+    // step-off fall before the latch no special: the gait holds through it.
     let s = MovementState {
         flags: move_flags::FORWARD | move_flags::FALLING,
         ..Default::default()
@@ -217,7 +202,7 @@ fn airborne_splits_jump_fall_and_gait_freeze() {
 
 #[test]
 fn fall_is_the_40_loop() {
-    // Fall(40) both ways — `enter_special` goes straight to the loop (no enter one-shot).
+    // Fall (40) has no enter one-shot: `enter_special` goes straight to the loop.
     assert_eq!(Special::Fall.enter(), 40);
     assert_eq!(Special::Fall.loop_id(), 40);
     assert!(!Special::Fall.interruptible_by_move());
@@ -225,7 +210,6 @@ fn fall_is_the_40_loop() {
 
 #[test]
 fn a_pose_yields_to_movement_but_a_jump_landing_plays_out() {
-    // A pose's stand-up is cut short the instant the unit moves; a jump's landing footplant isn't.
     assert!(Special::Pose(1).interruptible_by_move());
     assert!(Special::Pose(3).interruptible_by_move());
     assert!(Special::Pose(8).interruptible_by_move());
@@ -234,17 +218,15 @@ fn a_pose_yields_to_movement_but_a_jump_landing_plays_out() {
 
 #[test]
 fn jump_sequence_ids() {
-    // The asset-verified sequence: JumpStart 37 (`0x60e480`) → Jump 38 → the landing pick (below).
+    // JumpStart 37 (`0x60e480`) → Jump 38 → the landing pick.
     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`: 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).
+    // `0x602c60`: stopped JumpEnd 39, forward or strafing JumpLandRun 187; backpedaling, walking
+    // or swimming no clip, the gait taking over at touchdown.
     use move_flags::*;
     assert_eq!(jump_land_pick(0), Some(39));
     assert_eq!(jump_land_pick(FORWARD), Some(187));
@@ -255,10 +237,8 @@ fn jump_land_pick_is_the_0x602c60_rule() {
     assert_eq!(jump_land_pick(FORWARD | WALK_MODE), None);
     assert_eq!(jump_land_pick(SWIMMING), None);
     assert_eq!(jump_land_pick(FORWARD | SWIMMING), None);
-    // …and ROOTED → no clip either (decision 0880): a root or a stun caught mid-air ends the fall
-    // in mid-air, and the reference suppresses the FALL_LAND this dispatcher runs on
-    // (`0x602df3`). Without it the body plays JumpEnd 39 while hanging 400 yd up — measured, and
-    // exactly what "the animation doesn't freeze" looked like.
+    // Rooted, no clip: a root caught mid-air ends the fall there, and the reference sends no land
+    // packet (`0x602df3`), the one this dispatcher runs on.
     assert_eq!(jump_land_pick(ROOT), None);
     assert_eq!(jump_land_pick(ROOT | FORWARD), None);
 }
@@ -274,7 +254,7 @@ fn standstate_is_a_pose_special_only_while_still() {
     assert_eq!(Special::Pose(1).enter(), 96);
     assert_eq!(Special::Pose(1).loop_id(), 97);
     assert_eq!(Special::Pose(1).exit(), 98);
-    // Sleep / Kneel triples.
+    // Sleep and Kneel.
     assert_eq!(
         (Special::Pose(3).enter(), Special::Pose(3).loop_id()),
         (99, 100)
@@ -283,7 +263,7 @@ fn standstate_is_a_pose_special_only_while_still() {
         (Special::Pose(8).enter(), Special::Pose(8).loop_id()),
         (114, 115)
     );
-    // Moving suppresses the pose (you stand up to move).
+    // Moving suppresses the pose.
     let sit_moving = MovementState {
         speed: 3.0,
         flags: move_flags::FORWARD,
@@ -296,7 +276,7 @@ fn standstate_is_a_pose_special_only_while_still() {
 
 #[test]
 fn turn_in_place_shuffles_but_moving_turn_runs() {
-    // Turning the facing with no translation plays the foot-shuffle (11/12).
+    // Turning in place plays the shuffle (11, 12).
     let left = MovementState {
         flags: move_flags::TURN_LEFT,
         ..Default::default()
@@ -307,7 +287,7 @@ fn turn_in_place_shuffles_but_moving_turn_runs() {
         ..Default::default()
     };
     assert_eq!(gait_candidates(&right, 2.5, None, None), &[12, 0]);
-    // Turning *while* moving runs (the path curves) — not the in-place shuffle.
+    // Turning while moving plays the gait.
     let move_turn = MovementState {
         speed: 3.0,
         flags: move_flags::FORWARD | move_flags::TURN_LEFT,
@@ -318,7 +298,7 @@ fn turn_in_place_shuffles_but_moving_turn_runs() {
 
 #[test]
 fn sheath_clip_is_the_0x88_test() {
-    // The byte-verified pick: sheathe types 3 and 7 → HipSheath(90); everything else → 89.
+    // `0x88` is the mask of sheath types 3 and 7, which play HipSheath (90); the rest play 89.
     assert_eq!(sheath_clip(3), 90);
     assert_eq!(sheath_clip(7), 90);
     for t in [0, 1, 2, 4, 5, 6, 8] {
@@ -328,7 +308,7 @@ fn sheath_clip_is_the_0x88_test() {
 
 #[test]
 fn swing_ids_by_weapon_class() {
-    // The byte-verified 0x6246a0 mainhand table (decision 0073).
+    // The `0x6246a0` mainhand table.
     assert_eq!(swing_anim_main(Some((2, 7))), 17); // 1H sword
     assert_eq!(swing_anim_main(Some((2, 5))), 18); // 2H mace
     assert_eq!(swing_anim_main(Some((2, 0xa))), 19); // staff
@@ -347,7 +327,7 @@ fn swing_ids_by_weapon_class() {
 
 #[test]
 fn ready_ids_bucket_differently_from_swings() {
-    // Fist AND dagger ready as 1H (decision 0073's 0x5fcdc0 table) though they swing 16/85.
+    // Fist and dagger ready as 1H (`0x5fcdc0`), though they swing 16 and 85.
     assert_eq!(ready_anim(Some((2, 0xd))), 26);
     assert_eq!(ready_anim(Some((2, 0xf))), 26);
     assert_eq!(ready_anim(Some((2, 8))), 27); // 2H sword
@@ -358,25 +338,24 @@ fn ready_ids_bucket_differently_from_swings() {
 
 #[test]
 fn ready_idle_only_while_standing() {
-    // Standing + engaged → the Ready idle (with the unarmed + Stand fallbacks).
+    // Standing and engaged: the Ready idle, with the unarmed and Stand fallbacks.
     assert_eq!(
         gait_candidates(&MovementState::default(), 2.5, Some(26), None),
         &[26, 25, 0]
     );
-    // The caller suppresses ready while moving — locomotion always outranks it.
+    // The caller drops the Ready while moving: locomotion outranks it.
     assert_eq!(gait_candidates(&moving_forward(3.0), 2.5, None, None)[0], 4);
 }
 
 #[test]
 fn reconcile_priority_is_stow_over_draw() {
-    // Flag &4 stows unconditionally — even engaged (swimming mid-combat stows).
+    // `& 4` stows unconditionally, even engaged (swimming mid-combat).
     assert_eq!(reconcile_sheath(1, 42, 4, true, true, 1, false), Some(0));
-    // Flag &0x10 stows BEFORE the engaged draw: an engaged bare-fist unit playing
-    // ReadyUnarmed/AttackUnarmed (0x10) stows — fists need empty hands.
+    // `& 0x10` stows before the engaged draw: fists need empty hands.
     assert_eq!(reconcile_sheath(1, 25, 0x10, true, true, 1, false), Some(0));
-    // Engaged draws melee even on a flagless clip (the persistent engaged re-assert).
+    // Engaged draws melee even on a flagless clip.
     assert_eq!(reconcile_sheath(0, 0, 0, true, true, 0, false), Some(1));
-    // Flag &0x20 draws without engagement (readying, fishing).
+    // `& 0x20` draws without engagement (readying, fishing).
     assert_eq!(
         reconcile_sheath(0, 133, 0x20, false, true, 0, false),
         Some(1)
@@ -388,40 +367,37 @@ fn reconcile_priority_is_stow_over_draw() {
 
 #[test]
 fn reconcile_mounted_is_a_persistent_draw_block() {
-    // 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.
+    // Mounted stows on every recompute (`0x5fdfd9`), over the engaged draw, the `& 0x20` draw and
+    // a remote's server byte.
     assert_eq!(reconcile_sheath(1, 0, 0, true, true, 1, true), Some(0));
     assert_eq!(
         reconcile_sheath(1, 133, 0x20, false, true, 1, true),
         Some(0)
     );
     assert_eq!(reconcile_sheath(1, 0, 0, false, false, 1, true), Some(0));
-    // Already stowed: the force is idempotent (the caller's `forced != cur` gate skips the write).
+    // Already stowed: the caller's `forced != cur` gate skips the write.
     assert_eq!(reconcile_sheath(0, 0, 0, false, true, 0, true), Some(0));
 }
 
 #[test]
 fn reconcile_ranged_exemption_and_remote_pull_through() {
-    // Ranged-drawn: the 0x5fe180 predicate's nine ids — the ranged Load/Hold/Attack family —
-    // are exempt from the &0x10 stow (byte-verified set, see the const's doc)…
+    // Ranged-drawn, `0x5fe180`'s nine Load/Hold/Attack ids are exempt from the `& 0x10` stow…
     for anim in [46, 49, 105, 106, 107, 109, 110, 111, 112] {
         assert_eq!(reconcile_sheath(2, anim, 0x10, false, true, 2, false), None);
     }
-    // …ReadyThrown 108 is NOT exempt — it genuinely stows; the thrown wind-up survives via
-    // the driver's ranged-hold snap bracket, not an exemption…
+    // …ReadyThrown 108 is not: it stows, and the driver's snap bracket keeps the thrown wind-up…
     assert_eq!(
         reconcile_sheath(2, 108, 0x10, false, true, 2, false),
         Some(0)
     );
-    // …but any other &0x10 clip stows even while ranged-drawn (an emote lowers the bow)…
+    // …any other `& 0x10` clip stows while ranged-drawn (an emote lowers the bow)…
     assert_eq!(
         reconcile_sheath(2, 60, 0x10, false, true, 2, false),
         Some(0)
     );
-    // …and while ranged-drawn the melee draw rules don't apply (no engaged→1 overwrite).
+    // …and the melee draw rules do not apply while ranged-drawn.
     assert_eq!(reconcile_sheath(2, 0, 0, true, true, 2, false), None);
-    // A remote unit with no force pulls back to the server byte (swim ends → redraw)…
+    // A remote unit with no force takes the server byte (a swim ends, it redraws)…
     assert_eq!(reconcile_sheath(0, 0, 0, false, false, 1, false), Some(1));
     // …but the local player's committed state is never server-reconciled.
     assert_eq!(reconcile_sheath(0, 0, 0, false, true, 1, false), None);
@@ -429,7 +405,7 @@ fn reconcile_ranged_exemption_and_remote_pull_through() {
 
 #[test]
 fn backpedal_rate_speeds_up_a_slow_design_speed() {
-    // Backpedaling at 4.5 yd/s against WalkBack authored for 2.5 → 1.8× (the "too slow" fix).
+    // Backpedaling at 4.5 yd/s on a WalkBackwards authored at 2.5: 1.8×.
     assert!((playback_rate(&clip(13, 2.5), 4.5, 1.0) - 1.8).abs() < 1e-5);
     assert!((playback_rate(&clip(5, 7.0), 7.0, 1.0) - 1.0).abs() < 1e-5);
 }
@@ -441,48 +417,40 @@ fn non_locomotion_clips_play_at_unit_rate() {
     assert_eq!(playback_rate(&clip(60, 2.0), 9.0, 1.0), 1.0); // an id outside the scaled set
 }
 
-/// The `0x5fe2f0` divisor is `moveSpeed · |modelScale|`, not `moveSpeed` alone (decision 0903) —
-/// the real numbers behind the director's two reports, so a regression names the creature it broke.
+/// The `0x5fe2f0` divisor is `moveSpeed · |modelScale|`, not `moveSpeed` alone.
 #[test]
 fn a_big_model_cycles_its_legs_slower_for_the_same_ground_speed() {
     // The Gordok Ogre-Mage (creature 11443, display 12472): `CreatureModelScale` 2.2, walking at
-    // vmangos' `speed_walk` 1.6 × the 2.5 yd/s base = 4.0 yd/s, against ogremage.m2's Walk(4)
-    // authored `moveSpeed` 2.5. Scale-blind that reads 1.60× — the scurry the director reported.
+    // vmangos' `speed_walk` 1.6 × 2.5 = 4.0 yd/s on a Walk (4) authored at 2.5; 1.60× scale-blind.
     assert!((playback_rate(&clip(4, 2.5), 4.0, 2.2) - 0.727_27).abs() < 1e-4);
-    // The riding sabre (model 457, `CreatureModelScale` 1.5) at a 60% mount's 11.2 yd/s against
-    // Run(5)'s authored 6.94: 1.08×, not the scale-blind 1.61×.
+    // The riding sabre (model 457, `CreatureModelScale` 1.5) at a 60% mount's 11.2 yd/s on a Run
+    // (5) authored at 6.94: 1.08×, not the scale-blind 1.61×.
     assert!((playback_rate(&clip(5, 6.94), 11.2, 1.5) - 1.075_89).abs() < 1e-4);
-    // An unscaled model is the identity — every 1.0-scale creature and player is unaffected.
     assert!((playback_rate(&clip(5, 6.94), 11.2, 1.0) - 1.613_83).abs() < 1e-4);
 }
 
-/// GUARD A tests the *divisor*, so a degenerate scale falls through to 1× instead of dividing by
-/// zero (a 0-scale unit is reachable: `OBJECT_FIELD_SCALE_X` is server-set and briefly 0 on a
-/// half-applied morph). `|modelScale|` is a magnitude — a negative scale mirrors, never reverses.
+/// The guard tests the divisor, so scale 0 (`OBJECT_FIELD_SCALE_X` is server-set) plays at 1×,
+/// and `|modelScale|` makes a negative scale mirror, never reverse.
 #[test]
 fn a_degenerate_model_scale_falls_through_to_unit_rate() {
     assert_eq!(playback_rate(&clip(4, 2.5), 4.0, 0.0), 1.0);
     assert!((playback_rate(&clip(4, 2.5), 4.0, -2.2) - 0.727_27).abs() < 1e-4);
 }
 
-/// The SIGN of `moveSpeed` is load-bearing, and the `abs()` belongs to the scale ALONE (decision
-/// 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
-/// `move_speed.abs()` is an inviting-looking tidy-up that would invert both halves at once.
+/// The sign of `moveSpeed` is load-bearing and only the scale takes `abs()`: an authored backwards
+/// gait is negative (`RidingKodo.m2` seq 14, WalkBackwards at -2.5, `benilla-extract m2seq`), so
+/// the strict `divisor > 0` guard leaves it at 1×, while a model without one falls back to forward
+/// Walk (+2.5) and is scaled.
 #[test]
 fn an_authored_backwards_gait_is_not_rate_scaled_but_its_fallback_is() {
-    // The authored clip (RidingKodo WalkBackwards, −2.5) — flat 1×, at any scale.
     assert_eq!(playback_rate(&clip(13, -2.5), 4.5, 1.0), 1.0);
     assert_eq!(playback_rate(&clip(13, -2.5), 4.5, 2.2), 1.0);
-    // …while a model lacking it substitutes forward Walk and scales normally.
     assert!((playback_rate(&clip(13, 2.5), 4.5, 1.0) - 1.8).abs() < 1e-5);
 }
 
 #[test]
 fn ranged_load_idle_selects_by_weapon_and_ranks_below_ready() {
-    // The 0x5fd530 LUT (0099 phase 5): ranged-slot subclass → the held Load/Hold clip.
+    // The `0x5fd530` LUT: ranged-slot subclass → the Load/Hold clip.
     assert_eq!(ranged_load_anim(Some((2, 2))), 105); // Bow → LoadBow
     assert_eq!(ranged_load_anim(Some((2, 3))), 106); // Gun → LoadRifle
     assert_eq!(ranged_load_anim(Some((2, 18))), 106); // Crossbow → LoadRifle
@@ -497,15 +465,14 @@ fn ranged_load_idle_selects_by_weapon_and_ranks_below_ready() {
         gait_candidates(&standing, 2.5, None, Some(105)),
         &[105, 25, 0]
     );
-    // The engaged melee Ready outranks it (they can't co-occur in the client — auto-shot never
-    // sets the engaged GUID — but the ordering is pinned here anyway).
+    // The engaged melee Ready outranks it, though the two never co-occur: auto-shot sets no engaged
+    // guid.
     assert_eq!(gait_candidates(&standing, 2.5, Some(26), Some(105))[0], 26);
-    // Locomotion outranks it: a moving shooter runs, the idle waits for the stop.
     assert_eq!(
         gait_candidates(&moving_forward(3.0), 2.5, None, Some(105))[0],
         4
     );
-    // It fills the bare-Stand slot's rank — so it also blocks the state-emote idle.
+    // It takes the bare-Stand slot, so it also blocks the state-emote idle.
     assert!(!is_bare_stand(gait_candidates(
         &standing,
         2.5,
@@ -514,35 +481,25 @@ 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`]):
-/// `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.
+/// `0x5fd460` claims the drawn ranged idle ([`ranged_idle_gate`]) on the ranged sheath
+/// (`cmp [+0xd40],2`) and the local auto-repeat bit `0x200` (`test ah,0x2`) alone. The any-caster
+/// hold `0x400` is tested only by `0x5fc3f0`'s Hold sustain: one Serpent Sting sets it and no
+/// volley end clears it, so admitting it would leave a shooter aiming.
 #[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.
     assert!(ranged_idle_gate(true, Some(2)));
-    // …and it needs CUR == 2: a melee-drawn or stowed unit is never in the family.
+    // It needs the ranged sheath (2): a melee-drawn or stowed unit is never in the family.
     assert!(!ranged_idle_gate(true, Some(1)));
     assert!(!ranged_idle_gate(true, Some(0)));
     assert!(!ranged_idle_gate(true, None));
-    // Drawn ranged but not auto-repeating — a hunter who fired one Serpent Sting and stopped,
-    // and every REMOTE shooter (which never runs the local cast-send, so `0x200` cannot exist
-    // on it). No aim pose, whatever its weapon-visual hold says.
+    // Drawn ranged without auto-repeat, as after one Serpent Sting or on any remote shooter (only
+    // the local cast-send sets `0x200`): no aim pose, whatever `0x400` says.
     assert!(!ranged_idle_gate(false, Some(2)));
 }
 
-/// The Load → Hold promotion ([`ranged_hold_anim`]) — the completion dispatch's slot 11/12/15
-/// arms (decision 1544). Each ranged Load yields its weapon family's Hold, which is the one clip
-/// 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. 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.
+/// The completion dispatch promotes each ranged Load to its family's Hold (slots 11, 12 and 15),
+/// the cycle's one looping clip. A fire clip recomputes the base like any one-shot, through the
+/// dispatcher's deferred fire site (`0x7075af`).
 #[test]
 fn each_ranged_load_promotes_to_its_weapon_familys_hold() {
     assert_eq!(ranged_hold_anim(105), 109); // LoadBow → HoldBow
@@ -550,14 +507,11 @@ fn each_ranged_load_promotes_to_its_weapon_familys_hold() {
     assert_eq!(ranged_hold_anim(112), 111); // LoadThrown → HoldThrown
     assert_eq!(ranged_hold_anim(111), 111); // the wand's idle IS the hold: it re-arms itself
     assert_eq!(ranged_hold_anim(25), 25); // no ranged weapon holds nothing: ReadyUnarmed stays
-                                          // The promotion is keyed on the LOAD clip, so a fire id is not a valid input and must not
-                                          // silently map onto a hold — it recomputes the base instead, and the gait re-picks the Load.
-    assert_eq!(ranged_hold_anim(46), 46);
+    assert_eq!(ranged_hold_anim(46), 46); // a fire id is no Load and maps onto no hold
 }
 
 #[test]
 fn state_emote_idle_only_fills_the_bare_stand_slot() {
-    // Standing, nothing else going on: the one slot the state-emote idle may fill.
     assert!(is_bare_stand(gait_candidates(
         &MovementState::default(),
         2.5,
@@ -566,33 +520,29 @@ fn state_emote_idle_only_fills_the_bare_stand_slot() {
     )));
     assert_eq!(state_emote_gait(200), [200, STAND]);
 
-    // Movement outranks it — its own candidate array, not bare Stand.
     assert!(!is_bare_stand(gait_candidates(
         &moving_forward(3.0),
         2.5,
         None,
         None
     )));
-    // Turning in place outranks it too.
     let turning = MovementState {
         flags: move_flags::TURN_LEFT,
         ..Default::default()
     };
     assert!(!is_bare_stand(gait_candidates(&turning, 2.5, None, None)));
-    // Swimming idle outranks it.
     let swimming = MovementState {
         flags: move_flags::SWIMMING,
         ..Default::default()
     };
     assert!(!is_bare_stand(gait_candidates(&swimming, 2.5, None, None)));
-    // Engaged (the Ready idle) outranks it.
     assert!(!is_bare_stand(gait_candidates(
         &MovementState::default(),
         2.5,
         Some(26),
         None
     )));
-    // A chair-loop stand-state (server 4/5/6) already has its own slot, ranked above bare Stand.
+    // The chair stand states 4, 5 and 6 have their own slot, above bare Stand.
     for stand_state in [4, 5, 6] {
         let chair = MovementState {
             stand_state,
@@ -602,22 +552,22 @@ fn state_emote_idle_only_fills_the_bare_stand_slot() {
     }
 }
 
-// ── The per-play one-shot route (decision 0087) — one test per director-signed acceptance row.
-// Ids: Attack1H 17 (a combat swing), EmoteApplaud 80 / EmoteBow 66 (waist-up-authored emotes),
-// EmoteCheer 68 (full-body-authored emote). `stand_state` 1 = seated.
+// ── The per-play one-shot route ──
+// `esi` is the reference's route flag (`0x5fe6c8`). Ids: Attack1H 17 (a combat swing),
+// EmoteApplaud 80 and EmoteBow 66 (waist-up emotes), EmoteCheer 68 (a full-body emote);
+// `stand_state` 1 is seated.
 use OneShotRoute::{FullBody, Masked};
 
 #[test]
 fn route_row1_standing_swing_is_full_body() {
-    // Not moving, standState 0, combat(17) but not airborne → esi=0 → bone 0 (legs lunge, authored).
     assert_eq!(route_oneshot(17, 0, 0), FullBody);
 }
 
 #[test]
 fn route_row2_running_swing_is_masked() {
-    // Moving ([9e8] & 0x20003f) → esi=1 → SpineLow overlay; legs keep the run underneath.
+    // Moving (`[9e8] & 0x20003f`): `esi` 1, the SpineLow overlay over the run.
     assert_eq!(route_oneshot(17, move_flags::FORWARD, 0), Masked);
-    // Every direction bit — and the keyboard turn keys folded into 0x3f — commits the legs.
+    // Every direction bit commits the legs, the keyboard turn keys in `0x3f` included.
     for f in [
         move_flags::BACKWARD,
         move_flags::STRAFE_LEFT,
@@ -631,57 +581,49 @@ fn route_row2_running_swing_is_masked() {
 
 #[test]
 fn route_row3_midair_swing_is_masked() {
-    // Straight-up jump: not moving, standState 0, but combat(17) && airborne → esi=1 → overlay.
     assert_eq!(route_oneshot(17, move_flags::FALLING, 0), Masked);
-    // The airborne test is COMBAT-gated: a non-combat emote mid-jump is NOT masked on air alone.
+    // The airborne test is combat-gated: an emote mid-jump is not masked.
     assert_eq!(route_oneshot(68, move_flags::FALLING, 0), FullBody);
 }
 
 #[test]
 fn route_row4_seated_emote_is_masked() {
-    // standState ≠ 0 (seated) → esi=1 → overlay over the continuing Sit; /clap and /laugh alike.
     assert_eq!(route_oneshot(80, 0, 1), Masked);
     assert_eq!(route_oneshot(70, 0, 1), Masked); // EmoteLaugh family
 }
 
 #[test]
 fn route_row5_standing_clap_and_bow_are_full_body() {
-    // Not moving, standState 0, combat NO (66/80 ∉ COMBAT) → esi=0 → bone 0. The waist-up LOOK is
-    // asset authoring (clap ≤1.3°, bow feet 0°), not a route special-case — same route as /cheer.
+    // 66 and 80 are not COMBAT: `esi` 0, bone 0; their waist-up look is authored, not routed.
     assert_eq!(route_oneshot(80, 0, 0), FullBody);
     assert_eq!(route_oneshot(66, 0, 0), FullBody);
 }
 
 #[test]
 fn route_row6_standing_cheer_is_full_body() {
-    // Identical routing to row 5 (68 ∉ COMBAT, standing) → bone 0; cheer's legs are authored large.
+    // Routed as row 5; cheer's legs are authored large.
     assert_eq!(route_oneshot(68, 0, 0), FullBody);
 }
 
 #[test]
 fn route_row7_seated_cheer_is_masked() {
-    // Same cheer clip as row 6 but seated → esi=1 → overlay; the authored legs never reach the
-    // legs (overlay ⊅ legs), so the character neither stands nor moves its legs. The #6-vs-#7
-    // clincher: one clip, opposite looks, purely from the state route.
+    // Row 6's clip seated: `esi` 1, and the overlay never reaches the legs, which stay seated.
     assert_eq!(route_oneshot(68, 0, 1), Masked);
 }
 
 #[test]
 fn route_land_row8_picks_land_clip_from_touchdown_input() {
-    // Row 8 is a state-machine behavior (driven in `drive_animations`'s `Mode::Land` arm); its
-    // one-shot ids come from the `0x602c60` pick: JumpEnd 39 stopped, JumpLandRun 187 moving
-    // forward, no clip at all backpedaling/walking.
+    // Row 8 is `drive_animations`'s `Mode::Land`; its ids are the `0x602c60` pick.
     assert_eq!(jump_land_pick(0), Some(39));
     assert_eq!(jump_land_pick(move_flags::FORWARD), Some(187));
     assert_eq!(jump_land_pick(move_flags::BACKWARD), None);
-    // The land is not a non-preemptible bracket — `Mode::Land` re-picks on any flag change.
+    // `Mode::Land` re-picks on any flag change.
     assert!(!Special::Jump.interruptible_by_move());
 }
 
 #[test]
 fn route_classifier_memberships_are_the_decoded_bytes() {
-    // 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.
+    // COMBAT (`0x5fcc10`) is every swing, no emote; CLASS_A (`0x5fed90`) has 17, 66, 68 and 80.
     assert!(is_combat(17));
     for id in [66, 68, 80] {
         assert!(!is_combat(id), "emote {id} must not be COMBAT");
@@ -700,10 +642,8 @@ fn route_classifier_memberships_are_the_decoded_bytes() {
 
 #[test]
 fn state_emote_idle_never_reached_during_a_special() {
-    // Jump and the sit/sleep/kneel poses are gated by `current_special` *before*
-    // `gait_candidates` is ever consulted (see `drive_animations`'s Gait arm) — the
-    // state-emote idle can't leak into either, so this pins the exhaustive precedence:
-    // Special > (movement/turn/swim/ready/chair, all non-bare-Stand) > state-emote idle > Stand.
+    // `current_special` takes jumps and poses before `gait_candidates` runs, so the order is:
+    // Special, every non-bare-Stand pick, the state-emote idle, Stand.
     let jumping = MovementState {
         flags: move_flags::FALLING,
         ..Default::default()
@@ -728,8 +668,8 @@ fn strafe_body_offset_matches_the_client_sign_fold() {
     // Forward diagonal: ±45°.
     assert_eq!(strafe_body_offset(STRAFE_LEFT | FORWARD), FRAC_PI_4);
     assert_eq!(strafe_body_offset(STRAFE_RIGHT | FORWARD), -FRAC_PI_4);
-    // Backpedal diagonal mirrors (the client's `((flags>>1)&2)==(flags&2)` fold): a back-left
-    // diagonal faces the body forward-RIGHT and backpedals along the movement line.
+    // A backpedal diagonal mirrors (the client's `((flags>>1)&2)==(flags&2)` fold): back-left
+    // faces the body forward-right.
     assert_eq!(strafe_body_offset(STRAFE_LEFT | BACKWARD), -FRAC_PI_4);
     assert_eq!(strafe_body_offset(STRAFE_RIGHT | BACKWARD), FRAC_PI_4);
     // Not strafing (or both strafe keys cancelling): no offset.
@@ -741,14 +681,11 @@ fn strafe_body_offset_matches_the_client_sign_fold() {
 #[test]
 fn strafe_flip_always_swings_around_the_front() {
     use std::f32::consts::{FRAC_PI_2, PI};
-    // The left↔right flip is an exact 180° turn: easing the absolute yaw ties at the shortest-arc
-    // wrap and float noise picks a side — the reported "sometimes it spins around the back".
-    // Offset-space easing must swing through the aim (the front): the aim-relative offset stays
-    // within ±90° for the whole transition, both flip directions, at any aim (including one near
-    // the ±π wrap seam, where the absolute yaws cross the discontinuity mid-swing).
+    // The left-right flip is an exact 180° turn, where the absolute shortest arc ties; easing the
+    // aim-relative offset keeps it within ±90° through the front at any aim, the ±π seam included.
     for aim in [0.0_f32, 1.3, PI - 0.01, -2.6] {
         for (from, to) in [(-FRAC_PI_2, FRAC_PI_2), (FRAC_PI_2, -FRAC_PI_2)] {
-            // Bit-exactly converged on the old pose — the knife-edge case.
+            // Converged exactly on the old pose, the tie.
             let mut yaw = super::super::wrap_pi(aim + from);
             for _ in 0..120 {
                 yaw = ease_strafe_yaw(yaw, aim, to, 1.0 / 60.0);
@@ -766,7 +703,7 @@ fn strafe_flip_always_swings_around_the_front() {
 
 #[test]
 fn base_arm_head_force_is_the_combat_carveout() {
-    // Decision 0123 (the client's `0x5fdba0` re-zero gate): a relaxed arm rolls (−1)…
+    // The `0x5fdba0` re-zero gate: a relaxed arm rolls (-1)…
     assert!(!arm_forces_head(false, false, 0), "Stand → Stand re-arm");
     assert!(
         !arm_forces_head(false, false, 11),
@@ -776,7 +713,7 @@ fn base_arm_head_force_is_the_combat_carveout() {
         !arm_forces_head(false, false, 60),
         "an emote falling back to Stand"
     );
-    // …and engagement, a live cast hold, or a combat/cast/ready outgoing id force the head.
+    // …and engagement, a cast hold, or an outgoing combat, cast or ready id forces the head.
     assert!(arm_forces_head(true, false, 0), "auto-attack target set");
     assert!(arm_forces_head(false, true, 0), "cast/channel hold");
     assert!(arm_forces_head(false, false, 17), "outgoing Attack1H");
@@ -789,7 +726,7 @@ fn base_arm_head_force_is_the_combat_carveout() {
 
 #[test]
 fn wound_id_by_severity_then_engagement() {
-    // Decision 0111: crit outranks engagement; engagement decides 9 vs 8.
+    // A crit outranks engagement, which picks 9 over 8 (`0x60ea70`).
     assert_eq!(wound_anim(0x2 | 0x80, false), 10);
     assert_eq!(wound_anim(0x2 | 0x80, true), 10);
     assert_eq!(wound_anim(0x2, true), 9);
@@ -799,45 +736,42 @@ fn wound_id_by_severity_then_engagement() {
 #[test]
 fn wound_route_full_body_on_ready_stance_or_stationary_standwound() {
     use move_flags::*;
-    // (A) any id over a combat-ready base pose {25–29} — regardless of move flags (the client
-    // tests the bone-0 armed record alone).
+    // Any id over a ready stance (25-29), whatever the move flags: the client tests bone 0's
+    // armed record alone.
     assert!(wound_full_body(9, 26, 0, false));
     assert!(wound_full_body(10, 29, FORWARD, false));
-    // (B) StandWound, genuinely stationary. The client's 0x20200f mask has no turn bits: a
-    // keyboard turn-in-place does NOT block the full-body route.
+    // StandWound stationary: the client's `0x20200f` mask has no turn bits, so turning in place
+    // still routes full-body.
     assert!(wound_full_body(8, 0, 0, false));
     assert!(wound_full_body(8, 0, TURN_LEFT, false));
     assert!(!wound_full_body(8, 0, FORWARD, false));
     assert!(!wound_full_body(8, 0, FALLING, false));
     assert!(!wound_full_body(8, 0, SWIMMING, false));
-    // Masked otherwise: engaged victim mid-its-own-swing (base = the swing, not ready), a moving
-    // CombatWound, a stationary CombatWound over a non-ready base (unarmed idle).
+    // Masked otherwise: mid-swing (the base is the swing), moving, or over a non-ready base.
     assert!(!wound_full_body(9, 17, 0, false));
     assert!(!wound_full_body(9, 5, FORWARD, false));
     assert!(!wound_full_body(9, 0, 0, false));
-    // Mounted masks the stationary StandWound (decision 0441, the `[unit+0xdc]==0` companion
-    // clause): a rider's flinch never replaces the seat pose.
+    // Mounted masks StandWound (the `[unit+0xdc] == 0` clause): a flinch never replaces the seat.
     assert!(!wound_full_body(8, 0, 0, true));
 }
 
 #[test]
 fn wound_weight_decays_smoothstep_to_zero() {
-    // Fresh overlay: λ = 0.75 ⇒ w = 0.75/0.25 = 3 against a lone base (others = 1).
+    // Fresh: λ = 0.75, so w = 0.75/0.25 = 3 against a lone base (others = 1).
     assert!((wound_weight(1.0, 1.0) - 3.0).abs() < 1e-5);
-    // Expired: λ = 0 ⇒ the overlay contributes nothing.
     assert_eq!(wound_weight(0.0, 1.0), 0.0);
-    // Monotone decay in between (smoothstep, no bounce).
+    // Monotone smoothstep decay in between.
     let mid = wound_weight(0.6, 1.0);
     let late = wound_weight(0.3, 1.0);
     assert!(wound_weight(1.0, 1.0) > mid && mid > late && late > 0.0);
-    // Same λ against a heavier subtree (base 1 + a live one-shot overlay 8): the anchor scales.
+    // The same λ against a heavier subtree (base 1 and a one-shot overlay 8) scales the weight.
     assert!((wound_weight(1.0, 9.0) - 27.0).abs() < 1e-4);
 }
 
 #[test]
 fn defense_anim_matches_the_byte_lut() {
-    // Decision 0279: the `0x60ec98` LUT read off WoW.exe — dagger parries 1H (unlike its swing),
-    // fist parries UNARMED (unlike its Ready), ranged/none bail; dodge/deflect/block are fixed.
+    // The `0x60ec98` LUT: dagger parries 1H (unlike its swing), fist unarmed (unlike its Ready),
+    // ranged or none bails; dodge, deflect and block are fixed.
     assert_eq!(defense_anim(2, None), Some(30)); // dodge needs no weapon
     assert_eq!(defense_anim(8, Some((2, 7))), Some(30)); // deflect → Dodge too
     assert_eq!(defense_anim(5, None), Some(24)); // block → ShieldBlock
@@ -864,8 +798,8 @@ fn swing_ids_cover_both_hands() {
 
 #[test]
 fn a_flying_spline_is_fly_before_backward_and_speed() {
-    // `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.
+    // `0x5fd19c`: the fly branch sits between swim and backward, so a 32 yd/s taxi plays Fly 135,
+    // never Sprint 143 or WalkBackwards.
     let fly = MovementState {
         flying: true,
         ..moving_forward(32.0)
@@ -876,7 +810,7 @@ fn a_flying_spline_is_fly_before_backward_and_speed() {
         ..fly
     };
     assert_eq!(gait_candidates(&fly_back, 2.5, None, None), &[135, 0]);
-    // A GROUNDED spline ride (charge) keeps the speed cascade.
+    // A grounded spline ride (Charge) keeps the speed cascade.
     assert_eq!(
         gait_candidates(&moving_forward(32.0), 2.5, None, None)[0],
         143
@@ -895,26 +829,21 @@ fn unify_stamps_flying_from_the_live_spline_on_every_leg() {
         grounded,
         run_mode: true,
     };
-    // Self leg: the controller's stored component says nothing about the ride — the live
-    // Spline does (the client reads the active CMovement's spline flags at select time).
+    // Self leg: the live spline says flying, not the stored state, as the client reads the
+    // spline flags at select time.
     let m = moving_forward(32.0);
     assert!(unify(Some(&m), None, Some(&spline(false)), false, None).flying);
     assert!(!unify(Some(&m), None, Some(&spline(true)), false, None).flying);
     assert!(!unify(Some(&m), None, None, false, None).flying);
-    // Spline leg (a remote taxi after the stale-RemoteMotion drop): flying + FORWARD + speed.
+    // Spline leg (a remote taxi): flying, FORWARD and a speed.
     let v = unify(None, None, Some(&spline(false)), false, None);
     assert!(v.flying && v.flags & move_flags::FORWARD != 0 && v.speed > 0.0);
 }
 
-/// **The server-granted modes reach the selector's flags word** (decision 1780). They are bits of
-/// the same `CMovement+0x40` word the selector already tests, so a creature the server has put in
-/// walk mode or rooted must read as one — the reference re-runs this very selector on the spot when
-/// the grant lands (`0x6014ec push edi; call 0x60e480`, then `push -1; call 0x5fd9e0`), which is
-/// what makes this opcode family a *visual* one rather than bookkeeping.
-///
-/// The self leg is deliberately exempt: our own mover's modes are the ack'd family's, already
-/// folded into the `MovementState` the controller writes. Reading them from a second place would be
-/// a second source of truth for one bit.
+/// Server-granted modes are bits of the `CMovement+0x40` word the selector tests, and the
+/// reference re-selects when a grant lands (`0x6014ec push edi; call 0x60e480`, then
+/// `push -1; call 0x5fd9e0`). Our own mover is exempt: its modes are the ack'd family's, already
+/// in its `MovementState`.
 #[test]
 fn the_granted_modes_fold_into_the_flags_word_on_every_leg_but_our_own() {
     use crate::net::UnitMoveModes;
@@ -923,7 +852,7 @@ fn the_granted_modes_fold_into_the_flags_word_on_every_leg_but_our_own() {
     let rooted = UnitMoveModes(move_flags::ROOT);
     let walking = UnitMoveModes(move_flags::WALK_MODE);
 
-    // Creature leg — a standing NPC the server has rooted.
+    // Creature leg: a standing NPC the server rooted.
     let v = unify(None, None, None, false, Some(&rooted));
     assert_eq!(v.flags & move_flags::ROOT, move_flags::ROOT);
 
@@ -944,7 +873,7 @@ fn the_granted_modes_fold_into_the_flags_word_on_every_leg_but_our_own() {
         "the walk grant does not displace the spline's own travel bit"
     );
 
-    // Remote leg — OR'd onto the pose's flags, never replacing them.
+    // Remote leg: OR'd onto the pose's flags.
     let rm = crate::net::RemoteMotion {
         wow_pos: [0.0; 3],
         pending: std::collections::VecDeque::new(),
@@ -962,7 +891,7 @@ fn the_granted_modes_fold_into_the_flags_word_on_every_leg_but_our_own() {
     let v = unify(None, Some(&rm), None, false, Some(&walking));
     assert_eq!(v.flags, move_flags::FORWARD | move_flags::WALK_MODE);
 
-    // Self leg — untouched.
+    // Self leg: untouched.
     let m = moving_forward(32.0);
     assert_eq!(
         unify(Some(&m), None, None, false, Some(&rooted)).flags,
@@ -971,8 +900,8 @@ fn the_granted_modes_fold_into_the_flags_word_on_every_leg_but_our_own() {
     );
 }
 
-/// 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.
+/// The creep (`0x5fd1d3`) precedes the whole speed tail (`0x5fd202`): a stealthed mover plays 119
+/// at any speed.
 #[test]
 fn the_prowl_creeps_at_every_speed() {
     for speed in [0.5, 3.0, 7.0, 32.0] {
@@ -992,7 +921,7 @@ fn the_prowl_creeps_at_every_speed() {
             "unstealthed at {speed} yd/s must fall through to the speed tail",
         );
     }
-    // …and it steps down to Walk on a model lacking the clip (AnimationData row 119's own Fallback).
+    // Walk is row 119's `AnimationData` fallback.
     let creeping = MovementState {
         stealthed: true,
         ..moving_forward(7.0)
@@ -1003,8 +932,7 @@ fn the_prowl_creeps_at_every_speed() {
     );
 }
 
-/// Swim, the flying spline and backward each precede the stealth branch in the byte cascade
-/// (swim → fly → backward → **stealth** → speed tail), so each still wins while stealthed.
+/// Swim, fly and backward precede the stealth branch in the cascade, so each wins while stealthed.
 #[test]
 fn swim_fly_and_backpedal_all_outrank_the_prowl() {
     let stealthed = |flags: u32, flying: bool| MovementState {
@@ -1034,9 +962,8 @@ fn swim_fly_and_backpedal_all_outrank_the_prowl() {
     );
 }
 
-/// The prowl idle (`0x5fd830`, last resolver in the chain) sits exactly where plain Stand sat: every
-/// resolver ahead of it — the chair stand-states, the turn shuffle, the combat Ready idle — keeps
-/// winning, and the state-emote idle may still fill the slot ([`is_bare_stand`]).
+/// The prowl idle is the chain's last resolver (`0x5fd830`): every other idle outranks it, and the
+/// state-emote idle may still fill its slot.
 #[test]
 fn the_prowl_idle_is_the_lowest_priority_stand() {
     let idle = MovementState {
@@ -1068,8 +995,7 @@ fn the_prowl_idle_is_the_lowest_priority_stand() {
     );
 }
 
-/// The creep is NOT in the client's locomotion-rate whitelist (`0x5fee80`), so unlike Walk it plays
-/// at 1× however fast the unit is actually travelling.
+/// The creep is not in the rate-scaled set (`0x5fee80`), so it plays at 1× at any speed.
 #[test]
 fn the_prowl_creep_is_not_rate_scaled() {
     assert_eq!(playback_rate(&clip(STEALTH_WALK, 2.5), 7.0, 1.0), 1.0);
diff --git a/crates/benilla-app/src/creature_anim/sheath.rs b/crates/benilla-app/src/creature_anim/sheath.rs
index def1aa47..5194e069 100644
--- a/crates/benilla-app/src/creature_anim/sheath.rs
+++ b/crates/benilla-app/src/creature_anim/sheath.rs
@@ -1,8 +1,5 @@
-//! The sheath **policy layer**'s types + ceremony mechanics (decision 0080): the one-setter
-//! request, the client-side state cache's visual pin, the draw/stow ceremony overlays, and the
-//! `AnimationData.dbc` policy table. The driver systems in [`super::driver`] execute these — the setter,
-//! the field-apply adopt, and the per-animation reconcile all live in `drive_animations`, so
-//! every sheath transition has exactly one author.
+//! Weapon sheath state: the one setter's request, the draw/stow ceremony overlays and the
+//! `AnimationData.dbc` weapon flags; `drive_animations` executes every transition.
 
 use benilla_assets::ModelAnimations;
 use benilla_formats::AnimDataCatalog;
@@ -12,21 +9,13 @@ use benilla_assets::{LockRecover, WorldAssets};
 
 use super::{find_resolved, select, AnimDriver, Wielded};
 
-/// Holds a unit's *visual* sheath state **per arm** while the draw/stow one-shots play, so each
-/// weapon model swaps hand↔hip/back at its own clip's authored `$SHL`/`$SHR` event (~the moment
-/// that hand reaches the stow point — 500/567 ms into the 1 s clips, dumped from HumanMale.m2)
-/// instead of the instant the state changes. Per-arm because the ceremony is: a warrior going
-/// melee → ranged stows both hands *and then* reaches for the bow, so the sword leaves the right
-/// hand a full clip before the bow arrives in the left. Removed when every arm has settled — the
-/// equipment resolver then falls through to the committed sheath state. Absent = no transition in
-/// flight. Index by [`ARM_RIGHT`]/[`ARM_LEFT`] — or by held slot, via [`Self::for_slot`].
+/// A unit's visual sheath state per arm while a draw/stow ceremony plays: each weapon moves at its
+/// own clip's `$SHL`/`$SHR` key, not when the state changes. Absent, the committed state rules.
 #[derive(Component, Clone, Copy)]
 pub(crate) struct VisualSheath(pub(crate) [u8; 2]);
 
 impl VisualSheath {
-    /// The effective sheath state governing one **held slot**'s placement: mainhand on the right
-    /// arm, offhand on the left, and the ranged item on whichever arm its `InventoryType` puts it
-    /// (the byte-verified `0x1a`/`0x19` compare — see [`ranged_arm`]).
+    /// The state placing one held slot: mainhand right, offhand left, ranged by [`ranged_arm`].
     pub(crate) fn for_slot(self, slot: usize, inv_type: u32) -> u8 {
         self.0[match slot {
             0 => ARM_RIGHT,
@@ -37,34 +26,27 @@ impl VisualSheath {
     }
 }
 
-/// One arm's leg of the ceremony in flight — a masked one-shot on that arm's subtree (the client's
-/// per-slot `0x60b770` plays on sub-sequence 3/2), composed over whatever the body is doing: walk,
-/// run, jump; never cancelled.
+/// A ceremony leg in flight: a masked one-shot on one arm over whatever the body does (`0x60b770`).
 pub(super) struct SheathArm {
     node: bevy::animation::graph::AnimationNodeIndex,
-    /// The authored `$SHL`/`$SHR` moment — when this arm's weapon actually moves.
+    /// The authored `$SHL`/`$SHR` time, when this arm's weapon moves.
     swap_at: f32,
-    /// This clip ends with the weapon **in the hand** — the client's `+0xd58` phase bit (see
-    /// [`ArmLeg::drawing`]). `false` = a stow, and the one thing phase 2 keys on.
+    /// The clip ends with the weapon in hand (the client's `+0xd58` phase bit); a stow is `false`.
     drawing: bool,
-    /// The held slot this leg moves: 0 mainhand · 1 offhand · 2 ranged.
+    /// The held slot this leg moves: 0 mainhand, 1 offhand, 2 ranged.
     slot: u8,
-    /// The clip has passed [`Self::swap_at`] — the weapon has moved, the sound has rung.
     crossed: bool,
 }
 
-/// The draw/stow ceremony in flight — up to one leg per arm, each advancing independently.
+/// The draw/stow ceremony in flight: up to one leg per arm, each advancing on its own.
 pub(super) struct SheathSwap {
     arms: [Option<SheathArm>; 2],
-    /// The state the ceremony left (the client's `+0xd3c` PREV): the pre-swap placement for a
-    /// stow leg, and phase 2's gate.
+    /// The state the ceremony left (the client's `+0xd3c` PREV); phase 2's gate.
     prev: u8,
 }
 
 impl SheathSwap {
-    /// The effective sheath state for one arm: a stow leg shows [`Self::prev`] until its weapon
-    /// moves and stowed (0) after; a draw leg shows stowed until its weapon arrives and the
-    /// committed state after; an arm with no leg is simply snapped.
+    /// The state one arm shows: its leg's side of the swap, or `cur` with no leg.
     fn arm_state(&self, arm: usize, cur: u8) -> u8 {
         match &self.arms[arm] {
             None => cur,
@@ -86,49 +68,27 @@ impl SheathSwap {
     }
 }
 
-/// The per-arm overlay's weight over the gait on the arm bones both key: the ceremony dominates the
-/// walk's arm-swing ≈ 8:1 (the client's per-bone arming gives it the arm outright; a small bleed is
-/// the cost of Bevy's weighted blend). Legs are excluded entirely by the mask.
+/// The ceremony's weight over the gait on the arm bones, about 8:1, where the client's per-bone
+/// arming gives it the arm outright.
 const SHEATH_OVERLAY_WEIGHT: f32 = 8.0;
 
-/// A request to change a unit's sheath state — benilla's analogue of the client's **one setter**
-/// `SetSheatheState(newState, bInstant, bFireEvent)` (`0x611cf0`, decision 0080 structure 1).
-/// Every path that changes the state funnels here — the manual Z toggle (the only `ceremony`
-/// 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. Across all 24 client call sites, **only the manual
-/// `ToggleSheath` passes `bInstant = 0`** — every reactive trigger and the server-field apply snap.
+/// A sheath state change, the client's one setter `SetSheatheState(newState, bInstant,
+/// bFireEvent)` (`0x611cf0`), which `drive_animations` executes. Of its 24 call sites only the
+/// manual `ToggleSheath` passes `bInstant = 0`: every other change snaps.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct SheathRequest {
     pub(crate) entity: Entity,
-    /// The requested state: 0 unarmed/stowed · 1 melee drawn · 2 ranged drawn.
+    /// The requested state: 0 stowed, 1 melee drawn, 2 ranged drawn.
     pub(crate) state: u8,
     /// Play the draw/stow ceremony (the manual toggle's `bInstant = 0`); everything else snaps.
     pub(crate) ceremony: bool,
 }
 
-/// 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; 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)
-///         else ranged worn         -> 2 ranged     (0x5eb699: push 1, ebx=0, 2)
-///         else                     -> no call      (0x5eb697: je 0x5eb6ad)
-/// CUR 1   ranged worn              -> 2 ranged     (0x5eb671)
-///         else                     -> 0 stowed     (0x5eb67f)
-/// CUR 2                            -> 0 stowed     (0x5eb653)
-/// ```
-///
-/// So the press walks **three** states — melee, then ranged, then stowed — never a two-state
-/// flip. `melee`/`ranged` are the ref's three `GetWeapon(0/1/2)` results (vtable `+0x98`, called
-/// at `0x5eb5f0`/`0x5eb600`/`0x5eb610`); ours are [`Wielded`]'s slots, carrying the same "an item
-/// is worn there" fact. **Named deviation:** the ref also zeroes its ranged candidate when the
-/// unit's class byte fails a `DAT_00c0def4` "can hold a ranged weapon" lookup
-/// (`0x5eb616`–`0x5eb640`, INFERRED semantics) — unobservable here, since a class that fails it
-/// cannot equip a ranged item to begin with.
+/// The state a Z press asks for next, or `None` where the reference makes no call (`ToggleSheath`,
+/// `0x5eb642`–`0x5eb6a8`, over the committed state `[unit+0xd40]`): melee, then ranged, then
+/// stowed, each gated on what is worn (`GetWeapon(0/1/2)` at `0x5eb5f0`–`0x5eb610`).
+/// Deviation: the class lookup that can also clear the ranged candidate (`0x5eb616`–`0x5eb640`,
+/// `0xc0def4`, meaning inferred) is skipped, because a class failing it cannot equip one.
 pub(crate) fn toggle_sheath_next(cur: u8, (melee, ranged): (bool, bool)) -> Option<u8> {
     match cur {
         0 if melee => Some(1),
@@ -136,31 +96,24 @@ pub(crate) fn toggle_sheath_next(cur: u8, (melee, ranged): (bool, bool)) -> Opti
         0 => None,
         1 if ranged => Some(2),
         1 | 2 => Some(0),
-        _ => None, // the ref's `dec ecx; jne` tail — no call for a state outside {0, 1, 2}
+        _ => None, // no call for a state outside {0, 1, 2} (the `dec ecx; jne` tail)
     }
 }
 
-/// One arm's leg of a draw/stow ceremony: the clip to play, and whether that arm ends with its
-/// weapon **in the hand**. `drawing` is the client's `+0xd58` per-arm phase bit — set by the
-/// drawers (`0x6118a0 |= 0x100000`, `0x611960 |= 0x200000`, `0x611a20 |= 0x300000`), cleared by
-/// every stow leg (`0x611b60`'s `& 0xffefffff` / `& 0xffdfffff`). Layer B reads it at the clip's
-/// `$SHL`/`$SHR` event to decide hand-vs-sheath-bone, which is exactly what it means here.
+/// One arm's planned leg: the clip, and whether the arm ends with its weapon in hand (the
+/// client's `+0xd58` phase bit, set by the drawers and cleared by the stows in `0x611b60`).
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) struct ArmLeg {
     pub(super) clip: u16,
     pub(super) drawing: bool,
 }
 
-/// Arm indices — the client's animation **sub-sequence** slots, which are per-arm: the mainhand
-/// plays on 3 (HandRight), the offhand on 2 (HandLeft), and the ranged weapon on whichever its
-/// `InventoryType` picks (bow ⇒ left, gun/crossbow/wand/thrown ⇒ right).
+/// Arm indices; the client plays the mainhand on sub-sequence 3, the offhand on 2.
 pub(super) const ARM_RIGHT: usize = 0;
 pub(super) const ARM_LEFT: usize = 1;
 
-/// Which arm the ranged weapon occupies, and whether one is worn at all. Byte-verified compare
-/// (`0x611c74`, `0x6118db`, `0x611998`, `0x611a9a` — identical at every site): `[+3] == 0x1a`
-/// (RANGEDRIGHT — gun/crossbow/wand) or `== 0x19` (THROWN) ⇒ the **right** arm; anything else
-/// (`0x0f`, INVTYPE_RANGED — a bow) ⇒ the **left**.
+/// The arm a worn ranged weapon occupies: `InventoryType` 0x1a (gun, crossbow, wand) or 0x19
+/// (thrown) the right, a bow (0x0f) the left (`0x611c74`, `0x6118db`, `0x611998`, `0x611a9a`).
 fn ranged_arm(w: &Wielded) -> Option<usize> {
     w.ranged.map(|_| {
         if matches!(w.ranged_inv, 0x1a | 0x19) {
@@ -171,14 +124,11 @@ fn ranged_arm(w: &Wielded) -> Option<usize> {
     })
 }
 
-/// The **draw** leg one arm would play for a committed state — the shared body of the client's
-/// two per-arm drawers (`0x6118a0` right, `0x611960` left) and of the both-arms `0x611a20`, all
-/// of which run the identical `(1 << (rec[+4] & 0x1f)) & 0x88` pick on the slot's own record.
-/// `None` = that arm has nothing to draw for this state, and is released to its idle.
+/// The draw leg one arm plays for a committed state, as the drawers `0x6118a0` (right),
+/// `0x611960` (left) and `0x611a20` (both) pick it; `None` releases the arm to its idle.
 fn draw_leg(arm: usize, cur: u8, w: &Wielded) -> Option<ArmLeg> {
     let (item, sheath) = match (cur, arm) {
-        // The drawers read `GetWeapon(slot, 0)` like the rest of the sheath machine (1863), so a
-        // disarmed hand has nothing to draw — the reference's `0x5eb480` takes its unarmed branch.
+        // The drawers read `GetWeapon(slot, 0)`: a disarmed hand has nothing to draw (`0x5eb480`).
         (1, ARM_RIGHT) => (w.armed_main(), w.main_sheath),
         (1, ARM_LEFT) => (w.armed_off(), w.off_sheath),
         // The ranged weapon draws on exactly one arm; the other has no leg at all.
@@ -191,43 +141,19 @@ fn draw_leg(arm: usize, cur: u8, w: &Wielded) -> Option<ArmLeg> {
     })
 }
 
-/// **Phase 2** — the deferred draw, and the half of the ceremony benilla never had. The client
-/// runs it from its **on-anim-finish** handler (`0x5fc920` @ `0x5fca62`–`0x5fcab6`): when a
-/// `0x59`/`0x5a` clip finishes on sub-sequence 2 or 3 and that arm's phase bit is still **clear**
-/// (i.e. what just finished was a *stow*), it calls that arm's drawer — `0x611960` @ `0x5fcaaf`
-/// for the left, `0x6118a0` @ `0x5fca9a` for the right; a bit already set falls through to
-/// `0x7121a0(subSeq, -1, …)`, releasing the arm to its idle. A leg here is the second full
-/// movement: the arms come back to neutral, and only *then* does a hand reach for the new weapon.
-///
-/// The `prev == 0` refusal is the drawers' own first test (`0x6118a5` / `0x611965`:
-/// `if (PREV == 0) return 0`) — a draw **out of the stowed state** is a single movement, already
-/// played in full by [`sheath_phase1`]'s `0x611a20` leg, so there is nothing left to defer.
+/// Phase 2, the deferred draw: when a stow clip (89/90) finishes on sub-sequence 2 or 3 with the
+/// arm's phase bit clear, the finish handler calls that arm's drawer (`0x5fc920` @
+/// `0x5fca62`–`0x5fcab6`: `0x611960` @ `0x5fcaaf` left, `0x6118a0` @ `0x5fca9a` right). The
+/// drawers refuse out of `prev == 0` (`0x6118a5`, `0x611965`), a draw phase 1 already played.
 pub(super) fn sheath_phase2(arm: usize, prev: u8, cur: u8, w: &Wielded) -> Option<ArmLeg> {
     (prev != 0).then(|| draw_leg(arm, cur, w)).flatten()
 }
 
-/// **Phase 1** — what the setter itself plays, keyed on **PREV** (the client's `0x611b60`, the
-/// `bInstant == 0` fork of `SetSheatheState`). Byte-read at `0x611b60`–`0x611ce6`:
-///
-/// ```text
-/// PREV 0  -> 0x611a20: draw BOTH arms for CUR now, set both bits — ONE movement
-/// PREV 1  -> right: mainhand worn ? stow it : the right drawer (0x6118a0)
-///            left : offhand  worn ? stow it : the left  drawer (0x611960)
-/// PREV 2  -> no ranged item  ? 0x611a20 (as PREV 0)
-///            bow (left arm)  : stow LEFT with a literal 89, right drawer (0x611c8c/0x611ca1)
-///            gun/xbow/thrown : stow RIGHT with a literal 89, left drawer (0x611cd3/0x611ce1)
-/// ```
-///
-/// So an arm with nothing to put away **draws immediately** — the ref's tail calls into the
-/// drawers — while an arm that does put something away defers its draw to [`sheath_phase2`]. A
-/// warrior with both hands full stows both, *then* reaches: two movements. A lone mainhand leaves
-/// the other arm free, so the draw rides along with the stow: one.
-///
-/// **Named byte detail:** the PREV==2 stow legs push a literal `0x59` rather than running the
-/// `& 0x88` pick (`0x611c8c`, `0x611cd3`), so a ranged weapon is always put away with Sheath 89
-/// even where its own sheath type would have picked HipSheath 90 on the way out.
+/// Phase 1, what the setter plays by PREV (`0x611b60`–`0x611ce6`, the `bInstant == 0` fork): out
+/// of stowed both arms draw at once (`0x611a20`); otherwise an arm holding something stows it and
+/// defers its draw to [`sheath_phase2`], and a free arm draws now. A ranged weapon always stows
+/// with a literal Sheath 89, never its own pick (`0x611c8c`, `0x611cd3`).
 pub(super) fn sheath_phase1(prev: u8, cur: u8, w: &Wielded) -> [Option<ArmLeg>; 2] {
-    /// The ranged **stow** clip — a literal, not a pick (see above).
     const RANGED_STOW: ArmLeg = ArmLeg {
         clip: 89,
         drawing: false,
@@ -239,8 +165,7 @@ pub(super) fn sheath_phase1(prev: u8, cur: u8, w: &Wielded) -> [Option<ArmLeg>;
         })
     };
     match prev {
-        // `LAB_00611ce6 -> 0x611a20`: nothing is in hand to put away, so both arms draw at once
-        // and no phase 2 can follow (the drawers' `PREV == 0` refusal).
+        // Nothing in hand to put away: both arms draw at once (`0x611ce6` to `0x611a20`).
         0 => [draw_leg(ARM_RIGHT, cur, w), draw_leg(ARM_LEFT, cur, w)],
         1 => [
             match w.armed_main() {
@@ -261,28 +186,23 @@ pub(super) fn sheath_phase1(prev: u8, cur: u8, w: &Wielded) -> [Option<ArmLeg>;
     }
 }
 
-/// One executed draw/stow swap at its hand-touches-weapon moment — fired only by the *ceremony*,
-/// **once per arm** as that arm's clip crosses its authored `$SHL`/`$SHR` event. Snap transitions
-/// never fire it: in the client the draw/stow sound rides the ceremony clip's own keyframes, and a
-/// `bInstant` path plays no clip — so snaps are silent (director-verified on the ref).
-/// `sound::sheathe` rings [`Self::slot`]'s item off it, so a two-movement melee→ranged toggle
-/// rings the swords going away and then, a clip later, the bow coming out.
+/// A ceremony arm crossing its `$SHL`/`$SHR` key, once per arm; `sound::sheathe` rings the slot's
+/// item off it. A snap plays no clip and so is silent, as in the reference.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct SheathSwapMessage {
     pub(crate) entity: Entity,
-    /// The held slot whose model just moved: 0 mainhand · 1 offhand · 2 ranged.
+    /// The held slot whose model just moved: 0 mainhand, 1 offhand, 2 ranged.
     pub(crate) slot: u8,
-    /// `true` = this arm drew its weapon; `false` = it put it away.
+    /// Whether this arm drew its weapon rather than putting it away.
     pub(crate) drawing: bool,
 }
 
-/// `AnimationData.dbc` policy rows — the WeaponFlags column driving the per-animation sheath
-/// reconcile (decision 0080 structure 3). Optional: absent (no client data) the reconcile
-/// degrades to the engaged-draw + the remote server-byte pull-through.
+/// `AnimationData.dbc`'s rows, whose WeaponFlags drive the per-animation sheath reconcile; absent,
+/// only the engaged draw and the remote server-byte pull apply.
 #[derive(Resource)]
 pub(crate) struct AnimData(pub(crate) benilla_formats::AnimDataCatalog);
 
-/// Load `AnimationData.dbc` off the patch chain at startup (the sound catalogs' pattern).
+/// Load `AnimationData.dbc` off the patch chain at startup.
 pub(super) fn load_anim_data(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let Some(assets) = assets else { return };
     let loaded = {
@@ -298,9 +218,7 @@ pub(super) fn load_anim_data(mut commands: Commands, assets: Option<Res<WorldAss
     }
 }
 
-/// Arm an [`ArmLeg`] as a live masked overlay on one arm's subtree: the clip resolved through the
-/// model's own baked fallback first (decision 0082), played over whatever the body is doing. `None`
-/// when the model has no such clip or no arm mask — that arm then simply snaps.
+/// Play an [`ArmLeg`] as a masked overlay on one arm; `None` (no clip or no arm mask) snaps it.
 fn arm_leg(
     arm: usize,
     leg: ArmLeg,
@@ -328,18 +246,13 @@ fn arm_leg(
             .map(|e| e.time)
             .unwrap_or(c.duration * 0.5),
         drawing: leg.drawing,
-        // The moving slot is the ranged one whenever the leg's own state is ranged; otherwise the
-        // arm *is* the slot (mainhand right, offhand left).
+        // A ranged state moves the ranged slot; otherwise the arm is the slot.
         slot: if state == 2 { 2 } else { arm as u8 },
         crossed: false,
     })
 }
 
-/// Start the draw/stow **ceremony** for a [`SheathRequest`] that asked for one (the manual
-/// toggle's `bInstant = 0`) — **phase 1** ([`sheath_phase1`], the client's `0x611b60`): each arm
-/// gets at most one masked overlay, and [`VisualSheath`] holds that arm's pre-swap placement until
-/// its clip reaches the authored `$SHL`/`$SHR` moment. An arm whose leg has no playable clip
-/// snaps; no arm playing anything at all → no ceremony, and the whole transition snaps.
+/// Start a requested ceremony's phase 1 ([`sheath_phase1`]); with no playable leg it all snaps.
 pub(super) fn start_sheath_ceremony(
     commands: &mut Commands,
     entity: Entity,
@@ -356,7 +269,7 @@ pub(super) fn start_sheath_ceremony(
     let mut arms: [Option<SheathArm>; 2] = [None, None];
     for (arm, leg) in legs.into_iter().enumerate() {
         let Some(leg) = leg else { continue };
-        // A stow leg moves what the OLD state had in that hand; a draw leg, what the new one will.
+        // A stow leg moves the old state's item; a draw leg, the new state's.
         let state = if leg.drawing { new_state } else { old_state };
         arms[arm] = arm_leg(arm, leg, state, player, anims, catalog);
     }
@@ -373,11 +286,8 @@ pub(super) fn start_sheath_ceremony(
     }
 }
 
-/// Advance a ceremony in flight: cross each arm's swap point (moving that arm's weapon and ringing
-/// it), and — the client's **phase 2** — when a *stow* clip finishes, hand that arm to
-/// [`sheath_phase2`] so it can reach for the new weapon. The ceremony ends when every arm has run
-/// out of legs, at which point [`VisualSheath`] is dropped and the resolver falls back to the
-/// committed state.
+/// Advance a ceremony: cross each arm's swap point, hand a finished stow to [`sheath_phase2`], and
+/// drop [`VisualSheath`] once no arm has a leg left.
 pub(super) fn advance_sheath_ceremony(
     commands: &mut Commands,
     entity: Entity,
@@ -398,8 +308,7 @@ pub(super) fn advance_sheath_ceremony(
         let Some(leg) = &mut swap.arms[arm] else {
             continue;
         };
-        // An overlay that vanished under us (a model rebuild) counts as finished — never leave a
-        // weapon pinned to a placement nothing is animating towards.
+        // An overlay lost to a model rebuild counts as finished.
         let (crossed, finished) = match player.animation(leg.node) {
             Some(a) => (a.seek_time() >= leg.swap_at, a.is_finished()),
             None => (true, true),
@@ -418,9 +327,8 @@ pub(super) fn advance_sheath_ceremony(
         }
         let (node, drawing) = (leg.node, leg.drawing);
         player.stop(node);
-        // **Phase 2** (`0x5fc920` @ `0x5fca8c`/`0x5fcaa1`): a finished *stow* — the phase bit still
-        // clear — hands this arm to its drawer. A finished draw (bit set) falls through to the
-        // arm's idle, exactly as the ref releases the sub-sequence with `0x7121a0(subSeq, -1, …)`.
+        // Phase 2 (`0x5fc920` @ `0x5fca8c`/`0x5fcaa1`): a finished stow hands the arm to its
+        // drawer; a finished draw releases it to its idle (`0x7121a0(subSeq, -1, …)`).
         swap.arms[arm] = (!drawing)
             .then(|| sheath_phase2(arm, prev, cur, &w))
             .flatten()
@@ -441,9 +349,6 @@ pub(super) fn advance_sheath_ceremony(
 mod tests {
     use super::*;
 
-    /// The `ToggleSheath` cycle exactly as the bytes branch (`0x5eb642`–`0x5eb6a8`): three states,
-    /// each leg gated on what is actually worn. The director's report — "Z should take out swords
-    /// then range then nothing" — is the first row.
     #[test]
     fn the_z_press_walks_melee_then_ranged_then_stowed() {
         const MELEE_AND_BOW: (bool, bool) = (true, true);
@@ -456,8 +361,7 @@ mod tests {
         assert_eq!(toggle_sheath_next(1, MELEE_AND_BOW), Some(2));
         assert_eq!(toggle_sheath_next(2, MELEE_AND_BOW), Some(0));
 
-        // No ranged weapon: the CUR=1 leg falls through to the stow (`0x5eb67f`) — the two-state
-        // flip, which is correct only here.
+        // No ranged weapon: CUR 1 falls through to the stow (`0x5eb67f`).
         assert_eq!(toggle_sheath_next(0, MELEE_ONLY), Some(1));
         assert_eq!(toggle_sheath_next(1, MELEE_ONLY), Some(0));
 
@@ -465,15 +369,13 @@ mod tests {
         assert_eq!(toggle_sheath_next(0, BOW_ONLY), Some(2));
         assert_eq!(toggle_sheath_next(2, BOW_ONLY), Some(0));
 
-        // Nothing worn at all: the ref makes no call (`0x5eb697: je 0x5eb6ad`) — the press is a
-        // silent no-op, not a draw of empty hands.
+        // Nothing worn: no call at all (`0x5eb697: je 0x5eb6ad`).
         assert_eq!(toggle_sheath_next(0, EMPTY), None);
         assert_eq!(toggle_sheath_next(1, EMPTY), Some(0));
         assert_eq!(toggle_sheath_next(2, EMPTY), Some(0));
     }
 
-    /// A sword-and-board warrior carrying a bow — the director's loadout. Sheath types: sword on
-    /// the hip (3 ⇒ HipSheath 90), shield on the back (4 ⇒ Sheath 89), bow on the back (1 ⇒ 89).
+    /// Sword, shield and bow: sheath types 3 (hip, 90), 4 (back, 89) and 1 (back, 89).
     fn warrior() -> Wielded {
         Wielded {
             main: Some((2, 7)),   // one-handed sword
@@ -482,7 +384,7 @@ mod tests {
             main_sheath: 3,
             off_sheath: 4,
             ranged_sheath: 1,
-            ranged_inv: 0x0f,     // INVTYPE_RANGED — the left arm
+            ranged_inv: 0x0f,     // INVTYPE_RANGED, the left arm
             materials: [1, 6, 2], // metal sword, plate shield, wood bow (real 5875 values)
             disarmed: false,
         }
@@ -505,30 +407,22 @@ mod tests {
         drawing: true,
     };
 
-    /// **The director's report, as a table.** Both hands full: a melee → ranged toggle puts the
-    /// sword and shield away and draws *nothing* — the bow waits for phase 2, which fires when
-    /// each stow clip finishes and reaches for it on the left arm alone. Byte-read at `0x611b60`
-    /// (phase 1) and `0x5fc920` @ `0x5fca8c`/`0x5fcaa1` (phase 2).
     #[test]
     fn a_full_pair_of_hands_stows_first_and_only_then_reaches_for_the_bow() {
         let w = warrior();
 
-        // Phase 1 of melee → ranged: two stows, no draw anywhere. This is movement one.
+        // Phase 1 of melee → ranged: two stows, no draw.
         assert_eq!(sheath_phase1(1, 2, &w), [Some(STOW_HIP), Some(STOW_BACK)]);
-        // Phase 2, once those finish: the right arm has nothing to draw for a bow and is released
-        // to its idle; the left reaches over the shoulder. Movement two.
+        // Phase 2: the right arm is released to its idle; the left draws the bow.
         assert_eq!(sheath_phase2(ARM_RIGHT, 1, 2, &w), None);
         assert_eq!(sheath_phase2(ARM_LEFT, 1, 2, &w), Some(DRAW_BACK));
 
-        // …and back the same way (the director's "that's how it puts it back too"): the bow is
-        // stowed with a LITERAL 89 (`0x611c8c`) rather than its own `& 0x88` pick, and the
-        // mainhand — whose hand is free — draws right away, while the shield waits for phase 2.
+        // Back: the bow stows with a literal 89 (`0x611c8c`), the free right hand draws at once,
+        // and the shield waits for phase 2.
         assert_eq!(sheath_phase1(2, 1, &w), [Some(DRAW_HIP), Some(STOW_BACK)]);
         assert_eq!(sheath_phase2(ARM_LEFT, 2, 1, &w), Some(DRAW_BACK));
     }
 
-    /// The one-movement cases, which must NOT grow a second phase: every draw out of the stowed
-    /// state (`0x611b60` → `0x611a20`, both bits set) and every stow into it.
     #[test]
     fn drawing_from_stowed_is_a_single_movement() {
         let w = warrior();
@@ -536,7 +430,7 @@ mod tests {
         // 0 → 1 draws both hands at once; 0 → 2 puts the bow in the left and leaves the right out.
         assert_eq!(sheath_phase1(0, 1, &w), [Some(DRAW_HIP), Some(DRAW_BACK)]);
         assert_eq!(sheath_phase1(0, 2, &w), [None, Some(DRAW_BACK)]);
-        // The drawers' own `if (PREV == 0) return 0` (`0x6118a5`/`0x611965`) — nothing deferred.
+        // The drawers' `if (PREV == 0) return 0` (`0x6118a5`/`0x611965`): nothing deferred.
         for arm in [ARM_RIGHT, ARM_LEFT] {
             assert_eq!(sheath_phase2(arm, 0, 1, &w), None);
             assert_eq!(sheath_phase2(arm, 0, 2, &w), None);
@@ -551,9 +445,7 @@ mod tests {
         }
     }
 
-    /// A lone mainhand leaves the other arm free, so its draw rides along with the stow — the ref
-    /// falls straight through `0x611b60`'s `if (oh != 0) … return` into `FUN_00611960`. One
-    /// movement, and the reason the two-phase shape only shows up with both hands occupied.
+    /// No offhand: the left arm draws during the right's stow (`0x611b60` into `0x611960`).
     #[test]
     fn a_free_hand_draws_without_waiting() {
         let w = Wielded {
@@ -562,8 +454,7 @@ mod tests {
         };
         assert_eq!(sheath_phase1(1, 2, &w), [Some(STOW_HIP), Some(DRAW_BACK)]);
 
-        // A gun sits on the RIGHT arm (`[+3] == 0x1a`), so the same loadout inverts: the mainhand
-        // must be put away first, and the gun's draw is what defers.
+        // A gun sits on the right arm (`[+3] == 0x1a`): the mainhand stows, the gun's draw defers.
         let g = Wielded {
             ranged_inv: 0x1a,
             ..w
diff --git a/crates/benilla-app/src/creature_anim/spell_visual.rs b/crates/benilla-app/src/creature_anim/spell_visual.rs
index 9da64e24..4874ffd4 100644
--- a/crates/benilla-app/src/creature_anim/spell_visual.rs
+++ b/crates/benilla-app/src/creature_anim/spell_visual.rs
@@ -1,9 +1,5 @@
-//! The spell-visual **data plane + cast-edge router** (decision 0099 phase 2; schemas and stage
-//! wiring pinned decision 0107): `SpellVisual.dbc` × `SpellVisualKit.dbc` loaded once at startup
-//! exactly like [`super::AnimData`], and [`route_cast_visuals`] — the one place spell ids resolve
-//! to animations/sounds. The wire side ([`super::CastEvent`], written by the net bridge) and the
-//! render side ([`super::CastHold`] + [`super::EmoteAnim`] one-shots, consumed by the driver)
-//! never touch the DBC chain themselves.
+//! The spell-visual data (`SpellVisual.dbc` × `SpellVisualKit.dbc`) and the cast-edge router, the
+//! one place spell ids resolve to animations, sounds and effect models.
 
 #[cfg(test)]
 mod tests;
@@ -26,45 +22,27 @@ use super::{
     BaseAnimRecompute, CastEvent, CastEventKind, CastHold, EmoteAnim, SpellGoTargets, WoundAnim,
 };
 
-/// The client's literal missile-model fallback when the visual chain resolves to nothing
-/// (`0x860c9c` — a checkerboard cube, shipped in the real MPQs; faithful, not a joke).
+/// The 1.12 client's missile model for an unresolvable visual (`0x860c9c`), shipped in the MPQs.
 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 — `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.
+/// The [`SpellKitFx`] reap key for the loot sparkle, outside the spell id range; the reference keys
+/// these nodes by attach tag and node flag (`0x61fa10`). A unit wears at most one.
 const LOOT_FX_KEY: u32 = u32::MAX;
 
-/// The M2 attachment the three engine-spawned effects we ship hang from — the loot sparkle, the
-/// level-up ding and the mount poof. It is also the `spell_fx` attach cascade's own last
-/// 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** (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.
+/// The attachment the loot sparkle, ding and mount poof hang from, else the unit base
+/// (`0x61fb4f`). A per-effect table value (`0x80c968`), not a constant: a new user reads its row.
 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`; decision 0305).
+/// The level-up effect's `SpellVisualEffectName` name (`0x8618e0`).
 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 (`0x5ffa50`
-/// pushes index 6 to `0x61fae0`; decision 0927).
+/// The mount cloud, hardcoded index 6: row 1185, the druid-morph puff (`0x5ffa50` → `0x61fae0`).
 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 `0x4ca2c7` with the same `Effect_C` shape as the mount poof
-/// (decision 1974).
+/// The meeting-stone join, hardcoded index 0xc (`0x861808`), spawned on the local player by the
+/// `SMSG 0x295` status-1 arm (`0x4ca2c7`).
 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 —
-/// `0x61fae0(kind = 0xc, &guid, completion = 0x5fbf50)`: one-shot, non-persistent, the
-/// end-of-clip terminator, attached at `0x13` like every `HARDCODED` effect.
+/// The meeting-stone join visual on `entity`: a one-shot at `0x13` (`0x61fae0`, `0x5fbf50`).
 pub(crate) fn meeting_stone_join_fx(visuals: &SpellVisuals, entity: Entity) -> Option<SpellKitFx> {
     let (effect, path) = visuals.0.hardcoded_effect(MEETING_STONE_JOIN_EFFECT)?;
     Some(SpellKitFx::Begin {
@@ -81,151 +59,92 @@ pub(crate) fn meeting_stone_join_fx(visuals: &SpellVisuals, entity: Entity) -> O
     })
 }
 
-/// `SpellVisual.dbc` × `SpellVisualKit.dbc` — the stage-kit chain + each kit's anim/sound
-/// (`crate::creature_anim::spell_visual` module docs). Optional like every other DBC-backed
-/// resource: absent (no client data) degrades to no spell-visual playback, same shape as
-/// [`super::AnimData`].
+/// `SpellVisual.dbc` × `SpellVisualKit.dbc`; absent without client data.
 #[derive(Resource)]
 pub(crate) struct SpellVisuals(pub(crate) SpellVisualCatalog);
 
-/// A spell-visual kit's sound edge (kit field 13 → `SoundEntries.dbc`, decision 0107 verdict
-/// C5-corrected: the kit's own sound column, rung at kit start). Written here, consumed by
-/// `crate::sound`. One message type so the consumer sees the edges **in emission order** — a
-/// GO's stop-then-release never races.
+/// A kit's sound edge (kit field 13 → `SoundEntries.dbc`), rung at kit start, consumed by
+/// `crate::sound` in emission order.
 #[derive(Message, Clone, Copy, Debug)]
 pub(crate) enum SpellKitSound {
-    /// Ring this kit at the unit. A LOOPING kit (`SoundEntries` flag 0x200) becomes the unit's
-    /// tracked **hold loop** — the client's looping-test split (`0x458830` → tracked `0x61fec0`
-    /// vs one-shot `0x458870`) — sustained until [`Self::StopHold`].
+    /// Ring this kit at the unit; a looping kit (`SoundEntries` flag 0x200) becomes the unit's
+    /// tracked hold loop until [`Self::StopHold`] (`0x458830` → `0x61fec0`, one-shot `0x458870`).
     Play { entity: Entity, kit_sound: u32 },
-    /// The cast/channel hold ended (GO / fail / channel-clear / a replacing cast) — reap the
-    /// unit's tracked hold loop, if any (the client kills the effect's sound at `0x614150`).
+    /// The cast or channel hold ended: stop the unit's hold loop (`0x614150`).
     StopHold { entity: Entity },
-    /// Ring this kit at a bare **world point**, with no owning unit — the kit-sound leg's
-    /// `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).
+    /// Ring this kit at a world point, the kit play's `extra` override (`0x60f49e`): a missile's
+    /// ground arrival. Always a one-shot: no shipped ground-arrival kit loops.
     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 (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.
+    /// Stop this kit's sound on the unit as its aura leaves (`0x614150`, 0.15 s fade).
     StopKit { entity: Entity, kit_sound: u32 },
 }
 
-/// A spell-visual kit's **camera shake** (kit field 14 → a `SpellEffectCameraShakes.dbc` group id,
-/// decision 1849). Written here, consumed by [`crate::camera_shake`], and deliberately shaped like
-/// [`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**. 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.
+/// A kit's camera shake (kit field 14 → `SpellEffectCameraShakes.dbc`), consumed by
+/// [`crate::camera_shake`]: once per kit play at every stage (`0x620e11`, or `0x60f4e6` with no
+/// node), never cancelled.
 #[derive(Message, Clone, Copy, Debug)]
 pub(crate) enum SpellKitShake {
-    /// Shake at the playing unit's own world position — the ordinary kit play.
+    /// At the unit's position.
     Play { entity: Entity, group: u32 },
-    /// Shake at a bare world point — the kit play's `extra` override (`0x60f4c1`'s `[ebx+0x14]`),
-    /// the same arm [`SpellKitSound::PlayAt`] serves: a missile's ground arrival belongs where it
-    /// landed, not at the thrower.
+    /// At a world point, the kit play's `extra` override (`0x60f4c1`): a missile's ground arrival.
     PlayAt { pos: Vec3, group: u32 },
 }
 
-/// A persistent effect instance's **lifetime class** — which owner's reap can kill it.
-/// 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.
+/// Which owner's reap can kill a persistent effect. The reference's reap `0x614150(spellId,
+/// force)` spares stage-2 nodes (flag `0x1000`) unless `force` is set, which only the aura-remove
+/// path does (`0x612320` → `0x5ff290`), so a cast's GO never takes the same spell's aura models.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum FxClass {
-    /// Cast-lifecycle instances: precast/channel holds (and every self-terminating flash, whose
-    /// class never matters — they die on their own clock). Reaped by the cast router's edges.
+    /// Precast and channel holds, reaped by the cast router's edges.
     Hold,
-    /// Aura-state instances (stage 2 under a live aura) — owned and reaped only by
-    /// [`arm_aura_state_fx`]'s slot watcher.
+    /// Stage 2 under a live aura, reaped only by [`arm_aura_state_fx`].
     AuraState,
 }
 
-/// 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`).
-///
-/// 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 stage its caller passes to `0x60edf0`.
+/// The kit stage an instance's model runs its animation lifecycle as: `0x60edf0`'s per-stage
+/// completion callback (jump table `0x60f4f8`). Independent of [`FxClass`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum FxStage {
-    /// Stages 0/1 (kit push, cast release, impact) — callback `0x5fbf50`: destroy at the first
-    /// completion. Already modelled by the instance's own span clock, so it arms no watcher.
+    /// Stages 0 and 1: destroyed at the first completion (`0x5fbf50`).
     OneShot,
-    /// Stage 2 (aura state, channel) — callback `0x5ff170`: when the birth sequence completes, arm
-    /// **`Hold` (158)** if the model authors one and re-arm it for the effect's life; the reap arms
-    /// **`Decay` (159)** and the instance lives out that span. A model with no `Hold` is left
-    /// parked on its birth — `0x5ff170` does nothing at all in that case.
+    /// Stage 2: after birth, loop `Hold` (158) if the model has one, `Decay` (159) on reap; a
+    /// model with no `Hold` stays parked on its birth (`0x5ff170`).
     State,
-    /// Stages 3/4 (precast) — callback `0x60ed00`: **re-arm the id that just completed, forever**,
-    /// with no `Hold` lookup, no deadline and no destroy. So a precast model whose birth sequence
-    /// clamps still repeats it, where a loop-flag-only arm would freeze.
+    /// Stages 3 and 4: re-arm the sequence that just completed, forever (`0x60ed00`).
     Relive,
 }
 
-/// One attach-point **effect model** a play hangs on a unit: the `SpellVisualEffectName`
-/// **record id**, the M2 attachment tag it hangs from, and the model path.
-///
-/// 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
-/// (`[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.
+/// One effect model a play hangs on a unit. Record id and tag are the reference's same-slot
+/// replace key: `AddEffect` (`0x61fdd0`) first destroys the owner's nodes with the same record at
+/// the same tag (`0x6208e0`), while two rows naming one `.mdx` coexist.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub(crate) struct FxSlot {
-    /// The M2 attachment id to hang from ([`benilla_formats::KIT_SLOT_TAGS`]), or
-    /// [`benilla_formats::WORLD_EFFECT_TAG`] for the field-12 world plant — the reference's
-    /// `tag == -1`, which `0x620913` excludes from the replace walk, so those genuinely stack.
+    /// The M2 attachment, or [`benilla_formats::WORLD_EFFECT_TAG`] for the field-12 world plant,
+    /// which the replace walk skips (`0x620913`).
     pub(crate) tag: u16,
-    /// The `SpellVisualEffectName` record id — the replace key's other half.
+    /// The `SpellVisualEffectName` record id.
     pub(crate) effect: u32,
-    /// The effect model's path (the model-cache key).
+    /// The model-cache key.
     pub(crate) path: String,
 }
 
-/// A spell-visual kit's attach-point **effect model** edge (kit fields 3–11 →
-/// `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.
+/// A kit's attach-point effect models (kit fields 3 to 11 → `SpellVisualEffectName`, slot loop
+/// `0x60f00d`), consumed by `crate::entities::spell_fx` in emission order.
 #[derive(Message, Clone)]
 pub(crate) enum SpellKitFx {
-    /// Attach this kit's effect models to the unit — one instance per populated slot
-    /// ([`FxSlot`]). `persistent` = the precast/channel/aura-state
-    /// lifetime (lives until a matching-[`FxClass`] [`Self::Reap`] — the client's stage-4/2
-    /// no-self-termination); else the effect self-terminates after one pass of its model's
-    /// first sequence (the stage-0/1 completion callback `0x5fbf50`). A persistent Begin
-    /// replaces the unit's live persistent instances of the same `(spell_id, class)`.
+    /// Attach the kit's models. A persistent one lives until a matching [`Self::Reap`] and
+    /// replaces the unit's live persistent instances of the same `(spell_id, class)`; otherwise
+    /// it ends after one pass of its first sequence (`0x5fbf50`).
     Begin {
         entity: Entity,
         spell_id: u32,
         persistent: bool,
         class: FxClass,
-        /// The kit stage this play is, which decides the instances' **animation lifecycle**
-        /// ([`FxStage`]) — a separate axis from `class`/`persistent`, both of which are about
-        /// lifetime ownership rather than what the model plays.
+        /// The models' animation lifecycle ([`FxStage`]).
         stage: FxStage,
         effects: Vec<FxSlot>,
     },
-    /// The owner's lifetime ended (GO / fail / channel-clear / a replacing cast for
-    /// [`FxClass::Hold`]; the aura leaving the slots for [`FxClass::AuraState`]) — despawn the
-    /// unit's **persistent** effects matching `(spell_id, class)` (the client's spell-id-keyed
-    /// reap `0x614150`; self-terminating instances run out on their own clock).
+    /// Despawn the unit's persistent effects matching `(spell_id, class)` (`0x614150`).
     Reap {
         entity: Entity,
         spell_id: u32,
@@ -233,79 +152,53 @@ pub(crate) enum SpellKitFx {
     },
 }
 
-/// A kit whose `CharProc` slots name a **beam** just played on `entity` — the client's CharProc
-/// dispatcher reaching its chain case (`0x60da79`, decision 0955). Written here for every kit play
-/// that carries one (the dispatcher runs at `PlaySpellVisualKit`'s tail, `0x60f35c`, and again from
-/// the channel poll, `0x612b18`); consumed by `crate::entities::chain_beam`, which owns the target
-/// selection against the caster's hop array, the beam's lifetime, and its geometry.
+/// A kit play whose `CharProc` slots name a beam, the dispatcher's chain case (`0x60da79`), run at
+/// the kit tail (`0x60f35c`) and from the channel poll (`0x612b18`). Consumed by
+/// `crate::entities::chain_beam`.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct ChainProcPlay {
-    /// The unit the kit played on — the beam's caster end, and the owner of the hop array.
+    /// The caster end, owner of the hop array.
     pub(crate) entity: Entity,
-    /// The kit's spell (`0` for a bare kit push, which the client's own `spellId != 0` guard at
-    /// `0x6ecbd0` refuses to build a beam for).
+    /// `0` for a bare kit push, which never builds a beam (`0x6ecbd0`).
     pub(crate) spell_id: u32,
     pub(crate) proc: benilla_formats::ChainProc,
 }
 
-/// Launch a projectile from `caster` at each target (decision 0099 phase 4) — one missile per
-/// target, the client's per-target spawn on the Speed>0 GO branch (`0x6e8a50 → 0x60a3d0`).
-/// Written here (the DBC columns resolve in this module, like every kit edge); consumed by
-/// `crate::entities::missile`, which owns launch/flight/arrival and writes the arrival back as
-/// [`super::CastEventKind::Impact`].
+/// One projectile per target on the GO's Speed > 0 branch (`0x6e8a50` → `0x60a3d0`), consumed
+/// by `crate::entities::missile`.
 #[derive(Message, Clone)]
 pub(crate) struct MissileSpawn {
     pub(crate) caster: Entity,
     pub(crate) spell_id: u32,
-    /// The projectile's model path (`SpellVisual` field 7 → `SpellVisualEffectName`, already
-    /// `.mdx`-form; the client's literal `Spells\ErrorCube.mdx` when a nonzero id is
-    /// unresolvable). `None` = the visual chain names no missile (field 7 < 1, or no
-    /// `SpellVisual` row at all — every basic shot spell): the spawner falls to the wire ammo
-    /// model (the client's `0x479f40` branch), phase 5.
+    /// `SpellVisual` field 7's model, or `ERROR_CUBE` for an unresolvable id; `None` when field
+    /// 7 is below 1 or there is no row, and the spawner flies the wire ammo model (`0x479f40`).
     pub(crate) path: Option<String>,
-    /// The GO's ammo block — the flying arrow/bullet/thrown model when [`Self::path`] is `None`.
+    /// The GO's ammo display, flown when [`Self::path`] is `None`.
     pub(crate) ammo_display_id: Option<u32>,
-    /// The M2 attach tag the missile homes to on a live target (`SpellVisual` field 9's ordinal
-    /// through [`benilla_formats::MISSILE_ATTACH_TABLE`], the client's `0x860a18`) — `None` for
-    /// an out-of-table ordinal (the target's base position, the client's `-1` sentinel path).
+    /// The attach tag the missile homes to (`SpellVisual` field 9 through
+    /// [`benilla_formats::MISSILE_ATTACH_TABLE`], `0x860a18`); `None` aims at the target's base.
     pub(crate) dest_tag: Option<u16>,
-    /// `Spell.dbc` Speed, world units/sec — travel time = launch distance / speed, then
-    /// arrive-on-time (the client's `0x61ceb0`).
+    /// `Spell.dbc` Speed; flight time is distance over speed (`0x61ceb0`).
     pub(crate) speed: f32,
-    /// `(target, miss)` — `None` landed (arrival plays the impact hand-off); `Some(code)` the
-    /// wire's `SpellMissInfo`: the missile still flies, and arrival plays the victim's defense
-    /// clip for DODGE(3)/BLOCK(5) instead (the client's `Missile_C::Update` dispatch).
+    /// `None` for a hit; for a miss the `SpellMissInfo`, where the missile still flies and arrival
+    /// plays the victim's dodge (3) or block (5) clip.
     pub(crate) targets: Vec<(Entity, Option<u8>)>,
-    /// The **location fallback**: when [`Self::targets`] is empty and the GO carried a ground
-    /// 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). 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.
+    /// With no targets and a DEST point on the GO, one projectile flies at the point (`0x6e8a50`'s
+    /// empty-hit arm, `0x6e8aa2`), arriving as [`super::CastEventKind::GroundImpact`].
+    /// The reference latches on `flags & 0x60` and aims a SOURCE-only cast at a zeroed DEST
+    /// point; this launches only with a real DEST (`flags & 0x40`), a zeroed aim being a quirk
+    /// not aped.
     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
-    /// resolves through it at arrival (the caster may be gone by then; decision 0370).
+    /// The caster's ranged fallback visual, carried to arrival when the caster may be gone.
     pub(crate) weapon_visual: Option<u32>,
-    /// `SpellVisual` field 10 → the `SoundEntries.dbc` id the projectile LOOPS while it travels
-    /// (the thrown weapon's `WeaponLoop`, the fireball's `FireMissileLoop`) — the client's
-    /// per-missile loop handle (`CMissile+0x44`). `None` = a silent flight.
+    /// `SpellVisual` field 10: the sound the projectile loops in flight (`CMissile+0x44`).
     pub(crate) missile_sound: Option<u32>,
-    /// Whether the launch **waits for the cast animation's release keyframe** — the client queues
-    /// every projectile on the caster (`unit+0xac`) and its GO handler flushes immediately only
-    /// when the cast kit plays no body animation (`0x6e7a70`: `castKit == 0 || kit anim < 1` →
-    /// `0x60c9b0`); otherwise the launch is the animation's `$CSL`/`$CSR`/`$CST`/`$BWR` event
-    /// (the dispatcher `0x5ffbd0` → `0x60c940`), from the fired marker's live position — the
-    /// fireball leaves the raised hand mid-throw, not the hold pose at GO.
+    /// Launch at the cast animation's release event (`0x5ffbd0` → `0x60c940`), not at GO; the
+    /// reference launches at GO only when the cast kit plays no body animation (`0x6e7a70`).
     pub(crate) awaits_release: bool,
 }
 
-/// Load `SpellVisual.dbc` + `SpellVisualKit.dbc` off the patch chain at startup (mirrors
-/// [`super::sheath::load_anim_data`]'s pattern exactly).
+/// Load `SpellVisual.dbc` and `SpellVisualKit.dbc` off the patch chain at startup.
 pub(super) fn load_spell_visuals(mut commands: Commands, assets: Option<Res<WorldAssets>>) {
     let Some(assets) = assets else { return };
     let loaded = {
@@ -325,32 +218,26 @@ 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
-/// (decision 0370).
+/// The lookups behind the ranged fallback (`0x60d450`): caster → ranged weapon display →
+/// `ItemDisplayInfo` column 10.
 #[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>>,
-    // `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.
+    // `Without<ItemObject>`: an item's store overlaps the unit indices, so a unit read of it
+    // answers item fields.
     units: Query<'w, 's, (Option<&'static NetEntity>, &'static ObjectStore), Without<ItemObject>>,
 }
 
 impl WeaponVisualSrc<'_, '_> {
-    /// The caster's equipped ranged weapon's SUBSTITUTE `SpellVisual` id (`vtable+0xa0(slot 2)`
-    /// → `ItemDisplayInfo` col 10). A creature carries the display id on the wire
-    /// (`UNIT_VIRTUAL_ITEM_SLOT_DISPLAY[2]`); a player resolves entry → template through the
-    /// ask-once item layer (cached by the time anything shoots — the equipped weapon already
-    /// rendered through it). `None` = no ranged weapon, or its display names no visual (every
-    /// non-ranged item).
+    /// The caster's ranged weapon's substitute `SpellVisual` id.
     fn caster(&mut self, caster: Entity) -> Option<u32> {
         let (net_entity, store) = self.units.get(caster).ok()?;
         let s = &store.0;
         let display_id = match net_entity?.kind {
             EntityKind::Unit => s.unit_virtual_item_display(2),
-            // 17 = vmangos EQUIPMENT_SLOT_RANGED (the equipment layer's PLAYER_HELD_SLOTS[2]).
+            // 17: vmangos `EQUIPMENT_SLOT_RANGED`.
             EntityKind::Player => s
                 .player_visible_item_entry(17)
                 .filter(|e| *e != 0)
@@ -369,19 +256,9 @@ impl WeaponVisualSrc<'_, '_> {
     }
 }
 
-/// A spell's effective `SpellVisual` row (spell → `Spell.dbc` column 115 → `SpellVisual.dbc`).
-/// `None` = a silent cast (no visual chain at all).
-///
-/// The one place the client's **ranged weapon-visual merge** applies (`0x60d450`; the law is
-/// [`VisualStages::merged_over_weapon`], byte-read there): a RANGED-attribute spell
-/// (`Attributes & 0x2`) takes the caster's equipped ranged weapon's substitute visual for every
-/// slot its **own** row leaves at zero — precast/cast/impact kits, the missile block, the strike
-/// sound; never state/channel. A basic shot (`SpellVisual1 = 0`) is only the degenerate case of
-/// that fill — the whole zeroed row comes across (Throw → ReadyThrown/AttackThrown, Auto Shot →
-/// LoadBow/AttackBow, wand Shoot → the gun kits), which is what decision 0370 read as the *whole*
-/// mechanism; every hunter shot spell has its own impact + missile row and empty body-anim slots,
-/// so it needs the per-field arm (decision 0986, bug B153). A non-ranged spell never pays the
-/// lookup (`FnOnce`).
+/// A spell's effective `SpellVisual` row (`Spell.dbc` column 115). A ranged spell
+/// (`Attributes & 0x2`) fills its row's zero slots, never state or channel, from the caster's
+/// ranged weapon visual (`0x60d450`); a basic shot has no row and takes it whole.
 fn resolve_stages(
     spells: &crate::ui_action::Spells,
     visuals: &SpellVisualCatalog,
@@ -391,20 +268,16 @@ fn resolve_stages(
     let def = spells.catalog.get(spell_id)?;
     let own = visuals.stages(def.visual).copied();
     if !def.ranged_slot() {
-        return own; // `ebx` stayed 0 at `60d468` — the fill block is a no-op
+        return own; // no fill (`0x60d468`)
     }
-    // `60d46e`–`60d4aa`: the caster's ranged display → `ItemDisplayInfo` col 10 → its row.
     let Some(weapon) = weapon_visual().and_then(|v| visuals.stages(v)) else {
         return own;
     };
-    // No own row = the client's `rep stosd` zeroed `outKit` before the same fill (`60d4bc`).
+    // No own row: the reference zeroes the row before the same fill (`0x60d4bc`).
     Some(own.unwrap_or_default().merged_over_weapon(weapon))
 }
 
-/// Resolve one lifecycle stage of `spell_id`'s visual chain to its kit (spell → `Spell.dbc`
-/// column 115 → `SpellVisual` stage column → `SpellVisualKit` row), via the given stage selector.
-/// `None` anywhere along the chain = that stage is silent for this spell (the common case — most
-/// spells populate only some stages). `weapon_visual` is [`resolve_stages`]'s ranged fallback.
+/// One stage's kit from `spell_id`'s visual chain.
 fn resolve_kit(
     spells: &crate::ui_action::Spells,
     visuals: &SpellVisualCatalog,
@@ -418,26 +291,8 @@ fn resolve_kit(
         .flatten()
 }
 
-/// [`resolve_kit`] plus this lane's **one trace line** (`WOW_MOVE_TRACE`, tag `fx`) — the
-/// instrument the cast-edge router went without until bug B307, where "does the shooter's body
-/// kit resolve at all?" cost a day and three agents to answer and this line answers in one live
-/// run.
-///
-/// It earns its place because of *how* this chain fails. A basic ranged shot — Auto Shot 75, wand
-/// Shoot 5019, Throw 2764 — carries `SpellVisual = 0`, so its **entire** body animation comes from
-/// the equipped ranged weapon's `ItemDisplayInfo` col-10 substitute visual ([`resolve_stages`]'s
-/// merge). Every link in that chain degrades **silently** to "no kit": an empty ranged slot, an
-/// item template the ask-once layer has not answered yet, a display id naming no visual. The
-/// observable of each is identical, and identical to a shooter that simply never animates — so
-/// the symptom names nothing and the code must. The line separates them:
-/// `weapon=not-consulted` (a non-ranged spell — the fallback is not supposed to run),
-/// `weapon=none` (it ran and found nothing — the shot IS silent, the B307 shape), or the
-/// resolved visual id, followed by the kit and the anim id actually requested of the body. Pair
-/// it with the driver's `fct: anim play unit=… id=…` to see whether that request reached bone 0.
-///
-/// Free when the trace is off: the caller's lookup still runs exactly once (the [`Cell`] only
-/// records what it returned), and the diagnosis re-derives only inside the `enabled()` guard —
-/// re-using the recorded value rather than re-running the lookup.
+/// [`resolve_kit`] plus one `fx` trace line saying why a basic shot's kit did or did not resolve:
+/// `weapon=not-consulted` (not ranged), `weapon=none` (no ranged visual) or the weapon visual id.
 fn resolve_kit_traced(
     stage_name: &str,
     entity: Entity,
@@ -447,8 +302,7 @@ fn resolve_kit_traced(
     stage: impl Fn(&VisualStages) -> u32,
     weapon_visual: impl FnOnce() -> Option<u32>,
 ) -> Option<VisualKit> {
-    // `None` = the closure never ran (`resolve_stages` short-circuits before the fallback for a
-    // non-ranged spell); `Some(v)` = it ran and returned `v`. The two are different diagnoses.
+    // `None`: the fallback never ran (a non-ranged spell); `Some(v)`: it ran and returned `v`.
     let consulted: Cell<Option<Option<u32>>> = Cell::new(None);
     let kit = resolve_kit(spells, visuals, spell_id, &stage, || {
         let visual = weapon_visual();
@@ -462,7 +316,7 @@ fn resolve_kit_traced(
             Some(None) => "none".to_string(),
             Some(Some(visual)) => visual.to_string(),
         };
-        // Re-derived from the RECORDED weapon visual — never a second lookup.
+        // Re-derived from the recorded weapon visual, never a second lookup.
         let kit_id = resolve_stages(spells, visuals, spell_id, || consulted.get().flatten())
             .map_or(0, |s| stage(&s));
         benilla_assets::trace::line(
@@ -479,13 +333,8 @@ fn resolve_kit_traced(
     kit
 }
 
-/// 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 (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).
+/// The in-flight cast's strike sound for the `$TRD` event (`0x62faa0`): `SpellVisual` dword 14
+/// (Mining's 1143 "Mining Impact"). No ranged fallback: `$TRD` rides work animations only.
 pub(crate) fn held_strike_sound(
     spells: &crate::ui_action::Spells,
     visuals: &SpellVisualCatalog,
@@ -494,9 +343,7 @@ pub(crate) fn held_strike_sound(
     resolve_stages(spells, visuals, spell_id, || None)?.strike_sound
 }
 
-/// A kit's populated emitter slots resolved to `(attach tag, model path)` pairs — the
-/// [`SpellKitFx::Begin`] payload. Slots whose `SpellVisualEffectName` row/path is missing are
-/// dropped (the client's NULL-record skip in the slot loop).
+/// A kit's populated effect slots; a slot with no `SpellVisualEffectName` path is skipped.
 fn resolve_kit_effects(visuals: &SpellVisualCatalog, kit: &VisualKit) -> Vec<FxSlot> {
     kit.effects()
         .filter_map(|(tag, effect)| {
@@ -509,23 +356,18 @@ fn resolve_kit_effects(visuals: &SpellVisualCatalog, kit: &VisualKit) -> Vec<FxS
         .collect()
 }
 
-/// A server-pushed kit outside any cast (`SMSG_PLAY_SPELL_VISUAL` → the net bridge; decision
-/// 0280): the client bounds-checks the u32 against `SpellVisualKit.dbc` and plays it at a
-/// hardcoded **stage 0** — the instant, self-terminating flavour (spellRec NULL, so its effects
-/// carry spell id 0 and are reaped only by their own completion, `0x6e98d0` → `0x60edf0`). Live
-/// traffic: the eat/drink kits (406/438) re-sent every ~5 s, and mid-channel kit swaps.
+/// A server-pushed kit (`SMSG_PLAY_SPELL_VISUAL`), played at stage 0 with spell id 0: its effects
+/// end only on their own (`0x6e98d0` → `0x60edf0`).
 #[derive(Message, Clone, Copy)]
 pub(crate) struct KitPush {
     pub(crate) entity: Entity,
     pub(crate) kit_id: u32,
-    /// [`super::PlaySeq`] stamp at emission (the wire drain, in packet order).
+    /// [`super::PlaySeq`] stamp at the wire drain, in packet order.
     pub(crate) seq: u64,
 }
 
-/// The lanes [`route_cast_visuals`] resolves here but does not own — bundled into ONE system
-/// param because that system sits at Bevy's 16-`SystemParam` ceiling: the missile spawns
-/// (phase 4), the dest one-shot orders (0797), the beam plays (0955), the camera shakes (1849)
-/// and the weapon-trail arms (2076). Each is built by the module that owns what it becomes.
+/// The kit lanes [`route_cast_visuals`] writes but does not own, bundled into one param because
+/// the system is at Bevy's 16-`SystemParam` limit.
 type KitSpawnWriters<'w> = (
     MessageWriter<'w, MissileSpawn>,
     MessageWriter<'w, crate::entities::dest_fx::GroundBurst>,
@@ -535,66 +377,41 @@ type KitSpawnWriters<'w> = (
     MessageWriter<'w, BaseAnimRecompute>,
 );
 
-/// The writer set one discrete kit play fans out to — bundled so [`play_kit`] threads through the
-/// router's arms as one argument (each writer keeps its own system-param lifetime).
+/// The writers one kit play fans out to.
 struct KitOut<'a, 'w1, 'w2, 'w3, 'w4, 'w5, 'w6, 'w7, 'w8> {
     oneshots: &'a mut MessageWriter<'w1, EmoteAnim>,
     wounds: &'a mut MessageWriter<'w2, WoundAnim>,
     sounds: &'a mut MessageWriter<'w3, SpellKitSound>,
     fx: &'a mut MessageWriter<'w4, SpellKitFx>,
-    /// The kit's beam, if its `CharProc` slots name one — the dispatcher's chain case (0955).
+    /// The kit's beam, the dispatcher's chain case.
     chain: &'a mut MessageWriter<'w5, ChainProcPlay>,
-    /// The kit's camera shake, if field 14 names a group (1849).
     shakes: &'a mut MessageWriter<'w6, SpellKitShake>,
-    /// The kit's weapon-trail ARM, if its `CharProc` slots name one — the dispatcher's type-8
-    /// case (2076). A latch, not a play: nothing is drawn until the unit's next animation.
+    /// The kit's weapon-trail arm (type-8 case), a latch drawn from the unit's next animation.
     trails: &'a mut MessageWriter<'w7, crate::weapon_trail::TrailArm>,
-    /// The **stage-2** base recompute — what a state kit's anim id spends itself on instead of
-    /// playing ([`BaseAnimRecompute`], decision 2085).
+    /// The base recompute a stage-2 kit's anim id spends itself on.
     recomputes: &'a mut MessageWriter<'w8, BaseAnimRecompute>,
 }
 
-/// One kit played as a **discrete event** on a unit — the client's `PlaySpellVisualKit`
-/// (`0x60edf0`): the kit's anim, sound, and attach-point effect models. The anim branch is the
-/// client's own (`0x60f3ad` → `0x60f510`): a CombatWound-family id (8–10) lays into the wound
-/// SECONDARY-blend slot (never interrupting what plays — decision 0111); anything else is the
-/// ordinary over-the-gait one-shot. `persistent` is the stage's effect-model lifetime
-/// (decision 0107 verdict 2).
-/// One kit play's fan-out policy — which legs run, per stage:
-/// - `persistent`: the effect models' lifetime (the precast/channel hold vs self-terminating).
-/// - `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** (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).
+/// One kit play's policy on the reference's `PlaySpellVisualKit` (`0x60edf0`):
+/// - `persistent`: the effect models outlive the play (a precast or channel hold).
+/// - `effects`: whether the models spawn; `false` for the impact hand-off's state stage, whose
+///   models [`arm_aura_state_fx`] owns.
+/// - `sound`: whether the kit sound rings; its leg has no self test at any stage.
 #[derive(Clone, Copy)]
 struct KitPlay {
     persistent: bool,
     effects: bool,
     sound: bool,
-    /// The stage this play is, for the instances' animation lifecycle ([`FxStage`]).
+    /// The models' animation lifecycle ([`FxStage`]).
     stage: FxStage,
-    /// Is this the **stage-2** (state-kit) play? It is the client's `0x60f383
-    /// cmp [ebx+0x10],2`, and it forks the whole anim branch — which is why it is the stage and
-    /// not, as it was until decision 2085, a "may this lay a wound" flag.
-    ///
-    /// 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`. 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
-    /// branch in benilla: a precast kit's anim becomes the [`CastHold`], not a `play_kit` call.
+    /// The stage-2 (state kit) play (`0x60f383`): `0x60f387` branches around the only anim play
+    /// (`0x60f3c5`), so the id is only compared with what the unit plays, a mismatch spent on a
+    /// [`BaseAnimRecompute`].
     stage_2: bool,
 }
 
 impl KitPlay {
-    /// The ordinary discrete play (kit push, cast release, impact stage): self-terminating
-    /// models, every leg on. Stages 0/1 both land here — they share `0x5fbf50`.
+    /// Stages 0 and 1 (`0x5fbf50`): self-terminating models, every leg on.
     const DISCRETE: Self = Self {
         persistent: false,
         effects: true,
@@ -615,11 +432,11 @@ fn play_kit(
 ) {
     if let Some(anim_id) = kit.anim_id {
         if play.stage_2 {
-            // Stage 2: a COMPARISON, never a play ([`KitPlay::stage_2`]). The driver holds the
-            // armed id, so it makes the comparison and spends the mismatch on the recompute.
+            // Stage 2 compares, never plays; the driver holds the armed id and compares.
             out.recomputes.write(BaseAnimRecompute { entity, anim_id });
         } else if (8..=10).contains(&anim_id) {
-            // `0x60f3b8: push 0; call 0x60ea70` — severity 0, the kit's own id is NOT what plays.
+            // A CombatWound id (8 to 10) lays a severity-0 wound in the blend slot, not the
+            // kit's own id (`0x60f3ad` → `0x60f510`, `0x60f3b8`).
             out.wounds.write(WoundAnim { entity });
         } else {
             out.oneshots.write(EmoteAnim {
@@ -632,18 +449,11 @@ fn play_kit(
     if let Some(kit_sound) = kit.sound.filter(|_| play.sound) {
         out.sounds.write(SpellKitSound::Play { entity, kit_sound });
     }
-    // The kit's CAMERA SHAKE (field 14, decision 1849) — once per play, at the unit, at every
-    // stage. Not gated by `play.sound` or `play.effects`: the reference's shake leg sits in the
-    // first-created node's arm pass with no stage test, and the no-node fallback is gated only on
-    // "nothing was created". A kit that spawns no models still shakes — 28 of the 58 shipped
-    // shake kits carry nothing but the shake.
+    // The camera shake plays at every stage, gated on nothing.
     if let Some(group) = kit.shake {
         out.shakes.write(SpellKitShake::Play { entity, group });
     }
-    // The CharProc dispatcher's beam case — run for EVERY kit play, at every stage, exactly as
-    // `PlaySpellVisualKit`'s tail runs it (`0x60f35c`). It is not gated by `play.effects`: the
-    // beam is not one of the kit's attach-point effect models, and a kit whose caster carries no
-    // hop array simply draws nothing (`0x60db01`'s `count == 0` exit).
+    // The beam case runs for every play at every stage (`0x60f35c`), ungated by `play.effects`.
     if let Some(proc) = kit.chain_proc() {
         out.chain.write(ChainProcPlay {
             entity,
@@ -651,12 +461,8 @@ fn play_kit(
             proc,
         });
     }
-    // …and its type-8 case (`0x60d80a`, decision 2076), run on the same terms and for the same
-    // reason: the arm is two words written on the UNIT, not one of the kit's attach-point models,
-    // so `play.effects` does not gate it. The dispatcher runs at `0x60f35c` *before* the kit's own
-    // animation is played at `0x60f3c5`, which is how a kit carrying both a proc-8 and an anim id
-    // fires its trail on its own swing — our `EmoteAnim` above and this arm both land before the
-    // driver reads either, so that self-fire falls out of the ordering rather than being arranged.
+    // The trail arm (`0x60d80a`), on the same terms; the reference dispatches it before the kit's
+    // anim (`0x60f3c5`), so a kit with both fires its trail on its own swing.
     if let Some(trail) = kit.trail_proc() {
         out.trails
             .write(crate::weapon_trail::TrailArm { entity, trail });
@@ -677,38 +483,21 @@ fn play_kit(
     }
 }
 
-/// One spell landing on one unit — [`play_impact`]'s per-impact inputs.
+/// One spell landing on one unit.
 #[derive(Clone, Copy)]
 struct ImpactPlay {
     spell_id: u32,
-    /// 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.
+    /// The caster's ranged fallback, resolved before the caster can vanish.
     weapon_visual: Option<u32>,
-    /// Lay the victim's severity-0 wound flinch beside the kit (decision 2058).
+    /// Lay the victim's severity-0 wound flinch beside the kit.
     flinch: bool,
     seq: u64,
 }
 
-/// The **unit-impact hand-off** (the client's `0x61dc50`, decision 0099 phase 4): the spell
-/// landed on `entity` — play the impact kit (stage 1), then the state kit (stage 2). The state
-/// 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** (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
-/// `0x6e8bf0` does it after the kit iff the spell targets enemies (`0x6ea280 == 2`,
-/// [`benilla_formats::SpellDisplay::is_harmful`]), the missile hand-off `0x61dc50` does it
-/// before the kit for every living target. The caller decides which; the driver picks
-/// CombatWound/StandWound by engagement and blends it as a decaying overlay over whatever plays.
-/// Order between the flinch and the kit's own wound branch is moot here: both are severity-0
-/// edges on the same entity in the same frame.
+/// The unit-impact hand-off (`0x61dc50`): the impact kit (stage 1), then the state kit's anim and
+/// sound, its models owned by [`arm_aura_state_fx`]. The stage-2 gate `0x61dc20` is not built: its
+/// content is untraced. The flinch comes after the kit for a harmful instant hit (`0x6e8bf0`),
+/// before it for every missile target.
 fn play_impact(
     entity: Entity,
     impact: ImpactPlay,
@@ -746,22 +535,15 @@ fn play_impact(
     }
 }
 
-/// The cast-edge router (decision 0107): wire [`CastEvent`]s + the public channel descriptor →
-/// the resolved animation intents the driver renders.
+/// The cast-edge router: wire [`CastEvent`]s and the public channel field → animation intents.
 ///
-/// - **Start** → the **precast** kit: its anim becomes the unit's [`CastHold`] (sustained until
-///   the cast resolves — the client's stage-4 persistence), its sound rings.
-/// - **Go** → the hold drops; the **cast** kit plays as a discrete event ([`play_kit`]), and the
-///   GO's target lists ([`SpellGoTargets`]) branch on `Spell.dbc` Speed — 0 → the impacts play
-///   inline ([`play_impact`] per hit, the client's instant branch `0x6e8bf0`); >0 → one
-///   [`MissileSpawn`] (the projectile branch `0x6e8a50 → 0x60a3d0`), whose arrivals come back as
-///   `Impact` events.
-/// - **Impact** → the spell landed on this unit (a missile arrival) — [`play_impact`].
-/// - **Fail** → the hold drops silently (the client's spell-id-keyed reap; no release).
-/// - **Channel** (polled per frame, the client's `0x612a30` over `UNIT_CHANNEL_SPELL` — observers
-///   have no packet, decision 0099): field set → the **channel** kit's anim as the hold + its
-///   sound once at start; field cleared → hold drops. The per-entity edge cache is the dedup the
-///   client gets from its per-tick armed-id guard — a held channel never restarts its clip.
+/// - Start: the precast kit's anim becomes the [`CastHold`] (stage 4) and its sound rings.
+/// - Go: the hold drops and the cast kit plays; the GO's targets play their impacts inline when
+///   `Spell.dbc` Speed is 0 (`0x6e8bf0`), else fly a [`MissileSpawn`] (`0x6e8a50`).
+/// - Impact: a missile arrived on this unit ([`play_impact`]).
+/// - Fail: the hold drops silently.
+/// - Channel: `UNIT_CHANNEL_SPELL` polled per frame (`0x612a30`); observers have no packet. A set
+///   field holds the channel kit's anim and rings its sound once, a cleared one drops it.
 pub(super) fn route_cast_visuals(
     mut commands: Commands,
     mut events: MessageReader<CastEvent>,
@@ -781,10 +563,9 @@ pub(super) fn route_cast_visuals(
     mut channel_cache: Local<EntityHashMap<u32>>,
 ) {
     let (Some(visuals), Some(spells)) = (visuals.as_deref(), spells.as_deref()) else {
-        return; // no client data — no spell visuals (every DBC resource degrades this way)
+        return; // no client data
     };
-    // Disjoint field borrows: the beam writer rides `out` for the whole body while the missile and
-    // burst writers stay free for the GO loop below.
+    // Disjoint borrows: the beam writer rides `out` while the missile and burst writers stay free.
     let (missiles, bursts, chains, shakes, trails, recomputes) = (
         &mut spawns.0,
         &mut spawns.1,
@@ -804,13 +585,8 @@ pub(super) fn route_cast_visuals(
         recomputes,
     };
 
-    // The `holds` query is one command-flush stale: an instant cast's START and GO drain from
-    // the wire in the same frame, so the GO's spell-id-keyed release must see the hold its own
-    // batch's START just inserted — through the query it can't, the remove is skipped, and the
-    // deferred insert lands unopposed: the cast pose loops forever (the Demon Armor / Ice Armor
-    // stuck cast; the real client's handlers run synchronously in packet order, so it has no
-    // such gap). `pending` overlays this frame's hold writes; every hold read goes through
-    // `held_spell`.
+    // `holds` lags one command flush and an instant cast's START and GO drain together, so
+    // `pending` overlays this frame's hold writes (else the cast pose sticks).
     let mut pending: EntityHashMap<Option<u32>> = EntityHashMap::default();
     let held_spell = |pending: &EntityHashMap<Option<u32>>, entity: Entity| -> Option<u32> {
         match pending.get(&entity) {
@@ -820,14 +596,8 @@ pub(super) fn route_cast_visuals(
     };
 
     for p in pushes.read() {
-        // The kit-push opcode (decision 0280, stage-0 semantics): fresh transient effects/sound
-        // on EVERY send, with no *kit-level* active-scan — while the body anim rides the driver's
-        // arm-level same-id dedup (`0x5fdba0`), so a looping eat/drink clip free-runs across the
-        // ~5 s resends instead of restarting.
-        //
-        // "No dedup" was too strong, and decision 2057 corrected it: there is no kit-level scan,
-        // but each SLOT still runs the same-(record, tag) replace (`0x6208e0`) on its way in, so
-        // the resend **swaps the old batch out** rather than piling a second jug on the first.
+        // No kit-level scan, but each slot's same-(record, tag) replace (`0x6208e0`) swaps the old
+        // batch out; the driver's same-id dedup (`0x5fdba0`) keeps a looping clip running.
         if let Some(kit) = visuals.0.kit(p.kit_id) {
             play_kit(
                 p.entity,
@@ -842,21 +612,14 @@ pub(super) fn route_cast_visuals(
     }
 
     for ev in events.read() {
-        // **The subject may already be dead** (B130's crash, the second ever reported): every
-        // despawn of an *indexed* unit runs inside the wire drain — `DESTROY_OBJECT`, the
-        // out-of-range stream-out, the worldport purge — and those commands are applied at the sync
-        // point this chain sits behind (`.after(WorldStage::Net)`), so a SPELL_START and its
-        // subject's death drain from the same batch and the edge outlives the unit. Every arm below
-        // is *about* that unit (its hold, its sound, its effect models), so a dead subject skips
-        // whole rather than spraying the downstream lanes with edges for an entity that is gone —
-        // and rather than warning once per component removed off a corpse.
+        // A despawn applied at the net sync point can outlive a cast edge from the same batch;
+        // skip a dead subject whole.
         if commands.get_entity(ev.entity).is_err() {
             continue;
         }
         match ev.kind {
             CastEventKind::Start => {
-                // A replacing cast reaps the prior hold's loop before its own sound starts —
-                // and the prior spell's persistent effect models, keyed by the hold it replaces.
+                // A replacing cast reaps the prior hold's loop and persistent models first.
                 out.sounds
                     .write(SpellKitSound::StopHold { entity: ev.entity });
                 if let Some(prior) = held_spell(&pending, ev.entity) {
@@ -866,13 +629,8 @@ pub(super) fn route_cast_visuals(
                         class: FxClass::Hold,
                     });
                 }
-                // A ranged-attribute shot arms the **ranged stance** the moment its START lands —
-                // the client's snap `SetSheatheState(2,1,1)` on the same gate (remote casters at
-                // `0x6e78f3`; the local player armed at cast-send `0x6e5930`, whose echo START
-                // lands a frame later — same look). One START per auto-repeat activation
-                // (VERIFIED, vmangos `Spell::prepare`: the per-shot re-casts are triggered and
-                // send only GO), and the executor's `newState == CUR` refusal makes any
-                // re-activation free.
+                // A ranged-attribute START draws the ranged weapon (`0x6e78f3`); vmangos sends
+                // START once per auto-repeat activation (`Spell.cpp:3448`).
                 if spells
                     .catalog
                     .get(ev.spell_id)
@@ -893,22 +651,14 @@ pub(super) fn route_cast_visuals(
                     |s| s.precast,
                     || weapon_src.caster(ev.entity),
                 ) {
-                    // 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.
+                    // The `0x400` weapon-visual hold: a ranged visual play sets it (`0x60d020`),
+                    // any other clears it (`0x6ec39e`); it keeps a remote shooter drawn.
                     let ranged = spells
                         .catalog
                         .get(ev.spell_id)
                         .is_some_and(|d| d.ranged_slot());
-                    // Fallible, like every hold write in this system: the skip above sees only
-                    // despawns already *applied*, and `model_fade::apply_despawn_fade` is
-                    // Update-unordered against this chain — its instant path (a stream-out unit with
-                    // no fadeable geometry, which is what a creature streamed in and back out at
-                    // flight speed *is*) can queue the despawn this frame and have it applied before
-                    // our commands. An infallible `insert` panics there; nothing can see it coming.
+                    // Fallible: `model_fade::apply_despawn_fade` is unordered against this chain
+                    // and can despawn the unit before these commands apply.
                     if ranged {
                         commands.entity(ev.entity).try_insert(super::RangedHold);
                     } else {
@@ -928,9 +678,7 @@ pub(super) fn route_cast_visuals(
                             kit_sound,
                         });
                     }
-                    // The precast's attach-point effect models (the glowing hands) — persistent,
-                    // the client's stage-4 lifetime: they live until the cast resolves, and their
-                    // animation re-arms forever ([`FxStage::Relive`], `0x60ed00`).
+                    // Persistent until the cast resolves, re-armed forever (stage 4).
                     let effects = resolve_kit_effects(&visuals.0, &kit);
                     if !effects.is_empty() {
                         out.fx.write(SpellKitFx::Begin {
@@ -945,15 +693,12 @@ pub(super) fn route_cast_visuals(
                 }
             }
             CastEventKind::Go => {
-                // Spell-id-keyed reap (the client's `0x614150(spellId, 0)`) — a proc's GO landing
-                // mid-cast never drops another spell's hold.
+                // Spell-id-keyed (`0x614150(spellId, 0)`): a proc's GO keeps another spell's hold.
                 if held_spell(&pending, ev.entity) == Some(ev.spell_id) {
                     commands.entity(ev.entity).try_remove::<CastHold>();
                     pending.insert(ev.entity, None);
                 }
-                // The release reaps the precast's loop unconditionally-of-hold-state: an instant
-                // cast's Start may have begun a loop even when its precast kit carried no anim
-                // (so no CastHold). The effect-model reap is the same shape, spell-id-keyed.
+                // Reaped whatever the hold: a precast kit with no anim still starts a loop.
                 out.sounds
                     .write(SpellKitSound::StopHold { entity: ev.entity });
                 out.fx.write(SpellKitFx::Reap {
@@ -961,11 +706,8 @@ pub(super) fn route_cast_visuals(
                     spell_id: ev.spell_id,
                     class: FxClass::Hold,
                 });
-                // 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}): 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.
+                // A ranged-slot GO redraws ranged before the cast kit (`0x60f34c`, gate
+                // `Attributes & 0x2`, stages 0 and 4): what redraws a bow an emote lowered.
                 if spells
                     .catalog
                     .get(ev.spell_id)
@@ -977,10 +719,7 @@ pub(super) fn route_cast_visuals(
                         ceremony: false,
                     });
                 }
-                // 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 `0x60d450`:
-                // Throw's AttackThrown, Auto Shot's AttackBow).
+                // For a basic shot the cast kit is the fire clip, from the ranged fallback.
                 if let Some(kit) = resolve_kit_traced(
                     "cast",
                     ev.entity,
@@ -990,9 +729,7 @@ pub(super) fn route_cast_visuals(
                     |s| s.cast,
                     || weapon_src.caster(ev.entity),
                 ) {
-                    // The `0x400` hold's per-shot re-assert (and the stale-visual clear for a
-                    // non-ranged play) — the Start arm's twin; every mid-volley GO keeps a
-                    // remote shooter's hold alive.
+                    // The `0x400` hold re-asserted per shot, or cleared for a non-ranged play.
                     if spells
                         .catalog
                         .get(ev.spell_id)
@@ -1014,11 +751,7 @@ pub(super) fn route_cast_visuals(
                 }
             }
             CastEventKind::Impact { weapon_visual } => {
-                // A missile arrived on this unit (decision 0099 phase 4; speed-0 impacts play
-                // inline from the GO loop below and never round-trip through here). The caster's
-                // ranged fallback rode the missile — resolve through it, not the target.
-                // `0x61dc50` @ `0x61dc74`: the arrival flinches every living target — no
-                // hostility test on this path (decision 2058).
+                // The arrival flinches every living target, no hostility test (`0x61dc74`).
                 play_impact(
                     ev.entity,
                     ImpactPlay {
@@ -1033,33 +766,14 @@ pub(super) fn route_cast_visuals(
                 );
             }
             CastEventKind::GroundImpact { pos } => {
-                // A missile arrived at a POINT (`0x61e1d0` → `0x61d870`, its no-live-target
-                // arm — see [`crate::creature_anim::CastEventKind::GroundImpact`]): play
-                // `SpellVisual` field 13 — the **area kit** — at stage 3 on the caster, with
-                // `extra` = the landing point. The reference then walks the missile's own
-                // server-recorded hit array (`CMissile+0x58/+0x5c`) for per-unit impact/state
-                // kits; ours is empty by construction — this arm is only reached because the
-                // GO's hit list was empty, which is what selected the location fallback.
-                //
-                // The kit legs, against the shipped data: all six `SpellVisual` rows that can
-                // reach here (Volley 3229, the bomb/dynamite family 1704/3270, Goblin Mortar
-                // 695, Arcane Bomb 4831, Firecrackers 6447 — the whole census of speed>0 ∧
-                // `Targets & 0x40` ∧ field 6 ≠ 0 ∧ field 13 ≠ 0) carry **no body animation and
-                // no effect slots, only a sound**. So the arrival is exactly the kit's field-13
-                // `SoundEntries` id at the landing point, and the anim/slot legs that would need
-                // stage 3's forever-relive lifetime ([`FxStage::Relive`]) are dead data here —
-                // left unbuilt rather than guessed at.
-                // `|| None`: the weapon merge pointedly skips the dest-anchored `+0x2c/+0x30/
-                // +0x34` block ([`VisualStages::merged_over_weapon`]), so even Volley's area kit
-                // is its own row's — the lookup would be paid for nothing.
+                // A missile arrived at a point (`0x61e1d0` → `0x61d870`): `SpellVisual` field 13,
+                // the area kit, plays at the landing point. Every shipped row that reaches here
+                // carries only a sound, so the anim and slot legs are not built.
                 let area = resolve_kit(spells, &visuals.0, ev.spell_id, |s| s.area_kit, || None);
                 if let Some(kit_sound) = area.and_then(|k| k.sound) {
                     out.sounds.write(SpellKitSound::PlayAt { pos, kit_sound });
                 }
-                // …and its shake, at the same landing point (1849). Unlike the sound this is NOT
-                // dead data on the reachable rows: kit 1285 (Cannon Ball, Bolt Charge Bramble,
-                // Kill Urok Minion) carries no anim, no sound and no slots — it is a camera shake
-                // and nothing else.
+                // Kit 1285 (Cannon Ball) is a shake and nothing else.
                 if let Some(group) = area.and_then(|k| k.shake) {
                     out.shakes.write(SpellKitShake::PlayAt { pos, group });
                 }
@@ -1080,26 +794,17 @@ pub(super) fn route_cast_visuals(
         }
     }
 
-    // The GO's target lists: `Spell.dbc` Speed picks the client's two GO branches — 0 → every
-    // hit's impact plays now (`0x6e8bf0`); >0 → a projectile per target (`0x6e8a50 → 0x60a3d0`),
-    // arrival routed back as `Impact` by `crate::entities::missile`. Misses fly too (the client
-    // deflects them off the target; ours fizzle silently — a named approximation).
+    // Speed 0 plays every impact now (`0x6e8bf0`), Speed > 0 flies one projectile per target.
+    // Misses fly too; the reference deflects them off the target, which is not built.
     for go in go_targets.read() {
         let Some(display) = spells.catalog.get(go.spell_id) else {
             continue;
         };
-        // The caster's ranged weapon visual, resolved once per GO (the client's `0x6e802e` call
-        // into `0x60d450`) — its merged row `edi` is what EVERY consumer below reads: the dest
-        // one-shot (`[edi+0x18]`/`[edi+0x30]`), the cast kit (`[edi+0x8]`), the inline impacts
-        // (`6e8169 mov edx,edi`) and the missile spawn (`6e8199 mov edx,edi`).
+        // Resolved once per GO (`0x6e802e`); every consumer below reads the merged row.
         let wv = weapon_src.caster(go.caster);
         let stages = resolve_stages(spells, &visuals.0, go.spell_id, || wv);
-        // The GO's dest one-shot (decision 0797, byte-pinned `0x6e8088`–`0x6e8143`): a
-        // dest-carrying GO plays the SpellVisual field-12 model ONCE at the packet's point —
-        // 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 (the burst precedes the object).
+        // The dest one-shot (`0x6e8088`): field 12's model once at the dest point when field 6 is
+        // 0, fired at GO whatever the hit list.
         if let Some(dest) = go.dest {
             if let Some(stages) = stages {
                 if stages.missile_gate == 0 && stages.area_effect != 0 {
@@ -1113,8 +818,7 @@ pub(super) fn route_cast_visuals(
             }
         }
         if display.speed <= 0.0 {
-            // `0x6e8bf0` @ `0x6e8c7b`–`0x6e8c89`: each hit target flinches after its impact kit
-            // iff the spell targets enemies (decision 2058).
+            // Each hit flinches after its impact kit iff the spell is harmful (`0x6e8c7b`).
             let flinch = display.is_harmful();
             for &target in &go.hits {
                 play_impact(
@@ -1131,11 +835,7 @@ pub(super) fn route_cast_visuals(
                 );
             }
         } else {
-            // The spawn gate is Speed **alone** (byte-pinned: `0x60a3d0` fires on the projectile
-            // gate's fcomp; every basic shot spell has no `SpellVisual` row at all and still
-            // flies). The missile-model chain: field 7 ≥ 1 → its effect model (the client's
-            // literal ErrorCube when unresolvable); < 1 / no visual row → `None`, and the
-            // spawner falls to the GO's wire ammo model (`0x479f40`, phase 5).
+            // The spawn gate is Speed alone (`0x60a3d0`): basic shots have no visual row.
             let path = stages.and_then(|s| {
                 (s.missile_model >= 1).then(|| {
                     visuals
@@ -1145,12 +845,9 @@ pub(super) fn route_cast_visuals(
                         .to_string()
                 })
             });
-            // Field 9's ordinal → the attach tag the missile homes to. An out-of-table ordinal
-            // reads adjacent `.rdata` in the client; here it degrades to the base position.
+            // An out-of-table ordinal reads adjacent `.rdata` in the reference; here, the base.
             let dest_tag =
                 stages.and_then(|s| MISSILE_ATTACH_TABLE.get(s.missile_attach as usize).copied());
-            // Field 10: the flight loop the projectile carries the whole way (thrown WeaponLoop,
-            // fireball FireMissileLoop) — resolved off the same row as the model/attach.
             let missile_sound = stages.and_then(|s| s.missile_sound);
             let targets: Vec<(Entity, Option<u8>)> = go
                 .hits
@@ -1158,15 +855,10 @@ pub(super) fn route_cast_visuals(
                 .map(|&e| (e, None))
                 .chain(go.misses.iter().map(|&(e, code)| (e, Some(code))))
                 .collect();
-            // The location fallback ([`MissileSpawn::ground_aim`]): an empty hit array plus a
-            // point on the wire flies ONE projectile at the point. The hit array wins whenever
-            // it has anything in it — the client only consults the latch after
-            // `0x6e8abc … je 0x6e8ba2` has found the array empty.
+            // Only an empty hit array consults the ground point (`0x6e8abc … je 0x6e8ba2`).
             let ground_aim = targets.is_empty().then_some(go.dest).flatten();
             if !targets.is_empty() || ground_aim.is_some() {
-                // The release gate (the client's `0x6e7a70` flush condition, inverted): a cast
-                // kit that plays a body animation defers the launch to its release keyframe;
-                // no kit / no anim (`kit+8 < 1` ⇔ our `anim_id: None`) launches at GO.
+                // The release gate (`0x6e7a70`, inverted).
                 let awaits_release = stages
                     .filter(|s| s.cast != 0)
                     .and_then(|s| visuals.0.kit(s.cast))
@@ -1188,10 +880,8 @@ pub(super) fn route_cast_visuals(
         }
     }
 
-    // The channel poll: an edge on the PUBLIC `UNIT_CHANNEL_SPELL` descriptor drives an observed
-    // unit's channel loop (the self-only MSG_CHANNEL_* never carry this — decision 0099). Only
-    // *edges* act, so a held channel's clip is started once (the client's dedup guard) and a
-    // cleared field releases the hold even when the interrupt had no other wire trace.
+    // The channel poll: `UNIT_CHANNEL_SPELL` edges drive an observed unit's channel (the self-only
+    // `MSG_CHANNEL_*` do not); a cleared field drops the hold even with no other wire trace.
     for (entity, store) in &units {
         let cur = store.0.unit_channel_spell();
         let prev = channel_cache.get(&entity).copied().unwrap_or(0);
@@ -1202,36 +892,29 @@ pub(super) fn route_cast_visuals(
         if cur != 0 {
             out.sounds.write(SpellKitSound::StopHold { entity });
             if prev != 0 {
-                // A channel replacing a channel: the old spell's effects reap first.
+                // A channel replacing a channel reaps the old spell's effects first.
                 out.fx.write(SpellKitFx::Reap {
                     entity,
                     spell_id: prev,
                     class: FxClass::Hold,
                 });
             }
-            // No ranged fallback here: the channel poll is the descriptor-driven `0x612a30`
-            // path, not the SPELL_START/GO handlers' `0x60d450` resolve — and no basic shot
-            // channels anyway.
+            // No ranged fallback on the channel poll (`0x612a30`).
             if let Some(kit) = resolve_kit(spells, &visuals.0, cur, |s| s.channel, || None) {
                 if let Some(anim_id) = kit.anim_id {
-                    // Fallible for the same reason as the wire arms above — and this loop's
-                    // subjects need it *more*: a unit mid-stream-out is un-indexed but still
-                    // carries its `ObjectStore`, so it is in this very query while the fade lane
-                    // is free to despawn it out from under us this frame.
+                    // Fallible: a unit mid-stream-out is un-indexed but still in this query.
                     commands.entity(entity).try_insert(CastHold {
                         anim_id,
                         spell_id: cur,
-                        ranged: false, // no basic shot channels (the comment above)
+                        ranged: false, // no basic shot channels
                     });
                     pending.insert(entity, Some(cur));
                 }
                 if let Some(kit_sound) = kit.sound {
                     out.sounds.write(SpellKitSound::Play { entity, kit_sound });
                 }
-                // The CharProc dispatcher's SECOND caller (`0x612b18`, inside this very poll
-                // `0x612a30`) — which is how a channelled beam exists at all: Drain Life's kit
-                // is never reached by `PlaySpellVisualKit`, only from here. Emitted on the
-                // channel's rising edge; the beam then lives until the field clears (0955).
+                // The CharProc dispatcher's second caller (`0x612b18`): Drain Life's beam is
+                // reached only here, on the rising edge, and lives until the field clears.
                 if let Some(proc) = kit.chain_proc() {
                     out.chain.write(ChainProcPlay {
                         entity,
@@ -1239,16 +922,12 @@ pub(super) fn route_cast_visuals(
                         proc,
                     });
                 }
-                // …and the type-8 arm from the same caller: kit 370 (Whirlwind Primer / Axe
-                // Flurry, a 10 000 ms trail) is reached at the CHANNEL stage and nowhere else,
-                // so without this leg the longest trail in the table never arms (2076).
+                // The trail arm from the same caller: kit 370 (Whirlwind Primer) is reached here.
                 if let Some(trail) = kit.trail_proc() {
                     out.trails
                         .write(crate::weapon_trail::TrailArm { entity, trail });
                 }
-                // The channel kit's effect models — persistent while the field holds (the
-                // client's stage-2 lifetime, and so the stage-2 Birth → Hold → Decay lifecycle:
-                // the channel poll `0x612a30` is one of the caller table's stage-2 sites).
+                // Persistent while the field holds, with the stage-2 lifecycle.
                 let effects = resolve_kit_effects(&visuals.0, &kit);
                 if !effects.is_empty() {
                     out.fx.write(SpellKitFx::Begin {
@@ -1263,8 +942,7 @@ pub(super) fn route_cast_visuals(
             }
         } else {
             if held_spell(&pending, entity) == Some(prev) {
-                // Only the ending channel's own hold is reaped — a precast for the unit's next
-                // spell (already in flight when the field clears) survives.
+                // Only the ending channel's own hold drops; an in-flight precast survives.
                 commands.entity(entity).try_remove::<CastHold>();
                 pending.insert(entity, None);
             }
@@ -1276,61 +954,25 @@ pub(super) fn route_cast_visuals(
             });
         }
     }
-    // Streamed units despawn on range-out; drop their stale edge-cache rows with them.
+    // Streamed units despawn on range-out; drop their cache rows.
     channel_cache.retain(|e, _| units.contains(*e));
 }
 
-/// Arm/reap the **aura state kit** (stage 2's real lifetime — the bread in the eater's hand):
-/// a spell id appearing in a unit's `UNIT_AURA` slots arms its state kit's effect models
-/// **persistent**, and the id leaving the slots reaps them. This is what makes the food bread
-/// (spell 433 → visual 51 → state kit 409 → `Spells\Item_Bread.mdx` at the spell hand) sit in
-/// the hand for the aura's whole life — and puts it in the hand of a unit that streamed in
-/// already eating (the slots are public), which no impact-time play can do. Closes the 0107
-/// approximation "the state kit plays self-terminating (no aura tracking yet)": [`play_impact`]
-/// 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: 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).
-/// An aura refresh keeps its slot id present (no edge); a re-apply that flickers remove→add
-/// across frames reaps then re-begins — the drain's replace-on-persistent-begin keeps even the
-/// same-frame corner single-instanced.
-/// A state kit has **two halves** and this watcher owns the slot diff for both: the attach-point
-/// effect *models* above, and the kit's `CharProc` columns — what the aura does to the body itself
-/// (its translucency, its tint), emitted as [`AuraProc`] edges for [`crate::aura_visual`]. One diff
-/// and one kit resolve feed both fan-outs, the same way [`KitOut`] bundles a discrete play's writers,
-/// so the two halves of a kit can never disagree about when an aura came or went.
-///
-/// **The arm predicate is "this kit does *anything*", not "this kit has effect models"** — B114 was
-/// exactly that bug: Stealth's kit 312 carries no models, no anim and no attach at all (its whole
-/// 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:
-/// 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.
+/// The reference's aura watch span (`0x604d00`, registered at `0x604226`): from
+/// `FIELD_UNIT_AURA`, 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;
 
+/// Arm and reap each aura's state kit (stage 2) off the unit's `UNIT_AURA` slots: a spell entering
+/// the slots begins its kit's models persistent, also on a unit streamed in mid-aura, and leaving
+/// reaps them (`0x604d00` → `0x5ff350`; remove `0x612320` → `0x614150(spellId, force=1)`). The add
+/// edge rings the kit sound ungated (`0x5ff4c6`) and never plays the kit's anim: stage 2 compares
+/// it with what the unit plays, a mismatch spent on a [`BaseAnimRecompute`]. `CharProc` columns go
+/// out as [`AuraProc`] edges, and a kit arms for any leg (Stealth's kit 312 is one `CharProc`).
+/// `armed` holds only the pairs this watcher began.
 pub(crate) fn arm_aura_state_fx(
-    // The slot diff below is a pure function of the store's aura fields, so it re-runs for a unit
-    // only when one of THOSE moved — the field edges inside the reference's own aura watch span
-    // (decision 2297; before that, any store write: at the LBRS pin ~800 full aura-slot walks per
-    // frame re-deriving an unchanged answer, most of them health ticks) — and on the unit's first
-    // 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.
+    // Re-run on an edge inside the aura watch span and on first sight (a standing aura is a
+    // state); the full sweep runs once per DBC-resource arrival.
     units: Query<(Entity, &ObjectStore), Without<ItemObject>>,
     arrived: Query<Entity, (Added<ObjectStore>, Without<ItemObject>)>,
     mut edges: MessageReader<FieldChanged>,
@@ -1345,7 +987,7 @@ pub(crate) fn arm_aura_state_fx(
     let full_sweep = visuals.as_ref().is_some_and(|v| v.is_changed())
         || spells.as_ref().is_some_and(|s| s.is_changed());
     let (Some(visuals), Some(spells)) = (visuals.as_deref(), spells.as_deref()) else {
-        return; // no client data — no spell visuals (the DBC-resource degrade shape)
+        return; // no client data
     };
     let scan = if full_sweep {
         units.iter().collect::<Vec<_>>()
@@ -1364,8 +1006,7 @@ pub(crate) fn arm_aura_state_fx(
     };
     for (entity, store) in scan {
         let prev = armed.entry(entity).or_default();
-        // Occupied slots, deduped (the same spell re-applied by two casters holds two slots —
-        // one state instance either way).
+        // Occupied slots, deduped: one state instance per spell however many casters hold it.
         let mut cur: Vec<u32> = store.0.unit_auras().map(|a| a.spell_id).collect();
         cur.sort_unstable();
         cur.dedup();
@@ -1377,8 +1018,7 @@ pub(crate) fn arm_aura_state_fx(
                     class: FxClass::AuraState,
                 });
                 procs.write(AuraProc::Reap { entity, spell_id });
-                // A LOOPING state-kit sound is a tracked hold that dies with the aura
-                // (`0x614150`'s 0.15 s fade — 0852); kit-scoped, a no-op for one-shots.
+                // A looping state-kit sound dies with the aura (`0x614150`, 0.15 s fade).
                 if let Some(kit_sound) =
                     resolve_kit(spells, &visuals.0, spell_id, |s| s.state, || None)
                         .and_then(|k| k.sound)
@@ -1390,11 +1030,11 @@ pub(crate) fn arm_aura_state_fx(
         let mut next = Vec::with_capacity(prev.len());
         for &spell_id in &cur {
             if prev.contains(&spell_id) {
-                next.push(spell_id); // already armed, aura still live
+                next.push(spell_id); // still armed
                 continue;
             }
             let Some(kit) = resolve_kit(spells, &visuals.0, spell_id, |s| s.state, || None) else {
-                continue; // no state kit — not this watcher's aura
+                continue; // no state kit
             };
             let effects = resolve_kit_effects(&visuals.0, &kit);
             let nodes: Vec<crate::aura_visual::AuraNode> = kit
@@ -1406,7 +1046,7 @@ pub(crate) fn arm_aura_state_fx(
                 && kit.sound.is_none()
                 && kit.anim_id.is_none()
             {
-                continue; // a state kit that does nothing we model — nothing to arm or reap
+                continue; // nothing to arm or reap
             }
             if !effects.is_empty() {
                 fx.write(SpellKitFx::Begin {
@@ -1425,20 +1065,12 @@ pub(crate) fn arm_aura_state_fx(
                     nodes,
                 });
             }
-            // The ADD edge rings the kit sound — ungated and positional (0852: the kit play's
-            // sound leg has no self test; the old self-only reading belonged to a different
-            // aura-apply cue). Covers the streamed-in-mid-aura unit no impact play can; the
-            // same-frame duplicate against the impact hand-off's state flash collapses in the
-            // sound router.
+            // Ungated; a same-frame duplicate of the impact hand-off's collapses downstream.
             if let Some(kit_sound) = kit.sound {
                 sounds.write(SpellKitSound::Play { entity, kit_sound });
             }
-            // …and the ADD edge's stage-2 leg: the kit's anim id is a COMPARISON against what the
-            // unit is already playing, spent on a base recompute when they differ and on nothing
-            // when they agree ([`BaseAnimRecompute`], decision 2085). It is emitted only on this
-            // edge, which is the reference's own shape: an aura REFRESHED in place rewrites its
-            // slot with the same id and a non-zero flags nibble, and `0x604d00` fires neither of
-            // its two arms for that — no re-spawn, no re-arm, no recompute.
+            // The stage-2 anim leg, on the add edge only: an aura refreshed in place keeps its id,
+            // and `0x604d00` fires neither arm.
             if let Some(anim_id) = kit.anim_id {
                 recomputes.write(BaseAnimRecompute { entity, anim_id });
             }
@@ -1446,33 +1078,16 @@ pub(crate) fn arm_aura_state_fx(
         }
         *prev = next;
     }
-    // Streamed units despawn on range-out; their instances die with the entity — drop the rows.
+    // Streamed units despawn on range-out; drop their rows.
     armed.retain(|e, _| units.contains(*e));
 }
 
-/// 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)
-/// attached at `0x13` — the unit's looping its own first sequence, the corpse's arming no sequence
-/// at all (the divergence is named at the `stage` line below). The real client is edge-driven off the
-/// descriptor apply (watcher `0x600440`) with **no viewer/tap/distance/loot-window logic** — the
-/// server already strips the flag per viewer (vmangos's "hide lootable animation for unallowed
-/// players"). The falling edge (looted empty, rights lost) reaps with no fade (`0x600680`);
-/// a despawn tears the instance down with the unit. Rides the spell-kit fx plumbing under
-/// [`LOOT_FX_KEY`] — the client hangs loot art on the same `Effect_C` node type its spell
-/// visuals use, so sharing the one attach body is the faithful shape.
+/// Arm and reap the loot sparkle on a dead lootable unit and on a corpse object with
+/// `CORPSE_FIELD_DYNAMIC_FLAGS` bit 0 (`0x5d6de0`): the `"HARDCODED Loot Art"` row at `0x13`.
+/// Edge-driven (`0x600440`) with no viewer or distance logic, since the server strips the flag per
+/// viewer; the falling edge reaps with no fade (`0x600680`).
 pub(super) fn arm_loot_fx(
-    // Dead+lootable is a pure function of four store fields, so a unit is re-read on a field
-    // edge on any of them and on first sight (a body that streams in lootable wears the sparkle —
-    // the reference arms it at build, `0x5d6e30`, and re-arms off the field's own mirror handler),
-    // with the same one-shot full sweep as `arm_aura_state_fx` when the DBC resource lands after
-    // units already streamed in (decision 2297). `NetEntity` splits the two predicates: a **unit**
-    // answers `UNIT_DYNFLAG_LOOTABLE`, a **corpse object** answers its own
-    // `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.
+    // Re-read on an edge of any of the four fields and on first sight (armed at build, `0x5d6e30`).
     units: Query<(Entity, &ObjectStore, &crate::net::NetEntity)>,
     arrived: Query<Entity, (Added<ObjectStore>, Without<ItemObject>)>,
     mut edges: MessageReader<FieldChanged>,
@@ -1483,7 +1098,7 @@ pub(super) fn arm_loot_fx(
 ) {
     let full_sweep = visuals.as_ref().is_some_and(|v| v.is_changed());
     let Some((effect, path)) = visuals.as_ref().and_then(|v| v.0.loot_art_effect()) else {
-        return; // no client data / no such row — no loot art (the DBC-resource degrade shape)
+        return; // no client data or no such row
     };
     let scan = if full_sweep {
         units.iter().collect::<Vec<_>>()
@@ -1508,17 +1123,14 @@ 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: `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.
+        // A corpse object's sparkle: bit 0 rising calls `0x5d6e30`, the same row at the same tag.
         let lootable = if net.kind == benilla_protocol::EntityKind::Corpse {
             store.0.corpse_lootable()
         } else {
             store.0.unit_is_dead() && store.0.unit_lootable()
         };
         if lootable && armed.insert(entity) {
-            // `OnDynamicFlagsChanged`'s rise (`0x60049b`): the Looting tutorial (1976).
+            // The Looting tutorial on the rise (`0x60049b`).
             if let Some(t) = tutorials.as_mut() {
                 t.write(crate::tutorial::TutorialEvent::trigger(
                     crate::tutorial::id::LOOTING,
@@ -1529,20 +1141,9 @@ pub(super) fn arm_loot_fx(
                 spell_id: LOOT_FX_KEY,
                 persistent: true,
                 class: FxClass::Hold,
-                // Not a kit stage at all (this is `SpawnHardcodedEffect`, not
-                // `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
-                // loot art is an `Effect_C` node with a clip-end re-arm loop — "its own first
-                // sequence, LOOPING", which is what `Relive` renders. The corpse's is a **bare
-                // model instance**: `0x5d6e30` arms no sequence and registers no callback at all
-                // (`[model+0x80]` stays `-1`), so the `.m2`'s emitters are the entire look and
-                // nothing re-arms them. `OneShot` + `persistent` is the nearest shape this
-                // plumbing expresses — no watcher, no re-arm, and it lives until the flag falls.
-                // Named rather than smoothed over: if a lootable bone pile is ever seen sparkling
-                // on a loop where the reference's plays out and stops, this is the line.
+                // A unit's loot art loops its first sequence (`0x600640`). A corpse's is a bare
+                // model with no sequence armed (`0x5d6e30`); this plumbing has no such instance, so
+                // it runs `OneShot` persistent.
                 stage: if net.kind == benilla_protocol::EntityKind::Corpse {
                     FxStage::OneShot
                 } else {
@@ -1562,21 +1163,13 @@ pub(super) fn arm_loot_fx(
             });
         }
     }
-    // Streamed units despawn on range-out; their instances die with the entity — drop the rows.
+    // Streamed units despawn on range-out; drop their rows.
     armed.retain(|e| units.contains(*e));
 }
 
-/// 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
-/// `SMSG_LEVELUP_INFO`, so anyone leveling nearby flashes too. A unit that streams in
-/// *carrying* a level didn't just gain one — and the field-edge stream is create-suppressed, so
-/// that needs no memory here (decision 2297; this was the first `Local<EntityHashMap>` shadow
-/// to go). The instance self-terminates on its own 1.867 s clip (spell id 0, the kit-push
-/// stage-0 shape — no reap key needed, unlike the persistent loot sparkle above), and its
-/// **sound is the model's own** `$SND(888)` event → `Sound\Spells\LevelUp.wav`, fired by
-/// `crate::entities::spell_fx`'s event-track scanner.
+/// The level-up ding: any streamed unit's `UNIT_FIELD_LEVEL` change (`0x6045b0`) spawns
+/// [`LEVEL_UP_EFFECT`], independent of `SMSG_LEVELUP_INFO`; a unit streaming in does not ding. Its
+/// sound is the model's own `$SND` event.
 pub(super) fn arm_level_up_fx(
     mut edges: MessageReader<FieldChanged>,
     visuals: Option<Res<SpellVisuals>>,
@@ -1590,7 +1183,7 @@ pub(super) fn arm_level_up_fx(
             .as_ref()
             .and_then(|v| v.0.hardcoded_effect(LEVEL_UP_EFFECT))
         else {
-            continue; // no client data / no such row (the DBC-resource degrade shape)
+            continue; // no client data or no such row
         };
         debug!(
             "anim: level {} → {}, the ding flashes ({})",
@@ -1601,7 +1194,7 @@ pub(super) fn arm_level_up_fx(
             spell_id: 0,
             persistent: false,
             class: FxClass::Hold,
-            // The ding self-terminates on its own 1.867 s clip — the stage-0 shape.
+            // Self-terminates on its own 1.867 s clip.
             stage: FxStage::OneShot,
             effects: vec![FxSlot {
                 tag: HARDCODED_FX_ATTACH,
@@ -1612,45 +1205,17 @@ pub(super) fn arm_level_up_fx(
     }
 }
 
-/// The **mount poof** — the cloud the director reports seeing at mount-up and we never drew.
-///
-/// The reference's `UNIT_FIELD_MOUNTDISPLAYID` change-watcher (`0x604329` → `0x604570` →
-/// `0x5ffa50`) does three things on its **build** leg, and only there: tear down any old mount
-/// (`0x607ce0`, gated on the OLD value), build the new one (`0x607a00`), and then spawn a
-/// `HARDCODED` effect — `SMemAlloc(0x90)` → `Effect_C` ctor `0x61f490` → `0x61fae0(index=6,
-/// &ownerGUID, cb=0x5fbf50)` → `0x6210e0` (`5ffa90`–`5ffad9`). Index **6** resolves through the
-/// 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 (decision 0927).
-///
-/// 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.
-/// - **Any unit.** No active-player, local-player or distance gate exists anywhere in `0x5ffa50`
-///   — the same shape as the level-up ding. Range is the server's replication, not a filter.
-/// - **One-shot, on the rider's own body.** `[node+0x2c] = 0` (no world-plant, no dedup marker,
-///   not cancel-immune), tag `0x13` re-resolved against `[owner+0xd8]` every tick, and the
-///   registered callback is `0x5fbf50` — the CEffect *end-of-clip terminator* (its looping twin
-///   `0x600640` is what makes the loot sparkle repeat). So: `FxStage::OneShot`, non-persistent,
-///   2.8 s of its own clock. Because the rider's body is the mount's child at slot 0 (0917), the
-///   cloud rides the saddle for its whole span with no extra plumbing.
-///
-/// **Stated divergence.** The reference's tail `0x6208e0` is a same-record+same-tag dedup that
-/// destroys a still-running poof when a new one spawns on that unit; our one-shot instances carry
-/// no reap key, so a mount *swap* inside 2.8 s would show two overlapping clouds. Unreachable
-/// today (the mounted gate refuses a second mount spell) and bounded at "one extra puff", so it
-/// is named rather than modelled.
+/// The mount poof: a `UNIT_FIELD_MOUNTDISPLAYID` change to nonzero on any unit spawns
+/// [`MOUNT_POOF_EFFECT`] on the rider as a one-shot (`0x604570` → `0x5ffa50`, gated at `0x5ffa87`).
+/// The same-record, same-tag replace (`0x6208e0`) is not built, so a mount swap within 2.8 s would
+/// show two clouds.
 pub(super) fn arm_mount_poof_fx(
     mut edges: MessageReader<FieldChanged>,
     visuals: Option<Res<SpellVisuals>>,
     mut fx: MessageWriter<SpellKitFx>,
 ) {
     for e in edges.read() {
-        // The build leg's gate is on the NEW value, so a dismount (`new == 0`) spawns nothing —
-        // and a unit that streams in already mounted did not just mount, which the
-        // create-suppressed edge stream says for us, exactly as for the ding (2297).
+        // A dismount spawns nothing; the edge stream skips creation.
         if !e.unit_field(benilla_protocol::field::FIELD_UNIT_MOUNTDISPLAYID) || e.new == 0 {
             continue;
         }
@@ -1658,7 +1223,7 @@ pub(super) fn arm_mount_poof_fx(
             .as_ref()
             .and_then(|v| v.0.hardcoded_effect(MOUNT_POOF_EFFECT))
         else {
-            continue; // no client data / no such row (the DBC-resource degrade shape)
+            continue; // no client data or no such row
         };
         debug!(
             "anim: mount display {} → {}, the poof puffs ({})",
@@ -1669,7 +1234,7 @@ pub(super) fn arm_mount_poof_fx(
             spell_id: 0,
             persistent: false,
             class: FxClass::Hold,
-            // `0x5fbf50` — destroy at the first completion; the shipped model runs 2.8 s.
+            // `0x5fbf50`: destroyed at first completion; the shipped model runs 2.8 s.
             stage: FxStage::OneShot,
             effects: vec![FxSlot {
                 tag: HARDCODED_FX_ATTACH,
@@ -1680,25 +1245,15 @@ pub(super) fn arm_mount_poof_fx(
     }
 }
 
-/// 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, `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
-/// the unit ([`arm_morph_latch`]'s sweep).
+/// The pending-morph latch, the reference's `[unit+0xd54]`: armed by `0x5ff0c0` on every aura add
+/// and remove of an [`is_morph_spell`] spell; the display rebuild `0x60abe0` replays its impact kit
+/// (`0x60ad67`), the shapeshift cloud both ways. Shift-out works because the aura fields apply
+/// before `DISPLAYID`.
 #[derive(Resource, Default)]
 pub(crate) struct MorphLatch(EntityHashMap<u32>);
 
-/// The latch-arm predicate `0x5ff100`: any effect slot with `Effect == 6` (APPLY_AURA) whose
-/// `EffectApplyAuraName` is 36 (MOD_SHAPESHIFT) or 56 (TRANSFORM) — slot-paired, and NO other
-/// gate (no class/positive/unit-type test anywhere in `0x5ff0c0`).
+/// The latch-arm predicate (`0x5ff100`): an effect slot with `Effect` 6 (APPLY_AURA) whose aura is
+/// 36 (MOD_SHAPESHIFT) or 56 (TRANSFORM), slot-paired, with no other gate.
 fn is_morph_spell(spells: &crate::ui_action::Spells, spell_id: u32) -> bool {
     const SPELL_EFFECT_APPLY_AURA: u32 = 6;
     const SPELL_AURA_MOD_SHAPESHIFT: u32 = 36;
@@ -1711,14 +1266,9 @@ fn is_morph_spell(spells: &crate::ui_action::Spells, spell_id: u32) -> bool {
     })
 }
 
-/// Arm [`MorphLatch`] from the aura-slot edges — the reference's TWO arm sites folded into the
-/// one place benilla sees both: the aura-add watcher and the aura-remove handler's tail
-/// (`0x6123ad`) both call `0x5ff0c0(spellId)`, and a later arm overwrites an earlier one (one
-/// slot). Each `UNIT_FIELD_AURA` slot edge is one dword of `0x604d00`'s watch (decision 2297):
-/// its old spell is a REMOVE arm, its new spell an ADD arm — remove first, add second, so a
-/// form→form swap in one slot latches the form being ENTERED (both resolve to the same cloud
-/// family regardless). A unit's first sight emits no edge, so a druid streaming in mid-form does
-/// not latch — the reference's watchers fire on VALUES deltas, never on create.
+/// Arm [`MorphLatch`] from aura-slot edges, as the add watcher and the remove tail (`0x6123ad`)
+/// both call `0x5ff0c0`: old spell first, new second, so a form swap latches the form entered.
+/// First sight emits no edge, as the reference's watchers fire on deltas only.
 pub(super) fn arm_morph_latch(
     units: Query<(), With<ObjectStore>>,
     mut edges: MessageReader<FieldChanged>,
@@ -1743,21 +1293,13 @@ pub(super) fn arm_morph_latch(
             }
         }
     }
-    // Streamed units despawn on range-out — the latch dies with them.
+    // The latch dies with a despawned unit.
     latch.0.retain(|e, _| units.contains(*e));
 }
 
-/// 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
-/// it tears the visual down — the message crosses to the next frame, so the replay's instance
-/// spawns onto (or pends for) the rebuilt body, never the corpse of the old one. Named
-/// approximation: the reference's same-record+same-tag dedup `0x6208e0` is not modelled, so a
-/// cold-cache shift-in — whose SPELL_GO impact instance was still PENDING at the drain and thus
-/// survived — briefly runs that instance and the replay's twin together (one denser cloud, once
-/// per session per model; the warm-cache GO instance dies in the drain like the reference's).
+/// The rebuild's impact-kit replay (the tail of `0x60abe0`): a display swap with the latch armed
+/// plays the latched impact kit and clears it, a frame later on the rebuilt body. The same-record,
+/// same-tag replace (`0x6208e0`) is not built, so a cold-cache shift-in briefly shows two clouds.
 pub(super) fn replay_morph_kit(
     mut swaps: MessageReader<crate::entities::DisplaySwapped>,
     visuals: Option<Res<SpellVisuals>>,
@@ -1774,16 +1316,15 @@ pub(super) fn replay_morph_kit(
     mut recomputes: MessageWriter<BaseAnimRecompute>,
 ) {
     for swap in swaps.read() {
-        // Consume-and-clear even when the kit resolves to nothing — the reference clears
-        // unconditionally at `0x60ad6c`.
+        // Cleared even when the kit resolves to nothing (`0x60ad6c`).
         let Some(spell_id) = latch.0.remove(&swap.entity) else {
-            continue; // no latch — a GM morph / revive swap plays nothing
+            continue; // no latch
         };
         let (Some(visuals), Some(spells)) = (visuals.as_deref(), spells.as_deref()) else {
-            continue; // no client data — no spell visuals (the DBC-resource degrade shape)
+            continue; // no client data
         };
         let Some(kit) = resolve_kit(spells, &visuals.0, spell_id, |s| s.impact, || None) else {
-            continue; // a morph spell with no impact kit — a silent swap
+            continue; // no impact kit
         };
         debug!("anim: morph replay ({}, spell {spell_id})", swap.entity);
         let mut out = KitOut {
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 e24f1ed9..105ad105 100644
--- a/crates/benilla-app/src/creature_anim/spell_visual/tests.rs
+++ b/crates/benilla-app/src/creature_anim/spell_visual/tests.rs
@@ -1,9 +1,5 @@
-//! Headless integration tests for [`super::route_cast_visuals`] — the cast-edge router run in a
-//! minimal app over a synthetic visual chain. First tenant: the instant-cast hold release. An
-//! instant cast's START and GO drain from the wire in the same frame, so the GO's spell-id-keyed
-//! release must see the hold its own batch's START inserted through deferred `commands` — the
-//! stale-query miss left Demon Armor / Ice Armor casters looping the cast pose forever (the
-//! director's stuck-cast report, 2026-07-13).
+//! Headless tests for the cast-edge router [`super::route_cast_visuals`] and the aura and mount
+//! watchers, over synthetic visual chains and, where an install is present, the shipped tables.
 
 use std::collections::HashMap;
 
@@ -20,15 +16,13 @@ use super::{
 };
 use crate::creature_anim::SpellGoTargets;
 
-/// Demon Armor's real chain shape (5875 `spellvis 706`): visual 130 → precast kit 217, anim 52 —
-/// an instant self-buff whose precast kit carries a sustained cast anim.
+/// Demon Armor's shipped chain: visual 130 → precast kit 217 with anim 52, an instant self-buff.
 const SPELL: u32 = 706;
 const VISUAL: u32 = 130;
 const PRECAST_KIT: u32 = 217;
 const HOLD_ANIM: u16 = 52;
 
-/// A ranged-slot spell with its own chain (an Aimed-Shot shape: `Attributes & 0x2` + a real
-/// visual whose cast kit plays the fire clip) — the `0x400` hold tests' subject.
+/// A ranged-slot spell (`Attributes & 0x2`) whose own visual's cast kit plays the fire clip.
 const RANGED_SPELL: u32 = 19434;
 const RANGED_VISUAL: u32 = 3180;
 const RANGED_CAST_KIT: u32 = 900;
@@ -99,7 +93,7 @@ fn app() -> App {
                 RANGED_SPELL,
                 SpellDisplay {
                     visual: RANGED_VISUAL,
-                    attributes: 0x2, // USES_RANGED_SLOT — the `0x400` hold's gate
+                    attributes: 0x2, // USES_RANGED_SLOT, the `0x400` hold's gate
                     ..Default::default()
                 },
             ),
@@ -126,7 +120,6 @@ fn hold(app: &App, unit: Entity) -> Option<u32> {
     })
 }
 
-/// The timed-cast lifecycle: START arms the precast hold, the (later-frame) GO releases it.
 #[test]
 fn timed_cast_hold_arms_and_releases_across_frames() {
     let mut app = app();
@@ -143,8 +136,8 @@ fn timed_cast_hold_arms_and_releases_across_frames() {
     assert_eq!(hold(&app, unit), None, "GO releases it");
 }
 
-/// The instant-cast regression: START and GO in the SAME frame (one wire drain) — the GO must see
-/// the hold its own batch inserted, or it leaks and the cast pose loops forever.
+/// An instant cast's START and GO drain in one frame: the GO must see the hold its own batch
+/// inserted, or the hold leaks and the cast pose loops forever.
 #[test]
 fn same_frame_start_and_go_leave_no_hold() {
     let mut app = app();
@@ -162,14 +155,12 @@ fn same_frame_start_and_go_leave_no_hold() {
     );
 }
 
-/// The spell-id key survives the overlay: a different spell's GO landing mid-cast (a proc) never
-/// drops the held cast — across frames or within one.
+/// The hold is keyed by spell id, so a proc's GO never drops it, in the same frame or later.
 #[test]
 fn a_foreign_go_never_drops_the_hold() {
     let mut app = app();
     let unit = app.world_mut().spawn_empty().id();
 
-    // Same frame as the START (the proc-during-instant shape) …
     app.world_mut()
         .write_message(cast_event(unit, SPELL, CastEventKind::Start));
     app.world_mut()
@@ -181,17 +172,14 @@ fn a_foreign_go_never_drops_the_hold() {
         "same-frame foreign GO ignored"
     );
 
-    // … and a frame later (the classic mid-cast proc).
     app.world_mut()
         .write_message(cast_event(unit, 999, CastEventKind::Go));
     app.update();
     assert_eq!(hold(&app, unit), Some(SPELL), "later foreign GO ignored");
 }
 
-/// The precast kit's own sound (kit field 13) rings at START — the gathering shape: Herb
-/// Gathering's real chain (5875 `spellvis 2366`: visual 91 → precast kit 64, anim 123
-/// "UseStandingLoop", sound 1104 "Gather_Herb"). The hold arms AND the kit-sound edge fires
-/// once; the GO releasing the hold emits no second play.
+/// The precast kit's sound (kit field 13) rings once at START, not again at GO. Herb Gathering's
+/// shipped chain: visual 91 → precast kit 64, anim 123 (UseStandingLoop), sound 1104 (Gather_Herb).
 #[test]
 fn precast_kit_sound_rings_once_at_start() {
     const HERB: u32 = 2366;
@@ -281,9 +269,8 @@ fn precast_kit_sound_rings_once_at_start() {
     );
 }
 
-/// The `$TRD` resolver ([`super::held_strike_sound`]): the held spell's `SpellVisual` field-14
-/// strike sound (decision 0562) — Mining's real shape (visual 93 → 1143 "Mining Impact") rings;
-/// a visual without the field (Fireball's 67 shape) and an unknown spell stay `None`.
+/// The `$TRD` strike sound is the held spell's `SpellVisual` field 14: Mining's visual 93 names
+/// 1143 (Mining Impact), Fireball's visual 67 none.
 #[test]
 fn held_strike_sound_reads_the_visuals_field_14() {
     const MINING: u32 = 2575;
@@ -335,7 +322,6 @@ fn held_strike_sound_reads_the_visuals_field_14() {
     assert_eq!(super::held_strike_sound(&spells, &visuals, 999), None);
 }
 
-/// A same-frame START→FAIL (an instant refusal) releases like the GO path.
 #[test]
 fn same_frame_start_and_fail_leave_no_hold() {
     let mut app = app();
@@ -349,18 +335,15 @@ fn same_frame_start_and_fail_leave_no_hold() {
     assert_eq!(hold(&app, unit), None, "the failed cast's hold is released");
 }
 
-/// The ranged weapon-visual MERGE (`0x60d450`, decision 0986 correcting 0370's row-level
-/// reading), on [`super::resolve_stages`] directly: a RANGED-attribute spell (`Attributes & 0x2`)
-/// fills every ZERO slot of its own row from the caster's weapon visual — so a basic shot with no
-/// row at all takes the lot, a hunter shot keeps its impact/missile and gains the body kits, and a
-/// non-ranged spell never looks.
+/// The ranged weapon-visual merge (`0x60d450`): a spell with `Attributes & 0x2` fills every zero
+/// slot of its own row from the caster's weapon visual; a non-ranged spell never looks.
 #[test]
 fn ranged_spells_merge_the_weapon_visual_into_their_empty_slots() {
-    const THROW: u32 = 2764; // Attributes 0x410012, SpellVisual1 0 — the real Throw shape
+    const THROW: u32 = 2764; // Attributes 0x410012, SpellVisual1 0: the shipped Throw row
     const FIREBALL: u32 = 133; // its own visual; the fallback must stay unused
     const MULTI_SHOT: u32 = 2643; // RANGED, own visual 567: impact + missile, no body kits
-    const NO_VIS_MELEE: u32 = 772; // no visual, no RANGED attribute — stays silent
-    const WEAPON_VISUAL: u32 = 98; // the real thrown ItemDisplayInfo col-10 substitute
+    const NO_VIS_MELEE: u32 = 772; // no visual, no RANGED attribute: stays silent
+    const WEAPON_VISUAL: u32 = 98; // a shipped thrown weapon's ItemDisplayInfo col-10 visual
     const MULTI_SHOT_VISUAL: u32 = 567;
 
     let visuals = SpellVisualCatalog::from_tables(
@@ -381,8 +364,7 @@ fn ranged_spells_merge_the_weapon_visual_into_their_empty_slots() {
                 },
             ),
             (
-                // The real 5875 row: impact kit 658, missile model 528, gate 1, attach 1 — and
-                // both body-kit slots empty, which is the whole of B153.
+                // The shipped row: impact kit 658, missile 528, gate 1, attach 1, no body kits.
                 MULTI_SHOT_VISUAL,
                 VisualStages {
                     impact: 658,
@@ -409,7 +391,7 @@ fn ranged_spells_merge_the_weapon_visual_into_their_empty_slots() {
                 FIREBALL,
                 SpellDisplay {
                     visual: VISUAL,
-                    attributes: 0x2, // ranged bit set AND an own visual: own wins (`60d4b4`)
+                    attributes: 0x2, // ranged, with its own visual: its own slot wins (`0x60d4b4`)
                     ..Default::default()
                 },
             ),
@@ -417,7 +399,7 @@ fn ranged_spells_merge_the_weapon_visual_into_their_empty_slots() {
                 MULTI_SHOT,
                 SpellDisplay {
                     visual: MULTI_SHOT_VISUAL,
-                    attributes: 0x10002, // the real word: RANGED set, own visual present
+                    attributes: 0x10002, // the shipped word: RANGED set, own visual present
                     ..Default::default()
                 },
             ),
@@ -472,10 +454,8 @@ fn ranged_spells_merge_the_weapon_visual_into_their_empty_slots() {
     );
 }
 
-/// The aura state watcher (`arm_aura_state_fx`): a spell id appearing in a unit's aura slots
-/// arms its state kit's effects persistent under [`super::FxClass::AuraState`]; the id leaving
-/// the slots reaps them; a slot-hold in between writes nothing. Food's real chain shape
-/// (5875: spell 433 → visual 51 → state kit 409 → effect 393 `Spells\Item_Bread.mdx`).
+/// The aura watcher arms a state kit's effects persistent under [`super::FxClass::AuraState`] as
+/// the spell enters the slots and reaps them as it leaves. Food: spell 433 → visual 51 → kit 409.
 #[test]
 fn aura_state_kit_arms_persistent_and_reaps_on_aura_end() {
     use benilla_protocol::messages::ObjectFields;
@@ -492,9 +472,7 @@ fn aura_state_kit_arms_persistent_and_reaps_on_aura_end() {
     app.add_plugins(MinimalPlugins);
     app.add_message::<SpellKitFx>();
     app.add_message::<crate::net::FieldChanged>();
-    // The watcher's other fan-outs: the kit's CharProc edges (`crate::aura_visual`) and its
-    // sound leg (0852). Food's kit 409 carries neither, so nothing is asserted here — the
-    // messages just have to exist for the writers.
+    // The watcher's CharProc and sound writers need their messages; kit 409 carries neither.
     app.add_message::<crate::aura_visual::AuraProc>();
     app.add_message::<SpellKitSound>()
         .add_message::<SpellKitShake>()
@@ -512,7 +490,7 @@ fn aura_state_kit_arms_persistent_and_reaps_on_aura_end() {
         HashMap::from([(
             STATE_KIT,
             VisualKit {
-                // Slot 4 = the spell-hand tag (KIT_SLOT_TAGS[4] = 0x16) — bread's real slot.
+                // Slot 4 is the spell-hand tag (KIT_SLOT_TAGS[4] = 0x16), bread's shipped slot.
                 effect_slots: [
                     None,
                     None,
@@ -550,9 +528,8 @@ fn aura_state_kit_arms_persistent_and_reaps_on_aura_end() {
             .chain(),
     );
 
-    // The aura lands in slot 0: UNIT_FIELD_AURA[0] = 47 carries the spell id; the slot's
-    // AURAFLAGS nibble (field 95, low nibble) needs an effect-index bit (occupancy is the
-    // flags test, decision 0257).
+    // Slot 0: UNIT_FIELD_AURA[0] (field 47) holds the spell id; occupancy is an effect-index bit
+    // in the slot's AURAFLAGS nibble (field 95's low nibble).
     let eating = ObjectFields::from_pairs(&[(47, FOOD), (95, 0x0E)]);
     let fasted = ObjectFields::from_pairs(&[(95, 0)]);
 
@@ -590,7 +567,6 @@ fn aura_state_kit_arms_persistent_and_reaps_on_aura_end() {
         );
     }
 
-    // Slot held: no further edges.
     app.update();
     assert_eq!(
         app.world().resource::<FxLog>().0.len(),
@@ -598,7 +574,6 @@ fn aura_state_kit_arms_persistent_and_reaps_on_aura_end() {
         "a held aura re-arms nothing"
     );
 
-    // The aura leaves the slots: one AuraState reap.
     crate::net::apply_fields_for_test(
         app.world_mut(),
         unit,
@@ -619,15 +594,9 @@ fn aura_state_kit_arms_persistent_and_reaps_on_aura_end() {
     }
 }
 
-/// The GO's **release gate** (the client's `0x6e7a70` flush condition): a Speed>0 spell whose
-/// cast kit plays a body animation emits its [`MissileSpawn`] deferred (`awaits_release`) —
-/// the launch waits for the animation's release keyframe — while a cast kit with no animation
-/// (or none at all) launches at GO.
-/// The spell impact body twitch (decision 2058, sharpened by 2063): an instant harmful spell's GO
-/// lays ONE severity-0 wound on each hit target (`0x6e8bf0` @ `0x6e8c89`), a helpful one lays none;
-/// a state kit naming a wound anim adds nothing on either (the client's stage-2 play never reaches
-/// the `[8,10]` test, `0x60f383`); and a missile ARRIVAL wounds unconditionally (`0x61dc50` @
-/// `0x61dc74`) — even for the helpful spell.
+/// An instant harmful GO lays one severity-0 wound on each hit (`0x6e8bf0` at `0x6e8c89`), a
+/// helpful one none; a state kit's wound anim adds nothing (stage 2 never reaches the `[8,10]`
+/// test, `0x60f383`); a missile arrival always wounds (`0x61dc50` at `0x61dc74`).
 #[test]
 fn a_harmful_go_wounds_each_hit_once_and_a_missile_arrival_always() {
     const HARMFUL: u32 = 7386; // Sunder Armor's shape: instant, enemy-targeted
@@ -635,7 +604,7 @@ fn a_harmful_go_wounds_each_hit_once_and_a_missile_arrival_always() {
     const VISUAL_H: u32 = 406;
     const VISUAL_F: u32 = 280;
     const IMPACT_KIT: u32 = 556; // no anim
-    const STATE_KIT: u32 = 436; // names CombatWound(9) — must add nothing
+    const STATE_KIT: u32 = 436; // names CombatWound (9), which must add nothing
 
     let mut app = App::new();
     app.add_plugins(MinimalPlugins);
@@ -725,7 +694,6 @@ fn a_harmful_go_wounds_each_hit_once_and_a_missile_arrival_always() {
         app.update();
         assert_eq!(wounds(&mut app), expected, "instant GO of spell {spell_id}");
     }
-    // A missile landing wounds whoever it lands on, hostility untested.
     app.world_mut().write_message(cast_event(
         target,
         HELPFUL,
@@ -737,6 +705,8 @@ fn a_harmful_go_wounds_each_hit_once_and_a_missile_arrival_always() {
     assert_eq!(wounds(&mut app), vec![target], "missile arrival");
 }
 
+/// The GO's release gate (`0x6e7a70`): a Speed>0 spell whose cast kit plays a body animation
+/// defers its [`MissileSpawn`] to the animation's release keyframe; any other launches at GO.
 #[test]
 fn missile_spawn_defers_iff_the_cast_kit_animates() {
     const ANIMATED: u32 = 133; // Fireball's shape: cast kit with anim 53
@@ -847,11 +817,8 @@ fn missile_spawn_defers_iff_the_cast_kit_animates() {
     );
 }
 
-/// 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.
+/// A Speed>0 GO with no hits but a ground point spawns one projectile at it (`0x6e8a50`'s empty-hit
+/// arm), whose arrival (`0x61d870`) rings `SpellVisual` field 13's kit sound at the landing point.
 #[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
@@ -959,19 +926,9 @@ fn a_targetless_dest_go_spawns_a_ground_missile_whose_arrival_sounds_at_the_poin
     );
 }
 
-/// **B130's crash** — the second ever reported: a release build panicked on `insert<CastHold>`
-/// while flying at high speed through the Wetlands, applying hold commands to a unit that had
-/// despawned. Both windows are exercised here, because they fail for different reasons:
-///
-/// 1. **Already gone when the edge is read.** Every despawn of an indexed unit runs inside the wire
-///    drain (`DESTROY_OBJECT`, the out-of-range stream-out, the worldport purge), and those are
-///    applied at the sync point this chain sits behind — so a START and its subject's death arrive
-///    in one batch and the edge outlives the unit.
-/// 2. **Queued this frame, no sync point between.** `model_fade::apply_despawn_fade` is
-///    Update-unordered against this chain; its despawn can be queued before ours and applied first,
-///    which a queue-time existence check structurally cannot see.
-///
-/// The pass condition is that the frame completes — and that neither window resurrects the unit.
+/// A cast edge for a despawned unit neither panics the hold insert nor resurrects the unit, whether
+/// it died in the wire drain applied before this chain, or `model_fade::apply_despawn_fade`,
+/// unordered against it, queued the despawn first, which no queue-time check can see.
 #[test]
 fn a_despawned_subject_never_panics_the_router() {
     {
@@ -980,15 +937,15 @@ fn a_despawned_subject_never_panics_the_router() {
         app.world_mut().entity_mut(unit).despawn();
         app.world_mut()
             .write_message(cast_event(unit, SPELL, CastEventKind::Start));
-        app.update(); // window 1: panicked here before the fix
+        app.update(); // window 1: the unit is gone before the edge is read
         assert!(
             app.world().get_entity(unit).is_err(),
             "the hold write must not resurrect a dead subject"
         );
     }
     {
-        // `before_ignore_deferred` is exactly the fade lane's shape — an ordering edge with no sync
-        // point on it, so both command queues flush together and the despawn applies first.
+        // Window 2, the fade lane's shape: an ordering edge with no sync point, so both command
+        // queues flush together and the despawn applies first.
         let mut app = app();
         let unit = app.world_mut().spawn_empty().id();
         app.add_systems(
@@ -1008,15 +965,13 @@ fn a_despawned_subject_never_panics_the_router() {
     }
 }
 
-/// 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`).
+/// The `0x400` weapon-visual hold (`0x60d020`): a ranged spell's visual play inserts [`RangedHold`]
+/// on any caster, and a non-ranged play clears it (the 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();
     let unit = app.world_mut().spawn_empty().id();
 
-    // A remote shooter's per-shot GO (cast kit resolves) → the hold arms.
     app.world_mut()
         .write_message(cast_event(unit, RANGED_SPELL, CastEventKind::Go));
     app.update();
@@ -1025,7 +980,6 @@ fn ranged_visual_play_arms_the_any_caster_hold_and_a_non_ranged_play_clears_it()
         "a ranged GO's visual play sets the hold"
     );
 
-    // A later NON-ranged visual play (the buff's precast kit) → the stale-visual cleanup.
     app.world_mut()
         .write_message(cast_event(unit, SPELL, CastEventKind::Start));
     app.update();
@@ -1034,8 +988,7 @@ fn ranged_visual_play_arms_the_any_caster_hold_and_a_non_ranged_play_clears_it()
         "a non-ranged visual play clears the hold"
     );
 
-    // A ranged START (the volley activation's precast play) re-arms it too — but this shape's
-    // precast stage is empty, so drive it through the GO again after the clear.
+    // A ranged START re-arms it too, but this chain's precast stage is empty, so the GO re-arms it.
     app.world_mut()
         .write_message(cast_event(unit, RANGED_SPELL, CastEventKind::Go));
     app.update();
@@ -1045,22 +998,19 @@ fn ranged_visual_play_arms_the_any_caster_hold_and_a_non_ranged_play_clears_it()
     );
 }
 
-/// **The mount poof** ([`super::arm_mount_poof_fx`], decision 0927) — the three properties the
-/// reference's `UNIT_FIELD_MOUNTDISPLAYID` watcher gives it, each a real fork in `0x5ffa50`:
-/// **the build leg only** (the whole allocation sits behind `5ffa87 je 0x5ffade` on the NEW
-/// value, so a dismount spawns nothing), **any changed value** (0→N and N→N′ alike), and
-/// **first sight silent** (a unit that streams in already mounted did not just mount — the
-/// level-up ding's own treatment, decision 0305).
+/// The mount poof, as `0x5ffa50` gives it: only the build leg allocates it, behind
+/// `0x5ffa87 je 0x5ffade` on the new value, so a dismount is silent; any changed value puffs; and
+/// a unit streaming in already mounted does not.
 #[test]
 fn the_mount_poof_puffs_on_the_build_leg_only() {
     use benilla_protocol::ObjectFields;
 
-    /// `UNIT_FIELD_MOUNTDISPLAYID` (index 133, decision 0441).
+    /// `UNIT_FIELD_MOUNTDISPLAYID` (index 133).
     const FIELD_MOUNTDISPLAYID: u16 = 133;
-    /// `SpellVisualEffectName` row 1185's shipped path — the druid-morph cloud.
+    /// The shipped path of `SpellVisualEffectName` row 1185, the druid-morph cloud.
     const POOF: &str = "Spells\\DruidMorph_Impact_Base.mdx";
-    const POOF_FX: u32 = 1185; // the shipped `SpellVisualEffectName` row (decision 0927)
-    /// The M2 attach the hardcoded-effect spawn stamps (`DAT_0080c968[6]`).
+    const POOF_FX: u32 = 1185;
+    /// The M2 attach the hardcoded-effect spawn stamps (`0x80c968[6]`).
     const BASE_ATTACH: u16 = 0x13;
 
     let mut app = App::new();
@@ -1077,7 +1027,7 @@ fn the_mount_poof_puffs_on_the_build_leg_only() {
     app.add_systems(Update, super::arm_mount_poof_fx);
 
     let fields = |v: u32| ObjectFields::from_pairs(&[(FIELD_MOUNTDISPLAYID, v)]);
-    // Streams in ALREADY mounted: the create block is no edge (decision 2297), so silence.
+    // Streams in already mounted: a create block is no edge.
     let unit = app
         .world_mut()
         .spawn(crate::net::ObjectStore(
@@ -1105,12 +1055,11 @@ fn the_mount_poof_puffs_on_the_build_leg_only() {
         "a rider that streams into view did not just mount"
     );
 
-    // Dismount — the NEW value is 0, so the build leg (and the whole allocation) is skipped.
+    // Dismount: the new value is 0, so the build leg is skipped.
     crate::net::apply_fields_for_test(app.world_mut(), unit, fields(0));
     app.update();
     assert!(puffs(&mut app).is_empty(), "no poof on the way down");
 
-    // Mount: 0 → N.
     crate::net::apply_fields_for_test(app.world_mut(), unit, fields(2404));
     app.update();
     assert_eq!(
@@ -1123,12 +1072,11 @@ fn the_mount_poof_puffs_on_the_build_leg_only() {
         "the build leg puffs the druid-morph cloud at the base attach"
     );
 
-    // A steady mounted frame is not an edge — the watcher fires on the field CHANGING.
     crate::net::apply_fields_for_test(app.world_mut(), unit, fields(2404));
     app.update();
     assert!(puffs(&mut app).is_empty(), "no re-puff while just riding");
 
-    // A swap (N → N′) is a change, and the reference rebuilds and puffs again.
+    // A swap (N → N′) is a change: the reference rebuilds and puffs again.
     crate::net::apply_fields_for_test(app.world_mut(), unit, fields(2405));
     app.update();
     assert_eq!(
@@ -1141,13 +1089,9 @@ fn the_mount_poof_puffs_on_the_build_leg_only() {
     );
 }
 
-/// **The link that makes the beam exist at all** (decision 0955 slice 2): a kit carrying a chain
-/// `CharProc` emits a [`ChainProcPlay`] when it plays — from BOTH of the reference's dispatcher
-/// call sites, `PlaySpellVisualKit`'s tail (the cast release) and the channel poll (`0x612b18`,
-/// which is the only way a channelled beam is ever reached). A kit without one emits nothing.
-///
-/// This is the test that fails if the whole lane silently does nothing: the geometry, the hop
-/// array and the wire can all be right while no kit ever asks for a beam.
+/// A kit with a chain `CharProc` emits a `ChainProcPlay` from both dispatcher sites:
+/// `PlaySpellVisualKit`'s tail (the cast release) and the channel poll (`0x612b18`), the only way
+/// a channelled beam is reached.
 #[test]
 fn a_kit_with_a_chain_char_proc_asks_for_a_beam_from_both_dispatcher_sites() {
     use benilla_formats::{char_proc_type, CharProc};
@@ -1158,9 +1102,8 @@ fn a_kit_with_a_chain_char_proc_asks_for_a_beam_from_both_dispatcher_sites() {
     const BEAM_CHANNEL_KIT: u32 = 402;
 
     let mut app = app();
-    // Overlay the beam chain onto the fixture catalog: a cast kit with the real type-12 slot and a
-    // channel kit with the real type-0 one. Params are the shipped shape — chain id 1, one strand,
-    // and the flag that splits cast (0) from channel (1).
+    // A cast kit with a type-12 proc and a channel kit with a type-0 one, in the shipped shape:
+    // chain id 1, one strand, and the flag that splits cast (0) from channel (1).
     let mut visuals = HashMap::from([(
         BEAM_VISUAL,
         VisualStages {
@@ -1190,7 +1133,7 @@ fn a_kit_with_a_chain_char_proc_asks_for_a_beam_from_both_dispatcher_sites() {
             },
         );
     }
-    // …plus a beam-less kit, so "emits nothing" is a real control and not an empty catalog.
+    // A beam-less kit, the control.
     kits.insert(PRECAST_KIT, VisualKit::default());
     visuals.insert(
         VISUAL,
@@ -1228,7 +1171,7 @@ fn a_kit_with_a_chain_char_proc_asks_for_a_beam_from_both_dispatcher_sites() {
             .collect()
     };
 
-    // Site 1 — the cast release (`0x60f35c`).
+    // Site 1, the cast release (`0x60f35c`).
     let unit = app.world_mut().spawn_empty().id();
     app.world_mut()
         .write_message(cast_event(unit, BEAM_SPELL, CastEventKind::Go));
@@ -1239,14 +1182,13 @@ fn a_kit_with_a_chain_char_proc_asks_for_a_beam_from_both_dispatcher_sites() {
         "the cast kit's type-12 proc asks for a one-shot beam"
     );
 
-    // The control: a spell whose cast kit carries no chain proc asks for nothing.
     app.world_mut()
         .write_message(cast_event(unit, SPELL, CastEventKind::Go));
     app.update();
     assert!(plays(&mut app).is_empty(), "a beam-less kit stays silent");
 
-    // Site 2 — the channel poll (`0x612b18`). The rising edge of `UNIT_CHANNEL_SPELL` is what
-    // reaches Drain Life's kit; nothing else ever plays it.
+    // Site 2, the channel poll (`0x612b18`), on the rising edge of `UNIT_CHANNEL_SPELL`: the only
+    // play of a channel kit.
     let channeller = app
         .world_mut()
         .spawn(crate::net::ObjectStore(
@@ -1262,28 +1204,19 @@ fn a_kit_with_a_chain_char_proc_asks_for_a_beam_from_both_dispatcher_sites() {
     );
 }
 
-// ── The real-chain shooter pin (bug B307) ────────────────────────────────────────────────────
+// ── The shipped-table shooter ────────────────────────────────────────────────────────────────
 //
-// 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
-// `None` in all of them and nothing notices (their ranged spell carries its own cast kit).
-// These tests close that hole: the real 5875 DBCs, a real self-player, a real `item_template`
-// row, one `CastEvent` in, the body's clip out.
+// The tests above use bare units, for which `WeaponVisualSrc::caster` (a player's ranged weapon →
+// its substitute visual) is always `None`. These run the shipped DBCs, a self-player and a real
+// `item_template` row: one `CastEvent` in, the body's clip out.
 
-/// Auto Shot — the one spell every ranged auto-attack fires (one `SMSG_SPELL_GO` per shot).
-/// Its real 5875 row: `Attributes = 0x50012` (so `& 0x2`, USES_RANGED_SLOT, IS set),
-/// `AttributesEx2 = 0x20` (auto-repeat), Speed 40 — and **`SpellVisual1 = 0`**. It authors no
-/// visual whatsoever, so every clip it plays comes from the equipped weapon's substitute visual
-/// through [`super::resolve_stages`]'s merge. If that lookup fails, the shooter is silent.
+/// Auto Shot, one `SMSG_SPELL_GO` per shot. Its shipped row: `Attributes` 0x50012 (`& 0x2` set),
+/// `AttributesEx2` 0x20 (auto-repeat), Speed 40 and `SpellVisual1` 0, so every clip it plays comes
+/// from the weapon's substitute visual through [`super::resolve_stages`]'s merge.
 const AUTO_SHOT: u32 = 75;
 
-/// One real `item_template` row — what the wire hands the client for an equipped ranged weapon.
-/// Entry/display/class/subclass read from the live vmangos `mangos.item_template`; the
-/// display → `ItemDisplayInfo` col 10 → `SpellVisual` → kit → `AnimationData` tail is the real
-/// 5875 DBCs' and is re-derived by the test, never assumed.
+/// A ranged weapon's vmangos `item_template` row; the display → `ItemDisplayInfo` col 10 →
+/// `SpellVisual` → kit → anim chain is re-derived from the shipped DBCs by the test.
 struct RealRanged {
     name: &'static str,
     entry: u32,
@@ -1291,9 +1224,9 @@ struct RealRanged {
     /// `ItemClass` 2 (weapon) and its subclass: 2 bow, 3 gun, 18 crossbow.
     class: u32,
     subclass: u32,
-    /// The pull, from the weapon visual's PRECAST kit: LoadBow 105 / LoadRifle 106.
+    /// The pull, from the weapon visual's precast kit: LoadBow 105 or LoadRifle 106.
     load_anim: u16,
-    /// The release, from its CAST kit: AttackBow 46 / AttackRifle 49.
+    /// The release, from its cast kit: AttackBow 46 or AttackRifle 49.
     fire_anim: u16,
 }
 
@@ -1319,8 +1252,8 @@ const OLD_BLUNDERBUSS: RealRanged = RealRanged {
     fire_anim: 49,
 };
 
-/// A crossbow (`item_template` 12651, display 22929 → visual 743 → kits 803/804 → 106/49 —
-/// crossbows share the rifle clips, they do not have their own).
+/// A crossbow (`item_template` 12651, display 22929 → visual 743 → kits 803/804 → 106/49):
+/// crossbows share the rifle clips.
 const BLACKCROW: RealRanged = RealRanged {
     name: "Blackcrow",
     entry: 12651,
@@ -1331,22 +1264,18 @@ const BLACKCROW: RealRanged = RealRanged {
     fire_anim: 49,
 };
 
-/// `PLAYER_VISIBLE_ITEM_18_0` — the public item ENTRY worn in equipment slot 17 (vmangos
-/// `EQUIPMENT_SLOT_RANGED`), i.e. `PLAYER_VISIBLE_ITEM_1_CREATOR (258) + 2 + 12 × 17`. Spelled
-/// out because that base index is private to `benilla-protocol`; `player_visible_item_entry(17)`
-/// is the accessor it feeds, and this test would fail loudly if the two ever disagreed.
+/// `PLAYER_VISIBLE_ITEM_18_0`, the item entry in equipment slot 17 (vmangos
+/// `EQUIPMENT_SLOT_RANGED`): `PLAYER_VISIBLE_ITEM_1_CREATOR` (258) + 2 + 12 × 17, spelled out as
+/// the base is private to `benilla-protocol`.
 const VISIBLE_RANGED_ENTRY_FIELD: u16 = 258 + 2 + 12 * 17;
 
-/// Keeps the item layer's ask-once channel ALIVE for the app's life, so an unexpected
-/// `ItemQuery` send (the "template not landed" path — the failure mode that would silently
-/// starve the weapon lookup) is observable rather than swallowed by a dropped receiver.
+/// Keeps the item layer's ask-once channel alive, so an unexpected `ItemQuery` (a template not
+/// landed, which starves the weapon lookup) is observable.
 #[derive(Resource)]
 struct AskLog(crossbeam_channel::Receiver<crate::net::ClientCommand>);
 
-/// The cast router wired over the **real 5875 tables**, with a self-player wearing `weapon` in
-/// the ranged slot and its template already landed in the item cache — which is the live state
-/// by the time anything shoots (the equipped weapon rendered through the same ask-once layer
-/// long before). `None`, with the skip note printed, when there is no WoW install to read.
+/// The cast router over the shipped tables, with a self-player wearing `weapon` in the ranged slot
+/// and its template landed, as it is by the time anything shoots; `None` without an install.
 fn real_shooter(weapon: &RealRanged) -> Option<(App, Entity)> {
     let data = benilla_formats::wow_data_or_skip!(None);
     let mut chain = benilla_formats::open_chain(&data).expect("open the install's MPQ chain");
@@ -1385,7 +1314,7 @@ fn real_shooter(weapon: &RealRanged) -> Option<(App, Entity)> {
     template.class = weapon.class;
     template.subclass = weapon.subclass;
     template.display_info_id = weapon.display_id;
-    template.inventory_type = 15; // INVTYPE_RANGED — the real row's; unread by this chain
+    template.inventory_type = 15; // INVTYPE_RANGED, the real row's; unread by this chain
     items.insert_template(weapon.entry, Some(template));
     app.insert_resource(items);
 
@@ -1393,15 +1322,14 @@ fn real_shooter(weapon: &RealRanged) -> Option<(App, Entity)> {
     app.insert_resource(crate::net::NetCommands(tx));
     app.insert_resource(AskLog(rx));
 
-    // The shooter: our own body, a PLAYER on the wire, with the weapon's ENTRY in the public
-    // visible-item field — exactly what `SMSG_UPDATE_OBJECT` carries for equipment.
+    // Our own body, a player, with the weapon's entry in the visible-item field.
     let unit = app
         .world_mut()
         .spawn((
             crate::net::SelfPlayer,
             crate::net::NetEntity {
                 kind: benilla_protocol::EntityKind::Player,
-                display_id: Some(49), // HumanMale — authors 46/49/105/106 internally
+                display_id: Some(49), // HumanMale, which authors 46/49/105/106
                 scale: 1.0,
             },
             crate::net::ObjectStore(benilla_protocol::ObjectFields::from_pairs(&[(
@@ -1424,8 +1352,7 @@ fn emote_anims(app: &mut App, unit: Entity) -> Vec<u16> {
         .collect()
 }
 
-/// The entries the item layer had to ask the server for — empty is the expected reading (the
-/// template is pre-landed); anything here means the weapon lookup starved on a cold cache.
+/// The entries the item layer asked the server for; any means the weapon lookup starved.
 fn asked_entries(app: &App) -> Vec<u32> {
     app.world()
         .resource::<AskLog>()
@@ -1438,12 +1365,8 @@ fn asked_entries(app: &App) -> Vec<u32> {
         .collect()
 }
 
-/// **B307's pin, bow half.** One `SMSG_SPELL_GO` for Auto Shot on a self-player with a real bow
-/// equipped must reach the body as `EmoteAnim { anim_id: 46 }` (AttackBow) — through the live
-/// chain end to end: `Spell.dbc` 75 (`Attributes & 0x2`, no visual of its own) →
-/// [`super::WeaponVisualSrc::caster`] (`PLAYER_VISIBLE_ITEM` slot 17 → the item template →
-/// display 8106) → `ItemDisplayInfo` col 10 (visual 5) → the merge → `SpellVisual` 5's cast kit
-/// 164 → its anim 46.
+/// Auto Shot's GO with a bow equipped reaches the body as AttackBow (46): slot 17's template →
+/// display 8106 → `ItemDisplayInfo` col 10 (visual 5) → the merge → cast kit 164 → anim 46.
 #[test]
 fn a_real_bow_shooters_auto_shot_go_plays_attackbow() {
     let Some((mut app, unit)) = real_shooter(&WORN_SHORTBOW) else {
@@ -1464,9 +1387,7 @@ fn a_real_bow_shooters_auto_shot_go_plays_attackbow() {
     );
 }
 
-/// **B307's pin, "any ranged weapon" half.** A gun and a crossbow take the SAME road to a
-/// different pair of clips (visual 224 / 743 → AttackRifle 49) — so a fix that only ever saw a
-/// bow, or a schema that only decodes one display row, is caught here.
+/// A gun and a crossbow take the same road to AttackRifle (49), through visuals 224 and 743.
 #[test]
 fn a_real_gun_or_crossbow_shooters_auto_shot_go_plays_attackrifle() {
     for weapon in [&OLD_BLUNDERBUSS, &BLACKCROW] {
@@ -1485,10 +1406,8 @@ fn a_real_gun_or_crossbow_shooters_auto_shot_go_plays_attackrifle() {
     }
 }
 
-/// 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.
+/// Auto Shot's START, once per auto-repeat activation, arms the LoadBow (105) pull as the cast
+/// hold, with [`RangedHold`] and the ranged sheath snap; the GO releases it and fires.
 #[test]
 fn a_real_bow_shooters_auto_shot_start_arms_the_loadbow_hold() {
     let Some((mut app, unit)) = real_shooter(&WORN_SHORTBOW) else {
@@ -1516,7 +1435,6 @@ fn a_real_bow_shooters_auto_shot_start_arms_the_loadbow_hold() {
         .collect();
     assert_eq!(sheaths, vec![2], "…and the ranged stance snaps drawn");
 
-    // The GO releases it and fires — the shot's own clip, on the same body.
     app.world_mut()
         .write_message(cast_event(unit, AUTO_SHOT, CastEventKind::Go));
     app.update();
@@ -1531,16 +1449,13 @@ fn a_real_bow_shooters_auto_shot_start_arms_the_loadbow_hold() {
     );
 }
 
-/// The control that proves the tests above are actually exercising
-/// [`super::WeaponVisualSrc::caster`] and not passing for some other reason: the SAME shooter
-/// with an EMPTY ranged slot resolves nothing at all — Auto Shot has no visual of its own to
-/// fall back on.
+/// The control: with the ranged slot empty Auto Shot resolves no clip, having no visual of its own.
 #[test]
 fn a_shooter_with_no_ranged_weapon_resolves_no_clip_at_all() {
     let Some((mut app, unit)) = real_shooter(&WORN_SHORTBOW) else {
         return;
     };
-    // Strip the equipment field — the wire's "nothing in slot 17".
+    // Slot 17 empty, as the wire says it.
     crate::net::apply_fields_for_test(
         app.world_mut(),
         unit,
@@ -1562,22 +1477,11 @@ 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): `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,
-/// benilla played the 14 as a second one-shot — a `Stun` pose the reference never shows on
-/// anything.
-///
-/// **Scope, corrected by decision 2096:** the recompute this emits does NOT cut the Knockdown.
-/// `Knockdown` takes the base-animation lock when it arms, so the `Stand` the recompute resolves is
-/// refused and the clip plays out — which is what the director sees on the reference. The recompute
-/// cuts only what holds no lock. What this test pins is the router's half: one play, not two.
+/// A state kit's anim id is a compare, never a play: `0x60edf0`'s one play site
+/// (`0x60f3c5 call 0x5fe2f0`) is skipped for stage 2 (`0x60f387 jne`), the stage both field-4 users
+/// play (the aura watcher and the impact hand-off `0x61dced`), so the id only feeds `0x60f390`'s
+/// compare and a base recompute. Charge (22911) plays Knockdown (121) from impact kit 348; state
+/// kit 349's Stun (14) is a recompute, which Knockdown's base-animation lock refuses.
 #[test]
 fn a_state_kits_anim_is_a_recompute_and_never_a_second_play() {
     const CHARGE: u32 = 22911;
@@ -1681,11 +1585,8 @@ fn a_state_kits_anim_is_a_recompute_and_never_a_second_play() {
     );
 }
 
-/// A state kit whose **whole visual is its animation id** still arms (decision 2085). The aura
-/// watcher's entry test asks "does this kit do anything we model?", and the anim was missing from
-/// it — the B114 shape one level over, where an effects-only test dropped Stealth's proc-only kit.
-/// 15 of the shipped state kits are anim-only (`benilla-extract kitanim`), among them kit 586's
-/// `Stun`(14) — Sneezing Fit, Smoke Bomb and kin.
+/// An anim-only state kit still arms, and its add edge owes a recompute: 15 shipped state kits are
+/// anim-only (`benilla-extract kitanim`), kit 586's Stun (14) among them.
 #[test]
 fn an_anim_only_state_kit_still_arms_on_the_aura_add_edge() {
     use benilla_protocol::messages::ObjectFields;
diff --git a/crates/benilla-app/src/creature_anim/twist.rs b/crates/benilla-app/src/creature_anim/twist.rs
index c6d8666f..37edce6f 100644
--- a/crates/benilla-app/src/creature_anim/twist.rs
+++ b/crates/benilla-app/src/creature_anim/twist.rs
@@ -1,27 +1,15 @@
-//! 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
-//! then counter-rotates two key-bone subtrees back toward the aim, proportional to the remaining
-//! gap: **SpineLow (KeyBoneID 4)** takes half the gap capped at 45°, **Head (KeyBoneID 6)** takes
-//! the remainder capped at 45°. For a pure 90° strafe that composes to: hips/legs fully at the
-//! strafe heading, shoulders counter-twisted back ~45°, and the head landing *exactly* on the aim
-//! (45° + 45° = 90°) — nothing tuned, the arithmetic closes. The gap owner ([`crate::player`]'s
-//! controller for our avatar, [`crate::net::motion`] for remote movers) writes [`BodyTwist::yaw_gap`];
-//! the [`apply_body_twist`] system composes the twist onto the animated bone locals each frame,
-//! after Bevy's animation evaluation and before transform propagation.
+//! The strafe counter-twist (the `0x607ed0` tail → the `0x711f10` bone channels): a strafe turns
+//! the root toward the slide while the aim holds, and SpineLow (KeyBoneID 4) turns back half the
+//! gap and Head (KeyBoneID 6) the rest, each capped at 45°, so a pure strafe's head lands on the
+//! aim. [`crate::player`] and [`crate::net::motion`] write [`BodyTwist::yaw_gap`].
 
 use bevy::prelude::*;
 
-/// The body's counter-twist state, on a skinned unit's root entity. Inserted at visual attach when
-/// the model carries either twist key-bone ([`benilla_assets::ModelSkeleton::spine_bone`]/
-/// [`head_bone`](benilla_assets::ModelSkeleton::head_bone)); absent on beasts/props (the client's
-/// capability gates `[+0xd58] & 0x80/0x100` — a model without the key-bone plays no channel).
+/// The twist state, on a unit's root when its model has either key bone (the client's
+/// `[+0xd58] & 0x80`/`0x100`).
 #[derive(Component)]
 pub(crate) struct BodyTwist {
-    /// `wrap(aim − rendered root yaw)`, radians — how far the aim sits from the heading the model
-    /// renders at. Zero whenever the body faces its aim (everything but a strafe, today).
+    /// `wrap(aim − rendered root yaw)` in radians; zero while the body faces its aim.
     pub(crate) yaw_gap: f32,
     spine: Option<Channel>,
     head: Option<Channel>,
@@ -37,15 +25,13 @@ impl BodyTwist {
     }
 }
 
-/// One twist channel's bone + composition bookkeeping.
+/// One twist channel's bone and bookkeeping.
 struct Channel {
     bone: u16,
-    /// The animated local rotation the twist last composed on — the "base" under our twist.
+    /// The animated local rotation the twist last composed on.
     base: Quat,
-    /// What we last wrote (`base * twist`). If the bone still holds exactly this next frame, the
-    /// animation didn't retouch it this frame (a clip need not key every bone), so `base`
-    /// stays authoritative — composing onto the bone's current value instead would accumulate the
-    /// twist frame over frame and spin it.
+    /// What we last wrote (`base * twist`). A bone still holding it was not re-keyed this frame, so
+    /// `base` stays; composing onto it would accumulate the twist and spin the bone.
     last_out: Quat,
 }
 
@@ -59,22 +45,15 @@ impl Channel {
     }
 }
 
-/// Wrap an angle to `(−π, π]` — the shortest-arc form every yaw-gap computation here uses.
+/// Wrap an angle to `(−π, π]`, the shortest arc.
 pub(crate) fn wrap_pi(angle: f32) -> f32 {
     use std::f32::consts::{PI, TAU};
     PI - (PI - angle).rem_euclid(TAU)
 }
 
-/// Split a yaw gap into the (spine, head) counter-twist angles — the client's share math
-/// (`0x607ed0` tail, byte-VERIFIED): spine = half the gap capped at ±45°, head = the remainder
-/// capped at ±45° — so a pure 90° strafe composes to 45°+45° and the head lands exactly on the aim.
-///
-/// 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 — 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.
+/// The `(spine, head)` twist angles. The reference's full-share branch (`0x6103a0`) fires only for
+/// the local player during a click-to-move action (`[0xc4d888]` holds `0xc`, disabled, in
+/// ordinary play), which benilla does not have.
 fn twist_shares(gap: f32) -> (f32, f32) {
     use std::f32::consts::FRAC_PI_4;
     let spine = (gap * 0.5).clamp(-FRAC_PI_4, FRAC_PI_4);
@@ -82,47 +61,22 @@ fn twist_shares(gap: f32) -> (f32, f32) {
     (spine, head)
 }
 
-/// 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` (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
-/// while the shoulders ride the saddle rigidly; applying both wobbled a mounted strafe's head AND
-/// shoulders far past the reference (the director's mounted A/B — the observation that found this).
-///
-/// The gate is on the channel ARM, not on the share math, so the head keeps its full `gap − spine`
-/// share and — unlike the unmounted case — no longer lands exactly on the aim. And the spine's
-/// share goes to **zero** rather than the channel being skipped: the zero path rewrites the bone
-/// 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 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.)
+/// [`twist_shares`] with the mount gate: the `0x607ed0` tail arms SpineLow only while
+/// `CGUnit+0xdc`, the mount model (set by `0x613d80`, read as the mount by `0x614cd0`), is null,
+/// and Head always, so a rider's head keeps its share and stops short of the aim. A mounted spine
+/// share is zero, not skipped: the zero write restores the animated base, the reference's disarm
+/// (`0x711f10(4, 0, 0x80)`), where skipping would freeze the last twist.
 fn armed_shares(gap: f32, mounted: bool) -> (f32, f32) {
     let (spine, head) = twist_shares(gap);
     (if mounted { 0.0 } else { spine }, head)
 }
 
-/// Compose the counter-twist onto the animated bone locals — PostUpdate, in the pose post-pass
-/// window ([`benilla_world::rig_anim::PosePost`]: after the evaluator wrote this frame's pose, before the model
-/// compose folds it).
-///
-/// Each channel yaws its subtree about **world up through the bone's own pivot**: with `g` the
-/// bone's model-space rotation (ancestors × its animated local), `local' = local · Quat(g⁻¹·Y, θ)`
-/// conjugates to a pure up-axis yaw of the subtree (units stand upright and their root rotation is
-/// a Y-yaw, so model up and world up coincide). The head channel runs after the spine write, so its
-/// ancestor chain already carries the spine's twist — the head counter-rotates relative to the
-/// twisted spine, exactly the client's residual-gap composition. The ancestor walk runs up the
-/// rig's own parent table, then the entity frames between its `joints_root` and the unit (a
-/// conform node's tilt; a mounted rider's seat — splicing through the mount's bone chain via its
-/// [`benilla_world::rig_anim::RigAnchor`]), exactly the frames the joint-entity walk used to compose.
+/// Compose the twist onto the bone locals in [`benilla_world::rig_anim::PosePost`]: each channel
+/// yaws its subtree about world up through the bone's pivot, `local' = local · Quat(g⁻¹·Y, θ)`
+/// with `g` the bone's rotation up to the unit. The head runs after the spine, so it turns relative
+/// to the twisted spine, as the client composes the residual gap.
 pub(super) fn apply_body_twist(
-    // A parked rig's bones are frozen (decision 0448) — composing the twist onto them would
-    // recompute the palette every frame for a unit no one sees; the wake re-seats `base` from the
-    // fresh sample on its own (`cur != last_out`).
+    // A parked rig is skipped; on wake, `cur != last_out` re-seats `base`.
     mut units: Query<(Entity, &mut BodyTwist), Without<benilla_world::rig_anim::AnimParked>>,
     mut rigs: Query<&mut benilla_world::rig_anim::RigPose>,
     anchors: Query<&benilla_world::rig_anim::RigAnchor>,
@@ -130,10 +84,7 @@ pub(super) fn apply_body_twist(
     locals: Query<&Transform>,
     stores: Query<&crate::net::ObjectStore>,
 ) {
-    // `WOW_NO_TWIST=1` — stand the whole counter-twist down, and say what the gap WAS. The pass
-    // is inert at `yaw_gap == 0` (both shares are zero and every write is a no-op), so a bisect
-    // that only removes it cannot tell "the twist was innocent" from "the twist never ran"; the
-    // logged gap separates them.
+    // `WOW_NO_TWIST=1` stands the pass down and logs the gap it would have closed.
     if twist_off() {
         for (_, t) in &units {
             if t.yaw_gap != 0.0 {
@@ -162,16 +113,15 @@ pub(super) fn apply_body_twist(
                     let out = if angle == 0.0 {
                         base
                     } else {
-                        // The bone's model-space rotation: its own ancestor chain…
+                        // The bone's rotation: its own ancestor chain…
                         let mut g = base;
                         let mut b = rig.parents.get(bone).copied().unwrap_or(-1);
                         while let Ok(p) = usize::try_from(b) {
                             g = rig.locals.get(p)?.rotation * g;
                             b = rig.parents.get(p).copied().unwrap_or(-1);
                         }
-                        // …then the frames between joints_root and (excluding) the unit, splicing
-                        // a rig anchor's bone chain (the mount seat). Depth-capped against a
-                        // malformed hierarchy; the joint walk bottomed out at the world root.
+                        // …then the frames from joints_root up to the unit, splicing a rig
+                        // anchor's bone chain (the mount seat); capped against a bad hierarchy.
                         let mut e = rig.joints_root;
                         for _ in 0..32 {
                             if e == unit {
@@ -233,7 +183,7 @@ pub(super) fn plugin(app: &mut App) {
     );
 }
 
-/// `WOW_NO_TWIST`'s switch — read once. A bisect lever, not a shipping mode.
+/// `WOW_NO_TWIST`, read once: a bisect lever.
 fn twist_off() -> bool {
     static OFF: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *OFF.get_or_init(|| std::env::var_os("WOW_NO_TWIST").is_some())
@@ -244,9 +194,7 @@ mod tests {
     use super::{armed_shares, twist_shares};
     use std::f32::consts::{FRAC_PI_2, FRAC_PI_4, PI};
 
-    /// **A mounted rider counter-twists its HEAD only** — the `CGUnit+0xdc == 0` gate on the
-    /// SpineLow channel. The head's share is untouched by the gate (it is on the channel arm, not
-    /// the share math), so the two no longer sum to the gap and the head sits off the aim.
+    /// The mount gate disarms SpineLow alone; the head keeps its share, off the aim.
     #[test]
     fn mounted_disarms_the_spine_and_leaves_the_head_share_alone() {
         let (spine, head) = armed_shares(-FRAC_PI_2, true);
@@ -255,13 +203,13 @@ mod tests {
             head, -FRAC_PI_4,
             "the head keeps its full gap − spine share"
         );
-        // Unmounted, the same gap arms both — the 45°+45° close.
+        // Unmounted, the same gap arms both.
         assert_eq!(armed_shares(-FRAC_PI_2, false), twist_shares(-FRAC_PI_2));
     }
 
     #[test]
     fn pure_strafe_gap_closes_exactly_at_the_head() {
-        // 90° gap: spine 45°, head 45° — the head lands back on the aim.
+        // 90°: spine 45°, head 45°, the head back on the aim.
         let (spine, head) = twist_shares(-FRAC_PI_2);
         assert_eq!(spine, -FRAC_PI_4);
         assert_eq!(head, -FRAC_PI_4);
@@ -270,8 +218,7 @@ mod tests {
 
     #[test]
     fn diagonal_strafe_splits_evenly() {
-        // 45° gap: spine 22.5°, head 22.5° — head on the aim again (the half share, everywhere:
-        // the director's reference eye rejected the binary's local-player full-share branch).
+        // 45°: spine 22.5°, head 22.5°, the head on the aim again.
         let (spine, head) = twist_shares(FRAC_PI_4);
         assert_eq!(spine, FRAC_PI_4 / 2.0);
         assert_eq!(head, FRAC_PI_4 / 2.0);
@@ -279,7 +226,7 @@ mod tests {
 
     #[test]
     fn shares_cap_at_45_degrees_each() {
-        // An extreme gap (π) can't be fully absorbed: both channels cap at 45°.
+        // A gap of π cannot be absorbed: both channels cap at 45°.
         let (spine, head) = twist_shares(PI);
         assert_eq!(spine, FRAC_PI_4);
         assert_eq!(head, FRAC_PI_4);
diff --git a/crates/benilla-app/src/entities.rs b/crates/benilla-app/src/entities.rs
index 1a9bff5c..e44c5b16 100644
--- a/crates/benilla-app/src/entities.rs
+++ b/crates/benilla-app/src/entities.rs
@@ -1,18 +1,6 @@
-//! Streamed world entities: give each network entity ([`crate::net::NetEntity`]) a visual. NPCs **and
-//! other players** render as their real M2 (resolved from the display id via `CreatureCatalog` — a
-//! player's body resolves through the same creature chain, decision 0041), GameObjects as their model
-//! (`GameObjectCatalog`), and everything else as a colored cube.
-//!
-//! The entity itself — its identity, pose, and movement — is owned by the net bridge: `apply_net_updates`
-//! spawns one real ECS entity per server guid (with a [`Transform`] driven by `sample_splines`), and this
-//! module simply attaches a visual to it as soon as the model asset has loaded. There is no per-frame
-//! snapshot and no entity side-map: a unit *is* one entity.
-//!
-//! Models load through the standard `AssetServer` as `Handle<M2Model>`/`Handle<WmoModel>` (the same
-//! `mpq://` pipeline the terrain streamer uses) — deduped + async, no main-thread parse. Per display id
-//! we keep a [`DisplayModel`]: its handle + (for creatures) its skin variations, and the spawn parts
-//! built once the asset loads (creature `Monster1/2/3` skin slots filled here from the display's
-//! variations — see [`ModelSubmesh::skin_slot`]).
+//! The visuals of streamed entities ([`crate::net::NetEntity`]), attached once the model loads: a
+//! unit's display resolves to its M2 through the creature chain, a player's body included, a
+//! GameObject's to its model, and anything else draws as a cube.
 
 use std::collections::HashMap;
 
@@ -29,129 +17,91 @@ use benilla_assets::{AssetSet, LockRecover, WorldAssets};
 use benilla_world::model_fade::apply_render_fade;
 use benilla_world::schedule::WorldStage;
 
-/// Resolving a display id to its [`DisplayModel`] and building its spawn parts once the model asset
-/// loads (materials, skeleton, collider, camera/selection metrics) — the front half of this subsystem,
-/// kept in its own file as it carries the bulk of the per-display cache/build logic.
+/// The per-display model cache: a display id's [`DisplayModel`] and its spawn parts.
 pub(crate) mod display;
 use display::{
     build_parts, empty_display, empty_shell, new_creature_display, new_gameobject_display,
     DisplayModel, EntityPart, ModelHandle,
 };
 
-/// Attaching a visual to each net entity (the back half of this subsystem) — kept in its own file as it
-/// carries the bulk of the per-entity spawn logic (skeleton/animation, character geoset + skin, fade).
+/// Attaching a visual to each net entity: skeleton, animation, character geosets and skin, fade.
 mod attach;
 use attach::{attach_entity_visuals, build_dressup_preview, build_glue_pet, build_glue_preview};
 
-/// The dynamic point lights an entity's own model carries into the world — the held torch above all:
-/// decision 0016's law applied to the *entity* half of the scene, not just the placed half.
+/// The dynamic point lights an entity's own model carries, such as a held torch.
 mod carried_light;
 use carried_light::spawn_carried_lights;
 
-/// Equipment visuals (decisions 0072/0074): held items (weapon/shield/ranged) plus worn-armor and
-/// helm/shoulder resolution, all resolved from the unit descriptor + ItemDisplayInfo and spawned as
-/// children of the body's attach-point joints.
+/// Equipment from the descriptor and `ItemDisplayInfo`: armour, held items, helm and shoulders.
 mod equipment;
 use equipment::{attach_held_items, resolve_corpse_equipment, resolve_equipment};
 
-/// Item / enchant glow effects (decision 0805): the `Spells\Enchantments\*.mdx` models an item's
-/// `ItemVisuals` id hangs on the item's OWN attachment points — the permanent weapon glows and
-/// the shaman/oil enchant visuals.
+/// Item and enchant glows, hung on the item's own attachment points.
 mod item_glow;
 pub(crate) use item_glow::ItemGlowAttached;
 use item_glow::{attach_item_glows, ItemGlows};
 
-/// Mounts (decision 0441): the `UNIT_FIELD_MOUNTDISPLAYID` → second-creature-visual projection —
-/// the mount child + seat components and the transition's **re-seat** (B199: the reference
-/// re-parents the rider's model onto the mount, it never rebuilds it).
+/// Mounts: a second creature visual the rider's model is re-parented onto, never rebuilt.
 pub(crate) mod mount;
 use mount::reseat_mounts;
 
-/// Live descriptor appearance (decision 0695): a `Values` delta moving the display id swaps the
-/// model in place (druid forms, GM morphs — ledger B69/F04) and one moving `SCALE_X` eases the
-/// render scale (the reference's 2 s cosine smoothstep); both restamp the collision height.
-/// The corpse OBJECT (decision 1706): a `TYPEID_CORPSE` create rendered as the dead body — the
-/// character-model chain dressed from the corpse's own `CORPSE_FIELD_*` snapshot, or the
-/// `<Race><Sex>DeathSkeleton` prop once the server has converted it to bones.
+/// The corpse object, drawn as the dressed body or, once it turns to bones, a skeleton prop.
 pub(crate) mod corpse;
 
 mod live_display;
 pub(crate) use live_display::DisplaySwapped;
 use live_display::{refresh_live_display, tick_scale_ease};
 
-/// Terrain conform (decisions 0482/0486): every flagged model (`GlobalModelFlags & 3 ∈ {1,3}` —
-/// mounts and wild quadrupeds alike) tilts to the ground under its unit, through the conform
-/// node its root bones parent under.
+/// Terrain conform: a model flagged `GlobalModelFlags & 3 ∈ {1,3}` tilts to the ground.
 mod conform;
 
-/// The per-unit collision height (decision 0645): the display id's `CreatureModelData` column,
-/// scaled — the `h` the swim/wade/splash/foam depth lines are each a verified fraction of.
+/// The per-unit collision height, the `h` the swim, wade, splash and foam depths are fractions of.
 mod collision_height;
 use collision_height::stamp_collision_heights;
 pub(crate) use collision_height::CollisionHeight;
 
-/// Spell-visual effect models (decision 0099 phase 3): a casting unit's attach-point `.mdx` glows,
-/// spawned under the same attach-point joints as held items, lifetime per the kit stage.
+/// Spell missiles: the projectile a cast with a `Spell.dbc` Speed above 0 flies at each target.
 mod missile;
 use missile::{attach_missile_models, move_missiles, spawn_missiles};
 pub(crate) use missile::{MissileMiss, MissileSound, PendingMissiles};
 
-/// WMO-display GameObject doodad props (the ship's sails / the zeppelin's rotor): the WMO's MODD
-/// M2s spawned as children of the streamed gameobject, so they ride a moving transport.
+/// A WMO-display GameObject's doodad props (a ship's sails), parented under it to ride a transport.
 mod wmo_props;
 use wmo_props::{resolve_wmo_gameobject_props, spawn_wmo_gameobject_props};
 pub(crate) mod spell_fx;
 use spell_fx::{attach_spell_fx, resolve_spell_fx};
 
-/// Dest-anchored spell effects (decision 0797): a DynamicObject's persistent area visuals
-/// (Blizzard's storm, Flamestrike's burn) + the GO dest one-shot burst. (Distinct from
-/// `crate::ground_fx`, the flat-quad decal renderer this lane's models feed into.)
+/// Dest-anchored spell effects: a DynamicObject's area visual and a cast's burst at its point.
 pub(crate) mod dest_fx;
 use dest_fx::{
     arm_ground_effects, attach_ground_fx_models, spawn_ground_bursts, tick_shard_emitters,
 };
 
-/// Spell **chain beams** (decision 0955): the polyline of hops a kit's chain `CharProc` draws —
-/// Chain Lightning's arcs, Drain Life's rope of soul, C'Thun's eye beam. Its geometry rides the
-/// shared effect-quad stream beside the ribbon trails.
+/// Spell chain beams, such as Chain Lightning's arcs.
 mod chain_beam;
 pub(crate) use chain_beam::ChainHops;
 use chain_beam::{simulate_chain_beams, spawn_chain_beams};
-// The container feed reads the icon column off the same catalog resource (one DBC parse).
-// The one InventoryType → equipment-slot table (`attach::preview`): the dressing-room feed places a
-// tried-on item by the very same map the preview it feeds dresses by (decision 1060).
+// `equip_slot` is the one InventoryType → slot table; the dressing room places items by it.
 pub(crate) use attach::{equip_slot, BodyPartsDesc};
 pub(crate) use equipment::ItemDisplays;
 pub(crate) use equipment::{BoneAttach, Equipment};
-// The instruments' read of what a body is actually WEARING vs what it resolved (`WOW_DRESS_CENSUS`).
+// For the `WOW_DRESS_CENSUS` instrument: what a body wears against what it resolved.
 pub(crate) use equipment::{attach_id, DressKey, HeldAttached, ATTACH_SLOT_NAMES};
-// [`DressKey`] carries one of these per weapon slot, but nothing outside this module has to NAME
-// the type to hold or compare a key — only the tests that build one do.
+// Only the tests that build a `DressKey` name this type.
 #[cfg(test)]
 pub(crate) use equipment::ItemModelKind;
 
-/// The overhead attachment slot (`PlayerName`, id 18). The anchor of the overhead name, the
-/// floating combat text, and the questgiver marker alike.
+/// The overhead attachment (`PlayerName`, id 18), where the name, combat text and quest marker sit.
 pub(crate) const ATTACH_OVERHEAD: u16 = 18;
 
-/// Its mounted twin (`PlayerNameMounted`, id 29) — preferred while a mount model is attached
-/// (`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.
+/// The mounted overhead attachment (`PlayerNameMounted`, id 29), on the rider's own model,
+/// preferred while a mount model is attached (`0x6074c0`, `0x608640`).
 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`, 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
-/// ecx,3`), the very handler [`mount::reseat_mounts`] ports — so the reference re-runs the whole
-/// attach, slot choice included, on every mount and dismount. A per-frame *reader*
-/// ([`overhead_anchor`]) gets that for free; a consumer that PARENTS something at the slot
-/// ([`crate::quest_markers`]) has to notice the move and re-parent itself (decision 1871).
+/// The overhead slot for a unit now, the marker attach's pick on the body model (`0x6074c0`): 29
+/// when a mount model exists (`unit+0xdc`) and the body authors it, else 18, else `None` (never
+/// parented). The mount handler re-picks on every mount and dismount (`0x5ffa50` at `0x5ffae7`),
+/// so a consumer parented at the slot must re-parent.
 pub(crate) fn overhead_slot(attach: &BoneAttach, mounted: bool) -> Option<u16> {
     if mounted && attach.points.contains_key(&ATTACH_OVERHEAD_MOUNTED) {
         Some(ATTACH_OVERHEAD_MOUNTED)
@@ -166,82 +116,28 @@ pub(crate) fn overhead_slot(attach: &BoneAttach, mounted: bool) -> Option<u16> {
 /// attachment anchors overhead content at `feet + scale × bbox_z × 1.25`.
 const OVERHEAD_FALLBACK_FACTOR: f32 = 1.25;
 
-/// The unit's **Stand-animation box height** (model-local, pre-scale) — the chat bubble's anchor,
-/// and *only* the chat bubble's (1406).
-///
-/// 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
-/// 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.
+/// The Stand sequence's box height (model-local, pre-scale), the chat bubble's anchor alone. The
+/// reference reads it from the model file's header with no pose (`0x711a20`), once per chat line
+/// (cached at bubble `+0x354`), while the name's anchor is the posed attachment (`0x608640`).
 #[derive(Component)]
 pub(crate) struct StandBoxHeight(pub(crate) f32);
 
-/// The unit's model bbox z-extent (model-local, pre-scale) — stamped by the attach path for
-/// [`overhead_anchor`]'s fallback. `0.0` until the model loads (the fallback then anchors at
-/// feet — the same degenerate the client hits with no model).
+/// The model's bbox z-extent (model-local, pre-scale) for [`overhead_anchor`]'s fallback; `0.0`
+/// until the model loads, which anchors at the feet as the client does with no model.
 #[derive(Component)]
 pub(crate) struct OverheadFallback(pub(crate) f32);
 
-/// The unit's OVERHEAD anchor, world space (`0x608640`, byte-read): the **posed** PlayerName
-/// attachment (slot 29 while a mount model is attached, else 18 — head height, tracking model
-/// stature and the live pose intrinsically), else `feet + scale × bbox_z × 1.25`. Consumed
-/// per-frame by the nameplate and snapshotted at spawn by the floating combat text. Generic over
-/// the joint-globals query filter so a caller that also mutates `GlobalTransform` elsewhere (the
-/// nameplate placer) can pass a disjoint query.
-///
-/// A pure position read: it computes through `RigPose::posed_point` — the composed pose × the
-/// rig root's frame — and never touches an anchor entity, so the overhead bone spawns nothing
-/// (decision 1355).
-///
-/// **The rig root's frame is taken from `tf`, not from its propagated `GlobalTransform`, whenever
-/// the rig root IS the unit** — which is the normal case (a mounted rider's root is the seat
-/// anchor, a conform-tilted model's is its conform node; those two still read the propagated
-/// frame and keep the lag below). Bevy propagates `GlobalTransform` in `PostUpdate`, so an
-/// `Update` reader like the V-plate or the chat bubble gets **last frame's** world frame while the
-/// unit's own `Transform` beside it — and the camera it projects through, and the model being
-/// drawn — are this frame's. Running, that seam is one frame of travel: measured on a Westfall run
-/// (1398), "head above feet" — a body constant — wobbled up to **11.7 px** per frame and 15.1 px
-/// across the leg, and collapsed to 0.02 px the moment the anchor was paired with the position it
-/// was actually computed from. That is the chat bubble sliding against the head the director
-/// reported as jitter, and 1341 cleared the same term for the plate by measuring a unit that was
-/// STANDING STILL, where it is identically zero.
-///
-/// Reading `tf` is exact here because a unit is a world-root entity — nothing in the world lane
-/// parents a `NetEntity` (the `ChildOf` sites are the portrait booth, the pipe-warm menagerie and
-/// 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. 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.
+/// The client's per-attachment z-bias table (`0x862708`, ids `0..=0x24`): how far above the unit's
+/// position a sound plays when its model lacks the attachment asked for.
 const ATTACH_Z_BIAS: [f32; 37] = [
     1.0, 1.0, 1.0, 1.5, 1.5, 1.8, 1.8, 0.5, 0.5, 1.0, 1.0, 2.0, 1.5, 1.0, 1.0, 1.0, 1.0, 2.0, 2.5,
     0.0, 2.0, 1.5, 1.5, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 3.0, 1.5, 1.5, 1.0, 1.0, 1.5, 1.0, 1.0,
 ];
 
-/// **`0x623b90(attachId)` — where a unit-attached sound is born**, as a [`SystemParam`] because
-/// two different routers need the same three pure reads.
-///
-/// [`SystemParam`]: bevy::ecs::system::SystemParam
-///
-/// `AttachPoints::point` returns The attachment's live world
-/// point when the model carries it (`0x712cb0` finds the record, `0x712d50` transforms it), else
-/// the unit's own `GetPosition` raised by [`ATTACH_Z_BIAS`]`[attachId]` (`0x623be2 fadd
-/// [4·ebx + 0x862708]`).
-///
-/// 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 among the unit's anim-event
-/// arms — a player model's six head-mounted `$CSD` records do not decide where that sound plays.
+/// Where a unit-attached sound plays (`0x623b90`): the attachment's live world point when the
+/// model carries it (`0x712cb0`, `0x712d50`), else the unit's position raised by [`ATTACH_Z_BIAS`]
+/// (`0x623be2`). The emote voice `$CSD` asks for 17 (`0x623c3a`) and a whiffed swing's `$CSS` for
+/// 1 (`0x624bdd`), never the fired event's own point.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct AttachPoints<'w, 's> {
     anchors: Query<'w, 's, &'static BoneAttach>,
@@ -250,8 +146,7 @@ pub(crate) struct AttachPoints<'w, 's> {
 }
 
 impl AttachPoints<'_, '_> {
-    /// The world point, with `fallback` standing in for the reference's `GetPosition` (the caller
-    /// already holds the unit's transform, and passing it keeps this a pure read).
+    /// The world point; `fallback` is the unit's position, the reference's `GetPosition`.
     pub(crate) fn point(&self, entity: Entity, attach: u16, fallback: Vec3) -> Vec3 {
         self.anchors
             .get(entity)
@@ -267,6 +162,13 @@ impl AttachPoints<'_, '_> {
     }
 }
 
+/// The unit's overhead anchor in world space (`0x608640`): the posed PlayerName attachment (29
+/// while a mount model is attached, else 18), else `feet + scale × bbox_z × 1.25`.
+///
+/// When the rig root is the unit itself its frame comes from `tf`, not the `GlobalTransform` Bevy
+/// propagates in `PostUpdate`, which an `Update` reader sees a frame late (the chat bubble slid
+/// against the head). That is exact because a streamed unit is a world-root entity; a mounted
+/// rider or a conform-tilted model, rooted elsewhere, still reads the late propagated frame.
 pub(crate) fn overhead_anchor<F: bevy::ecs::query::QueryFilter>(
     entity: Entity,
     tf: &Transform,
@@ -297,34 +199,24 @@ pub(crate) fn overhead_anchor<F: bevy::ecs::query::QueryFilter>(
         })
 }
 
-/// The child mesh spawned by the fallback-cube arm of [`attach::attach_entity_visuals`] — "this
-/// entity's display named no model we could load".
-///
-/// A marker, so the condition is **countable** rather than eyeballed: `WOW_UNIT_VISUALS`
-/// ([`crate::capture::probes::UnitVisualsPlugin`]) reports how many streamed entities are standing
-/// as cubes, and on which displays. Before decision 1403 a cube also stood for every invisible
-/// trigger creature, which is what B13 saw as a black slab — an unlit `StandardMaterial` catches no
-/// light in our scene, so the "red" NPC box renders pure black. The census is how that stays
-/// visible if the gate ever regresses.
+/// Marks the cube spawned for an entity whose display named no loadable model, so
+/// `WOW_UNIT_VISUALS` can count the cubes and their displays.
 #[derive(Component)]
 pub(crate) struct FallbackCube;
 
-/// Shared fallback cube mesh + per-kind materials, used when an entity has no usable model. (No
-/// GameObject color: GameObjects render their model or nothing — a model-less GameObject is an
-/// effect/trigger that's invisible in the real client.)
+/// The fallback cube mesh and per-kind materials. There is no GameObject cube: a model-less
+/// GameObject is an invisible effect or trigger in the reference.
 #[derive(Resource)]
 pub(crate) struct CubeAssets {
     mesh: Handle<Mesh>,
-    /// Slimmer, shorter block for a player whose body model isn't available (smaller than the NPC box).
+    /// The slimmer block for a player whose body model is unavailable.
     player_mesh: Handle<Mesh>,
     player_mat: Handle<StandardMaterial>,
     npc_mat: Handle<StandardMaterial>,
 }
 
 impl CubeAssets {
-    /// The pipeline-warm rig parts ([`crate::pipe_warm`], decision 0938): the production cube
-    /// mesh + both materials, so the fallback-cube pipeline compiles behind the cover instead of
-    /// on the first model-less spawn in view.
+    /// The cube mesh and materials, for [`crate::pipe_warm`] to compile behind the loading cover.
     pub(crate) fn warm_parts(&self) -> (Handle<Mesh>, [Handle<StandardMaterial>; 2]) {
         (
             self.mesh.clone(),
@@ -333,8 +225,7 @@ impl CubeAssets {
     }
 }
 
-/// Creature rendering: the display→model catalog + a per-display [`DisplayModel`] cache. Optional — if
-/// the DBCs fail to load, NPCs stay cubes.
+/// The creature display catalog and per-display [`DisplayModel`] cache; absent, NPCs are cubes.
 #[derive(Resource)]
 pub(crate) struct Creatures {
     catalog: CreatureCatalog,
@@ -342,84 +233,63 @@ pub(crate) struct Creatures {
 }
 
 impl Creatures {
-    /// A display's **foley material** (`Material.dbc` id) — the creature half of the footfall
-    /// rustle; see [`benilla_formats::CreatureCatalog::foley_material`] and
-    /// [`crate::sound::footsteps`]. `None` for an unknown display.
+    /// A display's foley material (`Material.dbc` id), the creature half of the footfall rustle.
     pub(crate) fn foley_material(&self, display_id: u32) -> Option<u32> {
         self.catalog.foley_material(display_id)
     }
 
-    /// A display's collision height in **raw model units** — see [`CollisionHeight`] for the world
-    /// value and everything that reads it. `None` for an unknown display.
+    /// A display's collision height in raw model units; [`CollisionHeight`] is the world value.
     pub(crate) fn collision_height(&self, display_id: u32) -> Option<f32> {
         self.catalog.collision_height(display_id)
     }
 
-    /// A display's footprint-decal parameters (yards, pre-scale) — `None` = this model leaves no
-    /// prints. See [`benilla_formats::CreatureCatalog::footprint`].
+    /// A display's footprint-decal parameters (yards, pre-scale); `None` leaves no prints.
     pub(crate) fn footprint(&self, display_id: u32) -> Option<benilla_formats::FootprintParams> {
         self.catalog.footprint(display_id)
     }
 
-    /// Does this display's model breathe — may it wear the `$BTH` puffs (cold vapour, bubbles)?
-    /// `CreatureModelData.Flags & 0x2` suppresses the family: skeletons, ghosts, elementals,
-    /// golems, slimes, totems. See [`benilla_formats::CreatureCatalog::breathes`].
+    /// Whether the model wears `$BTH` breath puffs, which `CreatureModelData.Flags & 0x2` stops.
     pub(crate) fn breathes(&self, display_id: u32) -> bool {
         self.catalog.breathes(display_id)
     }
 
-    /// A display's **base render alpha** (`CreatureDisplayInfo.CreatureModelAlpha / 255`) — the
-    /// `baseAlpha` factor of the per-unit alpha product the aura CharProc nodes multiply into
-    /// (`crate::aura_visual`). `None` for an unknown display.
+    /// A display's `CreatureModelAlpha / 255`, the aura layer's `baseAlpha`.
     pub(crate) fn display_base_alpha(&self, display_id: u32) -> Option<f32> {
         self.catalog.display_base_alpha(display_id)
     }
 
-    /// A display's **footstep camera-shake preset** (`CameraModelData.FootstepShakeSize` → a
-    /// `CameraShakes.dbc` row id) — see [`crate::camera_shake`]. `None` for the 405 of 430 shipped
-    /// models that shake nothing.
+    /// A display's footstep camera shake (`FootstepShakeSize`); `None` for 405 of 430 models.
     pub(crate) fn footstep_shake(&self, display_id: u32) -> Option<u32> {
         self.catalog.footstep_shake(display_id)
     }
 
-    /// A display's **death-thud camera-shake preset** — same table, fired on `$DTH`.
+    /// A display's death-thud camera shake (`DeathThudShakeSize`), fired on `$DTH`.
     pub(crate) fn death_thud_shake(&self, display_id: u32) -> Option<u32> {
         self.catalog.death_thud_shake(display_id)
     }
 
-    /// A display's **audible size class** (`0 Small`..`4 Colossal`) — the axis the body-fall
-    /// sample is picked on (`crate::sound::death_thud`). The display's own column overrides the
-    /// model's; see [`benilla_formats::CreatureCatalog::size_class`].
+    /// A display's audible size class (0 Small to 4 Colossal), which picks the body-fall sample.
     pub(crate) fn size_class(&self, display_id: u32) -> Option<u32> {
         self.catalog.size_class(display_id)
     }
 
-    /// A display's **spawned-creature render scale** — see
-    /// [`benilla_formats::CreatureCatalog::model_scale`] for why almost nothing reads it and why
-    /// the glue screens' pet must. `None` for an unknown display.
+    /// A display's `modelScale × creatureModelScale`; only the glue screens' pet reads it, as the
+    /// server folds it into a spawned unit's `OBJECT_FIELD_SCALE_X`.
     pub(crate) fn model_scale(&self, display_id: u32) -> Option<f32> {
         self.catalog.model_scale(display_id)
     }
 
-    /// A display's two **blood-row candidates** — `CreatureDisplayInfo.BloodLevel` and
-    /// `CreatureModelData.BloodID`, tiers 1 and 2 of the reference's UnitBloodLevels resolve.
-    /// `None` = unknown display. The tiers themselves need the table, so they live in
-    /// [`benilla_formats::BloodCatalog::level_key`] — which is where tier 3 is, and 1850's whole
-    /// point is that tier 3 is not optional.
+    /// `CreatureDisplayInfo.BloodLevel` and `CreatureModelData.BloodID`, the reference's blood
+    /// tiers 1 and 2; [`benilla_formats::BloodCatalog::level_key`] adds tier 3.
     pub(crate) fn blood_candidates(&self, display_id: u32) -> Option<(i32, i32)> {
         self.catalog
             .model(display_id)
             .map(|m| (m.blood_display, m.blood_model))
     }
 
-    /// 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]`,
-    /// `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).
+    /// A built display's booth framing (model-local, pre-scale): its authored cameras, index 0 of
+    /// `cameraLookup` for the round portrait (`0x713540`) and raw index 1 for a `<PlayerModel>`
+    /// pane (`0x505890`), with each path's fallback for a model that has none.
     pub(crate) fn display_anchors(
         &self,
         display_id: u32,
@@ -436,21 +306,9 @@ impl Creatures {
         })
     }
 
-    /// A built display's **mirror lists** — the same `(PortraitPart, PortraitBillboard)` pair a
-    /// dressed unit's attach-spawned descendants carry, assembled straight from the display cache
-    /// for a creature that has **no world entity at all**: the stable window's stabled pet
-    /// ([`crate::portrait::PortraitStandIn`]).
-    ///
-    /// The split is [`crate::entities::attach::preview`]'s `assemble_pet` law verbatim — every
-    /// batch of the model, camera-facing ones separated out — because it is the same question:
-    /// only the character compositor selects among geosets, and a creature is not a character
-    /// model, so the world's creature path draws every batch of a beast the same way. The
-    /// billboards seat at [`crate::portrait::PortraitSeat::Body`] (the model's own rigged batch:
-    /// its bone's booth joint already bakes the pivot, the 0130 rig identity) with `attach: None`,
-    /// which is exactly what a host model's own batch is.
-    ///
-    /// `None` while the display's model is still loading — the same gate [`Self::display_rig`] and
-    /// [`Self::display_anchors`] apply, so all three become available together.
+    /// A built display's `(PortraitPart, PortraitBillboard)` lists, straight from the cache, for a
+    /// creature with no world entity ([`crate::portrait::PortraitStandIn`]): every batch, the
+    /// camera-facing ones as cards, since only the character compositor selects geosets.
     pub(crate) fn display_mirror(
         &self,
         display_id: u32,
@@ -481,11 +339,8 @@ impl Creatures {
         Some((meshes, cards))
     }
 
-    /// A built display's **booth rig** — what the portrait booth needs to pose a fresh instance at
-    /// 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).
+    /// A built display's rig, for the booth to pose a fresh instance at Stand as the reference's
+    /// bake does (`0x524f60`), not the unit's live pose; a WMO display's skeleton is empty.
     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
@@ -500,49 +355,36 @@ impl Creatures {
 /// The skeleton/animation surface the portrait booth poses a bake with ([`Creatures::display_rig`]).
 pub(crate) struct DisplayRig<'a> {
     pub(crate) skeleton: &'a benilla_assets::ModelSkeleton,
-    /// The shared inverse bind poses — `Some` for every M2 display (built at load), `None` only for
-    /// WMO / model-less displays (whose skeletons are empty anyway).
+    /// `None` only for a WMO or model-less display, whose skeleton is empty.
     pub(crate) inverse_bindposes: Option<Handle<bevy::mesh::skinning::SkinnedMeshInverseBindposes>>,
     pub(crate) animations: Option<&'a benilla_assets::ModelAnimations>,
 }
 
-/// GameObject rendering: the GameObjectDisplayInfo catalog + a per-display [`DisplayModel`] cache. Same
-/// fallback rules as [`Creatures`]; a model-less GameObject renders nothing (effect/trigger).
+/// The `GameObjectDisplayInfo` catalog and per-display [`DisplayModel`] cache.
 #[derive(Resource)]
 struct GameObjects {
     catalog: GameObjectCatalog,
     models: HashMap<u32, DisplayModel>,
 }
 
-/// Character geoset selection (decision 0041, Milestone B): the customization → visible-geoset tables.
-/// Optional — if the DBCs fail to load, players simply render every geoset (the un-filtered body), the
-/// same as before this feature.
+/// The customization → visible-geoset tables; without them players render every geoset.
 #[derive(Resource)]
 struct Characters(CharacterGeosets);
 
-/// Character skin textures (decision 0041, Milestone B): the CharSections base-skin lookup. Optional —
-/// if it fails to load, a player's body-skin batches stay untextured (the muted fallback), as before.
+/// The `CharSections` skin lookup; without it a player's body skin stays untextured.
 #[derive(Resource)]
 struct SkinSections(CharSections);
 
-/// Character-creation source data (decision 0423): per-race body displayIds, race/class combos, and
-/// the appearance-dial ranges. Read by the glue-preview builder ([`attach`]) — displayId +
-/// look — and by the char-create screen. Optional — absent ⇒ the create screen has no data (it
-/// degrades to disabled), but the rest of the game is unaffected.
+/// Character-creation data (body displays, race and class combos, appearance ranges).
 #[derive(Resource)]
 pub(crate) struct CharCreate(pub(crate) CharCreateCatalog);
 
-/// Per-appearance cache of composited body-skin atlases (decision 0044): each distinct character look
-/// composites + uploads its 256² skin once, and every player sharing that look reuses the handle. A
-/// composite is a fresh `Image` asset per build (unlike an `asset_server.load` path, which dedups by
-/// path), so without this cache every player would re-composite and break material dedup downstream.
+/// Composited body skins by look, so every player wearing a look shares one 256² atlas.
 #[derive(Resource, Default)]
 struct SkinComposites(benilla_assets::SpatialCache<SkinKey, Handle<Image>>);
 
-/// The appearance fields that determine a composited body skin (decision 0044): race/sex pick the
-/// CharSections rows; skin/face/facialHair/hairStyle/hairColor pick the base + overlay variations;
-/// `equip` (decision 0074) the worn armor display ids whose region textures paint over it, by
-/// bodyslot−2 — so each distinct dressed look composites + uploads once.
+/// What decides a composited body skin: race and sex pick the `CharSections` rows, the dials pick
+/// the variations, and `equip` holds the worn armour display ids by body slot − 2.
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 pub(super) struct SkinKey {
     pub(super) race: u8,
@@ -553,41 +395,26 @@ pub(super) struct SkinKey {
     pub(super) hair_style: u8,
     pub(super) hair_color: u8,
     pub(super) equip: [u32; 8],
-    /// The wearer's guild tabard (decision 1704) — part of the key, not of `equip`, because two
-    /// guilds' members wear the *same* tabard display and must not share one atlas. Without it the
-    /// first guild to composite would lend its crest to every other guild on screen.
+    /// The guild emblem: two guilds' members wear one tabard display but must not share an atlas.
     pub(super) emblem: Option<benilla_formats::GuildEmblem>,
-    /// The tabard designer's preview flag (1977): the emblem paints over an empty tabard slot.
+    /// The tabard designer's preview: the emblem paints over an empty tabard slot.
     pub(super) tabard_preview: bool,
 }
 
-/// Marks a net entity whose visual (model children or fallback cube) has been attached, so the attach
-/// system processes each entity exactly once. `pub(crate)`: the `waterfx` capture rig pre-marks its
-/// dummy unit so it never receives the fallback cube (which would occlude the foam under test).
+/// Marks a net entity whose visual is attached; the `waterfx` rig pre-marks its dummy unit.
 #[derive(Component)]
 pub(crate) struct VisualAttached;
 
-/// The per-frame entity-visuals pipeline (resolve → build → attach → held → refresh) as one set, so
-/// upstream writers can order themselves before the whole chain — the animation driver's
-/// [`crate::creature_anim::VisualSheath`] must land before [`resolve_equipment`] reads it, or a
-/// sheath transition double-swaps the weapon placement for a frame (the "flash").
+/// The per-frame entity-visuals chain as one set; [`crate::creature_anim::VisualSheath`] must land
+/// before it, or a sheath change places the weapon twice in one frame.
 #[derive(SystemSet, Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub(crate) struct EntityVisualsSet;
 
-/// [`update_display_models`]' ordering handle: anything that must **create** a display-cache entry
-/// in time for this frame's build orders before it.
-///
-/// It exists for one caller, the `fxview` fixture's driver — which registers itself against this
-/// from `capture` rather than being listed in the chain above, because a fixture's driver belongs
-/// with its fixture and gameplay may not name the harness (decisions 1173/1174). Same shape as the
-/// `waterfx` fixture's registration against the engine's `WaterFoamSet`.
+/// [`update_display_models`]' set: a creator of display-cache entries orders before it.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct DisplayBuildSet;
 
-/// Drop every display/material dedup on a cross-map transition (`world_map::MapChange` — see its
-/// doc for why a clear is always safe mid-session). These caches are get-or-insert at every use
-/// site, so a cleared entry rebuilds on the next spawn that wants it; without this, every display
-/// id, material key, and composited skin ever seen stayed resident for the life of the process.
+/// Drop every display and skin cache on a map change; an entry rebuilds on its next use.
 fn evict_display_caches(
     mut changes: MessageReader<benilla_world::world_map::MapChange>,
     mut composites: ResMut<SkinComposites>,
@@ -596,8 +423,6 @@ fn evict_display_caches(
     gos: Option<ResMut<GameObjects>>,
     items: Option<ResMut<equipment::ItemDisplays>>,
     glows: Option<ResMut<ItemGlows>>,
-    // The bone-pile bodies (decision 1706) — 16 at most, but they hold M2 handles like any other
-    // display cache and must die with the map for the same reason (the teleport asset leak).
     mut bones: ResMut<corpse::BonesModels>,
 ) {
     if changes.is_empty() {
@@ -630,12 +455,8 @@ fn evict_display_caches(
     bones.0.clear();
 }
 
-/// Expire the streamed-entity dedups by **distance** (decision 0793) — the within-map half of
-/// [`evict_display_caches`]. The composited skins are the notable half: each distinct dressed look is
-/// its own 256² `Image` (decision 0044), so a session that meets a lot of players accumulates
-/// uploads no map change ever reaches. The display-id → model caches (`Creatures`/`GameObjects`/
-/// `ItemDisplays`/`SpellFx`) are deliberately *not* swept: they key on ids, not places, and hold M2
-/// assets whose count is bounded by the catalogs rather than by where you have been.
+/// Expire composited skins by distance within a map. The display-id model caches are not swept:
+/// they key on ids, not places, so the catalogs bound them.
 fn scope_entity_art(
     mut scope: benilla_world::art_scope::ArtScope,
     mut composites: ResMut<SkinComposites>,
@@ -643,19 +464,12 @@ fn scope_entity_art(
     scope.apply(&mut composites.0, benilla_world::art_scope::ArtSlot::Skins);
 }
 
-/// **The armed idle's authored CAaBox for a built body**, model space — recorded by
-/// [`attach_entity_visuals`] where the display model is read, and restated onto
-/// [`WorldUnit::bound`](benilla_world::world_unit::WorldUnit::bound) by [`publish_world_units`].
-///
-/// Split from the field it feeds for the same reason `CollisionHeight` is: the attach knows the
-/// number, the reconciler owns the component, and one writer per component is decision 0025. Absent
-/// until a body's model resolves — and on a body that never gets one, absent for good.
+/// A built body's armed-idle box in model space, which [`publish_world_units`] restates as
+/// `WorldUnit::bound`; absent until the model resolves.
 #[derive(Component, Clone, Copy)]
 pub(crate) struct ModelBound(pub(crate) bevy::camera::primitives::Aabb);
 
-/// Everything [`publish_world_units`] reads to restate one body: its wire record, the two
-/// game-side components whose numbers it folds in, whether its `Visibility` is the transport
-/// tick's, and what it currently says.
+/// What [`publish_world_units`] reads to restate one body.
 type WireBody = (
     Entity,
     &'static NetEntity,
@@ -665,21 +479,18 @@ type WireBody = (
     Option<&'static benilla_world::world_unit::WorldUnit>,
 );
 
-/// One viewer-reconcile row: the entity, whether it is the embodied self, whether it is marked.
 type ViewerRow = (
     Entity,
     Has<crate::net::Embodied>,
     Has<benilla_world::world_unit::ViewerUnit>,
 );
 
-/// Only entities that can be a viewer at all — one of the two markers present.
 type ViewerCandidate = Or<(
     With<crate::net::Embodied>,
     With<benilla_world::world_unit::ViewerUnit>,
 )>;
 
-/// The edges on which a body's [`WorldUnit`](benilla_world::world_unit::WorldUnit) restatement can
-/// move — [`publish_world_units`]' query filter (the anchor's removal is read separately).
+/// The edges that can move a body's restatement; a removed transport anchor is read separately.
 type WireBodyMoved = Or<(
     Changed<NetEntity>,
     Changed<collision_height::CollisionHeight>,
@@ -687,25 +498,16 @@ type WireBodyMoved = Or<(
     Added<crate::transport::TransportAnchor>,
 )>;
 
-/// **Restate every wire body as a [`WorldUnit`](benilla_world::world_unit::WorldUnit)** — the game's half
-/// of the unit inversion (see that module).
-///
-/// One reconciler rather than a line at each of the dozen sites that spawn a `NetEntity`: a
-/// spawn path that forgets the marker is a body the world cannot see — no ground shade, no room
-/// claim, no foam — and that is exactly the kind of omission nobody notices until a screenshot.
-/// Runs between the wire drain and the rest of the frame, so a unit that arrived this frame is
-/// visible to the world this frame.
+/// Restate every wire body as a [`WorldUnit`](benilla_world::world_unit::WorldUnit), in one
+/// reconciler rather than at each spawn site. Runs right after the wire drain, so a unit that
+/// arrived this frame is visible to the world this frame.
 fn publish_world_units(
     mut commands: Commands,
-    // Only bodies whose inputs moved this frame: the restatement is a pure function of these
-    // four, and walking every resident body to compare equal answers was ~1.3 k struct builds
-    // a frame at the Stormwind pin (decision 1979's floor). A body leaving its transport loses
-    // the anchor without a `Changed` — that edge is read off `unanchored`.
+    // Only bodies whose inputs moved; leaving a transport removes the anchor with no `Changed`,
+    // so that edge comes from `unanchored`.
     bodies: Query<WireBody, WireBodyMoved>,
     all_bodies: Query<WireBody>,
     mut unanchored: RemovedComponents<crate::transport::TransportAnchor>,
-    // Only entities that can be a viewer at all: the reconcile below needs one of the two
-    // present, and an unfiltered query walked every entity in the world each frame.
     viewers: Query<ViewerRow, ViewerCandidate>,
 ) {
     let freed: Vec<Entity> = unanchored.read().collect();
@@ -714,29 +516,16 @@ fn publish_world_units(
         .chain(freed.iter().filter_map(|&e| all_bodies.get(e).ok()));
     for (entity, net, height, bound, anchored, current) in due {
         let want = benilla_world::world_unit::WorldUnit {
-            // The wire kind is answered HERE and never handed over (1177): the engine asks "does
-            // this body displace water", and translating its own vocabulary into that answer is
-            // the game's job. A live body wades; a GameObject, a dynamic-object spell anchor or
-            // anything else standing in a lake makes no ripple.
+            // A live body wades; a GameObject or dynamic object standing in a lake makes no ripple.
             wades: matches!(net.kind, EntityKind::Unit | EntityKind::Player),
             scale: net.scale,
-            // `unwrap_or_default`, NOT zero: `CollisionHeight`'s Default is the client's own
-            // ctor value, and its doc says why — at 0.0 "every depth line collapses and the unit
-            // swims on dry land". A body whose display has not resolved yet must read as a
-            // default-sized body, which is what the foam site did before this component existed.
+            // The client's constructor default until the display resolves, never 0.0, at which
+            // every depth line collapses.
             height: height.copied().unwrap_or_default().0,
-            // The box the exterior cull may elect this body by (decision 1270). **A transport
-            // answers `None` on purpose**: `transport::tick_transports` writes that root's
-            // `Visibility` every frame off its own timetable, and a second writer there is the
-            // fight decision 0025 exists to prevent — so the world is told not to decide, rather
-            // than told a box and left to race.
-            //
-            // Every other body is elected from its FIRST frame, with a degenerate box at its own
-            // origin until its model resolves. Waiting for the extent looks conservative and is
-            // not: the bound reaches this reconciler only after `attach_entity_visuals` has already
-            // spawned the visual, so "no box yet ⇒ admit" drew every streaming mob for one whole
-            // frame through a sealed ceiling — and a cavern runs slowly enough that one frame is
-            // most of a second. The origin is the server's own position, exact from the start.
+            // The box the exterior cull elects this body by. A transport answers `None`, as
+            // `transport::tick_transports` alone writes its `Visibility`. Every other body is
+            // elected from its first frame, on a point box at its origin until the model
+            // resolves, so a streaming mob is never drawn through a sealed ceiling.
             bound: (!anchored).then(|| {
                 bound.map_or_else(
                     || bevy::camera::primitives::Aabb::from_min_max(Vec3::ZERO, Vec3::ZERO),
@@ -744,8 +533,7 @@ fn publish_world_units(
                 )
             }),
         };
-        // Only write on a real change: the component is change-detected downstream, and a
-        // per-frame rewrite would mark every body dirty for every reader every frame.
+        // Written only on a real change: its readers are change-detected.
         let same = current.is_some_and(|c| {
             c.wades == want.wades
                 && c.scale == want.scale
@@ -756,8 +544,8 @@ fn publish_world_units(
             commands.entity(entity).insert(want);
         }
     }
-    // The viewer marker is reconciled independently of `NetEntity`: the self entity exists before
-    // its wire record does, and a `/logout` takes the record away first.
+    // Reconciled apart from `NetEntity`: the self entity exists before its wire record and
+    // outlives it on `/logout`.
     for (entity, is_self, marked) in &viewers {
         match (is_self, marked) {
             (true, false) => {
@@ -775,8 +563,7 @@ fn publish_world_units(
     }
 }
 
-/// The streamed-entity subsystem: builds the shared cube assets + display catalogs at startup, then
-/// each frame resolves/builds display models and attaches a visual to every net entity.
+/// Loads the display catalogs at startup and each frame gives every net entity its visual.
 pub(crate) struct EntitiesPlugin;
 
 impl Plugin for EntitiesPlugin {
@@ -789,121 +576,71 @@ impl Plugin for EntitiesPlugin {
         )
         .init_resource::<SkinComposites>()
         .init_resource::<attach::MergedFormsCache>()
-        // The 16 bone-pile body models (decision 1706), keyed (race, sex) rather than by a
-        // display id — a skeleton has no CreatureDisplayInfo row.
+        // The 16 bone-pile bodies, keyed by (race, sex): a skeleton has no display row.
         .init_resource::<corpse::BonesModels>()
         .init_resource::<spell_fx::SpellFx>()
         .init_resource::<spell_fx::FxTintAnims>()
         // The per-caster pending-projectile queues (the client's `unit+0xac` lists).
         .init_resource::<missile::PendingMissiles>()
-        // The projectile flight-loop edges (`crate::sound::missile` consumes them).
         .add_message::<MissileSound>()
-        // A travelling spell's DEFERRED outcome word (`crate::combat_text`, decision 2229).
         .add_message::<MissileMiss>()
-        // The cast router's dest one-shot orders (`dest_fx`, decision 0797).
         .add_message::<dest_fx::GroundBurst>()
-        // A live display-id swap's rebuild edge — consumed by the morph-latch replay
-        // (`crate::creature_anim`), the reference's `0x60abe0` impact-kit replay tail.
+        // A display swap's rebuild edge, for the impact-kit replay the reference runs at the end
+        // of `0x60abe0`.
         .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 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
-        // consumers all read `Option<&CollisionHeight>` against the ctor default, so a unit's
-        // first frame simply uses that — see `CollisionHeight`.
+        // After the net stage, whose Commands create the entity; until then its readers take the
+        // constructor default.
         .add_systems(Update, stamp_collision_heights.after(WorldStage::Net))
-        // Resolve/build display models before attaching, so a model is ready the frame attach wants it.
-        // **After `WorldStage::Net`**: `apply_net_updates` spawns the entities (via Commands), so
-        // these must run *after* that stage — with the sync point it forces — or they'd attach an
-        // entity the same frame its display id is still unresolved (`dm == None`) and lock in a cube.
-        // The net stage was previously unordered (`schedule.rs` chained only Input→Stream→Present), so
-        // this held only by luck of Bevy's auto-sort; pinning it makes display resolution deterministic.
+        // Display models resolve and build before attach, all after `WorldStage::Net` spawns the
+        // entities, or attach would meet an unresolved display and lock in a cube.
         .add_systems(
             Update,
             (
-                // Equipment resolution first (decisions 0072/0074): it *creates* item
-                // DisplayModel entries, which update_display_models then builds the same frame.
-                // The corpse's dress rides beside it (decision 1706, one nested unordered
-                // element — the outer tuple is at `chain()`'s 20-element ceiling): a disjoint
-                // entity set, the same item-model cache, the same must-be-before-the-build.
+                // Equipment resolution creates the item display entries built the same frame.
+                // The nested tuples are unordered groups: the outer tuple is at `chain()`'s
+                // 20-element ceiling.
                 (resolve_equipment, resolve_corpse_equipment),
-                // Spell-effect resolution likewise creates its path-keyed entries (0099 P3),
-                // as does the missile launcher (P4) — both feed the same SpellFx model cache.
+                // Spell effects and missiles create `SpellFx` entries too.
                 resolve_spell_fx,
                 move_missiles,
                 spawn_missiles,
-                // The dest-anchored lane (0797): the dynobj arm + the GO burst + the shard
-                // tick all create cache entries too — before the same-frame build below.
-                // One nested (unordered) element: three independent producers, and the
-                // outer tuple is at `chain()`'s 20-element ceiling.
+                // The dest-anchored lane's three independent producers also create entries.
                 (arm_ground_effects, spawn_ground_bursts, tick_shard_emitters),
                 update_display_models.in_set(DisplayBuildSet),
-                // The char-create preview (decision 0423): assemble the selected look's parts from
-                // the freshly-built display model, for the create booth to bake. After
-                // `update_display_models` (its want-list built the body) — server-less, at char select.
+                // The glue screens' character, assembled from the display built just above.
                 build_glue_preview,
-                // …and the select screen's PET beside it: an ordinary creature display, assembled
-                // off the same freshly-built cache, on its own latch so a slow pet model never
-                // holds the character back.
+                // The select screen's pet, on its own latch so a slow pet model never holds the
+                // character back.
                 build_glue_pet,
-                // The dressing room's preview (decision 1060): the same tuple-driven assembly,
-                // for the item nobody in the world is wearing. Beside the glue one — same
-                // dependency (the display cache built by `update_display_models` above), same
-                // retry-until-ready latch.
+                // The dressing room's preview, the same assembly and latch.
                 build_dressup_preview,
                 attach_entity_visuals,
-                // WMO-gameobject doodad props (the ship's sails): resolve the MODD list the
-                // frame after the WMO visual attaches, then spawn each prop as its M2 lands
-                // (parented under the entity — they sail with the boat).
+                // A WMO GameObject's doodad props, spawned as each M2 lands.
                 resolve_wmo_gameobject_props,
                 spawn_wmo_gameobject_props,
                 attach_held_items,
-                // One nested (unordered) element — the two passes that hang effect models on
-                // a unit: its spell-kit instances, and the glows its held items' `ItemVisuals`
-                // ids name (0805 — after `attach_held_items`, which makes the item roots).
-                // Independent of each other, both before the tint tick below; the outer tuple
-                // is at `chain()`'s 20-element ceiling.
+                // Spell-kit effect models and held-item glows, after the item roots exist.
                 (attach_item_glows, attach_spell_fx),
-                // One nested (unordered) element — two independent free-model attach
-                // passes, plus the world-plant tender (0850: sweeps orphaned plants,
-                // re-plants root-aura ones on owner displacement); the outer tuple is at
-                // `chain()`'s 20-element ceiling.
                 (
                     attach_missile_models,
                     attach_ground_fx_models,
                     spell_fx::tend_world_plants,
                 ),
-                // Tick the live per-instance tint clones AFTER the attach passes registered
-                // them, so a clone's first drawn frame is already on its own clock.
+                // After attach, so a tint clone's first drawn frame is on its own clock.
                 spell_fx::tick_fx_tint,
-                // Fire each live instance's crossed event keyframes (decision 0304) — after
-                // attach so a just-spawned instance's head window [0, cur] fires this frame.
-                // Beside it (one nested, unordered element — the outer tuple is at `chain()`'s
-                // 20-element ceiling): the effect-model completion callbacks, which advance an
-                // instance birth → Hold and arm the reap's Decay. Independent of the event
-                // scan; both only read a player Bevy already advanced in `PreUpdate`, and both
-                // want to run after the attach passes so a fresh instance is covered at once.
+                // Event keyframes and completion callbacks, after attach so a just-spawned
+                // instance's first window `[0, cur]` fires this frame.
                 (spell_fx::fire_fx_anim_events, spell_fx::advance_fx_anim),
-                // One nested (unordered) element — the outer tuple is at `chain()`'s
-                // 20-element ceiling. Two independent post-attach touch-ups on a standing
-                // visual: a gear change re-dresses it in place — a re-composited atlas on the
-                // same parts, the equipment geosets re-selected, every attachment left alone
-                // (decision 0835, the reference's own shape) — and a freshly attached corpse
-                // arms its settled Dead/Drowned pose (decision 1706).
+                // A gear change re-dresses the standing visual in place, every attachment left
+                // alone as in the reference; a new corpse arms its Dead or Drowned pose.
                 (attach::redress_player_looks, corpse::pose_corpses),
-                // A mount transition does the same, and for the same reason (B199): the
-                // field diff **re-seats** the standing rig — onto the mount's attachment-0
-                // joint, or back onto its own frame — where it used to tear the whole rider
-                // down and let attach rebuild it. The reference re-parents the body model
-                // (`0x712f70`/`0x713020`); it never re-creates it.
+                // A mount change re-seats the rig on the mount's attachment 0 or back, as the
+                // reference re-parents the body model (`0x712f70`, `0x713020`).
                 reseat_mounts,
-                // A live display-id / scale change (decision 0695): the display swap is the
-                // same teardown-and-rebuild; the scale change arms the reference's 2 s ease.
-                // The rig heal (decision 0863) rides the same nest (Bevy's 20-tuple ceiling):
-                // a unit denied a palette rig at attach rebuilds — the same teardown — once
-                // the table has headroom again; never a permanent statue.
+                // A display swap rebuilds, a scale change eases over the reference's 2 s, and a
+                // unit denied a palette rig rebuilds once the table has room.
                 (
                     refresh_live_display,
                     tick_scale_ease,
@@ -915,25 +652,16 @@ impl Plugin for EntitiesPlugin {
                 .in_set(EntityVisualsSet)
                 .after(WorldStage::Net),
         )
-        // The chain-beam spawner (0955): in the visuals set, so the cast router — which is
-        // `.before(EntityVisualsSet)` — has already emitted this frame's beam plays, and the
-        // net stage's Commands (the hop arrays) have already been applied.
+        // In the visuals set, after the cast router's beam plays and the net stage's hop arrays.
         .add_systems(
             Update,
             spawn_chain_beams
                 .in_set(EntityVisualsSet)
                 .after(WorldStage::Net),
         )
-        // …and its per-frame geometry, beside the ribbon trails and for the same reason: a
-        // beam's endpoints are attachment joints, so it must sample the pose the billboard
-        // palette and the rig finalizer just wrote.
-        //
-        // `.after(begin_effect_frame)` is the load-bearing one, and its omission is what made
-        // the whole beam invisible on first ship (B161): the clear carries an extra
-        // `.after(face_billboards)` the beam sim does not, so without this edge the sim
-        // becomes runnable a step EARLIER and its vertices are wiped before extract — every
-        // frame, silently, with the arithmetic perfect. Every writer into the shared stream
-        // declares this; the tripwire in `commit` now refuses a write that precedes the clear.
+        // The beam's endpoints are attachment joints, sampled from the pose the billboard
+        // palette and the rig finalizer just wrote. `.after(begin_effect_frame)` is load-bearing:
+        // without it the shared effect stream's clear can run after the sim and wipe the beam.
         .add_systems(
             PostUpdate,
             simulate_chain_beams
@@ -942,17 +670,14 @@ 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 `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.
+        // Terrain conform (`0x614cd0` → `0x7106c0`), before propagation so the globals carry this
+        // frame's tilt.
         .add_systems(
             PostUpdate,
             conform::conform_units.before(bevy::transform::TransformSystems::Propagate),
         )
-        // The unit lane's material-alpha compose: after every steady-state owner of the
-        // render-alpha field (the interior classifier, the visibility authority's own
-        // fade/effect writes), before the self-avatar feather that is allowed to override it.
+        // After every steady-state writer of the render-alpha field, before the self-avatar
+        // feather that overrides it.
         .add_systems(
             Update,
             apply_unit_mat_alpha
@@ -961,20 +686,16 @@ impl Plugin for EntitiesPlugin {
                 .after(apply_render_fade)
                 .before(crate::player::apply_self_model_fade),
         )
-        // The aura CharProc layer (`crate::aura_visual`): the state kit's effect on the BODY.
-        // The drain installs/removes this frame's nodes; the author then owns the render alpha
-        // of every part under a translucent unit — after the three steady-state alpha authors
-        // above so its override lands, before the self feather which folds the factor in itself.
+        // The aura CharProc layer (`crate::aura_visual`), after the steady-state alpha writers so
+        // its override lands, before the self feather, which folds the aura factor in itself.
         .add_systems(
             Update,
             (
-                // The display's own base alpha first (the reference's DISPLAYID-watcher leg
-                // `0x604990` of the same recompute `0x60d180` — no aura needed), so a
-                // same-frame aura edge retargets from the already-updated base.
+                // The display's base alpha first (`0x604990`'s leg of `0x60d180`), so a same-frame
+                // aura edge retargets from the new base.
                 crate::aura_visual::refresh_base_alpha,
                 crate::aura_visual::drain_aura_procs,
-                // The tint publish only needs the drain ahead of it (it writes a resource, not
-                // the alpha channel), so it rides the same chain rather than earning its own.
+                // The tint publish needs only the drain ahead of it.
                 (
                     crate::aura_visual::apply_aura_alpha,
                     crate::aura_visual::apply_aura_tint,
@@ -987,22 +708,20 @@ impl Plugin for EntitiesPlugin {
     }
 }
 
-/// Startup: build the shared cube mesh/materials (always), and load the creature/GameObject display
-/// catalogs off the shared chain (when present). On a catalog failure the resource is simply absent and
-/// those entities stay cubes (attach treats both as optional).
+/// Build the cube assets and load the display and data catalogs; a failed load leaves its
+/// resource absent, which every reader treats as optional.
 fn setup_entities(
     mut commands: Commands,
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<StandardMaterial>>,
     world_assets: Option<ResMut<WorldAssets>>,
 ) {
-    // A person-sized box (2 wide, 4 tall, 2 deep); origin is centered so we lift it by half-height.
+    // A person-sized box; its origin is centred, so it is lifted by half its height.
     let mesh = meshes.add(Cuboid::new(2.0, 4.0, 2.0));
-    // A player without a body model uses a slimmer, shorter block.
     let player_mesh = meshes.add(Cuboid::new(0.8, 2.0, 0.8));
     let mut mat = |r, g, b| {
         materials.add(StandardMaterial {
-            base_color: Color::linear_rgb(r, g, b), // GAMMA LANE (0161): raw bytes
+            base_color: Color::linear_rgb(r, g, b), // raw into the gamma lane
             perceptual_roughness: 0.7,
             ..default()
         })
@@ -1047,7 +766,7 @@ fn setup_entities(
             info!("lock catalog: {} locks", catalog.len());
             commands.insert_resource(crate::go_templates::Locks(catalog));
         }
-        // No lock data ⇒ every GameObject reads as lockless (right-click sends USE) — degraded, not broken.
+        // Without lock data every GameObject reads as lockless: a right-click sends USE.
         Err(e) => warn!("lock catalog unavailable, GameObjects treated as lockless: {e:#}"),
     }
     match benilla_formats::load_lock_type_catalog(&mut chain) {
@@ -1058,7 +777,7 @@ fn setup_entities(
             );
             commands.insert_resource(crate::go_templates::LockTypes(catalog));
         }
-        // No LockType data ⇒ lock-bearing GOs fall back to the Interact gear cursor — degraded, not broken.
+        // Without `LockType` data a locked GameObject shows the Interact cursor.
         Err(e) => warn!("lock-type catalog unavailable, GO cursors fall back to Interact: {e:#}"),
     }
     match (
@@ -1076,16 +795,13 @@ fn setup_entities(
                 loyalty,
             });
         }
-        // No pet tables ⇒ happiness answers its own gate-failure nil (so the icon hides) and the
-        // loyalty line is blank; the rest of the paper doll — XP, training points — reads straight
-        // off the descriptor and is unaffected. Degraded, not wrong.
+        // Without them happiness answers nil (the icon hides) and the loyalty line is blank; the
+        // rest of the pet page reads the descriptor.
         (p, l) => warn!(
             "pet stat tables unavailable, happiness/loyalty stay blank: {:#}",
             p.err().or(l.err()).expect("at least one of the two failed")
         ),
     }
-    // The family pair (decision 1062) — its own resource, so it degrades independently of the
-    // happiness tables above rather than taking them down with it.
     match (
         benilla_formats::load_creature_families(&mut chain),
         benilla_formats::load_pet_food_names(&mut chain),
@@ -1098,10 +814,8 @@ fn setup_entities(
             );
             commands.insert_resource(crate::ui_pet_stats::PetFamilyTables { families, foods });
         }
-        // No family tables ⇒ `UnitCreatureFamily("pet")` answers nil, which the reference's own
-        // guard turns into a BLANK level line on the pet page (ref `PetPaperDollFrame.lua:68-70`),
-        // and the diet tooltip shows nothing at all. That is exactly the state 1057 shipped in —
-        // degraded to the faithful fallback, not wrong.
+        // Without them `UnitCreatureFamily("pet")` is nil, which the stock page's guard turns into
+        // a blank level line (`PetPaperDollFrame.lua:68-70`), and the diet tooltip is empty.
         (f, p) => warn!(
             "pet family tables unavailable, the pet's level line stays blank: {:#}",
             f.err().or(p.err()).expect("at least one of the two failed")
@@ -1129,7 +843,6 @@ fn setup_entities(
         }
         Err(e) => warn!("item displays unavailable, units hold nothing: {e:#}"),
     }
-    // The glow chain's ItemVisuals join (decision 0805). Absent, weapons draw unadorned.
     match benilla_formats::load_item_visual_catalog(&mut chain) {
         Ok(visuals) => {
             info!("item visual catalog: {} glow rows", visuals.len());
@@ -1137,8 +850,7 @@ fn setup_entities(
         }
         Err(e) => warn!("item visuals unavailable, weapons never glow: {e:#}"),
     }
-    // `SpellItemEnchantment`'s two consumer columns — the enchant half of that glow chain, and
-    // the tooltip's enchant line (decision 0915). One load, one resource, both lanes.
+    // `SpellItemEnchantment`: the enchant glow and the tooltip's enchant line.
     match benilla_formats::load_enchant_catalog(&mut chain) {
         Ok(enchants) => {
             info!(
@@ -1150,8 +862,7 @@ fn setup_entities(
         }
         Err(e) => warn!("enchants unavailable: no enchant glow, no enchant line: {e:#}"),
     }
-    // `ItemRandomProperties` — the random-suffix roll's name and its enchant slots 2..6 (decision
-    // 1547). Absent, a rolled item reads by its base name and shows no suffix lines.
+    // `ItemRandomProperties`: a random suffix's name and its enchant slots 2..6.
     match benilla_formats::load_random_property_catalog(&mut chain) {
         Ok(props) => {
             info!("random-property catalog: {} suffix rows", props.len());
@@ -1183,12 +894,9 @@ fn setup_entities(
     }
 }
 
-/// For every display id active among the net entities: ensure its [`DisplayModel`] exists (resolve the
-/// catalog + request the model handle), and once the handle has loaded, build its spawn parts (the
-/// per-submesh material, with creature skin slots filled from the display's variations).
+/// Ensure a [`DisplayModel`] for every display id in use and build its parts once the model loads.
 fn update_display_models(
-    // `ObjectStore` rides along for the corpses: which cache holds a corpse's model is a
-    // descriptor question (`CORPSE_FLAG_BONES`), not a display-id one — decision 1706.
+    // For corpses: `CORPSE_FLAG_BONES` decides which cache holds the model.
     entities: Query<(&NetEntity, Option<&crate::net::ObjectStore>)>,
     mut creatures: Option<ResMut<Creatures>>,
     mut gameobjects: Option<ResMut<GameObjects>>,
@@ -1199,42 +907,31 @@ fn update_display_models(
     mut forms: ResMut<benilla_world::model_forms::ModelForms>,
     asset_server: Res<AssetServer>,
     mut mats: benilla_world::model_render::M2BatchMaterials,
-    // The UV lane a batch's texture transform is delivered on (decision 2295): an entity batch is
-    // seeded AND registered in one call, so a display built here can never be marked-but-frozen.
     mut uv_reg: ResMut<benilla_world::doodad_anim::UvAnimMaterials>,
     mut anim_table: ResMut<benilla_world::mat_anim_table::MatAnimTable>,
-    // The bone-pile display cache + the ChrRaces fileStrings its paths are built from (1706).
     mut bones: ResMut<corpse::BonesModels>,
-    // The glue-preview want (decisions 0423 + 0465): the glue screens' look's body displayId, so
-    // its model builds with no wire entity (the screens run pre-world, where no NetEntity carries it).
+    // The glue screens' body display, wanted with no wire entity.
     glue_preview: Option<Res<crate::portrait::GluePreview>>,
     char_create: Option<Res<CharCreate>>,
-    // 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.
+    // The stable pane's pet (`SetPetStablePaperdoll`, `0x4cb870`), with no wire entity.
     stable_booth: Option<Res<crate::portrait::StableBooth>>,
 ) {
     if !mats.ready() {
         return; // no lighting yet → no materials to build
     }
     let (m2s, wmos) = (&model_assets.0, &model_assets.1);
-    // `instance: None` — every display cache here is keyed by display id and shared by every unit
-    // wearing it, so these materials belong to the batch. The one population that needs its own
-    // (a GameObject whose file-sequence slots bake different loops) takes its clone at spawn,
-    // where the host entity exists (`attach::dress`).
+    // Shared per display, so the materials belong to the batch; a GameObject that needs its own
+    // clones them at spawn (`attach::dress`).
     let mut uv = benilla_world::model_render::EntityUvLane {
         reg: &mut uv_reg,
         table: &mut anim_table,
         instance: None,
     };
 
-    // The (kind, display) pairs live in the world this frame — cheap to collect.
     let mut actives: Vec<(EntityKind, u32)> = entities
         .iter()
-        // A **bone pile** is skipped here (decision 1706): it carries a perfectly valid display id
-        // — the server's corpse→bones conversion copies the field verbatim — and the client
-        // deliberately ignores it, so requesting the body it names would load and build a
-        // character model nothing will ever render. Its own model is collected below.
+        // A bone pile keeps the body's display id, which the client ignores; its own model is
+        // collected below.
         .filter(|(e, store)| {
             !matches!(
                 corpse::corpse_model(e, *store),
@@ -1243,12 +940,8 @@ fn update_display_models(
         })
         .filter_map(|(e, _)| e.display_id.map(|d| (e.kind, d)))
         .collect();
-    // The bone piles want the OTHER cache (decision 1706): their model is keyed (race, sex), so
-    // they are collected separately and never enter the display-id want list above — a bone pile's
-    // display id is a live field the client deliberately ignores, and building the body it names
-    // would load a model nothing renders. Their FLESH siblings need nothing here: a corpse's
-    // display id IS a `CreatureDisplayInfo` id, so the `Corpse` arm below resolves it exactly like
-    // a unit's.
+    // Bone piles want the (race, sex) cache; a flesh corpse's display id is a
+    // `CreatureDisplayInfo` id, resolved below like a unit's.
     let bones_wanted: Vec<(u8, u8)> = entities
         .iter()
         .filter_map(|(e, store)| match corpse::corpse_model(e, store) {
@@ -1256,8 +949,7 @@ fn update_display_models(
             _ => None,
         })
         .collect();
-    // The glue-preview body (decisions 0423 + 0465): a want beside the NetEntity scan, so the
-    // character on the glue stage has a model even though nothing streamed it in.
+    // The glue stage's character, which nothing streamed in.
     if let (Some(preview), Some(cc)) = (glue_preview.as_deref(), char_create.as_deref()) {
         if let Some(look) = preview.look {
             let (race, sex) = look.body();
@@ -1266,37 +958,26 @@ fn update_display_models(
             }
         }
     }
-    // The select screen's **pet** — the same kind of wantless want, one display further. It is an
-    // ordinary creature display (`Unit`, not `Player`): the enum's pet triple carries a
-    // `CreatureDisplayInfo` id, so it resolves down the plain creature chain, skins and all.
+    // The select screen's pet, a plain creature: its triple carries a `CreatureDisplayInfo` id.
     if let Some(preview) = glue_preview.as_deref() {
         if let Some(pet) = preview.look.and_then(|l| l.pet()) {
             actives.push((EntityKind::Unit, pet.display_id));
         }
     }
 
-    // The stable window's selected pet — the same wantless want, and the same `Unit` kind: the
-    // creature query answers with a `CreatureDisplayInfo` id, so it resolves down the plain
-    // creature chain, skins and all. Asked for whenever the pane names one, live pet or not; a
-    // summoned pet's display is already in the scan above, and a repeat is free (the cache is
-    // keyed by display).
+    // The stable window's selected pet, a plain creature display too; a repeat is free.
     if let Some(display) = stable_booth.as_deref().and_then(|b| b.display_id) {
         actives.push((EntityKind::Unit, display));
     }
 
     for (kind, disp) in actives {
         match kind {
-            // Players resolve their body model through the very same creature chain (decision 0041):
-            // displayId → CreatureDisplayInfo → CreatureModelData → a `Character\…\…\….mdx` body.
-            // …and so does a **corpse** that is not a bone pile (decision 1706): its
-            // `CORPSE_FIELD_DISPLAY_ID` is the dead player's own body display, which is the
-            // reference's own lookup at `0x5d6759`.
+            // A player's body resolves through the creature chain (`CreatureDisplayInfo` →
+            // `CreatureModelData` → a `Character\…` model), as does a flesh corpse's
+            // `CORPSE_FIELD_DISPLAY_ID` (`0x5d6759`).
             EntityKind::Unit | EntityKind::Player | EntityKind::Corpse => {
-                // Peek through `&` first: `Option<ResMut<T>>::as_deref_mut` marks the resource
-                // changed whether or not a byte is written, and `resolve_equipment`'s skip gate
-                // reads `Creatures::is_changed()` — so an every-frame `&mut` here re-resolved
-                // every rigged unit's equipment every frame (1697 item 1). A display that is
-                // present and built asks nothing of the cache.
+                // Peek through `&` first: `as_deref_mut` marks `Creatures` changed, and
+                // `resolve_equipment`'s skip gate reads that.
                 if creatures
                     .as_deref()
                     .is_some_and(|cr| cr.models.get(&disp).is_some_and(|dm| dm.parts.is_some()))
@@ -1320,14 +1001,13 @@ fn update_display_models(
                             &asset_server,
                             &mut mats,
                             &mut uv,
-                            false, // gameobject: creatures — no hull collider, no bake variant
+                            false, // gameobject: no hull collider, no bake variant
                         );
                     }
                 }
             }
             EntityKind::GameObject => {
-                // The same peek, for the same reason (no gate reads this tick today; the census
-                // that finds the next one should not have to look past it).
+                // The same peek, though no gate reads this change.
                 if gameobjects
                     .as_deref()
                     .is_some_and(|go| go.models.get(&disp).is_some_and(|dm| dm.parts.is_some()))
@@ -1351,7 +1031,7 @@ fn update_display_models(
                             &asset_server,
                             &mut mats,
                             &mut uv,
-                            true, // gameobject: hull collider + the interior BAKE material variant
+                            true, // gameobject: hull collider and the interior bake variant
                         );
                     }
                 }
@@ -1360,10 +1040,8 @@ fn update_display_models(
         }
     }
 
-    // The bone piles (decision 1706): request each wanted `(race, sex)` skeleton once, then build
-    // its parts as the M2 lands — the same two-step as every other display, on its own tiny cache.
-    // Character-creation data is the source of the race fileString the path is built from, so a
-    // session that could not load it simply shows no skeletons rather than guessing at names.
+    // Each wanted `(race, sex)` skeleton, built as its M2 lands. Its path needs the race's file
+    // string from the char-create data; without it there are no skeletons.
     if let Some(cc) = char_create.as_deref() {
         for key in bones_wanted {
             corpse::ensure_bones_display(&mut bones, &cc.0, key, &asset_server);
@@ -1377,18 +1055,15 @@ fn update_display_models(
                         &asset_server,
                         &mut mats,
                         &mut uv,
-                        false, // gameobject: a prop body — unit lighting, no hull collider
+                        false, // gameobject: a prop body, unit lighting, no hull collider
                     );
                 }
             }
         }
     }
 
-    // Held-item displays (decision 0072): entries are created by `resolve_equipment`; build each
-    // one's parts once its M2 loads. Items are static meshes — no collider, unit lighting.
-    // Each of the three path-keyed caches below is `&mut`-borrowed only when it holds an
-    // unbuilt entry — the read-side scan is a few hundred `Option` tests, the write-side tick
-    // would have read as "changed" on every frame of every run.
+    // Held items, effects and glows: each cache is borrowed `&mut` only while it holds an unbuilt
+    // entry, or it would read as changed every frame.
     fn unbuilt<K>(models: &HashMap<K, DisplayModel>) -> bool {
         models.values().any(|dm| dm.parts.is_none())
     }
@@ -1404,15 +1079,14 @@ fn update_display_models(
                         &asset_server,
                         &mut mats,
                         &mut uv,
-                        false, // gameobject: held items — unit lighting, no collider
+                        false, // gameobject: held items, unit lighting, no collider
                     );
                 }
             }
         }
     }
 
-    // Spell-effect displays (decision 0099 phase 3): entries are created by
-    // `spell_fx::resolve_spell_fx`; the same build, keyed by model path instead of display id.
+    // Spell-effect models, keyed by model path.
     if spell_fx.as_deref().is_some_and(|f| unbuilt(&f.models)) {
         if let Some(fx) = spell_fx.as_deref_mut() {
             for dm in fx.models.values_mut() {
@@ -1425,15 +1099,14 @@ fn update_display_models(
                         &asset_server,
                         &mut mats,
                         &mut uv,
-                        false, // gameobject: effects — unit lighting, no collider
+                        false, // gameobject: effects, unit lighting, no collider
                     );
                 }
             }
         }
     }
 
-    // Item/enchant glow models (decision 0805): path-keyed like the effect cache above, entries
-    // created by `resolve_equipment`'s glow resolve.
+    // Item and enchant glow models, path-keyed like the effects.
     if glows.as_deref().is_some_and(|g| unbuilt(&g.models)) {
         if let Some(glows) = glows.as_deref_mut() {
             for dm in glows.models.values_mut() {
@@ -1446,7 +1119,7 @@ fn update_display_models(
                         &asset_server,
                         &mut mats,
                         &mut uv,
-                        false, // gameobject: effects — unit lighting, no collider
+                        false, // gameobject: effects, unit lighting, no collider
                     );
                 }
             }
@@ -1454,24 +1127,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 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,
-/// interior-fog bit, shade byte and highlight bit all ride through), it writes the sampled factor
-/// **verbatim** rather than multiplying into what it finds — so re-running it is idempotent, unlike
-/// a compounding read-modify-write — and it is ordered after the steady-state owner (the interior
-/// classifier) so it re-asserts over that owner's whole-payload reclaim, exactly as
-/// `entity_shade::update_ground_shade` does for the shade byte.
-///
-/// Two owners deliberately keep the channel instead: a live **appear/despawn fade**
-/// (`RenderFade`/`PendingAppearFade` — excluded here, and `apply_render_fade` multiplies the factor
-/// into its own ramp), and the self-avatar zoom feather, which runs after this and wins on the self
-/// body while feathering (its own documented override).
+/// Write a unit part's animated colour alpha into its `MeshTag` alpha field, the dimming factor of
+/// the per-batch `A = instanceAlpha × colourAlpha × weight` (`0x707680`); the `A ≤ 0` cull is the
+/// `Visibility` authority's. Written verbatim, never multiplied in, after the interior classifier;
+/// a part under an appear or despawn fade is `apply_render_fade`'s, which folds the factor in.
 #[allow(clippy::type_complexity)]
 fn apply_unit_mat_alpha(
     mut parts: Query<
@@ -1499,9 +1158,8 @@ fn apply_unit_mat_alpha(
             tag.0 = bits;
         }
     }
-    // One breadcrumb per session, the first frame a unit batch actually resolves to the reference's
-    // `A <= 0` cull — the machine-readable "this lane is live" signal for a bug whose symptom is
-    // geometry that should not be on screen. The live count is in the debug panel's material meter.
+    // Logged once, the first frame a unit batch reaches the `A <= 0` cull; the debug panel's
+    // material meter has the live count.
     if !*logged && culled > 0 {
         *logged = true;
         info!("unit material alpha: {culled} batch(es) culled at A <= 0 (the first frame any did)");
@@ -1521,10 +1179,6 @@ mod world_unit_tests {
         }
     }
 
-    /// The reconciler is the *only* thing that makes a wire body visible to the world — no
-    /// `WorldUnit` means no ground shade, no WMO room claim, no foam ring, and nothing louder than
-    /// a slightly emptier screenshot to say so. So: a body gets one, the viewer gets its marker,
-    /// and both track the facts they restate.
     #[test]
     fn every_wire_body_becomes_a_world_unit_and_the_viewer_is_marked() {
         let mut app = App::new();
@@ -1556,8 +1210,7 @@ mod world_unit_tests {
              depth line collapses and the body swims on dry land (see the type's own doc)"
         );
 
-        // The wire→engine translation 1177 moved here: `benilla-world` no longer knows what a
-        // `TYPEID` is, so this is the only place the creature-vs-GameObject question is answered.
+        // `benilla-world` has no `TYPEID`: only the reconciler tells a creature from a GameObject.
         assert!(
             !w.get::<benilla_world::world_unit::WorldUnit>(chest)
                 .expect("a GameObject is still a body the world can shade and room-claim")
@@ -1581,8 +1234,6 @@ mod world_unit_tests {
         );
     }
 
-    /// The viewer marker is reconciled, not stamped once: a `/logout` takes `Embodied` away and
-    /// the marker has to go with it, or the next character is feathered as someone else's avatar.
     #[test]
     fn the_viewer_marker_follows_self_player_off_as_well_as_on() {
         let mut app = App::new();
@@ -1618,7 +1269,7 @@ mod display_mirror_tests {
     use super::*;
     use crate::portrait::PortraitSeat;
 
-    /// One synthetic batch — plain, or a camera-facing one on `bone`.
+    /// One synthetic batch, plain or camera-facing on `bone`.
     fn part(billboard: Option<u16>) -> crate::entities::display::EntityPart {
         crate::entities::display::EntityPart {
             mesh: Handle::default(),
@@ -1664,11 +1315,6 @@ mod display_mirror_tests {
         c
     }
 
-    /// **Every batch the display authored reaches the mirror, split by lane.** This is the same
-    /// failure mode decision 1539's imp filed against the select pet: a display-only assembly that
-    /// reads one field and drops another renders a creature that is *nearly* right, silently. The
-    /// assertion is "everything the cache holds arrives, in the right lane", not a count pinned to
-    /// one model.
     #[test]
     fn a_display_mirror_carries_every_batch_and_splits_the_camera_facing_ones() {
         let mut dm = crate::entities::display::empty_shell();
@@ -1699,10 +1345,6 @@ mod display_mirror_tests {
         );
     }
 
-    /// The gate that keeps a half-loaded display out of the booth: `display_mirror` answers `None`
-    /// until the parts are built, the same instant [`Creatures::display_rig`] and
-    /// [`Creatures::display_anchors`] start answering — so the stand-in never spawns a subject the
-    /// booth could frame from fabricated bounds.
     #[test]
     fn a_display_still_loading_mirrors_nothing() {
         let c = creatures(4449, crate::entities::display::empty_shell());
@@ -1715,7 +1357,7 @@ mod display_mirror_tests {
 mod overhead_slot_tests {
     use super::*;
 
-    /// A body model authoring exactly `slots` (the bone/offset payload is immaterial here).
+    /// A body model authoring exactly `slots`.
     fn body(slots: &[u16]) -> BoneAttach {
         BoneAttach {
             points: slots.iter().map(|&s| (s, (0u16, Vec3::ZERO))).collect(),
@@ -1723,11 +1365,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 (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.
+    /// `0x6074c0`'s pick. A character body (HumanMale) authors both slots, a Kobold only 18.
     #[test]
     fn twenty_nine_needs_both_a_mount_model_and_the_authored_point() {
         let both = body(&[ATTACH_OVERHEAD, ATTACH_OVERHEAD_MOUNTED]);
@@ -1761,16 +1399,13 @@ mod overhead_slot_tests {
 mod attach_bias_tests {
     use super::*;
 
-    /// 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.
+    /// The table at `0x862708`, verbatim; animation events reach it by ids 17 and 1.
     #[test]
     fn the_z_bias_table_is_the_reference_row_for_ever_id() {
         assert_eq!(ATTACH_Z_BIAS.len(), 0x25, "ids 0..=0x24");
         assert_eq!(ATTACH_Z_BIAS[17], 2.0, "$CSD's fallback lift");
         assert_eq!(ATTACH_Z_BIAS[1], 1.0, "a whiffed $CSS's");
-        // The two that are not 1.0-or-1.5, which is what makes a transcription slip visible.
+        // Values other than 1.0 and 1.5, where a transcription slip shows.
         assert_eq!(ATTACH_Z_BIAS[19], 0.0);
         assert_eq!(ATTACH_Z_BIAS[29], 3.0);
         assert_eq!(ATTACH_Z_BIAS[18], 2.5);
diff --git a/crates/benilla-app/src/entities/attach/char_skin.rs b/crates/benilla-app/src/entities/attach/char_skin.rs
index face5511..70aa8a49 100644
--- a/crates/benilla-app/src/entities/attach/char_skin.rs
+++ b/crates/benilla-app/src/entities/attach/char_skin.rs
@@ -1,10 +1,5 @@
-//! Character appearance → per-look skin materials — the *who wears what* half of [`super`].
-//!
-//! [`super`] (attach) spawns a streamed entity's visual; this module resolves the character-specific
-//! inputs it swaps in: the entity's [`CharLook`] (race/sex/customization — wire fields for a player,
-//! CreatureDisplayInfoExtra for a character-model NPC, decision 0041), its worn-equipment display ids
-//! ([`WornEquip`], decision 0074), and the per-appearance material quints over the composited body
-//! atlas / hair / cape textures ([`build_char_skin_materials`], decisions 0044 / 0045).
+//! A character body's appearance inputs: its look ([`CharLook`]), its worn display ids
+//! ([`WornEquip`]) and its per-appearance materials ([`build_char_skin_materials`]).
 
 use benilla_formats::{CharSkinSlot, ModelBlend};
 use benilla_protocol::EntityKind;
@@ -16,57 +11,42 @@ use benilla_assets::{repeat_texture_authored, LockRecover, WorldAssets};
 
 use super::super::{DisplayModel, EntityPart, SkinKey, SkinSections};
 
-/// The resolved character appearance for one entity that renders as a character-model body — either a
-/// **player** (appearance decoded from the wire) or a **character-model NPC** (from its display's
-/// CreatureDisplayInfoExtra, decision 0041). It drives both the geoset selection and the per-appearance
-/// skin/hair materials, so the two cases share one code path. `None` for a beast NPC / GameObject / a
-/// unit with no appearance data — those render whole, with their built textures, as before.
+/// A character-model body's appearance, from the wire or from its display's
+/// CreatureDisplayInfoExtra row; it drives both the geoset selection and the skin materials.
 pub(super) struct CharLook {
     pub(super) race: u8,
     pub(super) sex: u8,
-    /// skinColor — keys the composited base skin AND the standalone extra-skin BLP (the tauren fur,
-    /// M2 type 8), which even a pre-baked NPC atlas doesn't cover, so it lives here, not in `body`.
+    /// skinColor: keys the composite and the extra-skin BLP (tauren fur, M2 type 8), which a baked
+    /// NPC atlas does not cover.
     pub(super) skin: u8,
     pub(super) hair_style: u8,
     pub(super) hair_color: u8,
     pub(super) facial_hair: u8,
-    /// Where the body-skin atlas comes from.
     pub(super) body: BodySkin,
 }
 
 /// The body-skin atlas source for a [`CharLook`].
 pub(super) enum BodySkin {
-    /// A player (or a character-model NPC row that carries no bake name): composite the atlas live from
-    /// CharSections — needs the face (skinColor is on [`CharLook`]) — cached per appearance in
-    /// [`SkinComposites`].
+    /// Composited live from CharSections, cached per appearance: a player, or an NPC row with no
+    /// bake name.
     Composite { face: u8 },
-    /// A character-model NPC: the pre-baked body atlas the client ships under `Textures\BakedNpcTextures\`
-    /// (CreatureDisplayInfoExtra field 18). Loaded directly through the async `mpq://` pipeline — no
-    /// compositing (the faithful path: the file ships and the client loads it, it does not re-bake).
+    /// A character-model NPC's shipped atlas under `Textures\BakedNpcTextures\`
+    /// (CreatureDisplayInfoExtra field 18), loaded as is, never re-baked.
     Baked(String),
 }
 
-/// Resolve the character look for a net entity, or `None` if it isn't a character-model body. A player
-/// takes race/sex + customization from the wire (its [`ObjectStore`] descriptor fields); a
-/// character-model NPC takes them from its display's [`NpcAppearance`](benilla_formats::NpcAppearance)
-/// — a baked body when the row names one, else a live composite. A beast NPC / GameObject has no look.
+/// A net entity's character look; `None` unless its display is a character-model body.
 pub(super) fn resolve_char_look(
     net: &NetEntity,
     dm: Option<&DisplayModel>,
     entity: Entity,
     stores: &Query<&ObjectStore>,
 ) -> Option<CharLook> {
-    // The look follows the DISPLAY, not the entity kind (decision 0695): with live display-id
-    // 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 (the
-    // `0x60c690` getter family) — exactly this order: display appearance first,
-    // wire appearance only for a character body that carries none.
+    // The look follows the display, not the entity kind: the display's own appearance row first,
+    // the wire's only for a character body without one, as the reference's race and sex getters
+    // answer (`0x60c690`). A druid form is a plain creature model and has no look.
     let d = dm?;
     if let Some(npc) = d.npc_appearance.as_ref() {
-        // A character-model NPC display (whoever wears it): its CreatureDisplayInfoExtra
-        // appearance — a baked body when the row names one, else a live composite.
         return Some(CharLook {
             race: npc.race,
             sex: npc.sex,
@@ -80,12 +60,8 @@ pub(super) fn resolve_char_look(
             },
         });
     }
-    // A **corpse** that is not a bone pile (decision 1706): its look is its own
-    // `CORPSE_FIELD_BYTES_1/_2` snapshot, taken at death — not the owner's live `PLAYER_BYTES`,
-    // which the corpse cannot see and which may belong to a player who has since logged out. This
-    // is the reference's own source: `0x5d6260` reads `[[corpse+0x110]+0x69..+0x6f]` into the
-    // corpse's own `CCharacterComponent`. A bone pile builds no component and reads `None` here,
-    // which is exactly `0x5d6291`'s early skip.
+    // A corpse's look is its own `CORPSE_FIELD_BYTES_1/_2` snapshot from death, never the
+    // owner's `PLAYER_BYTES` (`0x5d6260`); a bone pile has none, `0x5d6291`'s early skip.
     if net.kind == EntityKind::Corpse && d.is_character_body {
         let look = super::super::corpse::corpse_char_look(stores.get(entity).ok())?;
         return Some(CharLook {
@@ -99,13 +75,9 @@ pub(super) fn resolve_char_look(
         });
     }
     if net.kind == EntityKind::Player && d.is_character_body {
-        // A player wearing a character body. Race/sex come from `UNIT_FIELD_BYTES_0`; the
-        // `PLAYER_BYTES` / `PLAYER_BYTES_2` customization is *optional on the wire* — vmangos omits an
-        // all-zero field from the create mask, so a fully-default character (like our own "One") sends
-        // no `PLAYER_BYTES` at all. Per UpdateFields semantics an absent field means its default (0),
-        // not "no data": default each byte to 0 rather than gate the whole look on its presence (an
-        // over-strict `?` here left a default-customized avatar unskinned — the pre-0061 component
-        // path defaulted these implicitly).
+        // Race and sex from `UNIT_FIELD_BYTES_0`. vmangos leaves an all-zero field out of the
+        // create mask (`Object.cpp:1149`), and an absent field is 0, so each customization byte
+        // defaults to 0.
         let s = &stores.get(entity).ok()?.0;
         return Some(CharLook {
             race: s.unit_race()?,
@@ -119,12 +91,10 @@ pub(super) fn resolve_char_look(
             },
         });
     }
-    // A beast display (whoever wears it), a GameObject, a model-less display: no look.
     None
 }
 
-/// The `mpq://` URL for a pre-baked NPC body atlas (a CreatureDisplayInfoExtra bake name) under
-/// `Textures\BakedNpcTextures\`. Lowercased forward-slash, like the other `mpq://` loads.
+/// The `mpq://` URL of a baked NPC atlas under `Textures\BakedNpcTextures\`.
 fn baked_npc_url(bake_name: &str) -> String {
     format!(
         "mpq://textures/bakednpctextures/{}",
@@ -132,27 +102,16 @@ fn baked_npc_url(bake_name: &str) -> String {
     )
 }
 
-/// The worn-equipment display ids that drive a character body's geoset selection (the equipment
-/// branches in [`benilla_formats::CharacterGeosets::visible_geosets`]) and — for a player — the
-/// region-texture composite: the 8 armor bodyslots (shirt..tabard, the [`EquipGeosets`] index order),
-/// the cloak, and the helm.
-///
-/// A **player** takes them from its resolved [`super::Equipment`] (the wire's visible-item entries →
-/// item template → display id, decision 0074). A **character-model NPC** takes them from its display's
-/// [`NpcAppearance`](benilla_formats::NpcAppearance) equipment columns (CreatureDisplayInfoExtra —
-/// decision 0060 named the gap; this is the fill): its bodyslots 2..9 (shirt..tabard) map straight onto
-/// the 8 slots, field 0 (head) is the helm, and there is no NPC cloak column (the row stops at bodyslot
-/// 9). A beast NPC / GameObject / a unit with no appearance row yields the all-zero naked default.
+/// The worn display ids behind a character body's geoset selection and, for a player, its region
+/// composite; all zero, the naked body, for anything without a look.
 #[derive(Default)]
 pub(super) struct WornEquip {
-    /// shirt · chest · belt · pants · boots · wrist · gloves · tabard (bodyslot 2–9).
+    /// Shirt, chest, belt, pants, boots, wrist, gloves, tabard (bodyslots 2 to 9).
     pub(super) bodyslots: [u32; 8],
     pub(super) cloak: u32,
     pub(super) helm: u32,
-    /// The wearer's guild tabard (decision 1704) — a **player's** only, off their resolved
-    /// [`super::Equipment`]. A character-model NPC has no guild: CreatureDisplayInfoExtra carries
-    /// no guild column, and a display-driven body never joins one, so this stays `None` there and a
-    /// tabard in an NPC's bodyslot-9 column keeps its own art.
+    /// The wearer's guild emblem, a player's only: CreatureDisplayInfoExtra has no guild column,
+    /// so an NPC's tabard keeps its own art.
     pub(super) emblem: Option<benilla_formats::GuildEmblem>,
     pub(super) tabard_preview: bool,
 }
@@ -163,10 +122,8 @@ pub(super) fn resolve_worn_equip(
     dm: Option<&DisplayModel>,
 ) -> WornEquip {
     match net.kind {
-        // A **corpse** rides the player arm (decision 1706): its `Equipment` is resolved from the
-        // 19 `CORPSE_FIELD_ITEM` slots, which are already ItemDisplayInfo ids — the same values a
-        // player's items resolve to, so the geoset + region-composite law downstream is literally
-        // the same law, on a different source.
+        // A corpse's `Equipment` comes from its 19 `CORPSE_FIELD_ITEM` slots, already
+        // ItemDisplayInfo ids.
         EntityKind::Player | EntityKind::Corpse => equipment
             .map(|e| WornEquip {
                 bodyslots: e.bodyslots,
@@ -176,9 +133,8 @@ pub(super) fn resolve_worn_equip(
                 tabard_preview: e.tabard_preview,
             })
             .unwrap_or_default(),
-        // A character-model NPC's worn gear ships in its display's CreatureDisplayInfoExtra columns
-        // (bodyslot-indexed) — the same ItemDisplayInfo ids a player's items resolve to. bodyslots
-        // 2..9 map directly onto the 8 armor slots; field 0 is the helm; there is no cloak column.
+        // An NPC wears its CreatureDisplayInfoExtra columns, ItemDisplayInfo ids by bodyslot: 2 to
+        // 9 are the armor slots, 0 the helm, and there is no cloak column.
         EntityKind::Unit => dm
             .and_then(|d| d.npc_appearance.as_ref())
             .map(|npc| WornEquip {
@@ -193,15 +149,9 @@ 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 `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).
-///
-/// [`EquipGeosets::tabard_preview`](benilla_formats::EquipGeosets::tabard_preview) (B6) is the
-/// tabard designer's flag, up on the local player's body while that window is open (decision
-/// 1977) — its only setter in the reference too.
+/// The worn geoset selectors for a set of display ids, the inputs of `0x477520`'s branches B1 to
+/// B8: each row's geoset columns, the cloak group and the helm's hide-mask rows (`0x4799a0`).
+/// `tabard_preview` (B6) is set only while the tabard designer is open, as in the reference.
 pub(in crate::entities) fn equip_geosets(
     displays: Option<&super::super::ItemDisplays>,
     bodyslots: &[u32; 8],
@@ -221,17 +171,14 @@ pub(in crate::entities) fn equip_geosets(
                 eg.bodyslots[i] = worn[i].map(|row| row.geoset_groups);
             }
         }
-        // B3's gate is the ArmLower tile's own occupancy, not "is a chest equipped" — the same
-        // plan the composite blits (decision 1864).
+        // B3's gate is the ArmLower tile's occupancy in the composite plan, not a worn chest.
         eg.forearm_dressed = benilla_formats::forearm_dressed(&worn);
         if cloak != 0 {
             eg.cloak = d.catalog.get(cloak).map(|row| row.geoset_groups[0]);
         }
         if helm != 0 {
-            // Only a display that names a head MODEL is a worn helm, and only a worn helm tucks
-            // hair/facial/ears away (B93: `CreatureDisplayInfoExtra`'s head column points 126
-            // character-model NPC displays at model-less jewellery rows that still carry a full
-            // hide mask — see [`benilla_formats::ItemDisplay::worn_helm_vis`]).
+            // Only a display naming a head model hides hair, facial hair and ears: NPC head columns
+            // can name model-less rows that still carry a full hide mask.
             eg.helm_vis = d
                 .catalog
                 .get(helm)
@@ -241,9 +188,8 @@ pub(in crate::entities) fn equip_geosets(
     eg
 }
 
-/// One per-appearance material set for a character runtime texture slot: (steady, interior-matte,
-/// appear-fade-blend, interior-bake, interior-bake-blend, depth-prime twin). `model_material` /
-/// `zfill_material` dedup by texture+blend, so all players of one look share them.
+/// One character slot's material set: (steady, interior-matte, fade blend, interior-bake,
+/// interior-bake blend, depth-prime twin), shared by every body of one look.
 pub(super) type MatQuint = (
     Handle<WowModelMaterial>,
     Handle<WowModelMaterial>,
@@ -253,10 +199,8 @@ pub(super) type MatQuint = (
     Option<Handle<WowModelMaterial>>,
 );
 
-/// The full character material set [`build_char_skin_materials`] returns: `(body, hair, object,
-/// skin_extra)`, the body + skin-extra each a (single-sided, two-sided) pair. Each per-slot
-/// [`MatQuint`] is `None` for an absent row (a bald style, a non-fur race) or missing tables. Named
-/// so the create-preview builder (`super::create_preview`) can select the steady variant per part.
+/// `(body, hair, object, skin_extra)`, body and extra skin as (single-sided, two-sided) pairs; a
+/// slot is `None` for an absent row (a bald style, a non-fur race) or missing tables.
 pub(super) type CharSkinMaterials = (
     Option<(MatQuint, MatQuint)>,
     Option<MatQuint>,
@@ -264,35 +208,22 @@ pub(super) type CharSkinMaterials = (
     (Option<MatQuint>, Option<MatQuint>),
 );
 
-/// The `WOW_PROBE_SHARED_SKIN` pricing lever (see its use in [`build_char_skin_materials`]).
+/// The `WOW_PROBE_SHARED_SKIN` pricing lever.
 fn shared_skin_probe() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_PROBE_SHARED_SKIN").is_some())
 }
 
-/// Build a character body's per-appearance materials — the **body** atlas (as a (single-sided,
-/// two-sided) pair — a body batch keeps its own M2 0x04, e.g. the robe skirt) and the **hair**-mesh
-/// texture (a single CharSections BLP, decision 0045) — each as a (steady, interior-matte, fade,
-/// interior-bake) quad. Works for a
-/// player (atlas composited live from CharSections + overlays, decisions 0041 / 0044) *and* a
-/// character-model NPC (atlas = the shipped pre-baked BLP), selected by [`CharLook::body`]. Returns
-/// `(body, hair, object, skin_extra)`; each is `None` for an absent row (e.g. a bald style has no hair
-/// texture, only tauren author an extra skin) or when the tables / world chain / lighting aren't
-/// available (those parts then keep their built, untextured material). A composited atlas is uploaded once per look ([`super::super::SkinComposites`] cache); a baked or hair
-/// BLP loads through the async `mpq://` pipeline (which dedups by path). `parts` supplies the hair
-/// batches' blend (hair is alpha-cut, so it can't be forced opaque like the body).
+/// Build a character body's per-appearance materials: the body atlas (composited live, or an NPC's
+/// baked BLP), the hair, the cape and the extra skin, each at its batches' own blend and
+/// sidedness from `parts`. Without the tables or the light buffer, parts keep their built material.
 #[allow(clippy::type_complexity)]
 pub(super) fn build_char_skin_materials(
     look: &CharLook,
-    // The worn armor display ids (bodyslot 2–9) + the cloak's, and the ItemDisplayInfo catalog to
-    // resolve their region textures (decision 0074). Consumed **only** on the live-composite path
-    // (a player, or the rare bake-less NPC row); a baked NPC atlas already owns the skin, so its
-    // equip ids don't paint here — they drive the geosets only. `[0; 8]`/`0`/`None` = the naked body.
+    // The armor ids paint only a live composite; a baked NPC atlas already carries its gear.
     equip: [u32; 8],
     cloak: u32,
-    // The wearer's guild tabard (decision 1704), painted over the torso layers of a tabard whose
-    // display asks for it. `None` = no guild, or its identity has not arrived; both leave the
-    // tabard garment showing its own art.
+    // Painted over a tabard whose display asks for it; `None` leaves the tabard's own art.
     emblem: Option<benilla_formats::GuildEmblem>,
     tabard_preview: bool,
     displays: Option<&super::super::ItemDisplays>,
@@ -307,8 +238,7 @@ pub(super) fn build_char_skin_materials(
     let (Some(sections), true) = (sections, mats.ready()) else {
         return (None, None, None, (None, None));
     };
-    // The quint IS the engine's variant set, in the order the character swap reads it: steady,
-    // interior-matte, appear-fade-blend, interior-bake, interior-bake-blend, depth-prime twin.
+    // The engine's variant set in `MatQuint` order.
     let quint = |v: benilla_world::model_render::BatchVariants| {
         (
             v.steady,
@@ -320,10 +250,8 @@ pub(super) fn build_char_skin_materials(
         )
     };
 
-    // Body-skin atlas. A character-model NPC loads its shipped, pre-baked atlas directly; a player (or an
-    // NPC row without a bake name) composites it live from CharSections + overlays, uploaded + cached
-    // once per appearance ([`SkinComposites`]). The composite reads its half-dozen BLPs synchronously off
-    // the shared chain (like the WDL/clutter main-thread loads) — fine behind the cache (once per look).
+    // The composite reads its BLPs synchronously off the shared chain, once per look behind the
+    // cache.
     let body_tex: Option<Handle<Image>> = match &look.body {
         BodySkin::Baked(name) => Some(asset_server.load::<Image>(baked_npc_url(name))),
         BodySkin::Composite { face } => world_assets.and_then(|world| {
@@ -339,10 +267,8 @@ pub(super) fn build_char_skin_materials(
                 emblem,
                 tabard_preview,
             };
-            // `WOW_PROBE_SHARED_SKIN=1` — a PRICING lever, never a look: every body composites
-            // the same key, so every body part of one mesh shares one material and bevy's
-            // batcher can instance them. What it measures is the ceiling of the shared-body-
-            // material lane (draw count → render-thread CPU) before that lane is built.
+            // `WOW_PROBE_SHARED_SKIN` prices a shared body material and is never a look: one key
+            // for every body lets Bevy's batcher instance them.
             if shared_skin_probe() {
                 key = SkinKey {
                     race: 1,
@@ -360,8 +286,6 @@ pub(super) fn build_char_skin_materials(
             match skin_cache.fetch(&key) {
                 Some(handle) => Some(handle),
                 None => {
-                    // The worn ItemDisplayInfo rows whose region textures dress the atlas
-                    // (decision 0074); an unknown/zero display id contributes nothing.
                     let catalog = displays.map(|d| &d.catalog);
                     let mut worn: [Option<&benilla_formats::ItemDisplay>; 8] = [None; 8];
                     if let Some(catalog) = catalog {
@@ -388,10 +312,8 @@ pub(super) fn build_char_skin_materials(
                             key.tabard_preview,
                         )
                         .ok()??;
-                    // Through the upload gate like every other texture: a composite is
-                    // layered texel-by-texel on the CPU so it is already RGBA8, and
-                    // `for_upload` is a no-op on it — but going through it is what makes
-                    // the format and the bytes provably agree (decision 1626).
+                    // Through the upload gate like every texture: a no-op on this RGBA8
+                    // composite, but it keeps the format and the bytes in agreement.
                     let handle = images.add(repeat_texture_authored(
                         benilla_assets::for_upload(composed),
                         (true, true),
@@ -402,12 +324,8 @@ pub(super) fn build_char_skin_materials(
             }
         }),
     };
-    // Body atlas: a (single-sided, two-sided) quint pair, chosen per body batch at the swap. The
-    // naked body is a closed single-sided mesh (the approved decision-0044 look), but body-slot
-    // batches carry their own M2 0x04: every race's robe skirt (geoset 1302) — and the undead
-    // ragged-trouser batch — is authored two-sided, and flattening it to the closed-body default
-    // culled the robe's inner faces (see-through from below). `model_material` dedups by key, so
-    // the second quint is a handful of cache entries per look, shared like the first.
+    // A single-sided and a two-sided set, chosen per batch by its own M2 `0x04`: the robe skirt
+    // (geoset 1302) is authored two-sided, the closed body is not.
     let body = body_tex.map(|tex| {
         (
             quint(
@@ -421,18 +339,12 @@ pub(super) fn build_char_skin_materials(
         )
     });
 
-    // Hair-mesh texture — a single CharSections BLP loaded through the async pipeline (dedups by path).
-    // Alpha-cut, so it takes the hair batches' own blend. `None` for a model with no hair part. Same
-    // for a player + an NPC: the baked/composited body atlas covers the head *skin*, but the 3D hair
-    // geometry is a separate geoset with its own texture, keyed here — and that same type-6 unit also
-    // dresses the *facial* hair on the races whose beards are geometry, so this resolves through
-    // `hair_mesh_texture`'s bald fallback rather than the raw row (a bald orc/gnome still has a beard
-    // to texture; taking the blank row left it flat white).
+    // The hair texture (M2 type 6) also dresses the facial hair of races whose beards are
+    // geometry, so it resolves through `hair_mesh_texture`'s bald fallback: a bald orc has a beard.
     let hair = sections
         .0
         .hair_mesh_texture(look.race, look.sex, look.hair_style, look.hair_color)
         .and_then(|path| {
-            // Hair cards are alpha-cut + two-sided (M2 `0x04`); carry both onto the swapped material.
             let hair_part = parts
                 .iter()
                 .find(|p| p.char_slot == Some(CharSkinSlot::Hair))?;
@@ -444,11 +356,8 @@ pub(super) fn build_char_skin_materials(
                 .map(&quint)
         });
 
-    // Cape texture (decision 0074's empirical pin): the worn cloak's ItemDisplayInfo
-    // `model_texture[0]` is the Cape BLP basename under `Item\ObjectComponents\Cape\`, bound to the
-    // body's runtime type-2 batches ([`CharSkinSlot::Object`]) — the cloak-geoset skin. `None`
-    // (cloak-less, unknown display, no Object part) keeps those parts' built material — moot when
-    // the cloak geoset branch has them hidden anyway.
+    // The cape: the cloak's ItemDisplayInfo `model_texture[0]`, a BLP under
+    // `Item\ObjectComponents\Cape\`, on the body's type-2 batches.
     let object = (cloak != 0)
         .then_some(())
         .and_then(|()| displays?.catalog.get(cloak)?.model_texture[0].as_deref())
@@ -464,13 +373,9 @@ pub(super) fn build_char_skin_materials(
                 .map(&quint)
         });
 
-    // Extra-skin texture (the tauren fur, M2 type 8) — CharSections `sectionType 0` `TextureName[1]`
-    // keyed by skinColor, loaded plain through the async pipeline (the client's extra loader is a bare
-    // TextureCreate — no compositing; a pre-baked NPC atlas doesn't cover it either, so this applies to
-    // players and NPCs alike). The batches come in exactly two authored flavors — the opaque
-    // single-sided fur core and the alpha-cut two-sided fringe cards — so build one quint per flavor
-    // from a representative part (a flavor no part carries is never selected). Empty column (every
-    // non-fur race) ⇒ `(None, None)`; those models carry no type-8 batch anyway.
+    // The extra skin (tauren fur, M2 type 8): CharSections section 0 `TextureName[1]` by
+    // skinColor, loaded plain as the reference does, never composited. Its batches are an opaque
+    // single-sided core and alpha-cut two-sided fringe cards, so one set per sidedness.
     let skin_extra = sections
         .0
         .skin_extra_texture(look.race, look.sex, look.skin)
diff --git a/crates/benilla-app/src/entities/attach/dress.rs b/crates/benilla-app/src/entities/attach/dress.rs
index 9626d034..3be9197b 100644
--- a/crates/benilla-app/src/entities/attach/dress.rs
+++ b/crates/benilla-app/src/entities/attach/dress.rs
@@ -1,14 +1,5 @@
-//! **Dressing** a unit's model parts — the per-batch spawn [`super::attach_entity_visuals`] runs
-//! once per visual, factored out so the **re-dress** ([`super::redress`]) can run the identical law
-//! over the parts a unit is already standing in.
-//!
-//! 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 `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.
+//! Dressing a unit's model parts: the per-batch spawn shared by the first build and the in-place
+//! re-dress ([`super::redress`]), so both dress a part by one law.
 
 use benilla_formats::CharSkinSlot;
 use bevy::camera::primitives::Aabb;
@@ -26,44 +17,28 @@ use benilla_world::model_render::{ModelKind, ModelPart};
 use super::super::EntityPart;
 use super::char_skin::CharSkinMaterials;
 
-/// The display-model batch a spawned part child was built from — its index into
-/// [`DisplayModel::parts`](super::super::DisplayModel), plus the world-root billboard card that
-/// belongs to it when the batch is a camera-facing one (decision 0153: the card is a ROOT entity,
-/// so it does not cascade with its anchor's despawn and must be named here).
-///
-/// This is the **re-dress edge** ([`super::redress`]): a gear change re-selects the geoset set and
-/// re-composites the atlas, and each standing part is found again through this index — its geoset
-/// id for "does it still show?", its char slot for "which atlas does it draw?". The index is stable
-/// for as long as the visual lives, because the only thing that can rebuild `parts` is the display
-/// itself changing, which is a teardown (`live_display::refresh_live_display`).
+/// The batch a part was spawned from, its index into `DisplayModel::parts`, by which the re-dress
+/// finds it again; stable for the visual's life, since only a display change (a teardown) rebuilds
+/// `parts`. `card` is a billboard batch's world-root card, which does not despawn with its anchor.
 #[derive(Component, Clone, Copy)]
 pub(in crate::entities) struct DressedPart {
     pub(in crate::entities) index: u32,
     pub(in crate::entities) card: Option<Entity>,
 }
 
-/// The material variants one part draws through, after the per-appearance character swap: the
-/// steady exterior material, its interior-matte / interior-bake law twins, and the `Blend` twins the
-/// appear/despawn ramps feather on.
-///
-/// One function answers it for both the spawn and the re-dress, which is the point: "which material
-/// does this batch wear?" has exactly one implementation, so a gear change can never dress a body
-/// differently from the way it was first built.
+/// The material variants one part draws through, after the character swap.
 pub(super) struct PartMaterials<'a> {
     pub(super) steady: &'a Handle<WowModelMaterial>,
     pub(super) interior: Option<&'a Handle<WowModelMaterial>>,
     pub(super) fade_blend: Option<&'a Handle<WowModelMaterial>>,
     pub(super) bake: Option<&'a Handle<WowModelMaterial>>,
     pub(super) bake_blend: Option<&'a Handle<WowModelMaterial>>,
-    /// The depth-prime twin (decision 0831) — carried per appearance like the rest, since its
-    /// cutout discard samples the same swapped texture.
+    /// The depth-prime twin, swapped per appearance too: its cutout samples the same texture.
     pub(super) zfill: Option<&'a Handle<WowModelMaterial>>,
 }
 
-/// Select `part`'s materials: on a character-slot batch the per-appearance variants over the
-/// composited body atlas / hair / cape / extra-skin textures (decisions 0041 / 0044 / 0045) — the
-/// body and the extra skin at the batch's own sidedness, since a robe skirt is authored two-sided
-/// and the closed body is not — and on every other batch the ones the shared model was built with.
+/// `part`'s materials: its character slot's per-appearance set (body and extra skin at the
+/// batch's own sidedness), else the ones the shared model was built with.
 pub(super) fn part_materials<'a>(
     part: &'a EntityPart,
     char_mats: &'a CharSkinMaterials,
@@ -103,13 +78,8 @@ pub(super) fn part_materials<'a>(
     }
 }
 
-/// The material store and the two animated-material registries, for the one entity population
-/// that needs a material of its **own** rather than the batch's (decision 2295).
-///
-/// Taken as one bundle, and taken by the dressing path itself rather than by a system that fixes
-/// parts up afterwards, because the cloned handles have to be in hand *before* the part's
-/// [`InteriorLit`](benilla_world::interior) and [`FadeMaterials`] are built from them — a later
-/// pass would have to reach into both and rewrite what the classifier already wrote.
+/// The material store and animated-material registries for a part that needs materials of its
+/// own; taken at spawn, since the part's interior and fade records are built from the clones.
 pub(super) struct OwnMats<'a> {
     pub(super) store: &'a mut Assets<WowModelMaterial>,
     pub(super) uv: &'a mut benilla_world::doodad_anim::UvAnimMaterials,
@@ -117,8 +87,7 @@ pub(super) struct OwnMats<'a> {
     pub(super) table: &'a mut benilla_world::mat_anim_table::MatAnimTable,
 }
 
-/// One part's **own** variant set — [`PartMaterials`]' owning twin, held by the spawn for as long
-/// as it takes to dress the part.
+/// One part's own variant set, the owning form of [`PartMaterials`].
 struct OwnedMaterials {
     steady: Handle<WowModelMaterial>,
     interior: Option<Handle<WowModelMaterial>>,
@@ -141,25 +110,10 @@ impl OwnedMaterials {
     }
 }
 
-/// Give this part a material set of its **own**, registered against its own instance's anim host —
-/// or `None`, which is every part but a measured thirteen batches (decision 2295).
-///
-/// **Who needs one.** A batch whose file-sequence slots bake *different* UV or tint loops cannot be
-/// served by a material every instance of the model shares: the registries are keyed by material,
-/// so one row would have to answer for placements that are playing different slots. That is
-/// 1408's finding, and the entity side of it is six GameObject models — `BloodOfHeroes`'s five
-/// bubble sheets (slot 0 holds them still, slot 1 sweeps them, at freq 16384/16383, so the pools
-/// bubble independently), `Valentines_Blanket`, `G_GnomeTerminal`'s screen, and on the tint
-/// channel `G_FreezingTrap`'s glow card, `OrgrimmarPentagram` and `ScholomanceCrystalBall01`.
-/// **Four of the five tint batches bake nothing in slot 0**, so their shared material can only
-/// ever seed white however faithfully it is ticked — the hunter's trap glows flat instead of
-/// pulsing blue-white as it arms.
-///
-/// **Why it is gated on `GameObject`.** Not as a safety valve: the census is the reason. No unit,
-/// no player body, no corpse and no held item in the shipped corpus authors a per-sequence set on
-/// either channel (`benilla-extract entityuvscan`), so widening this past GameObjects would add a
-/// clone-and-register branch to the hottest spawn path in the client for an empty population. If
-/// a future model joins it, the gate is the line to move and this paragraph is why.
+/// Give this part materials of its own, registered against its instance's clock, when its file
+/// sequences bake different UV or tint loops: the registries key by material, so a shared one
+/// cannot play two instances' slots. GameObjects only: no unit, player, corpse or held item in
+/// the shipped data authors such a set (`benilla-extract entityuvscan`).
 fn own_per_sequence_materials(
     part: &EntityPart,
     dress: &PartDress<'_>,
@@ -171,15 +125,11 @@ fn own_per_sequence_materials(
         return None;
     }
     let src = part_materials(part, dress.char_mats);
-    // The shared variants may still be PARKED (`model_render::lazy` reserves a handle and holds
-    // the value until something view-visible binds it), so each is realized before it is read —
-    // the same order `spell_fx`'s clone takes, and the reason 2038's registrations all returned
-    // `None` when they skipped it.
+    // A shared variant may still be parked (`model_render::lazy`): realize it before reading.
     let mut clone = |h: &Handle<WowModelMaterial>| -> Option<Handle<WowModelMaterial>> {
         benilla_world::model_render::lazy::realize(own.store, h.id());
         let mut mat = own.store.get(h.id()).cloned()?;
-        // A clone leaves the shared table (decision 1381): its rows are its own, and a carried
-        // slot would add the shared delta on top of them.
+        // A clone leaves the shared table: a carried slot would add the shared delta to its rows.
         mat.extension.anim_slots = Vec4::ZERO;
         Some(own.store.add(mat))
     };
@@ -189,13 +139,10 @@ fn own_per_sequence_materials(
         fade_blend: src.fade_blend.and_then(&mut clone),
         bake: src.bake.and_then(&mut clone),
         bake_blend: src.bake_blend.and_then(&mut clone),
-        // The depth-prime twin is NOT cloned and NOT registered, exactly as on the placed-doodad
-        // lane: it draws only while the part feathers, and its alpha test reading unscrolled UVs
-        // for those frames is the behaviour the streamer has always had.
+        // Neither cloned nor registered, as on the doodad lane: it draws only while feathering.
         zfill: src.zfill.cloned(),
     };
-    // Every variant the part can swap to over its life — indoors, feathering, both — takes a row,
-    // or a GameObject that walks under a roof would stop mid-scroll.
+    // Every variant the part can swap to takes a row, or it stops mid-scroll indoors or fading.
     for id in [
         Some(&owned.steady),
         owned.interior.as_ref(),
@@ -233,21 +180,10 @@ fn own_per_sequence_materials(
     Some(owned)
 }
 
-/// Put this part in `tick_anim_materials`' draw scan — **iff something registered a row for it**.
-///
-/// The marker and the registration have to ask ONE question, because 2038's whole bug class is the
-/// two disagreeing: a marked part with no registry entry trips the lane's own tripwire, and a
-/// registered material that no marked part accounts for freezes silently, which is how every
-/// waterfall in the game stood still for three days. So this is not a predicate over the part's
-/// channels — it is a statement about what actually happened a few lines up.
-///
-/// Two registrations can have happened. The **shared** UV lane's, made inside
-/// `entity_variants` when the batch's transform moves at all (`UvLoops::animates`, which is not
-/// `uv_anim.is_some()`: a rotate-only batch answers `None` there). And this instance's **own**
-/// clone, when it has one — which is the only way the TINT channel is ever registered on an
-/// entity, and why `owned` has to be consulted rather than the part's `rgb_seq` re-tested: the
-/// clone can decline (a full table, a dead handle), and a marker for a registration that did not
-/// happen is the first half of the bug above.
+/// Put this part in `tick_anim_materials`' scan iff a row was registered for it: the shared UV
+/// lane's in `entity_variants` (`UvLoops::animates`, which a rotate-only batch passes with no
+/// `uv_anim`), or its own clone's, the only tint registration an entity gets and one that can
+/// decline. A marker without a row trips the lane's check; a row without a marker freezes.
 fn mark_mat_anim(
     child: &mut bevy::ecs::system::EntityCommands<'_>,
     part: &EntityPart,
@@ -258,9 +194,8 @@ fn mark_mat_anim(
     }
 }
 
-/// Stamp a pickable part (or card) with the pick population its kind belongs to: the mouseover
-/// pickers filter by these markers instead of kind-comparing every `WorldObject` row per frame.
-/// One site for both the mesh-part and the billboard-card spawn, so the two can't drift.
+/// Stamp a part or card with its kind's pick-population marker, which the mouseover pickers
+/// filter by.
 fn insert_pick_marker(child: &mut bevy::ecs::system::EntityCommands<'_>, kind: ModelKind) {
     match kind {
         ModelKind::GameObject => {
@@ -269,14 +204,13 @@ fn insert_pick_marker(child: &mut bevy::ecs::system::EntityCommands<'_>, kind: M
         ModelKind::Creature => {
             child.insert(CreaturePickPart);
         }
-        // Doodad/WMO parts (terrain_stream's spawns) are never dressed here and take no marker.
+        // Doodad and WMO parts are never dressed here.
         ModelKind::Doodad | ModelKind::Wmo => {}
     }
 }
 
 impl<'a> PartMaterials<'a> {
-    /// The three handles the appear/despawn ramps feather through — this batch's slice of
-    /// [`FadeSet`], so the spawn and the fade can never disagree about which twin it wears.
+    /// This batch's [`FadeSet`], the handles the appear and despawn ramps feather through.
     pub(super) fn fade_set(&self) -> FadeSet<'a> {
         FadeSet {
             steady: self.steady,
@@ -287,52 +221,35 @@ impl<'a> PartMaterials<'a> {
     }
 }
 
-/// Everything one part's spawn reads from its UNIT — gathered once per visual so the per-part body
-/// isn't a twenty-argument call, and so the spawn path and the re-dress path provably feed it the
-/// same things.
+/// Everything a part's spawn reads from its unit, gathered once per visual.
 pub(super) struct PartDress<'a> {
-    /// The unit whose model this is: the parent, the interior classifier's anchor, the animation
-    /// clock every `MatAnim` follows.
+    /// The parent, the interior classifier's anchor and the clock every `MatAnim` follows.
     pub(super) unit: Entity,
     pub(super) kind: ModelKind,
     pub(super) char_mats: &'a CharSkinMaterials,
     /// Identity for the mouseover inspector, cloned onto every part and card.
     pub(super) object: &'a WorldObject,
-    /// `0` = the palette table was full: parts fall back to the static bind-pose mesh.
+    /// `0`: no palette slot, so parts draw the static bind-pose mesh.
     pub(super) inst_slot: u16,
-    /// Whether the unit built a rig at all — the gate on a part drawing its skinned twin.
+    /// Whether the unit built a rig: its skinned parts leave the view cull to the root.
     pub(super) rigged: bool,
-    /// Bone index → anchor entity, for a billboard batch's card to ride its live joint. Resolved
-    /// by the CALLER through `RigPose::anchor_for` for exactly the card bones this dress will
-    /// spawn (decision 1355) — owned, because the resolver needs `&mut` on the pose and this
-    /// context is shared immutably across every part.
+    /// Bone to anchor entity for billboard cards, resolved by the caller, since
+    /// `RigPose::anchor_for` needs `&mut` on the pose.
     pub(super) anchors: std::collections::HashMap<u16, Entity>,
-    /// The model's interior fold reference (model-local) — one verdict per unit, so a body can
-    /// never split across the two light laws.
+    /// The model-local interior fold point: one verdict per unit, so a body never splits across
+    /// the two light laws.
     pub(super) bake_center: Vec3,
-    /// The armed idle's authored CAaBox — the mouseover picker's volume for a skinned part.
+    /// The armed idle's authored CAaBox, the picker's volume for a skinned part.
     pub(super) idle_aabb: Option<Aabb>,
     /// `Time::elapsed_secs`, for a part joining a ramp already in progress.
     pub(super) now: f32,
-    /// What this part should do about the unit's appear-fade. A fresh visual passes
-    /// `Pending { since: now }` (decision 0032); a part spawned by a **re-dress** JOINS whatever the
-    /// unit's own clock says ([`benilla_world::model_fade::join_unit_appear_fade`]), exactly as a
-    /// late-resolving held item does — so a gear change during the login cascade neither pops the
-    /// new geoset opaque over a still-feathering body nor restarts a second ramp beside it.
+    /// `Pending` for a fresh visual; a re-dress joins the unit's own appear-fade clock, so a new
+    /// geoset neither pops opaque nor starts a second ramp.
     pub(super) fade: JoinedFade,
 }
 
-/// Spawn one part of `dress.unit`'s model as a child of it, dressed by [`part_materials`]. Returns
-/// whether it armed an appear-fade — the attach path mirrors that onto the unit root so a held item
-/// resolving later can join the same ramp.
-///
-/// A **billboard** batch (a glow card / chain) can't spawn as an ordinary child: its mesh is centred
-/// at the bone pivot and its transform belongs to the billboard system, so as a plain child it would
-/// render at the model origin (the "glow on the ground" family, decision 0153). It spawns as a
-/// lightweight mirror anchor under the unit plus a world-root card following the anchor's live joint.
-/// [`spawn_part`] for a merged group (`attach::merge`): the synthetic group part, the first
-/// member's index, and the member list the redress reads back. A singleton passes `None` and
-/// is exactly [`spawn_part`].
+/// [`spawn_part`] for a merged group: the group part, its first member's index, and for more than
+/// one member the list the re-dress reads back.
 pub(super) fn spawn_group(
     commands: &mut Commands,
     part: &EntityPart,
@@ -345,8 +262,8 @@ pub(super) fn spawn_group(
     spawn_part(commands, part, group.first() as usize, members, dress, own)
 }
 
-/// Spawn one mesh part (or billboard card) of a body under `dress.unit`; `group` is the merged
-/// member list for a group of several batches (`None` for a batch of its own).
+/// Spawn one mesh part or billboard card of a body under `dress.unit`; returns whether it armed
+/// an appear-fade, which the attach path mirrors onto the root for later held items to join.
 pub(super) fn spawn_part(
     commands: &mut Commands,
     part: &EntityPart,
@@ -358,24 +275,19 @@ pub(super) fn spawn_part(
     if let Some(info) = &part.billboard {
         return spawn_billboard_part(commands, part, index, info, dress, own);
     }
-    // A material of this instance's OWN, for the measured thirteen batches whose slots disagree
-    // (2295) — resolved first, because everything below dresses from whatever this returns.
+    // Resolved first: everything below dresses from it.
     let owned = own_per_sequence_materials(part, dress, own);
     let mats = match &owned {
         Some(o) => o.borrow(),
         None => part_materials(part, dress.char_mats),
     };
     let set = mats.fade_set();
-    // A freshly-streamed CGObject appear-fades in (decision 0032): spawn already on the blend twin
-    // with a ≈0 `MeshTag`, so it doesn't flash opaque for a frame before `apply_render_fade` ramps
-    // `α = t³`. A joiner computes the ramp's *current* alpha rather than 0, so it doesn't flash
-    // invisible for a frame either.
+    // A fresh part spawns on its blend twin at alpha ≈0 and a joiner at the ramp's current alpha,
+    // so neither flashes for a frame before `apply_render_fade` ramps `α = t³`.
     let effective = PartFade::resolve(dress.fade, &set);
     let (init_mat, tag_alpha) = effective.seed(&set, dress.now);
-    // A skinned creature part draws its skinned-mesh twin (the WOW joint attributes → the
-    // owned-palette `WOW_RIG_SKIN` shader path, decision 0720); everything else — and the
-    // palette-full fallback (slot 0) — the static mesh. Keyed on the part having a twin, which the
-    // slot alone no longer implies.
+    // A part with a palette slot and a skinned twin draws the twin (`WOW_RIG_SKIN`); any other
+    // draws the static mesh.
     let skinned = dress.inst_slot != 0 && part.skinned_mesh.is_some();
     let mesh = match &part.skinned_mesh {
         Some(sm) if skinned => sm.clone(),
@@ -390,18 +302,15 @@ pub(super) fn spawn_part(
             kind: dress.kind,
             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 `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).
+        // The portrait booth's mirror: both mesh twins (the booth poses the skinned one at Stand,
+        // as the reference's bake `0x524f60` does) and the steady material, never a fade variant.
         crate::portrait::PortraitPart {
             static_mesh: part.mesh.clone(),
             skinned_mesh: part.skinned_mesh.clone(),
             material: mats.steady.clone(),
         },
         dress.object.clone(),
-        // The picker's triangles (decision 0857): the render meshes are `RENDER_WORLD`-only, so
-        // the ray pickers read the model's resident geometry instead.
+        // The render meshes are `RENDER_WORLD`-only, so the ray pickers read this geometry.
         benilla_world::interact::PickMesh(part.geometry.clone()),
         DressedPart {
             index: index as u32,
@@ -412,52 +321,33 @@ pub(super) fn spawn_part(
         child.insert(group);
     }
     insert_pick_marker(&mut child, dress.kind);
-    // Every part gets a tag: the instance slot plus the live alpha field. Unconditional because the
-    // slot is a per-instance identity every part needs (the tint) rather than a skinning detail —
-    // and because the two conditional writers that used to seed it (the interior classifier, the
-    // animated-alpha compose) each covered only their own subset, leaving a part in neither with no
-    // tag at all.
+    // Every part gets a tag, the instance slot and the live alpha: the slot is the instance's
+    // identity (the tint reads it), not a skinning detail.
     child.insert(MeshTag(benilla_world::mesh_tag::spawn_tag(
         dress.inst_slot,
         tag_alpha,
     )));
-    // `RigPart` stays gated on actually being skinned by that rig — it is the CPU-side link for the
-    // mouseover picker's skinned ray test (decision 0720), which has nothing to say about a static
-    // part.
+    // The picker's skinned ray test links through `RigPart`, so only a skinned part takes it.
     if skinned {
         child.insert(benilla_world::rig_palette::RigPart(dress.unit));
     }
     if dress.rigged && part.skinned_mesh.is_some() {
-        // A skinned entity part is never PART-culled: the reference tests ONE sphere per scene
-        // 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, 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
-        // 0834: the static mesh is `RENDER_WORLD`-only, so its main-world data — which the old
-        // `compute_aabb` fallback read — is gone after extract). Both `calculate_bounds` queries
-        // skip `NoFrustumCulling` entities, so this box survives.
+        // The reference elects one sphere per object each frame, never one per batch
+        // (`0x683340`), so the root's election owns the view cull (`exterior_cull`) and
+        // `NoFrustumCulling` keeps Bevy's per-part test away. The `Aabb` then serves only the
+        // picker: the idle's authored CAaBox, else the build-time bind box, which
+        // `calculate_bounds` leaves alone on a `NoFrustumCulling` entity.
         let picker_aabb = dress.idle_aabb.or(part.aabb);
         if let Some(aabb) = picker_aabb {
             child.insert((aabb, NoFrustumCulling));
         }
     } else if let Some(aabb) = part.aabb {
-        // A STATIC part (a boneless GameObject model, a WMO-display batch) keeps Bevy's ordinary
-        // frustum cull — but its bind-pose box must be inserted here now (decision 0834):
-        // `calculate_bounds` used to derive it from the mesh's main-world data, which the
-        // `RENDER_WORLD`-only static form no longer has after extract.
+        // A static part keeps Bevy's frustum cull on its build-time box: the `RENDER_WORLD`-only
+        // mesh leaves `calculate_bounds` nothing to derive one from.
         child.insert(aabb);
     }
-    // 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 (`0x69e4c0`, `0x6a7300`),
-    // with the matte ×1.0 as the bake's miss fallback.
+    // Indoor lighting, anchored at the unit root so every part shares its verdict: 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 +357,8 @@ pub(super) fn spawn_part(
     ) {
         child.insert(lit);
     }
-    // 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.
+    // Animated material alpha (`0x707680`), authored per sequence: it samples the unit's own
+    // `AnimationPlayer`, in phase with the pose.
     if let Some(anim) = &part.alpha_anim {
         child.insert(benilla_world::doodad_anim::MatAnim::following(
             anim.clone(),
@@ -481,11 +369,9 @@ pub(super) fn spawn_part(
     effective.dress(&mut child, &set)
 }
 
-/// The camera-facing half of [`spawn_part`]: a mirror anchor under the unit (so the portrait /
-/// paper-doll booths can rebuild the batch — the visible card is a world ROOT and can never be
-/// mirrored) plus the card itself, following the batch's live joint when the unit is rigged and the
-/// anchor otherwise. Returns whether the card armed the unit's appear-fade, exactly as a mesh part
-/// does: the batch is the model's, so it fades with the model (decision 0836).
+/// A billboard batch, whose transform belongs to the billboard system: a mirror anchor under the
+/// unit for the portrait booths, and a world-root card following the batch's live joint, or the
+/// anchor when the unit is unrigged.
 fn spawn_billboard_part(
     commands: &mut Commands,
     part: &EntityPart,
@@ -503,13 +389,11 @@ fn spawn_billboard_part(
                 mesh: part.mesh.clone(),
                 material: part.material.clone(),
                 bone: info.bone,
-                // A rigged host's billboard bone already bakes the pivot into its booth joint (the
-                // 0130 rig identity) — and the batch belongs to the host's body, so a mount's own
-                // glow card prunes with the mount (`DressedLook::collect`).
+                // A batch of the host's body, so a mount's glow card prunes with the mount
+                // (`DressedLook::collect`).
                 seat: crate::portrait::PortraitSeat::Body,
                 kind: info.kind,
-                // A batch of the HOST model, not a sub-model in an attachment node — the
-                // reference's attach reset walks the attachment list and cannot reach it.
+                // Not an attachment's sub-model: the reference's attach reset cannot reach it.
                 attach: None,
             },
         ))
@@ -523,14 +407,9 @@ fn spawn_billboard_part(
     } else {
         BillboardCard::following(info, owner)
     };
-    // A card is a batch of the unit's own model, so it joins the unit's appear-fade like any other
-    // batch of it — the reference has ONE instance alpha per model and every batch draws through it
-    // (decision 0836). Splitting the batch into a world-root entity is benilla's parenting detail;
-    // it is not a reason for the glow on a weapon's gems to blaze at full strength over a body that
-    // has not appeared yet.
-    // A card may need a material of its own for exactly the same reason a mesh part does — and
-    // on this population it is the card that needs it: `World\Goober\G_FreezingTrap`'s animated
-    // batch IS the additive glow card, whose blue-white pulse is keyed in file slot 2 alone.
+    // The reference has one instance alpha per model, so a card joins the unit's appear-fade like
+    // any batch. It may need materials of its own like a mesh part: `G_FreezingTrap`'s animated
+    // batch is its additive glow card, keyed in file slot 2 alone.
     let owned = own_per_sequence_materials(part, dress, own);
     let mats = match &owned {
         Some(o) => o.borrow(),
@@ -548,23 +427,17 @@ fn spawn_billboard_part(
             blend: part.blend,
         },
         dress.object.clone(),
-        // The picker's triangles (decision 0857) — the caster centres a card at its pivot, the
-        // same bake the render form draws with.
+        // The picker's triangles, centred at the pivot like the render form.
         benilla_world::interact::PickMesh(part.geometry.clone()),
         card_follow,
     ));
     insert_pick_marker(&mut card, dress.kind);
-    // A card takes its MODEL's indoor law through the same constructor as the sibling meshes it was
-    // split out of (decision 0778), and carries the unit's INSTANCE slot like every sibling part
-    // even though it is never skinned by it — it is a batch of the unit's own model, so a tinted
-    // unit tints its eye-glow and torch cards too (decision 0812). No char-slot variants are
-    // consulted: a body/hair/cape/skin-extra batch is never a billboard batch.
+    // The unit's instance slot, though the card is never skinned: a tinted unit tints its cards.
     card.insert(MeshTag(benilla_world::mesh_tag::spawn_tag(
         dress.inst_slot,
         tag_alpha,
     )));
-    // The card's build-time bound (decision 0834) — `calculate_bounds` can no longer derive one
-    // from the `RENDER_WORLD`-only static form's data.
+    // The build-time bound: the `RENDER_WORLD`-only mesh leaves `calculate_bounds` nothing.
     if let Some(aabb) = part.aabb {
         card.insert(aabb);
     }
@@ -577,23 +450,17 @@ fn spawn_billboard_part(
     ) {
         card.insert(lit);
     }
-    // A card shares its batch's per-sequence alpha loops (the billboard split copies them onto every
-    // group), sampled off the same unit clock as the mesh parts.
+    // The batch's per-sequence alpha, off the same unit clock as the mesh parts.
     if let Some(anim) = &part.alpha_anim {
         card.insert(benilla_world::doodad_anim::MatAnim::following(
             anim.clone(),
             dress.unit,
         ));
     }
-    // …and its batch's material animation, on the same rule as a mesh part (2295). A card is a
-    // batch of the unit's own model; the split into a world-root entity is benilla's parenting
-    // detail, never a reason for one batch of a model to animate and its sibling not to — and on
-    // this population it is the card that carries it.
     mark_mat_anim(&mut card, part, &owned);
     let armed = effective.dress(&mut card, &set);
     let card = card.id();
-    // The card follows the JOINT when the unit is rigged, so it does not cascade with the anchor's
-    // despawn — the re-dress has to name it to reap it (see [`DressedPart::card`]).
+    // The card does not despawn with the anchor, so the anchor names it for the re-dress to reap.
     commands.entity(anchor).insert(DressedPart {
         index: index as u32,
         card: Some(card),
@@ -605,9 +472,7 @@ fn spawn_billboard_part(
 mod tests {
     use super::*;
 
-    /// A standalone [`OwnMats`] for the spawn tests — none of them dresses a GameObject, so the
-    /// lane is never taken; it exists so the spawn's signature can stay non-optional, which is
-    /// what stops a production caller passing `None` and silently losing the clone.
+    /// A standalone [`OwnMats`]; no test here dresses a GameObject, so its lane is never taken.
     #[derive(Default)]
     struct TestOwn {
         store: Assets<WowModelMaterial>,
@@ -628,8 +493,7 @@ mod tests {
     }
     use benilla_world::model_fade::{FadeMaterials, PendingAppearFade};
 
-    /// One synthetic batch at `char_slot`/`two_sided`, carrying its own (distinguishable) built
-    /// material set so the fallback arm is visible in the assertions.
+    /// One synthetic batch with its own distinguishable built material.
     fn part(char_slot: Option<CharSkinSlot>, two_sided: bool) -> EntityPart {
         EntityPart {
             mesh: Handle::default(),
@@ -660,8 +524,7 @@ mod tests {
         }
     }
 
-    /// A distinguishable material handle — a stable-id (`Uuid`) handle, which needs no `Assets`
-    /// store behind it and compares by identity like any other.
+    /// A distinguishable `Uuid` handle, which needs no `Assets` store behind it.
     fn mat(n: u128) -> Handle<WowModelMaterial> {
         Handle::Uuid(
             bevy::asset::uuid::Uuid::from_u128(n + 1),
@@ -669,7 +532,7 @@ mod tests {
         )
     }
 
-    /// A set of six distinguishable handles, so which variant landed where is checkable.
+    /// Six distinguishable handles.
     fn quint(seed: u128) -> super::super::char_skin::MatQuint {
         (
             mat(seed * 8),
@@ -681,9 +544,7 @@ mod tests {
         )
     }
 
-    /// The character swap picks a slot's quint — and the BODY (and extra skin) pick by the batch's
-    /// own sidedness, because a robe skirt (geoset 1302) is authored two-sided while the closed body
-    /// is not; flattening them to one variant culled the robe's inner faces (see-through from below).
+    /// A robe skirt (geoset 1302) is authored two-sided while the closed body is not.
     #[test]
     fn a_character_batch_takes_its_slots_variants_at_its_own_sidedness() {
         let single = quint(1);
@@ -710,13 +571,8 @@ mod tests {
         assert_eq!(m.bake_blend, Some(&hair.4));
     }
 
-    /// **`FadeMaterials` is a material RECORD, not a record of having armed a fade.** It used to be
-    /// inserted only alongside the appear-fade arm, so a part spawned by anything that isn't a spawn
-    /// — which, before decision 0835, meant a body rebuilt on *every gear change* — carried none at
-    /// all. Two things read it and both silently stopped working for a player who had swapped so
-    /// much as a shirt: the stream-out fade (`arm_despawn_descendants` gates on it) and, worse, the
-    /// self-avatar first-person feather, whose query takes `&FadeMaterials` outright — so your own
-    /// body stayed solid in your face. The item lane always did it this way; the body lane does now.
+    /// `FadeMaterials` is a material record, not a fade record: the stream-out fade and the
+    /// first-person feather read it off a part that spawned steady.
     #[test]
     fn a_steady_spawn_still_records_its_fade_materials() {
         let mut app = App::new();
@@ -767,13 +623,8 @@ mod tests {
         assert!(!found[0].1, "…without arming an appear fade");
     }
 
-    /// **A camera-facing batch fades with its model** (decision 0836): the split into a world-ROOT
-    /// card is benilla's parenting detail (0153), not a law — the reference has one instance alpha
-    /// per `CM2Model` and every batch draws through it, billboard batches included. The card used
-    /// to open at a flat opaque with no arm and no record, which is a night-elf's eye glow and an
-    /// undead's shoulder wisps burning at full strength over a body still at α 0.
-    ///
-    /// Asserted on the CARD, not the anchor: the anchor is a bare mirror carrier with no geometry.
+    /// The reference has one instance alpha per `CM2Model`, billboard batches included. Asserted
+    /// on the card, not the anchor, which has no geometry.
     #[test]
     fn a_billboard_card_joins_the_units_appear_fade() {
         const SINCE: f32 = 5.0;
@@ -848,11 +699,8 @@ mod tests {
         );
     }
 
-    /// The dress path stamps every pickable spawn — the mesh part and the billboard CARD (never
-    /// the bare mirror anchor) — with exactly its kind's pick-population marker, so the mouseover
-    /// pickers' marker-filtered sets equal the old kind-filtered ones by construction. Asserted
-    /// differentially: the marker set must equal the `WorldObject`-kind set, and the other kind's
-    /// marker must land on nothing.
+    /// The marker set equals the `WorldObject`-kind set (the mesh part and the card, never the
+    /// anchor), and the other kind's marker lands on nothing.
     #[test]
     fn a_spawned_part_carries_its_kinds_pick_marker() {
         for kind in [ModelKind::Creature, ModelKind::GameObject] {
@@ -935,15 +783,13 @@ mod tests {
         }
     }
 
-    /// A batch with no character slot — and a slot whose row the appearance didn't resolve (a bald
-    /// style has no hair texture, only tauren author an extra skin) — keeps the shared model's own
-    /// built materials. That is the arm a creature, a GameObject and an unresolvable look all take.
+    /// A slot the look did not fill (a bald style, a non-fur race) keeps the model's built
+    /// materials, like a batch with no slot, never another slot's set.
     #[test]
     fn an_unswapped_batch_keeps_the_models_own_materials() {
         let empty: CharSkinMaterials = (None, None, None, (None, None));
         let plain = part(None, false);
         assert_eq!(*part_materials(&plain, &empty).steady, plain.material);
-        // A slot the look didn't fill falls to the same place, not to another slot's quint.
         let mats: CharSkinMaterials = (Some((quint(1), quint(2))), None, None, (None, None));
         let bald = part(Some(CharSkinSlot::Hair), false);
         assert_eq!(*part_materials(&bald, &mats).steady, bald.material);
diff --git a/crates/benilla-app/src/entities/attach/merge.rs b/crates/benilla-app/src/entities/attach/merge.rs
index 9f9a3649..ec6e9eb9 100644
--- a/crates/benilla-app/src/entities/attach/merge.rs
+++ b/crates/benilla-app/src/entities/attach/merge.rs
@@ -1,39 +1,9 @@
-//! **A body's batches, merged by material** — one mesh entity per *material group* of a dressed
-//! body instead of one per authored M2 batch (decision 1940, the crowd rig's first proposal).
-//!
-//! A geared level-60 body stands as 12–27 mesh parts binding 5–16 distinct materials (the dress
-//! census's `parts=`/`mats=`, read off a 40-man raid at the Stormwind auction house): the skin
-//! composite serves the torso, arms, legs, hands and feet as separate opaque batches, the hair
-//! texture serves the hair and the facial geosets, and every one of those was its own entity —
-//! its own row in every per-entity sweep Bevy and we run each frame (bounds, specialization,
-//! visibility, extraction, the material walk), its own phase item, its own draw with its own
-//! bind-group and vertex-buffer sets in wgpu's pass encoder. The raid's cost is that population,
-//! not a hot function (1929), and per body about 40 % of it is batches that draw with a material
-//! the batch beside it already binds.
-//!
-//! **What merges.** Two visible batches of one body join when they would be *indistinguishable*
-//! to everything downstream of the spawn: the same six-handle material set (steady, the two
-//! interior lanes, the fade twins, the depth-prime twin — every component derived from them is
-//! then identical), the same blend/sidedness, both static or both skinned, and neither carrying
-//! per-batch state the merge cannot represent: an animated alpha track, a billboard, a welded
-//! billboard seam, a ground-decal quad. Transparent batches never meet — their material key
-//! carries the authored batch order (`model_render::MatKey::batch_order`), so each has its own
-//! handle by construction and painter's order is untouched. The key is *static*: which slot a
-//! batch's texture comes from and its authored flags, never the texture itself — so a gear change
-//! that swaps the composite re-points a group's material in place exactly as it re-pointed a
-//! part's, and only a change to the *visible set* (a geoset the new gear hides or reveals)
-//! rebuilds the groups it touches.
-//!
-//! **What a group is.** A synthetic [`EntityPart`] cloned from its first member, with the
-//! geometry replaced by the members' concatenation and the render forms built from it the way
-//! `model_forms` builds a batch's — the static form `RENDER_WORLD`-only, the skinned twin keeping
-//! its main-world copy for the picker (0834's contract, unchanged). The concatenated
-//! [`RenderSubmesh`] is also the group's [`PickMesh`], so the mouseover ray still tests the
-//! resident geometry it always did. Merged forms are cached per (model geometry, member set):
-//! forty humans in the same gear silhouette share them the way they shared the per-batch forms.
-//!
-//! Attach models (helm, shoulders, held items) are their own M2s with their own roots and are not
-//! in scope here; a body's billboard cards keep their own spawner (`dress::spawn_billboard_part`).
+//! A body's batches merged by material: one mesh entity per group of batches that nothing
+//! downstream of the spawn can tell apart (the same six-handle material set, blend, sidedness and
+//! skinning, and no alpha track, billboard, welded seam or ground quad), not one per M2 batch.
+//! A batch's own materials are keyed by its authored order (`MatKey`'s `batch_order`), so two
+//! transparent batches never merge. The key names a texture slot, never a texture, so a gear
+//! change re-points a group in place and only a change to the shown set rebuilds groups.
 
 use std::collections::HashMap;
 use std::sync::Arc;
@@ -50,17 +20,16 @@ use super::super::EntityPart;
 use super::char_skin::CharSkinMaterials;
 use super::dress::part_materials;
 
-/// The members of a merged group, on the group's entity beside its `DressedPart` (whose `index`
-/// is the first member). Absent on a singleton.
+/// A merged group's member indices, beside its `DressedPart` (whose `index` is the first member);
+/// absent on a singleton.
 #[derive(Component, Clone)]
 pub(in crate::entities) struct DressedGroup(pub(in crate::entities) Arc<[u32]>);
 
-/// What makes two of one body's batches interchangeable downstream of the spawn. Built from the
-/// part's *slot* and flags, never from a resolved texture — see the module doc.
+/// What makes two of a body's batches interchangeable: the material slot and flags, never a
+/// resolved texture.
 #[derive(Clone, PartialEq, Eq, Hash)]
 struct MergeKey {
-    /// The slot the material comes from: a character slot, or the batch's own built materials
-    /// (identified by their handles — the same six for every batch sharing a texture).
+    /// A character slot, or the batch's own six built material handles.
     source: MaterialSource,
     blend: ModelBlend,
     additive: bool,
@@ -116,8 +85,8 @@ impl BodyGroup {
     }
 }
 
-/// Partition the shown parts of a body into spawn groups, in first-member order. `shows` is the
-/// geoset predicate the dress and the redress both evaluate.
+/// Partition a body's parts that `shows` (the geoset predicate) into spawn groups, in
+/// first-member order.
 pub(in crate::entities) fn group_parts(
     parts: &[EntityPart],
     shows: impl Fn(&EntityPart) -> bool,
@@ -144,15 +113,10 @@ pub(in crate::entities) fn group_parts(
     groups
 }
 
-/// The members' geometry as one submesh: attributes concatenated, indices re-based. Every member
-/// shares the first's material facts by construction of the key, so the first's texture, flags
-/// and slots are the group's.
+/// The members' geometry as one submesh, indices re-based; the key makes the first member's
+/// material facts the group's.
 fn concat_geometry(first: &RenderSubmesh, rest: &[&RenderSubmesh]) -> RenderSubmesh {
     let mut out = first.clone();
-    // Per-vertex attributes that are either full-length or absent on every member: a mismatch
-    // in presence would leave the group half-attributed, so the merge key keeps such batches
-    // apart only implicitly (a model authors these per skin, not per batch); assert the
-    // invariant rather than guess.
     for sub in rest {
         let base = u32::try_from(out.positions.len()).expect("merged vertex count fits u32");
         out.positions.extend_from_slice(&sub.positions);
@@ -170,9 +134,8 @@ fn concat_geometry(first: &RenderSubmesh, rest: &[&RenderSubmesh]) -> RenderSubm
     out
 }
 
-/// Extend a per-vertex attribute so it stays either exactly full-length or empty: a member
-/// without it drops the attribute for the whole group (the renderer recomputes normals; a
-/// missing skin on any member means the group is not skinned, which the key already ensured).
+/// Extend a per-vertex attribute so it stays full-length or empty: one member without it drops it
+/// for the whole group.
 fn extend_matched<T: Copy>(dst: &mut Vec<T>, src: &[T], full: usize) {
     if dst.is_empty() && src.is_empty() {
         return;
@@ -185,8 +148,7 @@ fn extend_matched<T: Copy>(dst: &mut Vec<T>, src: &[T], full: usize) {
     }
 }
 
-/// A group's built render forms: the merged geometry (the group's `PickMesh`), its static form,
-/// its skinned twin when every member skins, and the static form's build-time bound.
+/// A group's render forms; `geometry` is also its `PickMesh`.
 #[derive(Clone)]
 pub(in crate::entities) struct MergedForms {
     pub(in crate::entities) geometry: Arc<RenderSubmesh>,
@@ -195,19 +157,15 @@ pub(in crate::entities) struct MergedForms {
     pub(in crate::entities) aabb: Option<Aabb>,
 }
 
-/// The merged-form cache, keyed by (the first member's geometry, the member set) — the geometry
-/// `Arc` is the model's own, shared by every unit of that display, so the key names one model's
-/// one silhouette. Strong handles: a cached form outlives its units the way a model's per-batch
-/// forms do, and the whole table drops past [`MERGED_FORMS_CAP`] entries rather than growing
-/// with every silhouette a session ever sees.
+/// Merged forms keyed by (the first member's geometry `Arc`, the member set): one model's one
+/// silhouette, shared by every unit of that display. Cleared whole past [`MERGED_FORMS_CAP`].
 #[derive(Resource, Default)]
 pub(crate) struct MergedFormsCache(HashMap<(usize, Vec<u32>), MergedForms>);
 
 const MERGED_FORMS_CAP: usize = 1024;
 
 impl MergedFormsCache {
-    /// The forms of `group` over `parts`, built on a miss. A singleton borrows the model's own
-    /// forms and never enters the cache.
+    /// The forms of `group`, built on a miss; a singleton borrows the model's own, uncached.
     pub(in crate::entities) fn forms(
         &mut self,
         parts: &[EntityPart],
@@ -237,8 +195,7 @@ impl MergedFormsCache {
         let merged = concat_geometry(&first.geometry, &rest);
         let stat = benilla_assets::submesh_to_static_mesh(&merged);
         let aabb = stat.compute_aabb();
-        // The skinned twin exists only when every member skins AND the concatenation kept a
-        // full joint set — a group drawn static on a rigged body would stand in bind pose.
+        // Skinned only when every member skins and the joints survived the concatenation.
         let skinned = (group
             .members
             .iter()
@@ -270,9 +227,8 @@ pub(in crate::entities) fn group_part(
     part
 }
 
-/// Do two members resolve the same materials? The key promises it for the static half; this is
-/// the check the character half makes at dress time (a slot resolving to `None` — no look, no
-/// tables — falls back to the batch's own materials, which the key did not compare).
+/// Whether every member resolves the same materials at dress time: a character slot with no
+/// look falls back to each batch's own materials, which the key does not compare.
 pub(in crate::entities) fn same_materials(
     parts: &[EntityPart],
     group: &BodyGroup,
@@ -295,8 +251,7 @@ pub(in crate::entities) fn same_materials(
         .all(|&i| ids(&part_materials(&parts[i as usize], char_mats)) == want)
 }
 
-/// Split every group whose members do not resolve the same materials into singletons — the
-/// dress-time guard behind [`same_materials`]. Cheap: the resolve is a slot match.
+/// Split into singletons every group that fails [`same_materials`].
 pub(in crate::entities) fn guard_groups(
     groups: Vec<BodyGroup>,
     parts: &[EntityPart],
@@ -378,9 +333,9 @@ mod tests {
         let mut parts = vec![
             part(1, 0),    // skin
             part(2, 100),  // hair
-            part(1, 400),  // gloves — the skin's material
-            part(1, 500),  // boots — the skin's material, hidden below
-            part(2, 200),  // facial — the hair's material, but animated: singleton
+            part(1, 400),  // gloves: the skin's material
+            part(1, 500),  // boots: the skin's material, hidden below
+            part(2, 200),  // facial: the hair's material, but a welded billboard
             part(3, 1500), // cloak: static form, its own material
         ];
         parts[4].welded_billboard = true;
diff --git a/crates/benilla-app/src/entities/attach/mod.rs b/crates/benilla-app/src/entities/attach/mod.rs
index 501258fc..08da268d 100644
--- a/crates/benilla-app/src/entities/attach/mod.rs
+++ b/crates/benilla-app/src/entities/attach/mod.rs
@@ -1,11 +1,6 @@
-//! Attaching a visual to a streamed entity (decision 0006) — the back half of [`super`].
-//!
-//! [`super`] resolves + builds a [`DisplayModel`](super::DisplayModel) per display id (shared across
-//! every entity of that display); this module gives each net entity its visual once that model has
-//! loaded: the submesh children + skeleton/animation infra (creatures + player bodies), the per-player
-//! character geoset selection + skin material (decision 0041 — the appearance/material resolution
-//! lives in [`char_skin`]), particle emitters, GameObject collision, or a colored cube fallback. It
-//! reaches the shared types + caches in the parent via `super::`.
+//! Attaching a visual to each streamed entity once its shared display model has loaded: the
+//! dressed parts, the rig and sequence clock, the character look ([`char_skin`]), emitters,
+//! lights, ribbons, GameObject collision, or a debug cube for a display that names no model.
 
 use avian3d::prelude::RigidBody;
 use benilla_assets::ModelAnimations;
@@ -40,10 +35,7 @@ pub(crate) use preview::equip_slot;
 pub(super) use preview::{build_dressup_preview, build_glue_pet, build_glue_preview};
 mod redress;
 
-/// The instruments' view of one body's draw population — what `WOW_DRESS_CENSUS` prints per
-/// part (`DRESS_PARTS`): index, merge group, blend, and the material id, so "why nine draws
-/// for one body" is a line of output and not a reading of the M2. Lives here because the
-/// group and index components are this module's private bookkeeping (0026's dev seam).
+/// One body's drawn parts as `WOW_DRESS_CENSUS` prints them: index, merge group, blend, material.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct BodyPartsDesc<'w, 's> {
     parts: Query<
@@ -85,32 +77,13 @@ impl BodyPartsDesc<'_, '_> {
 }
 pub(super) use redress::redress_player_looks;
 
-/// Set up the skinned instance shared by creatures/players (decision 0019) and animated
-/// GameObjects (decision 0242): the pose buffer, the palette rig slot, and the global-sequence
-/// drive.
-///
-/// The **sequence clock** — the `AnimationPlayer` + graph + [`ModelAnimations`] + the driver that
-/// owns the choice — is NOT set up here; it is [`arm_sequence_clock`], called by the spawn site
-/// whether or not this rig was built (decision 0941). Everything in this function costs a palette
-/// slot and a skinned twin, and is worth spending only on a model whose bones actually move; the
-/// clock is worth arming on every instance, because a sequence drives far more than a pose.
-///
-/// This lane spawns **no joint entities** (decision 0724) — the pose lives in a
-/// [`benilla_world::rig_anim::RigPose`] array — and **no anchor entities either** (decision
-/// 1355): a bone gets its anchor from `RigPose::anchor_for` the moment something actually
-/// consumes it, re-seated from the composed pose each frame it changes. Returns the pose (still
-/// in hand — see [`RigBuild`]) + the palette rig slot (decision 0720), or `None` when the model
-/// has no inverse bindposes. Slot `0` = the palette table was full: anchors still resolve
-/// (emitters/attachments ride them), but parts fall back to the static bind-pose mesh. No
-/// animations ⇒ the pose just holds bind pose (Milestone A).
-///
-/// `skins` is whether anything will actually **skin through this slot** — the same law the item
-/// lane's rider states (`equipment::spawn`: "a slot only earns its keep if something will
-/// actually SKIN through it"). A body that drew no batch at all (the invisible trigger creature
-/// holding a visible weapon — decision 1656) still needs the *pose*, because its attachment
-/// points carry what IS drawn, but it has nothing of its own to skin: it takes the slot-less rig
-/// [`benilla_world::rig_anim::finalize_rig_worlds`] has supported since 1365, and no `RigStarved`
-/// marker either (there is no starvation to heal).
+/// Set up the skinned instance of a creature, player body or animated GameObject: the pose
+/// buffer, the palette slot and the global-sequence drive; the sequence clock is
+/// [`arm_sequence_clock`]'s. No joint or anchor entities are spawned: a bone's anchor comes from
+/// `RigPose::anchor_for` on first use. `None` when the model has no inverse bindposes; slot 0
+/// means no palette slot, so parts draw the static bind-pose mesh. `skins` is false for a body
+/// that draws nothing of its own (an invisible holder of a visible weapon), which still needs the
+/// pose for its attachment points but takes no slot.
 fn setup_skinned_instance(
     commands: &mut Commands,
     palettes: &mut benilla_world::rig_palette::RigPalettes,
@@ -121,20 +94,10 @@ fn setup_skinned_instance(
 ) -> Option<RigBuild> {
     let ibp = d.inverse_bindposes.as_ref()?;
     let nbones = d.skeleton.joints.len();
-    // `joints_root` — the rig's model-space frame — is normally `entity` itself; a MOUNTED
-    // rider's frame is the seat anchor instead (decision 0441), a conform-tilted model's its
-    // conform node, while the `AnimationPlayer`/driver components stay on `entity`. Skinned
-    // parts render purely from the palette, so their own parentage is free.
-    // No anchor entities are spawned here (decision 1355). A consumer bone gets its anchor the
-    // moment something actually consumes it — [`benilla_world::rig_anim::RigPose::anchor_for`],
-    // called by the emitter/ribbon/light arms, the billboard dress, held items, the mount seat,
-    // spell kits and quest markers — and the position-only readers (the overhead anchor, missile
-    // launch points, the bowstring) read `RigPose::posed_point` and never need an entity at all.
-    // The eager population this replaced was 96 % never-consumed at the LBRS pin (decision 1354).
+    // `joints_root` is the rig's model-space frame: `entity`, a mounted rider's seat anchor or a
+    // conform node, while the `AnimationPlayer` and driver stay on `entity`.
     let pose = benilla_world::rig_anim::RigPose::new(joints_root, &d.skeleton);
-    // The owned palette rig (decision 0720): the world pass writes this rig's composed frames ×
-    // these bindposes into the slot; every skinned part below tags the slot so the vertex stage
-    // finds its palette. The on-replace hook frees the slot with the visual teardown.
+    // The on-replace hook frees the palette slot with the visual.
     let slot = match skins
         .then(|| {
             benilla_world::rig_palette::RigSkin::allocate_bones(
@@ -147,23 +110,19 @@ fn setup_skinned_instance(
     {
         Some(rig) => {
             let slot = rig.slot;
-            // The marker's invariant is "currently slot-less": a heal-triggered (or any
-            // other) rebuild that lands a slot clears it, or the healer would loop.
+            // `RigStarved` means slot-less: a rebuild that lands a slot clears it, or the healer
+            // loops.
             commands
                 .entity(entity)
                 .insert(rig)
                 .remove::<benilla_world::rig_palette::RigStarved>();
             slot
         }
-        // Nothing to skin (`skins == false`): the slot-less rig, on purpose and for ever — no
-        // starvation marker, or `heal_rig_starved` would rebuild this body every time the table
-        // gained headroom, chasing a slot it will never ask for.
+        // Nothing to skin: no starvation marker, or `heal_rig_starved` would rebuild the body for a
+        // slot it never asks for.
         None if !skins => 0,
         None => {
-            // Table full (warned): parts render the static bind-pose mesh — but no longer
-            // for ever. The marker hands the unit to `heal_rig_starved` (decision 0863),
-            // which rebuilds the visual once the table has headroom; without it a mob that
-            // streamed in during a full-table window stayed a statue for its whole life.
+            // Table full: static bind-pose parts until `heal_rig_starved` rebuilds with a slot.
             commands
                 .entity(entity)
                 .insert(benilla_world::rig_palette::RigStarved);
@@ -171,38 +130,21 @@ fn setup_skinned_instance(
         }
     };
     if let Some(anims) = d.animations.as_ref() {
-        // Global-sequence bone channels (the eye-blink eyelid scale, resting fidget pulses; a GO's
-        // free-running flicker): free-clock loops the per-sequence reader drops, driven on their own clock.
-        // Rig-bound (it writes bone slots), unlike the sequence clock — which is armed by
-        // [`arm_sequence_clock`] whether or not this instance ended up with a rig.
+        // Global-sequence bone channels (an eyelid's blink) run on their own clock; they write
+        // bone slots, so unlike the sequence clock they need the rig.
         if let Some(drive) =
             benilla_world::rig_anim::GlobalSeqDrive::new_rig(&anims.global_bones, nbones)
         {
             commands.entity(entity).insert(drive);
         }
     }
-    // The pose buffer travels in the build result, NOT onto the entity yet: the arms of
-    // `attach_entity_visuals` below still resolve anchors into it (`RigPose::anchor_for` needs
-    // `&mut`), and it lands on the entity in one piece once the build is dressed. The evaluator
-    // (decision 0712) samples the player state straight into `locals`; with no joint entities and
-    // no `AnimationTargetId`s, Bevy's `animate_targets` has nothing of ours to touch.
     Some(RigBuild { pose, slot })
 }
 
-/// Arm this instance's **sequence clock**: the `AnimationPlayer` + graph + [`ModelAnimations`] that
-/// say which sequence is playing and how far into it, plus the driver that owns the choice
-/// ([`crate::go_anim::GoAnim`] for a state GameObject, `AnimDriver` for a unit).
-///
-/// Separate from the rig on purpose (decision 0941). The two used to be one call — the clock was
-/// armed inside [`setup_skinned_instance`], so an instance that wasn't worth skinning got no clock
-/// either. But a skinned pose is only ONE of the things a sequence drives: the particle emitters'
-/// rate/enable/params tracks read it (`EmitClock::Host`), so do the material alpha/colour/UV loops
-/// and the GameObject state arm. 147 GameObject display models animate **only** through those —
-/// no keyed bone anywhere — and for them "no rig" silently meant "no clock", i.e. file slot 0 at
-/// t = 0 for ever: the Molten Core rune's flames read its *Closed* band, where every emission rate
-/// key is 0, and the flame ring's spawn window never opened past its first frame. The clock is a
-/// player and a handle; the rig is a palette slot and a skinned twin. Only the second is worth
-/// gating on whether bones actually move.
+/// Arm this instance's sequence clock: the `AnimationPlayer`, graph and [`ModelAnimations`], and
+/// the driver that picks the sequence ([`crate::go_anim::GoAnim`] for a state GameObject,
+/// `AnimDriver` for a unit). Armed with or without a rig: emitters, material loops and the
+/// GameObject state arm read the playing sequence even on a model whose bones never move.
 fn arm_sequence_clock(
     commands: &mut Commands,
     entity: Entity,
@@ -210,26 +152,18 @@ fn arm_sequence_clock(
     kind: EntityKind,
     go_state_machine: bool,
 ) {
-    // **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. 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.
+    // Every GameObject gets the loader-idle seed, which the reference arms the moment the M2 goes
+    // live (`0x70ebd0`); a door's object-layer arm (`0x5f3930`) lands after it. Seeding first
+    // spares a state GO a bind-pose first frame, and playing the seed through the transitions
+    // lets the first arm fade out of it rather than leave two clips live.
     let mut player = AnimationPlayer::default();
     let mut transitions = AnimationTransitions::new();
     if kind == EntityKind::GameObject {
-        // `idle_clip`, NOT `first_seq`: the loader arm's identity answer, taken without the
-        // rendering content gate (decision 0936's split). A GameObject whose sequences pose no
-        // bone has no `first_seq` at all and used to arm nothing — which is precisely how its
-        // emitters ended up reading file slot 0 at t = 0 for ever (0941).
+        // `idle_clip`, not `first_seq`: a GameObject whose sequences pose no bone has no
+        // `first_seq`, but its emitters still read the clock.
         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 (`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.
+            // Loop iff `M2Sequence.flags` bit 0 is clear; a set bit plays the window once and
+            // holds at its end (`0x714585`).
             let active = transitions.play(&mut player, clip.node, std::time::Duration::ZERO);
             if clip.looping {
                 active.repeat();
@@ -244,20 +178,15 @@ fn arm_sequence_clock(
     match kind {
         EntityKind::GameObject if go_state_machine => {
             commands.entity(entity).insert((
-                // Cross-fades the open/close transition over the clip's blend-in time (0242/0049),
-                // and carries the seed above as the pose the first arm transitions out of.
+                // Cross-fades each transition over the clip's blend-in time, from the seed.
                 transitions,
                 crate::go_anim::GoAnim::default(),
             ));
         }
-        // A loader-idle GameObject needs no driver and no transitions — the looping player IS the
-        // whole animation, and nothing will ever arm over it.
+        // A loader-idle GameObject needs no driver: the idle is its whole animation.
         EntityKind::GameObject => {}
-        // A **corpse** gets the clock and the transitions but **no** [`AnimDriver`] (decision
-        // 1706): its pose is one settled arm ([`super::corpse::pose_corpses`]), and the driver is
-        // the *unit* gait selector — movement flags, sheath ceremony, combat, fidget — none of
-        // which an object with no movement block can answer. Enrolling it there would put a
-        // corpse in Stand.
+        // A corpse gets no `AnimDriver`: its pose is one settled arm (`pose_corpses`), and the
+        // unit gait selector would stand it up.
         EntityKind::Corpse => {
             commands
                 .entity(entity)
@@ -268,31 +197,26 @@ fn arm_sequence_clock(
             commands
                 .entity(entity)
                 .insert((
-                    // Cross-fades over each clip's blend-in time, so a gait change eases (0049).
+                    // Cross-fades over each clip's blend-in time, so a gait change eases.
                     AnimationTransitions::new(),
                     AnimDriver::default(),
                 ))
-                // A (re)built rig is born live: fresh joints spawn pointing at the root, so a
-                // stale park marker from the torn-down visual would desync the LOD gate's
-                // edge-triggered bookkeeping (decision 0448). It re-parks on its own merits.
+                // A rebuilt rig is born live: a stale park marker would desync the LOD gate's
+                // edge-triggered bookkeeping.
                 .remove::<benilla_world::rig_anim::AnimParked>();
         }
     }
 }
 
-/// A collapsed rig's build result (decision 0724): the pose buffer, still in hand so the build's
-/// own arms can resolve anchors into it (decision 1355 — anchors spawn on first consumer, via
-/// [`benilla_world::rig_anim::RigPose::anchor_for`]), + the palette slot each skinned part tags.
-/// The pose lands on the entity at the end of the build.
+/// A rig's build result: the pose, held until the build has resolved its anchors into it
+/// (`anchor_for` needs `&mut`), and the palette slot each skinned part tags.
 struct RigBuild {
     pose: benilla_world::rig_anim::RigPose,
     slot: u16,
 }
 
-/// Attach a visual to each net entity that doesn't have one yet: its built model (creature / GameObject
-/// / player body) as submesh children, or a colored cube fallback. The entity's pose is owned by the
-/// net bridge — or, for our own avatar, the player controller — we only add the geometry (and bake
-/// per-display scale onto the root). Our own avatar is the same streamed entity and renders here too.
+/// Attach a visual to each net entity without one, our own avatar included. The net bridge or the
+/// player controller owns the entity's transform; only its scale is set here.
 #[allow(clippy::type_complexity)]
 pub(super) fn attach_entity_visuals(
     mut commands: Commands,
@@ -308,35 +232,22 @@ pub(super) fn attach_entity_visuals(
         ),
         Without<VisualAttached>,
     >,
-    // The mount children's build state (decision 0441): a mounted unit's rider waits on its mount
-    // child's attach — the seat resolves through the mount's attachment-0 point (`BoneAttach`)
-    // into its `RigPose` below; the `NetEntity` is the staleness check (the field moved while
-    // the unit was still pending).
+    // A mounted rider waits on its mount child, whose attachment-0 point is the seat.
     mount_children: super::mount::MountChildren,
-    // Already-built rigs' pose buffers — the mount child's, for its seat anchor to resolve on
-    // demand (decision 1355). The unit being built here has no `RigPose` component yet (its pose
-    // is still in `RigBuild`), so the two never alias.
+    // The mount child's pose, for its seat anchor; the unit being built has none yet, so the two
+    // never alias.
     mut built_poses: Query<&mut benilla_world::rig_anim::RigPose>,
-    // The ItemDisplayInfo catalog (armor region textures, decision 0074). Read-only here; the
-    // held-item systems in the same chain hold it mutably in their own turns.
     displays: Option<Res<super::ItemDisplays>>,
     mut transforms: Query<&mut Transform>,
     assets: Res<CubeAssets>,
     creatures: Option<Res<Creatures>>,
     gameobjects: Option<Res<GameObjects>>,
-    // The bone-pile body cache (decision 1706) — the corpse lane's second model source.
+    // The bone-pile models, a corpse's second model source.
     bones: Res<super::corpse::BonesModels>,
-    // Character geoset selection (decision 0041, Milestone B): the customization tables + the entity's
-    // decoded appearance, to pick which body geosets a player shows. Absent ⇒ no filtering (every geoset).
+    // The geoset tables; absent, every geoset shows.
     characters: Option<Res<Characters>>,
-    // A character body's race/sex + customization for the geoset filter + skin materials: for a player,
-    // its decoded descriptor fields ([`ObjectStore`]); a character-model NPC reads its display instead.
     stores: Query<&ObjectStore>,
-    // Character skin (decisions 0041 / 0044 / 0045): the CharSections lookup + the bits to composite +
-    // upload the per-appearance body atlas and to load + build the hair material — the shared chain (read
-    // the BLPs), the `Image` assets + per-appearance composite cache, the asset server (async hair-BLP
-    // load), the `WowModelMaterial` assets + dedup cache, and the light buffer. Nested into one param to
-    // stay within Bevy's 16-element system-param tuple limit.
+    // The character-skin build chain, nested for Bevy's 16-param system limit.
     skin_build: (
         Option<Res<SkinSections>>,
         Option<Res<WorldAssets>>,
@@ -344,22 +255,13 @@ pub(super) fn attach_entity_visuals(
         ResMut<SkinComposites>,
         Res<AssetServer>,
         benilla_world::model_render::M2BatchMaterials,
-        // The merged-group forms (`merge`): built on a body's first silhouette, shared after.
         ResMut<Assets<Mesh>>,
         ResMut<merge::MergedFormsCache>,
-        // …and the animated-material lane a spawned part may need a material of its OWN on
-        // (decision 2295) — a GameObject whose file-sequence slots bake different UV or tint
-        // loops. Taken by the dressing path itself, because the clone has to exist before the
-        // part's interior and fade records are built from it; nested here for this tuple's own
-        // stated reason, the 16-param limit.
         ResMut<benilla_world::doodad_anim::UvAnimMaterials>,
         ResMut<benilla_world::doodad_anim::TintAnimMaterials>,
         ResMut<benilla_world::mat_anim_table::MatAnimTable>,
     ),
-    // The owned skin-palette table (decision 0720): every skinned instance claims a rig slot.
     mut palettes: ResMut<benilla_world::rig_palette::RigPalettes>,
-    // The collider-set stamp (1384): the GameObject hull insert below is the one collider lane
-    // outside the streamer's attach queue, so it dates the world itself.
     mut collider_epoch: ResMut<benilla_world::collision::ColliderEpoch>,
     time: Res<Time>,
 ) {
@@ -376,31 +278,20 @@ pub(super) fn attach_entity_visuals(
         mut tint_reg,
         mut anim_table,
     ) = skin_build;
-    // Arm each entity's appear-fade at the moment its visual attaches (≈ its first-visible moment).
     let now = time.elapsed_secs();
     for (entity, net, equipment, reattached, mount_child, mount_body, anchored) in &pending {
-        // A player attaches only once its worn-equipment resolution settles (decision 0074): the
-        // template round trips are far faster than the model load, and waiting composites the
-        // dressed atlas directly instead of flashing naked. (`None` = the resolver hasn't run yet.)
+        // A player attaches once its equipment settles, so it never flashes naked.
         if net.kind == EntityKind::Player && !equipment.is_some_and(|e| e.settled) {
             continue;
         }
-        // A **corpse** waits on the same component for a different reason (decision 1706): its gear
-        // is final on arrival, so this is not a round-trip wait but a *descriptor* wait —
-        // `resolve_corpse_equipment` runs one step earlier in this same chain and inserts the
-        // component from the store. It matters because the corpse lane has no re-dress: its gear
-        // is a death-time snapshot that cannot change, so a body composited before the descriptor
-        // landed would stay naked for as long as it lies there.
+        // A corpse waits for `resolve_corpse_equipment`: it is never re-dressed, so a body
+        // composited early would stay naked.
         if net.kind == EntityKind::Corpse && equipment.is_none() {
             continue;
         }
-        // The entity's built display model (if it has one): None ⇒ no display / not a modeled kind.
-        //
-        // A **corpse** is the one kind whose model cache is not chosen by its display id (decision
-        // 1706): `CORPSE_FLAG_BONES` picks between the ordinary creature chain and the
-        // `<Race><Sex>DeathSkeleton` props, exactly as the reference's `0x5d6700` does. The fork
-        // lives in one function that both this pass and the display build read, so the two can
-        // never look in different caches for the same body.
+        // A corpse's model follows `CORPSE_FLAG_BONES`, the creature chain or the
+        // `<Race><Sex>DeathSkeleton` props (`0x5d6700`), through `corpse_model`, which the display
+        // build reads too.
         let dm = match net.kind {
             EntityKind::Corpse => match super::corpse::corpse_model(net, stores.get(entity).ok()) {
                 Some(super::corpse::CorpseModel::Bones(race, sex)) => bones.0.get(&(race, sex)),
@@ -417,27 +308,14 @@ pub(super) fn attach_entity_visuals(
                 _ => None,
             }),
         };
-        // Worn equipment driving the geoset selection (and, for a player, the region composite): a
-        // player from its resolved `Equipment`, a character-model NPC from its display's
-        // CreatureDisplayInfoExtra columns. Zeroed (a beast / GameObject / no data) = the naked body.
         let worn = resolve_worn_equip(net, equipment, dm);
         let equip = worn.bodyslots;
-        // **Did the display name a model file at all?** An empty `parts` list means two opposite
-        // things, and the cube below may only answer one of them (decision 1403): a display that
-        // resolved to a model which built zero batches has been *answered* — the model draws
-        // nothing — while a display that resolved to no model at all is a gap of ours.
+        // An empty `parts` list is either a model that draws nothing (an answer) or no model at
+        // all (a gap of ours, which the cube shows).
         let named_a_model = dm.is_some_and(DisplayModel::names_a_model);
-        // A model still loading (`parts == None`) waits — leave it un-attached and retry next frame
-        // rather than flash a cube we'd swap out.
-        //
-        // **The gate is "did the display name a model", not "did it build a batch"** (decision
-        // 1656). A model that named a file and built ZERO batches is a *loaded model instance that
-        // draws nothing* — the reference builds its `CM2Model` like any other and the per-batch
-        // loop simply has no trip to make — and everything an entity takes from its model but its
-        // pixels comes from that instance: the skeleton, the attachment points a held weapon rides,
-        // the sequence clock, the PlayerName anchor, the emitters. Keying the whole build on a
-        // drawn batch is what left the Naxxramas weapon mobs — an `InvisibleStalker` body holding
-        // a visible axe — with no axe and their name plate flat on the floor.
+        // A loading model (`parts == None`) retries next frame. A model that built no batch is
+        // still a loaded instance, as in the reference: its skeleton, attachment points, clock,
+        // name anchor and emitters all come from it.
         let model = match dm {
             Some(d) => match &d.parts {
                 None => continue,
@@ -446,33 +324,20 @@ pub(super) fn attach_entity_visuals(
             None => None,
         };
 
-        // Invisible interaction-zone GameObjects (the forge, fishing-bobber zone, aura generators, …)
-        // 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; 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).
+        // Invisible GameObjects and trigger creatures hide by transparent or empty M2s, never by a
+        // flag: the reference draws any loaded model and culls zero-alpha batches (`0x707b3a`),
+        // so their `parts` are empty and `named_a_model` keeps the cube off them.
         if let Some(parts) = model {
-            // ── Mounts (decision 0441): a mounted unit is TWO skeletons. The mount is a child
-            // entity carrying a plain creature `NetEntity` — this very system builds it like any
-            // beast next frame(s) — and the rider's rig then roots under the mount's attachment-0
-            // seat joint. Until the mount child has attached, the unit builds nothing (no
-            // naked-at-the-ground flash; the model loads dominate the wait anyway). A mount child
-            // itself has no `ObjectStore`, so it can never take this branch.
-            //
-            // This is the **first build** of a unit the field already says is mounted (a
-            // born-mounted NPC, a mounted player streaming in). A field change on a unit that is
-            // already standing is `mount::reseat_mounts`' job, and it re-seats the standing rig
-            // rather than coming back through here — the two share the seat leg below.
+            // A mounted unit is two skeletons: the mount is a child entity this system builds like
+            // any beast, and the rider's rig roots at its attachment-0 seat. The unit waits for
+            // the mount; a mount change on a standing unit is `mount::reseat_mounts`' job.
             let mount_display = match net.kind {
                 EntityKind::Unit | EntityKind::Player => stores
                     .get(entity)
                     .map_or(0, |s| s.0.unit_mount_display_id()),
                 _ => 0,
             };
-            // Where the rider's root bones parent: the unit entity, or the mounted seat anchor.
+            // The rider's rig root: the unit, or the seat anchor.
             let mut rider_root = entity;
             if mount_display != 0 {
                 match super::mount::seat_or_spawn_mount(
@@ -485,55 +350,40 @@ pub(super) fn attach_entity_visuals(
                     mount_display,
                     reattached,
                 ) {
-                    // The mount model is still building (or was just ordered) — wait.
                     super::mount::Seat::Wait => continue,
                     super::mount::Seat::Frame(anchor) => rider_root = anchor,
-                    // The reference logs and leaves the body at the unit matrix
-                    // (`0x60ce70`'s present-test miss) — `seat_or_spawn_mount` wrote the warning.
+                    // The reference leaves the body at the unit matrix (`0x60ce70`'s present-test
+                    // miss).
                     super::mount::Seat::UnitMatrix => {}
                 }
             } else if let Some(&super::mount::MountChild(child)) = mount_child {
-                // The field zeroed while this unit was still pending — drop the mount it ordered,
-                // or the build below would stand a riderless horse under a dismounted body.
+                // Dismounted while pending: drop the mount it ordered.
                 if let Ok(mut ec) = commands.get_entity(child) {
                     ec.despawn();
                 }
                 commands.entity(entity).remove::<super::mount::MountChild>();
             }
-            // Real model: submesh children inherit the entity's (pose-driven) transform; bake scale onto it.
             let kind = match net.kind {
                 EntityKind::GameObject => ModelKind::GameObject,
                 _ => ModelKind::Creature,
             };
             let emitters = dm.map(|d| d.emitters.as_slice()).unwrap_or_default();
             let model_lights = dm.map(|d| d.lights.as_slice()).unwrap_or_default();
-            // A GameObject's interior-fold reference point (model-local; the anchor transform
-            // applies the entity scale when the classifier folds).
+            // The model-local interior fold point; the classifier applies the entity scale.
             let bake_center = dm.map(|d| d.bake_center_local).unwrap_or(Vec3::ZERO);
-            // The dynamic ground-shade root (decision 0173): one light-node state per object, like
-            // the reference's `[obj+0xe0]`; every M2 part below (body, held items) reads it from the
-            // tree walk. Kind-independent — a unit and a GameObject run the same 2.5/0.5 MCSH chase,
-            // which is the byte-shared target law (0814 restored this; 0809 had split it by kind on
-            // the strength of a delivery state we do not model). `insert_if_new` so a gear-change
-            // re-attach keeps the already-ramped state instead of resetting it (no one-frame
-            // lighting pop).
+            // One ground-shade state per object (the reference's `[obj+0xe0]`), the same 2.5/0.5
+            // MCSH chase for every kind; `insert_if_new` so a rebuild keeps the ramped state.
             commands
                 .entity(entity)
                 .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, `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.
+            // Held items share the body's interior verdict (the reference aliases the wearer's
+            // collector into each item, `0x718960`), so they fold at the body's centre.
             commands
                 .entity(entity)
                 .insert(benilla_world::interior::BodyBakeCenter(bake_center));
-            // The light node's ATTACH MODE — the reference's `[node+0x90]` bit 13, written once at
-            // node creation from the descriptor TYPEMASK (`0x613e10`/`0x670db0`) and dispatched at
-            // `0x6a86d0`: a GameObject attaches by CONTAINMENT (`0x6a8c10`), anchored at the world
-            // bounding-box centre; a unit/player by DOWN-RAY (`0x6a8a20`), anchored at the position.
-            // The kind can't change under a live display-id swap, but the remove arm keeps the two
-            // mutually exclusive by construction rather than by that argument (decision 0776).
+            // The light node's attach mode (`[node+0x90]` bit 13, set from the TYPEMASK at
+            // `0x613e10`/`0x670db0`, dispatched at `0x6a86d0`): a GameObject by containment at its
+            // bounds centre (`0x6a8c10`), a unit by down-ray at its position (`0x6a8a20`).
             match net.kind {
                 EntityKind::GameObject => {
                     commands
@@ -546,57 +396,36 @@ pub(super) fn attach_entity_visuals(
                         .remove::<benilla_world::interior::ContainmentAttach>();
                 }
             }
-            // Identity for the mouseover inspector (and, later, hover tooltips / targeting).
             let object = WorldObject {
                 kind,
                 label: dm.map(|d| display_label(&d.handle)).unwrap_or_default(),
                 id: net.display_id.unwrap_or(0),
                 detail: format!("emitters: {}", emitters.len()),
             };
-            // Skeletal skin (decision 0019): a creature (Unit/Player) — and now any animated
-            // GameObject — draws through the skinned-mesh twin and a **per-instance** joint hierarchy
-            // whose entities are children of this entity (so they inherit its world pose; at bind pose
-            // every joint matrix collapses to that pose, so the model renders exactly where the static
-            // 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 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.
+            // Whether a GameObject runs the open/close state machine (the type dispatch at
+            // `0x5f76cc`); read once, so the rig and the clock's driver agree.
             let go_state_machine = net.kind == EntityKind::GameObject
                 && stores
                     .get(entity)
                     .is_ok_and(|s| crate::go_anim::go_animates(s.0.gameobject_type_id()));
-            // Will anything actually SKIN through this instance's palette slot? Every M2 part
-            // carries a skinned twin, so for an ordinary body this is simply "it drew something";
-            // a body that drew NOTHING (decision 1656's invisible weapon-holder) gets the rig
-            // without the slot — see [`setup_skinned_instance`].
+            // Whether anything skins through the palette slot: not for a body that draws nothing.
             let skins = parts.iter().any(|p| p.skinned_mesh.is_some());
             let mut skin: Option<RigBuild> = match (net.kind, dm) {
-                // A creature (or player body — decision 0041) with a real skeleton. The `!is_empty`
-                // guard keeps a degenerate boneless model on the static mesh (its skinned twin would
-                // carry joint attributes but have no joints to index — out of bounds).
+                // A boneless model stays static: its skinned twin would index joints that do not
+                // exist.
                 (EntityKind::Unit | EntityKind::Player, Some(d))
                     if !d.skeleton.joints.is_empty() =>
                 {
-                    // `rider_root`: the unit itself, or — mounted — the seat anchor under the
-                    // mount's attachment-0 joint (decision 0441). The `AnimationPlayer` stays
-                    // on the unit entity either way (targets bind by entity, not by path).
-                    //
-                    // Terrain conform (decisions 0482/0486): a flagged model's root bones
-                    // parent one level deeper, under a conform node `conform_units` rotates —
-                    // wild quadruped and mount child alike. A mounted RIDER never gets one
-                    // (`rider_root != entity`): the ref's `0x7106c0` dispatch is on the
-                    // mount-PREFERRED model, and the composite tilts through the mount's
-                    // node, seat joint included.
+                    // Terrain conform: a flagged model's root bones sit under a node
+                    // `conform_units` rotates. A mounted rider never gets one: the reference
+                    // dispatches on the mount's model (`0x7106c0`) and tilts through its node.
                     let mut joints_root = rider_root;
                     if d.terrain_tilt != 0 && rider_root == entity {
                         let node = commands
                             .spawn((
                                 super::conform::ConformNode {
-                                    // The ground/yaw source: the streamed unit — for a
-                                    // mount child, its HOST (the child sits at the unit
-                                    // matrix; its own `Transform` is local).
+                                    // The ground and yaw source: the unit, or a mount child's
+                                    // host.
                                     unit: mount_body.map_or(entity, |mb| mb.host),
                                     mode: d.terrain_tilt,
                                 },
@@ -616,26 +445,19 @@ pub(super) fn attach_entity_visuals(
                         skins,
                     )
                 }
-                // A **corpse** (decision 1706). A fresh body is a character model and its held
-                // Death pose is a bone pose, so it has to skin or it lies in bind pose — standing
-                // up. The `animations` guard is what keeps a **bone pile** off this path: the 16
-                // shipped skeletons are fully static two-bone props with no sequence at all, so
-                // skinning one could only reproduce the mesh it already renders, at the cost of a
-                // scarce palette slot (the same trade decision 0941 made for the poseless GOs).
+                // A fresh corpse skins, or its Death pose would stand in bind pose; a bone pile, a
+                // static prop with no sequence, takes no palette slot.
                 (EntityKind::Corpse, Some(d))
                     if !d.skeleton.joints.is_empty() && d.animations.is_some() =>
                 {
                     setup_skinned_instance(&mut commands, &mut palettes, entity, entity, d, skins)
                 }
-                // A GameObject whose model authors a real skeleton + animation draws through the
-                // 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
-                // (`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.
+                // An animated GameObject skins like a creature. A door, button or chest
+                // (`go_animates`) runs the `GAMEOBJECT_STATE` machine; any other (a mailbox's
+                // flags, a windmill) plays the loader idle the reference arms on every M2 instance
+                // (`0x70ebd0`), which `ModelAnimations::idle_clip` picks: id 0 through the playable
+                // lookup, else the first clip. One whose idle holds its rest pose with no global
+                // sequence (`DoodadAnimTier::Static`) keeps the static mesh.
                 (EntityKind::GameObject, Some(d))
                     if !d.skeleton.joints.is_empty() && d.animations.is_some() =>
                 {
@@ -644,10 +466,7 @@ pub(super) fn attach_entity_visuals(
                         benilla_world::doodad_anim::classify(&d.skeleton, d.animations.as_ref()),
                         benilla_world::doodad_anim::DoodadAnimTier::Static
                     );
-                    // A state GO whose model poses NO bone in any sequence gets no rig: skinning
-                    // it could only reproduce the bind-pose mesh it already renders, at the cost
-                    // of a scarce palette slot (decision 0941 — 147 display models are this
-                    // shape). It still gets the clock below, which is the half it was missing.
+                    // A state GO whose sequences pose no bone gets no rig, only the clock below.
                     let poses = d
                         .animations
                         .as_ref()
@@ -667,13 +486,7 @@ pub(super) fn attach_entity_visuals(
                 }
                 _ => None,
             };
-            // The instance's SEQUENCE CLOCK — armed for every M2 instance whose model has one,
-            // rigged or not (decision 0941). The rig above is a palette slot and a skinned twin,
-            // and is worth spending only when bones actually move; the clock is a player and a
-            // handle, and everything per-sequence reads it — the emitters' rate/enable/params
-            // tracks, the material alpha/colour/UV loops, the GameObject state arm. Bundling the
-            // two is what left the boneless-but-animated content (the Molten Core rune's flames,
-            // the flame ring's spreading spawn window) reading file slot 0 at t = 0 for ever.
+            // The sequence clock, rigged or not.
             if matches!(
                 net.kind,
                 EntityKind::Unit | EntityKind::Player | EntityKind::GameObject | EntityKind::Corpse
@@ -682,14 +495,10 @@ pub(super) fn attach_entity_visuals(
                     arm_sequence_clock(&mut commands, entity, anims, net.kind, go_state_machine);
                 }
             }
-            // The bone-riding surface (decision 0072): the model's attachment points + event
-            // markers, so held items (and future bone riders) can hang from the hand/hip/back
-            // joints. Pure model data — the anchor *entities* live in `RigPose.anchors` and
-            // spawn on first consumer (decision 1355).
+            // The attachment points and event markers that held items and other riders hang from.
             if let (Some(_), Some(d)) = (&skin, dm) {
-                // The event markers keep the client's first-match scan order: an ident already
-                // present wins (character models carry six `$CSD` records — the first is the one
-                // `0x7130e0` would return).
+                // The first marker of an ident wins, as the reference's scan (`0x7130e0`) returns
+                // it: character models carry six `$CSD` records.
                 let mut markers = std::collections::HashMap::new();
                 for m in &d.markers {
                     markers.entry(m.ident).or_insert((m.bone, m.offset));
@@ -702,9 +511,8 @@ pub(super) fn attach_entity_visuals(
                         .collect(),
                     markers,
                 });
-                // The display-facing counter-twist channels (the strafe body pose): the model's
-                // SpineLow/Head key-bones, straight into the pose buffer. Models without either
-                // key-bone (beasts, props) get no component — the client's capability gates.
+                // The strafe counter-twist on the SpineLow and Head key-bones; a model with neither
+                // gets none.
                 let nb = d.skeleton.joints.len();
                 let in_range = |b: Option<u16>| b.filter(|&i| (i as usize) < nb);
                 let (spine, head) = (
@@ -717,20 +525,10 @@ pub(super) fn attach_entity_visuals(
                         .insert(crate::creature_anim::BodyTwist::new(spine, head));
                 }
             }
-            // Character geoset selection (decision 0041, Milestone B): a player body model carries
-            // *every* hairstyle / facial-hair / body-option geoset; show only the selected ones. The
-            // model (and its `parts`) is shared across all players of this displayId, so the filter is
-            // **per-entity** here — from this player's decoded appearance — not baked into the cache.
-            // `None` (no look, or the tables unavailable) ⇒ render every part, as before.
-            //
-            // The character look: a player takes it from the wire, a character-model NPC from its
-            // display's CreatureDisplayInfoExtra (decision 0041). Both then drive the same geoset filter
-            // + skin/hair materials below; a beast NPC / GameObject has no look and is unaffected.
+            // A character model carries every hair, facial and body geoset, and is shared by its
+            // display, so the entity's own look picks which show.
             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, `0x4799a0`: hair/facial/ears tuck under it. For a
-            // character-model NPC the helm id is its CreatureDisplayInfoExtra head column.)
+            // The worn geoset selectors, the helm's hide-mask rows included (`0x4799a0`).
             let equip_geosets = equip_geosets(
                 displays.as_deref(),
                 &equip,
@@ -748,11 +546,6 @@ pub(super) fn attach_entity_visuals(
                     &equip_geosets,
                 ))
             });
-            // Character skin (decisions 0041 / 0044 / 0045): a character body's body-skin batches (M2
-            // type 1) get the body atlas, and its hair batches (type 6) get the hair-mesh texture — both
-            // per-appearance over the shared model, so built here (not in the shared model cache);
-            // `model_material` then dedups by texture so bodies of one look share them. `(None, None)` ⇒
-            // those parts keep their built (untextured) material (no look, or tables/chain absent).
             let char_mats = match look.as_ref() {
                 Some(l) => build_char_skin_materials(
                     l,
@@ -771,47 +564,23 @@ pub(super) fn attach_entity_visuals(
                 ),
                 None => (None, None, None, (None, None)),
             };
-            // Whether any spawned child armed a `PendingAppearFade` this pass — mirrored onto the unit
-            // root below as `UnitAppearFade` so a held item / helm / shoulder that resolves and spawns
-            // *later* (`entities::equipment::attach_held_items`, async — a template round trip, a model
-            // load) can join the same ramp instead of popping in opaque or racing its own fade from
-            // zero. Decision 0032 read as a per-unit property, not a per-mesh-at-attach-time stamp.
+            // Whether a part armed an appear-fade, mirrored onto the root so a held item that
+            // spawns later joins the ramp.
             let mut unit_will_fade = false;
-            // This unit's **instance slot**, in tag-field form — one value for the whole unit, worn by
-            // every part and card below. See the per-part note at the spawn for why it is the
-            // instance's identity rather than a skinning detail (decision 0812).
             let inst_slot = skin.as_ref().map_or(0, |rb| rb.slot);
-            // The armed idle's **authored** CAaBox (decision 0637) — the mouseover picker's
-            // volume for a skinned part, NOT a culling volume (skinned entity parts are never
-            // frustum-culled; see the `NoFrustumCulling` note at the insert below). The bind-pose
-            // box the mesh would otherwise get is only a fair stand-in while the animation keeps
-            // the model near rest — the duel flag breaks it: `DuelingFlag.m2` is modelled 9 yards
-            // in the air and its Stand translates the root `−9.124` to plant it, so the bind box
-            // sits a whole model-height above the drawn geometry. The M2 authors a per-sequence
-            // CAaBox for exactly this; for the flag's Stand it is ground-to-tip, which is also
-            // what makes the planted flag hoverable where it is actually seen.
+            // The armed idle's authored CAaBox, the picker's volume for a skinned part: the bind
+            // box can miss the drawn model (`DuelingFlag.m2` is modelled 9 yd up and its Stand
+            // translates the root −9.124 to plant it).
             let idle_aabb = dm.and_then(|m| m.animations.as_ref()).and_then(|a| {
                 let clip = a.first_seq.and_then(|i| a.clips.get(i))?;
                 (clip.bounds_max.cmpgt(clip.bounds_min).all()).then(|| {
                     bevy::camera::primitives::Aabb::from_min_max(clip.bounds_min, clip.bounds_max)
                 })
             });
-            // This body's **election bound** (decision 1270): standing in a sealed WMO room the
-            // reference never submits an outdoor object at all, so the cull needs one whole-object
-            // AABB per body, on its root. Recorded here and restated onto `WorldUnit::bound` by
-            // `publish_world_units` — the one reconciler that answers every "what is this body to
-            // the world" question, exactly as it already does for the collision height.
-            //
-            // **Not `idle_aabb` above, and that distinction is the whole of it.** `first_seq` is
-            // the *rendering* gate — "is this seed worth a skin + player" (0130's content gate) —
-            // and it is `None` for every model whose idle does not move its bones off the rest
-            // pose. The picker can take that: it falls back per part (`idle_aabb.or(part.aabb)`).
-            // The election cannot, because a body with no bound is a body it never decides — so
-            // reading the render gate here silently exempted a whole class of creature from the
-            // cull, and they kept drawing through the ceiling. `idle_clip` is the same selection
-            // asked as an *identity* (`ModelAnimations`' own doc: "conflating the two is the whole
-            // defect"), and where even that box is unauthored — a degenerate CAaBox is common in
-            // 1.12 art — the model's bind-pose extent is what an unarmed body actually draws.
+            // The body's election bound: in a sealed WMO room the reference submits no outdoor
+            // object, so the cull needs one box per body (restated onto `WorldUnit::bound`). It
+            // reads `idle_clip`, not `first_seq`, which is `None` for an idle at its rest pose and
+            // would exempt the body; a degenerate authored box falls back to the bind extent.
             let election_bound = dm
                 .and_then(|m| m.animations.as_ref())
                 .and_then(|a| a.idle_clip())
@@ -821,14 +590,8 @@ pub(super) fn attach_entity_visuals(
             if let Some(aabb) = election_bound {
                 commands.entity(entity).insert(super::ModelBound(aabb));
             }
-            // Everything one part's spawn reads from this unit, gathered once (`attach::dress`) —
-            // the same context the gear-change **re-dress** feeds `spawn_part`, so a body built at
-            // stream-in and a geoset that appears when a belt is swapped are dressed by one law.
-            //
-            // Billboard-card bones are the one dress input that needs an anchor ENTITY (the card
-            // rides its live joint), so they resolve here — through the same first-consumer
-            // resolver as everything else (decision 1355), over the same geoset predicate as the
-            // spawn loop below, so a hidden variant's card bone spawns nothing.
+            // A billboard card rides its live joint, so card anchors resolve here, over the spawn
+            // loop's geoset predicate: a hidden variant's card bone spawns no anchor.
             let card_anchors: std::collections::HashMap<u16, Entity> = match skin.as_mut() {
                 Some(rb) => parts
                     .iter()
@@ -857,20 +620,15 @@ pub(super) fn attach_entity_visuals(
                 bake_center,
                 idle_aabb,
                 now,
-                // A fresh visual arms the appear-fade on every fade-capable part (decision 0032).
-                // A rebuild that is NOT a spawn — a mount transition, a display swap — spawns
-                // steady: `Reattached` says the unit was already standing there.
+                // A fresh visual fades in; a rebuild (`Reattached`: a mount transition, a display
+                // swap) spawns steady.
                 fade: if reattached {
                     JoinedFade::Steady
                 } else {
                     JoinedFade::Pending { since: now }
                 },
             };
-            // A geoset this character doesn't show (an unselected hair/facial/body variant, or a
-            // body region its worn gear replaces) is skipped. The equipment half of that
-            // selection is re-run in place on a gear change (`attach::redress`); this is the
-            // same predicate, evaluated once at build. The shown batches spawn as material
-            // GROUPS (`merge`): one entity per set of batches nothing downstream can tell apart.
+            // The shown batches spawn as material groups (`merge`).
             let shows = |part: &super::EntityPart| {
                 visible_geosets
                     .as_ref()
@@ -893,13 +651,7 @@ pub(super) fn attach_entity_visuals(
                     },
                 );
             }
-            // Mirror the appear-fade clock onto the unit root (see `unit_will_fade` above): a held item
-            // / helm / shoulder attaching later reads this to join the same ramp
-            // (`entities::equipment::attach_held_items`). A `Reattached` rebuild — a mount
-            // transition, a display swap — abandons any in-flight fade outright, matching the body
-            // parts it just rebuilt steady, so anything spawned for that same rebuild is steady too.
-            // (A GEAR change no longer reaches here at all: it re-dresses in place, and the parts it
-            // spawns join this clock instead of clearing it — `attach::redress`.)
+            // A `Reattached` rebuild drops any in-flight fade, as its parts spawned steady.
             if unit_will_fade {
                 commands
                     .entity(entity)
@@ -909,56 +661,42 @@ pub(super) fn attach_entity_visuals(
                     .entity(entity)
                     .remove::<benilla_world::model_fade::UnitAppearFade>();
             }
-            // 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 (`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.
+            // Size is `OBJECT_FIELD_SCALE_X` alone: the server already folds the DBC scale into
+            // it (vmangos `Unit::GetScaleForDisplayId`, `Unit.cpp:9579`), and the reference
+            // renders at the field (`0x613ef0`).
             let placement = if let Ok(mut t) = transforms.get_mut(entity) {
                 t.scale = Vec3::splat(net.scale);
                 *t
             } else {
                 Transform::default()
             };
-            // The equipment this visual was dressed with (decision 0074): `redress_player_looks`
-            // diffs it against the live resolution and re-dresses the standing visual on a change.
+            // What the visual was dressed with, for `redress_player_looks` to diff.
             if let (EntityKind::Player, Some(e)) = (net.kind, equipment) {
                 commands
                     .entity(entity)
                     .insert(super::equipment::AppliedEquipment(*e));
             }
-            // Camera framing-pivot height (model-derived, pre-scale): the self-avatar reads it in the
-            // camera controller to target ~neck height instead of a fixed offset (harmless on NPCs).
+            // The camera's framing pivot, model-local, before scale.
             commands.entity(entity).insert(CameraPivot {
                 height_local: dm.map(|d| d.pivot_height_local).unwrap_or(0.0),
-                // …and how far that pivot drops while this body swims — the reference's third
-                // preset `cam+0x124`, stored as the delta it is built from (`0x50ccf6`). `0.0` for
-                // anything with no Swim sequence, so the two presets coincide.
+                // The pivot's drop while swimming, the reference's third preset `cam+0x124`
+                // (`0x50ccf6`); 0 without a Swim sequence.
                 swim_drop_local: dm.map(|d| d.swim_pivot_drop_local).unwrap_or(0.0),
             });
-            // The overhead-anchor fallback input (combat text over a model with no PlayerName
-            // attachment — `0x608640`'s defensive branch).
+            // The overhead fallback for a model with no PlayerName attachment (`0x608640`).
             commands.entity(entity).insert(super::OverheadFallback(
                 dm.map(|d| d.bbox_z_local).unwrap_or(0.0),
             ));
-            // The chat bubble's own anchor height — the Stand box's Z, a file constant, NOT the
-            // posed attachment the overhead name above rides (1406).
+            // The chat bubble's height: the Stand box's Z, not the posed PlayerName attachment.
             commands.entity(entity).insert(super::StandBoxHeight(
                 dm.map(|d| d.stand_box_z_local).unwrap_or(0.0),
             ));
-            // Selection-ring radius (model-local sphere radius, pre-scale) — the targeting ring reads it
-            // × the unit's scale (harmless on non-unit models, which are never ringed).
+            // The selection ring's model-local radius, scaled by the unit's scale.
             commands.entity(entity).insert(SelectionRadius(
                 dm.map(|d| d.ground_radius_local).unwrap_or(0.0),
             ));
-            // Particle emitters (flames/glows) — spawned per entity, despawning with it. A skinned
-            // creature's emitter rides its host bone's joint with the model-space origin rebased
-            // into the bone frame (`position − pivot`), exactly like a doodad emitter (0130 phase 4,
-            // same rig identity) — the kobold's candle flame follows the head through the crouch
-            // instead of floating at the rest-pose height. GameObjects/boneless models keep
-            // whole-entity follow (no joints; their bones hold rest pose anyway).
+            // Emitters ride their host bone's anchor, origin rebased into the bone frame
+            // (`position − pivot`), as a doodad's do; an unrigged model's follow the entity.
             {
                 for em in emitters {
                     let owner = skin
@@ -971,40 +709,24 @@ pub(super) fn attach_entity_visuals(
                         placement,
                         particles::EmitterFrames {
                             owner: Some(owner),
-                            // The cloud SORTS at the unit; bones compose births only. Since 1585
-                            // a world-mode store is frozen at birth, so neither can move a live
-                            // particle. (`[model+0x17c]` is the TRANSPORT matrix — 1591 — so it is
-                            // 0 for a unit on foot and this is not the attached/unattached split
-                            // it used to claim to be.)
+                            // The cloud sorts at the unit; bones compose births only, and a
+                            // world-mode particle is frozen at birth.
                             anchor: Some(entity),
-                            // The unit's model going away IS this emitter's model going away
-                            // (stream-out, a visual rebuild) — free the pool with it (0826).
+                            // The unit's model is the emitter's model: free the pool with it.
                             on_owner_loss: particles::OwnerLoss::Free,
-                            // The unit IS the model instance here, so its own render alpha
-                            // (appear ramp, stream-out ramp, the self-avatar feather) multiplies
-                            // its clouds — decision 0827.
+                            // The unit's render alpha multiplies its clouds.
                             alpha: Some(entity),
-                            // …and the entity IS the light node: one node per object, created
-                            // from its TYPEID and filled every frame whether or not a mesh batch
-                            // consumes it. A LIT emitter is a consumer of that node exactly as a
-                            // lit batch is, and on the Onyxia lava traps it is the ONLY one
-                            // (`crate::entities` → `benilla_world::interior::EmitterLitBy`).
+                            // The entity is the light node, filled whether or not a batch reads
+                            // it; a lit emitter consumes it as a lit batch does.
                             light_node: Some(entity),
                         },
-                        // The emitters' rate/enabled read this instance's PLAYING sequence — a
-                        // unit's or GameObject's `AnimationPlayer` on the root. A quest object's
-                        // explosion is authored inside its one-shot clips with an OFF window at
-                        // idle (B27); a creature's death-only smoke is the same shape.
+                        // Rate and enable read the instance's playing sequence.
                         particles::EmitClock::Host(entity),
                     );
                 }
             }
-            // The model's own M2 point lights (decision 0016) — a fire elemental's glow, a lit
-            // GameObject brazier. Same host-bone ride as the emitters, for the same reason: the
-            // reference re-registers each light at its LIVE bone position every frame. (The far more
-            // common carried light is the held torch — that one spawns on the item model, in
-            // `equipment`.) The light bones resolve BEFORE the call: the closure can't borrow
-            // `commands` while `spawn_carried_lights` holds it.
+            // The model's point lights ride their bones, as the reference re-registers each at its
+            // live bone every frame. Their anchors resolve first: the call holds `commands`.
             let light_anchors: std::collections::HashMap<i16, Entity> = model_lights
                 .iter()
                 .filter(|l| l.def.casts())
@@ -1019,21 +741,15 @@ pub(super) fn attach_entity_visuals(
             super::spawn_carried_lights(&mut commands, model_lights, entity, |bone| {
                 light_anchors.get(&bone).copied()
             });
-            // Ribbon trails (wisp streamers, trailing quest-object crystals) — the same host-bone
-            // ride as the emitters; the trail self-despawns when its owner joint/entity goes.
+            // Ribbon trails, on the same host-bone ride; each despawns with its owner.
             {
                 for rb in dm.map(|d| d.ribbons.as_slice()).unwrap_or_default() {
                     let (owner, use_pivot) = skin
                         .as_mut()
                         .and_then(|build| build.pose.anchor_for(&mut commands, entity, rb.def.bone))
                         .map_or((entity, false), |j| (j, true));
-                    // The `+0xc0` enable gate reads THIS instance's playing sequence, live —
-                    // a GameObject flips state under its own trails (a trap springs, a door
-                    // opens), so there is no spawn-time answer. Passing `None` here (the old
-                    // "body models don't author a gate" shortcut, true of creatures and false of
-                    // GameObjects) drew every trail a model authored in every state: the Frost
-                    // Trap's twelve trigger-only streamers became a permanent spinning column
-                    // over the placed trap (decision 1011).
+                    // The `+0xc0` enable gate reads the instance's live sequence: a GameObject
+                    // changes state under its own trails.
                     benilla_world::ribbons::spawn_ribbon(
                         &mut commands,
                         rb,
@@ -1041,28 +757,19 @@ pub(super) fn attach_entity_visuals(
                         use_pivot,
                         placement.scale.max_element(),
                         benilla_world::ribbons::RibbonSeq::Host(entity),
-                        // The unit's own render alpha gates its trail (0827).
+                        // The unit's own render alpha gates its trail.
                         Some(entity),
-                        // No fade sphere: a streamed unit is not a placed model — its
-                        // population is bounded by server visibility, and its trail by the
-                        // unit's own render alpha one line up.
+                        // No fade sphere: server visibility bounds a unit's population.
                         None,
                     );
                 }
             }
-            // The pose buffer lands last (decision 1355): every build arm above has resolved its
-            // anchors into it, so it arrives on the entity in one piece — the evaluator, the
-            // compose pass and every later `anchor_for` (a weapon equipped in combat, a spell
-            // kit) find the same buffer the build populated.
+            // The pose lands last, with every anchor the build resolved into it.
             if let Some(rb) = skin {
                 commands.entity(entity).insert(rb.pose);
             }
-            // Static collision for solid GameObjects (chests, mining veins, doors…): the model-local
-            // collider baked at build time rides the entity's pose, so player + camera collide with it.
-            // Hull-less GameObjects (herbs, small props) carry none — collide-iff-hull. GameObjects only;
-            // creatures use unit-collision, not modeled here. An anchored transport (boat/lift) is
-            // Kinematic — its body moves every frame, and a Static insert here would silently
-            // overwrite the arm's label when the asset finished loading after the arm ran.
+            // A GameObject with a hull collides; an anchored transport stays Kinematic, as its arm
+            // labelled it, since its body moves every frame.
             if matches!(net.kind, EntityKind::GameObject) {
                 if let Some(col) = dm.and_then(|d| d.collider.clone()) {
                     let body = if anchored {
@@ -1071,33 +778,16 @@ pub(super) fn attach_entity_visuals(
                         RigidBody::Static
                     };
                     commands.entity(entity).insert((body, col));
-                    // This lane bypasses the streamer's attach queue entirely (0761), so it stamps
-                    // the collider set itself — otherwise a creature standing where a GameObject
-                    // hull lands frames later keeps the answer it took before there was one
-                    // (decision 1384).
+                    // This lane bypasses the streamer's attach queue, so it stamps the collider
+                    // set itself.
                     collider_epoch.bump();
                 }
             }
         } else {
-            // Cube fallback: other players (cyan, slim block) and NPCs (red, person-box) whose display
-            // named **no model to load** — the debug signal for a gap of ours. The cube origin is
-            // centered, so a child offset lifts it onto the ground.
-            //
-            // 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, 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
-            // the same singleton `CM2Scene`, through the same `0x613e10` as every other typeId.
-            // That is the whole of how a **trigger creature** hides —
-            // `Creature\InvisibleStalker\InvisibleStalker.m2` ships with
-            // `nVertices == 0`, and its `NoName` sibling's one batch carries a constant-zero
-            // transparency track — no unit flag is consumed anywhere. Cubing them put a black slab
-            // over 154 vmangos templates on 8 displays (the Scarab Wall's Anachronos trigger,
-            // Yojamba's Zandalarian Event Generator). It was only ever the *unit* arm that got this
-            // wrong; the GameObject arm below has drawn nothing since 0024.
+            // A debug cube (a player cyan, an NPC red, lifted onto the ground) for a display that
+            // named no model, a gap of ours. One that named a model draws what it built, maybe
+            // nothing: every type reaches the same batch loop through `0x613e10`, and its trip
+            // count is the view's texUnit count (`0x707a72`).
             let fallback = match net.kind {
                 _ if named_a_model => None,
                 EntityKind::Player => {
@@ -1111,15 +801,8 @@ pub(super) fn attach_entity_visuals(
                     );
                     None
                 }
-                // A DynamicObject is deliberately invisible as an *object* — its look is the
-                // spell's area effect (the dest-anchored visual lane), never a fallback cube.
-                //
-                // A **corpse** takes no cube either (decision 1706), and for the GameObject arm's
-                // reason rather than the DynamicObject's: it reached here only because its display
-                // named no model — a `CORPSE_FIELD_DISPLAY_ID` absent from `CreatureDisplayInfo`,
-                // or a bone pile whose race has no shipped skeleton. Both are the reference's own
-                // null-row legs, which draw nothing (`0x5d6700` returns 0 and the model never
-                // loads); a body-sized red box on the ground would read as a bug in itself.
+                // A model-less corpse draws nothing, as the reference's null-row legs do
+                // (`0x5d6700` returns 0); a DynamicObject's look is its spell's area effect.
                 EntityKind::Corpse => {
                     debug!(
                         "corpse (display {:?}) has no usable model — not rendering",
@@ -1130,8 +813,7 @@ pub(super) fn attach_entity_visuals(
                 EntityKind::DynamicObject | EntityKind::Other => None,
             };
             if let Some((material, mesh, lift)) = fallback {
-                // Tag the cube as a pickable unit too (kind `Creature` covers units + player bodies), so
-                // a model-less NPC / other player can still be inspected and, crucially, targeted.
+                // Pickable, so a model-less unit can still be targeted.
                 let object = WorldObject {
                     kind: ModelKind::Creature,
                     label: format!("{:?} (no model)", net.kind),
@@ -1144,23 +826,17 @@ pub(super) fn attach_entity_visuals(
                         MeshMaterial3d(material),
                         Transform::from_translation(Vec3::Y * lift),
                         object,
-                        // …and into the unit pick's marker-filtered fallback population like any
-                        // dressed creature part.
                         benilla_world::interact::CreaturePickPart,
-                        // The cube has no resident `RenderSubmesh` to cast against — its `Aabb` IS
-                        // its shape, which it must SAY (decision 0929): the picker requires pick
-                        // geometry rather than inferring a box from its absence.
+                        // No `RenderSubmesh`: the picker casts against the cube's box.
                         benilla_world::interact::PickBox,
-                        // What makes "we are standing a cube here" a number a probe can read
-                        // (`WOW_UNIT_VISUALS`) rather than something only an eye finds — 1403.
+                        // Counted by `WOW_UNIT_VISUALS`.
                         super::FallbackCube,
                     ));
                 });
             }
         }
-        // The mount this visual was built with (decision 0441, the `AppliedEquipment` pattern):
-        // `refresh_mounts` diffs it against the live field and rebuilds on any transition. Written
-        // on the cube fallback too (same read, no seat), so a model-less unit can never churn.
+        // The mount the visual was built on, for `reseat_mounts` to diff; stamped on a cube too,
+        // so a model-less unit never churns.
         if matches!(net.kind, EntityKind::Unit | EntityKind::Player) {
             let applied = stores
                 .get(entity)
@@ -1172,32 +848,14 @@ pub(super) fn attach_entity_visuals(
         commands
             .entity(entity)
             .insert(VisualAttached)
-            // The display this visual was built with (decision 0695, the same pattern):
-            // `refresh_live_display` diffs it against the live descriptor and rebuilds on a
-            // change (druid form, GM morph). Stamped on the cube fallback too, so a model-less
-            // unit can never churn.
+            // The display the visual was built with, for `refresh_live_display` to diff.
             .insert(super::live_display::AppliedDisplay(net.display_id))
             .remove::<super::equipment::Reattached>();
     }
 }
 
-/// Spawn a rig's joint-entity hierarchy under `root` (decision 0019): one entity per bone
-/// carrying its rest-local translation, parented per the skeleton — root bones under `root` so
-/// they inherit the entity's world pose, others under their parent joint. Returns the joints in
-/// bone order, so a vertex's joint index maps straight in and every submesh's palette rig shares
-/// this one set. **The doodad/effect/booth lane only** (decision 0724): a streamed unit's rig is
-/// the joint-less [`benilla_world::rig_anim::RigPose`] buffer instead — this hierarchy remains for
-/// the Bevy-graph-driven hosts. `holder` is the rig root that carries (or will carry) the
-/// [`benilla_world::rig_palette::RigSkin`] — every joint marks it with a `RigJoint`, which is what the
-/// palette change-sweep iterates (0720).
-/// The enclosing box of a model's parts — its bind-pose extent, in model space.
-///
-/// The election bound's fallback (decision 1270) for a body whose armed idle authors no CAaBox.
-/// Every part of one model shares that space, so their union is the model, and for a body that is
-/// not armed at all it is exactly what gets drawn. A bind box can be a poor bound for a body whose
-/// idle moves it far (0637's duel flag, modelled 9 yd up and planted by its Stand) — which is why
-/// the authored box is preferred whenever there is one, and why this is a fallback rather than the
-/// rule. Over-large is the safe direction here: it can only admit, never hide.
+/// The union of a model's part boxes, its bind-pose extent: the election bound when the idle
+/// authors no CAaBox. Over-large only admits, never hides.
 fn union_aabb(
     boxes: impl Iterator<Item = bevy::camera::primitives::Aabb>,
 ) -> Option<bevy::camera::primitives::Aabb> {
@@ -1214,8 +872,7 @@ fn union_aabb(
     ))
 }
 
-/// A display model's source path as a readable inspector label (the asset path, sans `mpq://` source).
-/// Empty for the model-less variant or a path-less handle.
+/// A display model's asset path as an inspector label, empty without one.
 fn display_label(handle: &ModelHandle) -> String {
     let path = match handle {
         ModelHandle::M2(h) => h.path(),
@@ -1233,8 +890,7 @@ mod tests {
     use bevy::ecs::world::CommandQueue;
     use bevy::mesh::skinning::SkinnedMeshInverseBindposes;
 
-    /// A one-bone rest skeleton + its bindposes — the smallest rig `setup_skinned_instance` will
-    /// build, so the test is about the slot policy and nothing else.
+    /// The smallest rig `setup_skinned_instance` builds.
     fn one_bone(ibps: &mut Assets<SkinnedMeshInverseBindposes>) -> DisplayModel {
         DisplayModel {
             skeleton: ModelSkeleton {
@@ -1254,13 +910,8 @@ mod tests {
         }
     }
 
-    /// **A body with nothing to skin gets the rig without the palette slot** (decision 1656).
-    ///
-    /// The invisible trigger creature holding a visible weapon is a complete model instance — it
-    /// needs the pose, because its attachment points carry what IS drawn — and has no geometry of
-    /// its own for a palette slot to serve. It must also take **no `RigStarved`**: that marker
-    /// means "currently slot-less and wants one", and `heal_rig_starved` would rebuild this body
-    /// every time the table gained headroom, for ever, chasing a slot it never asks for.
+    /// A body with nothing to skin takes no `RigStarved` either, or `heal_rig_starved` would
+    /// rebuild it for ever.
     #[test]
     fn a_body_that_skins_nothing_takes_the_rig_without_a_slot() {
         use benilla_world::rig_palette::{RigPalettes, RigSkin, RigStarved};
diff --git a/crates/benilla-app/src/entities/attach/preview.rs b/crates/benilla-app/src/entities/attach/preview.rs
index af7415db..ca45002c 100644
--- a/crates/benilla-app/src/entities/attach/preview.rs
+++ b/crates/benilla-app/src/entities/attach/preview.rs
@@ -1,33 +1,9 @@
-//! The **tuple-driven character preview** builder (decisions 0423 + 0465, widened by 1060) — the
-//! entities-side half of every booth that shows a character nobody is standing in. It lives under
-//! `attach` so it can reuse the character body pipeline directly
-//! (`char_skin::build_char_skin_materials`, the geoset filter, the [`super::super::EntityPart`]
-//! source, the item-display models) without widening any of it.
-//!
-//! Two callers, **one assembly** ([`assemble`]). Each reduces its own look to the same
-//! [`PreviewSpec`] — body displayId + the five appearance dials + an enum-shaped
-//! `[CharEnumItem; 19]` — and gets back the flat part/rider/effect lists its booth bakes:
-//!
-//! - **The glue screens** ([`build_glue_preview`]): a **Select** look carries its roster record
-//!   verbatim; a **Create** look resolves the (race, class, sex) starting outfit (CharStartOutfit,
-//!   decision 0527) into that array — so the create preview is geared exactly like a select body
-//!   (the ref's create screen dresses the model, not the underwear-only body decision 0423 assumed).
-//! - **The dressing room** ([`build_dressup_preview`], decision 1060): the *live player's* own body
-//!   and appearance, wearing their own visible items with the tried-on ones substituted in. That
-//!   substitution is the whole feature, and it is why the dressing room cannot mirror a world
-//!   entity's spawned children the way the paper doll does (`portrait::sync_body_booth`) — nobody
-//!   in the world is wearing the item being previewed.
-//!
-//! 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 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
-//! entity — the dressing room's is the player's own, already built; item models register through
-//! the same [`ItemDisplays`] want the world path uses.
+//! The character preview behind every booth that shows a character nobody stands in: the glue
+//! screens' select and create bodies ([`build_glue_preview`]) and the dressing room
+//! ([`build_dressup_preview`]), whose try-ons nobody in the world wears. Each reduces its look to
+//! a [`PreviewSpec`], and [`assemble`] builds it the world's way: the display cache, the geoset
+//! filter, the composited body, the cloak, and the helm, shoulders and held weapons as riders
+//! (the select build `0x472950` holds weapons in the hands, `0x47a0c0`).
 
 use benilla_formats::CharSkinSlot;
 use benilla_protocol::{
@@ -50,23 +26,19 @@ use super::super::{
 };
 use super::char_skin::{equip_geosets, BodySkin, CharLook};
 
-/// The enum equipment slots that paint the armor-region composite, in the bodyslot order
-/// (shirt · chest · belt · pants · boots · wrist · gloves · tabard → bodyslot 2–9):
-/// equipment-slot indices 3, 4, 5, 6, 7, 8, 9, 18.
+/// The equipment slots of shirt, chest, belt, pants, boots, wrist, gloves and tabard, the armor
+/// composite's bodyslots 2 to 9.
 const ENUM_BODYSLOTS: [usize; 8] = [3, 4, 5, 6, 7, 8, 9, 18];
-/// The enum's helm / shoulder / cloak slots.
+/// The equipment slots of the helm, shoulders and cloak.
 const ENUM_HELM: usize = 0;
 const ENUM_SHOULDER: usize = 2;
 const ENUM_CLOAK: usize = 14;
-/// Main hand · off hand · ranged, in [`placement`]'s held-triple slot order (0/1/2).
+/// Main hand, off hand, ranged: [`placement`]'s held slots 0, 1, 2.
 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, `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).
+/// An item's `InventoryType` as its `EQUIPMENT_SLOT_*` index, so a CharStartOutfit item lands
+/// where a select record carries it (the compositor's render slots, `0x478cb0`); `None` for a
+/// type that never renders.
 pub(crate) fn equip_slot(inv_type: u8) -> Option<usize> {
     Some(match inv_type {
         1 => 0,             // HEAD
@@ -88,14 +60,10 @@ pub(crate) fn equip_slot(inv_type: u8) -> Option<usize> {
     })
 }
 
-/// One preview's complete input tuple — the body model, its five appearance dials, and the worn
-/// equipment in the `SMSG_CHAR_ENUM` slot shape. Both callers reduce their own look to this, so
-/// [`assemble`] has exactly one shape to build from and the two previews can never dress by
-/// different laws.
+/// One preview's input: the body display, its appearance, and the worn equipment in the
+/// `SMSG_CHAR_ENUM` slot shape.
 pub(in crate::entities) struct PreviewSpec {
-    /// The **body** display id, already resolved by the caller: the race/sex body for a glue look
-    /// (`CharCreateCatalog::body_display`), the live player's own display for the dressing room.
-    /// Its model must be in the display cache (or its want-list) or the assembly waits for it.
+    /// The race and sex body for a glue look, the player's own display for the dressing room.
     pub(in crate::entities) display_id: u32,
     pub(in crate::entities) race: u8,
     pub(in crate::entities) sex: u8,
@@ -104,30 +72,19 @@ pub(in crate::entities) struct PreviewSpec {
     pub(in crate::entities) hair_style: u8,
     pub(in crate::entities) hair_color: u8,
     pub(in crate::entities) facial_hair: u8,
-    /// Worn **ItemDisplayInfo** ids by equipment slot (`EQUIPMENT_SLOT_*`) — no template hop; the
-    /// caller has already resolved entries to displays.
+    /// Worn ItemDisplayInfo ids by `EQUIPMENT_SLOT_*`.
     pub(in crate::entities) equipment: [CharEnumItem; 19],
-    /// The wearer's guild tabard (decision 1704), or `None` for no crest.
     pub(in crate::entities) emblem: Option<benilla_formats::GuildEmblem>,
-    /// `CHARACTER_FLAG_*` bits; only hide-helm / hide-cloak are read here.
+    /// `CHARACTER_FLAG_*` bits; only hide-helm and hide-cloak are read.
     pub(in crate::entities) flags: u32,
-    /// **Whose held law this look follows** (decision 1076) — the one place the two previews
-    /// genuinely differ, and a *verified* difference rather than a convenience.
-    ///
-    /// `false` — the **character-select mannequin** (`0x472950`), whose equipment loop skips
-    /// `EQUIPMENT_SLOT_RANGED` outright (`0x472bfe cmp esi,0x11; je`) and forces SheatheType 0.
-    ///
-    /// `true` — the **dressing room** (`DressUpModel::TryOn 0x504d90`), which does not skip it: its
-    /// remap table (`0x504b7c` → `0x504b44`) sends `INVTYPE_RANGED` down the same held arm as a
-    /// weapon, and `sheathFlag = 0` is pushed literally at `0x504adc`, so a tried-on ranged weapon
-    /// is installed **at a hand and never at a sheath point, whatever its SheatheType** — by the
-    /// world's own split (bow → HandLeft, gun/crossbow/wand/thrown → HandRight). Which is exactly
-    /// why this rides [`placement`]'s existing, already-verified ranged arm rather than growing a
-    /// second copy of that mapping.
+    /// `false` for the select mannequin, whose equipment loop skips the ranged slot (`0x472950`,
+    /// `0x472bfe`); `true` for the dressing room (`0x504d90`), whose remap (`0x504b7c` to
+    /// `0x504b44`) and literal sheath 0 (`0x504adc`) put a tried-on ranged weapon in a hand
+    /// whatever its SheatheType, as [`placement`]'s ranged arm does: a bow left, the rest right.
     pub(in crate::entities) ranged_in_hand: bool,
 }
 
-/// What one [`assemble`] produced — the content half of a preview bake, in the booth's own shape.
+/// What [`assemble`] produced: a preview bake's content, in the booth's shape.
 pub(in crate::entities) struct Assembled {
     pub(in crate::entities) parts: Vec<PreviewPart>,
     pub(in crate::entities) riders: Vec<PreviewRider>,
@@ -136,16 +93,13 @@ pub(in crate::entities) struct Assembled {
     pub(in crate::entities) grip: [bool; 2],
 }
 
-/// The resource borrows [`assemble`] needs — the display caches it reads and registers wants with,
-/// the character/skin data the composite is built from, and the asset stores it writes into. A
-/// plain borrow struct rather than a `SystemParam`: each driver already holds these as its own
-/// `Res`/`ResMut` params and simply lends them for the call.
+/// The resources [`assemble`] borrows from its caller's system params.
 pub(in crate::entities) struct PreviewCtx<'a, 'w> {
     pub(in crate::entities) creatures: &'a Creatures,
     pub(in crate::entities) characters: Option<&'a Characters>,
     pub(in crate::entities) displays: Option<&'a mut ItemDisplays>,
-    /// The item/enchant glow chain (decision 0805): both previews resolve it themselves — the
-    /// world's `resolve_equipment` never runs pre-world, and never runs for a look nobody wears.
+    /// The glow chain, resolved here: the world's `resolve_equipment` never runs for a look
+    /// nobody wears.
     pub(in crate::entities) glows: Option<&'a mut ItemGlows>,
     pub(in crate::entities) sections: Option<&'a SkinSections>,
     pub(in crate::entities) world_assets: Option<&'a WorldAssets>,
@@ -155,10 +109,8 @@ pub(in crate::entities) struct PreviewCtx<'a, 'w> {
     pub(in crate::entities) mats: &'a mut benilla_world::model_render::M2BatchMaterials<'w>,
 }
 
-/// Assemble the preview part (+ rider) lists when the glue-screen look changes. Runs in the
-/// entity-visuals chain (after `update_display_models` has built the body model from the
-/// want-list), so a fresh look's models are ready within a frame or two; until then it leaves the
-/// bake untouched and retries. A bare yaw change never reaches here (the booth handles it).
+/// Assemble the glue-screen preview when its look changes, after `update_display_models`; until
+/// the models build it leaves the bake untouched and retries.
 pub(in crate::entities) fn build_glue_preview(
     preview: Res<GluePreview>,
     mut bake: ResMut<GluePreviewBake>,
@@ -166,8 +118,6 @@ pub(in crate::entities) fn build_glue_preview(
     characters: Option<Res<Characters>>,
     char_create: Option<Res<CharCreate>>,
     mut displays: Option<ResMut<ItemDisplays>>,
-    // The item/enchant glow chain (decision 0805): the glue screens resolve it themselves — the
-    // world's `resolve_equipment` never runs pre-world.
     mut glows: Option<ResMut<ItemGlows>>,
     sections: Option<Res<SkinSections>>,
     world_assets: Option<Res<WorldAssets>>,
@@ -175,17 +125,12 @@ 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 (`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.
+    // The ghost kit (`0x47280f`): its `SpellVisualKit` row, and the world's spell-effect model
+    // cache its models load through.
     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
-    // look whose models weren't ready yet keeps retrying until they build).
     mut state: Local<PreviewState>,
 ) {
-    // A new look resets the retry latch.
     if state.last_look != preview.look {
         state.last_look = preview.look;
         state.built = false;
@@ -194,7 +139,6 @@ pub(in crate::entities) fn build_glue_preview(
         return;
     }
 
-    // No look → clear the booth once.
     let Some(look) = preview.look else {
         if bake.look.is_some() {
             *bake = GluePreviewBake {
@@ -206,31 +150,23 @@ pub(in crate::entities) fn build_glue_preview(
         return;
     };
 
-    // displayId → the shared display cache. The want-list in `update_display_models` has already
-    // asked for this display; the assembly waits (retry, `built` stays false) until its model +
-    // parts are built.
     let (Some(creatures), Some(char_create)) = (creatures.as_deref(), char_create.as_deref())
     else {
         return;
     };
     let (race, sex) = look.body();
     let Some(display_id) = char_create.0.body_display(race, sex) else {
-        state.built = true; // a non-playable race can't resolve — nothing to show, don't spin
+        state.built = true; // a non-playable race: nothing to show, stop retrying
         return;
     };
 
-    // The body appearance is identical in shape for both looks (only its source struct differs).
     let (skin, face, hair_style, hair_color, facial_hair) = match look {
         GlueLook::Create(l) => (l.skin, l.face, l.hair_style, l.hair_color, l.facial_hair),
         GlueLook::Select(l) => (l.skin, l.face, l.hair_style, l.hair_color, l.facial_hair),
     };
 
-    // The equipment, unified as an enum-shaped `[CharEnumItem; 19]` + display flags: a Select look
-    // carries its roster record verbatim; a Create look resolves the (race, class, sex) starting
-    // outfit (CharStartOutfit, decision 0527) into the same slot array — each worn item at the
-    // equipment slot its InventoryType maps to. Display ids are ItemDisplayInfo ids in both cases
-    // (no template hop). A level-1 outfit carries no helm/cloak and there is no hide flag, so the
-    // create preview's flags are 0 — the create body is dressed exactly like a geared select body.
+    // A select look carries its roster record; a create look wears its (race, class, sex)
+    // CharStartOutfit, which has no helm or cloak to hide, so its flags are 0.
     let (equipment, flags): ([CharEnumItem; 19], u32) = match look {
         GlueLook::Create(l) => {
             let mut equipment = [CharEnumItem::default(); 19];
@@ -257,13 +193,11 @@ pub(in crate::entities) fn build_glue_preview(
         hair_color,
         facial_hair,
         equipment,
-        // No crest at character select (decision 1704). `SMSG_CHAR_ENUM` carries a `guildId` but
-        // not the five emblem indices, and there is no world session to `CMSG_GUILD_QUERY` with —
-        // so a Guild Tabard on the mannequin wears its own `Tabard_A_05Default` art, which is what
-        // the reference's own empty guild cache leaves it with too.
+        // No crest: `SMSG_CHAR_ENUM` has no emblem and there is no session to query, so a guild
+        // tabard wears its own art, as with the reference's empty guild cache.
         emblem: None,
         flags,
-        // The mannequin's own law: the select build skips EQUIPMENT_SLOT_RANGED (0x472bfe).
+        // The select build skips the ranged slot (`0x472bfe`).
         ranged_in_hand: false,
     };
     let Some(a) = assemble(
@@ -281,13 +215,10 @@ pub(in crate::entities) fn build_glue_preview(
             mats: &mut mats,
         },
     ) else {
-        return; // a model (body, item, or glow) is still loading — retry next frame
+        return; // a model is still loading: retry next frame
     };
 
-    // The ghost kit — a **Select** look only, and only when the roster record carries the bit
-    // (`CHARSELECT+0xfc & 0x2000`). A create look never can: the character does not exist yet, and
-    // the create screen builds its flags as `0` above. The kit's attached models join the ordinary
-    // lists; what the body renders with rides the bake.
+    // The ghost kit, for a select record with the ghost bit (`CHARSELECT+0xfc & 0x2000`).
     let mut a = a;
     let ghost = match look {
         GlueLook::Select(l) if l.flags & CHARACTER_FLAG_GHOST != 0 => {
@@ -303,7 +234,7 @@ pub(in crate::entities) fn build_glue_preview(
                 )
             })();
             if pending {
-                return; // an effect model is still loading — retry, don't bake a half ghost
+                return; // an effect model is still loading: retry
             }
             arm.map(|arm| {
                 a.riders.extend(arm.riders);
@@ -345,11 +276,8 @@ pub(in crate::entities) fn build_glue_preview(
     state.built = true;
 }
 
-/// Assemble the **dressing room**'s look (decision 1060) — the same law as the glue driver above,
-/// over a look whose equipment [`crate::ui_dressup`] composed from the player's own visible items
-/// plus the tried-on substitutions. The body display is the player's own, so it is already built
-/// (they are standing in the world); an ITEM model still has to load, which is what the retry latch
-/// is for.
+/// Assemble the dressing room's look, whose equipment [`crate::ui_dressup`] composed from the
+/// player's worn items and the try-ons; retries while an item model loads.
 pub(in crate::entities) fn build_dressup_preview(
     preview: Res<DressUpPreview>,
     mut bake: ResMut<DressUpBake>,
@@ -365,7 +293,6 @@ pub(in crate::entities) fn build_dressup_preview(
     mut mats: benilla_world::model_render::M2BatchMaterials,
     mut state: Local<DressUpState>,
 ) {
-    // A new look resets the retry latch (the glue driver's own shape).
     if state.last_look != preview.look {
         state.last_look = preview.look;
         state.built = false;
@@ -374,7 +301,6 @@ pub(in crate::entities) fn build_dressup_preview(
         return;
     }
 
-    // No look → clear the booth once (the window closed, or nothing to show).
     let Some(look) = preview.look else {
         if bake.look.is_some() {
             *bake = DressUpBake {
@@ -400,18 +326,12 @@ pub(in crate::entities) fn build_dressup_preview(
         facial_hair: look.facial_hair,
         equipment: look.equipment,
         emblem: look.emblem,
-        // **No hide flags here, because the hiding already happened upstream** (decision 1472).
-        // The dressing room DOES honour show-helm/show-cloak — byte-verified: `SetUnit 0x476cb0`
-        // clones the live player's per-bodyslot display pointers, so a suppressed piece is not in
-        // what is cloned — but a TRY-ON must preview the helm regardless, and only
-        // [`crate::ui_dressup`]'s look builder knows which slots are worn and which are tried on.
-        // So it applies the preference there, per slot, and hands us an already-correct array;
-        // re-applying a flag mask over it here would hide the very item being previewed.
+        // No hide flags: `crate::ui_dressup` already left out a hidden worn helm or cloak, as
+        // `SetUnit` (`0x476cb0`) clones the live display pointers, and a mask here would hide a
+        // tried-on one.
         flags: 0,
-        // The widget's law, not the mannequin's (decision 1076). Unconditional, because the ranged
-        // slot of a dressing-room look is only ever filled by a TRY-ON: `crate::ui_dressup` leaves
-        // a worn ranged weapon out, since the reference's Dress()/SetUnit clones the live world
-        // model and a ranged weapon shows there only while ranged-drawn.
+        // The ranged slot here only holds a try-on: `SetUnit` clones the live model, which shows
+        // a ranged weapon only while ranged-drawn, so `crate::ui_dressup` leaves a worn one out.
         ranged_in_hand: true,
     };
     let Some(a) = assemble(
@@ -429,7 +349,7 @@ pub(in crate::entities) fn build_dressup_preview(
             mats: &mut mats,
         },
     ) else {
-        return; // an item model is still loading — retry next frame
+        return; // an item model is still loading: retry next frame
     };
 
     debug!(
@@ -456,21 +376,13 @@ pub(in crate::entities) fn build_dressup_preview(
     state.built = true;
 }
 
-/// The one assembly both previews run — [`PreviewSpec`] in, the booth's flat lists out.
-///
-/// `None` means **not ready**: the body model, an item model, or a glow model is still loading.
-/// 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`. 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 (`0x5ff350`), so the two paths share one row by
-/// construction.
+/// The character-select ghost's `SpellVisualKit` row, hard-coded as in the reference: `0x47280f`
+/// loads `idmap[989]` behind the bound check at `0x4727f6`. It is `SpellVisual` 886's state kit,
+/// spell 8326 Ghost's, which a released ghost in the world rides too (`0x5ff350`).
 const GLUE_GHOST_KIT: u32 = 989;
 
-/// What the ghost kit contributes to a select bake: the body's own render properties, plus the
-/// kit's attached effect models already reduced to the booth's ordinary seat shapes.
+/// The ghost kit's share of a select bake: the body's tint and alpha, and its effect models as
+/// booth seats.
 struct GhostArm {
     kit: GhostKit,
     riders: Vec<PreviewRider>,
@@ -478,16 +390,11 @@ struct GhostArm {
     effects: Vec<PreviewEffects>,
 }
 
-/// Resolve [`GLUE_GHOST_KIT`] against the live `SpellVisualKit` catalog and the body's attachment
-/// table. `None` means **not ready** — either a DBC is absent (nothing to show, the caller stops
-/// retrying) or one of the kit's effect models is still loading (the caller retries), which the
-/// `pending` out-flag distinguishes.
-///
-/// The tint and alpha go through [`crate::aura_visual::node_for`] — the one dispatch point, the ECS
-/// twin of the client's `0x60dbfc` jump table — rather than a second decode here: the select screen
-/// and the world aura reach the same row, and a proc type newly given a mechanism must light up on
-/// both at once. What the select path does NOT share is the world's 1000 ms `StartAlphaFade` ramp:
-/// `0x4727f0` writes the instance fields straight through `0x710cb0`/`0x710cf0`, so this is instant.
+/// Resolve [`GLUE_GHOST_KIT`] against the kit catalog and the body's attachments; `pending` is set
+/// while an effect model loads. The tint and alpha decode through
+/// [`crate::aura_visual::node_for`], the reference's `0x60dbfc` table, as the world aura does, but
+/// land instantly (`0x4727f0` writes them through `0x710cb0`/`0x710cf0`), with no 1000 ms
+/// `StartAlphaFade`.
 fn glue_ghost_arm(
     body: &super::super::DisplayModel,
     visuals: &benilla_formats::SpellVisualCatalog,
@@ -504,9 +411,7 @@ fn glue_ghost_arm(
         match node {
             crate::aura_visual::AuraNode::Tint(rgb) => tint = Some(rgb),
             crate::aura_visual::AuraNode::Alpha(a) => alpha = Some(a),
-            // Every other proc type the row could carry belongs to a mechanism the select path has
-            // no equivalent for (the anim-rate freeze writes bone clocks on a world unit). 989
-            // carries only these two; a patched row that carries more is ignored, not guessed at.
+            // Row 989 carries only these two; other proc types have no select-screen mechanism.
             _ => {}
         }
     }
@@ -515,14 +420,12 @@ fn glue_ghost_arm(
         alpha: alpha.unwrap_or(1.0),
     };
 
-    // The kit's attached effect models, at the body's own attachment points. `Spells\Ghost_state.mdx`
-    // (slot tag 0x13, Base) is the only populated slot on the shipped row and is emitter-only — but
-    // the row is data, so geometry and camera-facing cards are carried too, split exactly the way the
-    // item-glow arm below splits an item's own model.
+    // The kit's effect models at the body's attachment points. The shipped row has only
+    // `Spells\Ghost_state.mdx` at Base (`0x13`), emitters only, but the row is data.
     let (mut riders, mut billboards, mut effects) = (Vec::new(), Vec::new(), Vec::new());
     for (tag, effect_id) in kit_row.effects() {
-        // The world-plant sentinel names no attachment point; the select build hangs models on the
-        // character alone (`0x472780` → `0x712f70`), so there is nowhere for it to go.
+        // The select build hangs models on the character alone (`0x472780` to `0x712f70`), so a
+        // world-planted effect has nowhere to go.
         if tag == benilla_formats::WORLD_EFFECT_TAG {
             continue;
         }
@@ -530,8 +433,8 @@ fn glue_ghost_arm(
             continue;
         };
         let path = path.to_string();
-        // `0x472780`'s `test esi,esi; jl 0x4727dd` rejects a `-1` attach id, and a body with no such
-        // point hangs nothing — the world path's rule, and the reference's.
+        // `0x472780` rejects a `-1` attach id (`jl 0x4727dd`); a body without the point hangs
+        // nothing.
         let Some(point) = body.attachments.iter().find(|a| a.id == tag) else {
             continue;
         };
@@ -545,7 +448,7 @@ fn glue_ghost_arm(
                     ..super::super::display::empty_shell()
                 });
         let Some(parts) = dm.parts.as_deref() else {
-            *pending = true; // still loading — the caller retries rather than baking half a ghost
+            *pending = true; // still loading: the caller retries
             continue;
         };
         for part in parts {
@@ -598,7 +501,7 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
         flags,
         ..
     } = *spec;
-    let dm = ctx.creatures.models.get(&display_id)?; // model not built yet — retry next frame
+    let dm = ctx.creatures.models.get(&display_id)?; // model not built yet: retry next frame
     let parts = dm.parts.as_deref()?; // asset still loading
 
     let char_look = CharLook {
@@ -622,26 +525,20 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
         equipment[ENUM_HELM].display_id
     };
     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`
-    // (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.
+    // Grip `[right, left]`: a hand whose attach point holds something closes (`0x5059a0`); a
+    // shield sits on the forearm 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),
     ];
 
-    // The rider models: register each want with [`ItemDisplays`] (built by
-    // `update_display_models` once the M2 loads) and gate the bake on ALL of them being ready —
-    // a geared character popping in piecewise would flicker on every selection change.
+    // Every rider model must be ready before the bake, or a geared character pops in piecewise.
     if let Some(d) = ctx.displays.as_deref_mut() {
         for w in &held {
             ensure_item_model(d, w.display, w.kind, ctx.asset_server);
         }
-        // The glow ids (decision 0805), and the models they imply: **held weapons/shields only**
-        // — the reference passes a display's visual from the hand attach and a literal `0` from
-        // the helm/shoulder ones (`crate::entities::item_glow`). The world lane resolves this in
-        // `resolve_equipment`, which never runs pre-world.
+        // Glows for held weapons and shields only: the helm and shoulder attaches pass a literal
+        // 0 visual (`crate::entities::item_glow`).
         if let Some(g) = ctx.glows.as_deref_mut() {
             for w in held
                 .iter_mut()
@@ -657,10 +554,9 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
                 .and_then(|m| m.parts.as_ref())
                 .is_some()
         }) {
-            return None; // an item model is still loading — retry next frame
+            return None; // an item model is still loading: retry next frame
         }
-        // Same gate for the glow models: they are tiny beside the weapon that carries them, and a
-        // weapon that pops in ahead of its glow would flicker on every selection change.
+        // The same gate for the glow models.
         if let Some(g) = ctx.glows.as_deref() {
             let pending = held
                 .iter()
@@ -673,8 +569,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
-    // (`0x4799a0`), exactly the world path's selection (the shared helper).
+    // The world path's geoset selection, the helm's hide-mask rows included (`0x4799a0`).
     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)
@@ -695,7 +590,6 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
         ctx.mats,
     );
 
-    // Whether this look shows the part's geoset (billboard or body alike).
     let shows = |p: &EntityPart| {
         visible
             .as_ref()
@@ -709,20 +603,14 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
             skinned_mesh: p.skinned_mesh.clone(),
             material: steady_material(p, &char_mats).unwrap_or_else(|| p.material.clone()),
             twins: part_twins(p, &char_mats),
-            // `None` — decision 0807's named gap, deliberately still open: a character batch with
-            // an authored dimming constant previews at 1.0. The select body's look is signed off
-            // as it stands, so closing it is its own change, not a rider on the pet's.
+            // Not carried yet: a character batch's authored dimming constant previews at 1.0.
             alpha_anim: None,
         })
         .collect();
 
-    // The eye-glow (and any character billboard) — the undead/night-elf glowing eyes. The world
-    // splits these into camera-facing cards; the booth is a separate camera, so it can't ride that
-    // system — carry them through to the booth spawn, which seats each on its billboard bone's joint
-    // and re-faces it ([`crate::portrait::booth::face_booth_billboards`]). Geoset-gated like the body
-    // parts: the undead glow rides geoset 302 (the glowing "Features" variants), faithful to the DBC.
-    // The batch is fullbright (M2 unlit), so it keeps its built material — no char-skin swap. Offset
-    // `ZERO`: the body IS rigged here, so its billboard bone's joint already bakes the pivot.
+    // The body's billboard batches (the undead and night-elf eye glow), which the booth faces to
+    // its own camera; geoset-gated like the body (the undead glow is geoset 302). Unlit, so they
+    // keep their built material; offset zero, since the rigged body's joint bakes the pivot.
     let mut preview_billboards: Vec<PreviewBillboard> = parts
         .iter()
         .filter(|p| shows(p))
@@ -742,42 +630,27 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
         })
         .collect();
 
-    // The riders: each want's item-model parts seated at the body's attach point (bone + offset),
-    // the world path's `PortraitRider` shape — plus, for a held weapon, the glows its display's
-    // `ItemVisuals` id hangs on the weapon's OWN attachment points (decision 0805). The reference
-    // reaches those through the same primitive here as in the world (`0x472c91` → `0x47a0c0`
-    // hands `ItemDisplayInfo+0x58` to `0x4798c0`), so a permanently-glowing weapon glows on the
-    // select screen too; the enum carries no enchant ids (vmangos `BuildEnumData` sends displayId
-    // + inventoryType only), so the fork's enchant half simply has no input here.
-    //
-    // 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. 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 —
-    // the same three off each glow model its `ItemVisuals` names.
+    // Each want seats at the body's attach point: its meshes, billboard batches and emitters, and
+    // for a held weapon the same off each glow model its `ItemVisuals` id names, reached as in the
+    // world (`0x472c91` to `0x47a0c0` hands `ItemDisplayInfo+0x58` to `0x4798c0`). The enum has
+    // no enchant ids (vmangos `Player.cpp:1724`), so no enchant glow shows here.
     let attach_point = |id: u16| dm.attachments.iter().find(|a| a.id == id);
     let mut riders = Vec::new();
     let mut preview_effects = Vec::new();
     if let Some(d) = ctx.displays.as_deref() {
         for w in &held {
             let Some(point) = attach_point(w.attach) else {
-                continue; // the body has no such attach point — hold nothing (world-path rule)
+                continue; // no such attach point: hold nothing, as in the world
             };
             let Some(item) = d.models.get(&(w.display, w.kind)) else {
-                continue; // gated above; belt-and-braces
+                continue; // gated above
             };
             let Some(item_parts) = item.parts.as_deref() else {
                 continue;
             };
             for p in item_parts.iter() {
-                // A camera-facing batch of the item — a wand's gem, a glowing rune (270 of the 2681
-                // `Item\` models author one). It can't be drawn as a plain rider mesh: the world
-                // splits it into a card, so the booth carries it as one too, seated at the attach
-                // point **plus its own model-local pivot** (an item model gets no rig here, so
-                // nothing else bakes that pivot).
+                // A billboard batch rides as a card at the attach point plus its own pivot: an item
+                // model gets no rig here to bake it.
                 match &p.billboard {
                     Some(info) => preview_billboards.push(PreviewBillboard {
                         mesh: p.mesh.clone(),
@@ -802,10 +675,7 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
                     }),
                 }
             }
-            // The item model's OWN particle emitters — the R14 PVP pauldron's `SPARKLE` twinkle
-            // (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.
+            // The item's own emitters (a torch's flame), spawned off a host at the attach point.
             if !item.emitters.is_empty() {
                 preview_effects.push(PreviewEffects {
                     bone: point.bone,
@@ -821,9 +691,8 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
                 .enumerate()
                 .filter_map(|(i, p)| p.as_ref().map(|p| (i, p)))
             {
-                // The seat: the body's attach point plus where this slot sits on the ITEM's own
-                // model. A slot the item model doesn't author hangs nothing — the world lane's
-                // rule, and the reference's.
+                // The body's attach point plus the slot's place on the item model; a slot the item
+                // does not author hangs nothing.
                 let at = crate::portrait::attachment_point(
                     &item.skeleton,
                     &item.attachments,
@@ -836,11 +705,8 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
                 };
                 let offset = point.offset + at;
                 for p in glow.parts.iter().flatten() {
-                    // Same split as the item's own batches above. This is not a rare arm:
-                    // `Spells\Enchantments\Sparkle_A.m2` is *one* additive camera-facing quad and
-                    // nothing else — no emitters at all — and `ItemVisuals` 28 (10 item displays)
-                    // hangs it on slot 4, so dropping billboard batches here glowed those items
-                    // nothing whatsoever at select.
+                    // Split as above: `Sparkle_A.m2` is one additive billboard quad and nothing
+                    // else.
                     match &p.billboard {
                         Some(info) => preview_billboards.push(PreviewBillboard {
                             mesh: p.mesh.clone(),
@@ -885,10 +751,8 @@ fn assemble(spec: &PreviewSpec, ctx: &mut PreviewCtx<'_, '_>) -> Option<Assemble
     })
 }
 
-/// One wanted rider model: which display + model kind, the body attach point it seats on, and —
-/// filled in by the caller once the display catalog is in hand — the `ItemVisuals` id its glow
-/// comes from (`0` for everything that never glows: helm, shoulders, and any weapon whose display
-/// authors none). Decision 0805.
+/// One wanted rider model; `visual` is its `ItemVisuals` glow id, 0 for none, filled in by the
+/// caller.
 struct HeldWant {
     display: u32,
     kind: ItemModelKind,
@@ -896,20 +760,11 @@ struct HeldWant {
     visual: i32,
 }
 
-/// The select character's attach-model wants from its enum record: helm + the shoulder pair, and
-/// 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
-/// [`placement`]'s **ranged-drawn** arm already carries, so the flag simply chooses which sheath
-/// state the ranged slot is asked with — the melee pair is always asked drawn.
+/// A preview's helm, shoulder pair and held weapons. The select build forces SheatheType 0
+/// (`0x472c8c`), so weapons go to the hands (main hand right, off hand left, a shield to its
+/// point) and the ranged slot is skipped (`0x472bfe`): [`placement`]'s melee-drawn arm. A held
+/// off-hand frill takes the same hand law; `0x47a0c0` is traced for weapons and shields only.
+/// `ranged_in_hand` asks the ranged slot ranged-drawn instead, the dressing room's hand install.
 fn held_wants(
     equipment: &[CharEnumItem; 19],
     helm: u32,
@@ -923,7 +778,7 @@ fn held_wants(
             display: helm,
             kind: ItemModelKind::Helm { race, sex },
             attach: attach_id::HELM,
-            visual: 0, // a helm never glows: its attach site pushes a literal 0 (0805)
+            visual: 0, // a helm never glows: its attach site passes a literal 0
         });
     }
     let shoulder = equipment[ENUM_SHOULDER].display_id;
@@ -936,7 +791,7 @@ fn held_wants(
                 display: shoulder,
                 kind,
                 attach,
-                visual: 0, // nor do shoulders — same rule
+                visual: 0, // nor do shoulders
             });
         }
     }
@@ -945,10 +800,7 @@ fn held_wants(
         if item.display_id == 0 {
             continue;
         }
-        // Per-slot, because the two arms want opposite sheath states: the melee pair yields while
-        // melee-drawn (1), the ranged slot only while ranged-drawn (2). The mannequin asks every
-        // slot drawn-melee, which is its own ranged skip; the dressing room asks the ranged slot
-        // drawn-ranged, which is the widget's hand install (decision 1076).
+        // The melee pair yields melee-drawn (1), the ranged slot only ranged-drawn (2).
         let unit_sheath = if held_slot == 2 && ranged_in_hand {
             2
         } else {
@@ -972,20 +824,11 @@ fn held_wants(
     wants
 }
 
-/// A batch's translucency twins ([`BoothTwins`]) as the preview carries them — the `AlphaMode::Blend`
-/// twin and the depth-prime twin, both already built beside the steady material by
-/// `M2BatchMaterials` (an `EntityPart` carries its own pair; a character composite's are the quint's
-/// third and sixth members). `char_mats` supplies them for a **character** batch, whose steady
-/// material is the composited atlas rather than the part's own built one; every other part answers
-/// from itself.
-///
-/// Only a bake whose instance alpha is below 1 ever draws through them (the ghost select), but they
-/// are collected unconditionally: they cost two handle clones on a bake that happens once per
-/// selection, and a look that resolves them *conditionally* would have to re-assemble on the ghost
-/// edge, which is exactly the sort of second code path the one-alpha law exists to prevent.
+/// A batch's blend and depth-prime twins ([`BoothTwins`]): a character batch's from its slot's
+/// set, any other's from itself. Only a bake below alpha 1 (the ghost) draws them, but they are
+/// always collected so the ghost edge needs no re-assembly.
 fn part_twins(part: &EntityPart, char_mats: &super::char_skin::CharSkinMaterials) -> BoothTwins {
-    // The same slot walk [`steady_material`] does, kept beside it so the pair can never disagree
-    // about which quint a batch reads.
+    // [`steady_material`]'s slot walk; the two must agree.
     let quint = (|| match part.char_slot {
         Some(CharSkinSlot::Body) => {
             let (single, two) = char_mats.0.as_ref()?;
@@ -1000,13 +843,11 @@ fn part_twins(part: &EntityPart, char_mats: &super::char_skin::CharSkinMaterials
         None => None,
     })();
     match quint {
-        // The quint's order is the engine's variant set: (steady, interior, fade_blend,
-        // interior_bake, interior_bake_blend, zfill) — `char_skin::build_char_skin_materials`.
+        // `MatQuint` order: the fade blend third, the depth-prime twin sixth.
         Some(q) => BoothTwins {
             blend: Some(q.2.clone()),
             zfill: q.5.clone(),
         },
-        // A non-character batch keeps its own built material, so it keeps its own twins.
         None => BoothTwins {
             blend: part.fade_blend.clone(),
             zfill: part.zfill.clone(),
@@ -1014,10 +855,7 @@ fn part_twins(part: &EntityPart, char_mats: &super::char_skin::CharSkinMaterials
     }
 }
 
-/// The steady, world-lit material a character part wears — the body atlas (at the part's sidedness),
-/// the hair texture, the cape, or the extra-skin fur — mirroring the attach swap ([`super`]) but
-/// keeping only the steady variant (the booth wants no fade / interior twin). `None` for a
-/// non-character part (it keeps its built material).
+/// A character part's steady material, the attach swap without its fade and interior variants.
 fn steady_material(
     part: &EntityPart,
     char_mats: &super::char_skin::CharSkinMaterials,
@@ -1042,25 +880,14 @@ fn steady_material(
     Some(quint.0.clone())
 }
 
-/// Assemble the select screen's **pet** — the hunter/warlock companion the enum's pet triple names
-/// (`SMSG_CHAR_ENUM`'s `petDisplayId`, the reference's secondary model `record+0x114`).
-///
-/// Its own system beside [`build_glue_preview`], not a limb of it, for the reason
-/// [`GluePetBake`] is its own resource: a pet is an ordinary creature display with no compositor,
-/// no equipment and no geoset selection between the display cache and the booth, and its model
-/// lands on its own schedule. Folding it into the character's assembly would gate the *character*
-/// on the pet's asset — a body that waits for a wolf to load is a worse screen than a body that is
-/// joined by one a frame later.
-///
-/// Runs after `update_display_models`, whose want-list asked for this display; retries (leaving
-/// `built` false) until its parts build.
+/// Assemble the select screen's pet, the enum's `petDisplayId` (the reference's secondary model,
+/// `record+0x114`); its own system, so the character never waits on the pet's model.
 pub(in crate::entities) fn build_glue_pet(
     preview: Res<GluePreview>,
     mut bake: ResMut<GluePetBake>,
     creatures: Option<Res<Creatures>>,
-    // The `CreatureFamily` size ramp (decision 1538) — the pet's scale is its family's, read at its
-    // level. Absent (the DBC failed to load) ⇒ every pet falls back to its display's own scale
-    // product, which is the reference's own family-miss fallthrough.
+    // The `CreatureFamily` size ramp; without it a pet takes its display's scale, the reference's
+    // family-miss fallthrough.
     families: Option<Res<crate::ui_pet_stats::PetFamilyTables>>,
     mut state: Local<PetState>,
 ) {
@@ -1072,8 +899,7 @@ pub(in crate::entities) fn build_glue_pet(
     if state.built {
         return;
     }
-    // No pet (every class but a living hunter's or warlock's — the server suppresses the triple
-    // for the rest) → clear the bake once and stop.
+    // The server sends a pet only for a living hunter or warlock (vmangos `Player.cpp:1693`).
     let Some(want) = want else {
         if bake.display_id != 0 {
             *bake = GluePetBake {
@@ -1088,7 +914,7 @@ pub(in crate::entities) fn build_glue_pet(
         return;
     };
     let Some(pet) = assemble_pet(creatures, families.as_deref(), want) else {
-        return; // the model is still loading — retry next frame
+        return; // the model is still loading: retry next frame
     };
     debug!(
         "glue pet: display {} (family {} level {}) → {} parts, {} camera-facing, scale {:.3}",
@@ -1106,12 +932,8 @@ pub(in crate::entities) fn build_glue_pet(
     state.built = true;
 }
 
-/// The pet's parts, straight off the shared display cache: every batch of the creature model, split
-/// into plain meshes and the camera-facing ones (a voidwalker's eyes are the latter). `None` while
-/// the display's model is still building.
-///
-/// No geoset filter: only the character compositor selects among a model's geosets, and a pet is
-/// not a character model — the world's creature path draws every batch of a beast the same way.
+/// The pet's parts off the display cache, meshes and billboards apart. No geoset filter: only the
+/// character compositor hides geosets.
 fn assemble_pet(
     creatures: &Creatures,
     families: Option<&crate::ui_pet_stats::PetFamilyTables>,
@@ -1131,10 +953,8 @@ fn assemble_pet(
                 skinned_mesh: p.skinned_mesh.clone(),
                 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 (`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.
+                // The pet hangs on the scene, never the character (`0x47306e`), so it is never
+                // ghosted with its owner; the twins are the batch's all the same.
                 twins: BoothTwins {
                     blend: p.fade_blend.clone(),
                     zfill: p.zfill.clone(),
@@ -1149,8 +969,7 @@ fn assemble_pet(
                     mesh: p.mesh.clone(),
                     material: p.material.clone(),
                     bone: info.bone,
-                    // `ZERO`: the pet is rigged, so its billboard bone's booth joint already bakes
-                    // the pivot (the 0130 rig identity) — the same seat the body's eye-glow takes.
+                    // The rigged pet's booth joint already bakes the pivot.
                     offset: Vec3::ZERO,
                     kind: info.kind,
                     twins: BoothTwins {
@@ -1160,13 +979,9 @@ fn assemble_pet(
                 })
             })
             .collect(),
-        // The model's own emitters, carried whole: an imp without its flames is the same kind of
-        // wrong as an imp without its wings. `parts` and `emitters` are captured together when the
-        // asset lands, so the `parts` gate above already answers for both.
+        // `parts` and `emitters` land together, so the `parts` gate covers both.
         emitters: model.emitters.clone(),
-        // The size: the family's level ramp, and the display's scale product only where the family
-        // table can't answer — which is the reference's own order (it computes the product, then
-        // overwrites it with the ramp, `0x472e87`). A display neither can size renders at 1.0.
+        // The family's level ramp overwrites the display's scale product (`0x472e87`).
         scale: families
             .and_then(|f| f.families.pet_scale(want.family, want.level))
             .or_else(|| creatures.model_scale(display_id))
@@ -1175,8 +990,7 @@ fn assemble_pet(
     })
 }
 
-/// [`build_glue_pet`]'s per-run memory — the pet display it last emitted a bake for, and whether
-/// that bake succeeded (a display whose model wasn't ready keeps retrying).
+/// [`build_glue_pet`]'s per-run memory.
 #[derive(Default)]
 pub(in crate::entities) struct PetState {
     last: Option<PetLook>,
@@ -1190,7 +1004,7 @@ pub(in crate::entities) struct PreviewState {
     built: bool,
 }
 
-/// [`build_dressup_preview`]'s per-run memory — the same latch over the dressing room's look.
+/// [`build_dressup_preview`]'s per-run memory.
 #[derive(Default)]
 pub(in crate::entities) struct DressUpState {
     last_look: Option<DressUpLook>,
@@ -1201,19 +1015,9 @@ pub(in crate::entities) struct DressUpState {
 mod tests {
     use super::*;
 
-    /// GOLDEN, against the **real shipped 5875 `SpellVisualKit.dbc`** — the one row the reference
-    /// hard-codes for the character-select ghost, decoded through the same dispatch point the world
-    /// aura uses.
-    ///
-    /// 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 an earlier reading (benilla
-    /// decision 0469 §6 carried it), and `0x472780`'s `test esi,esi; jl` rejects the eight `-1`s.
+    /// Against the shipped `SpellVisualKit.dbc`: 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 it fills
+    /// one effect slot, at Base (`0x13`); `0x472780` rejects the other eight `-1`s.
     #[test]
     fn the_shipped_ghost_kit_decodes_to_the_verified_row() {
         let data = benilla_formats::wow_data_or_skip!();
@@ -1239,7 +1043,6 @@ mod tests {
             "kit 989's CharProc 14 is 0.5; got {nodes:?}"
         );
 
-        // Exactly ONE populated slot, and it is the Base attach point — not nine.
         let effects: Vec<_> = kit.effects().collect();
         assert_eq!(effects.len(), 1, "kit 989 fills one slot, got {effects:?}");
         let (tag, effect_id) = effects[0];
@@ -1254,15 +1057,8 @@ mod tests {
         );
     }
 
-    /// **The bug the imp filed** (decision 1539): a pet is a *creature* display, and creature models
-    /// routinely author their own particle emitters — the Imp's three flame jets, the Voidwalker's
-    /// four smoke plumes. `assemble_pet` read `parts` and nothing else, so they never reached the
-    /// booth and the select screen stood a grey imp beside the warlock.
-    ///
-    /// Asserted as "everything the display cache holds arrives", not "three emitters arrive": the
-    /// failure mode was a *dropped field*, and a count pinned to one model would pass just as
-    /// silently the next time one is added. The billboard-chain emitter is in the fixture because
-    /// it is the branch that survives a booth's `without_camera_billboards` only through the frame
+    /// Every emitter the display holds reaches the bake (an imp's flames). The billboard-chain one
+    /// is in the fixture because a booth keeps it only through the frame
     /// [`crate::portrait::spawn_booth_own_emitters`] spawns for it.
     #[test]
     fn a_pet_carries_every_emitter_its_display_authored() {
@@ -1285,8 +1081,7 @@ mod tests {
             idle_seq: usize::from(bone),
         };
         let mut dm = crate::entities::display::empty_shell();
-        // Built, and it drew nothing of its own — the emitters are the whole model here. An empty
-        // `parts` list is still `Some`, which is what "the asset landed" means to the gate.
+        // An empty `parts` is still `Some`: the asset landed.
         dm.parts = Some(Vec::new());
         dm.emitters = vec![emitter(17, None), emitter(45, None), emitter(51, Some(42))];
         let mut creatures = Creatures {
@@ -1321,8 +1116,7 @@ mod tests {
             "the billboard host bone rides along — a booth needs it to seat the frame"
         );
 
-        // A display still loading (`parts: None`) yields nothing at all rather than a pet with
-        // emitters and no body: the retry latch is what stands it up a frame later.
+        // A display still loading yields no pet, not emitters without a body.
         let mut loading = crate::entities::display::empty_shell();
         loading.emitters = vec![emitter(17, None)];
         creatures.models.insert(4450, loading);
@@ -1341,10 +1135,8 @@ mod tests {
         );
     }
 
-    /// The InventoryType → equipment-slot map lands each worn kind where the Select pipeline reads
-    /// it, and drops the non-rendered kinds. Pinned against the real Human Warrior recruit set
-    /// (byte-verified in decision 0527): shirt→body(3), pants→legs(6), boots→feet(7), the mainhand
-    /// sword→15, the shield→offhand(16); the outfit's food/hearthstone (inv 0) drop out.
+    /// Pinned against the Human Warrior starting outfit: shirt, pants, boots, a main-hand sword and
+    /// a shield; its food and hearthstone (inv 0) drop out.
     #[test]
     fn equip_slot_maps_the_recruit_set_and_drops_non_worn() {
         assert_eq!(equip_slot(4), Some(ENUM_BODYSLOTS[0])); // shirt (BODY) → slot 3
@@ -1358,11 +1150,9 @@ mod tests {
         assert_eq!(equip_slot(16), Some(ENUM_CLOAK)); // BACK → cloak slot
         assert_eq!(equip_slot(19), Some(ENUM_BODYSLOTS[7])); // TABARD → slot 18
         assert_eq!(equip_slot(15), Some(ENUM_HELD[2])); // RANGED → ranged slot (17)
-                                                        // Non-worn / non-rendered kinds drop out entirely.
         for inv in [0u8, 11, 12, 18, 24, 27, 28] {
             assert_eq!(equip_slot(inv), None, "inv {inv} should not map to a slot");
         }
-        // Every mapped slot is a valid index into the 19-slot enum array.
         for inv in 0u8..=30 {
             if let Some(slot) = equip_slot(inv) {
                 assert!(slot < 19, "inv {inv} → slot {slot} out of range");
@@ -1370,14 +1160,8 @@ mod tests {
         }
     }
 
-    /// **The two held laws, side by side** (decision 1076). The character-select mannequin skips
-    /// `EQUIPMENT_SLOT_RANGED` outright (`0x472bfe`); the dressing-room widget installs it at a
-    /// hand, by the world's own split — bow (INVTYPE_RANGED 15) to HandLeft, gun/crossbow/wand
-    /// (26) and thrown (25) to HandRight.
-    ///
-    /// Asserted per inventory type rather than once, because a one-sided implementation — placing
-    /// every ranged type at the same hand — is the plausible wrong answer and it still shows *a*
-    /// bow, which is all the report asked for.
+    /// The mannequin skips the ranged slot (`0x472bfe`); the dressing room hands a bow (15) to the
+    /// left and a gun, crossbow or wand (26) or a thrown weapon (25) to the right.
     #[test]
     fn the_dressing_room_hands_a_ranged_weapon_where_the_mannequin_drops_it() {
         let ranged = |inv: u8| {
@@ -1405,8 +1189,8 @@ mod tests {
         }
     }
 
-    /// …and the flag touches ONLY the ranged slot: the melee pair is asked drawn either way, so a
-    /// dressing-room look still hands a sword to HandRight and a shield to the Shield point.
+    /// The flag touches only the ranged slot: a sword still goes to HandRight, a shield to its
+    /// point.
     #[test]
     fn the_ranged_flag_leaves_the_melee_pair_alone() {
         let mut e = [CharEnumItem::default(); 19];
diff --git a/crates/benilla-app/src/entities/attach/redress.rs b/crates/benilla-app/src/entities/attach/redress.rs
index 9fe2aec1..683d359e 100644
--- a/crates/benilla-app/src/entities/attach/redress.rs
+++ b/crates/benilla-app/src/entities/attach/redress.rs
@@ -1,30 +1,9 @@
-//! **Re-dressing** a character in place when its worn equipment changes — the gear-change half of
-//! [`super`] (decision 0074's teardown, replaced).
-//!
-//! A gear change used to tear the whole visual down (`despawn_related::<Children>()` + strip the rig,
-//! the animation player, the bone-attach table and the held-item bookkeeping) and let
-//! [`super::attach_entity_visuals`] rebuild it the next frame. That is not what the reference does,
-//! and the difference is visible: it destroys and re-creates *every* attached model too — both
-//! weapons, their enchant glows, the helm, the shoulders, every persistent aura visual — so swapping
-//! a belt blinked things that had nothing to do with the belt (and, before decision 0833 chained an
-//! effect's lifetime to its model, smeared their particle clouds across the ground behind a running
-//! character).
-//!
-//! 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 (`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:
-//!
-//! 1. re-composite the body atlas + re-resolve the cape texture for the new equipment, and re-point
-//!    every standing part's material variants at them ([`super::dress::part_materials`]);
-//! 2. re-run the geoset selection — a batch the new gear hides is despawned, one it reveals is
-//!    spawned by the same [`super::dress::spawn_part`] the first build used;
-//! 3. touch nothing else. The rig, the pose buffer, the bone anchors, the held items and everything
-//!    hanging off them are the same objects they were a frame ago.
+//! Re-dressing a character in place when its worn equipment changes. The reference re-dresses the
+//! same `CM2Model`: its compositor re-blits the atlas and re-runs the geoset selection
+//! (`0x477520`), which writes only the model's visibility array (`+0x98`, through `0x7110d0`), and
+//! never touches the attachments (`0x712f70`). So a re-dress re-points the standing parts at the
+//! new materials, despawns the batches the gear hides, spawns the ones it reveals, and leaves the
+//! rig and everything hanging off it alone.
 
 use benilla_protocol::EntityKind;
 use bevy::prelude::*;
@@ -50,11 +29,8 @@ use super::char_skin::{
 use super::dress::{part_materials, spawn_group, DressedPart, PartDress};
 use super::merge::{self, DressedGroup, MergedFormsCache};
 
-/// The per-part write surface of a re-dress: the displayed material and the three records that
-/// decide what a part draws when something *else* owns that channel — the interior classifier's law
-/// variants, the fade ramps' twin pair, and the portrait booths' steady mirror. All optional
-/// because a [`DressedPart`] is also carried by a billboard batch's **anchor**, which draws nothing
-/// (its card is a world root) and holds none of them.
+/// What a re-dress writes on a part: its material and its interior, fade and portrait records;
+/// all optional, since a billboard anchor carries a [`DressedPart`] and none of them.
 type PartWrites<'a> = (
     Option<Mut<'a, MeshMaterial3d<WowModelMaterial>>>,
     Option<Mut<'a, InteriorLit>>,
@@ -62,10 +38,8 @@ type PartWrites<'a> = (
     Option<Mut<'a, PortraitPart>>,
 );
 
-/// Re-dress every player whose worn equipment changed, in place (module docs). Players only: a
-/// creature's look never changes this way, and a character-model NPC wears its display's columns —
-/// a *display* change is a different model and stays a teardown
-/// ([`super::super::live_display::refresh_live_display`]).
+/// Re-dress every player whose worn equipment changed. A display change is a different model and
+/// stays a teardown (`refresh_live_display`).
 #[allow(clippy::type_complexity)]
 pub(in crate::entities) fn redress_player_looks(
     mut commands: Commands,
@@ -78,15 +52,14 @@ pub(in crate::entities) fn redress_player_looks(
             &Children,
             Option<&benilla_world::rig_palette::RigSkin>,
             Option<&super::super::BoneAttach>,
-            // The pose buffer: a revealed billboard batch's card bone resolves its anchor on
-            // first demand (`RigPose::anchor_for`, decision 1355).
+            // A revealed billboard batch's card bone resolves its anchor here.
             Option<&mut benilla_world::rig_anim::RigPose>,
             Option<&benilla_world::interior::BodyBakeCenter>,
             Option<&benilla_world::model_fade::UnitAppearFade>,
         ),
         With<VisualAttached>,
     >,
-    // The parts already standing under those players — found again by the batch index each carries.
+    // The standing parts, found again by their batch index.
     mut standing: Query<(
         &DressedPart,
         Option<&DressedGroup>,
@@ -101,8 +74,7 @@ pub(in crate::entities) fn redress_player_looks(
     creatures: Option<Res<Creatures>>,
     displays: Option<Res<ItemDisplays>>,
     characters: Option<Res<Characters>>,
-    // The character-skin build chain, nested to stay inside Bevy's system-param tuple limit — the
-    // same set [`super::attach_entity_visuals`] composites with, because it is the same composite.
+    // The skin build chain, nested for Bevy's system-param limit.
     skin_build: (
         Option<Res<SkinSections>>,
         Option<Res<WorldAssets>>,
@@ -113,10 +85,7 @@ pub(in crate::entities) fn redress_player_looks(
         ResMut<Assets<Mesh>>,
         ResMut<MergedFormsCache>,
     ),
-    // The animated-material lane a re-dressed part may need a material of its own on (2295).
-    // Plumbing here rather than a live case: a re-dress is a PLAYER's gear change, and no
-    // character batch in the corpus carries a per-sequence loop — but the dressing law is one law,
-    // and a path that could not express it would be a place for the two to drift.
+    // The own-material lane `spawn_part` takes; no character batch in the shipped data uses it.
     mut own_lane: (
         ResMut<benilla_world::doodad_anim::UvAnimMaterials>,
         ResMut<benilla_world::doodad_anim::TintAnimMaterials>,
@@ -138,14 +107,11 @@ pub(in crate::entities) fn redress_player_looks(
     for (entity, net, live, mut applied, children, rig, bones, mut pose, bake_center, unit_fade) in
         &mut players
     {
-        // `settled` (decision 0074): every non-empty visible-item entry has resolved through the
-        // template cache. Re-dressing on a half-resolved set would composite a half-dressed atlas
-        // and then composite again a frame later.
+        // Wait until every visible item has resolved, or a half-dressed atlas composites first.
         if net.kind != EntityKind::Player || !live.settled || *live == applied.0 {
             continue;
         }
-        // Stamp first, unconditionally: a player whose display resolved to no model at all (the
-        // cube fallback) has nothing to re-dress, and must not re-enter this arm every frame.
+        // Stamp first: a model-less player has nothing to re-dress and must not retry every frame.
         applied.0 = *live;
         let Some(dm) = net
             .display_id
@@ -157,7 +123,6 @@ pub(in crate::entities) fn redress_player_looks(
             continue;
         };
 
-        // The dressing inputs, re-resolved exactly as the first build resolved them.
         let worn = resolve_worn_equip(net, Some(live), Some(dm));
         let look = resolve_char_look(net, Some(dm), entity, &stores);
         let eg = equip_geosets(
@@ -171,8 +136,7 @@ pub(in crate::entities) fn redress_player_looks(
             let cg = characters.as_deref()?;
             Some(cg.0.visible_geosets(l.race, l.sex, l.hair_style, l.facial_hair, &eg))
         });
-        // The re-composite. Cached per (appearance, worn set) in `SkinComposites`, so a swap back
-        // to a set already worn this session costs a lookup.
+        // Cached per (appearance, worn set), so a swap back costs a lookup.
         let char_mats: CharSkinMaterials = match look.as_ref() {
             Some(l) => build_char_skin_materials(
                 l,
@@ -191,13 +155,10 @@ pub(in crate::entities) fn redress_player_looks(
             ),
             None => (None, None, None, (None, None)),
         };
-        // No look (a druid form, a GM morph — a Player-kind entity on a beast display) means no
-        // geoset filter, exactly as at build: every batch the model authors draws.
+        // No look (a druid form on a beast display) means no geoset filter, as at build.
         let shows = |geoset: u16| visible.as_ref().is_none_or(|v| v.contains(&geoset));
-        // The grouping the new gear asks for (`merge`): a standing group survives exactly when
-        // the new grouping contains its member set unchanged — then it re-points in place like
-        // any part; otherwise it is torn down and the new group spawns whole. Keyed by first
-        // member, which is what a standing entity's `DressedPart::index` carries.
+        // A standing group survives only if the new grouping keeps its member set; keyed by the
+        // first member, the standing entity's `DressedPart::index`.
         let groups = merge::guard_groups(
             merge::group_parts(parts, |p| shows(p.geoset_id)),
             parts,
@@ -206,7 +167,7 @@ pub(in crate::entities) fn redress_player_looks(
         let group_of: std::collections::HashMap<u32, &merge::BodyGroup> =
             groups.iter().map(|g| (g.first(), g)).collect();
 
-        // Pass 1 — the parts already standing: hide-by-despawn, or re-point.
+        // Pass 1, the standing parts: despawn if hidden, else re-point.
         let mut present = vec![false; parts.len()];
         let (mut hidden, mut repointed) = (0usize, 0usize);
         for child in children.iter() {
@@ -217,7 +178,7 @@ pub(in crate::entities) fn redress_player_looks(
             };
             let dp = *dp;
             let Some(part) = parts.get(dp.index as usize) else {
-                continue; // a stale index (the model rebuilt under us) — leave it to the teardown
+                continue; // a stale index: the teardown handles it
             };
             let standing_members: &[u32] = match group {
                 Some(g) => &g.0,
@@ -227,8 +188,7 @@ pub(in crate::entities) fn redress_player_looks(
                 .get(&dp.index)
                 .is_some_and(|g| g.members == standing_members);
             if !shows(part.geoset_id) || !still_grouped {
-                // A billboard batch's card is a world ROOT following this anchor's joint, so it does
-                // not cascade — reap it by name (decision 0153's lifecycle, [`DressedPart::card`]).
+                // A billboard card is a world root, so it is reaped by name.
                 if let Some(card) = dp.card {
                     if let Ok(mut ec) = commands.get_entity(card) {
                         ec.despawn();
@@ -241,8 +201,7 @@ pub(in crate::entities) fn redress_player_looks(
             for &m in standing_members {
                 present[m as usize] = true;
             }
-            // A card's material is the model's own batch material — never a character slot — so a
-            // billboard part has nothing to re-point.
+            // A billboard batch is never a character slot, so it has nothing to re-point.
             if part.billboard.is_none() {
                 repoint_part(
                     part,
@@ -254,12 +213,8 @@ pub(in crate::entities) fn redress_player_looks(
             }
         }
 
-        // Pass 2 — the batches the new gear reveals. They join the unit's own appear-fade clock if
-        // one is still in flight (the login gear cascade lands mid-ramp), exactly as a
-        // late-resolving held item does — never a second ramp of their own, never a pop.
-        //
-        // A revealed billboard batch's card bone resolves its anchor first (decision 1355), over
-        // exactly the parts the spawn loop below will dress.
+        // Pass 2, the revealed batches, which join the unit's appear-fade if one is in flight (the
+        // login gear cascade lands mid-ramp). Their card bones resolve anchors first.
         let card_anchors: std::collections::HashMap<u16, Entity> = match pose.as_mut() {
             Some(p) => parts
                 .iter()
@@ -309,12 +264,7 @@ pub(in crate::entities) fn redress_player_looks(
             );
             shown += 1;
         }
-        // One line per re-dress — a handful per session, and the only readout of a mechanism whose
-        // whole point is that nothing else moves. `atlas` is the composited body material's id: it
-        // must CHANGE when the worn set changes a body region, which is what says the re-composite
-        // reached the parts rather than merely being built. The counts say which batches the new
-        // gear hid and revealed. Nothing about the unit's attachments appears here because this
-        // system cannot touch them.
+        // `atlas` must change when the worn set changes a body region.
         info!(
             "redress: {entity} — {hidden} batch(es) hidden, {shown} shown, {repointed} re-pointed, \
              atlas {:?}",
@@ -323,24 +273,16 @@ pub(in crate::entities) fn redress_player_looks(
     }
 }
 
-/// Re-point one standing part at the freshly-built material set its unit now wears.
-///
-/// The three records are updated whatever the part is doing, because each is read by a *different*
-/// owner at a different moment: the interior classifier resolves the law's steady material, the fade
-/// ramps resolve their twin every frame from [`FadeMaterials`] + the law, and the portrait booths
-/// mirror the steady one whenever a booth rebuilds. The **displayed** material is only written when
-/// no ramp owns that channel — a part mid-appear-fade wears its blend twin, and
-/// [`benilla_world::model_fade::apply_render_fade`] re-resolves it from the two records above on its next
-/// tick, so writing the steady handle here would flash it opaque for a frame.
+/// Re-point one standing part at its unit's new materials. The records always update; the
+/// displayed material only when no fade ramp owns it, since `apply_render_fade` re-resolves a
+/// ramping part from the records and a steady write would flash it opaque for a frame.
 fn repoint_part(
     part: &EntityPart,
     char_mats: &CharSkinMaterials,
     (mat, lit, fade_mats, portrait): PartWrites,
     fading: bool,
 ) {
-    // A batch with no character texture slot draws its shared model's own built materials, which no
-    // amount of gear can change — the body atlas, the hair, the cape and the extra skin are the
-    // whole of what a re-dress can touch.
+    // Gear changes only the character slots' textures.
     if part.char_slot.is_none() {
         return;
     }
@@ -366,9 +308,7 @@ fn repoint_part(
     }
 }
 
-/// The armed idle's authored CAaBox — the mouseover picker's volume for a skinned part (decision
-/// 0637). Same read as the first build's; see the note there for why the bind box is not a fair
-/// stand-in.
+/// The armed idle's authored CAaBox, the picker's volume for a skinned part, read as at build.
 fn idle_aabb(dm: &super::super::DisplayModel) -> Option<bevy::camera::primitives::Aabb> {
     let anims = dm.animations.as_ref()?;
     let clip = anims.first_seq.and_then(|i| anims.clips.get(i))?;
@@ -388,10 +328,7 @@ mod tests {
 
     /// One synthetic body batch at `geoset`.
     fn part(geoset: u16) -> EntityPart {
-        // A DISTINCT material per stub batch: every real batch of a model has its own built
-        // material unless it shares a texture, and a fixture whose batches all bound the one
-        // default handle would merge into a single group (`merge`) and stop being the
-        // per-batch hide/show/re-point walk these tests are about.
+        // A distinct material per batch, or the fixture would merge into one group (`merge`).
         static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
         let n = NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
         EntityPart {
@@ -425,9 +362,7 @@ mod tests {
         }
     }
 
-    /// A player standing fully dressed: the display model behind it, the resource set the re-dress
-    /// reads, and — the point of the whole change — a bone anchor with a held item hanging off it,
-    /// exactly where a weapon and its enchant glow live.
+    /// A dressed player with a bone anchor and a held item hanging off it.
     struct Standing {
         app: App,
         player: Entity,
@@ -435,9 +370,8 @@ mod tests {
         held: Entity,
     }
 
-    /// Build one. `geosets` are the model's batches in order; `showing` the batch indices already
-    /// spawned as children (what the first build selected); `characters` the geoset tables (absent ⇒
-    /// no filter at all, the druid-form / beast-display arm).
+    /// `geosets` are the model's batches, `showing` the indices already spawned, `characters` the
+    /// geoset tables (absent: no filter).
     fn stand(geosets: &[u16], showing: &[usize], characters: Option<CharacterGeosets>) -> Standing {
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, AssetPlugin::default()))
@@ -446,19 +380,16 @@ mod tests {
             .init_asset::<WowModelMaterial>()
             .init_resource::<SkinComposites>()
             .init_resource::<MergedFormsCache>()
-            // The engine's material cache — normally `model_render::plugin`'s, which this bare
-            // harness does not install.
+            // Normally `model_render::plugin`'s.
             .init_resource::<benilla_world::model_render::ModelMaterials>()
-            // The animated-material lane the dressing path now takes (2295) — never exercised by
-            // a re-dress, which is a player's gear change, but the system asks for it.
+            // The own-material lane the system takes, which a re-dress never uses.
             .init_resource::<benilla_world::doodad_anim::UvAnimMaterials>()
             .init_resource::<benilla_world::doodad_anim::TintAnimMaterials>()
             .init_resource::<benilla_world::mat_anim_table::MatAnimTable>();
 
         let mut dm = empty_display();
         dm.parts = Some(geosets.iter().map(|g| part(*g)).collect());
-        // The look comes off the DISPLAY here (a character-model NPC row), which is the same
-        // `CharLook` the wire path builds — and needs no `ObjectStore` to stand one up.
+        // A look off the display (an NPC row) needs no `ObjectStore`.
         dm.npc_appearance = Some(NpcAppearance {
             race: 1,
             sex: 0,
@@ -474,8 +405,7 @@ mod tests {
             catalog: Default::default(),
             models: HashMap::from([(42u32, dm)]),
         });
-        // Display 7 = a pair of gloves whose `geosetGroup[0]` is 1 (→ geoset 402, the glove group's
-        // own range disabled).
+        // Display 7: gloves whose `geosetGroup[0]` is 1, selecting geoset 402.
         app.insert_resource(ItemDisplays::icons_for_tests(
             ItemDisplayCatalog::from_displays(HashMap::from([(
                 7u32,
@@ -510,8 +440,7 @@ mod tests {
                 Visibility::default(),
             ))
             .id();
-        // The rig's bone anchor and the item hanging off it — the weapon root a gear change used to
-        // take with it.
+        // A bone anchor and the item hanging off it.
         let joint = app
             .world_mut()
             .spawn((Transform::default(), Visibility::default(), ChildOf(player)))
@@ -571,10 +500,7 @@ mod tests {
         }
     }
 
-    /// **The director's report.** A gear change used to `despawn_related::<Children>()` the whole
-    /// visual, taking both weapons, their enchant glows, the helm, the shoulders and every aura
-    /// visual with it — everything hanging off a bone was destroyed and re-created because a belt
-    /// changed. Nothing on the unit but its own body batches may be touched.
+    /// A gear change touches nothing on the unit but its own body batches.
     #[test]
     fn a_gear_change_leaves_the_rig_and_every_attachment_standing() {
         let mut s = stand(&[0, 401], &[0, 1], None);
@@ -597,8 +523,7 @@ mod tests {
         );
     }
 
-    /// …and the diff is stamped, so the re-dress fires **once** per change rather than every frame
-    /// (the composite behind it is a synchronous BLP read on a miss).
+    /// The re-dress fires once per change: the composite behind it reads BLPs synchronously.
     #[test]
     fn a_gear_change_restamps_what_the_visual_is_dressed_with() {
         let mut s = stand(&[0], &[0], None);
@@ -614,11 +539,8 @@ mod tests {
         );
     }
 
-    /// The **geoset half**, against the shipped customization tables: putting gloves on replaces the
-    /// glove group — the naked 401 batch stops drawing and the item's 402 batch starts — and that
-    /// now happens by despawning/spawning exactly those two batches instead of rebuilding the unit.
-    /// (The reference flips two entries of the model's own visibility array; the visible result is
-    /// the same set, which is what this pins.)
+    /// Against the shipped tables: gloves hide the bare-hand 401 batch and show the item's 402, by
+    /// despawning and spawning just those two, the reference's two visibility-array flips.
     #[test]
     fn worn_gloves_replace_the_glove_geoset_in_place() {
         let data = benilla_formats::wow_data_or_skip!();
diff --git a/crates/benilla-app/src/entities/carried_light.rs b/crates/benilla-app/src/entities/carried_light.rs
index 026927e4..eac7b92d 100644
--- a/crates/benilla-app/src/entities/carried_light.rs
+++ b/crates/benilla-app/src/entities/carried_light.rs
@@ -1,26 +1,8 @@
-//! **Carried M2 lights** — the dynamic point lights an *entity* brings into the world, as opposed to
-//! the ones a placed ADT doodad / WMO prop brings (`benilla_world::terrain_stream`'s `spawn_lights_for`).
-//!
-//! The law is one law. `0x718960` runs per frame over **every** CM2Model the scene draws — a placed
-//! doodad, a creature, a GameObject, and (recursing at `7191b9`/`719286`) each attached child model —
-//! gathers that model's own `type==1` light blocks, transforms each def position by its **live bone
-//! matrix**, and registers the result into the world scene's light DB (`0x71b650` → `0x71bb60`). Every
-//! lit surface then selects its ≤3 nearest from that same DB (decisions 0016/0273/0285). Nothing in the
-//! chain distinguishes "prop" from "unit": a torch is a torch whether it is staked in the ground or
-//! held in a hand.
-//!
-//! benilla had implemented only the placed half, so a torch-bearing NPC carried a flame that lit
-//! nothing — the director's report from Westfall (Remy "Two Times", whose `Club_1H_Torch_A_01.m2`
-//! authors exactly one warm point light) is the reference doing the other half: the fence rails and
-//! the grass around him light up.
-//!
-//! **The bone ride is the whole reason this isn't just the placed spawner again.** A placed prop's
-//! light bone never moves, so the rest pose is exact and the light can be baked to a world point. An
-//! entity's does move — the hand swings — so each light is spawned as a **child of its host bone's
-//! joint entity** with the def position rebased into that bone's frame (`position − bone_pivot`),
-//! exactly as the emitters and ribbons ride (0130 phase 4). Bevy's transform propagation then walks
-//! the light through the animation for free, and the per-frame light packer
-//! ([`benilla_world::lighting`]) reads its `GlobalTransform` like any other point light.
+//! Carried M2 lights: the point lights an entity's models bring, beside the placed ones
+//! (`benilla_world::terrain_stream`'s `spawn_lights_for`). The reference makes no distinction:
+//! `0x718960` gathers every drawn model's `type == 1` lights each frame, attached children included
+//! (`0x7191b9`, `0x719286`), at the live bone matrix into the one scene light DB (`0x71b650`,
+//! `0x71bb60`), so a held torch lights the ground. Each light here rides its host bone's joint.
 
 use benilla_assets::coords::wow_to_bevy;
 use benilla_assets::ModelLight;
@@ -28,17 +10,10 @@ use bevy::prelude::*;
 
 use benilla_world::terrain_stream::point_light;
 
-/// Spawn a `PointLight` child for each **casting** (`type==1`, not visibility-gated dark) M2 light of
-/// an entity's model.
-///
-/// `joint` resolves a light's host bone index to the instance's live joint entity — `None` for a
-/// boneless/skeleton-less instance (a held item spawns no skeleton; its `root` already *is* the
-/// item's model frame), a `-1` bone, or a bone the instance doesn't carry. A light with a joint rides
-/// it in bone-local space; a light without one hangs off `frame` in plain model space, which is the
-/// exact rest-pose special case.
-///
-/// Children, not free entities: the light's lifecycle and its frame both come from the hierarchy, so
-/// a gear change, a despawn, or a mount transition takes its lights with it.
+/// Spawn a point light child for each casting M2 light of an entity's model. A light whose bone
+/// `joint` resolves rides that joint at `position − bone_pivot`; one without (a held item has no
+/// skeleton, a `-1` bone) hangs off `frame` in model space. As children, the lights leave with a
+/// gear change, a despawn or a mount transition.
 pub(super) fn spawn_carried_lights(
     commands: &mut Commands,
     lights: &[ModelLight],
@@ -95,12 +70,8 @@ mod tests {
         }
     }
 
-    /// GOLDEN — the carried-light spawn law. Only a **casting** light spawns (`type==1`, not held
-    /// 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`
-    /// round trip the packer inverts (`intensity/4π`).
+    /// Only casting lights spawn (the gather's gate in `0x718960`), each a child of its bone's
+    /// joint at `position − bone_pivot`; colour × intensity survives the packer's `intensity / 4π`.
     #[test]
     fn only_casting_lights_spawn_and_they_ride_their_bone() {
         let mut app = App::new();
@@ -131,7 +102,7 @@ mod tests {
             .iter(app.world())
             .map(|(e, _, t, c)| (e, t.translation, c.parent()))
             .collect();
-        // Spawn order, i.e. light-table order — `Entity`'s own `Ord` is not index-ascending.
+        // Spawn order, i.e. light-table order: `Entity`'s own `Ord` is not index-ascending.
         spawned.sort_by_key(|(e, ..)| e.index());
         assert_eq!(
             spawned.len(),
@@ -139,11 +110,9 @@ mod tests {
             "the directional and the dark one stay out"
         );
 
-        // Bone-ridden: parented to the joint, offset rebased into the bone frame.
         assert_eq!(spawned[0].2, joint);
         assert_eq!(spawned[0].1, wow_to_bevy([1.0, 0.0, 1.0]));
-        // Boneless (`-1`): hangs off the frame at plain model-space position — the rest-pose case
-        // a held item always takes (it spawns no skeleton).
+        // Boneless: off the frame in model space, as a held item's light always is.
         assert_eq!(spawned[1].2, frame);
         assert_eq!(spawned[1].1, wow_to_bevy([0.0, 0.0, 4.0]));
 
diff --git a/crates/benilla-app/src/entities/chain_beam.rs b/crates/benilla-app/src/entities/chain_beam.rs
index 9cc1b51b..3ade9048 100644
--- a/crates/benilla-app/src/entities/chain_beam.rs
+++ b/crates/benilla-app/src/entities/chain_beam.rs
@@ -1,77 +1,23 @@
-//! Spell **chain beams** — Chain Lightning's arcs, Drain Life's rope of soul, Mind Flay's mana
-//! beam, Chain Heal's arc, C'Thun's eye beam (decision 0955, slice 2: the renderer).
+//! Spell chain beams: Chain Lightning's arcs, the Drain Life and Mind Flay beams, Chain Heal. A kit
+//! whose `CharProc` decodes to a chain ([`benilla_formats::ChainProc`]) draws a polyline of hops,
+//! `caster → t1 → t2 → …`, one ribbon per hop, subdivided, jittered every frame and scrolled: the
+//! reference's `LightningObject` (`0x6ec460`) and `CLightning` (`0x7af9b0`/`0x7afcb0`).
 //!
-//! 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.
+//! Hop `i` burns in `[t0 + i × stagger, + life)` (`0x6ec980`), so a 3-hop cast arcs outward, and
+//! the beam expires at `t0 + hops × life`. `ChainProc::flag`, the decoded `CharParamTwo`, is the
+//! whole cast/channel split: set, both are bypassed and the beam lives until swept by
+//! `LightningObject::Stop` (`0x6ece10`), whose one caller is the channel teardown.
 //!
-//! ## What the reference does, and what this transcribes
+//! Endpoints are identities re-resolved from the live units every frame (`0x6ec460`), so a beam
+//! tracks moving units, and a hop whose unit does not resolve is hidden, not re-pathed.
 //!
-//! **The hop list is unit state, not packet state.** The reference parks it on the caster (the
-//! growable array at `unit+0xd44`) — [`ChainHops`] here — filled by **two** producers, `SMSG_SPELL_GO`'s
-//! hit list (`0x6e800d`) and `SMSG_SPELL_UPDATE_CHAIN_TARGETS` (`0x605767`), both dropping the
-//! caster's own guid, and **consumed exactly once** by the next chain proc (`0x60db72` zeroes the
-//! count on every exit path, including the ones that draw nothing).
+//! Render state (`0x7afcb0`, through the `EGxRs` applicator `0x59d350`): additive `SRC_ALPHA/ONE`,
+//! emissive white and never tinted, two-sided, depth-write off, fog off, drawn on the shared
+//! effect-quad stream ([`benilla_world::particles::buffer::EffectQuads`]).
 //!
-//! **Target selection** (`0x60dad4`–`0x60db19`): when the playing kit's spell **is** the unit's
-//! `UNIT_CHANNEL_SPELL`, its `UNIT_FIELD_CHANNEL_OBJECT` is set, and the hop count is `<= 1`, the
-//! beam runs to that single channel object; otherwise it runs the hop array, and an **empty array
-//! draws nothing at all**.
-//!
-//! **Per hop** (`Bolt[i] = (i, i+1)`, `0x6ec980`): a window `[t0 + i × stagger, + life)` — so a
-//! 3-hop Chain Lightning arcs *outward* — and the whole beam expires at `t0 + hops × life`. The
-//! **flag** ([`ChainProc::flag`], the decoded `CharParamTwo`) is the entire cast/channel split: with
-//! it set, the per-hop window and the expiry are both bypassed and the beam lives until swept
-//! (`LightningObject::Stop 0x6ece10`, whose one caller image-wide is the channel teardown).
-//!
-//! **Endpoints are identities, re-resolved from the live units every frame** (`0x6ec460` runs both
-//! through `ClntObjMgr` each tick), so a beam tracks a moving caster and a moving target; a hop
-//! whose unit is not resolvable is *hidden*, not re-pathed. The caster's end anchors at its `$CSL`
-//! marker, else `base + 0.75 × modelHeight × modelScale` (`0x6ec6f0`); every other endpoint anchors
-//! at the M2 attachment named by the spell's own `SpellVisual` field 9 — the same ordinal the
-//! missile homes to — with 34 as the fallback and the unit's base below that (`0x6ec780`).
-//!
-//! **Geometry per hop** (`0x7af6d0`), all VERIFIED:
-//! - `n = trunc(len / avgSegLen + 2.0)` sub-segments, `n+1` points, `point[i] = lerp(a, b, i/n)`;
-//!   the `+2` is a floor, so even a one-yard hop bends.
-//! - each interior point takes an independent 3-vector in `[−1, 1]³` scaled by `len × noiseScale`,
-//!   **re-rolled every frame**, and the live polyline advects toward it `0.75` old / `0.25` new.
-//! - the ribbon's cross-section is `(−d.y, d.x, 0)` taken **in EYE space**, not world space: the
-//!   strip is built from points already run through the world→eye transform (`0x7bca80` against
-//!   `0xcf5800 = T(−cameraPos)·VIEW`, assembled at `0x7affb1`–`0x7b00c4`; `VIEW` is the device's
-//!   slot-10 matrix, whose producer `0x50ab70` is `LookAt(eye = origin, …)` — **pure rotation, zero
-//!   translation row**, which is why the pre-translate is not a double translate). Eye axes are X
-//!   right, Y up, **+Z into the screen**, so the formula is the *screen*-plane 90° rotation and the
-//!   ribbon is **view-plane aligned**. In world axes it is `normalize(d × camForward)` — the same
-//!   vector, and the same magnitude, so the reference's `0.001` guard transfers unchanged. The
-//!   transform is an isometry with no projection (`0x7bca80` is row-vector affine, no w-divide) and
-//!   both the WORLD and VIEW slots are identity at the submit, so the strip is drawn in eye space
-//!   and the width stays **`2 × field2` world yards at any distance**. Decision 1653 corrects 0964,
-//!   which read the formula as world-space and drew every beam as a horizontal slab — a hairline
-//!   from any camera near the beam's own plane.
-//! - an interior vertex sits at `p ± 0.5·(perp₍ᵢ₋₁₎ + perpᵢ)·halfWidth`; **both ends collapse to a
-//!   point** with `v = 0.5` — the beam is a spindle, tapered at caster and target.
-//! - `u` runs `0 → 1` caster→target, translated by `−(phase / period)` where
-//!   `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 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
-//! conversion, same commit).
-//!
-//! **Named approximations.** (a) The strand count (`CharParamOne`, ≤ 3 — only Chain Burn ships > 1)
-//! is modelled as N independently-jittered copies of one polyline: the reference builds them from
-//! 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 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.
-//! (d) A beam takes no owner-last draw rung and no water-plane interleave: it belongs to no model.
+//! Strands (`CharParamOne`, at most 3, more than one only on Chain Burn) are independently jittered
+//! copies of one polyline; the reference builds them from identical arguments and they diverge only
+//! through their interleaved draws on one shared PRNG.
 
 use benilla_formats::{ChainEffect, MISSILE_ATTACH_TABLE};
 use bevy::prelude::*;
@@ -83,114 +29,97 @@ use benilla_world::view::WorldCamera;
 
 use super::OverheadFallback;
 
-/// The caster-end anchor's height factor when the model has no `$CSL` marker: the reference's
-/// `base + (0, 0, modelHeight × modelScale × 0.75)` (`0x6ec73e`–`0x6ec771`, the `0.75f` at
-/// `0x8012cc`). Our stand-in for `obj+0x90` is the model's authored bbox z-extent — the same
-/// "model height" the overhead-anchor fallback reads ([`OverheadFallback`]).
+/// The caster end's height factor with no `$CSL` marker, `base + modelHeight × modelScale × 0.75`
+/// (`0x6ec73e`–`0x6ec771`, the `0.75f` at `0x8012cc`). The height is the authored bbox z-extent
+/// that [`OverheadFallback`] carries, standing in for the reference's `obj+0x90`.
 const CASTER_HEIGHT_FACTOR: f32 = 0.75;
 
-/// The attachment every non-caster endpoint falls back to when the spell's `SpellVisual` field 9
-/// names no usable one — the reference's literal `0x22` (`0x6ec7b5`–`0x6ec7c7`). Below it, the
-/// unit's own position (which is what [`attach_world_pos`] already degrades to).
+/// The attachment a non-caster end falls back to when the spell's `SpellVisual` field 9 names
+/// none, the reference's literal `0x22` (`0x6ec7b5`–`0x6ec7c7`); below it, the unit's position.
 const CHAIN_ATTACH_FALLBACK: u16 = 34;
 
-/// The subdivision floor's constant (`fadd [0x801628] = 2.0f` @ `0x7af716`): `n = trunc(len/avg + 2)`.
+/// The subdivision floor, the `2.0f` at `0x801628` added at `0x7af716`: even a one-yard hop bends.
 const SUBDIVISION_FLOOR: f32 = 2.0;
 
-/// The normalisation guard on the cross-section vector (`fcom [0x801360]` @ `0x7b01bd`, strictly
-/// `>`): a perpendicular shorter than this is left **un-normalized**, collapsing that segment's
-/// width. The length it measures is the segment's *screen*-plane projection, so what it guards is a
-/// hop aimed at the camera — not one aimed at the sky, which is what 0964 believed.
-///
-/// It is a **numerical guard, not a visible behaviour**: because everything above it is normalized
-/// to full width, the pinch cone is `arcsin(0.001 / |d|)` — about `0.023°` for the ~2.5 yd
-/// sub-segments a 30 yd link subdivides into, and `noiseScale`'s per-frame re-roll walks the
-/// segment out of it. A beam does **not** thin as you turn to look down its length; it holds its
-/// width and then, at an angle no player can hold, degenerates instead of producing a NaN.
+/// The cross-section normalisation guard (`fcom [0x801360]` at `0x7b01bd`, strictly `>`): a
+/// shorter perpendicular stays un-normalized and collapses that segment's width. It measures the
+/// screen-plane projection, so it pinches only a hop aimed at the camera, within about 0.023° on a
+/// 2.5 yd sub-segment: a guard against NaN, not a visible thinning.
 const PERP_EPSILON: f32 = 0.001;
 
-/// The per-frame advection weight on the live polyline (`0x7afc10`/`0x7afc38`):
-/// `main = 0.75·main + 0.25·fresh`, interior points only.
+/// The per-frame advection weight on interior points, `main = 0.75·main + 0.25·fresh`
+/// (`0x7afc10`/`0x7afc38`), which makes the per-frame re-roll crawl rather than strobe.
 const ADVECT_KEEP: f32 = 0.75;
 
-/// A backstop on one hop's sub-segment count — the reference has none (it trusts the table), but a
-/// long hop against a small `avgSegLen` would otherwise size a vertex run off table data. The
-/// shipped worst case is far below this: 30 yd at `avgSegLen` 2.78 is 12.
+/// Deviation: a cap on one hop's sub-segment count, which the reference lacks, so a vertex run is
+/// never sized off table data alone; shipped rows peak at 12 (30 yd at `avgSegLen` 2.78).
 const MAX_SUBDIVISIONS: usize = 256;
 
-/// The caster's chain-target **hop array** — the reference's growable `unit+0xd44`
-/// (`{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::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
-/// endpoint we cannot place would be invisible anyway (the reference hides such a hop too).
+/// The caster's chain-target hop array, the reference's growable `unit+0xd44`: guids in wire
+/// order, the caster's own dropped as it fills (`0x6057bf`/`0x6057c9`). `crate::spell::net` fills
+/// it from the `SMSG_SPELL_GO` hit list (`0x6e800d`) and `SMSG_SPELL_UPDATE_CHAIN_TARGETS`
+/// (`0x605767`), clearing before each fill, and [`spawn_chain_beams`] consumes it once, as
+/// `0x60db72` zeroes the count on every exit. The reference gates the `SMSG_SPELL_GO` fill on
+/// `0x6e4870`, a predicate still untraced; here it always fills. Unstreamed targets are left out,
+/// as the reference hides a hop it cannot place.
 #[derive(Component)]
 pub(crate) struct ChainHops(pub(crate) Vec<Entity>);
 
-/// One hop of a live beam — the reference's 16-byte `Bolt`, whose `idxA`/`idxB` are always
+/// One hop of a live beam, the reference's 16-byte `Bolt`, whose `idxA`/`idxB` are always
 /// `(i, i+1)` into the node list.
 struct Bolt {
-    /// Absolute scene seconds — `t0 + i × boltStagger` (`0x6ec9d7`–`0x6ec9e8`). Ignored while the
-    /// beam is persistent (`0x6ec520` bypasses the window on the flag).
+    /// `t0 + i × boltStagger` in scene seconds (`0x6ec9d7`–`0x6ec9e8`).
     start: f32,
-    /// `start + boltLife` (`0x6ec9eb`). Ignored while persistent.
+    /// `start + boltLife` (`0x6ec9eb`).
     end: f32,
-    /// The live jittered polyline, one per strand — the reference's per-`CLightning` point array,
-    /// advected rather than rebuilt so the jitter reads as motion instead of noise. Empty until the
-    /// hop's first drawn frame (and cleared whenever its subdivision count changes).
+    /// The live jittered polyline per strand, advected rather than rebuilt; empty while the hop is
+    /// not drawn.
     strands: Vec<Vec<Vec3>>,
 }
 
-/// A live chain beam — the reference's 0x50-byte `LightningObject`.
+/// A live chain beam, the reference's 0x50-byte `LightningObject`.
 #[derive(Component)]
 pub(crate) struct ChainBeam {
-    /// The spell that drew it — the reap's key (`node+0x44`).
+    /// The reap key (`node+0x44`).
     spell_id: u32,
-    /// The unit it hangs off. Its loss ends the beam: nothing else would ever reap a persistent one.
+    /// Its loss ends the beam; nothing else would reap a persistent one.
     caster: Entity,
-    /// `[caster, hop0, hop1, …]` — **identities**, re-resolved every frame (`node+0x10`, the guid
-    /// array). The participant set never changes; a beam does not re-target.
+    /// `[caster, hop0, hop1, …]` as identities re-resolved every frame (`node+0x10`); a beam never
+    /// re-targets.
     nodes: Vec<Entity>,
     bolts: Vec<Bolt>,
     effect: ChainEffect,
     texture: Handle<Image>,
-    /// The M2 attachment every non-caster endpoint anchors at, resolved once from the spell's own
-    /// `SpellVisual` field 9 (the reference resolves it per frame; the row cannot change).
+    /// The attachment every non-caster endpoint anchors at, from the spell's `SpellVisual` field 9,
+    /// resolved once where the reference re-reads the unchanging row every frame.
     dest_tag: u16,
-    /// The decoded `CharParamTwo`: a **channel** beam, which never expires by time (`node+0x48`).
+    /// The decoded `CharParamTwo`: a channel beam, which never expires by time (`node+0x48`).
     persistent: bool,
-    /// `t0 + hops × boltLife` (`0x6ecd30`). Ignored while [`Self::persistent`].
+    /// `t0 + hops × boltLife` (`0x6ecd30`); ignored while [`Self::persistent`].
     expiry: f32,
-    /// The texture-scroll accumulator, seconds (`node`-side `+0x60`): `fmod(phase + dt, period)`.
+    /// The texture-scroll accumulator in seconds (`+0x60`).
     phase: f32,
     rng: u32,
 }
 
-/// `Textures\SpellChainEffects\Lightning.blp` → its `mpq://` load URL (the lowercase/forward-slash
-/// form every other BLP load in the client uses).
+/// The DBC's backslash path as the lowercase, forward-slash `mpq://` URL every BLP load uses.
 fn beam_texture_url(raw: &str) -> String {
     format!("mpq://{}", raw.to_ascii_lowercase().replace('\\', "/"))
 }
 
-/// One xorshift draw in `[−1, 1)` — our stand-in for the reference's `((rand & 0x7fffff) |
-/// 0x3f800000)` mantissa trick re-centred through the same `2.0`. Same distribution, different
-/// generator: the beam's look rests on the *amplitude* (`len × noiseScale`) and the 0.75/0.25
-/// advection, both exact, never on the reference's draw sequence.
+/// One xorshift draw in `[−1, 1)`. Deviation: not the reference's generator
+/// (`((rand & 0x7fffff) | 0x3f800000)` re-centred through `2.0`), because the look rests on the
+/// amplitude and the advection, both exact, never on the draw sequence.
 fn jitter(rng: &mut u32) -> f32 {
     *rng ^= *rng << 13;
     *rng ^= *rng >> 17;
     *rng ^= *rng << 5;
-    // The top 24 bits as [0,1), doubled and re-centred — the reference's own [1,2)→[−1,1) shape.
     (*rng >> 8) as f32 / (1u32 << 24) as f32 * 2.0 - 1.0
 }
 
-/// The **caster's** end (`0x6ec6f0`): the `$CSL` marker at the live pose, else
-/// `base + 0.75 × modelHeight × modelScale`. `None` only when the caster is gone. Every *other*
-/// endpoint goes through the missile lane's attachment resolver instead — `0x6ec780` and
-/// `0x61ceb0` read the same table the same way.
+/// The caster's end (`0x6ec6f0`): the `$CSL` marker at the live pose, else
+/// `base + 0.75 × modelHeight × modelScale`. Other ends anchor at the spell's field-9 attachment
+/// through the missile's resolver, as `0x6ec780` and `0x61ceb0` read the same table the same way.
 fn caster_world_pos(
     caster: Entity,
     units: &super::missile::AttachPosQuery,
@@ -209,10 +138,9 @@ fn caster_world_pos(
     }))
 }
 
-/// The kit's chain proc → the beam's participants, the reference's selection exactly
-/// (`0x60dad4`–`0x60db19`): the channel object when the kit's spell **is** the live channel, that
-/// channel names an object, and the hop array holds at most one entry; else the hop array; else
-/// nothing at all.
+/// The beam's participants (`0x60dad4`–`0x60db19`): the channel object when the kit's spell is the
+/// live channel, it names an object and the hop array holds at most one entry; else the hop array;
+/// else nothing.
 fn select_targets(
     spell_id: u32,
     hops: Option<&ChainHops>,
@@ -223,21 +151,20 @@ fn select_targets(
     let channelling = spell_id != 0 && store.0.unit_channel_spell() == spell_id;
     if channelling && hops.len() <= 1 {
         if let Some(object) = store.0.unit_channel_object().filter(|g| *g != 0) {
-            // `count = 1, ptr = descriptor+0x38` — the single-target path. A channel object we
-            // haven't streamed leaves the beam with nothing to run to, like a hidden hop.
+            // The single-target path (`count = 1, ptr = descriptor+0x38`); an unstreamed channel
+            // object leaves nothing to run to, like a hidden hop.
             return index.0.get(&object).copied().into_iter().collect();
         }
     }
     hops.to_vec()
 }
 
-/// Spawn/replace/reap the beam entities: the CharProc dispatcher's beam case, ECS-side.
-///
-/// Reaps run **before** plays so a GO's own spell-id-keyed reap (which precedes its cast-kit play in
-/// the router) never eats the beam that play is about to draw. Only **persistent** beams are
-/// reapable: the reference only ever publishes a flagged node to the owner slots that the channel
-/// teardown sweeps (`0x6ecdaa` gates the AddRef on the flag), so a one-shot beam always runs its own
-/// clock to the end.
+/// The CharProc dispatcher's beam case: spawns, replaces and reaps beams. Reaps run before plays,
+/// so a GO's spell-keyed reap, which precedes its cast-kit play in the router, never eats the beam
+/// that play draws. Only a persistent beam is reapable: the reference publishes only a flagged node
+/// to the owner slots the channel teardown sweeps (`0x6ecdaa`), so a one-shot runs its own clock.
+/// The reference re-enters the dispatcher every channel tick (`0x612b18`); one held beam shows the
+/// same steady beam, ending with the channel.
 pub(super) fn spawn_chain_beams(
     mut commands: Commands,
     time: Res<Time>,
@@ -249,10 +176,8 @@ pub(super) fn spawn_chain_beams(
     index: Res<GuidIndex>,
     stores: Query<(&crate::net::ObjectStore, Option<&ChainHops>)>,
     beams: Query<(Entity, &ChainBeam)>,
-    // The removal below is deferred to the next sync point, so a SECOND play on the same caster
-    // this frame (a cast kit and an impact kit, an auto-repeat's twin GO) would still see the
-    // array through the query. The reference zeroes the count in-place, mid-dispatch — this
-    // overlay is that, and it is the same shape as the router's own `pending` hold overlay.
+    // The removal below lands at the next sync point, so a second play on the same caster this
+    // frame would still see the array; this set is the reference's in-place zeroing.
     mut consumed: Local<bevy::ecs::entity::EntityHashSet>,
 ) {
     consumed.clear();
@@ -274,16 +199,15 @@ pub(super) fn spawn_chain_beams(
 
     let now = time.elapsed_secs();
     for play in plays.read() {
-        // The caster may have died inside the same wire drain that produced this play (the router's
-        // own law) — and a beam is entirely *about* that unit.
+        // The caster may be gone within the same wire drain that produced this play.
         let Ok((store, hops)) = stores.get(play.entity) else {
             continue;
         };
-        // Consume once, on every path — `0x60db72` zeroes the count even when nothing is drawn.
+        // Consume once, on every path: `0x60db72` zeroes the count even when nothing is drawn.
         let hops = hops.filter(|_| !consumed.contains(&play.entity));
         consumed.insert(play.entity);
         commands.entity(play.entity).try_remove::<ChainHops>();
-        // `0x6ecbd0`'s own guards: no spell, no strands, no targets ⇒ silent return.
+        // `0x6ecbd0`'s guards: no spell, no strands or no targets is a silent return.
         let targets = select_targets(play.spell_id, hops, store, &index);
         if play.spell_id == 0 || play.proc.beams == 0 || targets.is_empty() {
             continue;
@@ -294,16 +218,15 @@ pub(super) fn spawn_chain_beams(
         let Some(effect) = visuals.0.chain_effect(play.proc.effect_id).cloned() else {
             continue; // an id naming no row is the client's own no-op (`0x6ecc2e`)
         };
-        // `0x6ec780`: the spell's OWN visual row, field 9's ordinal through the missile table —
-        // no ranged fallback (that belongs to the kit resolve, not to this one).
+        // `0x6ec780`: the spell's own visual row, field 9 through the missile table, with no
+        // ranged fallback.
         let dest_tag = spells
             .catalog
             .get(play.spell_id)
             .and_then(|d| visuals.0.stages(d.visual))
             .and_then(|s| MISSILE_ATTACH_TABLE.get(s.missile_attach as usize).copied())
             .unwrap_or(CHAIN_ATTACH_FALLBACK);
-        // A replacing persistent beam takes the previous one's place (a channel re-armed on the
-        // same caster+spell), matching the effect-model lane's persistent-Begin law.
+        // A persistent beam replaces the one before it on the same caster and spell.
         if play.proc.flag {
             for (e, beam) in &beams {
                 if beam.persistent && beam.caster == play.entity && beam.spell_id == play.spell_id {
@@ -338,21 +261,16 @@ pub(super) fn spawn_chain_beams(
                 dest_tag,
                 persistent: play.proc.flag,
                 phase: 0.0,
-                // Per-beam seed: one strand per beam would otherwise draw the same jitter as
-                // its neighbour on the same frame (see the module's approximation (a)).
+                // Per-beam seed, so neighbouring beams never draw the same jitter on one frame.
                 rng: 0x9E37_79B9 ^ (play.spell_id.wrapping_mul(2654435761)),
             },
         ));
     }
 }
 
-/// Advance the texture-scroll accumulator and derive the frame's `u` translate — the reference's
-/// two halves (`0x7af9c7` Update, `0x7b0544` Render): `phase = fmod(phase + dt, period)` and
-/// `u = −(phase / period)`, with a zero period disabling the scroll outright.
-///
-/// The **sign** rides through untouched: C `fmod` takes its dividend's sign, so a negative period
-/// still lands the accumulator in `[0, |period|)` and only `u`'s direction flips — which is exactly
-/// why the four drain rows' `−0.5` flows their texture back toward the caster.
+/// The texture scroll (`0x7af9c7` Update, `0x7b0544` Render): `phase = fmod(phase + dt, period)`
+/// and `u = −(phase / period)`; a zero period disables it. `fmod` keeps the dividend's sign, so a
+/// negative period only flips `u`'s direction: the drains' `−0.5` flows back toward the caster.
 fn advance_scroll(phase: f32, dt: f32, period: f32) -> (f32, f32) {
     if period == 0.0 {
         return (0.0, 0.0);
@@ -361,8 +279,9 @@ fn advance_scroll(phase: f32, dt: f32, period: f32) -> (f32, f32) {
     (phase, -(phase / period))
 }
 
-/// One hop's fresh subdivision, jittered — the reference's `0x7af6d0` rebuild, run every frame.
-/// Endpoints are exact; interior points take `len × noiseScale` of independent 3-vector jitter.
+/// One hop's fresh subdivision (`0x7af6d0`, rebuilt every frame): `n = trunc(len / avgSegLen + 2)`
+/// segments, exact endpoints, and each interior point offset by an independent `[−1, 1]³` vector
+/// scaled by `len × noiseScale`.
 fn subdivide(a: Vec3, b: Vec3, effect: &ChainEffect, rng: &mut u32, out: &mut Vec<Vec3>) {
     let len = a.distance(b);
     let n = if effect.avg_seg_len > 0.0 {
@@ -384,20 +303,18 @@ fn subdivide(a: Vec3, b: Vec3, effect: &ChainEffect, rng: &mut u32, out: &mut Ve
     }
 }
 
-/// One strand's polyline, written into the shared stream as a triangle strip expressed in quads
-/// (the ribbon lane's conversion: strip triangles `(t₀,b₀,t₁),(b₀,b₁,t₁)` = quad `[b₀,b₁,t₁,t₀]`).
+/// One strand's polyline into the shared stream, strip triangles `(t₀,b₀,t₁),(b₀,b₁,t₁)` written
+/// as the quad `[b₀,b₁,t₁,t₀]`. Cross-section, ends and texcoords are the reference's
+/// (`0x7b0196`–`0x7b0541`): an interior vertex at `p ± 0.5·(perp₍ᵢ₋₁₎ + perpᵢ)·halfWidth`, both
+/// ends collapsed to a point at `v = 0.5` (a spindle), `u` 0→1 caster→target plus the scroll, and
+/// the constant colour `0xFFFFFFFF`.
 ///
-/// Cross-section, ends and texcoords are the reference's (`0x7b0196`–`0x7b0541`): the **view-plane
-/// aligned** perpendicular, un-normalized below [`PERP_EPSILON`]; an interior vertex at
-/// `p ± 0.5·(perp₍ᵢ₋₁₎ + perpᵢ)·halfWidth`; both ends collapsed to a point at `v = 0.5`; `u`
-/// running 0→1 caster→target plus the scroll translate. The colour is the beam's constant
-/// `0xFFFFFFFF` — emissive white, never tinted.
-///
-/// `cam_forward` is the world camera's unit forward axis (into the screen) — **one axis for the
-/// whole strand**, not a per-point eye ray: the reference's only use of the camera position is the
-/// single pre-translate that builds the world→eye matrix (`0x7affb1`), after which every point
-/// shares one linear map. So the ribbon lies in the view plane and keeps its authored world width
-/// from every angle.
+/// The perpendicular is `(−d.y, d.x, 0)` in eye space: the reference runs the points through
+/// `0x7bca80` against `0xcf5800 = T(−cameraPos)·VIEW` (built at `0x7affb1`–`0x7b00c4`; `VIEW` is
+/// the pure rotation `0x50ab70` builds), an isometry with no projection, and submits with identity
+/// WORLD and VIEW. Eye axes are X right, Y up, +Z into the screen, so the ribbon lies in the view
+/// plane and spans `2 × halfWidth` world yards at any distance; in world axes the perpendicular is
+/// `d × cam_forward`, one axis for the whole strand.
 fn push_strand(
     verts: &mut Vec<EffectVertex>,
     pts: &[Vec3],
@@ -410,12 +327,9 @@ fn push_strand(
         return;
     }
     let seg_perp = |i: usize| -> Vec3 {
-        // `(−d.y, d.x, 0)` on the EYE-space delta is `d × camForward` in world axes: same vector,
-        // same magnitude — `|d|` projected onto the screen plane — so the reference's 0.001 guard
-        // on the raw length transfers unchanged. The order is `d × F`, not `F × d`: the two differ
-        // by a sign, which mirrors `v` across the beam's centreline, and this is the one that puts
-        // the `v = 0` rail on the same side the reference does (eye axes X right / Y up / +Z into
-        // the screen — a beam running rightwards across the screen carries `v = 0` on top).
+        // The eye-space `(−d.y, d.x, 0)` in magnitude too, so the 0.001 guard transfers. `d × F`,
+        // not `F × d`: the other order mirrors `v` across the centreline, and this one puts
+        // `v = 0` on top of a rightward beam, as the reference does.
         let raw = (pts[i + 1] - pts[i]).cross(cam_forward);
         if raw.length() > PERP_EPSILON {
             raw.normalize()
@@ -423,7 +337,7 @@ fn push_strand(
             raw
         }
     };
-    // (top, bottom, v) for point `i` — the collapsed ends share a vertex and stamp v = 0.5.
+    // (top, bottom, v) for point `i`; the collapsed ends share a vertex and stamp v = 0.5.
     let rail = |i: usize| -> (Vec3, Vec3, f32) {
         if i == 0 || i == count - 1 {
             (pts[i], pts[i], 0.5)
@@ -438,7 +352,7 @@ fn push_strand(
     for i in 0..count - 1 {
         let b = rail(i + 1);
         let (ua, ub) = (i as f32 / span + u_scroll, (i + 1) as f32 / span + u_scroll);
-        // v: 0 on the top rail, 1 on the bottom — except at a collapsed end, where both are 0.5.
+        // v is 0 on the top rail and 1 on the bottom, but 0.5 on both at a collapsed end.
         let (va_t, va_b) = (a.2.min(0.5), if a.2 == 0.5 { 0.5 } else { 1.0 });
         let (vb_t, vb_b) = (b.2.min(0.5), if b.2 == 0.5 { 0.5 } else { 1.0 });
         for (pos, uv) in [
@@ -457,9 +371,9 @@ fn push_strand(
     }
 }
 
-/// Per frame: age the beam, re-resolve every hop's live endpoints, re-jitter and advect its
-/// polyline, and write the ribbons into the shared effect-quad stream — the reference's
-/// `LightningObject::Update` (`0x6ec460`) and `CLightning::Render` (`0x7afcb0`) in one pass.
+/// Per frame: age each beam, re-resolve its endpoints, re-jitter and advect its polylines and write
+/// the ribbons, the reference's `LightningObject::Update` (`0x6ec460`) and `CLightning::Render`
+/// (`0x7afcb0`) in one pass.
 pub(crate) fn simulate_chain_beams(
     time: Res<Time>,
     mut commands: Commands,
@@ -475,15 +389,13 @@ pub(crate) fn simulate_chain_beams(
     let Ok((cam, cam_xf)) = world_cam.single() else {
         return;
     };
-    // The reference's world→eye map is rebuilt from the live camera every `CLightning::Render`
-    // (`0x7aff82`–`0x7b00c4`), so the cross-section follows the camera frame by frame; one axis
-    // serves the whole beam.
+    // The reference rebuilds its world→eye map every render (`0x7aff82`–`0x7b00c4`).
     let cam_forward = *cam_xf.forward();
     let dt = time.delta_secs().min(0.1);
     let now = time.elapsed_secs();
     for (entity, mut beam) in &mut beams {
-        // Dead ⇔ `flag == 0 && now >= expiry` (`0x6ec6b9`); and a beam whose caster is gone has
-        // nothing left to hang off — the one reap a persistent beam would otherwise never get.
+        // Dead when `flag == 0 && now >= expiry` (`0x6ec6b9`), or when the caster is gone, the one
+        // end a persistent beam would otherwise never get.
         if (!beam.persistent && now >= beam.expiry) || !units.contains(beam.caster) {
             commands.entity(entity).despawn();
             continue;
@@ -491,7 +403,7 @@ pub(crate) fn simulate_chain_beams(
         let (phase, u_scroll) = advance_scroll(beam.phase, dt, beam.effect.scroll_period_s);
         beam.phase = phase;
         if !images.contains(&beam.texture) {
-            continue; // not resident yet — nothing to draw, nothing to advect against
+            continue; // texture not resident yet
         }
         let (dest_tag, half_width, persistent, texture) = (
             beam.dest_tag,
@@ -510,13 +422,12 @@ pub(crate) fn simulate_chain_beams(
         let mut batch = draw.batch(cam, texture);
         let (mut anchor_sum, mut anchor_n) = (Vec3::ZERO, 0.0f32);
         for (i, bolt) in bolts.iter_mut().enumerate() {
-            // The per-hop window — bypassed entirely while the flag is set (`0x6ec520`).
+            // The per-hop window, bypassed while the flag is set (`0x6ec520`).
             if !persistent && !(bolt.start <= now && now < bolt.end) {
                 bolt.strands.iter_mut().for_each(Vec::clear);
                 continue;
             }
-            // Both endpoints re-resolved from the live units, every frame. Either missing hides
-            // this hop (`SetVisible(handle, 0)`) without touching the rest of the chain.
+            // A missing endpoint hides only this hop (`SetVisible(handle, 0)`).
             let dest = [dest_tag, CHAIN_ATTACH_FALLBACK];
             let from = if i == 0 {
                 caster_world_pos(nodes[0], &units, &joints, &heights)
@@ -535,9 +446,7 @@ pub(crate) fn simulate_chain_beams(
             for pts in bolt.strands.iter_mut() {
                 subdivide(from, to, effect, rng, &mut scratch);
                 if pts.len() == scratch.len() {
-                    // Advect the live polyline toward the fresh roll — interior only, endpoints
-                    // exact (`0x7afbe7`–`0x7afc81`). This is what turns a per-frame re-roll into
-                    // a crawl rather than a strobe.
+                    // Advect toward the fresh roll, interior only (`0x7afbe7`–`0x7afc81`).
                     let last = pts.len() - 1;
                     pts[0] = scratch[0];
                     pts[last] = scratch[last];
@@ -545,8 +454,8 @@ pub(crate) fn simulate_chain_beams(
                         pts[k] = pts[k] * ADVECT_KEEP + scratch[k] * (1.0 - ADVECT_KEEP);
                     }
                 } else {
-                    // First frame, or the subdivision count changed under a moving endpoint:
-                    // take the fresh polyline whole (the reference's dirty-bit rebuild).
+                    // First frame, or a new subdivision count: take the fresh polyline whole (the
+                    // reference's dirty-bit rebuild).
                     pts.clear();
                     pts.extend_from_slice(&scratch);
                 }
@@ -554,11 +463,11 @@ pub(crate) fn simulate_chain_beams(
             }
         }
         if anchor_n == 0.0 {
-            continue; // every hop hidden — `commit_quads` over an empty range is a no-op anyway
+            continue; // every hop hidden
         }
-        // `EGxRs 0x07 = 3` → `glBlendFunc(SRC_ALPHA, ONE)`, and `0x0f = 0` → GL_FOG off (the
-        // lane's default). Depth-write off and two-sided come with the additive pipeline. No
-        // owner rung: a beam is not a model's emitter (module docs, approximation (d)).
+        // `EGxRs 0x07 = 3` is `glBlendFunc(SRC_ALPHA, ONE)` and `0x0f = 0` is fog off; depth-write
+        // off and two-sided come with the additive pipeline. No owner draw rung and no water-plane
+        // interleave: a beam belongs to no model.
         batch
             .additive()
             .anchored(anchor_sum / anchor_n)
@@ -567,10 +476,7 @@ pub(crate) fn simulate_chain_beams(
     }
 }
 
-/// 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 are mis-named in the community schemas (decision 0955).
+/// The beam's arithmetic against the reference's constants, and the hop array's consumption.
 #[cfg(test)]
 mod tests {
     use std::collections::HashMap;
@@ -582,12 +488,11 @@ mod tests {
     use super::*;
     use crate::net::ObjectStore;
 
-    /// Chain Lightning's real chain (5875 `spellvis 421`): visual 36, `SpellChainEffects` id 1.
+    /// Chain Lightning (`benilla-extract <Data> spellvis 421`): visual 36, chain effect id 1.
     const CHAIN_SPELL: u32 = 421;
     const CHAIN_VISUAL: u32 = 36;
 
-    /// `SpellChainEffects` id 1 — Chain Lightning's row, verbatim from the shipped table
-    /// (`benilla-extract <Data> chaincensus`).
+    /// Chain Lightning's `SpellChainEffects` row as shipped (`benilla-extract <Data> chaincensus`).
     fn lightning() -> ChainEffect {
         ChainEffect {
             avg_seg_len: 2.78,
@@ -600,7 +505,6 @@ mod tests {
         }
     }
 
-    /// A minimal app running only [`spawn_chain_beams`] over Chain Lightning's synthetic chain.
     fn beam_app() -> App {
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, bevy::asset::AssetPlugin::default()));
@@ -613,8 +517,8 @@ mod tests {
                 HashMap::from([(
                     CHAIN_VISUAL,
                     VisualStages {
-                        // Field 9's ordinal — index 1 of the missile table is attachment 34,
-                        // which is also the chain's own fallback.
+                        // Field 9's ordinal: missile-table index 1 is attachment 34, also the
+                        // chain's fallback.
                         missile_attach: 1,
                         ..Default::default()
                     },
@@ -644,8 +548,7 @@ mod tests {
             .id()
     }
 
-    /// A cast-stage Chain Lightning play: chain id 1, one strand, flag clear. The params go through
-    /// the client's small-int decode, which round-trips an integer written as a float.
+    /// A cast-stage Chain Lightning play: chain id 1, one strand, flag clear.
     fn play(entity: Entity, spell_id: u32) -> ChainProcPlay {
         ChainProcPlay {
             entity,
@@ -676,9 +579,7 @@ mod tests {
             .collect()
     }
 
-    /// `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:
-    /// 30 / 2.78 + 2 → 12 segments, 13 points.
+    /// `n = trunc(len / avgSegLen + 2.0)` (`0x7af713`): 30 yd gives 12 segments, 13 points.
     #[test]
     fn subdivision_carries_the_plus_two_floor() {
         let (e, mut rng, mut out) = (lightning(), 1u32, Vec::new());
@@ -695,8 +596,7 @@ mod tests {
         assert_eq!(out.len(), 3);
     }
 
-    /// Endpoints are **exact** — the jitter is interior-only — and the interior offset is bounded by
-    /// `len × noiseScale` per axis (`amp = len × field3`, `0x7af748`).
+    /// Exact endpoints, and interior offsets bounded by `len × noiseScale` per axis (`0x7af748`).
     #[test]
     fn jitter_is_interior_only_and_scales_with_hop_length() {
         let (e, mut rng, mut out) = (lightning(), 0x1234_5678u32, Vec::new());
@@ -721,9 +621,6 @@ mod tests {
         assert_eq!(moved, out.len() - 2, "every interior point takes a draw");
     }
 
-    /// The ribbon spans `2 × halfWidth` across its cross-section, that cross-section is square to
-    /// the **camera** (perpendicular to the view axis, not to world up), and **both ends collapse
-    /// to a point** — the beam is a spindle, not a slab (`0x7b0196`–`0x7b0541`).
     #[test]
     fn the_ribbon_is_a_spindle_two_half_widths_across() {
         let pts = [
@@ -735,7 +632,6 @@ mod tests {
         let cam_forward = -Vec3::X;
         let mut verts = Vec::new();
         push_strand(&mut verts, &pts, 0.5, 0.0, cam_forward);
-        // 2 segments × one quad each.
         assert_eq!(verts.len(), 8);
         // Quad corner order is [b₀, b₁, t₁, t₀]: the first quad's b₀/t₀ are the collapsed caster
         // end, and the second's b₁/t₁ the collapsed target end.
@@ -743,26 +639,18 @@ mod tests {
         assert_eq!(verts[3].pos, pts[0].to_array());
         assert_eq!(verts[5].pos, pts[2].to_array());
         assert_eq!(verts[6].pos, pts[2].to_array());
-        // The middle point carries the full width…
         let (mid_bottom, mid_top) = (Vec3::from(verts[1].pos), Vec3::from(verts[2].pos));
         assert!(
             (mid_top.distance(mid_bottom) - 1.0).abs() < 1e-5,
             "2 × 0.5 yd"
         );
-        // …spread square to the view axis, which for this camera means straight up/down.
         let across = (mid_top - mid_bottom).normalize();
         assert!(across.dot(cam_forward).abs() < 1e-6, "square to the camera");
         assert!(across.x.abs() < 1e-6 && across.z.abs() < 1e-6, "±Y here");
-        // …and the collapsed ends stamp v = 0.5 on both rails.
         assert_eq!(verts[0].uv[1], 0.5);
         assert_eq!(verts[3].uv[1], 0.5);
     }
 
-    /// **The defect decision 1653 fixes.** A long, level hop watched from a camera in its own
-    /// plane — the Razorgore-room beam, and Chain Lightning's mob-to-mob jumps — kept its full
-    /// authored width in the reference and collapsed to a hairline for us, because 0964 spread the
-    /// ribbon across *world* horizontal instead of the *screen* plane. Any camera axis must give
-    /// the same `2 × halfWidth` span, and it must never lie along the view direction.
     #[test]
     fn a_level_hop_keeps_its_width_from_a_level_camera() {
         let pts = [Vec3::ZERO, Vec3::X * 15.0, Vec3::X * 30.0];
@@ -789,11 +677,6 @@ mod tests {
         }
     }
 
-    /// The `v = 0` rail sits where the reference puts it. Eye axes are X right, Y up, `+Z` into
-    /// the screen, and the perp is `(−d.y, d.x, 0)`, so a beam running **rightwards** across the
-    /// screen carries `v = 0` along its **top** edge. In world axes that is `d × camForward`; the
-    /// opposite order is the same line mirrored, which would flip the texture across the beam's
-    /// centreline.
     #[test]
     fn the_v_zero_rail_is_the_top_edge_of_a_rightward_beam() {
         // Camera at the origin looking along −Z with +Y up: a hop along +X runs left→right.
@@ -809,12 +692,6 @@ mod tests {
         );
     }
 
-    /// A hop pointing **at the camera** has no screen-plane extent, and the reference skips the
-    /// normalisation below `0.001` (`0x7b01bd`), so the segment degenerates instead of producing a
-    /// NaN. This is a **numerical guard, not a behaviour you can see**: the cone is
-    /// `arcsin(0.001/|d|)` ≈ `0.023°` on a real sub-segment, and every angle outside it is
-    /// normalized to full width. A hop pointing straight *up* is not in the regime at all — that
-    /// was 0964's world-space misreading, and it drew a vertical beam as nothing.
     #[test]
     fn a_hop_aimed_at_the_camera_collapses_instead_of_exploding() {
         let pts = [Vec3::ZERO, Vec3::Y * 5.0, Vec3::Y * 10.0];
@@ -827,7 +704,6 @@ mod tests {
         );
         assert!(verts.iter().all(|v| v.pos.iter().all(|c| c.is_finite())));
 
-        // …and the same hop, from a camera beside it, is at full width.
         verts.clear();
         push_strand(&mut verts, &pts, 0.5, 0.0, Vec3::NEG_Z);
         let (mid_bottom, mid_top) = (Vec3::from(verts[1].pos), Vec3::from(verts[2].pos));
@@ -854,9 +730,7 @@ mod tests {
         assert_eq!(verts[5].uv[0], 0.75);
     }
 
-    /// The scroll accumulator wraps on `|period|` and a **negative** period reverses `u`'s
-    /// direction with its magnitude unchanged — the four drains' `−0.5` is why their texture flows
-    /// back toward the caster (`0x7af9d7` / `0x7b055f`).
+    /// `0x7af9d7`/`0x7b055f`: the accumulator wraps on `|period|`; a negative one reverses `u`.
     #[test]
     fn the_scroll_period_sign_reverses_the_direction() {
         // One second of a 1 s period sweeps u from 0 to −1 and wraps.
@@ -876,11 +750,9 @@ mod tests {
         let (phase, u) = advance_scroll(0.0, 0.25, -0.5);
         assert!((phase - 0.25).abs() < 1e-6, "accumulator stays positive");
         assert!((u - 0.5).abs() < 1e-6, "…and u runs the other way");
-        // A zero period disables the scroll outright rather than dividing by it.
         assert_eq!(advance_scroll(0.4, 0.25, 0.0), (0.0, 0.0));
     }
 
-    /// The jitter draw stays in `[−1, 1)` — the amplitude bound the test above rests on.
     #[test]
     fn jitter_draws_stay_in_range() {
         let mut rng = 0x9E37_79B9u32;
@@ -890,9 +762,7 @@ mod tests {
         }
     }
 
-    /// A hop array holding at most one entry, on a unit channelling THIS spell at an object,
-    /// selects that **channel object** — the reference's single-target path (`0x60dae5`). Anything
-    /// else runs the array, and an empty array draws nothing at all.
+    /// The single-target path (`0x60dae5`) takes the channel object only with at most one hop.
     #[test]
     fn target_selection_prefers_the_channel_object_only_on_its_own_narrow_path() {
         use benilla_protocol::ObjectFields;
@@ -946,9 +816,6 @@ mod tests {
         );
     }
 
-    /// The end-to-end spawn: a play + a filled hop array becomes a beam whose nodes are
-    /// `caster → t1 → t2`, whose hops carry the reference's staggered windows, and whose expiry is
-    /// `hops × boltLife`. And the array is **consumed** — a second play the same frame draws nothing.
     #[test]
     fn a_play_over_a_filled_hop_array_builds_the_staggered_polyline_once() {
         let mut app = beam_app();
@@ -980,7 +847,6 @@ mod tests {
         assert!((expiry - bolts[0].0 - 2.0).abs() < 1e-5, "hops × boltLife");
         assert!(!persistent, "a cast-stage proc (flag 0) self-terminates");
 
-        // The array is gone — the same law as `0x60db72`, which zeroes the count on every path.
         assert!(app.world().entity(caster).get::<ChainHops>().is_none());
         app.world_mut().write_message(play(caster, CHAIN_SPELL));
         app.update();
@@ -991,7 +857,6 @@ mod tests {
         );
     }
 
-    /// The consume is immediate, not deferred: two plays in ONE frame must not both see the array.
     #[test]
     fn two_plays_in_one_frame_share_no_hops() {
         let mut app = beam_app();
@@ -1005,10 +870,6 @@ mod tests {
         assert_eq!(beams(&mut app).len(), 1, "only the first play consumes");
     }
 
-    /// The flag is the whole cast/channel split: a **persistent** beam never expires by time and is
-    /// ended only by the kit reap (the channel teardown's `LightningObject::Stop`), while a one-shot
-    /// ignores that reap entirely and runs its own clock — the reference only ever publishes a
-    /// FLAGGED node to the slots the teardown sweeps.
     #[test]
     fn only_a_persistent_beam_answers_the_kit_reap() {
         for persistent in [false, true] {
@@ -1038,9 +899,6 @@ mod tests {
         }
     }
 
-    /// The client's own guards, each a silent return in `0x6ecbd0`: a bare kit push (spell id 0),
-    /// a zero strand count, and a chain id naming no table row all build nothing — while still
-    /// consuming the array on the way out.
     #[test]
     fn the_constructors_guards_build_nothing_but_still_consume() {
         for (spell_id, beams_param, effect_id) in [
@@ -1069,8 +927,6 @@ mod tests {
         }
     }
 
-    /// The DBC's backslash path becomes the lane's `mpq://` URL (lowercased, forward slashes) —
-    /// the same shape every other BLP load in the client uses.
     #[test]
     fn the_texture_path_becomes_an_mpq_url() {
         assert_eq!(
diff --git a/crates/benilla-app/src/entities/collision_height.rs b/crates/benilla-app/src/entities/collision_height.rs
index a389518e..b145e9a6 100644
--- a/crates/benilla-app/src/entities/collision_height.rs
+++ b/crates/benilla-app/src/entities/collision_height.rs
@@ -1,9 +1,5 @@
-//! The per-unit **collision height** ([`CollisionHeight`]) — the reference's `CMovement+0xb4`,
-//! derived from the unit's display id and stamped on every streamed entity (decision 0645).
-//!
-//! It lives beside the display cache because that is where a display id becomes model facts; every
-//! *consumer* is elsewhere (`player::swim`, `sound::water`, `sound::footsteps`, `water_fx`,
-//! `net::motion::spline`), which is exactly why it is a component and not five private constants.
+//! The per-unit collision height ([`CollisionHeight`]), the reference's `CMovement+0xb4`, derived
+//! from the unit's display id and stamped on every streamed entity.
 
 use bevy::prelude::*;
 
@@ -11,75 +7,32 @@ use crate::net::{NetEntity, ObjectStore};
 
 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 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).
+/// A unit's collision height in yards, the reference's `CMovement+0xb4`: the `h` whose fractions
+/// are the depth lines (swim `0.75·h`, splash `0.4·h`, foam gate `max(2·h, 1.0)`; `0x6030c0`,
+/// `0x5fa760`). It is `CreatureModelData.collisionHeight`, the MD20 collision box's Z extent in
+/// model units, times `k = max(SCALE_X, CreatureDisplayInfo.creatureModelScale)`: `0x60b270`
+/// passes the larger (`0x60b312`) to `0x6174b0`, which stores the product (`0x617501`), and the
+/// unit model build `0x5fb9dd` runs it for every unit.
 ///
-/// `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)`** — 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 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.
-///
-/// **At rest the floor is inert, which is why its absence hid**: not one of the 430 shipped
-/// `CreatureModelData` rows scales below 1.0, so the folded `SCALE_X ≥ CreatureDisplayInfo.scale`
-/// always and `max` picks `SCALE_X`. It bites exactly where `SCALE_X` drops *below* the display's
-/// column — a shrink aura, and the **390** `creature_template` rows on our own server whose
-/// `display_scale` override undercuts it (by up to 6×). Those units swam at a fraction of their
-/// real depth. The floor can only ever *raise* `h`, so no unit that swims correctly today stops.
-///
-/// **The display it is derived from is the unit's NATIVE one** — `UNIT_FIELD_NATIVEDISPLAYID`, not
-/// the one being rendered. `0x60b270` fetches its `CreatureDisplayInfo` row at
-/// `[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**.
-///
-/// 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
-/// the reference deliberately letting the collision box and the drawn body disagree — and nothing
-/// here needs them to agree, because every consumer of this number is a *depth line* (a fraction of
-/// `h`), never a rendered size. Decision 0695 restamped it from the rendered display on the
-/// opposite premise ("the collision box and the drawn body can never disagree"); 1574 corrects that.
-///
-/// **Not** the movement capsule: that stays the constant-height tunable it has always been
-/// ([`crate::player::CAPSULE_HEIGHT`] — see its doc for why the two are deliberately separate).
+/// The `max` is a floor, not a second multiplier: `SCALE_X` already folds the DBC scales in
+/// (vmangos `Unit.cpp:9579`) and is the whole render scale (`0x613fc9`); it bites only where a
+/// shrink aura or a `display_scale` override sinks `SCALE_X` under the display's column. The
+/// display is the native one (`UNIT_FIELD_NATIVEDISPLAYID`, index 132 at `0x60b270`), so a
+/// transform keeps the unit's own depth lines. Not the movement capsule,
+/// [`crate::player::CAPSULE_HEIGHT`].
 #[derive(Component, Clone, Copy, Debug, PartialEq)]
 pub(crate) struct CollisionHeight(pub(crate) f32);
 
 impl Default for CollisionHeight {
-    /// The client's own ctor default — never `0.0`, at which every depth line collapses and the
-    /// unit swims on dry land. This is what makes the type safe to hold in a `Default`-derived
-    /// struct ([`crate::player::Player`] does).
+    /// The `CMovement` ctor's default, never `0.0`, at which every depth line collapses and the
+    /// unit swims on dry land.
     fn default() -> Self {
         Self(crate::player::DEFAULT_COLLISION_HEIGHT)
     }
 }
 
-/// The display id the collision prism is derived from: **`UNIT_FIELD_NATIVEDISPLAYID`**, falling
-/// back to the rendered display when the field is absent (a unit with no descriptor block yet, a
-/// synthetic entity like a mount child). `0` is treated as absent — the wire's own "unset".
-///
-/// This is the whole of decision 1574: one field swap, at the two sites that derive the prism.
+/// The display the collision height derives from: `UNIT_FIELD_NATIVEDISPLAYID`, else the rendered
+/// display when that is absent or `0` (no descriptor block yet, a synthetic mount child).
 pub(crate) fn prism_display_id(store: Option<&ObjectStore>, rendered: Option<u32>) -> Option<u32> {
     store
         .and_then(|s| s.0.unit_native_displayid())
@@ -88,9 +41,8 @@ pub(crate) fn prism_display_id(store: Option<&ObjectStore>, rendered: Option<u32
         .or(rendered)
 }
 
-/// A unit's collision height from its display id and render scale — [`CollisionHeight`]'s one
-/// derivation, shared by the ECS stamp below and the avatar's mirror of it
-/// (`player::wire_in`), so the two can never drift into different answers.
+/// [`CollisionHeight`]'s one derivation, shared by the first stamp and the live restamp
+/// ([`super::live_display::refresh_live_display`]) so the two cannot disagree.
 pub(crate) fn collision_height_for(
     creatures: Option<&Creatures>,
     display_id: Option<u32>,
@@ -99,36 +51,24 @@ pub(crate) fn collision_height_for(
     let row = creatures.zip(display_id);
     let raw = row
         .and_then(|(c, id)| c.collision_height(id))
-        // A zero column is real in the data (67 rows — invisible triggers and the like); it means
-        // "no authored box", not "a unit of no height", so it falls back like a missing row.
+        // A zero column (67 rows: invisible triggers and the like) means no authored box, so it
+        // falls back like a missing row.
         .filter(|h| *h > 0.0)
         .unwrap_or(crate::player::DEFAULT_COLLISION_HEIGHT);
     let k = prism_scale(scale, row.and_then(|(c, id)| c.catalog.display_scale(id)));
     CollisionHeight(raw * k)
 }
 
-/// `k = max(OBJECT_FIELD_SCALE_X, CreatureDisplayInfo.creatureModelScale)` — the collision prism's
-/// multiplier, split out so the FLOOR is assertable on its own (see [`CollisionHeight`] for the
-/// byte law and why the floor is not a second multiplier). A display we can't resolve — and the
-/// three shipped rows whose column is 0 — contributes nothing and leaves `SCALE_X` standing alone.
-/// Never returns 0: at zero every depth line collapses and the unit swims on dry land.
+/// `k = max(SCALE_X, CreatureDisplayInfo.creatureModelScale)`; an unresolved display or a `0`
+/// column (3 shipped rows) leaves `SCALE_X` alone. Never 0, at which every depth line collapses.
 fn prism_scale(scale: f32, display_scale: Option<f32>) -> f32 {
     display_scale
         .map_or(scale, |s| scale.max(s))
         .max(f32::MIN_POSITIVE)
 }
 
-/// Give every streamed unit its [`CollisionHeight`] the frame its display resolves. Queries the
-/// not-yet-stamped only, so it costs nothing in steady state and self-heals if `Creatures` (the DBC
-/// catalog) lands after the first units stream in. A display id that misses the DBCs — or a unit
-/// carrying none at all — is still stamped, at the ctor default, so no consumer has to tell
-/// "not resolved yet" apart from "resolved to nothing".
-///
-/// This system stamps only the **first** value. A live change to either input — the unit's
-/// **native** display id or its `SCALE_X` — restamps through
-/// [`super::live_display::refresh_live_display`]. A *rendered* display swap (druid form, GM morph)
-/// deliberately does **not**: see [`CollisionHeight`] for why the reference lets the collision box
-/// and the drawn body disagree.
+/// Stamp each streamed unit's first [`CollisionHeight`], at the ctor default when its display
+/// misses the DBCs; only the unstamped are queried, so it heals if `Creatures` loads late.
 pub(super) fn stamp_collision_heights(
     mut commands: Commands,
     creatures: Option<Res<Creatures>>,
@@ -147,24 +87,20 @@ mod native_display {
     use crate::net::ObjectStore;
     use benilla_protocol::ObjectFields;
 
-    /// `UNIT_FIELD_NATIVEDISPLAYID`, index 132 — the gap between DISPLAYID (131) and
-    /// MOUNTDISPLAYID (133), both of which this crate already pins independently.
+    /// `UNIT_FIELD_NATIVEDISPLAYID`, between DISPLAYID (131) and MOUNTDISPLAYID (133).
     const NATIVE: u16 = 132;
 
     fn store(pairs: &[(u16, u32)]) -> ObjectStore {
         ObjectStore(ObjectFields::from_pairs(pairs))
     }
 
-    /// A druid in bear form: rendered display 2281, native still the night elf's 55. The prism
-    /// follows the native one — decision 1574's whole observable.
+    /// A druid in bear form: rendered display 2281, native still the night elf's 55.
     #[test]
     fn a_shapeshifted_unit_keeps_its_native_display() {
         let shifted = store(&[(NATIVE, 55)]);
         assert_eq!(prism_display_id(Some(&shifted), Some(2281)), Some(55));
     }
 
-    /// The fallbacks, all three of them, all landing on the rendered display: no descriptor block
-    /// yet, a descriptor without the field, and the wire's own "unset" zero.
     #[test]
     fn an_absent_or_zero_native_falls_back_to_the_rendered_display() {
         assert_eq!(prism_display_id(None, Some(2281)), Some(2281));
@@ -172,11 +108,9 @@ mod native_display {
         assert_eq!(prism_display_id(Some(&empty), Some(2281)), Some(2281));
         let zeroed = store(&[(NATIVE, 0)]);
         assert_eq!(prism_display_id(Some(&zeroed), Some(2281)), Some(2281));
-        // …and a unit with neither stays None, which `collision_height_for` reads as "no row".
         assert_eq!(prism_display_id(Some(&empty), None), None);
     }
 
-    /// An unshifted unit — native == rendered — is the common case and must be untouched.
     #[test]
     fn an_unshifted_unit_is_unaffected() {
         let plain = store(&[(NATIVE, 4945)]);
@@ -188,21 +122,15 @@ mod native_display {
 mod prism {
     use super::prism_scale;
 
-    /// The **floor**, and the two shapes it has to get right. `SCALE_X` normally already carries
-    /// the DBC product (the server folded it), so the display column can only ever equal or
-    /// undercut it — which is why the floor is inert on shipped data and bit only when a server
-    /// override or a shrink aura pushed `SCALE_X` under the display's own size.
     #[test]
     fn the_display_column_is_a_floor_never_a_multiplier() {
-        // The Shore Strider (display 4945): `modelScale` 1.0 × `CDI.scale` 1.75, folded → 1.75.
-        // The floor is inert here, which is exactly why the height was NOT B311's cause.
+        // The Shore Strider (display 4945): `modelScale` 1.0 × `CDI.scale` 1.75, folded to 1.75.
         assert_eq!(prism_scale(1.75, Some(1.75)), 1.75);
-        // A `creature_template.display_scale` override under the display's own column (390 rows on
-        // our server), or a shrink aura: the prism holds at the display size, it does not shrink.
+        // Under the column (a `display_scale` override, a shrink aura): held at the display size.
         assert_eq!(prism_scale(1.0, Some(6.0)), 6.0);
-        // A growth aura pushes SCALE_X above the column: the prism grows with it.
+        // A growth aura above the column grows it.
         assert_eq!(prism_scale(3.5, Some(1.75)), 3.5);
-        // …and it is never a product: 1.75 × 1.75 = 3.06 would be the double-apply.
+        // Never a product: 1.75 × 1.75 would apply the display scale twice.
         assert_ne!(prism_scale(1.75, Some(1.75)), 1.75 * 1.75);
     }
 
diff --git a/crates/benilla-app/src/entities/conform.rs b/crates/benilla-app/src/entities/conform.rs
index acc6d845..9058b295 100644
--- a/crates/benilla-app/src/entities/conform.rs
+++ b/crates/benilla-app/src/entities/conform.rs
@@ -1,12 +1,8 @@
-//! 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.
-//! The [`ConformNode`] is the tilt carrier: an extra node a flagged model's root bones parent
-//! under (spawned by [`super::attach`]), so one rotation write tilts the whole composite — a
-//! mount's seat joint, rider included, hangs below it — while the unit root keeps its net-driven
-//! yaw and the collider/selection footprint stay upright. `WOW_NO_MOUNT_TILT=1` disables (the
-//! A/B lever; the name predates this creature generalization and is kept stable).
+//! Terrain conform (`0x7106c0`): a model whose M2 has `GlobalModelFlags & 3` of 1 pitches to the
+//! ground (mounts, quadrupeds) and of 3 pitches and rolls (low wide bodies: kodo, basilisk, crab),
+//! wild or mounted alike. The tilt is one [`ConformNode`] the root bones hang under, so a rider
+//! tilts with its mount while the unit's yaw and collider stay upright. `WOW_NO_MOUNT_TILT=1`
+//! disables it.
 
 use avian3d::prelude::SpatialQuery;
 use bevy::ecs::entity::{EntityHashMap, EntityHashSet};
@@ -15,33 +11,25 @@ use bevy::prelude::*;
 /// Ray envelope around the unit's feet: start this far up, reach this far down past the feet.
 const TILT_PROBE_UP: f32 = 2.0;
 const TILT_PROBE_DOWN: f32 = 4.0;
-/// The walkable cutoff on a sampled face normal — the producer's `[0x80e028]` ≈ cos 89°: a
-/// steeper face isn't ground at all (zero qualifying contacts → the ref writes world-up).
+/// The walkable cutoff (`[0x80e028]`, about cos 89°): a steeper face targets world-up.
 const TILT_WALKABLE_Y: f32 = 0.0175;
-/// The freeze band — the bridge's `[0x80c6a8]` = 0.3572 ≈ cos 69.07°: ground steeper than ~69°
-/// FREEZES the smoothed up-vector (holds the last stance) instead of conforming.
+/// The freeze band (`[0x80c6a8]`, about cos 69.07°): steeper ground holds the last stance.
 const TILT_FREEZE_Y: f32 = 0.3572;
-/// The up-vector smoothing decay — the bridge's `[0x80c6a0]`: per-frame factor `0.0018^dt`
-/// (≈ `e^(−6.32·dt)`, τ ≈ 158 world) applied to the RESIDUAL toward the target normal.
+/// The up-vector smoothing (`[0x80c6a0]`): the residual toward the target decays by `0.0018^dt`.
 const TILT_DECAY: f32 = 0.0018;
 
-/// The tilt carrier a flagged model's root bones parent under — spawned by the attach path when
-/// the built display's `terrain_tilt != 0`, despawned with the visual (it's a child of the
-/// unit). [`conform_units`] writes its local rotation each frame: the ref's `0x7106c0` model
-/// matrix stage isolated into one node.
+/// The tilt carrier a flagged model's root bones hang under, a child of the unit spawned when the
+/// display's `terrain_tilt != 0`; [`conform_units`] writes its rotation, the `0x7106c0` stage.
 #[derive(Component)]
 pub(super) struct ConformNode {
-    /// The streamed unit whose feet sample the ground and whose yaw frames the normal — for a
-    /// mount child's node, the HOST unit (the mount body sits at the unit matrix).
+    /// The unit whose feet sample the ground and whose yaw frames it: for a mount child, the host.
     pub(super) unit: Entity,
     /// The model's `GlobalModelFlags & 3` dispatch mode (1 = pitch, 3 = pitch + roll).
     pub(super) mode: u8,
 }
 
-/// The per-frame target for the smoothed up-vector, from one sampled ground-face normal — the
-/// producer + bridge gates composed (`0x637140` / `0x614cd0`): a miss or an unwalkable face
-/// (steeper than ~89°) targets world-up; a face in the freeze band (69°..89°) holds the current
-/// stance (`None`); a walkable face tracks its normal.
+/// The smoothed up-vector's target for one sampled face normal (`0x637140`, `0x614cd0`): world-up
+/// on a miss or an unwalkable face, `None` (hold the stance) in the freeze band, else the normal.
 fn tilt_target(sampled: Option<Vec3>) -> Option<Vec3> {
     match sampled {
         Some(n) if n.y < TILT_WALKABLE_Y => Some(Vec3::Y),
@@ -51,24 +39,15 @@ 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:
-///
-/// - **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
-///   `atan2(n.z, n.y)` (the roll component of the normal is discarded).
-/// - **flag 3 (pitch + roll, `0x710a80`)**: left = up × forward (NOT horizontal), forward =
-///   left × up, and the model's up row is the normal **verbatim** — full conform.
-/// - anything else: level (flag 2 is byte-verified inert; no shipped M2 authors it).
-///
-/// No clamp and no easing here — the ref has neither; all smoothing lives on the up-vector input.
+/// The `0x7106c0` flag dispatch in the unit's local frame: flag 1 (`0x710769`) keeps left
+/// horizontal, a pure pitch of `atan2(n.z, n.y)` without roll; flag 3 (`0x710a80`) takes the normal
+/// as up; any other, flag 2 included, is level. No clamp, no easing: all smoothing is upstream.
 fn conform_rotation(mode: u8, n_local: Vec3) -> Quat {
     match mode {
         1 => Quat::from_rotation_x(n_local.z.atan2(n_local.y)),
         3 => {
             let up = n_local.normalize_or_zero();
-            // left = up × fwd0 (WoW row order, mapped to the Bevy local frame: fwd = −Z,
-            // left = −X, up = +Y — right-handed).
+            // left = up × forward, in the Bevy local frame (forward −Z, left −X, up +Y).
             let left = up.cross(Vec3::NEG_Z);
             if up == Vec3::ZERO || left.length_squared() < 1e-6 {
                 return Quat::IDENTITY; // degenerate normal (≈ along the facing axis)
@@ -81,19 +60,14 @@ fn conform_rotation(mode: u8, n_local: Vec3) -> Quat {
     }
 }
 
-/// Conform every flagged model to the terrain under its unit (decisions 0482/0486). The pipeline
-/// mirrors the ref's three stages: a ground normal per unit (theirs: the averaged walkable
-/// collision-contact normal `CMovement+0x24`; ours: ONE ground-face normal from a down-ray
-/// against the decal-receiver set — a named approximation that coincides on uniform slopes),
-/// exponentially smoothed **on the up-vector** at `0.0018^dt` with the ~69° freeze band, then
-/// the flag-picked basis written to the [`ConformNode`] — no angle clamp anywhere.
+/// Conform every flagged model to the ground under its unit: one face normal per unit from a
+/// down-ray against the decal receivers (the reference averages its walkable contact normals,
+/// `CMovement+0x24`; the two agree on a uniform slope), smoothed on the up-vector.
 ///
-/// Two named divergences from the ref's every-unit-every-frame maintenance, both invisible by
-/// construction: only units carrying a flagged visual are tracked (a flag-0 unit's vector is
-/// never consumed), with the first sight seeding AT the slope — warm, so a mount-up or a fresh
-/// spawn seats instantly like the reference; and a parked rig (off-frustum, the 0448 anim-LOD
-/// gate) skips its ray and drops its vector, re-seeding warm on wake — the 0448 absolute-snap
-/// philosophy applied to the stance, bounding the cost at one ray per flagged unit ON SCREEN.
+/// Deviation: the reference updates every unit every frame; here only units showing a flagged
+/// visual are tracked, and a parked rig skips its ray and re-seeds at the slope on waking, to bound
+/// the cost at one ray per flagged unit on screen. Nothing shows: an unflagged unit's vector is
+/// never read, and a first-sight seed at the slope seats a mount-up at once, as the reference does.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 pub(super) fn conform_units(
     time: Res<Time>,
@@ -103,8 +77,6 @@ pub(super) fn conform_units(
     mut nodes: Query<(&ConformNode, &mut Transform)>,
     mut ups: Local<EntityHashMap<Vec3>>,
     mut disabled: Local<Option<bool>>,
-    // Once-a-second census at debug level — "is anything actually tilting, and how much",
-    // answerable from a probe log (the blob-shadow census pattern).
     mut census_at: Local<f32>,
 ) {
     if *disabled.get_or_insert_with(|| std::env::var_os("WOW_NO_MOUNT_TILT").is_some()) {
@@ -123,16 +95,12 @@ pub(super) fn conform_units(
             ups.remove(&node.unit);
             continue;
         }
-        // Sample + smooth once per unit per frame (a unit could host two flagged visuals —
-        // a flagged NPC body over a mount field — and double-stepping would square the decay).
+        // Sample and smooth once per unit per frame: a unit can host two flagged visuals (a
+        // flagged body over a mount), and stepping twice would square the decay.
         if seen.insert(node.unit) {
-            // A unit riding a FLYING spline settles to level here: the flying attitude (pitch,
-            // 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
-            // ConformNode at all). The ground probe misses in the air → `tilt_target` yields
-            // world-up, easing any flagged flier level.
+            // A unit on a flying spline eases level here: its flying pitch and bank are on the unit
+            // transform, from `sample_splines` (`0x7c5490`'s flying branch), whatever the model
+            // flags. The probe misses in the air, so `tilt_target` yields world-up.
             let target = {
                 let origin = unit_tf.translation + Vec3::Y * TILT_PROBE_UP;
                 let sampled = spatial
@@ -182,8 +150,6 @@ pub(super) fn conform_units(
 mod tests {
     use super::*;
 
-    /// The producer + bridge gates (`0x637140` / `0x614cd0`): a miss and a near-vertical face
-    /// target world-up, the ~69°..~89° band freezes, a walkable face tracks its normal.
     #[test]
     fn tilt_target_bands_match_the_byte_gates() {
         assert_eq!(tilt_target(None), Some(Vec3::Y));
@@ -193,9 +159,6 @@ mod tests {
         assert_eq!(tilt_target(Some(n)), Some(n));
     }
 
-    /// The `0x7106c0` flag dispatch: level is identity in every mode; flag 1 pitches nose-up on
-    /// an uphill normal and discards roll; flag 3 carries the normal verbatim as the model's up
-    /// (roll included) and reduces to flag 1 on a roll-free normal; flags 0/2 stay level.
     #[test]
     fn conform_rotation_matches_the_flag_dispatch() {
         for mode in [0u8, 1, 2, 3] {
diff --git a/crates/benilla-app/src/entities/corpse.rs b/crates/benilla-app/src/entities/corpse.rs
index 44eae27e..d7ee3735 100644
--- a/crates/benilla-app/src/entities/corpse.rs
+++ b/crates/benilla-app/src/entities/corpse.rs
@@ -1,96 +1,19 @@
-//! **The corpse OBJECT rendered as the dead body** (decision 1706) — the deferral decision 0308 §7
-//! opened ("the corpse *object* rendered as the dead body — CGCorpse law") and this closes.
+//! The corpse object (`TYPEID_CORPSE`) drawn as the dead body: a released player's body, and the
+//! bone pile the server turns it into once it is reclaimed, looted or timed out.
 //!
-//! A `TYPEID_CORPSE` (7) object is what you run back to: the body a released player leaves behind,
-//! and the **bone pile** the server converts it into once it is reclaimed, looted, or times out.
-//! Until 1706 it streamed in, spawned an entity, latched its guid for the reclaim send — and drew
-//! nothing at all, because [`EntityKind`] had no variant for it and every model lane matched on
-//! `Unit | Player | GameObject`.
+//! The reference forks once, on `CORPSE_FLAG_BONES` (dress `0x5d6260`, model getter `0x5d6700`).
+//! A fresh body (`0x5d6297`) is a player body: `CORPSE_FIELD_DISPLAY_ID` down the usual display
+//! chain (`0x5d6759`), dressed from the corpse's own appearance bytes and item slots through the
+//! living player's compositor (`0x478cb0`), armour only. A bone pile (`0x5d6291`) has no
+//! appearance and takes a static two-bone `<Race><Sex>DeathSkeleton` model (`0x5d670c`).
 //!
-//! ## The reference's law (`CGCorpse_C` dress `0x5d6260`, model getter `0x5d6700`)
+//! No selection decal: `0x5d6fe0` draws one only for the locked target, and `SetSelection`
+//! (`0x493540`) refuses a corpse, whose selectability slot `0x469fe0` returns 0.
 //!
-//! It forks once, on `CORPSE_FIELD_FLAGS` bit 0 (`CORPSE_FLAG_BONES`), and the two halves share
-//! nothing:
-//!
-//! - **A fresh body** (`0x5d6297`) allocates a `CCharacterComponent` at `[corpse+0x29c]` and fills
-//!   it from the corpse's OWN snapshot — the seven `CORPSE_FIELD_BYTES_1/_2` bytes (`+0x69..+0x6f`)
-//!   and the 19 `CORPSE_FIELD_ITEM` slots (`+0x1c + slot*4`, low 24 bits = the ItemDisplayInfo id)
-//!   — through the very same compositor entry `0x478cb0` a living player is dressed by. Its model
-//!   is `CORPSE_FIELD_DISPLAY_ID` down the ordinary CreatureDisplayInfo → CreatureModelData chain
-//!   (`0x5d6759`), which is why the whole character pipeline (decisions 0041/0044/0045/0074) simply
-//!   applies: a corpse *is* a player body wearing a wire-supplied look.
-//! - **A bone pile** (`0x5d6291 jne`) builds **no component at all** — no appearance, no gear — and
-//!   takes its model from race/sex instead: `0x5d670c` formats
-//!   `World\Generic\PassiveDoodads\DeathSkeletons\%s%sDeathSkeleton.mdx` from `ChrRaces[race]+0x3c`
-//!   (the client fileString: `"Human"`, `"Scourge"`, …) and `["Male","Female","NOSEX"][sex]`. Those
-//!   16 shipped models are fully static, two-boned, one hardcoded texture each.
-//!
-//! 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 (`0x5ed700`) — and
-//! `0x5d644e` skips slot 0x11 (ranged) unconditionally.
-//!
-//! ## What a corpse deliberately does NOT wear
-//!
-//! **No weapons.** Slots 0xf/0x10 detour at `0x5d645a`/`0x5d645f` to `0x5d649b`, which pushes the
-//! raw `CORPSE_FIELD_ITEM` word as a **guid** into the object-manager lookup `0x468460` with
-//! typemask 2 (`TYPEMASK_ITEM`) and skips the slot on the null return. That word is
-//! `DisplayInfoID | (InventoryType << 24)` — never a guid — so the lookup cannot succeed and the
-//! branch is dead. We reproduce the *outcome* (a corpse wears armour, not weapons), not the
-//! mechanism: aping a dead lookup would be aping a quirk, which §3 of the contract is against.
-//!
-//! ## The ground decal, and the one divergence
-//!
-//! `[corpse+0x2b0]` is **not** a render scale (its old ledger gloss); it is `0.5 ×` the MD20 render
-//! bounding-sphere radius, read by exactly one site — `0x5d6fe0`, which sizes the corpse's
-//! `UnitSelectTexture` ground decal by it × `OBJECT_FIELD_SCALE_X`.
-//!
-//! **That decal is dead code, and we owe it nothing** (1727, closed by 1732). Its one dispatcher
-//! image-wide gates on the object being the **Locked Target** (`[0xb4e2d8]`/`[0xb4e2dc]`), and
-//! `SetSelection 0x493540` refuses any object whose `[vt+0x58]` selectability slot returns 0 —
-//! CGCorpse's is `0x469fe0`, literally `33 c0 c3`. No corpse, bones or fresh, can ever be the
-//! locked target, so `0x5d6fe0` never runs. (The same refusal is independently why a click on a
-//! body leaves your current target alone: `0x4935f3` bails *before* the clear-the-old-selection
-//! 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** (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
-//! the world directly at attach time, a frame or more later, so our `Drowned` leg is reachable
-//! whether or not theirs is. The failure is one-sided — we can only ever show `Drowned` where the
-//! reference might show `Dead`, never the reverse — and it needs a drowned corpse to observe.
-//!
-//! ## 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. 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
-//! ```
-//!
-//! strict (`test ah,0x41` read by `jne`, so equality and NaN are both false), and 2/3 yd is this
-//! client's submersion depth generally — `0x60a740`, whose result is pushed as the `$FSD` **wading**
-//! flag, runs the same subtraction against the same constant.
-//!
-//! Both ids resolve through the model's own fallback table before playing (which is what
-//! `0x7121a0` itself does: `0x711c10` playableAnimationLookup, then `0x712470` animationLookup,
-//! before any `nSequences` bounds check): `HumanMale.m2` authors neither 6 nor 132's head directly,
-//! and `AnimationData.dbc` walks `Dead → Death(1)` and `Drowned → Drown(131)`.
-//!
-//! The clip is armed **once, seeked to its end**, which is the reference's own shape: `0x5d6260`
-//! runs exactly once per object (one call site, no data-section pointer to it anywhere in the PE),
-//! it caches the verdict in `[corpse+0x2ac]`, and nothing ever recomputes it. `0x5d6850` re-arms
-//! from that cached byte, but it is the **model-ready callback** (vtable `+0x34`, fired by the
-//! trampoline `0x613d70` that SetModel registers), not a per-frame tick. A corpse object never
-//! collapses in front of you either — it is created after the release, already lying down — so this
-//! is a settled pose, never a replay.
+//! The reference takes the drowned verdict inside the create, from the scene node's cached liquid
+//! probe, and an unprobed node (`[node+0x90] & 0x20`) falls to `Dead`; whether it is probed that
+//! early is untraced. This asks the world at attach time, so it can show `Drowned` where the
+//! reference shows `Dead`, never the reverse.
 
 use std::collections::HashMap;
 
@@ -102,34 +25,31 @@ use super::display::{empty_shell, DisplayModel, ModelHandle};
 use crate::creature_anim::AnimData;
 use crate::net::{NetEntity, ObjectStore};
 
-/// `AnimationData.dbc` **6 `Dead`** — the settled corpse pose (`0x5d63fe push 0x6`).
+/// `AnimationData.dbc` 6 `Dead`, the settled corpse pose (`0x5d63fe push 0x6`).
 const DEAD: u16 = 6;
-/// `AnimationData.dbc` **132 `Drowned`** — the submerged corpse pose (`0x5d63f7 push 0x84`).
+/// `AnimationData.dbc` 132 `Drowned`, the submerged corpse pose (`0x5d63f7 push 0x84`).
 const DROWNED: u16 = 132;
-/// `[0x80abfc]`, read out of the shipped PE's `.rdata`: how far a corpse must be under a liquid
-/// surface before it lies drowned rather than dead. Yards.
+/// `[0x80abfc]`, in yards: how far under a liquid surface a corpse lies drowned rather than dead;
+/// the wading test (`0x60a740`) uses the same constant.
 const DROWNED_DEPTH: f32 = 0.666_666_7;
 
-/// The **bone-pile** body models, keyed `(race, sex)` — 16 at most, one per playable ChrRaces row ×
-/// sex, and every one a static two-bone prop. Kept out of [`super::Creatures`] on purpose: that map
-/// is keyed by `CreatureDisplayInfo` id, a real DBC keyspace, and a skeleton has no id in it.
+/// The bone-pile models by `(race, sex)`, apart from [`super::Creatures`] because a skeleton has no
+/// `CreatureDisplayInfo` id.
 #[derive(Resource, Default)]
 pub(crate) struct BonesModels(pub(crate) HashMap<(u8, u8), DisplayModel>);
 
-/// Where one corpse's body model comes from — the `0x5d6700` fork, resolved once and read by both
-/// the display-build pass and the attach pass so the two can never disagree about which cache holds
-/// this corpse's model.
+/// A corpse's model source, the `0x5d6700` fork, read by both the display build and the attach
+/// pass so they agree on which cache holds it.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(in crate::entities) enum CorpseModel {
-    /// `CORPSE_FLAG_BONES` — `<Race><Sex>DeathSkeleton`, from [`BonesModels`].
+    /// `CORPSE_FLAG_BONES`: `<Race><Sex>DeathSkeleton`, from [`BonesModels`].
     Bones(u8, u8),
-    /// A fresh body — a `CreatureDisplayInfo` id, from [`super::Creatures`] like any other body.
+    /// A fresh body: a `CreatureDisplayInfo` id, from [`super::Creatures`].
     Flesh(u32),
 }
 
-/// Classify a corpse entity's model source. `None` when it is not a corpse, or while its descriptor
-/// has not landed (the one-frame window between the create's entity spawn and the pending-fields
-/// flush), or for a bone pile whose race/sex the client data cannot name.
+/// `None` for anything but a corpse, before its descriptor lands, or for a bone pile whose race the
+/// client data cannot name.
 pub(in crate::entities) fn corpse_model(
     net: &NetEntity,
     store: Option<&ObjectStore>,
@@ -142,33 +62,27 @@ pub(in crate::entities) fn corpse_model(
         let look = s.corpse_look()?;
         return Some(CorpseModel::Bones(look.race, look.sex.min(1)));
     }
-    // The wire's display id, which for a corpse is the dead player's own body display. A corpse
-    // whose create carried none has no body to build — the debug cube would be the wrong answer
-    // here (nothing named a model), so it draws nothing, like the reference's null-row leg.
+    // The dead player's own body display; a corpse whose create carried none draws nothing, not
+    // the debug cube, like the reference's null-row leg.
     net.display_id.map(CorpseModel::Flesh)
 }
 
-/// The corpse's appearance snapshot — [`ObjectFields::corpse_look`](benilla_protocol::ObjectFields::corpse_look)
-/// for a corpse that is not a bone pile. `None` for anything else, which is exactly the reference's
-/// gate: a bone pile builds no character component, so it has no look to read.
+/// A fresh corpse's appearance snapshot; a bone pile has none, as the reference builds it no
+/// character component.
 pub(in crate::entities) fn corpse_char_look(store: Option<&ObjectStore>) -> Option<CorpseLook> {
     let s = &store?.0;
     (!s.corpse_is_bones()).then(|| s.corpse_look())?
 }
 
-/// `World\Generic\PassiveDoodads\DeathSkeletons\<Race><Sex>DeathSkeleton.m2` — `0x5d673c`'s format
-/// string `0x85fb30` with `ChrRaces[race]` column 15 and the sex table `0x856450`.
-///
-/// Sex is clamped to the two shipped halves: the reference's third string is `"NOSEX"`, for which no
-/// skeleton file exists, and no player corpse can carry it.
+/// `0x5d673c`'s format string `0x85fb30` with `ChrRaces[race]` column 15 and the sex table
+/// `0x856450`, clamped to its two shipped entries: the third, `NOSEX`, has no skeleton file.
 fn bones_model_path(race_file: &str, sex: u8) -> String {
     let sex = if sex == 0 { "Male" } else { "Female" };
     format!("World\\Generic\\PassiveDoodads\\DeathSkeletons\\{race_file}{sex}DeathSkeleton.mdx")
 }
 
-/// Ensure a `(race, sex)` bone-pile display exists in the cache, requesting its model on first ask.
-/// A race with no `ChrRaces` fileString (nothing playable — no skeleton ships) caches an empty
-/// display, so the miss is asked once rather than every frame.
+/// Request a `(race, sex)` bone-pile model on first ask; a race with no `ChrRaces` fileString
+/// caches an empty display, so the miss is asked once.
 pub(in crate::entities) fn ensure_bones_display(
     bones: &mut BonesModels,
     races: &benilla_formats::CharCreateCatalog,
@@ -188,18 +102,16 @@ pub(in crate::entities) fn ensure_bones_display(
     bones.0.insert(key, dm);
 }
 
-/// This corpse's held pose has been armed — once-only, like the reference's: `0x5d6260` computes
-/// the verdict once per object and caches it in `[corpse+0x2ac]`, and no site recomputes it.
+/// The corpse's pose is armed, once: `0x5d6260` caches the verdict at `[corpse+0x2ac]` and nothing
+/// recomputes it.
 #[derive(Component)]
 pub(super) struct CorpsePosed;
 
-/// Arm each freshly-attached corpse's settled pose: `Dead`, or `Drowned` when it lies more than
-/// [`DROWNED_DEPTH`] under a liquid surface, seeked to the clip's end.
-///
-/// Runs off the attach's own output (an `AnimationPlayer` + the model's [`ModelAnimations`]) rather
-/// than off a driver: a corpse has no state machine to run, and giving it an
-/// [`AnimDriver`](crate::creature_anim::AnimDriver) would enrol it in the unit gait selector, which
-/// has no meaning for an object with no movement, no sheath and no combat.
+/// Arm each newly attached corpse's pose on bone 0 through `0x7121a0` (`0x5d63de`, `0x5d6402`):
+/// `Dead`, or `Drowned` past [`DROWNED_DEPTH`] under a liquid (`0x5d6540`), held at the clip's end.
+/// The corpse is created already lying down, and the reference re-arms only from the cached
+/// verdict when the model loads (`0x5d6850`). No `AnimDriver`: that would enrol a corpse in the
+/// unit gait selector.
 #[allow(clippy::type_complexity)] // one query's tuple + its Without filter
 pub(super) fn pose_corpses(
     mut commands: Commands,
@@ -222,26 +134,20 @@ pub(super) fn pose_corpses(
             continue;
         }
         let wow = benilla_assets::coords::bevy_to_wow(tf.translation());
-        // The reference's `0x5d6540`: ANY liquid, not water alone — it is the generic `0x670630`
-        // probe, the same one the breath classifier runs, so lava and slime count too. Strict `>`,
-        // like the emitted `jne` (equality and NaN both read as not-submerged).
-        //
-        // The reference subtracts `CORPSE_FIELD_POS_Z` (its position getter `0x5d7690` copies
-        // `[[corpse+0x110]+0xc/0x10/0x14]`), where this reads the entity's world pose. They are the
-        // same number: vmangos writes the descriptor POS fields and the movement block's
-        // `HAS_POSITION` pose from one `Relocate` (`Corpse.cpp:100-103`), and nothing moves a
-        // corpse afterwards.
+        // `0x5d6540` takes any liquid (the generic probe `0x670630`, so lava and slime too), and
+        // strictly: equality and NaN read as dry. It subtracts `CORPSE_FIELD_POS_Z` (`0x5d7690`),
+        // the same number as the entity pose: vmangos writes both from one position
+        // (`Corpse.cpp:86-103`) and never moves a corpse.
         let submerged = world
             .liquid_at(benilla_world::world_point::Subject::Unit(entity), wow)
             .is_some_and(|hit| hit.surface_z - wow[2] > DROWNED_DEPTH);
         let want = if submerged { DROWNED } else { DEAD };
-        // The model's own fallback resolution (decision 0082) — a character body authors neither
-        // `Dead` nor `Drowned` directly and walks to `Death`/`Drown`.
+        // The model's fallback table (`0x711c10`, `0x712470`): a character body authors neither,
+        // and walks `Dead` to `Death` (1) and `Drowned` to `Drown` (131).
         let catalog = anim_data.as_deref().map(|a| &a.0);
         let resolved = catalog.map_or(want, |cat| anims.resolve(want, cat).id);
         let Some(clip) = anims.find(resolved) else {
-            // No clip to hold: mark it posed anyway so this doesn't re-run every frame for a body
-            // whose model authors nothing (a bone pile — static, and correct as it stands).
+            // No clip (a static bone pile): posed anyway, so it is not retried every frame.
             commands.entity(entity).insert(CorpsePosed);
             continue;
         };
@@ -255,7 +161,7 @@ pub(super) fn pose_corpses(
     }
 }
 
-/// Play `clip` and hold it at its end pose — the settled corpse, never the collapse.
+/// Play `clip` held at its end pose: the settled corpse, never the collapse.
 fn arm_settled(
     player: &mut AnimationPlayer,
     transitions: &mut bevy::animation::transition::AnimationTransitions,
@@ -284,16 +190,15 @@ mod tests {
             bones_model_path("Scourge", 1),
             "World\\Generic\\PassiveDoodads\\DeathSkeletons\\ScourgeFemaleDeathSkeleton.mdx"
         );
-        // `.mdx` is the authored extension the client formats; the loader swaps it for the shipped
-        // `.m2` like every other model path.
+        // The client formats `.mdx`; the loader swaps it for the shipped `.m2`.
         assert_eq!(
             m2_url(&bones_model_path("NightElf", 0)),
             "mpq://world/generic/passivedoodads/deathskeletons/nightelfmaledeathskeleton.m2"
         );
     }
 
-    /// The model fork is the BONES bit, and nothing else: a bone pile carries a perfectly good
-    /// display id (the server's conversion copies it verbatim) and must still resolve to a skeleton.
+    /// A bone pile keeps the body's display id (vmangos copies it over, `Map.cpp:3633`), yet
+    /// resolves to a skeleton.
     #[test]
     fn bones_flag_beats_the_display_id() {
         use benilla_protocol::ObjectFields;
@@ -320,7 +225,6 @@ mod tests {
             corpse_model(&net, Some(&bones)),
             Some(CorpseModel::Bones(1, 0))
         );
-        // …and a bone pile has no look to dress from, where a fresh body does.
         assert!(corpse_char_look(Some(&bones)).is_none());
         assert!(corpse_char_look(Some(&flesh)).is_some());
     }
diff --git a/crates/benilla-app/src/entities/dest_fx.rs b/crates/benilla-app/src/entities/dest_fx.rs
index 6b20b1c7..2afd4099 100644
--- a/crates/benilla-app/src/entities/dest_fx.rs
+++ b/crates/benilla-app/src/entities/dest_fx.rs
@@ -1,40 +1,7 @@
-//! **Dest-anchored spell effects** (decision 0797, B132's second half): what a ground cast shows
-//! at the point. Two producers, one spawn/attach lane:
-//!
-//! - **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**, 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),
-//!     Z-rotated by `DYNAMICOBJECT_FACING` (`0x613ef0` → `0x7bdd60`), looping its sequence
-//!     (`0x5d5580` re-fires on completion).
-//!   - **Visual B** — the shard emitter (`AUBlizzardObject`, `0x5d55c0` → `0x6ece30`):
-//!     `SpellVisual` field 13 → `SpellVisualKit` → the first `CharProcType == 9` block; its
-//!     `CharParamZero` small-int-decodes (`bits(p0 + 512.0) >> 14 & 0xff`) into a **hardcoded
-//!     7-entry model table** (`0x870e24` — [`SHARD_MODELS`]), `CharParamOne` is the emit rate
-//!     (× the graphics-quality factor — we run max quality, ×1.0). Each emitted shard spawns at
-//!     a random offset inside `DYNAMICOBJECT_RADIUS` — the wire radius IS the visual footprint
-//!     (`0x6ebad0`). The kit's field-13 `SoundEntries` is the looping area sound.
-//! - **The GO dest one-shot** ([`spawn_ground_bursts`] ← the router's [`GroundBurst`]):
-//!   `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 (a trap).
-//!
-//! **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
-//! `RemovedComponents<NetEntity>` hold-loop reaper.
-//!
-//! Named approximations: the ref's 3 s sound fade at destroy is a hard stop here (no channel
-//! fade affordance yet); the hardcoded loop sequence id `0x9e` (fired when `obj+0x190` bit 1 is
-//! set — the bit's source is unpinned) is approximated by looping the model's first clip; the
-//! quality-tier emit factor is pinned at ×1.0 (max); Flamestrike's kit sound plays even though
-//! its kit has no type-9 proc (the ref couples sound to the emitter object — whether a
-//! procless kit still sounds is unread; the burn crackle missing would be the wronger look).
+//! Dest-anchored spell effects: what a ground cast shows at its point. A DynamicObject anchors a
+//! persistent area effect with two visuals, its own looping model and a shard emitter, outside the
+//! unit kit pipeline (no `PlaySpellVisualKit` `0x60edf0` call site is on this class), and
+//! `SMSG_SPELL_GO` plays a one-shot at the dest point.
 
 use bevy::prelude::*;
 
@@ -44,8 +11,7 @@ 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). `CharParamZero`'s decoded
-/// small int indexes it.
+/// The client's hardcoded shard-model table (`0x870e24`), indexed by `CharParamZero`'s small int.
 const SHARD_MODELS: [&str; 7] = [
     "Spells\\Blizzard_Impact_Base.mdx",
     "Spells\\RainOfFire_Impact_Base.mdx",
@@ -56,34 +22,25 @@ const SHARD_MODELS: [&str; 7] = [
     "Spells\\StarShards_Impact_Base.mdx",
 ];
 
-/// The `CharProcType` the dynobj emitter chain scans for (`0x5d55c0`). One key out of the same
-/// dispatch space the aura-state body procs come from (`crate::aura_visual`, decision 0806) — the
-/// kit column is shared, the consumers are not.
+/// The `CharProcType` whose first kit block the emitter chain takes (`0x5d55c0`).
 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` in `0x5d55c0`
-/// — data ≥ 7 reads past the table; a trap).
+/// `CharParamZero`'s small int ([`benilla_formats::char_proc_small_int`]), clamped into
+/// [`SHARD_MODELS`]: the client has no bounds check (`mov cl,al` in `0x5d55c0`) and reads past it.
 fn shard_model_index(param0: f32) -> usize {
     let idx = benilla_formats::char_proc_small_int(param0) as usize;
     idx.min(SHARD_MODELS.len() - 1)
 }
 
-/// A free-standing dest-anchored effect-model instance (visual A, a shard, a GO burst) —
-/// [`attach_ground_fx_models`] hangs the model parts once the M2 builds.
+/// A dest-anchored effect model: visual A, a shard or a GO burst.
 #[derive(Component)]
 pub(super) struct GroundFx {
     /// The [`SpellFx`] model-cache key.
     path: String,
-    /// `true` = loop the clip for the instance's whole life (visual A — the ref re-fires its
-    /// sequence on completion); `false` = one pass of sequence 0 then despawn (a shard, a
-    /// burst — the kit pipeline's self-termination clock).
+    /// Loop for life (visual A), or one pass of sequence 0 then despawn (a shard, a burst).
     looping: bool,
     /// Parts attached (the model was ready).
     spawned: bool,
-    /// The repeat override landed on the live `AnimationPlayer` (loop instances only).
     loop_armed: bool,
     /// One-shot self-termination deadline (`time.elapsed_secs()`), set at attach.
     expires: Option<f32>,
@@ -101,37 +58,35 @@ impl GroundFx {
     }
 }
 
-/// The shard emitter riding a DynamicObject anchor (visual B — the ref's `AUBlizzardObject`).
-/// Dies with the anchor (emission stops at destroy); its spawned shards are free entities and
-/// finish on their own — the ref's emitter tail.
+/// Visual B, a DynamicObject's shard emitter (`AUBlizzardObject`, `0x5d55c0`, `0x6ece30`). It dies
+/// with the anchor (`0x6ecf20` zeroes the rate); its shards are free entities that run out their
+/// own lifetimes.
 #[derive(Component)]
 pub(super) struct ShardEmitter {
     /// The [`SHARD_MODELS`] path.
     path: String,
-    /// `DYNAMICOBJECT_RADIUS` — the per-shard random spawn spread (the AoE footprint).
+    /// `DYNAMICOBJECT_RADIUS`: the wire radius is the spread (`0x6ebad0`).
     radius: f32,
-    /// Shards per second (`CharParamOne` × the quality factor, ×1.0 here).
+    /// Shards per second: `CharParamOne` times the graphics-quality factor, here its 1.0 maximum.
     rate: f32,
     /// Fractional emissions carried between frames.
     accum: f32,
-    /// A tiny LCG for the spawn offsets (the ref rolls real randoms; seeded per emitter).
+    /// xorshift* state for the spawn offsets, seeded per emitter: no rand dependency.
     rng: u64,
 }
 
-/// The router's dest one-shot order (`SMSG_SPELL_GO` + `TARGET_FLAG_DEST_LOCATION`, gate
-/// `SpellVisual` field 6 == 0 ∧ field 12 ≠ 0 — resolved router-side where the catalogs live).
+/// The router's dest one-shot: `SMSG_SPELL_GO` to a dest location plays `SpellVisual` field 12 once
+/// at the point when field 6, the missile, is 0 (`0x6e8088`..`0x6e8143`).
 #[derive(Message, Clone)]
 pub(crate) struct GroundBurst {
     /// The field-12 `SpellVisualEffectName` model path.
     pub(crate) path: String,
-    /// The dest point, bevy coords (converted at the apply seam).
+    /// The dest point, in Bevy coordinates.
     pub(crate) pos: Vec3,
 }
 
-/// Arm a freshly-created DynamicObject anchor: resolve the spell's visual row and hang the two
-/// visuals + the area sound (module doc). Runs on `Added<ObjectStore>` so the create's fields
-/// are the trigger; a dynobj is created once and never re-created in place (a re-cast is a new
-/// guid — captured live, 0797).
+/// Arm each new DynamicObject off its create's fields: visual A, the shard emitter and the area
+/// sound. A re-cast is a new guid, never a re-create in place.
 pub(super) fn arm_ground_effects(
     mut commands: Commands,
     created: Query<(Entity, &NetEntity, &ObjectStore), Added<ObjectStore>>,
@@ -164,8 +119,9 @@ pub(super) fn arm_ground_effects(
             .dynamicobject_position()
             .map(|(_, f)| f)
             .unwrap_or(0.0);
-        // Visual A — the object's own model, gated on field 11, Z-rotated by FACING. A child of
-        // the anchor: the destroy pop takes it exactly like the ref's scene-node teardown.
+        // Visual A (`0x5d57c0`): field 12's model when field 11 is set, at the object's position
+        // with no terrain projection, turned by `DYNAMICOBJECT_FACING` (`0x613ef0`, `0x7bdd60`);
+        // as a child it goes with the anchor.
         if stages.area_gate != 0 && stages.area_effect != 0 {
             if let Some(path) = visuals.0.effect_path(stages.area_effect) {
                 let path = path.to_string();
@@ -180,9 +136,9 @@ pub(super) fn arm_ground_effects(
                 commands.entity(anchor).add_child(child);
             }
         }
-        // Visual B — the shard emitter, from the area kit's first type-9 CharProc block; the
-        // kit's own sound column is the looping area sound (a tracked hold loop the sound
-        // module reaps when the anchor's NetEntity is removed).
+        // Visual B from field 13's kit, whose sound loops as the area sound: stopped at destroy,
+        // where the reference fades it over 3 s. A kit with no type-9 block sounds here; whether
+        // the reference, which ties the sound to the emitter, sounds it is untraced.
         if let Some(kit) = visuals.0.kit(stages.area_kit) {
             if let Some(proc) = kit.char_procs().find(|p| p.ty == PROC_TYPE_SHARD_EMITTER) {
                 let path = SHARD_MODELS[shard_model_index(proc.params[0])].to_string();
@@ -212,8 +168,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 (a trap).
+/// Spawn the GO dest one-shots at once, never waiting on the DynamicObject create that follows.
 pub(super) fn spawn_ground_bursts(
     mut commands: Commands,
     mut bursts: MessageReader<GroundBurst>,
@@ -231,9 +186,8 @@ pub(super) fn spawn_ground_bursts(
     }
 }
 
-/// Emit shards: `rate` per second, each a free one-shot instance at a random offset inside the
-/// wire radius (uniform over the disc, horizontal plane — the ref's per-particle spread scaled
-/// by `+0x11c`).
+/// Emit `rate` shards per second, each a free one-shot at a uniform random point of the radius's
+/// horizontal disc (the reference's spread scaled by `+0x11c`).
 pub(super) fn tick_shard_emitters(
     mut commands: Commands,
     time: Res<Time>,
@@ -243,7 +197,6 @@ pub(super) fn tick_shard_emitters(
         em.accum += em.rate * time.delta_secs();
         while em.accum >= 1.0 {
             em.accum -= 1.0;
-            // xorshift* — cheap, per-emitter deterministic, no rand dependency.
             let mut next = || {
                 em.rng ^= em.rng >> 12;
                 em.rng ^= em.rng << 25;
@@ -264,9 +217,8 @@ pub(super) fn tick_shard_emitters(
     }
 }
 
-/// Attach model parts to pending instances whose M2 finished building (the missile pattern —
-/// free world models, ground-anchored so authored flat quads decal to the terrain), start the
-/// one-shot clocks, and run both reapers (one-shot expiry; the loop-repeat override).
+/// Attach each pending instance's parts once its M2 builds, start the one-shot clocks, arm the
+/// loops and despawn expired one-shots.
 pub(super) fn attach_ground_fx_models(
     mut commands: Commands,
     time: Res<Time>,
@@ -286,19 +238,17 @@ pub(super) fn attach_ground_fx_models(
         if !inst.spawned {
             ensure_model(&mut fx, &asset_server, &inst.path);
             let Some(dm) = fx.models.get(&inst.path) else {
-                continue; // unreachable — just inserted
+                continue; // unreachable: just inserted
             };
             if !attach_effect_visuals(
                 &mut commands,
                 entity,
                 dm,
                 now,
-                true, // a dest-anchored area model's flat quads ARE ground decals
-                // A free world model standing at the point, chained to nothing: its trail stays
-                // world-frozen and its pool finishes in place when the effect ends.
+                true, // a dest-anchored model's flat quads are ground decals
+                // Chained to nothing: its trail stays world-frozen and its pool finishes in place.
                 super::spell_fx::EffectHost::default(),
-                // The dest one-shot is not a `CEffect` on a unit: it plants at the packet's point and
-                // runs its own span clock, so it keeps the plain single-clip arm.
+                // Not a `CEffect` on a unit: its own span clock, the plain single-clip arm.
                 None,
                 &mut FxMaterials {
                     store: &mut wow_materials,
@@ -310,19 +260,18 @@ pub(super) fn attach_ground_fx_models(
                 &mut palettes,
                 None,
             ) {
-                continue; // model still building — attach on a later pass
+                continue; // model still building
             }
             inst.spawned = true;
             if !inst.looping {
-                // One pass of the first sequence — the kit pipeline's completion-callback
-                // stand-in (`spell_fx`'s span clock, same law).
+                // One pass of the first sequence, as `spell_fx`'s span clock times a kit.
                 let span = dm.first_seq_span.unwrap_or(super::spell_fx::FALLBACK_SPAN);
                 inst.expires = Some(now + span);
             }
-            continue; // the AnimationPlayer lands next frame — the loop override waits
+            continue; // the AnimationPlayer lands next frame
         }
-        // The loop override: the ref re-fires the sequence on completion (`0x5d5580`); ours
-        // marks the live player's animations repeat-forever, once.
+        // The reference re-fires on completion (`0x5d5580`), the hardcoded sequence `0x9e` when
+        // `obj+0x190` bit 1 is set (its source untraced); this repeats the first clip.
         if inst.looping && !inst.loop_armed {
             if let Some(mut player) = player {
                 for (_, anim) in player.playing_animations_mut() {
@@ -343,10 +292,8 @@ pub(super) fn attach_ground_fx_models(
 mod tests {
     use super::*;
 
-    /// 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 — a
-    /// trap).
+    /// The `0x5d55c0` decode, `bits(f32(param0 + 512.0)) >> 14 & 0xff`; the real rows carry 0.0
+    /// (Blizzard) and 1.0 (Rain of Fire).
     #[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 dc019880..66bc19ba 100644
--- a/crates/benilla-app/src/entities/display.rs
+++ b/crates/benilla-app/src/entities/display.rs
@@ -1,9 +1,6 @@
-//! Per-display model cache + build (decision 0006) — the front half of [`super`].
-//!
-//! Resolves a creature/GameObject/held-item display id to a [`DisplayModel`] (loading its M2/WMO
-//! through the standard `AssetServer`, deduped by path) and, once the asset loads, builds its spawn
-//! parts once — shared by every entity of that display. [`super::attach`] then gives each net entity
-//! a visual from the built model.
+//! The per-display model cache: a creature, GameObject or held-item display id resolves to a
+//! [`DisplayModel`] whose spawn parts are built once, when its M2 or WMO loads, and shared by every
+//! entity of that display; [`super::attach`] gives each entity its visual from them.
 
 use avian3d::prelude::Collider;
 use benilla_assets::coords::wow_to_bevy;
@@ -19,152 +16,89 @@ use bevy::prelude::*;
 use benilla_assets::materials::WowModelMaterial;
 use benilla_assets::{m2_url, skin_url, wmo_url};
 
-/// A loaded display model's asset handle — an M2 (creatures, most GameObjects) or a WMO (building
-/// GameObjects). `None` ⇒ the display resolved to no model (invisible trigger / missing) → cube/none.
+/// A display's model asset: an M2 (creatures, most GameObjects), a WMO (building GameObjects), or
+/// none when the display names no model.
 pub(crate) enum ModelHandle {
     M2(Handle<M2Model>),
     Wmo(Handle<WmoModel>),
     None,
 }
 
-/// One spawn part of a display model: a submesh's mesh + its built `WowModelMaterial` + blend (for the
-/// `ModelPart` toggle). Built once the model asset loads **and** the model-forms furnisher has
-/// built its render forms (decision 0834 — the handles here come from the app-side cache, not the
-/// loader).
+/// One spawn part of a display model: a submesh's render forms and built materials.
 #[derive(Clone)]
 pub(super) struct EntityPart {
     pub(super) mesh: Handle<Mesh>,
-    /// The batch's decoded geometry — the model's resident CPU copy (`ModelSubmesh::geometry`),
-    /// cloned onto every spawned part/card as [`benilla_world::interact::PickMesh`] so the ray pickers read
-    /// triangles from here: the static render form is `RENDER_WORLD`-only (decision 0834), so no
-    /// main-world mesh data exists to ray-cast (decision 0857).
+    /// The resident CPU geometry, cloned onto each part as [`benilla_world::interact::PickMesh`]:
+    /// the render forms are `RENDER_WORLD`-only, leaving pickers no mesh to ray-cast.
     pub(super) geometry: std::sync::Arc<benilla_formats::RenderSubmesh>,
-    /// The static form's build-time `Aabb` (decision 0834): the static mesh is `RENDER_WORLD`-only,
-    /// so a consumer that used to compute a bound from its main-world data (the attach path's
-    /// picker-volume fallback) reads this instead. `None` for degenerate geometry.
+    /// The static form's build-time bound, the mesh itself being `RENDER_WORLD`-only.
     pub(super) aabb: Option<bevy::camera::primitives::Aabb>,
-    /// The skinned twin of [`Self::mesh`] (decision 0019), present for every M2 part. An animated
-    /// instance (a creature, or a GameObject that runs the state machine / loops a loader-idle seq)
-    /// renders this, skinned through its palette slot's rows (decision 0720); a truly static
-    /// instance uses `mesh`. `None` for WMO-display parts (no skeleton).
+    /// The skinned form of [`Self::mesh`], which an animated M2 instance draws.
     pub(super) skinned_mesh: Option<Handle<Mesh>>,
     pub(super) material: Handle<WowModelMaterial>,
-    /// The interior-lit variant (M2 only): the same material in the plain day/night matte
-    /// (`interior = false`, sun ×1.0 — the base-CGLight law), which the interior classifier
-    /// ([`benilla_world::interior`]) swaps to when the entity stands inside a WMO room. `None` for
-    /// WMO-display entities (their interior is per-submesh, already baked into `material`).
+    /// The M2 variant the interior classifier ([`benilla_world::interior`]) swaps to inside a WMO
+    /// room: the plain day/night matte, sun ×1.0. A WMO part's interior is baked into `material`.
     pub(super) material_interior: Option<Handle<WowModelMaterial>>,
-    /// 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` `0x6716f0`), so one law lights them all indoors
-    /// (`0x6a7300`, superseding the 0315 unit/GO split). `None` for WMO parts.
+    /// The interior-prop variant, whose `MeshTag` the shader reads as an SH-probe slot. Units and
+    /// GameObjects alike take it: the reference registers every entity M2 with one entity-node fill
+    /// (`Node::SetModel` `0x6716f0`), so one law lights them all indoors (`0x6a7300`).
     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
-    /// feather instead of jumping to the exterior twin's lit-outdoor intensity (0355).
+    /// The bake variant's blend form, so a fading bake-lit part keeps its probe light.
     pub(super) material_interior_bake_blend: Option<Handle<WowModelMaterial>>,
-    /// The `AlphaMode::Blend` twin of the exterior material, for the spawn appear-fade ([`RenderFade`]):
-    /// the entity feathers in on this while `α < 1`, then swaps back to `material`. `Some` for M2 parts
-    /// (creatures + M2 GameObjects, the CGObjects that appear-fade); `None` for WMO-display parts.
+    /// The exterior material's blend form, worn during the spawn appear-fade (`RenderFade`).
     pub(super) fade_blend: Option<Handle<WowModelMaterial>>,
-    /// The **depth-prime twin** material ([`benilla_world::model_render::zfill_material`] — the reference's
-    /// `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
-    /// disables z-write/z-test (the reference's own `(flags & 0x10) == 0` twin gate) or cannot
-    /// fade at all (Mod/Mod2x), and for WMO-display parts.
+    /// The depth-prime form ([`benilla_world::model_render::zfill_material`], the reference's
+    /// `M2UseZFill` clone, `0x707f7d`–`0x708072`): a translucent part's colour-masked, z-writing
+    /// child draws it first, so a fading or stealthed body blends as one layer. `None` when the
+    /// batch disables z-write or z-test (the reference's `(flags & 0x10) == 0` gate) or cannot fade
+    /// (Mod/Mod2x).
     pub(super) zfill: Option<Handle<WowModelMaterial>>,
     pub(super) blend: ModelBlend,
-    /// Whether this part blends **additively** (M2 blend mode 3 `NoAlphaAdd` / 4 `Add`).
-    /// [`ModelBlend`] deliberately folds "alpha-blended / additive" into its single `Blend`
-    /// variant, so [`Self::blend`] alone CANNOT answer this — the material path recovers it from
-    /// [`benilla_world::model_render`]'s separate `is_additive` input (marker bit 2 of `clutter_fade.z`,
-    /// which `specialize` turns into the pure-add state). Any consumer that re-derives a blend
-    /// state from `blend` needs this alongside it, or every additive batch silently draws
-    /// alpha-blended — decision 0748, the black ground-decal tile.
+    /// Additive blending (M2 blend mode 3 `NoAlphaAdd` or 4 `Add`), which [`ModelBlend`]'s single
+    /// `Blend` variant folds in with alpha: anything re-deriving a blend state from `blend` needs
+    /// this too, or an additive batch draws alpha-blended.
     pub(super) additive: bool,
-    /// Whether this part renders two-sided (M2 material `0x04`). Retained so a per-appearance material
-    /// swap (the character hair, decision 0045 — hair cards are two-sided) preserves it; `part.material`
-    /// already bakes it for the un-swapped parts.
+    /// Two-sided (M2 material flag `0x04`), kept so a per-appearance material swap preserves it.
     pub(super) two_sided: bool,
-    /// The part's `skinSectionId` (geoset / mesh-part ID). For a player body the per-entity attach
-    /// filters parts by it (only the selected hair/facial/body geosets spawn); **unfiltered for
-    /// everything else — which is correct, but NOT because those models have a single geoset.**
-    ///
-    /// 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 (`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.
+    /// The part's `skinSectionId` (geoset id). A player body's attach spawns only the selected
+    /// geosets; every other model draws whole, even with several authored (101 creature models):
+    /// the reference's visibility array starts all visible and only the character compositor
+    /// writes it, which a creature never reaches (`0x5fb200`).
     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
-    /// (decisions 0041 / 0044 / 0045); `None` and ignored otherwise (it keeps its built material).
+    /// The character texture slot (type 1 body, 6 hair) a player's attach re-skins per appearance.
     pub(super) char_slot: Option<CharSkinSlot>,
-    /// A billboard batch (glow card / chain): its pivot + facing info. The spawn sites must NOT
-    /// spawn it as an ordinary child — its mesh is centred at the bone pivot and its transform is
-    /// owned by the billboard system (a following [`benilla_world::billboard::BillboardCard`], decision
-    /// 0153: the brazier/torch "glow on the ground" family). `None` for ordinary geometry.
+    /// A billboard batch's pivot and facing. Never spawn it as an ordinary child: its mesh is
+    /// centred at the bone pivot and a following `BillboardCard` owns its transform.
     pub(super) billboard: Option<benilla_assets::BillboardInfo>,
-    /// This part's geometry is **welded** to a billboard bone the card split refused
-    /// ([`benilla_formats::RenderSubmesh::welded_billboard`], decision 0839): a shoulder flap whose
-    /// root ring is half-weighted to the plate and whose tip swings to the camera. It draws right
-    /// only through a joint palette, which is why a display carrying one makes even the **item**
-    /// lane rig ([`DisplayModel::welds_billboard`], decision 0841). `false` for every ordinary part.
+    /// Geometry welded to a billboard bone the card split refused, which draws right only through a
+    /// joint palette ([`DisplayModel::welds_billboard`]).
     pub(super) welded_billboard: bool,
-    /// The part's animated material-alpha loops (colour-alpha × transparency-weight, decision 0130
-    /// phase 2, per-sequence since 0641). The **effect lane** ([`super::spell_fx`]) samples them
-    /// per instance on its armed slot; the unit/GameObject lane follows the host's live playing
-    /// sequence (`MatAnim::following` — 0641 collected the old deferral here). `None` for static
-    /// batches.
+    /// The animated material alpha per sequence, colour alpha × transparency weight.
     pub(super) alpha_anim: Option<std::sync::Arc<benilla_formats::AlphaAnim>>,
-    /// The part's animated RGB tint (the M2Color colour track, time-varying only). The static
-    /// vertex tint was skipped at parse for these parts: `material`/its variants are built with
-    /// the **first key** seeded as the material tint (pixel-identical to the old static bake);
-    /// the effect lane clones + ticks the tint per instance. `None` for constant tints.
+    /// The animated RGB tint (the M2Color track, time-varying only), its first key seeded into the
+    /// materials.
     pub(super) rgb_anim: Option<std::sync::Arc<benilla_formats::RgbAnim>>,
-    /// The per-file-sequence-slot form of [`Self::rgb_anim`], carried only where the slots
-    /// disagree (decision 1408) — [`Self::uv_seq`]'s twin, and the reason a GameObject may need a
-    /// material of its own. Five batches on three GameObject models author one, and **four of
-    /// them bake nothing in slot 0**, so `rgb_anim` is `None` for them and a shared material can
-    /// only ever seed white: the hunter's Freezing Trap glow card is the class (decision 2295).
+    /// [`Self::rgb_anim`] per file sequence slot, only where the slots disagree: four of the five
+    /// such batches are empty in slot 0, so a shared material would seed white (Freezing Trap).
     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, `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
-    /// WMO parts.
+    /// The texture-transform translation that scrolls the batch's UVs (`0x70b740`).
     pub(super) uv_anim: Option<std::sync::Arc<benilla_formats::UvAnim>>,
-    /// The per-file-sequence-slot form of [`Self::uv_anim`], carried only where the slots
-    /// disagree (decision 1408) — an effect that advances `Stand` → `Hold` → `Decay` reads the
-    /// slot it is actually playing. `None` for every batch whose slots agree.
+    /// [`Self::uv_anim`] per file sequence slot, only where the slots disagree, so an effect
+    /// advancing `Stand` → `Hold` → `Decay` reads the slot it plays.
     pub(super) uv_seq: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 2]>>>,
-    /// The texture transform's **rotation** loop per file sequence slot (decision 2019) and its
-    /// scaling twin. Three effect models in the whole 1.12 corpus author them — Shield Wall's
-    /// halo turns *and* scales, Grounding Totem's glow is a scale-only transform — which is
-    /// precisely why the effect lane has to read them from the asset rather than from memory
-    /// (`benilla-extract fxuvscan`). `None` everywhere else.
+    /// The texture transform's rotation loop per file sequence slot, and below it the scaling one;
+    /// three effect models author them (`benilla-extract fxuvscan`), Shield Wall's halo among them.
     pub(super) uv_rot_seq: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 4]>>>,
     pub(super) uv_scale_seq: Option<std::sync::Arc<benilla_formats::SeqLoops<[f32; 2]>>>,
-    /// The part's flat **ground-plane quad** shape (detected at M2 load — see
-    /// [`benilla_formats::GroundQuad`]). On a base-anchored spell effect the fx attach renders it
-    /// as a projected surface decal ([`crate::ground_fx`]) instead of free geometry, so it drapes
-    /// terrain like the selection ring. `None` for ordinary geometry and all WMO parts.
+    /// A flat ground-plane quad ([`benilla_formats::GroundQuad`]), which a base-anchored spell
+    /// effect draws as a terrain-draping decal (`benilla_world::ground_fx`).
     pub(super) ground_quad: Option<benilla_formats::GroundQuad>,
 }
 
 impl EntityPart {
-    /// This part's four baked texture-transform channels, in the shape the engine's lanes take
-    /// them — **the one place a spawner reads them**, so "does this batch animate its transform"
-    /// has a single answer wherever it is asked (the effect attach's clone test, the entity
-    /// spawn's [`benilla_world::doodad_anim::AnimMatPart`] marker). `UvLoops::animates` is that
-    /// question: a scale-only transform and a dead-slot-0 translation each answer `None` to the
-    /// channel you would check first.
+    /// The four texture-transform channels as the engine's lanes take them, the one place a spawner
+    /// reads them. Ask `UvLoops::animates`: a scale-only transform or a dead slot-0 translation is
+    /// `None` on the channel you would check first.
     pub(super) fn uv_loops(&self) -> benilla_world::doodad_anim::UvLoops {
         benilla_world::doodad_anim::UvLoops {
             seqs: self.uv_seq.clone(),
@@ -175,158 +109,96 @@ impl EntityPart {
     }
 }
 
-/// Everything needed to render one display id, cached so a model is loaded + built once and shared by
-/// every entity of that display. `parts` is `None` while the asset loads, then `Some` — empty if the
-/// model failed / has no geometry (→ cube/none fallback), else the spawn parts.
+/// Everything needed to render one display id, built once and shared by its entities; `parts` is
+/// `None` while the asset loads, and empty for a model with no geometry.
 pub(crate) struct DisplayModel {
     pub(crate) handle: ModelHandle,
-    /// The model's directory (for creature skin paths); empty for WMOs / no-skin models.
+    /// The model's directory, where its skin textures live.
     pub(super) dir: String,
-    /// Creature `Monster1/2/3` skin variation names; all `None` for GameObjects.
+    /// The creature's `Monster1/2/3` skin variation names.
     pub(super) skins: [Option<String>; 3],
-    /// A character-model NPC's body appearance (CreatureDisplayInfoExtra, decision 0041's creature
-    /// chain): its race/sex + customization selectors + the pre-baked body-atlas name. `Some` only for a
-    /// humanoid NPC display; `None` for a beast (Monster skins instead), a GameObject, or a *player*
-    /// display (a player's appearance is on the wire — its `ObjectStore`, not here). The per-entity
-    /// attach reads it to skin + geoset-filter a character-model NPC the same way it does a player.
+    /// A humanoid NPC's body from `CreatureDisplayInfoExtra` (race, sex, customization, the baked
+    /// body atlas), skinned and geoset-filtered as a player's is; a player's own rides the wire.
     pub(super) npc_appearance: Option<NpcAppearance>,
-    /// A held item display's runtime **object skin** — the ItemDisplayInfo model-texture basename
-    /// (decision 0072), bound to the model's type-2 batches ([`CharSkinSlot::Object`]) at build, from
-    /// [`Self::dir`]. `None` for creature/GameObject displays (their type-2 batches — a body model's
-    /// cape slot — stay untextured until equipment provides one).
+    /// A held item's object skin, the `ItemDisplayInfo` texture bound to type-2 batches
+    /// ([`CharSkinSlot::Object`]) from [`Self::dir`].
     pub(super) object_texture: Option<String>,
     pub(super) parts: Option<Vec<EntityPart>>,
-    /// The model's particle emitters (flames/glows), captured alongside `parts` when the asset loads.
-    /// Spawned per entity in [`attach_entity_visuals`], owned-by + following that entity. Empty for
-    /// WMOs / no-emitter models.
     pub(super) emitters: Vec<ModelEmitter>,
-    /// The model's ribbon emitters (weapon trails, wisp streamers), captured like `emitters`.
     pub(super) ribbons: Vec<benilla_assets::ModelRibbon>,
-    /// The model's **M2 light blocks**, captured like `emitters` — the authored dynamic light an
-    /// entity carries into the world (decision 0016). The common case is the **held torch**:
-    /// `Club_1H_Torch_A_01.m2` authors one warm `type==1` point light, which is why a torch-bearing
-    /// NPC lights the fence rails and grass around him on the reference. Empty for WMOs and for the
-    /// ~all models that author none.
+    /// The model's M2 lights, the dynamic light an entity carries: a held torch
+    /// (`Club_1H_Torch_A_01.m2`, one `type == 1` point light) lights the ground around its bearer.
     pub(super) lights: Vec<benilla_assets::ModelLight>,
-    /// Model-local collision collider, baked once from the model's collision hull when the asset loads —
-    /// built **only for GameObjects** (creatures use unit-collision, not modeled here). `None` for a
-    /// hull-less model (collide-iff-hull): that's why a herb/small prop is non-solid while a chest, mining
-    /// vein, or door collides. Cloned (Arc-shared shape) onto each instance in [`attach_entity_visuals`],
-    /// where the entity's own pose places it.
+    /// The model-local collider from the collision hull, GameObjects only; a hull-less model does
+    /// not collide, so a herb is walk-through while a chest, vein or door is solid.
     pub(super) collider: Option<Collider>,
-    /// The model's rest skeleton (decision 0019), captured with `parts` when an M2 asset loads. The
-    /// creature attach path spawns one joint entity per bone from it, per instance. Empty for WMO /
-    /// boneless / model-less displays.
     pub(super) skeleton: ModelSkeleton,
-    /// The model's attachment points (decision 0072), captured with `parts` on load: id → bone +
-    /// Bevy-space offset. The attach path folds them into each instance's [`BoneAttach`] so held
-    /// items (and future bone riders) can hang from the hand/hip/back joints. Empty for WMO / static.
+    /// Attachment points (id → bone and Bevy-space offset) for each instance's `BoneAttach`.
     pub(super) attachments: Vec<benilla_assets::ModelAttachment>,
-    /// The model's animation-event positional markers, captured with `parts` on load: 4CC →
-    /// bone + Bevy-space offset, file order (first-match queries). The attach path folds them into
-    /// [`BoneAttach`] beside the attachments — the missile launch points ($CSL/$CSR/$CST/$BWR).
+    /// Animation-event markers (FourCC → bone and offset, in file order, first match wins), such as
+    /// the missile launch points `$CSL`/`$CSR`/`$CST`/`$BWR`.
     pub(super) markers: Vec<benilla_assets::ModelMarker>,
-    /// The matching inverse bind poses, shared across every instance of this display. `Some` for an M2
-    /// display, `None` for WMO / model-less. Paired with `skeleton` to build each instance's palette rig.
     pub(super) inverse_bindposes: Option<Handle<SkinnedMeshInverseBindposes>>,
-    /// The model's animations (decision 0019), captured with `parts` on load. The creature attach path
-    /// gives each instance an `AnimationPlayer` driving them (playing Stand). `None` for WMO / static.
     pub(super) animations: Option<ModelAnimations>,
-    /// The file-order-first sequence's authored duration ([`M2Model::first_seq_span`]), captured with
-    /// `parts` on load — the spell-fx self-termination clock for a model whose sequences build no clip
-    /// (the eat/drink tankard: a 6.667 s sequence, zero bone keys). `None` for WMO / sequence-less.
+    /// The first sequence's authored duration, the spell-effect clock for a model whose sequences
+    /// build no clip (the eat/drink tankard: 6.667 s, no bone keys).
     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 (`0x50cbc0`).
-    /// `0.0` for a bounds-less / WMO / model-less display (→ the camera floors it).
+    /// The camera framing pivot's height in model-local yards before scale (`0x50cbc0`), stamped on
+    /// each instance as `CameraPivot`; `0.0` without bounds.
     pub(super) pivot_height_local: f32,
-    /// How far that framing pivot drops while this body **swims**, model-local yards, pre-scale —
-    /// [`M2Bounds::swim_pivot_drop`], captured in [`build_parts`] beside the height it modifies.
-    /// The reference builds its swim preset `cam+0x124` as the standing height less exactly this
-    /// (`0x50ccf6`: `StandSeq.bounds.max.z − SwimSeq.bounds.max.z`) and `0x50f880` picks it on
-    /// MOVEFLAG_SWIMMING. Stamped onto each instance as [`CameraPivot::swim_drop_local`]. `0.0` for
-    /// a model with no Swim sequence (every non-character model) and for a bounds-less / WMO /
-    /// model-less display — the swim preset then simply is the standing one.
+    /// How far that pivot drops while swimming: the reference's swim preset `cam+0x124` is the
+    /// standing height less `StandSeq.max.z − SwimSeq.max.z` (`0x50ccf6`), picked on
+    /// `MOVEFLAG_SWIMMING` (`0x50f880`); `0.0` without a Swim sequence, the reference's own guard.
     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` (`0x608e00`/`0x60aee0`, emulated to the
-    /// reference pixels). `0.0` for a bounds-less / WMO / model-less display (the ring then uses a fallback).
+    /// The selection ring's radius in model-local yards before scale, the Stand footprint
+    /// `sqrt(0.5 · sqrt(dx² + dy²))`, scaled by `OBJECT_FIELD_SCALE_X` (`0x608e00`/`0x60aee0`).
     pub(super) ground_radius_local: f32,
-    /// 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).
+    /// The authored portrait camera the portrait booth frames through (`0x713540`).
     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 (`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.
+    /// Camera-table index 1, the rig a `<PlayerModel>` widget renders through (`0x505890`); without
+    /// it the reference uses its fixed fallback camera.
     pub(super) pane_camera: Option<benilla_assets::PortraitCamera>,
-    /// 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.
+    /// A bow's `$WTT`/`$WTB` string anchors (`0x611ff0`), `[top, bottom]` as
+    /// `(bone, model-local Bevy position)`.
     pub(super) string_anchors: Option<[(u16, Vec3); 2]>,
-    /// 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.
+    /// A fishing pole's `$CCH` line anchor (`0x61f780`) in mesh-frame Bevy space.
     pub(super) cch_marker: Option<Vec3>,
-    /// The authored bbox z-extent (`maxZ − minZ`, model-local yards, pre-scale) — the overhead-anchor
-    /// fallback's input (`0x608640`: a unit whose model has no PlayerName attachment anchors overhead
-    /// text at `feet + scale × this × 1.25`). `0.0` for a bounds-less display.
+    /// The authored bbox z-extent in model-local yards before scale: a model with no PlayerName
+    /// attachment anchors overhead text at `feet + scale × this × 1.25` (`0x608640`).
     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`; 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.
+    /// The Stand sequence box's z-extent, the chat bubble's anchor height (`0x711a20`): a file
+    /// constant, so the bubble never moves with the pose as the overhead name does.
     pub(super) stand_box_z_local: f32,
-    /// The M2 vertex-box CENTRE in Bevy model-local (pre-scale) — the interior fold's MOLR
-    /// 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.
+    /// The vertex-box centre in Bevy model space, the interior fold's MOLR reference point for a
+    /// GameObject (the reference's `[def+0x5c]` anchor).
     pub(super) bake_center_local: Vec3,
-    /// 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.
+    /// MD20 `GlobalModelFlags & 3` (`0x7106c0`): `1` pitches to the slope, `3` pitches and rolls,
+    /// anything else stays level.
     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 (the `0x60c690` getter family).
+    /// A `Character\` model, the gate for the customization pipeline. It follows the display, not
+    /// the entity kind (a druid in bear form wears a creature model), as the reference's race and
+    /// gender getters read the display's row (`0x60c690`).
     pub(super) is_character_body: bool,
 }
 
 impl DisplayModel {
-    /// Does any built part weld geometry to a billboard bone
-    /// ([`EntityPart::welded_billboard`], decision 0839)? Such a part has no correct rigid
-    /// placement — the reference blends it per vertex — so the lane that draws it must run a joint
-    /// palette even where it otherwise wouldn't. The rigged lanes always do; this is the gate that
-    /// makes the **item** lane rig for the seven shoulder models that need it (decision 0841).
-    /// `false` while the model is still loading, and for the other 9684 models in the game.
+    /// Whether a built part is welded to a billboard bone: it has no rigid placement (the reference
+    /// blends it per vertex), so even the item lane must rig for it (seven shoulder models).
     pub(super) fn welds_billboard(&self) -> bool {
         self.parts
             .as_ref()
             .is_some_and(|p| p.iter().any(|part| part.welded_billboard))
     }
 
-    /// Does this display name a model FILE at all? The line between **"the model's own answer is
-    /// draw nothing"** and **"we could not resolve one"** — which are the same empty `parts` list
-    /// and must never be treated alike (decision 1403).
-    ///
-    /// `true` once a display resolved through its catalog to a path we handed the asset server;
-    /// `false` only for [`empty_display`] — a display id absent from `CreatureDisplayInfo` /
-    /// `GameObjectDisplayInfo`, a zero-scale row, or a GameObject display naming no path. That
-    /// second set is *our* gap, and the debug cube is how a session sees it.
+    /// Whether the display names a model file. An empty `parts` from a named model is that model's
+    /// answer, draw nothing; [`empty_display`] (no catalog row, a zero-scale row, no model path) is
+    /// an unresolved display, and earns the debug cube.
     pub(super) fn names_a_model(&self) -> bool {
         !matches!(self.handle, ModelHandle::None)
     }
 }
 
-/// Resolve a creature display id to a [`DisplayModel`]: load its M2 (no skins — the slots are filled at
-/// build time from `textures`). A missing/zero-scale display gets an empty model → cube fallback.
+/// A creature display's M2, its skins filled at build; a missing or zero-scale row is empty.
 pub(super) fn new_creature_display(
     catalog: &CreatureCatalog,
     display_id: u32,
@@ -348,8 +220,7 @@ pub(super) fn new_creature_display(
     }
 }
 
-/// Resolve a GameObject display id to a [`DisplayModel`]: load its M2 or WMO by path. No model path
-/// (invisible trigger) gets an empty model → no render.
+/// A GameObject display's M2 or WMO; one with no model path is empty.
 pub(super) fn new_gameobject_display(
     catalog: &GameObjectCatalog,
     display_id: u32,
@@ -369,8 +240,7 @@ pub(super) fn new_gameobject_display(
     }
 }
 
-/// A blank [`DisplayModel`] shell — `parts: None` (awaiting [`build_parts`]) and every capture field
-/// at its default — for constructors that override only what their source provides.
+/// A blank [`DisplayModel`] awaiting [`build_parts`], for constructors to override.
 pub(crate) fn empty_shell() -> DisplayModel {
     DisplayModel {
         handle: ModelHandle::None,
@@ -404,7 +274,7 @@ pub(crate) fn empty_shell() -> DisplayModel {
     }
 }
 
-/// A display with no model — `parts` already resolved to empty, so attach renders a cube/nothing.
+/// A display with no model, its `parts` already empty.
 pub(super) fn empty_display() -> DisplayModel {
     DisplayModel {
         parts: Some(Vec::new()),
@@ -412,29 +282,23 @@ pub(super) fn empty_display() -> DisplayModel {
     }
 }
 
-/// Build a display model's spawn parts once its asset has loaded — each submesh's `WowModelMaterial`,
-/// with a creature skin slot filled from the display's variation (`<dir>\<name>.blp`). Returns early
-/// (leaving `parts` `None`) while the asset is still loading.
+/// Build a display's spawn parts once its asset and render forms are ready, filling a creature skin
+/// slot from the display's variation (`<dir>\<name>.blp`); until then `parts` stays `None`.
 pub(super) fn build_parts(
     dm: &mut DisplayModel,
     m2s: &Assets<M2Model>,
     wmos: &Assets<WmoModel>,
-    // The app-built render forms (decision 0834): parts wait for the furnisher exactly as they
-    // wait for the asset. Entity displays request at priority 0 — a mob walking into view never
-    // queues behind a city crossing's scenery (whose placements request at 16+).
+    // Entity displays request forms at priority 0, ahead of scenery placements (16 and up).
     forms: &mut benilla_world::model_forms::ModelForms,
     asset_server: &AssetServer,
     mats: &mut benilla_world::model_render::M2BatchMaterials,
-    // Where this display's animated texture transforms are delivered (decision 2295) — taken
-    // rather than reached for, because building an entity batch's material and putting it on the
-    // lane are one act.
+    // Where the display's animated texture transforms go as its materials are built.
     uv: &mut benilla_world::model_render::EntityUvLane<'_>,
-    // Whether this display is a GAMEOBJECT: gates the hull-collider build (chests/veins/doors;
-    // creatures use unit collision).
+    // Only a GameObject builds the hull collider.
     gameobject: bool,
 ) {
     if !mats.ready() {
-        return; // no shared light buffer yet — retry next frame, like a still-loading asset
+        return; // no shared light buffer yet; retry next frame
     }
     let mut emitters = Vec::new();
     let mut ribbons = Vec::new();
@@ -462,51 +326,30 @@ pub(super) fn build_parts(
             let Some(model) = m2s.get(h) else {
                 return; // still loading
             };
-            // Every M2 entity lane can rig (creatures, animated GameObjects, held items with
-            // billboard chains), so both forms are requested; the static form still serves the
-            // truly static instances and the billboard cards.
+            // Every M2 lane can rig, so both forms are requested; static instances and billboard
+            // cards draw the static one.
             if !forms.require_rigged(h, 0) {
-                return; // forms still building — same retry-next-frame as the asset itself
+                return; // forms still building
             }
             emitters = model.emitters.clone();
             ribbons = model.ribbons.clone();
             lights = model.lights.clone();
             terrain_tilt = (model.global_flags & 3) as u8;
-            // 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 (`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).
+            // Not the render sphere (`0xCC`), which sizes the corpse decal (`0x5d6fe0`).
             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`): **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
-            // head), exactly why the old fixed 3.0 rode high.
+            // Attachment 17's Z + 0.0972, about neck height on every character model, else 0.9 ×
+            // the vertex-box Z extent, a box that spans every animation (`0x50cbc0`).
             pivot_height_local = model.bounds.map_or(0.0, |b| {
                 b.pivot_z
                     .map(|z| z + 0.0972)
                     .unwrap_or_else(|| 0.9 * (b.bbox_max[2] - b.bbox_min[2]).max(0.0))
             });
-            // The camera's SWIM framing-pivot preset, as the delta the reference stores it as: the
-            // standing height above less `StandSeq.max.z − SwimSeq.max.z` is `cam+0x124`
-            // (`0x50ccf6`), and `0x50f880` selects it whenever the camera target carries
-            // MOVEFLAG_SWIMMING. `0.0` for a model with no Swim sequence, which is the reference's
-            // own both-present guard and means a body that cannot swim keeps one height.
             swim_pivot_drop_local = model.bounds.map_or(0.0, |b| b.swim_pivot_drop);
-            // The raw vertex-box z-extent — the overhead-anchor FALLBACK's input (see the struct
-            // field). Kept separate from the pivot: the fallback is the client's own formula, and
-            // only fires for a model with no PlayerName attachment.
             bbox_z_local = model
                 .bounds
                 .map_or(0.0, |b| (b.bbox_max[2] - b.bbox_min[2]).max(0.0));
-            // The chat bubble's anchor height — the STAND sequence box's Z, off the same parse the
-            // selection ring takes its XY from, so the two can never resolve different animations.
+            // The same Stand box the ring's footprint reads.
             stand_box_z_local = model.bounds.map_or(0.0, |b| b.stand_box_z);
-            // The vertex-box centre (Bevy local) — a GameObject's interior-fold reference point.
             bake_center_local = model.bounds.map_or(Vec3::ZERO, |b| {
                 benilla_assets::coords::wow_to_bevy([
                     (b.bbox_min[0] + b.bbox_max[0]) * 0.5,
@@ -514,9 +357,6 @@ pub(super) fn build_parts(
                     (b.bbox_min[2] + b.bbox_max[2]) * 0.5,
                 ])
             });
-            // The rest skeleton + shared inverse bind poses + the animation graph (decision 0019) — the
-            // creature attach path spawns a joint hierarchy + an AnimationPlayer from these. Captured
-            // here, with `parts`, on load.
             skeleton = model.skeleton.clone();
             attachments = model.attachments.clone();
             markers = model.markers.clone();
@@ -544,21 +384,13 @@ pub(super) fn build_parts(
                         dm.object_texture.as_deref(),
                         asset_server,
                     );
-                    // The authored batch order (index + 1), into every variant's transparent sort
-                    // bias — one model's coplanar transparent batches (the Naxx items' Mod2x
-                    // sheen + Blend overlay) draw in file order instead of re-flipping a sort tie
-                    // every frame (`model_render::BATCH_ORDER_SORT_EPS`).
+                    // The authored batch order (index + 1) biases the transparent sort, so coplanar
+                    // transparent batches draw in file order instead of flipping a tie each frame.
                     let order = u16::try_from(pi + 1).unwrap_or(u16::MAX);
-                    // The whole variant set for this batch — steady, the indoor pair, their
-                    // blend twins and the depth-prime twin — built once by the engine, which owns
-                    // the law that decides which of them collapse onto each other (decisions 0842
-                    // / 0865 / 0831 / 0355). `None` cannot happen here: the caller gated on the
-                    // light buffer before the first build.
                     let v = mats.entity_variants(sub, texture, order, uv);
                     let v = v.expect("light buffer checked at entry");
                     EntityPart {
-                        // Index-parallel with the submeshes by the forms contract; a miss is a
-                        // broken contract — a default (dead) handle draws nothing rather than panic.
+                        // Index-parallel with the submeshes; a miss draws nothing, never panics.
                         mesh: stat_forms
                             .get(pi)
                             .map(|(h, _)| h.clone())
@@ -595,7 +427,7 @@ pub(super) fn build_parts(
             let Some(model) = wmos.get(h) else {
                 return;
             };
-            // WMO-display GameObjects never skin — static forms only.
+            // WMO-display GameObjects never skin: static forms only.
             if !forms.require_static(h, 0) {
                 return;
             }
@@ -614,30 +446,28 @@ pub(super) fn build_parts(
                         .unwrap_or_default(),
                     geometry: sub.geometry.clone(),
                     aabb: stat_forms.get(pi).and_then(|(_, a)| *a),
-                    geoset_id: sub.geoset_id, // 0 for WMO — no geoset selection
+                    geoset_id: sub.geoset_id, // 0 for WMO: no geoset selection
                     char_slot: None,          // WMO is never a character body
-                    skinned_mesh: None,       // WMO-display GameObjects don't skin (no skeleton)
-                    // A WMO-display GameObject draws one material per batch: its interior law
-                    // is per-submesh and already baked into the batch (MOBA class + SIDN +
-                    // WINDOW), so there is no M2 footprint-probe pair to build. Batch order 0 —
-                    // these are single-building props, not the streamer's coplanar MOBA stacks.
+                    skinned_mesh: None,       // no skeleton to skin
+                    // One material per batch, interior light baked per submesh (MOBA class, SIDN,
+                    // WINDOW); batch order 0: one building, not the streamer's coplanar stacks.
                     material: mats
                         .steady(sub, sub.texture.clone(), 0)
                         .expect("light buffer checked at entry"),
-                    material_interior: None, // WMO entity: interior is per-submesh, baked into `material`
-                    material_interior_bake: None, // …and never the M2 footprint lane
+                    material_interior: None, // interior is baked into `material`
+                    material_interior_bake: None, // never the M2 footprint lane
                     material_interior_bake_blend: None,
-                    fade_blend: None, // WMO-display GameObjects don't appear-fade (rare; M2 only)
-                    zfill: None,      // …so they never need the depth-prime twin either
+                    fade_blend: None, // WMO-display GameObjects do not appear-fade
+                    zfill: None,      // so no depth-prime form either
                     blend: sub.blend,
-                    additive: false, // WMO MOMT carries no additive mode (`RenderSubmesh::additive`)
+                    additive: false, // WMO MOMT has no additive mode
                     two_sided: sub.two_sided,
                     billboard: None,         // WMO groups have no billboard bones
-                    welded_billboard: false, // …so nothing can be welded to one
-                    alpha_anim: None,        // …nor colour/weight loops
+                    welded_billboard: false, // so nothing is welded to one
+                    alpha_anim: None,        // nor colour or weight loops
                     rgb_anim: None,
                     rgb_seq: None,
-                    uv_anim: None, // …nor texture transforms (WMO has none)
+                    uv_anim: None, // nor texture transforms
                     uv_seq: None,
                     uv_rot_seq: None,
                     uv_scale_seq: None,
@@ -671,10 +501,8 @@ pub(super) fn build_parts(
     dm.terrain_tilt = terrain_tilt;
 }
 
-/// Bake a model-local avian trimesh collider from a model's raw-WoW collision hull, mapping each vertex
-/// through `wow_to_bevy` so it coincides with the entity's rendered submeshes (same convention as the
-/// map-doodad [`benilla_world::terrain_stream`] bake, minus the placement — the entity's own pose places it).
-/// `None` for a hull-less or degenerate mesh: collide-iff-hull, so herbs/props stay non-solid.
+/// A model-local trimesh collider from the raw collision hull, through `wow_to_bevy` like the
+/// rendered submeshes; `None` for a hull-less or degenerate hull, which does not collide.
 fn model_local_collider(hull: &CollisionMesh) -> Option<Collider> {
     if hull.indices.len() < 3 {
         return None;
@@ -690,10 +518,9 @@ fn model_local_collider(hull: &CollisionMesh) -> Option<Collider> {
     Some(Collider::trimesh(verts, tris))
 }
 
-/// A submesh's texture: its embedded one; for an unfilled creature skin slot, the display's variation
-/// (`<dir>\<name>.blp`); for a runtime **object** slot (M2 type 2 — a held item's blade/face skin),
-/// the display's ItemDisplayInfo model texture, same folder (decision 0072). `None` ⇒ untextured
-/// (the material's muted fallback — e.g. a body model's cape slot with nothing equipped).
+/// A submesh's texture: its embedded one, else the display's creature variation
+/// (`<dir>\<name>.blp`) for a skin slot, or its `ItemDisplayInfo` texture for an object slot (M2
+/// type 2); `None` draws the material's muted fallback.
 fn resolve_skin(
     sub: &ModelSubmesh,
     dir: &str,
@@ -714,8 +541,7 @@ fn resolve_skin(
     }
 }
 
-/// The directory of a model path (`Creature\Kobold\Kobold.mdx` → `Creature\Kobold`), where its skin
-/// variation BLPs live. Empty if the path has no directory component.
+/// `Creature\Kobold\Kobold.mdx` → `Creature\Kobold`, where the skin variations live.
 fn model_dir(model_path: &str) -> &str {
     model_path
         .rsplit_once(['\\', '/'])
@@ -727,11 +553,8 @@ fn model_dir(model_path: &str) -> &str {
 mod tests {
     use super::*;
 
-    /// The line the attach path's debug cube hangs on (decision 1403, bug B13). Both sides of it
-    /// carry the SAME empty `parts` list once built, so the handle is the only thing that can tell
-    /// them apart: `empty_display` is a display that named no model — our gap, worth a cube —
-    /// while a display holding a real handle has been answered by its model, even when the answer
-    /// is "draw nothing" (the invisible trigger creatures).
+    /// Both kinds carry the same empty `parts` once built, so only the handle tells a display that
+    /// named no model from one whose model draws nothing.
     #[test]
     fn only_a_display_with_no_model_file_earns_the_cube() {
         assert!(
@@ -750,7 +573,7 @@ mod tests {
         assert!(
             DisplayModel {
                 handle: ModelHandle::M2(Handle::default()),
-                // Built, and it drew nothing — `InvisibleStalker.m2`'s zero batches. Not a cube.
+                // Built with nothing to draw, like `InvisibleStalker.m2`'s zero batches.
                 parts: Some(Vec::new()),
                 ..empty_shell()
             }
diff --git a/crates/benilla-app/src/entities/equipment/mod.rs b/crates/benilla-app/src/entities/equipment/mod.rs
index 1921ab37..f3daee14 100644
--- a/crates/benilla-app/src/entities/equipment/mod.rs
+++ b/crates/benilla-app/src/entities/equipment/mod.rs
@@ -1,31 +1,8 @@
-//! Equipment visuals (decisions 0072/0074): held items (weapons, shields, ranged), worn-armor
-//! resolution, and helm/shoulder attach models on units' bodies.
-//!
-//! Two halves, both per-frame systems chained after [`super::attach_entity_visuals`]:
-//!
-//! - **Resolution** ([`resolve_equipment`]) — what should each unit hold, and where? A **creature**
-//!   carries its item **display ids directly** in `UNIT_VIRTUAL_ITEM_SLOT_DISPLAY` (+ class/invType and
-//!   a per-item sheath type in `UNIT_VIRTUAL_ITEM_INFO`) — no lookup. A **player** exposes only item
-//!   *entries* (`PLAYER_VISIBLE_ITEM_*`); the display id / inventory type / sheath type come from the
-//!   item template, resolved through the ask-once item layer ([`crate::items::Items`], `CMSG_ITEM_QUERY_SINGLE` on
-//!   miss — the real client's ItemCache does exactly this; other players' inventory GUIDs are
-//!   server-private, so the visible-item entry is the *only* path). Drawn-vs-stowed placement follows
-//!   the unit's sheath state (`UNIT_FIELD_BYTES_2` byte 0) + the item's sheath type.
-//! - **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`). 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/
-//! GameObjects use, resolved from `ItemDisplayInfo.dbc` into `Item\ObjectComponents\{Weapon,Shield}\`),
-//! with the display's model texture bound to the model's runtime type-2 batches
-//! ([`CharSkinSlot::Object`]).
-//!
-//! Three files, along the same seam the doc above describes: **`resolve`** (what should each unit
-//! hold, and where — the descriptor read + the placement law), **`spawn`** (the sub-model children
-//! that ride the bones), and this module, which owns what both share — the attach-id table, the
-//! display cache, and the components they diff through.
+//! Equipment visuals: `resolve` decides what each unit holds and wears and where, and `spawn`
+//! hangs the item models from the body's attachment joints (the reference's attach install,
+//! `0x47a380`). A creature carries display ids (`UNIT_VIRTUAL_ITEM_SLOT_DISPLAY`), a player only
+//! item entries (`PLAYER_VISIBLE_ITEM_*`), resolved through the templates as the reference's
+//! ItemCache does.
 
 use std::collections::HashMap;
 
@@ -42,71 +19,49 @@ pub(super) use resolve::{resolve_corpse_equipment, resolve_equipment};
 mod spawn;
 pub(super) use spawn::attach_held_items;
 
-/// The three held-item descriptor slots (vmangos `WeaponAttackType`): 0 mainhand · 1 offhand · 2 ranged.
+/// The held-item descriptor slots, in vmangos `WeaponAttackType` order: mainhand, offhand, ranged.
 const HELD_SLOTS: usize = 3;
 
-/// A player's visible-item equipment slots for the held items (vmangos `EQUIPMENT_SLOT_MAINHAND/
-/// OFFHAND/RANGED` = 15/16/17 — the `PLAYER_VISIBLE_ITEM_*` blocks are indexed by equipment slot).
+/// The held items' equipment slots, which index the `PLAYER_VISIBLE_ITEM_*` blocks.
 const PLAYER_HELD_SLOTS: [u8; HELD_SLOTS] = [15, 16, 17];
 
-/// M2 attachment-point ids (empirically pinned on `HumanMale.m2` — decision 0072): the drawn-hand
-/// points, the shield forearm, and the sheathed family the client's `0x47a070` jump table selects
-/// from (`K − (mainhand)` over `K ∈ {27, 31, 33}`, const 28 for the shield).
-/// `pub(crate)` because the ids are a shared vocabulary, not this module's private numbering:
-/// the model panes filter the reference's attach reset and probe hand occupancy by them
-/// ([`crate::portrait::attach_reset`], [`crate::portrait::hand_grip`]).
+/// M2 attachment ids. A stowed item's is `0x47a070`'s: K - 1 for the mainhand and K for the
+/// offhand, K = 27 two-hander, 31 staff, 33 one-hander; 28 for a shield.
 pub(crate) mod attach_id {
-    /// Left forearm — a *drawn* shield.
+    /// Left forearm: a drawn shield.
     pub(crate) const SHIELD: u16 = 0;
-    /// Right/left shoulder (pivots at ∓0.21 Y, shoulder height) — the pauldron pair.
     pub(crate) const SHOULDER_RIGHT: u16 = 5;
     pub(crate) const SHOULDER_LEFT: u16 = 6;
-    /// Head — the helm.
     pub(crate) const HELM: u16 = 11;
-    /// Right hand — the drawn mainhand (and a drawn ranged weapon).
+    /// The drawn mainhand, and a drawn gun, crossbow, wand or thrown weapon (`0x611e10`).
     pub(crate) const HAND_RIGHT: u16 = 1;
-    /// Left hand — a drawn non-shield offhand.
+    /// A drawn offhand other than a shield, and a drawn bow.
     pub(crate) const HAND_LEFT: u16 = 2;
-    /// Right/left shoulder-blade — the stowed two-hander family (and a stowed ranged weapon).
     pub(crate) const BACK_RIGHT: u16 = 26;
     pub(crate) const BACK_LEFT: u16 = 27;
-    /// Centre back — the stowed shield.
     pub(crate) const SHIELD_BACK: u16 = 28;
-    /// Lower-back pair — the stowed staff family.
     pub(crate) const BACK_LOWER_MAIN: u16 = 30;
     pub(crate) const BACK_LOWER_OFF: u16 = 31;
-    /// Hip pair — the stowed one-hander family (mainhand on the *left* hip, drawn across the body).
+    /// The mainhand's hip is the left one.
     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 (`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.
+    /// HandArrow, the nocked arrow's one body attach (`0x712f70(body, 0x23)` in `0x60ba30` and the
+    /// `$BWP` handler). The 0x18/0x19 that `0x479f40` takes pick a model directory, not an attach.
     pub(crate) const HAND_ARROW: u16 = 0x23;
-    /// 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.
+    /// The worn quiver's attachment (`0x479c50`), the stowed mainhand two-hander's point.
     pub(crate) const QUIVER: u16 = 26;
 }
 
-/// Item-display rendering: the `ItemDisplayInfo.dbc` catalog (held models + armor region textures,
-/// decisions 0072/0074) + a per-display [`DisplayModel`] cache for held items. Optional resource —
-/// if the DBC fails to load, units hold nothing and armor stays unpainted.
+/// The `ItemDisplayInfo.dbc` catalog and the item model cache; absent if the DBC fails to load.
 #[derive(Resource)]
 pub(crate) struct ItemDisplays {
-    /// `pub(crate)`: the container feed ([`crate::ui_items`]) reads the icon column off the same
-    /// parse — one catalog resource serves both the world and the bags.
     pub(crate) catalog: ItemDisplayCatalog,
-    /// Keyed by `(display id, model kind)` — a helm display resolves to a different file per
-    /// race/sex, a shoulder display to a left/right pair (0074 slice 3c).
+    /// Keyed by model kind too: a helm display has a file per race and sex, a shoulder a pair.
     pub(super) models: HashMap<(u32, ItemModelKind), DisplayModel>,
 }
 
 #[cfg(test)]
 impl ItemDisplays {
-    /// The icon-only test seam: a synthetic catalog with an empty model cache — for the UI feeds
-    /// that read nothing off this resource but the icon column (the action bar, the bags). They
-    /// live outside this module, so `models` is not theirs to build.
     pub(crate) fn icons_for_tests(catalog: ItemDisplayCatalog) -> Self {
         ItemDisplays {
             catalog,
@@ -115,52 +70,32 @@ impl ItemDisplays {
     }
 }
 
-/// A player's worn-equipment display ids by **bodyslot − 2** (shirt, chest, belt, pants, boots,
-/// wrist, gloves, tabard — the armor-composite slots, decision 0074), `0` = empty. `settled` means
-/// every non-empty visible-item entry has resolved through the template cache (hit or recorded
-/// miss) — the attach path waits for it so a player composites dressed, not naked-then-flicker.
-/// Players only; a character-model NPC's armor ships pre-baked (decision 0060).
+/// A player's worn display ids, 0 for none (an NPC's armor is baked into its display);
+/// `bodyslots` by bodyslot - 2, shirt to tabard. `settled` holds once every worn entry has a
+/// template answer, so the first composite is dressed rather than naked for a frame.
 #[derive(Component, Clone, Copy, PartialEq, Eq, Default, Debug)]
 pub(crate) struct Equipment {
     pub(crate) bodyslots: [u32; 8],
-    /// The back slot's display id (0 = no cloak) — a geoset + runtime cape texture, no body region.
+    /// A geoset and a 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 (`0x4799a0`).
+    /// An attach model plus the masks that hide hair, facial hair and ears (`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**
-    /// for a guild whose `CMSG_GUILD_QUERY` has not answered yet; the tabard shows its own art
-    /// until it does.
-    ///
-    /// It lives here rather than in a component of its own because it is part of *what this body
-    /// 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.
+    /// The guild emblem off `PLAYER_GUILDID`; `None` for no guild, or until its query answers.
     pub(crate) emblem: Option<benilla_formats::GuildEmblem>,
-    /// 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.
+    /// The tabard designer's preview on our own body (`[cc+0xc]`, `0x5e07d0`).
     pub(crate) tabard_preview: bool,
     pub(crate) settled: bool,
 }
 
-/// The [`Equipment`] a player's attached visual was **dressed** with (its composite key's equip
-/// half). [`super::attach::redress_player_looks`] diffs it against the live resolution and re-dresses
-/// the standing visual in place on a change — the reference's own shape, and the reason a weapon
-/// glow no longer blinks when a belt is swapped (decision 0835, superseding 0074's teardown).
+/// The [`Equipment`] a player's visual was dressed with; a change re-dresses it in place.
 #[derive(Component)]
 pub(in crate::entities) struct AppliedEquipment(pub(in crate::entities) Equipment);
 
-/// Marks a unit whose visual was torn down and is being rebuilt for something **other** than a
-/// spawn: the re-attach skips the appear-fade. A mount transition ([`super::mount`]) and a live
-/// display swap ([`super::live_display`]) are the two remaining tear-downs; a gear change is not one
-/// of them any more (decision 0835).
+/// A visual rebuilt for a mount or display swap, not a spawn: it skips the appear-fade.
 #[derive(Component)]
 pub(super) struct Reattached;
 
-/// Player equipment slots feeding the armor composite → their bodyslot−2 index (decision 0074):
-/// shirt(3) chest(4) waist(5) legs(6) feet(7) wrists(8) hands(9) tabard(18). The visible-item block
-/// is indexed by equipment slot, so no invType mapping is needed on this path.
+/// The armor composite's equipment slots and their `Equipment::bodyslots` index.
 const COMPOSITE_SLOTS: [(u8, usize); 8] = [
     (3, 0),
     (4, 1),
@@ -172,54 +107,30 @@ const COMPOSITE_SLOTS: [(u8, usize); 8] = [
     (18, 7),
 ];
 
-/// The attach sub-model slots a unit shows this frame — the three held items (mainhand/offhand/
-/// ranged) plus the helm, the shoulder pair (0074 slice 3c), and the nocked ammo, each an item
-/// display + model variant + the body attachment point it hangs from. Recomputed by
-/// [`resolve_equipment`] and diffed by [`attach_held_items`], so equipment/sheath changes
-/// re-spawn only on an actual change.
+/// The item models a unit shows this frame, in [`ATTACH_SLOT_NAMES`] order.
 #[derive(Component, Default, Clone, PartialEq, Eq)]
 pub(super) struct HeldItems {
     slots: [Option<HeldSlot>; ATTACH_SLOTS],
 }
 
-/// Total attach sub-model slots: the 3 held + helm + shoulder L/R + the nocked ammo + the
-/// worn quiver (self-only, ranged-drawn — `0x611e10`).
 pub(super) const ATTACH_SLOTS: usize = 8;
 
-/// **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
-/// goes up it takes the hidden hand's weapon **off the hand** — `0x5ff676 call
-/// 0x47a310(model, 0xf, 0, 0)`, an unlink of every child at that attachment plus an `OpenHand` —
-/// but only while the sheath state `[unit+0xd40]` is non-zero, i.e. while the weapon is drawn.
-/// Then nothing puts it back: every attach site (`0x60b770`, `0x605da0`, `0x60b590`) is dominated
-/// by a `GetWeapon(slot, 0)` that now reads NULL, so the weapon can be neither re-attached nor
-/// moved until the flag clears.
-///
-/// The observable shape, and why a plain "hide it while disarmed" is wrong in both directions:
-///
-/// | when the flag went up | what stays on screen |
-/// |---|---|
-/// | weapon **drawn** | nothing — it leaves the hand |
-/// | weapon **stowed** | it stays on the back/hip, and stays there even if the unit then engages |
-/// | we never saw the edge (the unit streamed in already disarmed) | nothing was ever attached |
+/// What the disarm reflex left attached: the reference builds attachments from events, and this is
+/// the one such state kept across frames. `0x5ff580` runs on any unit whose disarm bit changes
+/// (`0x5ff619`); as it rises, a drawn weapon leaves the hidden hand (`0x5ff676`,
+/// `0x47a310(model, 0xf, 0, 0)`) and a stowed one stays, and no attach site (`0x60b770`,
+/// `0x605da0`, `0x60b590`) moves it while `GetWeapon(slot, 0)` reads NULL.
 #[derive(Component, Clone, Copy, PartialEq, Eq)]
 pub(super) struct DisarmFreeze {
-    /// The held slot the ladder hid at the edge — 0 mainhand, 1 offhand.
+    /// The hand hidden at the edge: 0 mainhand, 1 offhand.
     slot: u8,
-    /// The display id that was in that hand. A *different* item has no edge of its own and so was
-    /// never attached (the reference's attach sites all decline while the flag is up).
+    /// The item in that hand; a different one was never attached while the flag is up.
     display: u32,
-    /// Where the reflex left it, or `None` when it was in the hand and got detached.
+    /// Where the reflex left it; `None` when it was detached from the hand.
     attach: Option<u16>,
 }
 
 impl DisarmFreeze {
-    /// Record what the reflex left, at the edge.
     pub(super) fn new(slot: u8, display: u32, attach: Option<u16>) -> Self {
         DisarmFreeze {
             slot,
@@ -228,8 +139,7 @@ impl DisarmFreeze {
         }
     }
 
-    /// Where `display` still hangs in `slot`, or `None` — including when this freeze is about a
-    /// different hand or a different item, neither of which the reflex ever attached.
+    /// Where `display` still hangs in `slot`; `None` for any other hand or item.
     pub(super) fn attach_for(&self, slot: u8, display: u32) -> Option<u16> {
         (self.slot == slot && self.display == display)
             .then_some(self.attach)
@@ -242,29 +152,18 @@ struct HeldSlot {
     display: u32,
     kind: ItemModelKind,
     attach: u16,
-    /// The `ItemVisuals.dbc` id this item glows with — its display's intrinsic visual, else its
-    /// first enchant's (decision 0805, [`super::item_glow`]). `0` on the overwhelming majority.
-    /// Part of the diff key on purpose: applying or losing an enchant is a different MODEL set, so
-    /// the item is rebuilt and the glow follows. (A sheath change is not — same item, new attach
-    /// point: that one MOVES the spawned root instead, decision 0826.)
+    /// The `ItemVisuals.dbc` glow, the display's own else its first enchant's; usually 0.
     visual: i32,
 }
 
 impl HeldSlot {
-    /// The same item model, wherever it hangs — the test that separates a **move** (the sheath
-    /// swap: one item, a new attach point, so the spawned root is re-parented and everything
-    /// riding it comes along — decision 0826) from a **rebuild** (a different display, model
-    /// variant, or glow, which is a different model and must be built from scratch).
+    /// The same model wherever it hangs: a change of attach point alone is a move, not a rebuild.
     fn same_item(&self, other: &Self) -> bool {
         self.display == other.display && self.kind == other.kind && self.visual == other.visual
     }
 }
 
-/// Which of an item display's models a slot shows, and where its file lives (decision 0074 slice 3c
-/// — all pinned empirically against the real MPQ listing):
-/// `Item\ObjectComponents\{Weapon,Shield}\model[0]` for held items; `Shoulder\model[0]`/`model[1]`
-/// for the left/right pauldron (each with its own `model_texture` column); `Head\<stem>_<Ra><S>.m2`
-/// for helms — per-race/sex files, prefix by race id (Hu Or Dw Ni Sc Ta Gn Tr), M/F by sex.
+/// Which of an item display's models a slot shows; `ensure_item_model` maps each to its file.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub(crate) enum ItemModelKind {
     Weapon,
@@ -275,35 +174,24 @@ pub(crate) enum ItemModelKind {
         race: u8,
         sex: u8,
     },
-    /// A nocked-ammo model ([`crate::creature_anim::NockedAmmo`]) — the missile module's shape
-    /// 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\`.
+    /// A nocked-ammo model: a display with `model[0]` is a thrown weapon under `Weapon\`, one with
+    /// only `model[1]` an arrow or bullet under `Ammo\`.
     Ammo,
-    /// 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.
+    /// The worn ammo container (`0x479c50`), on the back while the ranged weapon is drawn.
     Quiver,
 }
 
-/// The per-instance bone-riding surface, inserted at visual attach (decision 0072): the model's
-/// attachment points and event markers (id → bone + Bevy-space local offset). **Pure model data**
-/// — the anchor *entities* live in `RigPose.anchors` and spawn on first consumer (decision 1355):
-/// a rider that needs a frame to parent under resolves `points`/`markers` here, then
-/// `RigPose::anchor_for(bone)`; a reader that only needs a position goes straight to
-/// `RigPose::posed_point(bone, offset)` and touches no entity at all.
+/// A body model's attachment points and event markers, each a bone and a Bevy-space offset from
+/// its bind pivot; the joint entities are `RigPose::anchor_for`'s.
 #[derive(Component)]
 pub(crate) struct BoneAttach {
-    /// Attachment id → `(bone index, bevy-space offset from the bone's bind pivot)`.
     pub(crate) points: HashMap<u16, (u16, Vec3)>,
-    /// Animation-event marker 4CC → the same `(bone, offset)` shape — first record per ident
-    /// (the client's `0x7130e0` first-match scan). The missile launch points: `$CSL`/`$CSR`/`$CST`
-    /// (casting hand left/right/two-hand, `0x60c9b0`'s cascade) and `$BWR` (ranged release).
+    /// First record per FourCC (`0x7130e0`): the missile launch points `$CSL`/`$CSR`/`$CST`
+    /// (`0x60c9b0`) and `$BWR`.
     pub(crate) markers: HashMap<[u8; 4], (u16, Vec3)>,
 }
 
-/// The held-item children currently spawned for a unit: the [`HeldItems`] they were built from (the
-/// diff key) + the spawned root entity **per slot** — indexed, not a flat list, because the diff is
-/// per slot (decision 0826): a slot that didn't change keeps its root, and a slot that only changed
-/// attach point has its root moved. Only a slot whose item really changed is despawned and rebuilt.
+/// The item models spawned for a unit: the [`HeldItems`] they were built from and each slot's root.
 #[derive(Component, Default)]
 pub(crate) struct HeldAttached {
     applied: HeldItems,
@@ -311,18 +199,11 @@ pub(crate) struct HeldAttached {
 }
 
 impl HeldAttached {
-    /// The spawned root per attach slot, read-only — for the **instruments** (`WOW_DRESS_CENSUS`),
-    /// which need the *visual* truth and not just the resolution: "is a helm model actually hanging
-    /// off this body right now" is a different question from "did we resolve a helm display id",
-    /// and a report about a piece of gear showing when it should not (B123) turns on the gap
-    /// between them. Nothing in gameplay reads this — the diff owns the array (decision 0026's
-    /// dev seam: dev may see anything, nothing may depend on dev).
+    /// The spawned root per attach slot: the models actually on the body, not the resolution.
     pub(crate) fn spawned_slots(&self) -> &[Option<Entity>; ATTACH_SLOTS] {
         &self.spawned
     }
 
-    /// The spawned roots as they would be after an attach pass — the one field a consumer test
-    /// needs, without standing up the resolver, the display cache and the attach chain to get it.
     #[cfg(test)]
     pub(crate) fn with_spawned(spawned: [Option<Entity>; ATTACH_SLOTS]) -> Self {
         Self {
@@ -332,22 +213,18 @@ impl HeldAttached {
     }
 }
 
-/// The attach-slot names, in [`HeldAttached::spawned_slots`] order — the instruments' labels for
-/// the eight slots [`resolve_equipment`](super::equipment::resolve) fills.
+/// The attach slots' names, in [`HeldAttached::spawned_slots`] order.
 pub(crate) const ATTACH_SLOT_NAMES: [&str; ATTACH_SLOTS] = [
     "main", "off", "ranged", "helm", "shL", "shR", "ammo", "quiver",
 ];
 
-/// The glow id of a slot the reference never glows: **helm (attach 11), shoulders (5/6) and the
-/// quiver (26) push a literal `0`** into the item-attach primitive `0x4798c0` — byte-read at
-/// `0x479aa2`/`0x479e5f`/`0x479cf2`/`0x479db4` (decision 0805). Only the weapon/shield hand attach
-/// (`0x47a200`) and the ranged/ammo builder pass a display's real visual, so a glowing *shoulder*
-/// display — three robes and a chest carry one — is inert in 1.12, and inert here.
+/// The glow of a slot the reference never lights: the helm, shoulder and quiver builders pass a
+/// literal 0 to `0x4798c0` (`0x479aa2`, `0x479e5f`, `0x479cf2`, `0x479db4`); only the hand attach
+/// (`0x47a200`) and the ranged and ammo builder pass the display's visual.
 const NO_GLOW: i32 = 0;
 
-/// Ensure `display` has a [`DisplayModel`] entry: resolve its ItemDisplayInfo row to the
-/// `Item\ObjectComponents\{Weapon,Shield}\` model + its runtime object texture (the display's model
-/// texture — an independently-named BLP in the same folder, never derived from the model name).
+/// Ensure `display` has a [`DisplayModel`] for `kind`; its texture is the BLP the display row
+/// names, never derived from the model name.
 pub(in crate::entities) fn ensure_item_model(
     held: &mut ItemDisplays,
     display: u32,
@@ -357,10 +234,6 @@ pub(in crate::entities) fn ensure_item_model(
     if held.models.contains_key(&(display, kind)) {
         return;
     }
-    // Per-kind: the ObjectComponents directory, which model/texture column, and the helm's
-    // per-race/sex filename (`<stem>_<Ra><S>.m2` — prefix by race id, empirically pinned, 0074).
-    // Ammo follows the missile module's shape rule: a `model[0]` row is a thrown weapon
-    // (`Weapon\`), a `model[1]`-only row an arrow/bullet (`Ammo\`).
     let (dir_name, col) = match kind {
         ItemModelKind::Weapon => ("Weapon", 0),
         ItemModelKind::Shield => ("Shield", 0),
@@ -385,8 +258,7 @@ pub(in crate::entities) fn ensure_item_model(
         Some(d) if d.model[col].is_some() => {
             let mut model = d.model[col].clone().unwrap();
             if let ItemModelKind::Helm { race, sex } = kind {
-                // Race id 1–8 → Hu Or Dw Ni Sc Ta Gn Tr; M/F by sex. All 16 variants ship for
-                // every helm stem (verified against the full MPQ listing).
+                // Race 1-8 is Hu Or Dw Ni Sc Ta Gn Tr, sex M or F.
                 const RACE_PREFIX: [&str; 8] = ["Hu", "Or", "Dw", "Ni", "Sc", "Ta", "Gn", "Tr"];
                 let prefix = RACE_PREFIX[(race.clamp(1, 8) - 1) as usize];
                 let letter = if sex == 1 { 'F' } else { 'M' };
@@ -400,8 +272,7 @@ pub(in crate::entities) fn ensure_item_model(
             );
             DisplayModel {
                 handle: ModelHandle::M2(asset_server.load(m2_url(&format!("{dir}\\{model}")))),
-                // The runtime object skin (bound to the model's type-2 batches) — its own basename in
-                // the same folder, never derived from the model name (decision 0072's naming trap).
+                // The runtime object skin, bound to the model's type-2 batches.
                 object_texture: d.model_texture[col].clone(),
                 dir,
                 ..super::empty_shell()
diff --git a/crates/benilla-app/src/entities/equipment/resolve.rs b/crates/benilla-app/src/entities/equipment/resolve.rs
index 17061b20..652b36a1 100644
--- a/crates/benilla-app/src/entities/equipment/resolve.rs
+++ b/crates/benilla-app/src/entities/equipment/resolve.rs
@@ -1,9 +1,4 @@
-//! Equipment **resolution** (decisions 0072/0074, split out of `super`'s one file): what each unit
-//! should be holding this frame, and where — the descriptor read (a creature's virtual items, a
-//! player's visible-item entries through the ask-once item layer), the drawn-vs-stowed placement
-//! law, the item/enchant glow id (decision 0805), and the player teardown a gear change forces.
-//! The output is [`HeldItems`] + [`Equipment`] + [`Wielded`], which `super::spawn` turns into
-//! children.
+//! Equipment resolution: what each unit holds and wears this frame, and where each item hangs.
 
 use benilla_protocol::EntityKind;
 use bevy::prelude::*;
@@ -21,17 +16,9 @@ use super::{
     ItemModelKind, ATTACH_SLOTS, COMPOSITE_SLOTS, HELD_SLOTS, NO_GLOW, PLAYER_HELD_SLOTS,
 };
 
-/// The drawn/stowed attachment point for one held slot, or `None` when the item shows nothing (empty
-/// slot, sheath-type-less item while stowed, or an unresolved template).
-///
-/// 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 — `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).
+/// Where one held slot's item hangs, if it shows: a melee item drawn in sheath state 1, else by
+/// its own sheath type (`0x47a070`); a ranged weapon only in state 2, a bow in the left hand and
+/// the rest in the right (`0x611e10`), and detached when stowed (`0x7130a0`).
 pub(in crate::entities) fn placement(
     slot: usize,
     inv_type: u32,
@@ -41,13 +28,11 @@ pub(in crate::entities) fn placement(
     use attach_id::*;
     let shield = inv_type == 14; // INVTYPE_SHIELD
     match slot {
-        // Ranged: in hand while ranged-drawn (bow left, everything else right), invisible otherwise.
         2 => (unit_sheath == 2).then_some(if inv_type == 15 {
-            HAND_LEFT // INVTYPE_RANGED — bows
+            HAND_LEFT // INVTYPE_RANGED: bows
         } else {
             HAND_RIGHT
         }),
-        // Melee/shield slots: drawn in melee sheath state, else stowed by the item's sheath type.
         0 | 1 if unit_sheath == 1 => Some(match (slot, shield) {
             (0, _) => HAND_RIGHT,
             (_, true) => SHIELD,
@@ -68,12 +53,7 @@ pub(in crate::entities) fn placement(
     }
 }
 
-/// One held slot's enchant ids, folded to a single change-detectable number for [`DressKey`].
-///
-/// The **scan width is the glow resolver's** (`0x62ec70`'s seven `CGItem` enchant slots), so the
-/// fold moves exactly when the thing it stands in for — the item's glow — could. Creatures carry
-/// none: a virtual item has no enchant fields, like the synthetic item the reference's
-/// `GetVirtualItem` hands its own resolver.
+/// One held slot's enchant ids folded for [`DressKey`], over the seven `CGItem` slots (`0x62ec70`).
 fn enchant_fold(
     s: &benilla_protocol::messages::ObjectFields,
     kind: EntityKind,
@@ -87,21 +67,15 @@ fn enchant_fold(
         .fold(0i32, |acc, e| acc.wrapping_mul(31).wrapping_add(e as i32))
 }
 
-/// 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.
+/// The nocked ammo's attachment (`0x60ba30`): HandArrow, once the `$BWP` latch is set
+/// (`[+0xd58] & 0x4000`, [`NockLatch`]). Only a bow gets there: gun and crossbow return early
+/// (`gunXbow`), thrown fails the `== 0x18` gate, and a wand's Shoot has no ammo item.
 fn ammo_attach(ranged_inv_type: Option<u32>, nock_latched: bool) -> Option<u16> {
     const INVTYPE_RANGED_BOW: u32 = 0x0f;
     (ranged_inv_type == Some(INVTYPE_RANGED_BOW) && nock_latched).then_some(attach_id::HAND_ARROW)
 }
 
-/// The glow id for one held item, and the model requests it implies: the base-or-enchant fork
-/// ([`item_glow::effective_visual`]) plus the cache entries for whatever it resolves to. `0` when
-/// the glow chain's DBCs are absent — the item simply draws unadorned, as before decision 0805.
+/// One item's glow id, requesting the glow's models; 0 when the glow DBCs are absent.
 fn resolve_glow(
     glows: Option<&mut ItemGlows>,
     enchant_rows: Option<&benilla_formats::EnchantCatalog>,
@@ -119,15 +93,8 @@ fn resolve_glow(
     visual
 }
 
-/// The resolve inputs that live OUTSIDE the unit's own descriptor and the global caches — the
-/// settled sheath byte, the ceremony's per-arm visual state, and the nock lane. Compared each
-/// frame by [`resolve_equipment`]'s skip gate (1490): a unit whose descriptor tick, key, and
-/// cache epochs all held still resolves to the same loadout **by construction** — every other
-/// read in the rebuild is either a field of the store or a static-after-load catalog
-/// (`ItemDisplays::catalog`, the enchant rows; the `models` map is write-only from here) — so
-/// the rebuild (the template probes, the 7-slot enchant scans, the quiver bag walk, the
-/// ensure/glow calls) is skipped whole. The output diff below stays as the last fence: this
-/// gate may only ever skip work, never change what lands.
+/// The resolve inputs outside the descriptor and global caches. Skipping a unit on them is sound
+/// only while every other input of the rebuild is a store field or a catalog fixed after load.
 #[derive(Component, Clone, Copy, PartialEq)]
 pub(in crate::entities) struct ResolveKey {
     committed_sheath: u8,
@@ -136,41 +103,23 @@ pub(in crate::entities) struct ResolveKey {
     latched: bool,
 }
 
-/// 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 (`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
-/// weapon renders nothing at all, and so does a sheath-type-less melee weapon — so a key built
-/// from `HeldItems` would move every time the player drew a bow. This one does not.
-///
-/// Deliberately absent: the **nocked ammo** and the **quiver**, both sheath-derived, and neither a
-/// model-event producer in the reference (`0x60ba30` reaches no queue site at all). Helm,
-/// shoulders and the body composite are absent for the opposite reason — they cannot move with a
-/// sheath, so the pane keys on their mirrored geometry directly.
+/// The dress half of the resolve, one of a model widget's re-take triggers (`0x5dee30`,
+/// `crate::portrait::SnapKey`). Its weapons are read above [`placement`], so a sheath that shows
+/// or hides one does not move it. Left out: the nocked ammo and quiver, which raise no model event
+/// (`0x60ba30` reaches no queue site), and what no sheath moves, read off the mirrored geometry.
 #[derive(Component, Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) struct DressKey {
     /// The body the widget duplicates.
     pub(crate) display_id: Option<u32>,
-    /// Mainhand · offhand · ranged: `(ItemDisplayInfo id, model kind, ItemVisuals id)`.
+    /// Mainhand, offhand, ranged: the display id, model kind and folded enchant ids.
     pub(crate) held: [Option<(u32, ItemModelKind, i32)>; HELD_SLOTS],
-    /// Every weapon identity above has a model with **built parts**. Ours, not the reference's:
-    /// it duplicates a model the world had already finished assembling, where our item models
-    /// stream in. While false the pane keeps re-taking, so a weapon that lands a few frames after
-    /// the window opened is not frozen out of the bake.
+    /// Every placed weapon's model has built parts. Deviation: the reference copies a finished
+    /// model, ours stream in, so while false the pane keeps re-taking and a late weapon is baked.
     pub(crate) held_ready: bool,
 }
 
-/// Resolve every unit's held items from its descriptor. Creatures read display/invType/sheath straight
-/// from the virtual-item fields; players go visible-item entry → [`crate::items::Items`] (ask-once query on
-/// a miss). Ensures each needed display id has a [`DisplayModel`] entry in [`ItemDisplays`] (built
-/// by [`super::update_display_models`] once the asset loads) and writes [`HeldItems`] on change.
-///
-/// **Skip-gated per unit** ([`ResolveKey`]): the full rebuild runs only when the unit's own
-/// descriptor changed, its key changed, or a global input moved — the [`Items`] epochs (an
-/// object ingest covers the quiver bag walk, a landed template answers every pending ask) and
-/// the two client-data load edges. The idle crowd costs one tick check and one small compare.
+/// Resolve every unit's held and worn items, skipping one whose descriptor, [`ResolveKey`] and
+/// the global epochs all held still.
 #[allow(clippy::type_complexity)]
 pub(in crate::entities) fn resolve_equipment(
     mut commands: Commands,
@@ -194,40 +143,27 @@ pub(in crate::entities) fn resolve_equipment(
     templates: Res<Items>,
     net: Res<NetCommands>,
     asset_server: Res<AssetServer>,
-    // The creature display cache — a character-model NPC's helm/shoulder ids + race/sex live on its
-    // display's `NpcAppearance` (CreatureDisplayInfoExtra), read here to resolve its attach models.
+    // A character-model NPC's helm, shoulders, race and sex (CreatureDisplayInfoExtra).
     creatures: Option<Res<Creatures>>,
-    // The item/enchant glow chain (decision 0805): resolved here beside the item itself, so a glow
-    // model is requested the same frame its weapon is and an enchant change rides the item diff.
-    // 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`] 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`.
+    // The template epoch and guild identity generation at the last run: the gate's global half.
     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).
+    // The object lookup and the item entities' change watch, one param under Bevy's limit of 16.
     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.
+    // Mutable because a miss sends the `CMSG_GUILD_QUERY` whose answer paints the tabard.
     mut guilds: Option<ResMut<crate::ui_guild::GuildState>>,
-    // The tabard designer's five under preview (decision 1977) — a change re-dresses our body.
     tabard_design: Option<Res<crate::ui_tabard::TabardDesign>>,
 ) {
     let Some(mut held) = held else {
         return;
     };
-    // The guild cache's landed counter joins the item epochs for the same reason those are here:
-    // 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.
+    // A guild query answered after a player spawned changes their tabard, not their descriptor.
     let epochs = (
         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).
+    // Drained every run, gate or not: `moved` consumes the removals.
     let (objects, mut item_changes) = item_objects;
     let items_moved = item_changes.moved();
     let caches_moved = last_epochs.replace(epochs) != Some(epochs)
@@ -258,9 +194,7 @@ pub(in crate::entities) fn resolve_equipment(
             continue;
         }
         let s = &store.0;
-        // The settled sheath state: the anim layer's **client-side committed state** (the
-        // setter/reconcile cache, decision 0080 — the descriptor byte plus the policy's forces);
-        // else, before the driver first runs, the raw descriptor byte.
+        // The anim layer's committed sheath state, else the raw byte until the driver runs.
         let committed = driver
             .and_then(|d| d.sheath_state())
             .or_else(|| s.unit_sheath_state())
@@ -277,26 +211,9 @@ pub(in crate::entities) fn resolve_equipment(
         if current_key != Some(&key) {
             commands.entity(entity).insert(key);
         }
-        // The two **equipment-display preferences** (decision 1472, B123): `PLAYER_FLAGS`'
-        // `HIDE_HELM 0x400` / `HIDE_CLOAK 0x800`, read off THIS unit's own descriptor. The field is
-        // public, so this is per rendered body and not a local setting — a remote player who hides
-        // their helm hides it on our screen, exactly as ours hides on theirs. A creature has no
-        // `PLAYER_FLAGS` and reads `false` for both (its head/shoulder columns come from
-        // CreatureDisplayInfoExtra, which carries no such preference).
-        //
-        // 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 `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.
+        // `PLAYER_FLAGS`' `HIDE_HELM 0x400` and `HIDE_CLOAK 0x800` are public, so another player's
+        // choice shows here; a hidden piece is display id 0, so its model and `0x4799a0` masks go.
         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
-        // dressed atlas directly (the template cache makes later logins instant).
         if net_entity.kind == EntityKind::Player {
             let mut eq = Equipment {
                 settled: true,
@@ -311,20 +228,14 @@ pub(in crate::entities) fn resolve_equipment(
                     None => eq.settled = false, // asked; answer pending
                 }
             }
-            // The cloak (equipment slot 14): geoset + cape texture, resolved the same way.
-            // The hide preference zeroes the RESOLVED id rather than skipping the lookup, so
-            // `settled` keeps meaning "every worn entry has an answer" — switching the preference
-            // back on then re-dresses from a warm template cache instead of stalling a frame on a
-            // round trip the player would see as a flicker.
+            // The cloak (slot 14) and helm (slot 0). A hidden piece is still looked up and zeroed
+            // after, so `settled` keeps its meaning and showing it again needs no round trip.
             if let Some(entry) = s.player_visible_item_entry(14).filter(|e| *e != 0) {
                 match templates.held(entry, &net) {
                     Some(t) => eq.cloak = t.display_info_id,
                     None => eq.settled = false,
                 }
             }
-            // 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,
@@ -337,17 +248,11 @@ pub(in crate::entities) fn resolve_equipment(
             if hide_helm {
                 eq.helm = 0;
             }
-            // The guild tabard (decision 1704). Resolved for every player, tabard worn or not —
-            // the composite's own gate is the tabard DISPLAY's flag, and asking here keeps the
-            // query on the same lazy-cache idiom as every other read of that cache. A miss answers
-            // `None` for this frame and re-runs when the response bumps the counter above.
+            // The emblem, for every player; the composite paints it only on a flagged tabard.
             eq.emblem = guilds
                 .as_deref_mut()
                 .and_then(|g| crate::ui_guild::unit_guild_emblem(s, g, &net));
-            // The tabard designer's preview (decision 1977): while it is open on OUR body the
-            // five under design replace the guild's emblem and the tabard geoset is forced on
-            // over the empty slot — the reference's `[cc+0xc]` flag and its `0x47a610` install,
-            // both on the local player's character component and nobody else's.
+            // The designer's preview, our own body only (`[cc+0xc]`, the `0x47a610` install).
             if is_self {
                 if let Some(design) = tabard_design.as_deref().and_then(|d| d.preview()) {
                     eq.emblem = Some(design);
@@ -358,25 +263,13 @@ pub(in crate::entities) fn resolve_equipment(
                 commands.entity(entity).insert(eq);
             }
         }
-        // …and the *visual* sheath governing a given slot's placement (`committed` was read
-        // into the key above), which during a draw/stow
-        // ceremony is **per arm** ([`VisualSheath`]): each hand's weapon moves at its own clip's
-        // authored $SHL/$SHR moment, not at the byte change. A melee → ranged toggle therefore
-        // has the sword already on the back while the bow is still on its way to the other hand —
-        // the ceremony's two movements (`creature_anim::sheath`).
+        // The sheath a slot is placed by: per arm during a draw or stow ceremony (`VisualSheath`),
+        // each weapon moving at its own clip's `$SHL`/`$SHR` key rather than at the byte change.
         let sheath_of = |slot: usize, inv_type: u32| {
             visual_sheath.map_or(committed, |v| v.for_slot(slot, inv_type))
         };
-        // 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`), 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
-        // naga's trident) is a different, unit-level mechanism and rides the Unit arms untouched.
-        // An unresolved display cache entry (the one-frame window after a live swap) reads as a
-        // character body — harmless: this diff re-runs every frame, and an attach needs the
-        // rebuilt body's `BoneAttach` first anyway.
+        // A player in a non-character display (a form, a morph) resolves `Wielded` but attaches no
+        // item models: the reference's attach lives on the character component (`0x47a0c0`).
         let char_component = net_entity.kind != EntityKind::Player
             || net_entity
                 .display_id
@@ -384,20 +277,13 @@ pub(in crate::entities) fn resolve_equipment(
                 .is_none_or(|dm| dm.is_character_body);
         let mut slots: [Option<HeldSlot>; ATTACH_SLOTS] = [None; ATTACH_SLOTS];
         let mut wielded = Wielded {
-            // The disarm bit, read off this unit's own descriptor exactly where the reference
-            // reads it — inside `GetWeapon` (`[[unit+0x110]+0xa0] & 0x200000`, `0x5ec2b8`). It
-            // decides the COMBAT reading of the hands ([`Wielded::armed_main`]) and, through
-            // [`DisarmFreeze`] below, what the hidden hand still shows (decision 1863).
+            // Read where the reference's `GetWeapon` reads it (`0x5ec2b8`).
             disarmed: s.unit_flags() & UNIT_FLAG_DISARMED != 0,
             ..Wielded::default()
         };
         let mut ranged_inv_type = None;
-        // The DRESS, gathered as we go: what the unit *wears* in the three weapon slots, recorded
-        // before `placement` decides whether any of it is currently rendered ([`DressKey`]).
         let mut worn: [Option<(u32, ItemModelKind, i32)>; HELD_SLOTS] = [None; HELD_SLOTS];
-        // **Pass 1 — what each hand HOLDS** (`GetWeapon(slot, 1)`). All three slots first, because
-        // the disarm ladder is a question about BOTH hands at once (`Wielded::disarmed_hand`) and
-        // cannot be asked while they are still being filled in.
+        // Pass 1, what each hand holds (`GetWeapon(slot, 1)`), all before the disarm ladder.
         let mut resolved: [Option<(u32, u32, u8, u8, u8, u8)>; HELD_SLOTS] = [None; HELD_SLOTS];
         for slot in 0..HELD_SLOTS {
             // (display id, inventory type, item sheath type, class, subclass, material) per slot.
@@ -431,13 +317,10 @@ pub(in crate::entities) fn resolve_equipment(
             let Some((_, inv_type, item_sheath, class, subclass, material)) = resolved[slot] else {
                 continue;
             };
-            // The item's Material — the draw/stow sound's only key (decision 0882). Both wire
-            // sources carry it; neither is a guess.
+            // The item's Material, the draw and stow sound's only key.
             wielded.materials[slot] = material;
-            // The wielded weapon-class pair (decision 0073's swing/ready selectors) — what's *in*
-            // the hand, independent of whether its model is displayed (a sheath-less item still
-            // swings with its own class). The mainhand's sheath type picks the draw/stow one-shot
-            // (Sheath 89 back / HipSheath 90 hip).
+            // The class pair the swing and ready anims select by; the mainhand's sheath type
+            // picks the draw and stow anim (Sheath 89 at the back, HipSheath 90 at the hip).
             match slot {
                 0 => {
                     wielded.main = Some((class, subclass));
@@ -447,9 +330,6 @@ pub(in crate::entities) fn resolve_equipment(
                     wielded.off = Some((class, subclass));
                     wielded.off_sheath = item_sheath;
                 }
-                // The ranged slot: the local auto-repeat idle's Load/Hold selector reads it
-                // (`select::ranged_load_anim`, 0099 phase 5); the InventoryType picks the
-                // nocked ammo's attach point below.
                 2 => {
                     wielded.ranged = Some((class, subclass));
                     wielded.ranged_sheath = item_sheath;
@@ -459,48 +339,35 @@ pub(in crate::entities) fn resolve_equipment(
                 _ => {}
             }
         }
-        // **The ladder** (decision 1863) — which single hand `UNIT_FLAG_DISARMED` hides, now that
-        // both are known. `None` while the flag is down, or when neither hand holds a weapon.
+        // The one hand `UNIT_FLAG_DISARMED` hides, if any.
         let hidden = wielded.disarmed_hand();
-        // The rising edge, as SEEN HERE: the reference's reflex `0x5ff580` fires on the bit
-        // *changing*, so a unit that streamed in already disarmed never had its weapon attached at
-        // all, and one whose edge we watched keeps whatever the reflex left (see [`DisarmFreeze`]).
+        // The rising edge (`0x5ff580` fires on a change); a unit first seen disarmed never had one.
         let disarm_edge = hidden.is_some() && current_wielded.is_some_and(|w| !w.disarmed);
         let mut next_freeze = match hidden {
-            // Flag down, or neither hand holds a weapon: no freeze at all, and the falling edge
-            // therefore clears it — `0x5ff67d`'s re-attach, which puts the weapon back wherever
-            // the live sheath state says it belongs.
+            // The falling edge clears it: `0x5ff67d` re-attaches by the live sheath state.
             None => None,
-            // The edge itself writes it below, from the placement the weapon had at that moment.
+            // The edge writes it below, from the placement the weapon had at that moment.
             Some(_) if disarm_edge => None,
-            // Steady state: keep what the reflex left.
             Some(_) => freeze.copied(),
         };
-        // **Pass 2 — the models.**
+        // Pass 2, the models.
         for slot in 0..HELD_SLOTS {
             let Some((display, inv_type, item_sheath, _, _, _)) = resolved[slot] else {
                 continue;
             };
             if !char_component {
-                continue; // wielded resolved; the model never attaches on a non-character body
+                continue;
             }
             let kind = if inv_type == 14 {
                 ItemModelKind::Shield
             } else {
                 ItemModelKind::Weapon
             };
-            // The dress, recorded **above** the placement gate — the one line that makes a
-            // widget's snapshot blind to the sheath. Third term: the slot's enchant ids, folded.
-            // Read straight off the descriptor rather than taken from the resolved `visual` below,
-            // because that one is only computed for a slot that is actually placed — and an
-            // enchant change is a model-event producer whether or not the weapon is drawn.
+            // The dress, above the placement gate; its enchants come off the descriptor, since an
+            // enchant raises a model event drawn or not and `visual` exists only for a placed slot.
             worn[slot] = Some((display, kind, enchant_fold(s, net_entity.kind, slot)));
             let live = placement(slot, inv_type, item_sheath, sheath_of(slot, inv_type));
-            // The disarm reflex (`0x5ff580`, decision 1863). The hidden hand's weapon is NOT
-            // placed from the live sheath state — while the flag is up nothing may attach it or
-            // move it, so it is wherever the reflex left it at the edge: gone if it was in the
-            // hand (`0x5ff676`'s detach), still at its body point if it was stowed, and gone if
-            // we never saw the edge because nothing ever attached it.
+            // The hidden hand's weapon stays where the disarm reflex left it (`0x5ff580`).
             let attach = if hidden == Some(slot) {
                 if disarm_edge {
                     let kept = live
@@ -517,13 +384,8 @@ pub(in crate::entities) fn resolve_equipment(
                 continue;
             };
             ensure_item_model(&mut held, display, kind, &asset_server);
-            // The glow (decision 0805): the display's intrinsic visual, else this weapon slot's
-            // first enchant with one. The enchant half is **players only** — the enchant ids ride
-            // `PLAYER_VISIBLE_ITEM`, and a creature's virtual item carries none, exactly like the
-            // synthetic item the reference's `GetVirtualItem` hands its resolver.
             let enchants = (net_entity.kind == EntityKind::Player).then(|| {
-                // All 7 CGItem enchant slots, the reference's scan width (`0x62ec70`); 1.12
-                // broadcasts the first two (PERM, TEMP).
+                // All seven `CGItem` slots (`0x62ec70`); 1.12 sends two, PERM and TEMP.
                 (0..7u8).filter_map(|j| s.player_visible_item_enchant(PLAYER_HELD_SLOTS[slot], j))
             });
             let visual = resolve_glow(
@@ -541,10 +403,8 @@ pub(in crate::entities) fn resolve_equipment(
                 visual,
             });
         }
-        // Publish the dress the moment the weapons are resolved. `held_ready` asks only about
-        // slots that are actually PLACED — a stowed ranged weapon has no model requested at all,
-        // so counting it would leave the key permanently unready and the pane permanently live,
-        // which is the very thing this component exists to stop.
+        // `held_ready` counts only placed slots: a stowed ranged weapon requests no model, and
+        // counting it would keep the pane re-taking for ever.
         let dress = DressKey {
             display_id: net_entity.display_id,
             held: worn,
@@ -558,12 +418,7 @@ pub(in crate::entities) fn resolve_equipment(
         if current_dress != Some(&dress) {
             commands.entity(entity).insert(dress);
         }
-        // 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
-        // client's `$BWP`/`$BWR` keyframes through [`NockLatch`] (`drive_nock_latch`, decision
-        // 0408 — the arrow appears at the pull and leaves with the release).
+        // The nocked ammo, per shot from `SMSG_SPELL_START` for any caster (`ammo_attach`).
         if let (true, Some(ammo), Some(attach)) = (
             char_component,
             nocked,
@@ -575,9 +430,7 @@ pub(in crate::entities) fn resolve_equipment(
                 ItemModelKind::Ammo,
                 &asset_server,
             );
-            // The ammo model's own intrinsic visual — the reference attaches it at the tail of
-            // the ranged/ammo builder `0x479f40` (`47a051: mov edx,[ebx+0x58]`), the same way the
-            // hand attach does. No enchant lane here: this is a model, not an equipped item.
+            // The ammo model's own visual (`0x479f40`, at `0x47a051`); ammo carries no enchants.
             let visual = resolve_glow(
                 glows.as_deref_mut(),
                 enchant_rows,
@@ -593,17 +446,13 @@ pub(in crate::entities) fn resolve_equipment(
                 visual,
             });
         }
-        // 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
-        // clip, a few hundred ms apart, and the two are never seen separately.)
+        // The quiver, players only, while the ranged weapon is drawn (`0x611e10`): the first
+        // ItemClass 11 bag in the unit's own bag slots, at attachment 26. Those slots are private
+        // fields (`UpdateFields_1_12_1.cpp:237`), so only our own body shows one; the reference is
+        // inferred to match, as its scan (`0x611f2d`) reads the unit's own inventory.
+        // Deviation: it attaches at that clip's `$SHL`, where the reference attaches it at the
+        // draw's start, because it keys on the ranged slot's sheath so it arrives with the bow it
+        // feeds; the two are a few hundred ms apart in one clip and never seen apart.
         if net_entity.kind == EntityKind::Player
             && char_component
             && sheath_of(2, ranged_inv_type.unwrap_or(0)) == 2
@@ -632,13 +481,7 @@ pub(in crate::entities) fn resolve_equipment(
                 });
             }
         }
-        // Helm + shoulders (0074 slice 3c / the npc-armor arc): attach sub-models like the held items —
-        // the helm's file is per-race/sex, the shoulders a left/right model pair off one display row.
-        // A **player** sources them from its visible-item entries (wire → item template → display id)
-        // with race/sex off its descriptor; a **character-model NPC** sources them from its display's
-        // CreatureDisplayInfoExtra head/shoulder columns with race/sex from the same row — those are
-        // direct ItemDisplayInfo display ids, no template round-trip. A beast NPC (no appearance row)
-        // resolves nothing here, exactly as before.
+        // Helm and shoulders: a player's visible items, or an NPC's CreatureDisplayInfoExtra.
         let head_shoulder: Option<(u32, u32, u8, u8)> = match net_entity.kind {
             EntityKind::Player if char_component => {
                 let race = s.unit_race().unwrap_or(1);
@@ -651,8 +494,7 @@ pub(in crate::entities) fn resolve_equipment(
                         .filter(|d| *d != 0)
                         .unwrap_or(0)
                 };
-                // The helm's attach sub-model. Zero when hidden — the same id the geoset half
-                // above was given, so the two halves of one preference can never disagree.
+                // Zero when hidden, the id the geoset half got, so the two cannot disagree.
                 let helm = if hide_helm { 0 } else { resolve(0) };
                 let shoulder = resolve(2);
                 Some((helm, shoulder, race, sex))
@@ -691,9 +533,7 @@ 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 (`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.
+        // A weapon at a hand's attachment closes that hand (`0x60b590`); a forearm shield does not.
         let grip = HandGrip {
             right: next
                 .slots
@@ -712,8 +552,7 @@ pub(in crate::entities) fn resolve_equipment(
         if current_wielded != Some(&wielded) {
             commands.entity(entity).insert(wielded);
         }
-        // The freeze rides the same diff as the hands. Absent is a real state — "nothing is
-        // attached to that hand" — so the falling edge REMOVES it rather than storing an empty.
+        // No freeze is a real state, so the falling edge removes the component.
         match next_freeze {
             Some(f) if freeze != Some(&f) => {
                 commands.entity(entity).insert(f);
@@ -726,50 +565,27 @@ pub(in crate::entities) fn resolve_equipment(
     }
 }
 
-/// **The corpse's dress** (decision 1706) — [`resolve_equipment`]'s sibling for a `TYPEID_CORPSE`
-/// body, kept apart from it rather than threaded through it because almost nothing it does applies.
-///
-/// A corpse's gear is a *snapshot*, and it is already resolved: the 19 `CORPSE_FIELD_ITEM` slots
-/// carry `DisplayInfoID | (InventoryType << 24)` (vmangos `Player.cpp:4821`), so there is no item
-/// entry, no template round trip, and therefore no `settled` handshake to wait on — the answer is
-/// complete the moment the descriptor lands. There is likewise no sheath state, no draw/stow
-/// ceremony, no nock lane, no quiver, no enchant scan and no glow: the reference's corpse dress
-/// (`0x5d6260`) is one flat loop over the 19 slots into `0x478cb0`, and nothing else.
-///
-/// **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). 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
-///   wears armour, not weapons. See this module's sibling `entities::corpse` for why we reproduce
-///   the outcome and not the dead lookup.
-///
-/// A **bone pile** wears nothing at all (`0x5d6291`'s early skip — it builds no character component
-/// in the first place). It still gets an empty [`Equipment`], because that component is also the
-/// attach gate: a corpse whose descriptor has not landed must wait a frame rather than composite a
-/// naked body it would never re-dress (the corpse lane has no re-dress — its gear cannot change).
-#[allow(clippy::type_complexity)] // one query's tuple + its change filter
+/// A corpse's dress: the reference loops its 19 `CORPSE_FIELD_ITEM` slots into `0x478cb0`
+/// (`0x5d6260`), each `DisplayInfoID | InventoryType << 24` (vmangos `Player.cpp:4822`). Its own
+/// `HIDE_HELM 0x08` and `HIDE_CLOAK 0x10` zero head and back (`0x5d6465`, `0x5d6470`); ranged is
+/// skipped (`0x5d644e`) and the weapons are looked up as object guids that never resolve
+/// (`0x5d649b`, `0x468460`). A bone pile wears nothing (`0x5d6291`) but gets an empty
+/// [`Equipment`], which also gates the attach.
+#[allow(clippy::type_complexity)]
 pub(in crate::entities) fn resolve_corpse_equipment(
     mut commands: Commands,
     corpses: Query<(Entity, &NetEntity, Ref<ObjectStore>, Option<&Equipment>)>,
     held: Option<ResMut<ItemDisplays>>,
     asset_server: Res<AssetServer>,
     net: Res<NetCommands>,
-    // The guild identity cache, `ResMut` for the same reason the player lane's is: the miss is
-    // what SENDS the `CMSG_GUILD_QUERY` whose answer paints the crest.
+    // Mutable because a miss sends the `CMSG_GUILD_QUERY` whose answer paints the crest.
     mut guilds: Option<ResMut<crate::ui_guild::GuildState>>,
     mut last_guild_epoch: Local<Option<u64>>,
 ) {
     let Some(mut held) = held else {
         return;
     };
-    // The change gate moved off the query filter and in here to make room for the guild counter
-    // (the player lane's own shape): an answer landing three frames after the corpse streamed in
-    // changes what its tabard paints, and nothing about the corpse's descriptor moves to say so.
+    // A guild answer landing after the corpse streamed in changes its tabard, not its descriptor.
     let epoch = guilds.as_ref().map_or(0, |g| g.identity_generation());
     let guilds_moved = last_guild_epoch.replace(epoch) != Some(epoch);
     for (entity, net_entity, store, current) in &corpses {
@@ -781,8 +597,7 @@ pub(in crate::entities) fn resolve_corpse_equipment(
         }
         let s = &store.0;
         let bones = s.corpse_is_bones();
-        // The armour composite + the two preference-gated slots. `settled` is unconditionally
-        // true: every id here is final on arrival.
+        // Every id here is final on arrival, so `settled` always holds.
         let mut eq = Equipment {
             settled: true,
             ..default()
@@ -797,12 +612,8 @@ pub(in crate::entities) fn resolve_corpse_equipment(
             if !s.corpse_hides_helm() {
                 eq.helm = s.corpse_item(0).map_or(0, |(display, _)| display);
             }
-            // 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 (`0x6d6d20`). A
-            // bone pile builds no character component, so it never reaches this leg — which is
-            // exactly where this sits.
+            // The crest off the corpse's own `CORPSE_FIELD_GUILD` (`0x5d6ec0`, at tabard slot 0x12
+            // when its display has flag bit 0), through the living body's guild cache (`0x6d6d20`).
             eq.emblem = guilds
                 .as_deref_mut()
                 .and_then(|g| crate::ui_guild::corpse_guild_emblem(s, g, &net));
@@ -810,10 +621,7 @@ pub(in crate::entities) fn resolve_corpse_equipment(
         if current != Some(&eq) {
             commands.entity(entity).insert(eq);
         }
-        // The two attach sub-models a corpse can wear: the helm (equipment slot 0, per-race/sex
-        // file) and the shoulder pair (slot 2, one display row → a left/right model pair). Both are
-        // ordinary `0x478cb0` slots in the reference's loop; they are attachments on our side
-        // because that is how a character body carries them.
+        // Helm and shoulders: ordinary `0x478cb0` slots in the reference, attachments here.
         let mut slots: [Option<HeldSlot>; ATTACH_SLOTS] = [None; ATTACH_SLOTS];
         if let (false, Some(look)) = (bones, s.corpse_look()) {
             let (race, sex) = (look.race, look.sex.min(1));
@@ -827,7 +635,7 @@ pub(in crate::entities) fn resolve_corpse_equipment(
                     visual: NO_GLOW,
                 });
             }
-            // Shoulders carry no hide preference — the reference gates only slots 0 and 0xe.
+            // Shoulders have no hide flag: the reference gates only slots 0 and 0xe.
             if let Some((shoulder, _)) = s.corpse_item(2) {
                 for (kind, attach, idx) in [
                     (ItemModelKind::ShoulderLeft, attach_id::SHOULDER_LEFT, 4),
@@ -859,21 +667,16 @@ mod tests {
     use benilla_protocol::messages::{ItemInfo, ObjectFields};
     use benilla_protocol::EntityKind;
 
-    /// A corpse's dress is the descriptor, packed (decision 1706): armour off the
-    /// `CORPSE_FIELD_ITEM` slots as ItemDisplayInfo ids with no template round trip, the head and
-    /// back slots suppressed by the corpse's OWN `CORPSE_FLAG_HIDE_HELM`/`HIDE_CLOAK` bits, and
-    /// **never** a weapon or a ranged slot.
     #[test]
     fn corpse_dresses_from_its_own_snapshot() {
         use benilla_protocol::messages::ObjectType;
 
-        /// `CORPSE_FIELD_ITEM + slot` = field 13 + slot, packing
-        /// `DisplayInfoID | (InventoryType << 24)`.
+        /// `CORPSE_FIELD_ITEM` is field 13, each slot `DisplayInfoID | InventoryType << 24`.
         fn item(slot: u16, display: u32, inv: u32) -> (u16, u32) {
             (13 + slot, display | (inv << 24))
         }
-        // Head 900, shoulders 901, chest 902, back 903, mainhand 904, ranged 905 — and race 1 /
-        // sex 0 in CORPSE_FIELD_BYTES_1 bytes 1/2.
+        // Fields 32, 33 and 35 are `CORPSE_FIELD_BYTES_1` (race and sex in bytes 1 and 2),
+        // `CORPSE_FIELD_BYTES_2` and `CORPSE_FIELD_FLAGS`.
         let dressed = |flags: u32| {
             let mut pairs = vec![
                 item(0, 900, 1),
@@ -893,9 +696,6 @@ mod tests {
         let run = |store: ObjectStore| {
             let mut app = App::new();
             app.add_plugins((MinimalPlugins, bevy::asset::AssetPlugin::default()));
-            // The guild-crest leg's channel (the emblem resolve is lazy and would send a
-            // `CMSG_GUILD_QUERY` on a miss); no `GuildState` here, so the crest reads `None` —
-            // which is the guildless case and exactly what this test's corpse is.
             let (tx, _rx) = crossbeam_channel::unbounded::<ClientCommand>();
             app.insert_resource(NetCommands(tx));
             app.insert_resource(ItemDisplays::icons_for_tests(
@@ -924,7 +724,7 @@ mod tests {
         };
 
         let (eq, held) = run(dressed(0));
-        // Chest is composite index 1 (the COMPOSITE_SLOTS table's equipment slot 4).
+        // Chest, equipment slot 4, is composite index 1.
         assert_eq!(eq.bodyslots[1], 902, "chest off CORPSE_FIELD_ITEM[4]");
         assert_eq!(eq.helm, 900);
         assert_eq!(eq.cloak, 903);
@@ -937,14 +737,12 @@ mod tests {
             held.slots[4].is_some() && held.slots[5].is_some(),
             "the shoulder pair attaches off equipment slot 2"
         );
-        // The three slots the reference never dresses: mainhand, offhand, ranged.
         assert!(
             held.slots[..HELD_SLOTS].iter().all(Option::is_none),
             "a corpse wears armour, never weapons"
         );
 
-        // HIDE_HELM 0x08 / HIDE_CLOAK 0x10 — this corpse's own bits, suppressing by a ZERO id so
-        // the geoset masks and the attach model fall away together.
+        // The corpse's own HIDE_HELM 0x08 and HIDE_CLOAK 0x10.
         let (eq, held) = run(dressed(0x08));
         assert_eq!(eq.helm, 0);
         assert_eq!(eq.cloak, 903, "the cloak bit is a different bit");
@@ -953,7 +751,7 @@ mod tests {
         assert_eq!(eq.cloak, 0);
         assert_eq!(eq.helm, 900);
 
-        // BONES 0x01 — no character component at all, so nothing is worn however full the slots.
+        // BONES 0x01: nothing is worn, however full the slots.
         let (eq, held) = run(dressed(0x01));
         assert_eq!(
             eq,
@@ -965,10 +763,7 @@ mod tests {
         assert!(held.slots.iter().all(Option::is_none));
     }
 
-    /// The ranged slot's whole placement law: in hand only while ranged-drawn (state 2) — bow
-    /// (INVTYPE_RANGED 15) to the left hand, gun/crossbow/wand/thrown (RANGEDRIGHT 26 / THROWN 25)
-    /// to the right — and invisible in every other sheath state, regardless of the item's own
-    /// sheath type.
+    /// InventoryType 15 is a bow, 25 thrown, 26 a gun, crossbow or wand.
     #[test]
     fn ranged_slot_hidden_unless_ranged_drawn() {
         for inv_type in [15, 25, 26] {
@@ -985,7 +780,6 @@ mod tests {
         }
     }
 
-    /// Melee slots keep the sheath-type stow table (unchanged by the ranged rule).
     #[test]
     fn melee_slots_stow_by_item_sheath_type() {
         assert_eq!(placement(0, 17, 1, 0), Some(attach_id::BACK_RIGHT));
@@ -994,21 +788,17 @@ mod tests {
         assert_eq!(placement(0, 21, 3, 1), Some(attach_id::HAND_RIGHT));
     }
 
-    /// 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() {
-        assert_eq!(ammo_attach(Some(0x0f), true), Some(attach_id::HAND_ARROW)); // bow, volleying
-        assert_eq!(ammo_attach(Some(0x0f), false), None); // bow, idle — pre-BowPull, no attach
-        assert_eq!(ammo_attach(Some(0x19), true), None); // thrown — directory 0x19, never an id
-        assert_eq!(ammo_attach(Some(0x1a), true), None); // gun/xbow/wand — the gunXbow early return
+        assert_eq!(ammo_attach(Some(0x0f), true), Some(attach_id::HAND_ARROW)); // bow, nocked
+        assert_eq!(ammo_attach(Some(0x0f), false), None); // bow before its `$BWP`
+        assert_eq!(ammo_attach(Some(0x19), true), None); // thrown: fails the 0x18 gate
+        assert_eq!(ammo_attach(Some(0x1a), true), None); // gun, crossbow or wand
         assert_eq!(ammo_attach(None, true), None); // no ranged record
     }
 
-    /// `PLAYER_FLAGS` (field 190) and the visible-item block (`PLAYER_VISIBLE_ITEM_1_CREATOR` 258,
-    /// +12 per slot, the entry at +2) by their raw wire indices — the constants are crate-private
-    /// to benilla-protocol, so every descriptor fixture in this crate spells them out.
+    /// Raw field indices, private to benilla-protocol: `PLAYER_FLAGS` is 190, and the visible-item
+    /// blocks start at 258 (`PLAYER_VISIBLE_ITEM_1_CREATOR`), 12 per slot, the entry at +2.
     const PLAYER_FLAGS: u16 = 190;
     const BYTES_0: u16 = 36;
 
@@ -1031,9 +821,8 @@ mod tests {
         }
     }
 
-    /// Run one `resolve_equipment` pass over a player wearing helm 900 / cloak 800 / chest 700,
-    /// with `flags` on their descriptor, and return what the body was dressed with: the
-    /// [`Equipment`] triple and whether the helm's ATTACH sub-model slot was filled.
+    /// One resolve pass over a player in helm 900, cloak 800 and chest 700: the [`Equipment`] and
+    /// whether the helm model attached.
     fn dress(flags: u32) -> (Equipment, bool) {
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, bevy::asset::AssetPlugin::default()));
@@ -1043,7 +832,6 @@ 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(
@@ -1071,11 +859,7 @@ mod tests {
         (eq, helm_attached)
     }
 
-    /// **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 `0x4799a0`
-    /// hide-mask stripping the hair.
+    /// `PLAYER_FLAGS`' `HIDE_HELM 0x400` and `HIDE_CLOAK 0x800` zero the resolved display ids.
     #[test]
     fn the_hide_preferences_undress_the_helm_and_cloak_on_a_world_body() {
         let (shown, helm_attached) = dress(0);
@@ -1100,7 +884,6 @@ mod tests {
         assert!(hidden.settled, "the worn set is still fully resolved");
     }
 
-    /// The two bits are independent: hiding one leaves the other worn.
     #[test]
     fn the_two_hide_preferences_do_not_reach_each_other() {
         let (helm_only, helm_attached) = dress(0x400);
@@ -1111,11 +894,7 @@ mod tests {
         assert!(helm_attached);
     }
 
-    /// **The skip gate** (1490): a unit whose descriptor tick, [`super::ResolveKey`] and cache
-    /// epochs held still is not rebuilt at all. Proven the sharp way: a descriptor edit smuggled
-    /// past change detection — a thing the wire can never do — must NOT land, because the only
-    /// system that could land it skipped; the same edit under a normal (marked) touch lands on
-    /// the next pass. The control half is what guards against the gate ever wrongly holding.
+    /// An unmarked store edit must not land, as the gate skips the unit; a marked one must.
     #[test]
     fn an_unchanged_unit_is_not_rebuilt_and_a_real_change_still_lands() {
         let mut app = App::new();
@@ -1125,7 +904,6 @@ 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(
@@ -1143,11 +921,11 @@ mod tests {
             ))
             .id();
         app.add_systems(Update, resolve_equipment);
-        app.update(); // resolve (caches_moved: first run)
-        app.update(); // steady state — this frame already skips
+        app.update(); // the first run resolves
+        app.update(); // steady state: this frame skips
         assert_eq!(app.world().get::<Equipment>(player).unwrap().helm, 900);
 
-        // The smuggled edit: helm entry 100 → 101 with the change tick left untouched.
+        // Helm entry 100 to 101 without marking the store changed.
         app.world_mut()
             .get_mut::<ObjectStore>(player)
             .unwrap()
@@ -1161,7 +939,7 @@ mod tests {
             "an unmarked store must not be rebuilt — the gate held"
         );
 
-        // The wire's shape: the same store, now MARKED changed — the swap lands.
+        // Marked changed, as every wire update is.
         app.world_mut()
             .get_mut::<ObjectStore>(player)
             .unwrap()
@@ -1175,29 +953,18 @@ mod tests {
         drop(rx);
     }
 
-    /// **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() {
         use crate::creature_anim::Wielded;
 
-        /// `UNIT_FIELD_FLAGS`, `UNIT_FIELD_BYTES_2` (byte 0 = the sheath state) and the
-        /// mainhand's public entry — raw wire indices, spelled out like every other descriptor
-        /// fixture in this file.
+        /// Raw field indices; byte 0 of `UNIT_FIELD_BYTES_2` is the sheath state.
         const UNIT_FLAGS: u16 = 46;
         const UNIT_BYTES_2: u16 = 164;
         const VISIBLE_ITEM_MAINHAND_ENTRY: u16 = 258 + 2 + 12 * 15;
         /// `UNIT_FLAG_DISARMED`.
         const DISARMED: u32 = 0x0020_0000;
 
-        // A one-handed sword worn on the hip: class 2 subclass 7, INVTYPE_WEAPONMAINHAND, sheath
-        // type 3 — so the stowed placement has a real body point to land on and the drawn one is
-        // the right hand.
+        // A one-handed sword (class 2, subclass 7, InventoryType 21) of sheath type 3: the hip.
         let store = |flags: u32, sheath: u8| {
             ObjectStore(ObjectFields::from_pairs(&[
                 (BYTES_0, 1 | 1 << 8), // race 1 (human), class 1, male
@@ -1223,7 +990,6 @@ 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(
@@ -1246,7 +1012,6 @@ mod tests {
             app.update();
             (app, player, rx)
         };
-        /// Where the mainhand's model hangs this frame, or `None` for "not on screen at all".
         fn mainhand(app: &App, player: Entity) -> Option<u16> {
             app.world()
                 .get::<HeldItems>(player)
@@ -1254,8 +1019,7 @@ mod tests {
                 .map(|slot| slot.attach)
         }
 
-        // (1) DRAWN when the flag goes up — the reflex detaches it. It is not in the hand, and it
-        //     does not fall back to the hip either: nothing re-attaches while the flag is up.
+        // (1) Drawn at the edge: detached, and not put back on the hip either.
         let (mut app, player, rx) = spawn(0, 1);
         assert_eq!(
             mainhand(&app, player),
@@ -1273,7 +1037,7 @@ mod tests {
             None,
             "a drawn weapon leaves the hand on the disarm edge"
         );
-        // …and comes back when the flag clears (`0x5ff67d` → `0x60b770(0)`).
+        // It comes back when the flag clears (`0x5ff67d`, `0x60b770(0)`).
         *app.world_mut().get_mut::<ObjectStore>(player).unwrap() = store(0, 1);
         app.update();
         assert_eq!(
@@ -1283,9 +1047,7 @@ mod tests {
         );
         drop(rx);
 
-        // (2) STOWED when the flag goes up — the reflex's detach is gated on the sheath state
-        //     being non-zero, so nothing happens and the sword stays on the hip. It stays there
-        //     even once the unit draws: while disarmed the transition moves nothing.
+        // (2) Stowed at the edge: it stays on the hip, even when the unit then draws.
         let (mut app, player, rx) = spawn(0, 0);
         assert_eq!(mainhand(&app, player), Some(attach_id::HIP_MAIN));
         *app.world_mut().get_mut::<ObjectStore>(player).unwrap() = store(DISARMED, 0);
@@ -1304,8 +1066,7 @@ mod tests {
         );
         drop(rx);
 
-        // (3) Already disarmed when we first see the unit — the edge happened elsewhere, so
-        //     nothing was ever attached to that hand and the attach sites all decline.
+        // (3) Disarmed when first seen: nothing was ever attached.
         let (app, player, rx) = spawn(DISARMED, 1);
         assert_eq!(
             mainhand(&app, player),
@@ -1315,9 +1076,6 @@ mod tests {
         drop(rx);
     }
 
-    /// The COMBAT reading is separate from the display one, and only the display one is frozen:
-    /// the hands still report what is worn (`GetWeapon(slot, 1)` — what the paperdoll shows),
-    /// while `armed_main` reports what the unit can fight with.
     #[test]
     fn the_hands_keep_the_worn_reading_through_a_disarm() {
         use crate::creature_anim::Wielded;
@@ -1342,7 +1100,6 @@ 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(
diff --git a/crates/benilla-app/src/entities/equipment/spawn.rs b/crates/benilla-app/src/entities/equipment/spawn.rs
index b74f980c..2e947a7a 100644
--- a/crates/benilla-app/src/entities/equipment/spawn.rs
+++ b/crates/benilla-app/src/entities/equipment/spawn.rs
@@ -1,7 +1,4 @@
-//! Equipment **attach** (decisions 0072/0074, split out of `super`'s one file): the sub-model
-//! children a unit's resolved [`HeldItems`] spawns — each item model's parts under its attach
-//! point's joint entity, plus everything that rides an item (its billboard cards, emitters,
-//! lights, ribbons, and the glow its `ItemVisuals` id names — decision 0805).
+//! Equipment attach: each item model under its attachment's joint, with everything riding it.
 
 use bevy::mesh::MeshTag;
 use bevy::prelude::*;
@@ -19,9 +16,7 @@ use super::{
     attach_id, BoneAttach, HeldAttached, HeldItems, HeldSlot, ItemDisplays, ATTACH_SLOTS, NO_GLOW,
 };
 
-/// The three material handles one attach-model batch fades through — the item lane's
-/// [`FadeSet`], read straight off the built part (an item batch never carries a character
-/// runtime slot the way a body batch does).
+/// The materials one item batch fades through.
 fn item_fade_set(part: &super::super::EntityPart) -> FadeSet<'_> {
     FadeSet {
         steady: &part.material,
@@ -31,28 +26,23 @@ fn item_fade_set(part: &super::super::EntityPart) -> FadeSet<'_> {
     }
 }
 
-/// Everything one slot's spawn needs from its WEARER, read once per unit — the context
-/// [`spawn_slot`] carries so the per-slot body isn't a fifteen-argument call.
+/// What one slot's spawn needs from its wearer, read once per unit.
 struct WearerCtx<'a> {
-    /// The unit wearing the item — the parent whose tint, light collector and fade it inherits.
+    /// The unit wearing the item, whose tint, light collector and fade it inherits.
     wearer: Entity,
     bones: &'a BoneAttach,
-    /// The unit's appear-fade clock, for a part spawning mid-ramp ([`join_unit_appear_fade`]).
+    /// The unit's appear-fade clock, for a part spawning mid-ramp.
     joined: JoinedFade,
     now: f32,
-    /// The wearer's rig-palette slot, pre-shifted into `MeshTag` bits (decision 0812).
+    /// The wearer's rig-palette slot, pre-shifted into `MeshTag` bits.
     rig_slot: u16,
-    /// The wearer's body bake centre, when it has one — the interior classifier's fold reference.
+    /// The wearer's body bake centre, the interior classifier's fold reference.
     body_center: Option<Vec3>,
-    /// The wire scale the unit renders at: the world yards its held effects' draw-order rung is
-    /// measured in ([`benilla_world::particles::owner_last_bias`]).
+    /// The unit's wire scale, which its held effects' draw-order rung is measured in.
     scale: f32,
 }
 
-/// The **re-seat writers** (decision 0826): everything under an item root that caches *where on the
-/// body* the item sits. A pure attach-point change — the sheath swap — MOVES the root instead of
-/// rebuilding it, and these move by the same delta, so the item's glow instances, its effect hosts
-/// and its live particle clouds all ride along instead of being orphaned and respawned.
+/// Everything under an item root that caches where on the body it sits, re-seated on a move.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(in crate::entities) struct SeatWriters<'w, 's> {
     children: Query<'w, 's, &'static Children>,
@@ -63,17 +53,9 @@ pub(in crate::entities) struct SeatWriters<'w, 's> {
 }
 
 impl SeatWriters<'_, '_> {
-    /// Move every cached seat in `root`'s subtree to the item's new attach point: the body `bone`
-    /// it now hangs from, and `delta` = `new_offset − old_offset` applied to each cached offset.
-    ///
-    /// The delta (rather than an assignment) is what makes this total: a mirror's offset is the
-    /// attach point *plus* something model-local — a card's own pivot, a glow slot's point on the
-    /// item — and only the attach-point term moves. The walk is recursive because an item's glow
-    /// instances hang two levels down.
-    ///
-    /// `attach` is assigned, not delta'd: it names WHICH attachment node the item now sits in, and
-    /// that is what a widget's attach reset filters on ([`crate::portrait::attach_reset`]). A move
-    /// that left it stale would keep, say, a stowed weapon marked with the hand id it left.
+    /// Move every cached seat under `root` to `bone`, shifting each offset by `delta` (a mirror's
+    /// offset also holds a model-local term, a card's pivot, that stays) and setting `attach` for
+    /// the widgets' attach reset. Recursive: glow instances hang two levels down.
     fn reseat(&mut self, root: Entity, bone: u16, attach: u16, delta: Vec3) {
         let mut stack = vec![root];
         while let Some(e) = stack.pop() {
@@ -109,21 +91,10 @@ impl SeatWriters<'_, '_> {
     }
 }
 
-/// Spawn/refresh the held-item children for every unit whose [`HeldItems`] changed (or whose item
-/// model finished loading): each slot's model parts spawn under the attach point's joint entity at
-/// the attachment offset, so they ride the bone. Slots whose model is still loading are left pending
-/// (the `applied` diff key keeps them un-applied) and picked up on a later pass. A part spawning while
-/// the unit's own appear-fade is still in flight joins it ([`join_unit_appear_fade`]) instead of
-/// 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`) 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.
+/// Spawn each changed slot's item model under its attachment's joint once the model has built.
+/// The diff is per slot, and a new attach point alone moves the root: the reference's sheath
+/// paths touch only the weapon and quiver ids (`0x611770`) and stow a melee weapon by re-parenting
+/// its model (`0x60b590`, `0x712f70`), so the model and everything riding it survive.
 #[allow(clippy::type_complexity)]
 pub(in crate::entities) fn attach_held_items(
     mut commands: Commands,
@@ -134,32 +105,18 @@ pub(in crate::entities) fn attach_held_items(
         Entity,
         Option<&UnitAppearFade>,
         Option<&benilla_world::interior::BodyBakeCenter>,
-        // The unit root's own transform — its scale is the wire `NetEntity::scale` the streamer
-        // writes (`entities::attach`), and the held effects' draw-order rung is measured in the
-        // world yards that scale produces.
         Option<&Transform>,
-        // The WEARER's rig, for its instance slot — the fallback an attached model's parts carry
-        // in their tag when they have no slot of their own, so the wearer's body tint still
-        // reaches them (decision 0812 — the reference's attached models inherit the parent CM2's
-        // computed colours, `0x714000`). An item that owns a slot carries its own instead and
-        // inherits the tint up the `ParentModel` chain: the `welds_billboard` joint rig (0841),
-        // and — since 1609 — every ordinary attached model, which rides one rigid palette frame
-        // composed in this rig's frame rather than an absolute world matrix.
+        // The wearer's slot, which a slotless item's parts carry so the body tint reaches them;
+        // an attached model inherits its parent's computed colours (`0x714000`).
         Option<&benilla_world::rig_palette::RigSkin>,
-        // The wearer's pose buffer: the attach joint spawns on first demand from the composed
-        // pose (`RigPose::anchor_for`, decision 1355) — a weapon equipped in combat seats at the
-        // live pose, never the rest pose.
+        // The attach joint spawns on demand from the live pose, never the rest pose.
         Option<&mut benilla_world::rig_anim::RigPose>,
     )>,
     held: Option<Res<ItemDisplays>>,
     time: Res<Time>,
     mut seats: SeatWriters,
-    // The MOVE path re-seats a rider in place: an attach-point change is the one edit that leaves
-    // the item's entity alive while changing the bone its palette frame is composed from (1609).
+    // A move keeps the item alive but changes the bone its palette frame is composed from.
     mut movers: Query<&mut benilla_world::rig_rider::RigRider>,
-    // Every attached model with a skeleton allocates a palette slot of its own: one rigid frame in
-    // the wearer's rig frame (1609), or — for a display that welds geometry to a billboard bone,
-    // which has no correct rigid placement at all — its own camera-replaced joint rig (0841).
     mut palettes: ResMut<benilla_world::rig_palette::RigPalettes>,
 ) {
     let Some(held) = held else {
@@ -169,11 +126,7 @@ pub(in crate::entities) fn attach_held_items(
     for (items, bones, attached, entity, unit_fade, body_center, unit_tf, skin, mut pose) in
         &mut units
     {
-        // A held item / helm / shoulder resolves and spawns asynchronously (a template round trip, a
-        // model load) — often *after* the body has already armed its appear-fade (decision 0032 is a
-        // per-unit property: the reference fades the whole unit, attachments included, as one). Read
-        // the unit root's fade clock once per unit so every part spawned below joins the same ramp
-        // instead of popping in opaque.
+        // The reference fades a unit and its attachments as one, so a late part joins the ramp.
         let ctx = WearerCtx {
             wearer: entity,
             bones,
@@ -183,8 +136,7 @@ pub(in crate::entities) fn attach_held_items(
             body_center: body_center.map(|c| c.0),
             scale: unit_tf.map_or(1.0, |t| t.scale.max_element()),
         };
-        // Diff against what's spawned; skip when unchanged. A slot whose model hasn't built parts yet
-        // is masked out of `next` so it stays "not yet applied" and re-attaches once the parts exist.
+        // A slot whose model has not built stays unapplied, and attaches once it has.
         let mut next = items.clone();
         for slot in next.slots.iter_mut() {
             let ready = slot.is_some_and(|hs| {
@@ -218,9 +170,7 @@ pub(in crate::entities) fn attach_held_items(
             if was == wants {
                 continue;
             }
-            // The MOVE: same item, new attach point (the sheath swap). Everything riding the root
-            // — meshes, cards, glow instances, lights, ribbons and the live particle pools that
-            // owner-follow it — comes along, and the cached booth seats shift with it.
+            // The move: same item, new attach point; everything riding the root comes along.
             if let (Some(w), Some(n), Some(root)) = (was, wants, *root) {
                 if w.same_item(&n) {
                     if let Some((&(bone, offset), &(_, old))) = ctx
@@ -237,10 +187,7 @@ pub(in crate::entities) fn attach_held_items(
                             commands
                                 .entity(root)
                                 .insert(Transform::from_translation(offset));
-                            // The rider's frame is composed from (bone, offset), so the move has
-                            // to carry it — otherwise a sheathed sword keeps drawing at the hand
-                            // it was drawn from while its entity, its glow and its emitters all
-                            // travel to the hip (1609).
+                            // The rider's frame is composed from (bone, offset): carry it too.
                             if let Ok(mut rider) = movers.get_mut(root) {
                                 rider.bone = bone;
                                 rider.local = offset;
@@ -255,8 +202,7 @@ pub(in crate::entities) fn attach_held_items(
                     }
                 }
             }
-            // Otherwise this slot really is a different item (or none): tear the old one down —
-            // model gone, effects gone with it — and build the new one.
+            // A different item, or none: rebuild.
             if let Some(old) = root.take() {
                 commands.entity(old).despawn();
             }
@@ -285,9 +231,7 @@ pub(in crate::entities) fn attach_held_items(
     }
 }
 
-/// Spawn one slot's item model under its attach point, with everything that rides it: the mesh
-/// parts, the camera-facing cards, the booth mirrors, the item glow, the emitters, the lights and
-/// the ribbons. `None` when the display has no built parts or the body has no such attach point.
+/// Spawn one slot's item model and everything riding it, if its parts and attach point exist.
 fn spawn_slot(
     commands: &mut Commands,
     palettes: &mut benilla_world::rig_palette::RigPalettes,
@@ -301,29 +245,20 @@ fn spawn_slot(
     let (bones, joined, now) = (ctx.bones, ctx.joined, ctx.now);
     let dm = held.models.get(&(hs.display, hs.kind))?;
     let parts = dm.parts.as_ref()?;
-    // Body model has no such attach point (a non-character skeleton) — hold nothing.
     let &(bone, offset) = bones.points.get(&hs.attach)?;
-    // The attach joint, spawned on first demand from the wearer's composed pose (decision 1355).
     let joint = pose?.anchor_for(commands, entity, bone)?;
     let root = commands
         .spawn((
             Transform::from_translation(offset),
             Visibility::default(),
-            // This item model is CHAINED to the body wearing it (`0x712f70` attach → the
-            // `[model+0x1cc]` parent link): the wearer's computed render alpha multiplies
-            // everything this root carries, and everything chained below it in turn — its glow
-            // instances included (decision 0833).
+            // Chained to the wearer (`0x712f70` sets `[model+0x1cc]`): the wearer's render alpha
+            // multiplies everything under this root, glow instances included.
             benilla_world::model_fade::ParentModel(entity),
         ))
-        // Chain-only visibility (benilla_world::vis_chain): the wrapper renders nothing —
-        // the item's parts and glows are the children.
         .vis_chain_only()
         .id();
     commands.entity(joint).add_child(root);
-    // The item/enchant glow (decision 0805): its instances hang off the ITEM's own
-    // attachment points, so they are children of this root — spawned by
-    // [`super::item_glow::attach_item_glows`] once the glow models build, and reaped with
-    // the root on any gear/sheath change, which is the whole lifetime rule.
+    // The glow hangs off the item's own attachment points, so it lives and dies with this root.
     if hs.visual != NO_GLOW {
         commands
             .entity(root)
@@ -331,39 +266,28 @@ fn spawn_slot(
                 display: hs.display,
                 kind: hs.kind,
                 visual: hs.visual,
-                // The item's seat on the BODY, carried so the glow attach can publish its own
-                // booth mirrors at a seat composed from it (decision 0822) — the glow spawns
-                // asynchronously and knows only this root. The attach id rides along for the
-                // same reason: a glow is chained UNDER the item, so the reference's attach reset
-                // takes it exactly when it takes the item ([`crate::portrait::attach_reset`]).
+                // The item's seat, for the glow's booth mirrors, and its attach id, so the
+                // widgets' attach reset takes the glow with the item.
                 bone,
                 offset,
                 attach: hs.attach,
             });
     }
-    // The engine-drawn bowstring (0408 §G2) — for the drawn BOW only: the ranged slot's
-    // 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 (`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).
+    // The bowstring, for a drawn bow only, the ranged slot in the left hand: `0x611e10` registers
+    // `0x611ff0` for subclass Bow. The `$WTT`/`$WTB` markers are not the gate, as melee weapons
+    // author them too for the swing trail (`0x6c67f0`).
     if slot_idx == 2 && hs.attach == attach_id::HAND_LEFT {
         if let Some([top, bottom]) = dm.string_anchors {
             commands.entity(root).insert(crate::bowstring::Bowstring {
                 owner: entity,
-                // Bone AND offset: the prop flexes, so the tips move (decision 2281).
+                // Bone and offset: the prop flexes, so the tips move.
                 top,
                 bottom,
             });
         }
     }
-    // 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
-    // the special case, not the rule. `0x6c67f0`'s `0x7130e0` presence gate is exactly the
-    // `string_anchors` `Option` — a weapon authoring only one marker draws nothing at all.
+    // The swing trail's `WTOBJECT`, one per weapon hand (`0x608d60`) and freed with the model,
+    // for a model with both markers (`0x6c67f0`'s `0x7130e0` presence gate).
     if slot_idx <= 1 {
         if let Some([top, bottom]) = dm.string_anchors {
             commands
@@ -371,11 +295,8 @@ fn spawn_slot(
                 .insert(crate::weapon_trail::WeaponTrail::new(top.1, bottom.1));
         }
     }
-    // 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
-    // the bowstring can't key the same way). The drawer spans it to the owner's channel bobber.
+    // The fishing line's near anchor (`0x61f780`). The reference gates on class 2 subclass 20 and
+    // `$CCH`; only one weapon model in the data authors `$CCH`, so the marker alone is equivalent.
     if slot_idx == 0 {
         if let Some(tip) = dm.cch_marker {
             commands
@@ -383,40 +304,18 @@ fn spawn_slot(
                 .insert(crate::fishing_line::FishingPoleTip { owner: entity, tip });
         }
     }
-    // **The RANGED PROP's own animation** (decision 2281) — benilla's `[CGUnit+0xd24]`. The
-    // reference keeps the equipped ranged weapon's M2 *instance* and re-arms its animation from the
-    // body's `$BWP`/`$BWR` keyframes: BowPull(160) on the pull, and on the release either Stand(0)
-    // (a bow's limbs relax) or **BowRelease(161)** — which on a firearm is the muzzle blast, seven
-    // particle emitters keyed to zero in Stand and to a 0.2 s burst in 161. See
-    // [`crate::ranged_flex`] for the byte law and the corpus measurement.
-    //
-    // So this one held model is NOT the lane's "rests at bind pose" case, and it earns the three
-    // things a resting attach model is denied: a pose buffer, a player, and bone ANCHORS for its
-    // emitters (bone 2 of every firearm is keyed +90° in 161 — that rotation is what aims the blast
-    // down the barrel). The gate is the asset: 46 of the 571 shipped weapon models author 160 or
-    // 161, all of them bows, crossbows and firearms, and nothing else in the corpus does.
+    // The ranged prop (`[CGUnit+0xd24]`) animates off the body's `$BWP`/`$BWR` keys: BowPull (160)
+    // on the pull, then Stand or BowRelease (161), a firearm's muzzle blast (`crate::ranged_flex`).
+    // So it gets a pose, a player and bone anchors; only bows, crossbows and firearms author them.
     let flexes = slot_idx == 2
         && !dm.skeleton.joints.is_empty()
         && dm.animations.as_ref().is_some_and(|a| {
             a.owns(crate::ranged_flex::BOW_PULL) || a.owns(crate::ranged_flex::BOW_RELEASE)
         });
-    // **The item rig** (decisions 0841, withdrawn by 0847, RESTORED by 0854) — the one case an
-    // 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 (`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 (`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
-    // global-sequence drive — all seven affected models are **keyless** (`m2bones`: not one
-    // T/R/S key between them), so every non-billboard joint's palette row is the identity the
-    // static mesh already drew, and the emitters/lights/ribbons below keep riding `root`.
+    // The item rig, for geometry welded to a billboard bone (an R14 pauldron's spikes): the
+    // reference billboards an attached model like a standalone one (`0x718657`..`0x71876f`),
+    // blending the bone's camera-replaced row per vertex (`0x71a460`). All seven such models are
+    // keyless, so no other joint moves.
     let item_rig = dm
         .inverse_bindposes
         .as_ref()
@@ -429,15 +328,10 @@ fn spawn_slot(
             {
                 commands.entity(root).insert(bb);
             }
-            // Slot 0 (table full, warned once) ⇒ no rig: the parts below fall back to the static
-            // mesh and the wearer's slot, i.e. exactly the pre-0841 look. Never a crash, never a
-            // missing shoulder.
+            // A full palette table gives no rig: the static mesh and the wearer's slot instead.
             let rig = benilla_world::rig_palette::RigSkin::allocate(palettes, joints, ibp.clone())?;
             let slot = rig.slot;
             commands.entity(root).insert(rig);
-            // The lane is otherwise invisible from outside the renderer — seven models in 9691 take
-            // it, and a run where the gate silently stopped firing looks exactly like a run where
-            // nothing was equipped. Naming the slot is what lets a probe say which it was.
             debug!(
                 "item rig: display {} welds a billboard bone → palette slot {slot} ({} bones)",
                 hs.display,
@@ -445,25 +339,12 @@ fn spawn_slot(
             );
             Some(slot)
         });
-    // **The rider** (decision 1609) — the other, and now ordinary, reason an attached model owns a
-    // palette slot. It is not the item's skeleton: an item rests at bind pose, so every row of it
-    // is the same placement matrix, and the lane writes that ONE frame — composed in the WEARER's
-    // rig frame, with the wearer's world position riding the slot's `rig_origin`.
-    //
-    // The picture is unchanged by construction (bind pose ⇒ `row = F` ⇒ the static mesh's own
-    // placement); what changes is that the placement is never an absolute f32 world coordinate.
-    // Built as a `~9500 + ~1` sum every frame, it landed on the 0.98 mm ULP grid of the large map
-    // axis and the helm snapped a whole ULP sideways every other frame while the body under it
-    // moved exactly — the jitter the director reported on the Goldshire guard. See
-    // [`benilla_world::rig_rider`] for the measurement and the residuals.
-    //
-    // A boneless display has no skinned twin to draw and keeps the old route; so does a palette
-    // with no room, which is the same graceful fallback the `welds_billboard` lane already had.
+    // The rider: an item at bind pose draws through one palette frame composed in the wearer's rig
+    // frame, never an absolute f32 world matrix, whose ~9500 yd sums fall on a 0.98 mm grid and
+    // jitter. A boneless display, or a full palette, keeps the static mesh.
     let rider = match item_rig {
         Some(_) => None,
-        // A slot only earns its keep if something will actually SKIN through it: a display with
-        // bones but no skinned twin on any drawn part (a card-only model) would take a slot that
-        // no vertex ever indexes, and keep the absolute placement anyway.
+        // Only when some drawn part has a skinned twin to index the slot.
         None => (!dm.skeleton.joints.is_empty()
             && parts
                 .iter()
@@ -472,9 +353,8 @@ fn spawn_slot(
             benilla_world::rig_palette::RigSkin::allocate_bones(
                 palettes,
                 dm.skeleton.joints.len() as u32,
-                // A resting rider needs no inverse bindposes — at bind pose every row collapses to
-                // the placement and 1609's write never consults them. A FLEXING prop's rows are
-                // `F × model[b] × ibp[b]`, so its slot carries the real handle.
+                // A resting rider's rows are the placement alone; a flexing prop's are
+                // `F × model[b] × ibp[b]`.
                 if flexes {
                     dm.inverse_bindposes.clone().unwrap_or_default()
                 } else {
@@ -497,17 +377,9 @@ fn spawn_slot(
             slot
         }),
     };
-    // The flexing prop's own pose buffer and clock (see `flexes` above). The collapsed lane
-    // ([`benilla_world::rig_anim::RigPose`] — no joint entities; bone anchors are minted on demand
-    // by the emitter loop below), armed on the model-load bootstrap the reference gives every M2
-    // instance: animation id 0 through the model's own `playableAnimationLookup`. From there
-    // [`crate::ranged_flex`] re-arms it per keyframe.
-    //
-    // Its palette rows stay the RIDER lane's — `RigRider` is still on this root, and 2281 taught
-    // that lane to compose a pose rather than repeat one frame. That is deliberate: composing this
-    // prop from its own absolute `GlobalTransform` instead would hand the bow back the 0.98 mm
-    // one-ULP staircase 1609 exists to have removed (the attach point is a ~1 yd quantity summed
-    // onto a ~9500 yd one, recomputed every frame).
+    // The flexing prop's pose and clock, armed as the reference arms every M2 at load (animation 0
+    // through its `playableAnimationLookup`). Its palette rows stay the rider's, composed in the
+    // wearer's frame, not from its own `GlobalTransform`.
     let mut prop_pose = (flexes && rider.is_some()).then(|| {
         let anims = dm.animations.as_ref().expect("flexes ⇒ animations");
         let mut player = AnimationPlayer::default();
@@ -525,16 +397,11 @@ fn spawn_slot(
         ));
         benilla_world::rig_anim::RigPose::new(root, &dm.skeleton)
     });
-    // The instance slot every part below carries in its `MeshTag`. The WEARER's only when the item
-    // has no palette slot of its own — that is what puts a tinted body's colour on a boneless
-    // helm (decision 0812). An item WITH a slot must carry its own, because the vertex stage
-    // indexes the palette with the same field; the wearer's tint reaches it through the
-    // `ParentModel` chain instead, which is the reference's own route for an attached model's
-    // colours (`0x714000`, `aura_visual::chained_tint`).
+    // The slot each part's `MeshTag` carries: the item's own when it has one, as the vertex stage
+    // indexes the palette by it and the tint arrives up the `ParentModel` chain (`0x714000`),
+    // else the wearer's, which carries the body's tint.
     let rig_slot = item_rig.or(rider).unwrap_or(ctx.rig_slot);
-    // Billboard batches (the torch's glow card) collected for the world-root card spawn
-    // below — as plain children they'd render at the item root (the grip), not the
-    // authored pivot (the torch head). Decision 0153.
+    // Billboard batches spawn as world-root cards below; as children they would sit at the grip.
     let mut billboard_parts = Vec::new();
     commands.entity(root).with_children(|parent| {
         for part in parts {
@@ -542,16 +409,11 @@ fn spawn_slot(
                 billboard_parts.push((info.clone(), part));
                 continue;
             }
-            // Per-part join decision: `joined` (the unit's clock) combined with whether this
-            // part is fade-capable at all. A pending part opens on the blend twin at ≈0 and a
-            // joiner at the ramp's *current* alpha, so neither flashes for a frame.
+            // A part joining the unit's fade opens at the ramp's current alpha: it never flashes.
             let set = item_fade_set(part);
             let effective = PartFade::resolve(joined, &set);
             let (init_mat, tag_alpha) = effective.seed(&set, now);
-            // An item with a palette slot draws the SKINNED twin — every part of it, not only a
-            // welded batch: the model rests at bind pose, so each non-billboard bone's palette row
-            // is the placement matrix itself and the batches land pixel-for-pixel where the static
-            // mesh had them. Slotless (boneless display, or a full palette) falls back to `mesh`.
+            // An item with a palette slot draws every part's skinned twin, a slotless one `mesh`.
             let skinned = item_rig.or(rider).and(part.skinned_mesh.as_ref());
             let mut child = parent.spawn((
                 Mesh3d(skinned.unwrap_or(&part.mesh).clone()),
@@ -561,14 +423,9 @@ fn spawn_slot(
                     kind: ModelKind::Creature,
                     blend: part.blend,
                 },
-                // The picker's triangles (decision 0857): the `WOW_PICK` probe names worn gear
-                // through `ModelPart`, and the render meshes are `RENDER_WORLD`-only.
+                // The picker's triangles; the render meshes are `RENDER_WORLD`-only.
                 benilla_world::interact::PickMesh(part.geometry.clone()),
-                // The portrait booth mirrors this rider ([`crate::portrait`]): steady
-                // material (not the fade twin) + where it sits, so the bake can seat it at
-                // the bone's bind-pose global (the booth spawns no skeleton). It stays the
-                // STATIC mesh even for a rigged item — the booth has no palette to skin
-                // through, and bind pose is what it wants to bake anyway.
+                // The booth's mirror: the static mesh and steady material at the bone's bind pose.
                 crate::portrait::PortraitRider {
                     static_mesh: part.mesh.clone(),
                     material: part.material.clone(),
@@ -578,42 +435,20 @@ fn spawn_slot(
                 },
             ));
             if skinned.is_some() {
-                // The palette replaces this part's world matrix outright, so its model-local
-                // `Aabb` below is not the volume it draws in — the same reason the effect lane's
-                // skinned parts opt out (`spell_fx`). It also keeps the reference's own rule that
-                // a scene object is elected ONCE, at the body root, never per batch (1473) — which
-                // is what a rider's part would otherwise start doing, since the skinned twin keeps
-                // main-world data and so earns the `calculate_bounds` the static twin never had.
+                // The palette replaces the part's world matrix, so its `Aabb` is not where it
+                // draws; and the reference elects a scene object once, at the body root.
                 child.insert((
                     benilla_world::rig_palette::RigPart(root),
                     bevy::camera::visibility::NoFrustumCulling,
                 ));
             }
-            // Interior-light parity with the body: both material variants + a MeshTag, so the
-            // classifier relights the weapon inside a WMO room like it does its wielder. While
-            // joining the unit's appear-fade the tag carries its alpha instead — the classifier
-            // 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`), 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.
-            //
-            // The tag is unconditional (it used to ride the classifier's `Some`): it carries
-            // the WEARER's instance slot, which is what puts a tinted body's colour on its
-            // helm and shoulders — the director's report on the dwarf Stoneform tint. A part
-            // with no interior variant got no tag at all before, so it was also invisible to
-            // the ground-shade ramp that darkens its wielder; both now follow the body, which
-            // is the same light-collector aliasing the comment above describes.
+            // Lit as its wearer, whose light collector an equipped item aliases
+            // (`[item+0x3b8] = [wearer+0x3b8]`, `0x718960`). Every part gets a tag, interior
+            // variant or not, so the tint and the ground shade reach it.
             child.insert(MeshTag(benilla_world::mesh_tag::spawn_tag(
                 rig_slot, tag_alpha,
             )));
-            // The item part's build-time bound (decision 0834): `calculate_bounds` can no longer
-            // derive one from the `RENDER_WORLD`-only static form's data. Skipped for a skinned
-            // part — it opted out of the frustum cull above, and a stale bound would only mislead
-            // the picker volume that reads it.
+            // The build-time bound, as the render mesh is `RENDER_WORLD`-only; none when skinned.
             if let (None, Some(aabb)) = (skinned, part.aabb) {
                 child.insert(aabb);
             }
@@ -626,46 +461,26 @@ fn spawn_slot(
             ) {
                 child.insert(lit);
             }
-            // 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).
+            // The authored alpha, `colourAlpha × weight` (`0x707680`), pinned to the file's first
+            // sequence and composed into the tag in the unit lane's order.
             if let Some(anim) = &part.alpha_anim {
-                // `resting` is the attach model's pinned read — right for every held item but the
-                // one that plays sequences (decision 2281): a flexing prop's per-sequence alpha
-                // loops follow its own player, like a creature's do.
+                // A flexing prop's alpha follows its own player.
                 child.insert(if flexes {
                     benilla_world::doodad_anim::MatAnim::following(anim.clone(), root)
                 } else {
                     benilla_world::doodad_anim::MatAnim::resting(anim.clone())
                 });
             }
-            // …and the batch's texture transform (decision 2295), on the same one predicate every
-            // other entity spawn asks. One held-item batch in the whole 1.12 corpus animates one —
-            // `Item\ObjectComponents\Shield\shield_epic_a_01`, the Drillborer Disk, whose
-            // Ragnaros-skinned lava is a 6.7 s global-sequence scroll — which is exactly why the
-            // marker is a property of the batch here and not of a list somebody maintains.
             if part.uv_loops().animates() {
                 child.insert(benilla_world::doodad_anim::AnimMatPart);
             }
             effective.dress(&mut child, &set);
         }
     });
-    // The billboard cards (decision 0153): world-root entities FOLLOWING `root` — it sits
-    // at the attach offset under the hand joint, is fresh per attach, and despawns on a
-    // gear change, so the card's lifecycle and frame both come for free (same owner
-    // contract as the item's emitters below).
+    // The billboard cards: world-root entities following `root`, which they despawn with.
     for (info, part) in billboard_parts {
-        // …and, under `root`, the booth **mirror carrier** for that card (decision 0822).
-        // The card itself is a world-ROOT entity, so the portrait / paper-doll booths — which
-        // mirror the unit's dressed descendants — cannot see it; without this marker an
-        // item's camera-facing batch (a wand's gem, this torch's `GLOWWHITE32` halo) simply
-        // did not exist in those panes. Its seat is the attach point **plus the batch's own
-        // model-local pivot**: an item model spawns no rig, so nothing else bakes that pivot.
+        // The booths mirror only the unit's descendants, so the card's mirror sits under `root`,
+        // seated at the attach point plus the batch's own pivot.
         commands.entity(root).with_child((
             Transform::default(),
             Visibility::default(),
@@ -678,11 +493,7 @@ fn spawn_slot(
                 attach: Some(hs.attach),
             },
         ));
-        // A card is a batch of the item's model and joins the wearer's appear-fade exactly like
-        // its mesh siblings above — same [`PartFade`], same seed, same arm. It used to spawn at
-        // a flat opaque with neither `RenderFade` nor `FadeMaterials`, which is why a weapon's
-        // glowing gems were already blazing before the character carrying them had faded in
-        // (director-reported on the Hungering Cold; decision 0836).
+        // A card joins the wearer's appear-fade like its mesh siblings.
         let set = item_fade_set(part);
         let effective = PartFade::resolve(joined, &set);
         let (init_mat, tag_alpha) = effective.seed(&set, now);
@@ -694,18 +505,14 @@ fn spawn_slot(
                 kind: ModelKind::Creature,
                 blend: part.blend,
             },
-            // The picker's triangles (decision 0857), pivot-centred by the caster like the bake.
+            // The picker's triangles, pivot-centred by the caster like the bake.
             benilla_world::interact::PickMesh(part.geometry.clone()),
             BillboardCard::following(&info, root),
         ));
-        // The card's build-time bound (decision 0834) — same rule as its mesh siblings above.
         if let Some(aabb) = part.aabb {
             card.insert(aabb);
         }
-        // Same interior-light membership the item's mesh parts get above, through the same
-        // constructor and anchored at the same WEARER (decision 0778) — so a held torch's
-        // glow card can never split from the arm holding it. …and the wearer's instance slot,
-        // like its mesh siblings: a tinted body colours the torch's glow card too (0812).
+        // Tagged and lit as its mesh siblings, anchored at the wearer.
         card.insert(MeshTag(benilla_world::mesh_tag::spawn_tag(
             rig_slot, tag_alpha,
         )));
@@ -718,8 +525,7 @@ fn spawn_slot(
         ) {
             card.insert(lit);
         }
-        // The card's own share of the authored material alpha (the Hungering Cold's gems are
-        // keyed 0.30) — same pinned lane as the mesh parts.
+        // The card's authored alpha, pinned as the mesh parts' is.
         if let Some(anim) = &part.alpha_anim {
             card.insert(benilla_world::doodad_anim::MatAnim::resting(anim.clone()));
         }
@@ -728,26 +534,12 @@ fn spawn_slot(
         }
         effective.dress(&mut card, &set);
     }
-    // The item's own particle emitters — the held torch's flame (0130 phase 4: the same
-    // owner-follow rider as doodad emitters). `root` sits at the attach offset under the
-    // hand joint and its frame IS the item's model frame; a held item spawns no skeleton,
-    // so the rest pose applies and no pivot rebase is needed — the flame burns at its
-    // authored spot (the torch tip) and follows the hand through the swing. Free entities:
-    // they self-despawn with `root` via the owner contract (gear change, unit despawn).
-    // The spawn transform does two jobs, and neither is placing the emitter (the owner
-    // overwrites the position every frame): its TRANSLATION seeds the flicker RNG —
-    // root's entity bits de-sync two torch-bearers standing side by side — and its SCALE
-    // is the wearer's, which is what the effects' draw-order rung is measured in
-    // (`particles::owner_last_bias`). An item on a twice-size wielder reaches twice as
-    // far from its own origin, so its rung has to grow with it; reading the scale off a
-    // transform built as a bare RNG seed silently pinned every held effect at 1×.
+    // The item's emitters: free entities following `root` at rest pose, despawned with it. The
+    // spawn transform does not place them: its translation seeds the flicker RNG per item and its
+    // scale is the wearer's, which the effects' draw-order rung is measured in.
     let spawn_tf = Transform::from_translation(Vec3::splat(root.to_bits() as f32))
         .with_scale(Vec3::splat(ctx.scale));
-    // 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. One marker per item, on
-    // the root that already reaps with it.
+    // The booths' mirror of those emitters, which are not unit descendants.
     if !dm.emitters.is_empty() {
         commands
             .entity(root)
@@ -759,23 +551,10 @@ fn spawn_slot(
             });
     }
     for em in &dm.emitters {
-        // …with ONE exception to "the rest pose applies": a **billboard** bone in the
-        // emitter's chain. Its palette rows are replaced with the camera basis about its
-        // own pivot every frame and children multiply onto that, so the reference's
-        // emitter origin is `pivot + camBasis·(position − pivot)` — camera-dependent, and
-        // up to two chain-offsets away from where the rest pose puts it (decision 0813).
-        // The rig lane gets this from its joint palette; an item model has no rig, so the
-        // frame is realized as a mesh-less billboard card the emitter OWNS-follows
-        // (`BillboardCard::frame_following`). Nothing else in the chain is live: of the
-        // 95 item models whose emitters ride a billboard bone, none animates its chain.
-        //
-        // …and ONE exception to *that*: a **flexing ranged prop** (decision 2281) does have a rig,
-        // so its emitter rides its BONE's anchor. The firearm muzzle bank hangs off bone 2, which
-        // BowRelease(161) keys a constant +90° about Y against Stand's 0° — on the root frame the
-        // blast sprays out of the receiver, on the bone it goes down the barrel. `bone_pivot`
-        // rebases the authored model-space origin into that bone's frame, exactly as the doodad and
-        // widget lanes do. A billboard chain still wins the fork above: it is camera-replaced, and
-        // no flexing model in the corpus has one.
+        // A billboard bone in the chain puts the reference's emitter origin at
+        // `pivot + camBasis·(position − pivot)`, so the emitter follows a mesh-less billboard frame
+        // at rest pose. A flexing prop's emitter rides its bone's anchor, rebased by `bone_pivot`:
+        // the firearm muzzle bone turns 90° in BowRelease.
         let posed = prop_pose
             .as_mut()
             .filter(|_| em.billboard.is_none())
@@ -809,30 +588,17 @@ fn spawn_slot(
             spawn_tf,
             benilla_world::particles::EmitterFrames {
                 owner: Some(posed.unwrap_or(owner)),
-                // A held item is an attached model — the flame fans with the swing.
-                // The cloud anchors at the MODEL; the bone composes births only.
+                // The cloud anchors at the model; the bone composes births only.
                 anchor: Some(root),
-                // The item model is destroyed when the item is replaced or unequipped, and the
-                // reference frees a model's emitters at its dtor — so no cloud is left hanging in
-                // the air behind the character (decision 0826). A sheath swap no longer comes
-                // through here at all: the root is MOVED, and this pool rides it.
+                // The reference frees a model's emitters with the model: no cloud is left behind.
                 on_owner_loss: benilla_world::particles::OwnerLoss::Free,
-                // This emitter's own model instance is the item root; `ParentModel` above chains
-                // it to the wearer, and the chain is what an ATTACHED model's composed alpha is
-                // (`0x714000`) — so the sparkle on a pauldron fades in with the body wearing it
-                // and vanishes with the avatar in first person (0827/0833).
+                // The item root, whose chain is an attached model's alpha (`0x714000`).
                 alpha: Some(root),
-                // The light node is the WEARER's, never the item's: the reference has one node
-                // per object and aliases the wearer's collector into each attached model
-                // (`[item+0x3b8] = [wearer+0x3b8]`, `0x718960`) — the same rule this item's mesh
-                // batches already classify under (`BodyBakeCenter`).
+                // The wearer's light node, aliased into each attached model (`0x718960`).
                 light_node: Some(entity),
             },
-            // A held item spawns no rig; its emitters run the item model's own **loader-idle**
-            // slot on the spawn clock (the torch burns always — the doodad law). A flexing ranged
-            // prop does have a player, and its rate/gate tracks read the sequence it is actually
-            // on: the gun's blast is keyed to zero in Stand and to a 0.2 s burst in BowRelease,
-            // so a pinned clock would emit nothing on it for ever (decision 2281).
+            // A resting item's emitters run its loader-idle sequence; a flexing prop's the one it
+            // plays, since a gun's blast is keyed only in BowRelease.
             if flexes {
                 benilla_world::particles::EmitClock::Host(root)
             } else {
@@ -840,18 +606,9 @@ fn spawn_slot(
             },
         );
     }
-    // The item's own M2 point light — **the held torch's glow** (decision 0016's law on the
-    // entity half of the scene; see `super::carried_light`). `Club_1H_Torch_A_01.m2` — the
-    // torch every torch-bearing NPC carries — authors exactly one: a warm
-    // `(0.467, 0.290, 0.133) × 3.0` point light 0.58 yd up the shaft. It rides `root` like
-    // the emitters and for the same reason (the item poses at rest, so its model space IS
-    // the bone-local frame), which walks it through the hand's swing; the fence rails and
-    // grass around the bearer then gather it like any other scene point light.
+    // The item's own M2 point lights (a held torch's glow), riding `root` like the emitters.
     spawn_carried_lights(commands, &dm.lights, root, |_| None);
-    // The item's ribbon trails (weapon enchant streaks): ride the item root — a held item
-    // poses at rest, so the bone-local origin is model-space (no pivot rebase). A held item
-    // rests in Stand (anim 0): a thrown weapon's trail is keyed dark there, so the flight
-    // ribbon never shows in the hand — it lights only on the InFlight missile.
+    // The ribbons ride the item root in Stand, where a thrown weapon's flight trail is keyed dark.
     for rb in &dm.ribbons {
         benilla_world::ribbons::spawn_ribbon(
             commands,
@@ -859,14 +616,11 @@ fn spawn_slot(
             root,
             false,
             ctx.scale,
-            // A worn item rests in `Stand` and nothing on it plays anything else — the one lane
-            // where the enable gate genuinely has a fixed answer for the instance's life.
+            // Stand, the sequence a worn item rests in.
             benilla_world::ribbons::RibbonSeq::Fixed(0),
-            // Its own model instance — chained to the wearer above — so an enchant streamer is
-            // gone with the avatar in first person and absent until the body is shown (0827/0833).
+            // The item root, chained to the wearer, for its alpha.
             Some(root),
-            // No fade sphere: a carried item is not a placed model — it rides its wearer's
-            // residency, and its streamer the wearer's render alpha one line up.
+            // No fade sphere: a carried item follows its wearer's residency.
             None,
         );
     }
@@ -897,9 +651,7 @@ mod tests {
     use super::super::{HeldSlot, ItemModelKind};
     use super::*;
 
-    /// One synthetic item part. `interior` picks whether it carries an interior material variant —
-    /// the axis that used to decide whether the part got a `MeshTag` at all, and so whether it could
-    /// ever be tinted or ground-shaded.
+    /// One synthetic item part, with or without an interior material variant.
     fn part(interior: bool) -> EntityPart {
         EntityPart {
             mesh: Handle::default(),
@@ -930,8 +682,7 @@ mod tests {
         }
     }
 
-    /// A mesh handle distinguishable from the static form's `Handle::default()` — so "which of the
-    /// two forms did the part actually spawn with" is an assertion rather than a guess.
+    /// A mesh handle distinct from the static form's `Handle::default()`.
     fn skinned_handle() -> Handle<Mesh> {
         Handle::Uuid(
             bevy::asset::uuid::Uuid::from_u128(0x5c1_11ed),
@@ -939,14 +690,8 @@ mod tests {
         )
     }
 
-    /// Spawn a wearer with one SHOULDER slot whose display optionally welds geometry to a billboard
-    /// bone (decision 0841), and run the attach. Returns the part tags, the wearer's own instance
-    /// slot, the item root's palette slot (`None` when it spawned no rig), and the mesh the part
-    /// actually drew with.
-    /// What the shoulder harness reports: the spawned parts' tags, the wearer's own slot, the
-    /// item's slot (the one that is not the wearer's), the mesh it drew, and — the fact that
-    /// separates 1609's rider from 0841's joint rig on the same shape — the [`RigRider`] the item
-    /// root carries, if any.
+    /// What the shoulder harness reports: the parts' tags, the wearer's and the item's palette
+    /// slots, the mesh drawn, the item root's rider and the joint rig count.
     struct Attached {
         tags: Vec<u32>,
         wearer_slot: u16,
@@ -969,9 +714,7 @@ mod tests {
         p.welded_billboard = welded;
         p.skinned_mesh = Some(skinned_handle());
         dm.parts = Some(vec![p]);
-        // The shoulder's own skeleton: a root plus one spherical-billboard spike, the shape
-        // `LShoulder_Plate_PVPAlliance_A_01` authors. Both halves are needed — the gate is
-        // "welded geometry AND a skeleton to pose it with".
+        // A root and one spherical-billboard spike, as `LShoulder_Plate_PVPAlliance_A_01` has.
         dm.skeleton = benilla_assets::ModelSkeleton {
             joints: vec![
                 benilla_assets::ModelJoint {
@@ -1029,7 +772,7 @@ mod tests {
             .iter(app.world())
             .map(|t| t.0)
             .collect();
-        // The item root's rig is the one that is NOT the wearer's (the wearer holds its own).
+        // The item root's slot is the one that is not the wearer's.
         let item_rig = app
             .world_mut()
             .query::<&benilla_world::rig_palette::RigSkin>()
@@ -1063,13 +806,11 @@ mod tests {
         }
     }
 
-    /// The welded case, named for the assertion that reads it.
     fn attach_a_welded_shoulder() -> Attached {
         attach_a_shoulder(true)
     }
 
-    /// Spawn a wearer with one helm slot and run the attach. Returns the spawned parts' tags plus the
-    /// wearer's own instance slot (`0` when `rigged` is false — a boneless wearer).
+    /// Attach one helm; returns the parts' tags and the wearer's slot (0 for a boneless wearer).
     fn attach_a_helm(rigged: bool, interior: bool) -> (Vec<u32>, u16) {
         const HELM_KIND: ItemModelKind = ItemModelKind::Helm { race: 3, sex: 0 };
         let mut app = App::new();
@@ -1126,10 +867,7 @@ mod tests {
         (tags, slot)
     }
 
-    /// **The director's report (dwarf Stoneform tinted the body but not the helm/shoulders).** An
-    /// attachment carries its WEARER's instance slot, so the body tint reaches it — decision 0812's
-    /// named gap, closed. The reference's own rule: an attached model inherits the parent CM2's
-    /// computed colours (`0x714000`).
+    /// An attached model inherits its parent's computed colours (`0x714000`).
     #[test]
     fn an_attachment_wears_its_wearers_instance_slot() {
         for interior in [true, false] {
@@ -1144,9 +882,6 @@ mod tests {
         }
     }
 
-    /// The tag is unconditional now. It used to ride the interior classifier's `Some`, so a part with
-    /// no interior variant carried none at all — invisible to the tint AND to the ground-shade ramp
-    /// that darkens its wielder. Both halves of that are asserted: a tag exists, and it is opaque.
     #[test]
     fn a_part_without_an_interior_variant_still_gets_a_tag() {
         let (tags, _) = attach_a_helm(true, false);
@@ -1155,8 +890,6 @@ mod tests {
         assert!((benilla_world::mesh_tag::alpha_of(tags[0]) - 1.0).abs() < 1.0 / 63.0);
     }
 
-    /// A wearer with no rig at all (a boneless model holding something) lands on the identity slot 0
-    /// rather than borrowing someone else's colour.
     #[test]
     fn a_rigless_wearer_leaves_the_slot_at_identity() {
         let (tags, _) = attach_a_helm(false, true);
@@ -1164,19 +897,7 @@ mod tests {
         assert_eq!(benilla_world::mesh_tag::rig_of(tags[0]), 0);
     }
 
-    /// **The item rig (decision 0841, restored by 0854).** A display whose geometry is welded to a
-    /// billboard bone has no correct rigid placement — 0839 stopped tearing it into a card, leaving
-    /// it whole and still. Such an item spawns a rig of its own, and the three things that makes
-    /// true are asserted together because any one of them alone is a silent no-op: the part draws
-    /// the **skinned** twin (a static mesh is never skinned — `WOW_RIG_SKIN` compiles off the vertex
-    /// layout, not the tag), it carries its OWN palette slot rather than the wearer's, and the root
-    /// really holds the `RigSkin` that slot belongs to.
-    ///
-    /// 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 (`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.
+    /// A display welded to a billboard bone gets its own joint rig (`0x718657`..`0x71876f`).
     #[test]
     fn a_welded_billboard_item_spawns_its_own_rig() {
         let a = attach_a_welded_shoulder();
@@ -1199,25 +920,13 @@ mod tests {
             Some(skinned_handle()),
             "…and draws the skinned twin"
         );
-        // The welded lane keeps its own camera-replaced JOINT rig — it is not a rigid frame, and
-        // that is exactly why 1609's rider cannot serve it (see `rig_rider`'s residuals).
+        // A welded display needs the camera-replaced joint rig; a rigid rider frame cannot bend.
         assert_eq!(a.joints, 1, "the welded item runs a billboard joint rig");
         assert!(a.rider.is_none(), "…and is not a rider");
     }
 
-    /// **The rider (decision 1609).** The counter-anchor, on the same harness: an ordinary item —
-    /// the 9684 models that weld nothing — now takes a palette slot too, but a different KIND of
-    /// one. It is one rigid frame composed in the wearer's rig frame, not a joint rig, and the
-    /// four things that makes true are asserted together because any one alone is a silent no-op:
-    /// the part draws the **skinned** twin (a static mesh is never skinned), it carries its OWN
-    /// slot rather than the wearer's (the vertex stage indexes the palette with that field), the
-    /// root holds a [`RigRider`] naming the wearer and the attach bone, and no joint rig was built.
-    ///
-    /// Until 1609 this test asserted the opposite — no slot, the wearer's tag, the static mesh —
-    /// because the ordinary lane placed an item through its entity's absolute `GlobalTransform`.
-    /// At Elwynn's ~9481 yards that sum lands on an 0.98 mm f32 grid and is rebuilt every frame,
-    /// so a standing guard's helm hopped a whole grid step every other frame while the body under
-    /// it moved exactly. The static-mesh route is what this test now forbids coming back.
+    /// An ordinary item rides one rigid frame in the wearer's rig, never an absolute f32 world
+    /// matrix, which at ~9500 yd falls on a 0.98 mm grid.
     #[test]
     fn an_ordinary_item_rides_one_rigid_frame_in_its_wearers_rig() {
         let a = attach_a_shoulder(false);
@@ -1240,19 +949,7 @@ mod tests {
         assert_eq!(a.joints, 0, "a rigid item builds no joint rig");
     }
 
-    /// **The ranged prop gets a clock, and only the ranged prop** (decision 2281).
-    ///
-    /// Four things have to be true together or the gun's muzzle blast never fires, and each one
-    /// alone is a silent no-op: the prop root carries a [`crate::ranged_flex::RangedProp`] naming
-    /// its wearer (that is how a `$BWR` key finds it), a [`benilla_world::rig_anim::RigPose`] and a
-    /// player (so 161 can be armed and posed at all), its emitter is **hosted on that root** rather
-    /// than pinned to the loader idle (the blast's gate track is keyed only in 161 — a pinned
-    /// emitter reads Stand's flat zero for ever), and the emitter rides its BONE's anchor rather
-    /// than the model root (bone 2 is what aims it down the barrel).
-    ///
-    /// The control is the same display in the MAINHAND slot: nothing is ever passed to the
-    /// reference's `[+0xd24]` arms but the ranged weapon, so a melee item keeps the resting lane —
-    /// no player, no pose, a pinned clock.
+    /// Only the ranged prop (`[+0xd24]`) gets a pose, a player and emitters on its bone and clock.
     #[test]
     fn a_flexing_ranged_prop_gets_a_pose_a_clock_and_hosted_emitters() {
         fn attach(slot_idx: usize, attach: u16) -> (App, Option<Entity>) {
@@ -1275,7 +972,7 @@ mod tests {
                         billboard: None,
                         parent_arm: None,
                     },
-                    // The muzzle bone the emitters hang off.
+                    // The muzzle bone the emitter hangs off.
                     benilla_assets::ModelJoint {
                         parent: 0,
                         local_translation: Vec3::X,
@@ -1293,7 +990,7 @@ mod tests {
                 clips: Vec::new(),
                 hand_close: [None, None],
                 playable_animation_lookup: Vec::new(),
-                // `owns(161)` — the gate, the reference's own `0x711960` question.
+                // `owns(161)`, the reference's `0x711960` test.
                 animation_lookup: {
                     let mut v = vec![0xffffu16; 162];
                     v[0] = 0;
@@ -1342,7 +1039,6 @@ mod tests {
             (app, Some(wearer))
         }
 
-        // The ranged slot (2), drawn in the right hand.
         let (mut app, wearer) = attach(2, attach_id::HAND_RIGHT);
         let wearer = wearer.unwrap();
         let (prop, owner) = app
@@ -1372,7 +1068,6 @@ mod tests {
             vec![Some(prop)],
             "its emitter reads the sequence the PROP is playing"
         );
-        // The emitter's owner frame is the muzzle bone's anchor, not the model root.
         let anchors: Vec<(Entity, u16)> = app
             .world_mut()
             .query::<&benilla_world::rig_anim::RigAnchor>()
@@ -1384,7 +1079,7 @@ mod tests {
             "the emitter minted the muzzle bone's anchor: {anchors:?}"
         );
 
-        // The control: the SAME display in the mainhand keeps the resting lane.
+        // The same display in the mainhand keeps the resting lane.
         let (mut app, _) = attach(0, attach_id::HAND_RIGHT);
         assert_eq!(
             app.world_mut()
@@ -1407,16 +1102,8 @@ mod tests {
         );
     }
 
-    /// **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
-    /// from every pane. The attach must therefore publish a mirror for both, at the seat the booth
-    /// needs: the attach point **plus the batch's own model-local pivot** for a card (an item spawns no
-    /// rig, so nothing else bakes that pivot), the bare attach point for the effect host.
-    ///
-    /// Both offsets are asserted against a nonzero attach point AND a nonzero pivot, so publishing
-    /// either one alone — or adding them in the wrong frame — fails.
+    /// A card's booth mirror seats at the attach point plus its pivot, the emitters' at the attach
+    /// point; both nonzero, so either term missing fails.
     #[test]
     fn an_equipped_items_card_and_emitters_are_published_for_the_booths() {
         const SHOULDER_KIND: ItemModelKind = ItemModelKind::ShoulderRight;
@@ -1429,7 +1116,7 @@ mod tests {
             benilla_formats::ItemDisplayCatalog::from_displays(HashMap::new()),
         );
         let mut dm = empty_display();
-        // The R14 pauldron's shape: a plain mesh batch, a camera-facing batch, and emitters.
+        // An R14 pauldron's shape: a plain mesh batch, a camera-facing batch, and emitters.
         let mut card = part(false);
         card.billboard = Some(benilla_assets::BillboardInfo {
             pivot: PIVOT,
@@ -1504,15 +1191,7 @@ mod tests {
         );
     }
 
-    /// **The director's report on the Hungering Cold** (decision 0836): a weapon's glowing gems
-    /// were already blazing at full strength before the character carrying them had faded in.
-    /// The sword authors five camera-facing `GENERICGLOW1` batches, and a card used to spawn with
-    /// neither `RenderFade` nor `FadeMaterials` — a batch that pops. It is a batch of the item's
-    /// model like any other, so it joins the wearer's ramp with the mesh parts.
-    ///
-    /// The same spawn also pins the batch's **authored** alpha: the sword's cards are keyed
-    /// `weight 0.30` and every item batch drew at 1.0, because no attach-model part ever carried a
-    /// `MatAnim` at all (321 of the 2681 shipped item models dim a batch this way).
+    /// A card joins the wearer's pending fade and keeps its authored 0.30 weight.
     #[test]
     fn an_items_card_joins_the_wearers_fade_and_keeps_its_authored_alpha() {
         const KIND: ItemModelKind = ItemModelKind::Weapon;
@@ -1563,8 +1242,7 @@ mod tests {
             attach: attach_id::HAND_RIGHT,
             visual: NO_GLOW,
         });
-        // The wearer is mid-login: its own ramp is still pending, so everything attaching to it
-        // must join that ramp rather than open opaque beside it.
+        // The wearer's own fade is still pending.
         let wearer = app
             .world_mut()
             .spawn((
@@ -1616,14 +1294,8 @@ mod tests {
         );
     }
 
-    /// **The director's login report on the Naxx items** (decision 0865): a MULTIPLY sheen batch
-    /// (Mod2x — the ARMORREFLECT family) used to spawn Steady, popping as a full-strength ×2 layer
-    /// over a body still fading in. Its blend equation reads no alpha, so no material swap can
-    /// feather it (0528) — instead the part arms the ramp on its STEADY material (the "twin" is
-    /// itself) and the shader lerps its colour toward the blend identity by the tag alpha, which
-    /// is the reference's own preset-5 fade (1489; 0865 built it believing it a deviation).
-    /// Headless, this asserts the arm half: joined ramp, tag alpha ≈ 0, no material swap, and a
-    /// FadeMaterials record so despawn/stealth ramps re-arm it too.
+    /// A Mod2x sheen reads no alpha, so it fades on its steady material while the shader lerps its
+    /// colour toward the blend identity by the tag alpha, the reference's preset-5 fade.
     #[test]
     fn a_multiply_sheen_joins_the_wearers_ramp_on_its_steady_material() {
         const KIND: ItemModelKind = ItemModelKind::Weapon;
@@ -1642,7 +1314,7 @@ mod tests {
         let mut sheen = part(false);
         sheen.blend = benilla_formats::ModelBlend::Mod2x;
         sheen.material = steady.clone();
-        // What `entities::display` now builds for a multiply batch: the steady self as the twin.
+        // As `entities::display` builds a multiply batch: the steady self as the twin.
         sheen.fade_blend = Some(steady.clone());
         dm.parts = Some(vec![sheen]);
         displays.models.insert((7, KIND), dm);
@@ -1699,8 +1371,7 @@ mod tests {
         );
     }
 
-    /// A wearer holding a **weapon** (mainhand, drawn in the hand) and wearing a **shoulder** that
-    /// carries emitters — the bench for the sheath-swap tests below. Returns the app and the wearer.
+    /// A wearer with a drawn mainhand weapon and a shoulder that carries emitters.
     fn dress_a_wearer() -> (App, Entity) {
         let mut app = App::new();
         app.add_plugins(MinimalPlugins);
@@ -1715,8 +1386,7 @@ mod tests {
         ] {
             let mut dm = empty_display();
             let mut p = part(false);
-            // A real item model has a skeleton and a skinned twin, so it takes a rider slot
-            // (1609) — which is what makes the sheath swap's rider re-seat below observable.
+            // A skeleton and a skinned twin, so the item takes a rider slot.
             p.skinned_mesh = Some(skinned_handle());
             dm.parts = Some(vec![p]);
             dm.skeleton = benilla_assets::ModelSkeleton {
@@ -1746,8 +1416,7 @@ mod tests {
         }
         app.insert_resource(displays);
 
-        // Three attach points on three bones: the hand, the back (where a stowed weapon rides)
-        // and the shoulder — their joints spawn on first demand (decision 1355).
+        // The hand, a back sheath point and the shoulder, on three bones.
         let bones = BoneAttach {
             points: HashMap::from([
                 (attach_id::HAND_RIGHT, (1u16, HAND_AT)),
@@ -1783,10 +1452,9 @@ mod tests {
     const HAND_AT: Vec3 = Vec3::new(0.1, 1.0, 0.0);
     const BACK_AT: Vec3 = Vec3::new(-0.2, 1.3, -0.15);
     const SHOULDER_AT: Vec3 = Vec3::new(0.21, 1.42, 0.06);
-    /// A back sheath point (`attach_id`'s `BACK_SHEATH` family — any id the body publishes).
+    /// Stands in for a back sheath point: any id the body publishes will do.
     const SHEATH_BACK: u16 = 6;
 
-    /// The roots this wearer currently has attached, per slot.
     fn roots_of(app: &App, wearer: Entity) -> [Option<Entity>; ATTACH_SLOTS] {
         app.world()
             .entity(wearer)
@@ -1795,22 +1463,14 @@ mod tests {
             .spawned
     }
 
-    /// **The director's report, at its cause** (decision 0826): drawing/stowing a weapon changed one
-    /// slot's attach point, and the old code rebuilt the unit's WHOLE kit — so the shoulders' and
-    /// helm's emitters were orphaned mid-swing and their live particles hung in world space while
-    /// the character walked on ("armor and weapon particles … lag behind when doing a weapon draw").
-    ///
-    /// Three things are asserted, and each one alone would reproduce the bug if it regressed: the
-    /// untouched slot keeps its root entity (so its pool is never orphaned), the moved slot keeps
-    /// ITS root (so the weapon's own effects ride the swap, as the reference's re-parent does), and
-    /// the moved root really is re-seated — new parent joint, new local offset.
+    /// A sheath swap re-parents the weapon's root, and no other slot's root is rebuilt.
     #[test]
     fn a_sheath_swap_moves_the_weapon_and_leaves_the_other_slots_alone() {
         let (mut app, wearer) = dress_a_wearer();
         let before = roots_of(&app, wearer);
         let (weapon, shoulder_root) = (before[0].expect("weapon"), before[4].expect("shoulder"));
 
-        // Stow it: the same item, a new attach point — nothing else about the kit changes.
+        // Stow it: the same item at a new attach point.
         let mut items = app.world_mut().entity_mut(wearer);
         let mut items = items.get_mut::<HeldItems>().unwrap();
         items.slots[0].as_mut().unwrap().attach = SHEATH_BACK;
@@ -1855,7 +1515,6 @@ mod tests {
             BACK_AT,
             "…at the new attach point's offset"
         );
-        // The booth mirrors move with it — a paper doll must show the stowed weapon on the back.
         let seat = app
             .world_mut()
             .query::<&crate::portrait::PortraitRider>()
@@ -1863,11 +1522,7 @@ mod tests {
             .find(|r| r.offset.distance(BACK_AT) < 1e-5)
             .map(|r| r.bone);
         assert_eq!(seat, Some(2), "the rider's cached seat followed the move");
-        // **And the palette rider followed it too** (decision 1609). The MOVE is the one edit that
-        // keeps the item's entity alive while changing the bone its frame is composed from, so the
-        // rider is the one thing a re-parent can silently leave behind: the sword would go on
-        // drawing at the hand it was stowed from while its entity, its glow and its emitters all
-        // travelled to the back.
+        // The palette rider follows too, or the sword would draw at the hand it left.
         let rider = app
             .world()
             .entity(weapon)
@@ -1878,9 +1533,6 @@ mod tests {
         assert_eq!(rider.host, wearer);
     }
 
-    /// The other half of the per-slot diff: a slot whose item genuinely CHANGED is rebuilt (its old
-    /// model is destroyed — the reference's dtor, which takes that model's emitters with it), and
-    /// still nobody else's slot is touched.
     #[test]
     fn a_real_item_change_rebuilds_only_its_own_slot() {
         let (mut app, wearer) = dress_a_wearer();
@@ -1904,14 +1556,6 @@ mod tests {
         assert_eq!(after[4], Some(shoulder_root), "the shoulders are untouched");
     }
 
-    /// The chain's first link, on the real spawn path (decision 0833): an item model is CHAINED to
-    /// the body wearing it, and the emitters it spawns point at **their own** root rather than at
-    /// the wearer. Both halves matter — the item's own sparkle would fade correctly either way,
-    /// but a glow instance hung on this root two links down can only reach the wearer through it,
-    /// and that is the link the enchant-glow lane never had.
-    ///
-    /// It survives the sheath MOVE for the same reason the pool does: the root is re-parented, not
-    /// rebuilt.
     #[test]
     fn an_item_model_is_chained_to_its_wearer() {
         use benilla_world::model_fade::ParentModel;
diff --git a/crates/benilla-app/src/entities/item_glow.rs b/crates/benilla-app/src/entities/item_glow.rs
index 93719fd8..f85c4fd0 100644
--- a/crates/benilla-app/src/entities/item_glow.rs
+++ b/crates/benilla-app/src/entities/item_glow.rs
@@ -1,49 +1,13 @@
-//! **Item / enchant glow effects** (decision 0805): the permanent weapon glow a display authors,
-//! and the enchant glow a weapon's enchant carries — `Spells\Enchantments\*.mdx` effect models
-//! hung on the ITEM's own model, not on the wearer's body.
+//! Item glows: the permanent glow an item display authors and the glow a weapon enchant carries,
+//! `Spells\Enchantments` models hung on the item's own model, not the wearer's body.
 //!
-//! ## The chain, and where each half is verified
-//!
-//! `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 (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
-//!   `0x479700` iff the id is **`> 0`** (`jle` skip). The same primitive attaches the helm (id
-//!   11), the shoulders (5/6) and the quiver (26) — and **every one of those call sites pushes a
-//!   literal `0`**, so on a character body only the WEAPON/SHIELD hand attach can glow. The
-//!   ranged-ammo lane (`0x479f40`) passes `[ebx+0x58]` at its tail, so a thrown/ammo model glows
-//!   from its own display too.
-//! - **Enchant** — `0x5eed50` per weapon slot → `0x62ec70(item)`: if the base display's
-//!   ItemVisuals row **exists**, it returns `-1` and the enchant glow is suppressed (the base
-//!   already draws one); otherwise the first of the item's 7 enchant slots whose
-//!   `SpellItemEnchantment` row carries a nonzero visual wins. [`effective_visual`] is that fork.
-//!
-//! ## Where the glow hangs
-//!
-//! `0x479700` walks the 5 effect columns and calls `0x712f70(glow, itemModel, attachId = the
-//! column index)` — so **slot i is M2 attachment id i on the item's own model**, and a row that
-//! repeats one effect across all five slots (BlueGlow_Med ×5, the common shape) reads as a glow
-//! along the whole blade.
-//!
-//! **How many of the five actually land is the model's business, and it varies**: of the 160
-//! distinct weapon models the 360 glowing displays resolve to, 61 author the full ids 0..4 and 44
-//! author only 2/3/4 (Ironfoe's hammer is one — three of its five copies draw). An id the model
-//! doesn't author hangs nothing at all, byte-verified: `0x712f70` stores `0x710310`'s `0xffff`
-//! miss and every consumer of that field (`0x7140aa`, `0x718668`, `0x719266`) tests
-//! `cmp 0xffff; je` and skips the child — there is no fallback to the model origin. Which record
-//! an id resolves to is the model's **AttachLookup**, never a scan of its table
-//! (`benilla_m2::M2Model::attachment`): ~5% of weapon models author two records under one id.
-//!
-//! An item model poses at rest (no rig is spawned for it — `super::equipment`), so the attach
-//! point is its bind-pose position ([`crate::portrait::attachment_point`]) and the glow instance
-//! is a plain child of the item root: it rides the hand/hip/back bone with the weapon, and dies
-//! with it on a gear or sheath change. Everything past that — the effect model's own rig,
-//! emitters, ribbons, material animation — is the shared effect body
-//! ([`super::spell_fx::attach_effect_visuals`]); these models are almost all pure particle
-//! emitters (BlueGlow_Med: zero render batches, one Plane/Add emitter on `Flare.blp`).
+//! The chain is `ItemDisplayInfo` column 22, then `ItemVisuals`, then five `ItemVisualEffects`
+//! models ([`benilla_formats::ItemVisualCatalog`]). The held-item attach passes the display's own
+//! id (`0x47a200` into `0x4798c0`, attaching at `0x479700` when it is above 0); the helm, shoulder
+//! and quiver sites pass a literal 0, so on a body only hand items glow, and the ammo lane
+//! (`0x479f40`) passes its own. `0x479700` hangs effect i on the item model's attachment id i
+//! (`0x712f70`). An item model rests at bind pose, so each glow is a plain child of the item root:
+//! it goes with a gear change and moves with a sheath swap.
 
 use std::collections::HashMap;
 
@@ -57,15 +21,8 @@ use super::equipment::{ItemDisplays, ItemModelKind};
 use super::spell_fx::{attach_effect_visuals, EffectHost, FxMaterials, FxTintAnims};
 use super::{DisplayModel, ModelHandle};
 
-/// The glow chain's data + the effect-model cache: the joined `ItemVisuals`/`ItemVisualEffects`
-/// catalog, plus a path-keyed [`DisplayModel`] per glow model (the [`super::spell_fx::SpellFx`]
-/// pattern — entries are created by [`ensure_glow_models`] at equipment-resolve time and built by
-/// `super::update_display_models` the same frame). Optional resource: without the DBC nothing
-/// glows, exactly as before this lane existed.
-///
-/// The enchant half of the fork lives in [`crate::items::Enchants`] — the same
-/// `SpellItemEnchantment` load the tooltip's enchant line reads (decision 0915). Without it a
-/// weapon still shows its INTRINSIC glow; only the enchant leg goes quiet.
+/// The joined `ItemVisuals`/`ItemVisualEffects` catalog and a path-keyed [`DisplayModel`] per glow
+/// model. Without it nothing glows; without [`crate::items::Enchants`] only enchant glows go quiet.
 #[derive(Resource)]
 pub(crate) struct ItemGlows {
     pub(super) visuals: ItemVisualCatalog,
@@ -80,19 +37,15 @@ impl ItemGlows {
         }
     }
 
-    /// The glow models an ItemVisuals id resolves to, by attach slot — `None` when the id names
-    /// no row (0, the shipped `-1`s, out of range).
+    /// The glow models by attach slot; `None` when the id names no row (0, the shipped `-1`s).
     pub(super) fn effects(&self, visual: i32) -> Option<&[Option<String>; ITEM_VISUAL_SLOTS]> {
         self.visuals.effects(visual)
     }
 }
 
-/// The ItemVisuals id an item actually glows with — the reference's base-or-enchant fork
-/// (`0x62ec70`): the **base** display's id wins whenever it names a real ItemVisuals row (the
-/// client returns `-1` from the enchant resolver precisely so the two can't double up); otherwise
-/// the **first** enchant slot whose `SpellItemEnchantment` row carries a nonzero visual. `0` when
-/// neither does.
-/// `enchants` absent (the DBC failed to load) means only the base leg can answer.
+/// The ItemVisuals id an item glows with, the fork of `0x62ec70` (per weapon slot, `0x5eed50`):
+/// the base display's id when it names a row, which suppresses the enchant's, else the first
+/// enchant slot with a nonzero visual, else 0.
 pub(in crate::entities) fn effective_visual(
     glows: &ItemGlows,
     enchants: Option<&EnchantCatalog>,
@@ -111,9 +64,8 @@ pub(in crate::entities) fn effective_visual(
     0
 }
 
-/// Create the [`DisplayModel`] cache entries for a visual's glow models, so
-/// `super::update_display_models` builds them the same frame the equipment resolve asked for
-/// them (the held-item pattern).
+/// Create a visual's glow-model cache entries, so `super::update_display_models` builds them the
+/// frame the equipment resolve asks.
 pub(in crate::entities) fn ensure_glow_models(
     glows: &mut ItemGlows,
     visual: i32,
@@ -141,41 +93,29 @@ pub(in crate::entities) fn ensure_glow_models(
     }
 }
 
-/// A spawned held-item root that should carry a glow: the item's display-model key (for its
-/// attachment table) and the resolved ItemVisuals id. Written by `super::equipment`'s attach;
-/// consumed once by [`attach_item_glows`], which then marks it [`ItemGlowAttached`].
+/// A held-item root that should carry a glow, written by `super::equipment`'s attach and consumed
+/// once by [`attach_item_glows`].
 #[derive(Component)]
 pub(in crate::entities) struct ItemGlow {
     pub(in crate::entities) display: u32,
     pub(in crate::entities) kind: ItemModelKind,
     pub(in crate::entities) visual: i32,
-    /// The ITEM's seat on the wearer's body — the attach point's bone and offset
-    /// ([`super::BoneAttach`]). Carried purely so this lane can publish the booth mirrors of what it
-    /// spawns (decision 0822): a glow's seat is this offset plus the slot's point on the item model,
-    /// and by the time the glow models load the attach path that knew the body bone is long gone.
+    /// The item's seat on the body ([`super::BoneAttach`]), kept to place the portrait mirrors:
+    /// the attach path that knew it is gone by the time the glow models load.
     pub(in crate::entities) bone: u16,
     pub(in crate::entities) offset: bevy::prelude::Vec3,
-    /// The ITEM's **M2 attachment id** on the body, for the same reason: a glow is chained under
-    /// the item (`0x712f70`), so a widget's attach reset takes the glow exactly when it takes the
-    /// item it hangs on ([`crate::portrait::attach_reset`]).
+    /// The item's M2 attachment id on the body: a glow chains under its item (`0x712f70`), so a
+    /// widget's attach reset takes both together.
     pub(in crate::entities) attach: u16,
 }
 
-/// Set once an item root's glow instances are spawned (or resolved to nothing) — the once-only
-/// gate. The instances are children of the root, so they need no lifetime bookkeeping of their
-/// own: a gear change or the unit despawning takes the root and them with it. A **sheath swap**
-/// keeps them: it moves the root to the new attach point (decision 0826), so a glowing weapon
-/// keeps its glow — and its live particles — across the draw.
+/// The item's glow instances are spawned, or there were none. As children of the root they go
+/// with a gear change and move, live particles and all, with a sheath swap.
 #[derive(Component)]
 pub(crate) struct ItemGlowAttached;
 
-/// Spawn each pending item root's glow instances: one effect-model instance per authored slot, at
-/// that slot's attachment point on the item's own model.
-///
-/// All-or-nothing per item — while any of the item's glow models is still loading the whole set
-/// waits, so a two-model visual can't spawn half of itself and then re-enter here. A model that
-/// never loads simply never glows (the item is still perfectly drawn); the retry is a handful of
-/// roots per frame.
+/// Spawn each pending item's glow instances, one per authored slot at that slot's attachment point
+/// on the item model; all or nothing, so the set waits while any of its models loads.
 pub(super) fn attach_item_glows(
     mut commands: Commands,
     pending: Query<(Entity, &ItemGlow), Without<ItemGlowAttached>>,
@@ -188,9 +128,7 @@ pub(super) fn attach_item_glows(
     mut anim_table: ResMut<benilla_world::mat_anim_table::MatAnimTable>,
     ibps: Res<Assets<bevy::mesh::skinning::SkinnedMeshInverseBindposes>>,
     mut palettes: ResMut<benilla_world::rig_palette::RigPalettes>,
-    // One breadcrumb per session the first time a glow actually spawns — the machine-readable
-    // "this lane is live" signal for a subsystem whose whole symptom is *absence* (the same
-    // idiom `apply_unit_mat_alpha` uses for its cull).
+    // The session's first spawned glow is logged once at info level.
     mut logged: Local<bool>,
 ) {
     let (Some(glows), Some(items)) = (glows, items) else {
@@ -203,10 +141,9 @@ pub(super) fn attach_item_glows(
             continue;
         };
         let Some(item) = items.models.get(&(glow.display, glow.kind)) else {
-            continue; // the item's own display entry is gone (a cache evict) — retry
+            continue; // the item's display entry was evicted: retry
         };
-        // Ready = every authored slot's model has built its parts. Emitter-only models build an
-        // EMPTY part list, which is `Some` — the readiness test is the option, not the length.
+        // Ready: every model has built its parts; an emitter-only model's empty list is `Some`.
         let ready = paths
             .iter()
             .flatten()
@@ -223,13 +160,9 @@ pub(super) fn attach_item_glows(
             let Some(dm) = glows.models.get(path) else {
                 continue;
             };
-            // Slot index == M2 attachment id on the ITEM model (module doc). **A model missing
-            // that point hangs nothing there**, and that is the reference's behaviour, not a
-            // shortcut: `0x712f70` stores the attach-lookup miss as `0xffff`
-            // (`0x710310`'s bounds return), and every consumer of that field —
-            // `0x7140aa`/`0x718668`/`0x719266` — tests `cmp 0xffff; je` and skips the child
-            // outright. It is a common case, not a corner: Ironfoe's hammer authors only ids
-            // 2/3/4, so three of its visual's five copies draw and two do not.
+            // A model without this slot's attachment hangs nothing there, as in the reference:
+            // `0x712f70` stores `0x710310`'s miss as `0xffff`, whose child `0x7140aa`, `0x718668`
+            // and `0x719266` skip. Common: Ironfoe's hammer authors only ids 2 to 4.
             let Some(at) =
                 crate::portrait::attachment_point(&item.skeleton, &item.attachments, slot as u16)
             else {
@@ -243,14 +176,9 @@ pub(super) fn attach_item_glows(
                 .spawn((Transform::from_translation(at), Visibility::default()))
                 .id();
             commands.entity(root).add_child(instance);
-            // The booth mirrors for this instance (decision 0822), at its seat on the BODY: the item's
-            // attach point plus this slot's point on the item model. `attach_effect_visuals` below
-            // spawns the effect's real geometry and emitters — the meshes as instance children, the
-            // emitters as free owner-followed entities — and the shared spell-fx lane is deliberately
-            // not the place to stamp portrait markers (a *spell's* fx must never reach a booth), so
-            // this lane publishes its own from the same `dm`. Without them a permanently-glowing
-            // weapon glowed nothing in the character window: 32 of the 35 shipped glow models are pure
-            // emitters, and `Sparkle_A.m2` is a lone camera-facing quad.
+            // The portrait mirrors, at the item's seat plus this slot's point. The shared spell-fx
+            // lane stamps none, as a spell's effect must never reach a portrait, so the glow's
+            // come from here; 32 of the 35 shipped glow models are pure emitters.
             let seat = glow.offset + at;
             for p in dm.parts.iter().flatten() {
                 match &p.billboard {
@@ -299,13 +227,10 @@ pub(super) fn attach_item_glows(
                 dm,
                 now,
                 false, // a weapon glow is never ground-anchored
-                // An attached model in the client's sense — it rides the ITEM (`0x712f70`), so it
-                // is chained to that item root and through it to the wearer: the glow fades in
-                // with the body instead of blazing over a character that has not appeared yet,
-                // and it dies with the weapon instead of hanging in the air behind it (0833).
+                // Chained to the item root (`0x712f70`) and through it to the wearer, so it fades
+                // in with the body and dies with the weapon.
                 EffectHost { parent: Some(root) },
-                // An `ItemVisuals` glow is armed by a different leg than `PlaySpellVisualKit`
-                // (0805) and carries no kit stage — the plain single-clip arm, as before.
+                // Not armed by `PlaySpellVisualKit`: no kit stage, the plain single-clip arm.
                 None,
                 &mut FxMaterials {
                     store: &mut wow_materials,
@@ -315,14 +240,12 @@ pub(super) fn attach_item_glows(
                 },
                 &ibps,
                 &mut palettes,
-                None, // the glow models author one looping sequence — the default pick
+                None, // the glow models author one looping sequence
             );
             spawned += 1;
         }
         commands.entity(root).insert(ItemGlowAttached);
-        // Counted from what actually spawned, never from what the row *authors* — the two differ
-        // whenever the item model lacks a point (above), and a count of authored paths reads as a
-        // glow that isn't there.
+        // What spawned, not what the row authors: they differ where the model lacks a point.
         let authored = paths.iter().flatten().count();
         if !*logged && spawned > 0 {
             *logged = true;
@@ -365,28 +288,20 @@ mod tests {
         )
     }
 
-    /// The base-or-enchant fork (`0x62ec70`): an intrinsic visual wins and **suppresses** the
-    /// enchant's, an item without one takes the first enchant slot that carries a visual, and
-    /// enchant slots with no visual are walked past rather than ending the scan.
     #[test]
     fn base_visual_wins_over_enchant_and_suppresses_it() {
         let (glows, ench) = catalog(&[25, 61], &[(1, 61), (7, 25)]);
         let ench = Some(&ench);
-        // Base 25 exists → base, even with an enchant that also carries one.
         assert_eq!(effective_visual(&glows, ench, 25, [1]), 25);
-        // No base → the enchant's.
         assert_eq!(effective_visual(&glows, ench, 0, [1]), 61);
-        // A visual-less enchant in the way: the scan continues to the one that has it.
+        // An enchant without a visual is walked past, not the end of the scan.
         assert_eq!(effective_visual(&glows, ench, 0, [999, 7]), 25);
-        // Nothing anywhere.
         assert_eq!(effective_visual(&glows, ench, 0, [999]), 0);
         // The shipped `-1` base is not a row: it neither glows nor suppresses the enchant.
         assert_eq!(effective_visual(&glows, ench, -1, [1]), 61);
         assert_eq!(effective_visual(&glows, ench, -1, []), 0);
     }
 
-    /// No enchant catalog (the DBC failed to load): the INTRINSIC leg still answers in full, and
-    /// only the enchant leg goes quiet — the split's whole safety claim.
     #[test]
     fn without_the_enchant_catalog_only_the_base_leg_answers() {
         let (glows, _) = catalog(&[25, 61], &[(1, 61)]);
diff --git a/crates/benilla-app/src/entities/live_display.rs b/crates/benilla-app/src/entities/live_display.rs
index 848410a0..8a1deedc 100644
--- a/crates/benilla-app/src/entities/live_display.rs
+++ b/crates/benilla-app/src/entities/live_display.rs
@@ -1,31 +1,14 @@
-//! Live descriptor **appearance** changes (decision 0695): a `Values` delta that moves
-//! `UNIT_FIELD_DISPLAYID` / `GAMEOBJECT_DISPLAYID` swaps the entity's model in place, and one that
-//! moves `OBJECT_FIELD_SCALE_X` eases its render scale — the druid-shapeshift / GM-morph gap
-//! (ledger B69/F04) and `NetEntity::scale`'s old standing deferral, closed together because they
-//! are one family: the create path interpreted both fields once and nothing ever re-read them.
+//! Live appearance changes: a values delta that moves `UNIT_FIELD_DISPLAYID` or
+//! `GAMEOBJECT_DISPLAYID` swaps the entity's model in place, and one that moves
+//! `OBJECT_FIELD_SCALE_X` eases its render scale.
 //!
-//! The reference watches both fields through its field-change registry. The DISPLAYID handler
-//! reaches the model rebuild (`0x60abe0`), self-gated by "the display record actually changed"
-//! (`0x60ae10` against the per-unit display cache `[unit+0xb34]`), re-resolves every model fact
-//! 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** (`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
-//! rebuild — fade-skipped (a shapeshift isn't a spawn), waiting out the new model's async load
-//! rather than flashing a cube. The collision height restamps **in the same commit** as the swap —
-//! the 0645 rule that the collision box and the drawn body can never disagree is exactly why
-//! neither restamped alone before this.
-//!
-//! A **teardown is right here and only here**: a display swap is a different model, so there is
-//! nothing to keep. The two siblings that used to share this shape no longer do — a gear change
-//! re-dresses in place (0835) and a mount transition re-seats in place (B199), because in the
-//! reference neither touches the body model at all. What survives a teardown is the unit's own
-//! per-unit state, and one piece of it is load-bearing: its [`super::spell_fx::FxAttached`] list
-//! outlives the model exactly as the reference's `+0xb4` does, so its persistent instances
-//! re-spawn onto the new body rather than being lost with the old one.
+//! The reference's display handler rebuilds the model (`0x60abe0`) when the display record changed
+//! (`0x60ae10`, against `[unit+0xb34]`), re-resolving its model facts (`0x60afb0`) and the stand or
+//! ride animation (`0x60ce70`): an instant swap, a ghost's revive too. Its scale handler eases
+//! over 2 s with a cosine smoothstep (`0x614bbf`). Here a swap tears the visual down for
+//! `attach_entity_visuals` to rebuild without the spawn fade; the unit's
+//! [`super::spell_fx::FxAttached`] list outlives it, as the reference's per-unit `+0xb4` effect
+//! list does, so persistent effects re-spawn on the new body.
 
 use benilla_protocol::EntityKind;
 use bevy::prelude::*;
@@ -38,25 +21,20 @@ use super::{Creatures, VisualAttached};
 /// The reference's scale-ease window: 2 s, cosine smoothstep (`0x614bbf`).
 const SCALE_EASE_SECS: f32 = 2.0;
 
-/// On the entity: the display id its current visual was BUILT with — [`refresh_live_display`]'s
-/// diff key (the `AppliedEquipment` pattern). Stamped by the attach path on every (re)build,
-/// cube fallback included (same read, no churn for a model-less unit); torn down with the visual.
+/// The display id the visual was built with, cube included: [`refresh_live_display`]'s diff key.
 #[derive(Component)]
 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
-/// (`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`).
+/// A live display swap tore this entity's visual down. The reference's rebuild ends by replaying
+/// the pending morph's impact kit (`0x60ad67`), which `crate::creature_anim`'s morph-latch watcher
+/// does on this edge.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct DisplaySwapped {
     pub(crate) entity: Entity,
 }
 
-/// A live render-scale ease toward [`NetEntity::scale`]: the reference's 2 s cosine smoothstep
-/// (`0x614bbf`), ticked by [`tick_scale_ease`] as absolute writes (a mid-ease visual rebuild's
-/// snap is simply overwritten next frame, so the ease survives it).
+/// A render-scale ease toward [`NetEntity::scale`], written absolutely each tick so a mid-ease
+/// rebuild's snap is overwritten.
 #[derive(Component)]
 pub(super) struct ScaleEase {
     from: f32,
@@ -64,10 +42,8 @@ pub(super) struct ScaleEase {
     elapsed: f32,
 }
 
-/// The live descriptor's display id for this entity kind — the values-delta twin of the protocol's
-/// create-time interpretation (`events/decode.rs` `display_id`): per-kind field, `0`/absent → `None`
-/// (a real morph never zeroes it; the create block's absent-is-zero fold means `0` also reads
-/// "never sent", so neither tears a visual down to a cube).
+/// The live display id, read per kind as `benilla_protocol` reads it at create: `0` is absent, so
+/// it never tears a visual down to a cube.
 fn live_display_id(kind: EntityKind, store: &ObjectStore) -> Option<u32> {
     match kind {
         EntityKind::Unit | EntityKind::Player => store
@@ -80,29 +56,18 @@ fn live_display_id(kind: EntityKind, store: &ObjectStore) -> Option<u32> {
             .gameobject_displayid()
             .filter(|&d| d > 0)
             .map(|d| d as u32),
-        // A corpse's body display (decision 1706). It is not expected to move — the field is a
-        // death-time snapshot — but it is the same field the create interpreted, so the same
-        // differ answers for it. **Not** covered here: the flesh→bones flip, which the reference
-        // reacts to with a full model reload (its `CORPSE_FIELD_FLAGS` mirror handler
-        // `0x5d5fa0`→`0x5d6d60`). vmangos cannot produce it — the conversion destroys the corpse
-        // object and creates a *separate* bones object under a new guid (`Map.cpp:3625`,
-        // `RemoveCorpses`) — so the reload path is deliberately unbuilt rather than speculatively
-        // modelled; see decision 1706's named omissions.
+        // A death-time snapshot. The in-place flesh-to-bones flip, which the reference reloads on
+        // (`CORPSE_FIELD_FLAGS` handler `0x5d5fa0`, `0x5d6d60`), is not built: vmangos removes the
+        // corpse and adds a separate bones object under the same guid (`Map.cpp:3608-3649`).
         EntityKind::Corpse => store.0.corpse_display_id(),
         _ => None,
     }
 }
 
-/// Diff each attached entity's live descriptor appearance against what its visual was built with,
-/// and apply the change: a **display-id** move swaps the model (teardown → rebuild — the one
-/// transition that still earns one) and a **scale** move arms the 2 s ease — both restamp
-/// [`CollisionHeight`] in the same commit (its two inputs are exactly these two fields; decision
-/// 0645's stamp-once rule was correct only while neither could change).
-///
-/// The self-avatar needs nothing special: it is the streamed entity (decision 0042), so the swap
-/// rebuilds its body like any other unit and `player::mirror_self_collision_height` re-syncs the
-/// swim lines from the restamp next frame. Mount children carry no [`ObjectStore`], so they can
-/// never take this path (their display is the host's field, diffed by `mount::reseat_mounts`).
+/// Diff each attached entity's live appearance against what its visual was built with: a display
+/// move swaps the model, a scale move arms the 2 s ease, and a change of the native display or
+/// `SCALE_X` restamps [`CollisionHeight`]. Mount children carry no [`ObjectStore`]: their display
+/// is the host's field, diffed by `mount::reseat_mounts`.
 #[allow(clippy::type_complexity)]
 pub(super) fn refresh_live_display(
     mut commands: Commands,
@@ -132,10 +97,7 @@ pub(super) fn refresh_live_display(
                 );
                 net.display_id = Some(live);
                 swapped.write(DisplaySwapped { entity });
-                // The full visual teardown set + our own diff key: children (parts, anchors,
-                // held roots, mount child) despawn, the per-instance visual components strip, and
-                // `attach_entity_visuals` rebuilds next frame(s) with the new display —
-                // fade-skipped via `Reattached` (a shapeshift isn't a spawn).
+                // `attach_entity_visuals` rebuilds from scratch, fade-skipped by `Reattached`.
                 commands
                     .entity(entity)
                     .despawn_related::<Children>()
@@ -164,9 +126,8 @@ pub(super) fn refresh_live_display(
         }
 
         // ── The scale ease ───────────────────────────────────────────────────────────────────
-        // The same kinds the create path scales (`events/decode.rs` `object_scale`): a kind whose
-        // create ignored the field must keep ignoring its deltas, or the first delta would "fix"
-        // a scale the create deliberately floored to 1.0.
+        // The kinds the create path scales: a kind whose create ignored the field ignores its
+        // deltas too, or the first delta would undo the create's 1.0.
         let scaled_kind = matches!(
             net.kind,
             EntityKind::Unit | EntityKind::Player | EntityKind::GameObject | EntityKind::Corpse
@@ -187,17 +148,9 @@ pub(super) fn refresh_live_display(
         }
 
         // ── The collision prism ──────────────────────────────────────────────────────────────
-        // Derived from the unit's **native** display, so the rendered swap above is NOT one of its
-        // inputs (decision 1574 — the reference reads `NATIVEDISPLAYID` at `[unit+0x110]+0x1f8`).
-        // Its two real inputs are `UNIT_FIELD_NATIVEDISPLAYID` and `SCALE_X`, and neither has a
-        // change-gate we can piggyback on, so it is recomputed and diffed against the stamped
-        // component instead: two `HashMap` lookups per attached unit per frame, the same order as
-        // the two store reads this loop already does above (~0.02 ms at 300 units — a twentieth of
-        // the standing-idler cost decision 1445 gated away, and unlike a gate it cannot miss a
-        // native-display change that moved no pixel).
-        //
-        // Snapped to the TARGET scale immediately (the swim/wade/splash lines move once) — easing
-        // a collision plane would drag the resolver through two seconds of intermediate depths.
+        // From the native display (`[unit+0x110]+0x1f8`) and `SCALE_X`, not the rendered swap
+        // above; recomputed and diffed each frame, as no change gate covers both. It snaps to the
+        // target scale: easing it would drag the depth lines through two seconds of depths.
         let prism = super::collision_height::prism_display_id(Some(store), net.display_id);
         let h = collision_height_for(creatures.as_deref(), prism, net.scale);
         if height != Some(&h) {
@@ -216,8 +169,8 @@ pub(super) fn refresh_live_display(
     }
 }
 
-/// Tick every live [`ScaleEase`]: `scale(t) = from + (to − from) · (0.5 − 0.5·cos(π·t/2s))` — the
-/// reference's cosine smoothstep (`0x614bbf`) — then land exactly on the target and retire.
+/// Tick every [`ScaleEase`], `from + (to − from) · (0.5 − 0.5·cos(π·t/2 s))` (`0x614bbf`), then
+/// land exactly on the target.
 pub(super) fn tick_scale_ease(
     mut commands: Commands,
     time: Res<Time>,
@@ -235,23 +188,15 @@ pub(super) fn tick_scale_ease(
     }
 }
 
-/// Palette headroom below which the healer waits: rebuilding into a still-tight table would just
-/// re-starve, and the doodad reaper (`doodad_anim::lazy`) is what makes room. Deliberately under
-/// the reaper's low-water (256) so the reaper engages first and the heal follows into the space
-/// it opened.
+/// Palette headroom the healer waits for, under the doodad reaper's low-water (256) so the reaper
+/// makes room first; rebuilding into a tight table would starve again.
 const HEAL_MIN_HEADROOM: usize = 128;
 
-/// Visual rebuilds per frame — a starved *population* (a whole stream-in burst denied at once)
-/// heals over a second or two instead of one spike of teardown+reattach commands.
+/// Rebuilds per frame, so a starved stream-in burst heals over a second or two, not in one spike.
 const HEAL_PER_FRAME: usize = 2;
 
-/// Rebuild the visuals of units whose attach was DENIED a palette rig (decision 0863 — the
-/// [`RigStarved`](benilla_world::rig_palette::RigStarved) marker): the same teardown set as the
-/// display-id swap above (the reference's `0x60abe0` rebuild), fade-skipped via `Reattached` —
-/// a heal is not a spawn. `attach_entity_visuals` rebuilds next frame(s), allocating with the
-/// headroom this system waited for; if the table filled again in between, the attach re-marks
-/// and the healer comes back. Before this system, a full-table denial froze the unit at bind
-/// pose for its whole life — the "statue mobs at the stream-in boundary" bug.
+/// Rebuild units whose attach was denied a palette rig (`RigStarved`), which otherwise stay at bind
+/// pose: the display swap's teardown, fade-skipped; a table full again re-marks them.
 #[allow(clippy::type_complexity)] // one query's two-marker filter
 pub(super) fn heal_rig_starved(
     mut commands: Commands,
@@ -304,10 +249,6 @@ pub(super) fn heal_rig_starved(
 mod tests {
     use super::*;
 
-    /// The heal law (decision 0863): a rig-starved unit rebuilds — visual children despawned,
-    /// the attach trigger re-armed (`VisualAttached` off, `Reattached` on), the marker consumed
-    /// — but ONLY when the palette has real headroom; against a still-tight table the healer
-    /// waits (rebuilding into it would just re-starve).
     #[test]
     fn a_starved_unit_rebuilds_when_the_table_has_room_and_waits_when_it_has_not() {
         let mut app = App::new();
@@ -325,7 +266,7 @@ mod tests {
             .add_child(child)
             .id();
 
-        // Choke the table under the heal's minimum headroom: the unit is left alone.
+        // Fill the table past the heal's minimum headroom: the unit is left alone.
         let hoard: Vec<benilla_world::rig_palette::RigSkin> = {
             let mut palettes = app
                 .world_mut()
@@ -346,7 +287,7 @@ mod tests {
             "no headroom ⇒ the healer waits"
         );
 
-        // Room opens (the reaper's doing, in the live app): the rebuild teardown lands.
+        // Room opens, as the reaper makes it in the app: the rebuild teardown lands.
         {
             let mut palettes = app
                 .world_mut()
@@ -373,8 +314,6 @@ mod tests {
         );
     }
 
-    /// The ease's shape is the reference's (`0x614bbf`): starts at `from`, cosine-smooth (half-way
-    /// in value at half-way in time), lands exactly on `to` at 2 s and holds.
     #[test]
     fn scale_ease_is_the_2s_cosine_smoothstep() {
         let w = |elapsed: f32| {
@@ -382,11 +321,9 @@ mod tests {
             0.5 - 0.5 * (std::f32::consts::PI * t).cos()
         };
         assert_eq!(w(0.0), 0.0);
-        assert!((w(1.0) - 0.5).abs() < 1e-6); // cos(π/2) = 0 → half-way in value at 1 s
+        assert!((w(1.0) - 0.5).abs() < 1e-6); // cos(π/2) = 0: half-way in value at 1 s
         assert_eq!(w(2.0), 1.0);
         assert_eq!(w(3.0), 1.0); // clamped past the window
-                                 // Smoothstep, not linear: the first quarter of the window covers less than a quarter
-                                 // of the value (the eased head), symmetric with the tail.
         assert!(w(0.5) < 0.25);
         assert!(w(1.5) > 0.75);
     }
diff --git a/crates/benilla-app/src/entities/missile.rs b/crates/benilla-app/src/entities/missile.rs
index 29015251..e4ebd844 100644
--- a/crates/benilla-app/src/entities/missile.rs
+++ b/crates/benilla-app/src/entities/missile.rs
@@ -1,84 +1,48 @@
-//! Spell **missiles** (decision 0099 phase 4): the travelling projectile a Speed>0 cast launches
-//! at each target — Fireball's fireball, an NPC frostbolt — and the impact hand-off when it
-//! arrives.
+//! Spell missiles: the projectile a cast with a `Spell.dbc` Speed above 0 flies at each target, and
+//! the hand-off when it arrives. The router emits one [`MissileSpawn`] per GO; this module owns
+//! launch and flight.
 //!
-//! The router (`crate::creature_anim::spell_visual::route_cast_visuals`) resolves the GO's DBC
-//! chain and emits one [`MissileSpawn`]; this module owns launch and flight.
+//! Launch is release-keyed: a GO whose cast kit plays a body animation parks its projectiles on
+//! the caster ([`PendingMissiles`]) until the animation's `$CSL`/`$CSR`/`$CST` (casting hand) or
+//! `$BWR` (ranged) event drains them from its live position (`0x5ffbd0` → `0x60c940`). A GO with no
+//! cast-kit animation launches at once (`0x6e7a70`), and a queue whose event never fires launches
+//! when the one-shot ends (`0x5fc920`), both from the `$CSL` → `$CSR` → `$CST` → base cascade
+//! (`0x60c9b0`).
 //!
-//! **Launch is release-keyed, not GO-keyed** (the client's `unit+0xac` pending queue): a GO whose
-//! cast kit plays a body animation parks its projectiles on the caster ([`PendingMissiles`]) and
-//! launches them when that animation's **release event keyframe** fires — `$CSL`/`$CSR`/`$CST`
-//! (casting hand left/right/two-hand) or `$BWR` (ranged release), the anim-event dispatcher's
-//! drain arms (`0x5ffbd0` → `0x60c940`) — from the fired marker's live bone-ridden position: the
-//! fireball leaves the raised hand at the top of the throw, not the hold pose at GO. A GO with no
-//! cast-kit animation launches immediately (`0x6e7a70`'s flush), and a queued cast whose keyframe
-//! never fires launches when the one-shot ends (the client's on-anim-finish `0x5fc920` →
-//! `0x60c9b0`), both through the same `$CSL` → `$CSR` → `$CST` → unit-base cascade (`0x60c9b0`).
+//! The arrival deadline is fixed at GO: the launch (`0x61ceb0`) flies `distance / Speed` less the
+//! time queued, and a release already past it, as at melee range, shows only the impact. In flight
+//! the missile homes on the target's live attachment and arrives on time (`0x61e2a0`).
 //!
-//! The **arrival deadline is fixed at GO** (the client's `0x61ceb0`: remaining travel time =
-//! `distance / Spell.dbc Speed` **minus the time spent queued** — riding the hand eats flight
-//! time, the same clock the server delays the damage by). A release already past its deadline
-//! 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.
+//! On arrival `0x61e1d0` picks an arm by whether the target guid still resolves, then by the hit
+//! bit `[missile+0x38] & 1`, set only at the spawn (`0x60a4e8`):
+//! - `0x61dc50`, a live target hit: wound, flinch and impact visual, no word; here
+//!   [`CastEventKind::Impact`].
+//! - `0x61dd50`, a live target missed: the outcome word, `UNIT_COMBAT` and chat, then the
+//!   disposition; here the defense clip and [`MissileMiss`].
+//! - `0x61d870`, no live target: plays on the caster, then walks the missile's guid list skipping
+//!   code 0; here [`CastEventKind::GroundImpact`]. A target that despawned mid-flight lands here as
+//!   well as a ground cast.
 //!
-//! 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** —
-//! so a moving target bends the path (homing) and arrival lands exactly on schedule. Arrival on a
-//! landed target writes [`CastEventKind::Impact`] back to the router (the client's unit-impact
-//! 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).
+//! With no visual-chain model a missile flies the wire's ammo (Auto Shot, Shoot, Throw: all
+//! `SpellVisual` 0), an `ItemDisplayInfo` row resolved by shape: a model in the right slot is
+//! `Item\ObjectComponents\Ammo\`, in the left `…\Weapon\` (thrown), each with its object skin. The
+//! reference resolves the row through `0x479f40`, forking on the wire's ammo InventoryType (`0x19`,
+//! thrown), and the shape rule matches it on every shipped row. With no model at all the missile
+//! flies invisible and still impacts on schedule.
 //!
-//! **`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.
+//! A GO with no unit targets but a point flies one projectile at it (`0x6e8a50`'s empty-hit-array
+//! arm calls `0x60a3d0` once, unit slot −1): the Flare, a bomb thrown at empty ground. It aims at a
+//! fixed point ([`Aim::Ground`]), arrives as [`CastEventKind::GroundImpact`] on the caster
+//! (`0x61d870`) and flies the same straight, arrive-on-time line as a unit missile: the
+//! reference's flight is linear, with no gravity (`0x61ceb0`, `0x61e2a0`).
 //!
-//! | arm | reached when | what it does | ours |
-//! |---|---|---|---|
-//! | `0x61dc50` | live target, HIT set | wound/flinch + impact visual. **Floats no word.** | [`CastEventKind::Impact`] |
-//! | `0x61dd50` | live target, HIT clear | floats the outcome word + UNIT_COMBAT + chat, then disposes of the projectile per code | the defense clip + [`MissileMiss`] |
-//! | `0x61d870` | **no live target resolved** | plays on the CASTER, then walks the missile's own guid list (skipping code 0 per target) | [`CastEventKind::GroundImpact`] |
-//!
-//! Two consequences worth stating because they are easy to get backwards. A missed travelling
-//! spell's wound/flinch is not "skipped" — `0x61dc50` is never *reached*, because a nonzero
-//! outcome means the spawn was not told HIT. And `0x61d870` is **not** "the ground arm": a
-//! ground cast is only its commonest cause; a target that despawned mid-flight lands there too.
-//!
-//! A missile with no visual-chain model flies the **wire ammo model** instead (decision 0099
-//! phase 5 — every basic shot spell: Auto Shot, the Shoot family, Throw, all `SpellVisual = 0`):
-//! the GO's ammo block names an `ItemDisplayInfo` row, resolved by its **shape** — flight model
-//! in the right slot → `Item\ObjectComponents\Ammo\` (arrows/bullets), left slot → `…\Weapon\`
-//! (thrown: the weapon itself flies) — each with its own object skin, exactly the held-items
-//! texture mechanism. The client resolves the same row through `0x479f40`, forking on the wire's
-//! ammo InventoryType (`0x19` = thrown); the shape rule reproduces it on every real row
-//! (`benilla-formats` `items.rs` tests). No model at all (no chain, no ammo) → the missile flies
-//! invisible and still impacts on schedule.
-//!
-//! Approximations, named: `$BWR` launches from its own event marker rather than the ranged
-//! weapon model's HandArrow/Bullet attachment (`0x23`/`0x24` — the client's first choices before
-//! it, too, falls back to the event position); the anim-end flush is a **polled** edge (plus a
-//! [`RELEASE_WAIT_MAX`] never-played timeout) where the client gets a per-anim finish callback;
-//! homing aims at the dest attach point rather than solving the client's
-//! ray-vs-bounding-sphere intercept (`0x61d230` — same body point in practice); a missed
-//! target's arrival plays its dodge/block clip and floats its word, but the projectile itself
-//! always ends there. **`0x61dd50`'s per-outcome DISPOSITION table is not implemented** (its
-//! jump table `0x61d76c` + case bytes `0x61d784`): the reference despawns on MISS/DODGE/EVADE
-//! and on DEFLECT/ABSORB, but persists a BLOCKed missile 5000 ms (`0x61e7c0`), rebuilds the
-//! model for RESIST/IMMUNE (`0x707350` on `0x861790`) before persisting, **deflects** a parried
-//! one along a curve (`0x4531e0` + two `0x7be490` rotations + a velocity damp), and on REFLECT
-//! re-targets the CASTER and re-launches with the wire's `reflectResult` as the new code. We
-//! 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). 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 is still open — so a lobbed
-//! shot reads as a straight glide here.
+//! Not built: `$BWR` launches from its event marker, where the reference first tries the ranged
+//! weapon's HandArrow/Bullet attachment (`0x23`/`0x24`); homing aims at the attachment point, not
+//! the ray-sphere intercept `0x61d230`, the same body point in practice; and `0x61dd50`'s
+//! per-outcome disposition (jump table `0x61d76c`, cases `0x61d784`), which keeps a BLOCK 5000 ms
+//! (`0x61e7c0`), rebuilds a RESIST or IMMUNE model (`0x707350` on `0x861790`), curves a DEFLECT
+//! away (`0x4531e0`, `0x7be490`) and re-launches a REFLECT at the caster, where every miss here
+//! ends on arrival.
 
 use bevy::animation::transition::AnimationTransitions;
 use bevy::ecs::entity::EntityHashMap;
@@ -94,119 +58,90 @@ use super::equipment::ItemDisplays;
 use super::spell_fx::{attach_effect_visuals, ensure_model, EffectHost, FxMaterials, SpellFx};
 use super::{BoneAttach, DisplayModel, ModelHandle};
 
-/// The anim-event idents that release queued missiles — the dispatcher's drain arms (`0x5ffbd0`:
-/// `$CSL`/`$CSR`/`$CST` casting hand, `$BWR` ranged release; all four call the queue drain
-/// `0x60c940`).
+/// The release events whose dispatcher arms drain the queue (`0x5ffbd0` → `0x60c940`).
 const RELEASE_IDENTS: [[u8; 4]; 4] = [*b"$CSL", *b"$CSR", *b"$CST", *b"$BWR"];
 
-/// The flush cascade when no release event names a marker (immediate launch at GO, the anim-end
-/// flush): the client's `0x60c9b0` — `$CSL`, then `$CSR`, then `$CST`, else the unit's base.
+/// The `0x60c9b0` launch cascade when no release event names a point, before the unit's base.
 const MARKER_CASCADE: [[u8; 4]; 3] = [*b"$CSL", *b"$CSR", *b"$CST"];
 
-/// How long a queued missile waits for a one-shot that never starts before flushing anyway
-/// (seconds). The release animation arms within a frame or two of the GO, after which the
-/// anim-end edge owns the flush and this window no longer applies; a caster that never shows one
-/// (the kit anim didn't resolve on this model) would otherwise hang its projectiles forever —
-/// the client has no such window because its anim-finish callback always fires. Comfortably
-/// above any arm latency (a frame or two, even hitchy).
+/// Seconds a queue waits for a one-shot that never starts, well above the frame or two a release
+/// animation takes to arm. The reference's per-animation finish callback always fires; here the end
+/// is a polled edge, and a kit animation that never resolves on the model would hang the queue.
 const RELEASE_WAIT_MAX: f32 = 0.25;
 
-/// The dest-attach fallback tail (after the spawn's own tag): the client's cascade again.
+/// The destination attachments tried after the spawn's own tag, as the reference cascades.
 const DEST_FALLBACKS: [u16; 2] = [0xf, 0x13];
 
-/// `AnimationData.dbc` **InFlight** — the sequence a projectile MODEL plays while it travels. A
-/// thrown weapon (`Item\ObjectComponents\Weapon\Thrown_1H_*.m2`) authors it as the end-over-end
-/// tumble (e.g. the dagger's 19-key bone rotation) and keys its trail ribbon's per-sequence
-/// visibility ON only here — Stand (worn in hand) and Impact (landed) keep it off. A projectile
-/// model without an InFlight sequence (arrows/bullets fly straight; the fireball tumbles via a
-/// global sequence) is unaffected — the rig falls back to its file-order-first clip.
+/// `AnimationData.dbc` InFlight, the sequence a projectile model plays in flight: a thrown weapon
+/// tumbles end over end and shows its trail only here; a model without it plays its first clip.
 const INFLIGHT_ANIM: u16 = 144;
 
-/// The missile's orientation for flight direction `f` (Bevy space) — the client's exact frame
-/// 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`,
-/// local +Y (image of wow +Z) → the re-orthogonalized up.
+/// The missile's orientation for flight direction `f`, the reference's frame (`0x61e2a0`): model
+/// +X along the flight, side = up × dir, up = dir × side, so it never rolls however the flight
+/// pitches. In Bevy, local −Z (wow +X) maps to `f` and local +Y (wow +Z) to that up.
 fn missile_facing(f: Vec3) -> Quat {
     let side = Vec3::Y.cross(f);
     if side.length_squared() < 1e-6 {
-        // Straight up/down — the degenerate vertical case; any roll is fine here.
+        // Straight up or down: any roll will do.
         return Quat::from_rotation_arc(-Vec3::Z, f);
     }
     let up = f.cross(side.normalize()).normalize();
-    // Columns are the images of local X/Y/Z: X → f × up (= −side, the handedness-consistent
-    // image of wow +Y), Y → up, Z → −f.
+    // Columns are the images of local X, Y, Z: `f × up` (−side, the image of wow +Y), `up`, `−f`.
     Quat::from_mat3(&Mat3::from_cols(f.cross(up), up, -f))
 }
 
-/// 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`.
+/// The projectile's looping flight sound, `SpellVisual` field 10: the reference's first flight
+/// step starts it (`0x61e79e`) and every later step moves it with the missile (`0x61e77c`).
+/// Written by [`spawn_missiles`] and [`move_missiles`] for `crate::sound::missile`.
 #[derive(Message, Clone, Copy)]
 pub(crate) enum MissileSound {
-    /// Begin `kit_sound` as a loop tracked to `entity` (the launched projectile). `pos` is the
-    /// launch point — the channel is born positional there (the just-spawned entity's `Transform`
-    /// may not have flushed yet), then rides the entity as it flies.
+    /// Start `kit_sound` on the launched `entity`, born at `pos`, the launch point, since the new
+    /// entity's `Transform` may not have flushed yet.
     Start {
         entity: Entity,
         kit_sound: u32,
         pos: Vec3,
     },
-    /// The projectile is gone (arrived / streamed out) — stop its flight loop.
+    /// The projectile arrived or streamed out.
     Stop { entity: Entity },
 }
 
-/// What a projectile flies at — the client's two `CMissile` flavours, split by whether the spawn
-/// had an owning unit slot (`0x60a5ec` writes −1 for the location fallback) and dispatched apart
-/// on arrival by `0x61e1d0` (`0x61dc50` a live unit, `0x61d870` the ground).
+/// What a projectile flies at, the reference's two `CMissile` kinds: an owning unit slot, or −1
+/// for the location fallback (`0x60a5ec`).
 #[derive(Clone, Copy)]
 enum Aim {
-    /// A unit target: the flight homes to its live attach point, so a moving target bends the path.
+    /// A unit target, homed to its live attachment, so a moving target bends the path.
     Unit {
-        /// The unit it flies at (despawn quietly if it streams out mid-flight).
         target: Entity,
-        /// The M2 attach tag it homes to on the target (`SpellVisual` field 9), `None` = base.
+        /// The attachment it homes to (`SpellVisual` field 9); `None` is the base.
         dest_tag: Option<u16>,
-        /// `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) and no impact kit.
+        /// The wire's `SpellMissInfo` code for a miss, which arrives as the victim's defense clip
+        /// instead of the impact; `None` for a hit.
         miss: Option<u8>,
     },
-    /// A fixed world point — the GO's dest, with no unit to home to and nothing that can make the
-    /// flight end early. Arrival is the ground hand-off on the caster.
+    /// The GO's destination point; arrival is the ground hand-off on the caster.
     Ground(Vec3),
 }
 
 /// One projectile in flight.
 #[derive(Component)]
 pub(super) struct Missile {
-    /// The spell that fired it — the impact event's key.
     spell_id: u32,
-    /// The unit that launched it — the ground arrival's kit subject (`0x61d870` plays on the
-    /// caster). Unused by a unit arrival, which plays on the target.
+    /// A ground arrival plays on the caster (`0x61d870`), a unit arrival on the target.
     caster: Entity,
-    /// Where it is going.
     aim: Aim,
-    /// The model-cache key ([`SpellFx`]); parts attach once the M2 loads. `None` = nothing to
-    /// show (no visual-chain model, no resolvable ammo) — an invisible flight that still impacts.
+    /// The [`SpellFx`] cache key; `None` flies invisible and still impacts.
     path: Option<String>,
-    /// Remaining flight time, seconds — the client's arrive-on-time integrator state.
+    /// Remaining flight time in seconds, the arrive-on-time integrator's state.
     arrive_in: f32,
-    /// Model parts/emitters spawned (they wait on the async M2 load, like every display model).
     parts_spawned: bool,
-    /// The caster's ranged-weapon fallback `SpellVisual` id (resolved at GO time) — handed back
-    /// in the arrival's [`CastEventKind::Impact`] so a basic shot's impact kit resolves through
-    /// it (the caster may despawn mid-flight; decision 0370).
+    /// The caster's ranged-weapon `SpellVisual`, resolved at GO, so a basic shot's impact kit
+    /// resolves even if the caster despawns mid-flight.
     weapon_visual: Option<u32>,
 }
 
-/// The unit-side inputs every attach/marker **position read** shares: the base frame, the
-/// attachment/marker tables, and the pose the point is computed from. A pure read — the point
-/// comes from `RigPose::posed_point` (composed pose × rig root frame), so these reads spawn no
-/// anchor entity (decision 1355). Shared with the chain-beam lane.
+/// The unit-side inputs of an attachment or marker position read: the base frame, the tables and
+/// the pose, read through `RigPose::posed_point` without an anchor entity.
 pub(super) type AttachPosQuery<'w, 's> = Query<
     'w,
     's,
@@ -217,9 +152,8 @@ pub(super) type AttachPosQuery<'w, 's> = Query<
     ),
 >;
 
-/// A unit's attach-point world position through the given tag cascade, else its base translation.
-/// `None` only when the unit itself is gone. Shared with the chain-beam lane, whose non-caster
-/// endpoints anchor through the very same table and cascade (`0x6ec780`; decision 0955).
+/// A unit's attachment position through the tag cascade, else its base; `None` only when the unit
+/// is gone. Chain-beam endpoints use it too, as `0x6ec780` reads the same table the same way.
 pub(super) fn attach_world_pos(
     unit: Entity,
     tags: impl IntoIterator<Item = u16>,
@@ -236,9 +170,7 @@ pub(super) fn attach_world_pos(
     Some(point.unwrap_or_else(|| base.translation()))
 }
 
-/// Where a missile is heading **this frame**: a unit target's live dest attach point (so the
-/// path bends as it moves — the client's re-solve per tick), or the ground shot's fixed point.
-/// `None` only when a unit target is gone.
+/// This frame's aim, re-solved every tick as the reference does.
 fn aim_point(aim: Aim, units: &AttachPosQuery, joints: &Query<&GlobalTransform>) -> Option<Vec3> {
     match aim {
         Aim::Unit {
@@ -253,11 +185,8 @@ fn aim_point(aim: Aim, units: &AttachPosQuery, joints: &Query<&GlobalTransform>)
     }
 }
 
-/// The caster's **launch position**: the fired release event's own marker when there is one (the
-/// dispatcher passes the event's live position, `0x5ffbd0` → `0x60c940(param_4)`), else the
-/// `$CSL` → `$CSR` → `$CST` marker cascade at the current pose, else the unit's base — the
-/// client's `0x60c9b0` exactly. Same bone-riding transform as [`attach_world_pos`], reading the
-/// event-marker table instead of the attachment table. `None` only when the caster is gone.
+/// The caster's launch point: the fired release event's own marker, as the dispatcher passes the
+/// event's live position (`0x5ffbd0` → `0x60c940`), else the `0x60c9b0` cascade at this pose.
 fn launch_world_pos(
     caster: Entity,
     fired: Option<[u8; 4]>,
@@ -275,46 +204,35 @@ fn launch_world_pos(
     Some(point.unwrap_or_else(|| base.translation()))
 }
 
-/// One GO's projectiles parked on their caster, waiting for the release keyframe — the client's
-/// `unit+0xac` pending list. The model-cache key is resolved at queue time (the client creates
-/// the missile's M2 at queue too, so the async load warms while the release animation plays).
+/// One GO's projectiles parked on the caster until the release keyframe, a node of the reference's
+/// `unit+0xac` list; its model loads from queue time, as the reference creates the M2 there.
 struct QueuedGo {
     spawn: MissileSpawn,
-    /// The [`SpellFx`] cache key ([`Missile::path`]'s value-to-be) — `None` = an invisible flight.
+    /// The [`SpellFx`] key that becomes [`Missile::path`].
     key: Option<String>,
-    /// Seconds spent queued — subtracted from the flight time at launch (`0x61ceb0`'s
-    /// `elapsed` term: the arrival deadline was fixed at GO).
+    /// Seconds queued, subtracted from the flight at launch (`0x61ceb0`'s `elapsed` term).
     queued: f32,
-    /// Whether a one-shot has been seen live on the caster since queuing — arms the anim-end
-    /// flush edge (never flush on "no one-shot" before the release animation even started).
+    /// A one-shot has played on the caster since queuing, which arms the anim-end flush.
     saw_oneshot: bool,
 }
 
-/// 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). `[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.
+/// Every caster's queue of projectiles awaiting release, the reference's `CGUnit+0xac` list of
+/// `CMissile` nodes, filled by the spawner `0x60a3d0` and drained by the release event; a caster
+/// that streams out drops its queue. It is also a gate: the `$BWR` handler tests the list head
+/// (`0x600182`) and only when a projectile waits re-animates the ranged prop, looks up the
+/// attachment and launches (`0x600294` calls `0x60c940`), so a shot's flex and launch are one act.
 #[derive(Resource, Default)]
 pub(crate) struct PendingMissiles(EntityHashMap<Vec<QueuedGo>>);
 
 impl PendingMissiles {
-    /// Is a projectile queued on `caster`, waiting for its release keyframe? The reference's
-    /// `test eax,eax` on the list head — asked by [`crate::ranged_flex`] before the drain, which is
-    /// the order `0x600182` and `0x600294` sit in.
+    /// Whether a projectile waits on `caster` for its release keyframe, the reference's list-head
+    /// test; [`crate::ranged_flex`] asks it before the drain, in the reference's order.
     pub(crate) fn releasing(&self, caster: Entity) -> bool {
         self.0.get(&caster).is_some_and(|q| !q.is_empty())
     }
 
-    /// Queue one projectile on `caster` — **test-only**, for the consumers of the gate above
-    /// ([`crate::ranged_flex`]), which need the queue non-empty without standing up the whole GO
-    /// path to put something in it. The node's contents are irrelevant to every reader of
-    /// [`Self::releasing`]; only its presence is.
+    /// Queues one projectile on `caster` for tests of the gate's consumers; only its presence
+    /// matters.
     #[cfg(test)]
     pub(crate) fn queue_a_shot(app: &mut bevy::app::App, caster: Entity) {
         let spawn = MissileSpawn {
@@ -344,10 +262,8 @@ impl PendingMissiles {
     }
 }
 
-/// The ammo display's flight model as a [`SpellFx`] cache entry: the **shape rule** (module
-/// docs — right slot = `Ammo\`, left slot = `Weapon\`, thrown), with the row's own object skin.
-/// The key is `ammo:<display id>` — opaque to the cache, unique per display, so two displays
-/// sharing a model but not a skin never collide. `None` = unknown display / model-less row.
+/// The ammo display's flight model by the shape rule (module docs), as a [`SpellFx`] entry keyed
+/// `ammo:<display id>`, so two displays sharing a model but not a skin never collide.
 fn ensure_ammo_model(
     fx: &mut SpellFx,
     displays: &ItemDisplays,
@@ -375,38 +291,27 @@ fn ensure_ammo_model(
     Some(key)
 }
 
-/// A travelling spell's **deferred outcome word** (decision 2229) — the arrival half of the
-/// floating-combat-text miss word.
-///
-/// `SMSG_SPELL_GO`'s inline word emit is skipped whenever `Spell.dbc` Speed is nonzero
-/// (`0x6e7d4e`), and the projectile floats the word when it lands instead: the arrival handlers
-/// re-resolve the spell record from `[missile+0x18]` and call the same word emitter `0x607140`
-/// the inline site calls. Written here because only the flight knows *when*; the source class,
-/// the CVar gates and the colour are `crate::combat_text::missile_miss_text`'s, which owns that
-/// law for every emitter.
+/// A travelling spell's deferred miss word. `SMSG_SPELL_GO` skips its inline word when the
+/// `Spell.dbc` Speed is nonzero (`0x6e7d4e`); the arrival re-resolves the spell from
+/// `[missile+0x18]` and calls the same emitter `0x607140`. Its source class, CVar gates and colour
+/// are `crate::combat_text::missile_miss_text`'s.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct MissileMiss {
-    /// The unit that cast it — the colour law's source class (`K`).
+    /// The colour law's source class (`K`).
     pub(crate) caster: Entity,
-    /// The unit the word floats over — **always the missed target**, `0x61ddb3`'s `this = edi`
-    /// (`0x61d9dc`'s is the per-entry target). Unlike the *inline* site, the arrival never
-    /// re-anchors a REFLECT to the caster: `0x61dd50` floats "Reflect" over the target and then
-    /// re-launches the projectile at the caster, so the caster's word comes from that second
-    /// flight — which we do not yet fly (the disposition table, module doc).
+    /// Always the missed target (`0x61ddb3`; `0x61d9dc`'s is the per-entry target). Unlike the
+    /// inline site the arrival floats Reflect over the target, and the caster's word belongs to
+    /// the re-launched flight, which is not built.
     pub(crate) anchor: Entity,
-    /// The spell — the colour law's `B` bit resolves off its record.
+    /// The colour law's `B` bit resolves off its record.
     pub(crate) spell_id: u32,
     /// The wire's `SpellMissInfo` code (1–11).
     pub(crate) code: u8,
 }
 
-/// **A travelling spell cannot be PARRIED — it is DEFLECTED.** The launch classifier `0x61d720`
-/// (sole caller `0x61cebb`, inside the launch `0x61ceb0`) rewrites the outcome as it picks the
-/// projectile's disposition: `61d753 or eax,0x40` then `61d756 mov dword ptr [ecx+0x48],0x9` —
-/// PARRY(4) is stored back as DEFLECT(9), so every downstream reader (the word emitter, the
-/// UNIT_COMBAT feed, the chat line) sees 9. This is the mechanism behind the recorded negative
-/// that a ranged arrival never plays a parry clip: by arrival there is no parry left to play.
-/// Every other code passes through.
+/// A travelling spell is deflected, never parried: the launch classifier `0x61d720`, called from
+/// the launch at `0x61cebb`, stores PARRY(4) back as DEFLECT(9) (`0x61d756`), so the word, the
+/// `UNIT_COMBAT` feed and the chat line all see 9. Every other code passes through.
 fn launch_outcome_code(code: u8) -> u8 {
     if code == 4 {
         9
@@ -415,13 +320,9 @@ fn launch_outcome_code(code: u8) -> u8 {
     }
 }
 
-/// The wire `SpellMissInfo` codes whose missile arrival plays a victim defense clip, mapped to
-/// the melee `$CPP` dispatch's victimState keys (the [`DefenseAnim`] consumer's
-/// `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 negative that a ranged arrival never parries
-/// (`0x61ceb0`).
+/// The victim clip a missed arrival plays, as the melee `$CPP` dispatch's victim state
+/// ([`DefenseAnim`]): DODGE(3) plays Dodge (30), BLOCK(5) ShieldBlock (24), any other code
+/// nothing; PARRY(4) never arrives, as [`launch_outcome_code`] rewrote it.
 fn miss_defense_state(code: u8) -> Option<u32> {
     match code {
         3 => Some(2), // SPELL_MISS_DODGE → the dispatch's DODGES state
@@ -430,38 +331,23 @@ fn miss_defense_state(code: u8) -> Option<u32> {
     }
 }
 
-/// **The arrival hand-off's writer set, as one system parameter.** Both missile systems sit at
-/// 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
-/// the combat log's CVar context ([`crate::combat_log::Ctx`]) is, so the call sites read `out.words` rather
-/// than a positional tuple field.
+/// Everything a landing projectile emits, as one system parameter: both missile systems sit at
+/// Bevy's 16-parameter ceiling.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(super) struct ArrivalOut<'w> {
-    /// The router's landed-target impact / ground-burst event.
     impacts: MessageWriter<'w, CastEvent>,
-    /// A missed target's dodge/block clip ([`miss_defense_state`]).
     defenses: MessageWriter<'w, DefenseAnim>,
-    /// A missed target's floating outcome WORD ([`MissileMiss`]).
     words: MessageWriter<'w, MissileMiss>,
 }
 
-/// The arrival hand-off — the client's per-tick outcome dispatch (`0x61e1d0` over `0x61ceb0`'s
-/// clock): a landed spell routes back to the router as [`CastEventKind::Impact`] on the target
-/// (the impact/state kits + wound flinch); a missed one instead plays the victim's defense clip
-/// per [`miss_defense_state`], and no impact kit plays; a **ground** arrival routes
-/// [`CastEventKind::GroundImpact`] to the CASTER carrying the landing point (`0x61d870`).
-///
-/// A missed arrival ALSO floats the outcome WORD ([`MissileMiss`], decision 2229) — the deferred
-/// half of the miss text, which `SMSG_SPELL_GO` skipped because this spell has a travel speed.
+/// The arrival hand-off, by the arms of the reference's per-tick dispatch `0x61e1d0` (module docs).
 fn arrival_handoff(
     missile: &Missile,
     at: Vec3,
     out: &mut ArrivalOut,
     play_seq: &mut crate::creature_anim::PlaySeq,
 ) {
-    // Scene-time stamp: the client plays the arrival after the frame's packet handlers — a fresh
-    // tick sorts it the same way.
+    // A fresh tick sorts the arrival after the frame's packet handlers, as the reference plays it.
     let mut event = |entity, kind| CastEvent {
         entity,
         spell_id: missile.spell_id,
@@ -504,12 +390,8 @@ fn arrival_handoff(
     }
 }
 
-/// Launch one queued GO's projectiles from `launch`: one missile entity per target — or the
-/// single ground projectile when the GO had no unit targets and a point instead — its
-/// **remaining** travel time `distance / speed − time queued` (the client's `0x61ceb0` — the
-/// arrival deadline was fixed at GO). A release already past its deadline arrives on the spot:
-/// the arrival hand-off plays now, no flight entity, no flight loop — the melee-range cast
-/// shows only the hit, the reference's close-range look.
+/// Launch one queued GO from `launch`: a missile per target, or the one ground shot, each flying
+/// `distance / speed − time queued` (`0x61ceb0`); one already past its deadline hands off at once.
 fn launch_go(
     go: &QueuedGo,
     launch: Vec3,
@@ -520,8 +402,8 @@ fn launch_go(
     out: &mut ArrivalOut,
     play_seq: &mut crate::creature_anim::PlaySeq,
 ) {
-    // The unit targets, else the location fallback's lone ground shot (the client consults the
-    // `flags & 0x60` latch only once the hit array has come back empty).
+    // The unit targets, else the location fallback's one ground shot: the reference reads the
+    // `flags & 0x60` latch only for an empty hit array.
     let aims: Vec<Aim> = if go.spawn.targets.is_empty() {
         go.spawn.ground_aim.map(Aim::Ground).into_iter().collect()
     } else {
@@ -537,7 +419,7 @@ fn launch_go(
     };
     for aim_at in aims {
         let Some(aim) = aim_point(aim_at, units, joints) else {
-            continue; // target already gone — its impact would be invisible anyway
+            continue; // target already gone
         };
         let missile = Missile {
             spell_id: go.spawn.spell_id,
@@ -545,7 +427,7 @@ fn launch_go(
             aim: aim_at,
             path: go.key.clone(),
             arrive_in: launch.distance(aim) / go.spawn.speed.max(f32::EPSILON) - go.queued,
-            // Nothing to show → nothing to wait on (the invisible flight).
+            // An invisible flight has no parts to wait on.
             parts_spawned: go.key.is_none(),
             weapon_visual: go.spawn.weapon_visual,
         };
@@ -561,8 +443,7 @@ fn launch_go(
                 Visibility::default(),
             ))
             .id();
-        // The flight loop starts at launch and rides the projectile (the sound is independent
-        // of the model — an invisible missile still whooshes) until `move_missiles` reaps it.
+        // The flight loop starts at launch and rides the projectile, even an invisible one.
         if let Some(kit_sound) = go.spawn.missile_sound {
             sounds.write(MissileSound::Start {
                 entity,
@@ -573,15 +454,8 @@ fn launch_go(
     }
 }
 
-/// Consume the router's [`MissileSpawn`] and own the **pending queue** (module docs): a GO whose
-/// cast kit animates parks on the caster; the release keyframe (`$CSL`/`$CSR`/`$CST`/`$BWR` off
-/// the caster's playing clip) drains it from the fired marker's live position; a GO without one
-/// launches now through the `0x60c9b0` cascade. Backstops: the one-shot ending without its
-/// keyframe (the client's on-anim-finish flush), a one-shot that never starts
-/// ([`RELEASE_WAIT_MAX`]), a caster that streams out (queue dies with it). The model-cache entry
-/// is created at queue time (shared with the attach-point effects — the same `.mdx` is one load
-/// however many things use it); a chain-less spawn resolves the wire ammo display instead
-/// ([`ensure_ammo_model`]).
+/// Takes the router's [`MissileSpawn`]s and runs the pending queue (module docs): park, drain on
+/// the release keyframe or launch at once, and flush a queue whose keyframe never comes.
 pub(super) fn spawn_missiles(
     mut commands: Commands,
     time: Res<Time>,
@@ -605,8 +479,7 @@ pub(super) fn spawn_missiles(
     mut play_seq: ResMut<crate::creature_anim::PlaySeq>,
 ) {
     let Some(mut fx) = fx else { return };
-    // Intake: resolve the model key now (warm the load while the release animation plays), then
-    // park or launch on the GO's release gate.
+    // Resolve the model now, so it loads while the release animation plays.
     for spawn in spawns.read() {
         let key = match (&spawn.path, spawn.ammo_display_id) {
             (Some(path), _) => {
@@ -642,11 +515,9 @@ pub(super) fn spawn_missiles(
                 &mut out,
                 &mut play_seq,
             );
-        } // else: caster gone before its projectile left — nothing to show
+        } // else the caster is already gone
     }
-    // The release keyframes: a drain ident fired on a caster with a queue launches everything
-    // queued there, from the fired marker's position (the client passes the event's own position
-    // into the drain).
+    // A release ident fired on a caster launches its whole queue from the event's own position.
     for ev in anim_events.read() {
         if !RELEASE_IDENTS.contains(&ev.ident) {
             continue;
@@ -670,15 +541,14 @@ pub(super) fn spawn_missiles(
             );
         }
     }
-    // The backstop poll: age every queue; flush when the caster's one-shot ended without firing
-    // a release keyframe (the client's on-anim-finish `0x5fc920` → `0x60c9b0`), or never started
-    // ([`RELEASE_WAIT_MAX`]); drop a queue whose caster is gone.
+    // Age every queue, and flush one whose one-shot ended without its keyframe (the reference's
+    // anim-finish `0x5fc920` → `0x60c9b0`) or never started.
     let dt = time.delta_secs();
     let catalog = anim_data.as_deref().map(|d| &d.0);
     let mut flushes: Vec<(Entity, Vec<QueuedGo>)> = Vec::new();
     pending.0.retain(|&caster, gos| {
         if !units.contains(caster) {
-            return false; // caster streamed out — its pending projectiles die with it
+            return false; // caster streamed out: its queue dies with it
         }
         let live = casters
             .get(caster)
@@ -690,8 +560,7 @@ pub(super) fn spawn_missiles(
             flush |= (go.saw_oneshot && !live) || (!go.saw_oneshot && go.queued > RELEASE_WAIT_MAX);
         }
         if flush {
-            // Launched below — the launch's borrows (commands, the queries) are disjoint from
-            // this retain, but not expressible inside its closure.
+            // Launched below: the launch's borrows cannot live inside this closure.
             flushes.push((caster, std::mem::take(gos)));
             return false;
         }
@@ -716,9 +585,8 @@ pub(super) fn spawn_missiles(
     }
 }
 
-/// Spawn a missile's model parts + particle emitters once its M2 finishes building (the shared
-/// cache's `parts` fill in `super::update_display_models`) — children of the missile entity, so
-/// they ride the mover below. An unloadable model just flies invisible and still impacts on time.
+/// Spawn a missile's parts and emitters as its children once its M2 has built, so they ride the
+/// mover; an unloadable model flies invisible and still impacts on time.
 pub(super) fn attach_missile_models(
     mut commands: Commands,
     mut missiles: Query<(Entity, &mut Missile)>,
@@ -740,34 +608,22 @@ pub(super) fn attach_missile_models(
             continue;
         }
         let Some(key) = missile.path.clone() else {
-            continue; // unreachable (spawn sets parts_spawned) — but never look up a None key
+            continue; // unreachable: the spawn sets `parts_spawned`
         };
         ensure_model(&mut fx, &asset_server, &key);
         let Some(dm) = fx.models.get(&key) else {
-            continue; // unreachable — just inserted
+            continue; // unreachable: just inserted
         };
-        // The one shared effect-visuals body (`spell_fx::attach_effect_visuals`): the rig (the
-        // fireball's constant bone keys rotate its authored frame into flight-forward, its
-        // global sequence tumbles the molten core, bones 7/8 set the ribbon + cross), skinned
-        // parts, joint-riding cards/emitters/ribbons. `false` = still loading — attach on a
-        // later pass, mid-flight is fine.
-        //
-        // The missile runs its model's InFlight sequence when it authors one: the thrown weapon
-        // (Thrown_1H_*.m2) tumbles end-over-end through its InFlight bone rotation AND keys its
-        // trail ribbon's per-sequence visibility ON — the worn item sits in Stand with neither.
-        // A projectile with no InFlight sequence (an arrow, a fireball whose tumble is a global
-        // sequence) falls to the model's own `Stand` inside the rig, unchanged.
+        // `false` means still loading; a later pass attaches mid-flight.
         if !attach_effect_visuals(
             &mut commands,
             entity,
             dm,
             time.elapsed_secs(),
-            false, // a missile flies — its flat quads are geometry, never ground decals
-            // A missile is a FREE world model: its trail stays world-frozen, and its pool
-            // finishes in place when it impacts (0202's drain).
+            false, // a missile's flat quads are geometry, never ground decals
+            // A free world model: its trail stays world-frozen and its pool finishes in place.
             EffectHost::default(),
-            // A projectile is the separate `CMissile` TU, not a `CEffect`: it has no kit stage and
-            // no Birth/Hold/Decay lifecycle — it flies its one sequence and dies on arrival.
+            // A `CMissile`, not a `CEffect`: no kit stage and no Birth/Hold/Decay, one sequence.
             None,
             &mut FxMaterials {
                 store: &mut wow_materials,
@@ -785,12 +641,8 @@ pub(super) fn attach_missile_models(
     }
 }
 
-/// The per-frame mover — the client's arrive-on-time step (`0x61e2a0` over `0x61ceb0`'s clock):
-/// each frame the missile covers `dt / remaining-time` of the gap to the target's live dest
-/// attach point, so speed re-derives as `distance / remaining time` and a moving target bends
-/// the path. On schedule-end it snaps to the point, runs the [`arrival_handoff`] (a landed
-/// target's impact, a missed one's dodge/block), and despawns (children with it; emitters
-/// self-release via the owner contract).
+/// The reference's arrive-on-time step `0x61e2a0`: each frame covers `dt / remaining time` of the
+/// gap to the live aim; at the deadline the missile snaps there, hands off and despawns.
 pub(super) fn move_missiles(
     mut commands: Commands,
     time: Res<Time>,
@@ -804,11 +656,9 @@ pub(super) fn move_missiles(
     let dt = time.delta_secs();
     for (entity, mut missile, mut transform) in &mut missiles {
         let Some(aim) = aim_point(missile.aim, &units, &joints) else {
-            // The target streamed out mid-flight. The reference routes this to `0x61d870` (the
-            // no-live-target arm), which plays on the CASTER and still floats a word per guid
-            // from the missile's own list — the eighth `0x607140` call site, `0x61d9dc`. Ours
-            // just ends the flight silently: a named divergence, and the only word path decision
-            // 2229 left unbuilt. A ground shot has no target to lose.
+            // A unit target streamed out mid-flight: the reference's `0x61d870` plays on the
+            // caster and floats a word per guid from the missile's list (`0x61d9dc`, calling
+            // `0x607140`); not built, the flight ends silently.
             sounds.write(MissileSound::Stop { entity });
             commands.entity(entity).despawn();
             continue;
@@ -828,11 +678,8 @@ pub(super) fn move_missiles(
     }
 }
 
-/// Headless tests for the **pending queue** (module docs): park on a deferred GO, drain on the
-/// release keyframe from the fired marker, subtract the queued time from the flight, impact on
-/// the spot past the deadline, flush a never-played one-shot. The anim-end flush edge
-/// (`saw_oneshot` set, then the one-shot finishing) needs a live driver rig — that path rides the
-/// director's live NPC-caster runs instead.
+/// The pending queue, headless; the anim-end flush edge needs a live animation rig and is not
+/// covered here.
 #[cfg(test)]
 mod tests {
     use std::collections::HashMap;
@@ -871,8 +718,7 @@ mod tests {
         app.update();
     }
 
-    /// A caster whose `$CSL` marker sits at `hand` (the release launch point) — bone 0 of its
-    /// pose is seated there, and the read computes through `posed_point` (decision 1355).
+    /// A caster whose `$CSL` marker, on bone 0 of its pose, sits at `hand`.
     fn caster(app: &mut App, hand: Vec3) -> Entity {
         let caster = app
             .world_mut()
@@ -893,7 +739,7 @@ mod tests {
         MissileSpawn {
             caster,
             spell_id: 133,
-            path: None, // an invisible flight — the queue mechanics under test don't need a model
+            path: None, // an invisible flight; the queue needs no model
             ammo_display_id: None,
             dest_tag: None,
             speed: SPEED,
@@ -922,8 +768,6 @@ mod tests {
             .collect()
     }
 
-    /// A deferred GO parks; the `$CSL` keyframe drains it from the marker's live position, with
-    /// the time spent queued already subtracted from the flight (the client's `0x61ceb0`).
     #[test]
     fn release_keyframe_launches_from_the_marker_minus_queued_time() {
         let mut app = app();
@@ -957,8 +801,6 @@ mod tests {
         );
     }
 
-    /// A release already past its arrival deadline (melee range) spawns no flight at all — the
-    /// impact plays on the spot, the reference's close-range look.
     #[test]
     fn release_past_deadline_impacts_on_the_spot() {
         let mut app = app();
@@ -991,9 +833,7 @@ mod tests {
         assert_eq!(impacts[0].spell_id, 133);
     }
 
-    /// The location fallback (`0x6e8a50`'s empty-hit-array arm): a GO with no unit targets and a
-    /// point on the wire flies **exactly one** projectile, at the point — a pure ground cast's
-    /// whole visible flight, which before this had none at all.
+    /// The location fallback (`0x6e8a50`'s empty-hit-array arm) flies exactly one projectile.
     #[test]
     fn a_targetless_dest_go_flies_one_projectile_at_the_point() {
         let mut app = app();
@@ -1020,9 +860,7 @@ mod tests {
         assert_eq!(ground, 1, "aimed at the point, homing to nothing");
     }
 
-    /// The hit array wins: the client consults the location latch only after finding the array
-    /// empty (`0x6e8abc … je 0x6e8ba2`), so a dest-carrying GO that *did* hit units flies at the
-    /// units — never an extra shot at the ground.
+    /// The reference reads the location latch only for an empty hit array (`0x6e8abc`).
     #[test]
     fn a_dest_go_that_hit_units_flies_at_the_units_not_the_point() {
         let mut app = app();
@@ -1044,9 +882,7 @@ mod tests {
         assert_eq!(aims, vec![true], "one unit-homing shot, no ground shot");
     }
 
-    /// A ground arrival hands off as [`CastEventKind::GroundImpact`] on the **caster**, carrying
-    /// the landing point — the client's `0x61e1d0` ground arm (`0x61d870`), whose kit plays on the
-    /// caster with `extra` = that position. Never the unit impact hand-off.
+    /// `0x61d870` plays the kit on the caster with `extra` = the landing point.
     #[test]
     fn a_ground_arrival_hands_off_to_the_caster_with_the_landing_point() {
         let mut app = app();
@@ -1081,8 +917,6 @@ mod tests {
         );
     }
 
-    /// A one-shot that never starts (the kit anim didn't resolve on this model) flushes after
-    /// [`RELEASE_WAIT_MAX`] through the marker cascade instead of hanging forever.
     #[test]
     fn never_played_oneshot_flushes_after_the_wait_window() {
         let mut app = app();
@@ -1106,18 +940,9 @@ mod tests {
         );
     }
 
-    /// A missed target's arrival plays the victim's defense clip, not the impact (the
-    /// `0x61dd50` arm of `0x61e1d0`'s dispatch): DODGE(3) → the dodge state, BLOCK(5) → the
-    /// block state, a plain MISS(1) → nothing — and PARRY(4) → nothing.
-    ///
-    /// It also floats the outcome WORD (decision 2229), and two of its legs are only visible
-    /// here:
-    /// - **PARRY is gone by arrival.** [`launch_outcome_code`] rewrote it to DEFLECT(9) at
-    ///   launch (`0x61d756`), so the word reads "Deflect" — which is *why* no parry clip plays,
-    ///   rather than a separate rule that suppresses one.
-    /// - **REFLECT floats over the TARGET**, not the caster. The inline site re-anchors a
-    ///   reflect (`0x6e7e51`); this one does not — `0x61dd50` words the target and then
-    ///   re-launches at the caster, and the caster's word belongs to that second flight.
+    /// The `0x61dd50` arm: a miss plays the victim's dodge or block clip, never the impact, and
+    /// floats its word over the target. A parry reads Deflect, rewritten at launch; a Reflect
+    /// floats over the target, where the inline site re-anchors it to the caster (`0x6e7e51`).
     #[test]
     fn missed_arrival_words_the_target_deflects_a_parry_and_plays_dodge_or_block() {
         for (code, expect_state, expect_word) in [
@@ -1190,8 +1015,7 @@ mod tests {
         }
     }
 
-    /// A GO whose cast kit plays no body animation launches the frame it arrives (the client's
-    /// `0x6e7a70` flush), from the marker cascade, full flight time.
+    /// A GO with no cast-kit animation launches at once (`0x6e7a70`), with the full flight time.
     #[test]
     fn immediate_go_launches_at_once() {
         let mut app = app();
diff --git a/crates/benilla-app/src/entities/mount.rs b/crates/benilla-app/src/entities/mount.rs
index 9355e936..b016f0a9 100644
--- a/crates/benilla-app/src/entities/mount.rs
+++ b/crates/benilla-app/src/entities/mount.rs
@@ -1,40 +1,15 @@
-//! Mounts (decisions 0441 / this session's re-seat): the projection from
-//! `UNIT_FIELD_MOUNTDISPLAYID` — the wire's one mounted signal — to a second creature visual under
-//! the unit. The mount is a child entity carrying a plain creature `NetEntity`, built by the
-//! ordinary attach path; the rider's rig re-roots under the mount's attachment-0 seat joint (the
-//! `0x60ce70` present-test law); the rider's base pins to Mount(91) while the mount child
-//! locomotes through the untouched gait driver, fed the host's own movement view
-//! ([`crate::creature_anim`]'s host-view redirect). This module owns the transition.
+//! Mounts: `UNIT_FIELD_MOUNTDISPLAYID` drawn as a second creature visual, a child entity with its
+//! own `NetEntity` built by the ordinary attach path. The rider's rig roots under the mount's
+//! attachment-0 seat (`0x60ce70`) and holds Mount (91), while the mount child walks on the host's
+//! movement ([`crate::creature_anim`]).
 //!
-//! ## The transition is a RE-SEAT, not a rebuild (B199)
-//!
-//! 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 (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.
-//!
-//! benilla used to answer the same field change with a **full teardown** of the rider's visual
-//! (`despawn_related::<Children>()` + a strip of the rig, the player, the driver, the attach table)
-//! and let `attach_entity_visuals` rebuild it — the shape 0835 removed from gear changes for the
-//! same reason it is wrong here. Everything hanging off the rider died with it, and the one class
-//! that never came back was the **persistent aura kit instance**: `FxAttached` lives on the *unit*,
-//! survived the teardown holding a dangling root, and `attach_spell_fx`'s spawn gate is
-//! `root.is_some()` — so a mage's Ice Barrier glow was destroyed on mount-up and never re-attached,
-//! not even on dismount (the aura watcher is edge-driven off the slot set, and the aura never left
-//! it). That is B199, and 0835 named exactly this teardown as the surviving source.
-//!
-//! So the transition now moves the rig's **consumer anchors** — the only children the rig's model
-//! frame owns (decision 0724) — from the unit's own frame onto the seat anchor and back, and
-//! re-points [`RigPose::joints_root`]. Skinned parts render purely from the palette and never move;
-//! held items, spell-effect instances and overhead riders hang off the anchors and ride along, so
-//! nothing on the rider is destroyed, re-created, re-composited or re-faded by mounting.
+//! The change handler `0x5ffa50` tears the old seat down, then builds the new, and neither half
+//! touches the rider's model. Mounting (`0x607a00`) sets the mount model (`0x613d80`, into
+//! `CGUnit+0xdc`) and re-parents the body onto its attachment 0 (`0x712f70`), recomposed each frame
+//! from that live bone (`0x718657`..`0x71876f`); dismounting (`0x607ce0`) detaches the body
+//! (`0x713020`), destroys the mount model and stands the body, instantly. Here the rig's consumer
+//! anchors move between the unit's frame and the seat, re-pointing [`RigPose::joints_root`], so
+//! nothing that rides the rider is rebuilt.
 
 use benilla_protocol::EntityKind;
 use bevy::prelude::*;
@@ -42,13 +17,10 @@ use bevy::prelude::*;
 use crate::net::{NetEntity, ObjectStore};
 use benilla_world::rig_anim::RigPose;
 
-/// The mount child — the second creature visual a mounted unit carries (the client's
-/// `unit+0xdc` secondary model instance). Spawned by [`seat_or_spawn_mount`] (from the first
-/// build or from a transition), despawned by the dismount leg or with its parent.
+/// The mount child, the client's `unit+0xdc` second model.
 #[derive(Component)]
 pub(crate) struct MountBody {
-    /// The mounted unit — the streamed entity whose field this child projects. The animation
-    /// driver reads the HOST's movement view through this to locomote the mount.
+    /// The mounted unit, whose movement the animation driver reads to walk the mount.
     pub(crate) host: Entity,
 }
 
@@ -56,21 +28,16 @@ pub(crate) struct MountBody {
 #[derive(Component)]
 pub(crate) struct MountChild(pub(crate) Entity);
 
-/// On the unit: the mount display id its rig is currently **seated on** (`0` = standing on its own
-/// frame) — [`reseat_mounts`]' diff key, the `AppliedEquipment` pattern. Distinct from the live
-/// field while a transition waits on the mount model to load.
+/// On the unit: the mount display its rig is seated on (`0` standing), [`reseat_mounts`]' diff
+/// key; it lags the field while a mount model loads.
 #[derive(Component)]
 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, `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
-/// a mount cast should look like — the horse is *there* the instant the cast lands, not ramped in
-/// over the streaming fade meant for units coming into view.
+/// Spawn a unit's mount child (the client's `0x607a00` model creation), built as an ordinary
+/// creature. `scale` is the `CreatureDisplayInfo.creatureModelScale` column alone (`0x607a75`), as
+/// the unit's `SCALE_X` composes through the hierarchy. `fade_skip` drops the streaming fade, so a
+/// cast mount is there at once: our choice, as whether the reference fades a new mount in is
+/// untraced.
 pub(super) fn spawn_mount_child(
     commands: &mut Commands,
     host: Entity,
@@ -98,13 +65,9 @@ pub(super) fn spawn_mount_child(
     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 (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).
+/// The seat anchor, the rider's model frame while mounted: under the mount's attachment-0 joint,
+/// counter-scaled so the rider keeps its size (`0x607b49`, `0x710620`), and a
+/// [`benilla_world::rig_anim::RigFrame`] so a re-seat cascades into the rider's palette.
 fn spawn_seat_anchor(
     commands: &mut Commands,
     joint: Entity,
@@ -124,23 +87,17 @@ fn spawn_seat_anchor(
     anchor
 }
 
-/// The seat leg shared by the first build and the transition: given a unit whose mount field says
-/// `display`, make sure the mount child exists and — once it has attached — return the frame the
-/// rider's rig should root under.
-///
-/// Three outcomes, and the caller acts on each: [`Seat::Wait`] (the mount model is still
-/// building — nothing to do this frame), [`Seat::Frame`] (seat it here) and [`Seat::UnitMatrix`]
-/// (the mount authors no attachment 0 — the reference logs and leaves the body at the unit matrix,
-/// `0x60ce70`'s present-test miss).
+/// Where the seat leg leaves the rider: [`Seat::Wait`] while the mount model builds,
+/// [`Seat::Frame`] to root there, or [`Seat::UnitMatrix`] when the mount authors no attachment 0
+/// and the reference leaves the body at the unit matrix (`0x60ce70`'s miss).
 pub(super) enum Seat {
     Wait,
     Frame(Entity),
     UnitMatrix,
 }
 
-/// The mount children's build state a [`seat_or_spawn_mount`] caller reads: attached yet, its
-/// anchors, and the display it was actually built with (the staleness check — the field can move
-/// again while the model loads).
+/// The mount children's build state: attached yet, its anchors, and the display it was built
+/// with, which the field can move off while the model loads.
 pub(super) type MountChildren<'w, 's> = Query<
     'w,
     's,
@@ -152,9 +109,8 @@ pub(super) type MountChildren<'w, 's> = Query<
     With<MountBody>,
 >;
 
-/// Drive one unit's mount side to the point where the rider can be seated. Spawns the child when
-/// it is missing, drops and retries a child built for a display the field has since moved off, and
-/// resolves the seat frame once the child's rig is up.
+/// The seat leg of the first build and the transition: spawn the mount child when missing, drop
+/// one built for a display the field has left, and resolve the seat once its rig is up.
 pub(super) fn seat_or_spawn_mount(
     commands: &mut Commands,
     children: &MountChildren,
@@ -165,9 +121,7 @@ pub(super) fn seat_or_spawn_mount(
     mount_display: u32,
     fade_skip: bool,
 ) -> Seat {
-    // The mount scale law (`0x607a75`): rendered =
-    // `SCALE_X × CreatureDisplayInfo.creatureModelScale` — the CDI column ALONE (no
-    // CreatureModelData.modelScale).
+    // `0x607a75`: `SCALE_X` × `creatureModelScale` alone, without `CreatureModelData.modelScale`.
     let mount_scale = creatures
         .and_then(|c| c.catalog.display_scale(mount_display))
         .unwrap_or(1.0);
@@ -175,8 +129,7 @@ pub(super) fn seat_or_spawn_mount(
         spawn_mount_child(commands, unit, mount_display, mount_scale, fade_skip);
         return Seat::Wait;
     };
-    // A child built for a display the field has since moved off (or one that is simply gone):
-    // drop it and let the next pass start over.
+    // Built for a display the field has left, or gone: drop it and start over next pass.
     let built = children.get(child).map(|(_, _, n)| n.display_id).ok();
     if built != Some(Some(mount_display)) {
         if let Ok(mut ec) = commands.get_entity(child) {
@@ -188,9 +141,8 @@ pub(super) fn seat_or_spawn_mount(
     let Ok((true, Some(bones), _)) = children.get(child) else {
         return Seat::Wait; // the mount child is still building
     };
-    // The mount's attachment-0 joint, spawned on first demand from the MOUNT's composed pose
-    // (`RigPose::anchor_for`, decision 1355) — registered into the mount's own `RigPose.anchors`,
-    // which is what lets the world pass's patch walk find the seat subtree and cascade the rider.
+    // The mount's attachment-0 joint, made on demand in the mount's own `RigPose.anchors`, where
+    // the world pass's patch walk finds the seat and cascades the rider.
     let Some((joint, offset)) = bones.points.get(&0).and_then(|&(bone, offset)| {
         poses
             .get_mut(child)
@@ -213,10 +165,9 @@ pub(super) fn seat_or_spawn_mount(
     ))
 }
 
-/// The rider's **ground** frame: its own entity, or — for a model the reference tilts to the
-/// terrain (`GlobalModelFlags & 3 ∈ {1,3}`, decisions 0482/0486) — a fresh conform node under it.
-/// The mounted rider never gets one: the tilt dispatch is on the mount-preferred model, and the
-/// composite tilts through the *mount's* node, seat joint included.
+/// The rider's ground frame: its own entity, or a fresh conform node under it for a model the
+/// reference tilts to the terrain (`GlobalModelFlags & 3` of 1 or 3). Mounted, the composite
+/// tilts through the mount's node instead.
 fn ground_frame(
     commands: &mut Commands,
     unit: Entity,
@@ -241,13 +192,9 @@ fn ground_frame(
     node
 }
 
-/// Move a rig's consumer anchors onto `frame` and make it the rig's model frame — the ECS twin of
-/// `0x712f70 CM2Model::attachChild` / `0x713020`'s detach. The anchors are the only children the
-/// frame owns (decision 0724: skinned parts render from the palette and hang off the unit), so
-/// this one re-parent carries every held item, spell-effect instance and overhead rider with it.
-///
-/// `pose_dirty` is raised so the same frame's compose re-seats the anchors' locals and re-writes
-/// the palette against the new root, rather than waiting for the next pose change.
+/// Move a rig's consumer anchors onto `frame` and make it the model frame, as `0x712f70` attaches
+/// and `0x713020` detaches; the anchors carry every held item, effect and overhead rider.
+/// `pose_dirty` re-seats them and the palette in the same frame's compose.
 fn reseat_rig(commands: &mut Commands, rig: &mut RigPose, frame: Entity, conform: bool) {
     if rig.joints_root == frame {
         return;
@@ -258,9 +205,7 @@ fn reseat_rig(commands: &mut Commands, rig: &mut RigPose, frame: Entity, conform
     }
     let old = std::mem::replace(&mut rig.joints_root, frame);
     rig.pose_dirty = true;
-    // A conform node the rig has just left has nothing under it any more — it belongs to the
-    // frame, not to the visual, so it goes with it. (A seat anchor needs no such sweep: it dies
-    // with the mount child that carries it.)
+    // A conform node the rig just left is empty, so it goes; a seat anchor dies with its mount.
     if conform {
         if let Ok(mut ec) = commands.get_entity(old) {
             ec.despawn();
@@ -268,14 +213,9 @@ fn reseat_rig(commands: &mut Commands, rig: &mut RigPose, frame: Entity, conform
     }
 }
 
-/// Re-seat a unit's rig when its mount field changes — the client's `0x5ffa50` change handler:
-/// **tear the old seat down, then build the new one**, with the rider's own visual untouched
-/// throughout (module docs).
-///
-/// The two legs are separate frames on purpose, exactly as they are separate calls there: a
-/// re-mount (id→id′) detaches onto the ground frame first, and the build leg then waits however
-/// many frames the new mount model needs to load. A rider mid-transition therefore stands on its
-/// own feet rather than vanishing — the teardown era rendered *nothing at all* for that window.
+/// Re-seat a unit's rig when its mount field changes, the client's `0x5ffa50`: tear the old seat
+/// down, then build the new, with the rider's own visual untouched. The legs run in separate
+/// frames, so a remount stands the rider on its feet while the new mount model loads.
 #[allow(clippy::type_complexity)]
 pub(super) fn reseat_mounts(
     mut commands: Commands,
@@ -289,10 +229,7 @@ pub(super) fn reseat_mounts(
         ),
         With<super::VisualAttached>,
     >,
-    // One pose query for BOTH sides of the seat — the rider's rig (re-rooted onto the seat) and
-    // the mount's (its attachment-0 anchor resolves on demand, decision 1355). Split from the
-    // `units` query because the two sides are different entities out of the same component, and
-    // borrowed strictly in sequence below.
+    // One pose query for both sides, the rider's rig and the mount's, borrowed in sequence below.
     mut poses: Query<&mut RigPose>,
     children: MountChildren,
     conforms: Query<(), With<super::conform::ConformNode>>,
@@ -304,18 +241,14 @@ pub(super) fn reseat_mounts(
         }
         let live = store.0.unit_mount_display_id();
         let applied = applied.map_or(0, |a| a.0);
-        // Settled: seated on what the field says — and, when the field says nothing, holding no
-        // mount model either. The second clause is not redundant: a mount-up whose field zeroes
-        // again *before* the model finishes loading leaves an ordered-but-unseated child behind
-        // (`applied` never left 0), and without it that horse would stand under a dismounted
-        // rider for the rest of the unit's life.
+        // Settled: seated on what the field says, and holding no mount model when it says none.
+        // A mount-up whose field zeroes before the model loads leaves an unseated child (`applied`
+        // never left 0), which would otherwise stand under the dismounted rider for good.
         if live == applied && (live != 0 || child.is_none()) {
             continue;
         }
-        // A model-less unit (the cube fallback) has no rig to seat, and the build path never
-        // orders it a mount — stamp the field so it can never churn, exactly as the first build
-        // does, and sweep a child if one ever did reach it (the stamp alone would then re-fire
-        // every frame, since the settled test asks about the child too).
+        // A model-less unit (the cube) has no rig to seat: stamp the field so it never churns, and
+        // sweep any child, which the settled test would otherwise re-fire on every frame.
         let Ok(seated_root) = poses.get(entity).map(|r| r.joints_root) else {
             if let Some(&MountChild(child)) = child {
                 if let Ok(mut ec) = commands.get_entity(child) {
@@ -327,16 +260,12 @@ pub(super) fn reseat_mounts(
             continue;
         };
         let child = child.map(|&MountChild(c)| c);
-        // ── Leg 1 · `0x607ce0` — detach the body onto its own frame, destroy the mount model.
-        // It runs when we are seated on a mount the field has moved off, and when the field says
-        // "not mounted" at all (which covers the pending-child case above). A unit merely *waiting*
-        // for its first mount model must not take it, or the build leg would tear down the child
-        // it just ordered, every frame, for ever.
+        // ── Leg 1 · `0x607ce0`: detach the body onto its own frame, destroy the mount model.
+        // Taken when seated on a mount the field left or when the field says none; a unit waiting
+        // on its first mount model must not take it, or it would tear down its own order.
         if applied != 0 || live == 0 {
-            // Only a body that is actually ON a seat needs detaching: a rig already standing —
-            // on its own entity, or on the conform node that tilts it — is where it belongs, and
-            // asking for a ground frame anyway would orphan a second conform node beside the
-            // first.
+            // Only a body on a seat detaches: a rig on its own entity or its conform node stays,
+            // or a second conform node would be orphaned beside the first.
             if seated_root != entity && !conforms.contains(seated_root) {
                 let ground = ground_frame(&mut commands, entity, net, creatures.as_deref());
                 if let Ok(mut rig) = poses.get_mut(entity) {
@@ -354,7 +283,7 @@ pub(super) fn reseat_mounts(
                 .insert(AppliedMount(0));
             continue;
         }
-        // ── Leg 2 · `0x607a00` — build the mount model and attach the body to its seat.
+        // ── Leg 2 · `0x607a00`: build the mount model and attach the body to its seat.
         match seat_or_spawn_mount(
             &mut commands,
             &children,
diff --git a/crates/benilla-app/src/entities/mount/tests.rs b/crates/benilla-app/src/entities/mount/tests.rs
index fe6c1ffa..0a3bfdf5 100644
--- a/crates/benilla-app/src/entities/mount/tests.rs
+++ b/crates/benilla-app/src/entities/mount/tests.rs
@@ -1,12 +1,5 @@
-//! The mount transition's law: **nothing on the rider is destroyed by mounting**.
-//!
-//! 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
-//! bone anchor — a held item and a spell-effect instance root — and assert they are the same
-//! entities on the far side of a mount, a dismount and a re-mount.
+//! The mount transition re-seats the rider and destroys nothing on it: the held item and the aura
+//! glow hung off its bone anchor stay the same entities through a mount, a dismount and a re-mount.
 
 use super::*;
 use benilla_assets::{ModelJoint, ModelSkeleton};
@@ -15,20 +8,17 @@ use benilla_protocol::ObjectFields;
 use crate::entities::{BoneAttach, VisualAttached};
 use crate::net::ObjectStore;
 
-/// `UNIT_FIELD_MOUNTDISPLAYID` (index 133, decision 0441) — the wire's one mounted signal.
+/// `UNIT_FIELD_MOUNTDISPLAYID` (index 133), the wire's one mounted signal.
 const FIELD_MOUNTDISPLAYID: u16 = 133;
 /// The mount's attachment-0 bone in the fixture mount rig.
 const SEAT_BONE: u16 = 3;
 
-/// A rider standing on its own feet, wearing everything a mount transition used to destroy: one
-/// consumer anchor (the rig's only child), a held item under it, and a persistent spell-effect
-/// instance root under it — the Ice Barrier glow, in the shape `attach_spell_fx` builds.
+/// A standing rider: one consumer anchor (the rig's only child) with a held item and a persistent
+/// spell-effect root under it, in the shape `attach_spell_fx` builds.
 struct Standing {
     app: App,
     rider: Entity,
-    /// The rig's consumer anchor — the entity every attachment hangs from.
     anchor: Entity,
-    /// The held weapon root and the aura glow root, both under `anchor`.
     held: Entity,
     glow: Entity,
 }
@@ -49,7 +39,6 @@ fn rig_at(frame: Entity, anchor: Entity) -> RigPose {
     rig
 }
 
-/// The descriptor store for a unit whose mount field reads `display`.
 fn mounted_on(display: u32) -> ObjectStore {
     ObjectStore(ObjectFields::from_pairs(&[(FIELD_MOUNTDISPLAYID, display)]))
 }
@@ -98,7 +87,6 @@ fn stand() -> Standing {
 }
 
 impl Standing {
-    /// Move the wire field and run one pass.
     fn field(&mut self, display: u32) {
         self.app
             .world_mut()
@@ -107,12 +95,11 @@ impl Standing {
         self.app.update();
     }
 
-    /// Finish the mount child's build the way `attach_entity_visuals` would: mark it attached and
-    /// give it the attachment-0 anchor the seat hangs from. Returns the child.
+    /// Finish the mount child's build as `attach_entity_visuals` would: attached, with the
+    /// attachment-0 point the seat hangs from.
     fn mount_attaches(&mut self) -> Entity {
         let child = self.mount_child().expect("a mount child was ordered");
-        // The seat joint spawns on first demand out of the mount's pose (decision 1355) — the
-        // test provides the pose, not a hand-built joint.
+        // The seat joint spawns on demand from the mount's pose, so the test gives only the pose.
         let pose =
             benilla_world::testing::test_rig_pose(child, &[Vec3::ZERO; SEAT_BONE as usize + 1]);
         self.app.world_mut().entity_mut(child).insert((
@@ -135,7 +122,6 @@ impl Standing {
             .map(|c| c.0)
     }
 
-    /// The rig's current model frame.
     fn frame(&self) -> Entity {
         self.app
             .world()
@@ -157,7 +143,6 @@ impl Standing {
             .map_or(0, |a| a.0)
     }
 
-    /// Everything that must survive every transition, by entity id.
     fn attachments_alive(&self) -> bool {
         let w = self.app.world();
         w.get_entity(self.anchor).is_ok()
@@ -166,12 +151,8 @@ impl Standing {
     }
 }
 
-/// **The director's report (B199).** Mounting used to destroy the rider's whole visual, taking the
-/// aura's persistent kit instance with it — and because `FxAttached` outlived the teardown holding
-/// a dangling root while the aura never left its slots, the glow never came back, not even after
-/// dismounting. The reference re-parents the body model onto the mount (`0x712f70`); it never
-/// re-creates it. So: the same anchor, the same held item, the same glow root — now hanging under
-/// the mount's seat.
+/// The reference re-parents the body model onto the mount (`0x712f70`) and never re-creates it:
+/// the same anchor, held item and glow root, now under the mount's seat.
 #[test]
 fn mounting_re_seats_the_rig_and_destroys_nothing_on_the_rider() {
     let mut s = stand();
@@ -200,9 +181,7 @@ fn mounting_re_seats_the_rig_and_destroys_nothing_on_the_rider() {
     );
 }
 
-/// The dismount half — `0x607ce0`: detach the body back onto its own frame, destroy the mount
-/// model. The rider is again the rig's root, the mount child and its seat are gone, and the glow
-/// the report says never returns is the same entity it always was.
+/// Dismount (`0x607ce0`) detaches the body onto its own frame and destroys the mount model.
 #[test]
 fn dismounting_puts_the_rig_back_on_its_own_frame_and_keeps_the_glow() {
     let mut s = stand();
@@ -225,9 +204,7 @@ fn dismounting_puts_the_rig_back_on_its_own_frame_and_keeps_the_glow() {
     assert!(s.attachments_alive(), "the rider's own visual is untouched");
 }
 
-/// A re-mount (id→id′) is `0x5ffa50`'s two calls in order: tear the old seat down first, then
-/// build the new one. The old mount dies, the new one is ordered, and the rider — which is not
-/// part of either half — never notices.
+/// A re-mount is `0x5ffa50`'s two calls in order: tear the old seat down, then build the new one.
 #[test]
 fn a_re_mount_tears_the_old_seat_down_before_it_builds_the_new_one() {
     let mut s = stand();
@@ -249,9 +226,8 @@ fn a_re_mount_tears_the_old_seat_down_before_it_builds_the_new_one() {
     assert!(s.attachments_alive());
 }
 
-/// The field can also zero again mid-load — a cast that lands and is cancelled inside the model
-/// load. `AppliedMount` never left 0, so the diff must key on the *ordered* mount too, or the
-/// horse arrives riderless and stays for the unit's life.
+/// A field that zeroes mid-load leaves `AppliedMount` at 0, so the diff also keys on the ordered
+/// mount; otherwise the horse arrives riderless and stays for the unit's life.
 #[test]
 fn a_mount_ordered_and_then_cancelled_mid_load_is_dropped() {
     let mut s = stand();
@@ -268,9 +244,6 @@ fn a_mount_ordered_and_then_cancelled_mid_load_is_dropped() {
     assert!(s.mount_child().is_none(), "and it stays gone — no churn");
 }
 
-/// The field can move again while the mount model is still loading. The pending child is dropped
-/// for one built with the display the field actually says, and the rider — which was never torn
-/// down to begin with — just keeps standing.
 #[test]
 fn a_field_that_moves_mid_load_drops_the_pending_mount() {
     let mut s = stand();
@@ -294,9 +267,8 @@ fn a_field_that_moves_mid_load_drops_the_pending_mount() {
     );
 }
 
-/// A mount that authors no attachment 0 is the reference's `0x60ce70` present-test miss: it logs
-/// and leaves the body at the unit matrix — mounted, but unseated. It must not spin (the field is
-/// stamped) and it must not tear the rider down either.
+/// A mount with no attachment 0 fails `0x60ce70`'s present test: the reference logs and leaves the
+/// body at the unit matrix. The field is still stamped, so the diff cannot churn.
 #[test]
 fn a_mount_without_a_seat_leaves_the_body_at_the_unit_matrix() {
     let mut s = stand();
diff --git a/crates/benilla-app/src/entities/spell_fx/lifecycle.rs b/crates/benilla-app/src/entities/spell_fx/lifecycle.rs
index 430de0c0..27bf6361 100644
--- a/crates/benilla-app/src/entities/spell_fx/lifecycle.rs
+++ b/crates/benilla-app/src/entities/spell_fx/lifecycle.rs
@@ -1,57 +1,15 @@
-//! 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. 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 effect-model animation lifecycle, `Stand` → `Hold` → `Decay`, of a spell-visual `CEffect`.
 //!
-//! ## The mechanism
+//! The model-load bootstrap (`0x710153`–`0x71019b`) arms `AnimationData.dbc` id 0 `Stand`, not the
+//! file-order-first sequence. At each span's end the scene tick runs the model's completion
+//! callback with the completed id (`0x719370`, `0x707595`), picked per [`FxStage`] by
+//! `PlaySpellVisualKit 0x60edf0`: stages 0/1 destroy (`0x5fbf50`), which the span clock in
+//! [`super::attach_spell_fx`] models; stage 2 hands over to `Hold` if the model authors it, else
+//! stays on the birth (`0x5ff170`); stages 3/4 re-arm the completed id forever (`0x60ed00`). The
+//! reap plays `Decay` out (`0x614150`); the destructor `0x6203e0` plays nothing.
 //!
-//! A `CEffect`'s model is armed **by `AnimationData.dbc` id, never by file order**. The model-load
-//! bootstrap (`0x710153`–`0x71019b`) arms **id 0 `Stand`, variation 0** — the *birth*
-//! ([`benilla_assets::ModelAnimations::preferred_clip`] is that resolve). When the armed sequence's
-//! authored span elapses, the CM2 Advance `0x719370` latches once (`block+0xc0`) and enqueues the
-//! model's registered completion callback; the scene tick drains it at `0x707595` at the **end of
-//! the same tick**, passing **the id that just completed** as its first argument. `Which` callback
-//! is registered is chosen by `PlaySpellVisualKit 0x60edf0` **per stage** — that table is
-//! [`FxStage`], and this module is its three arms:
-//!
-//! - **[`FxStage::OneShot`]** (stages 0/1, `0x5fbf50`) — destroy at the first completion. Modelled
-//!   by the instance's own span clock in [`super::attach_spell_fx`], so nothing here watches it.
-//! - **[`FxStage::State`]** (stage 2, `0x5ff170`) — iff the model authors **`Hold` (158)**, arm it
-//!   and keep it running for the effect's whole life; if it does not, do **nothing at all** (no
-//!   destroy, no re-loop — the model simply stays parked on its birth sequence). The reference's
-//!   "keep running" is a literal re-arm every span by `0x5ff1d0`, gated on a deadline at
-//!   `node+0x58` that is **nonzero only at stage 3** — so for an aura state or a channel it never
-//!   fires and Hold repeats forever. **This is Ice Barrier's pulse.**
-//! - **[`FxStage::Relive`]** (stages 3/4, `0x60ed00`) — re-arm **the id that just completed**,
-//!   forever, with no `Hold` lookup, no deadline and no destroy. A precast whose birth sequence
-//!   clamps therefore still repeats it.
-//!
-//! 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).
-//!
-//! ## What this replaces, and how wrong it was
-//!
-//! Every effect instance used to arm **one** clip for its whole life — the model's *file-order-first*
-//! sequence, repeated only if that sequence's own loop flag was clear. For `Spells\IceShield_State`
-//! (Ice Barrier's state kit) that is the 0.70 s clamping birth, so the shield grew in and then held
-//! its last frame for the aura's entire duration. `benilla-extract fxlifescan` sizes the class:
-//! **163 of 9691 models author a `Hold`/`Decay` leg** (158 of them under `Spells\`), **116 of which
-//! froze** exactly this way — Mana Shield, Lightning Shield, Divine Shield, Frost Nova, the Fire and
-//! Frost Wards, Immolate, Net, the healing auras.
-//!
-//! ## Named divergences
-//!
-//! - The reference re-arms `Hold` with variation `-1` (a `_rand`-weighted walk of the alias chain),
-//!   so a model authoring several `Hold` variations could pick a different one each pass. We run one
-//!   repeating play instead. Corpus: of the 692 `Spells\` models, 507 have a single sequence, 119
-//!   two, 65 three and **one** has four or more — so a multi-variation `Hold` is at most that single
-//!   model, and it is not worth a per-pass re-roll's complexity until one shows.
-//! - A **ribbon**'s per-sequence visibility is still decided once at spawn ([`benilla_world::ribbons`],
-//!   which spawns per fixed-sequence entity). A trail authored dark in `Stand` and lit in `Hold`
-//!   would stay dark. Left as a residual: the ribbon lane's own spawn shape has to change for it,
-//!   and no reported effect turns on it.
+//! Deviation: `Hold` is one repeating play where the reference re-arms it each pass with variation
+//! -1, a weighted random pick, because at most one `Spells\` model authors several variations.
 
 use benilla_assets::ModelAnimations;
 use bevy::animation::{graph::AnimationNodeIndex, RepeatAnimation};
@@ -59,39 +17,26 @@ use bevy::prelude::*;
 
 use crate::creature_anim::FxStage;
 
-/// `AnimationData.dbc` **158 `Hold`** — the sustained pulse leg (`0x9e` at `0x5ff188`/`0x5ff1bb`).
+/// `AnimationData.dbc` 158 `Hold`, the sustained pulse leg (`0x9e` at `0x5ff188`/`0x5ff1bb`).
 pub(crate) const ANIM_HOLD: u16 = 158;
-/// `AnimationData.dbc` **159 `Decay`** — the fade-out leg (`0x9f` at `0x5ff233`/`0x6141c0`).
+/// `AnimationData.dbc` 159 `Decay`, the fade-out leg (`0x9f` at `0x5ff233`/`0x6141c0`).
 pub(crate) const ANIM_DECAY: u16 = 159;
 
-/// The completion callback one effect-model instance carries — the ECS twin of the `model+0x70`
-/// registration `0x711bb0` writes, and of the callback *swap* `0x5ff170` performs when it hands the
-/// birth over to `Hold`.
-///
-/// Present on every kit-effect instance root that armed a rig, whatever its stage: the reap
-/// ([`arm_decay`]) needs a handle on the player of an instance whose lifecycle is otherwise
-/// finished. A missile, an item glow or the `fxview` fixture arms none — they are not `CEffect`s
-/// (the missile is the separate `CMissile` TU) and keep the plain single-clip arm.
+/// The completion callback an effect instance carries (the `model+0x70` registration `0x711bb0`
+/// writes). On every kit-effect root that armed a rig, since the reap needs its player; a missile,
+/// an item glow or the `fxview` fixture is not a `CEffect` and carries none.
 #[derive(Component)]
 pub(crate) enum FxAnimLife {
-    /// Stage 2's birth, waiting to hand over — `0x5ff170` is the only callback that watches for a
-    /// completion and then does something *other* than re-arm or destroy.
+    /// Stage 2's birth, waiting for `0x5ff170`'s handover to `Hold`.
     Birth(AnimationNodeIndex),
-    /// Nothing left to advance: the birth handed over to `Hold` (whose "re-arm every span" is the
-    /// repeating play), or this stage never had a handover at all — `0x5fbf50`'s destroy is the
-    /// instance's own span clock, and `0x60ed00`'s re-arm-forever is the repeat armed below. The
-    /// node is still carried so a reap can stop it before arming `Decay`.
+    /// Nothing left to advance; the node is kept so a reap can stop it before arming `Decay`.
     Settled(AnimationNodeIndex),
 }
 
 impl FxAnimLife {
-    /// Arm `clip` on `player` for `stage` and return the watcher that finishes the job.
-    ///
-    /// The repeat policy is the stage's, not the sequence flag's alone: a [`FxStage::Relive`]
-    /// instance re-arms unconditionally (`0x60ed00` consults no flag, so a clamping precast still
-    /// repeats), while the other stages play the sequence exactly as the M2 sampler would —
-    /// wrapping on a bit0-CLEAR sequence (`0x71462a`'s modulo), holding the last frame on a
-    /// bit0-SET one (`0x7145db`'s clamp).
+    /// Arm `clip` for `stage`. [`FxStage::Relive`] repeats whatever the sequence flag says
+    /// (`0x60ed00` reads none); the other stages wrap a bit-0-clear sequence (`0x71462a`) and clamp
+    /// a bit-0-set one (`0x7145db`), as the M2 sampler does.
     pub(super) fn arm(
         player: &mut AnimationPlayer,
         clip: &benilla_assets::AnimClip,
@@ -107,7 +52,6 @@ impl FxAnimLife {
         }
     }
 
-    /// The graph node currently armed.
     fn armed(&self) -> AnimationNodeIndex {
         match self {
             Self::Birth(n) | Self::Settled(n) => *n,
@@ -115,21 +59,16 @@ impl FxAnimLife {
     }
 }
 
-/// Marker: this instance has been reaped and should play its **`Decay`** out (`0x614150`'s
-/// `0x6141c0`). Written by [`super::resolve_spell_fx`], which also sets the instance's expiry to
-/// the decay span; consumed once by [`advance_fx_anim`], which arms the clip through [`arm_decay`].
+/// Marks a reaped instance that plays its `Decay` out (`0x6141c0`); its expiry is already set to
+/// the decay span.
 #[derive(Component)]
 pub(crate) struct FxDecay;
 
-/// Run the completion callbacks of every live effect instance — the birth → `Hold` handover, and
-/// the reap's `Decay` arm.
-///
-/// The reference dispatches these at the END of the tick that advanced the models (`0x707595` in
-/// the scene tick `0x7074b0`); Bevy advances `AnimationPlayer`s in `PreUpdate`, so an `Update`
-/// system reading [`bevy::animation::ActiveAnimation::completions`] fires in the same frame the
-/// span elapsed. Completion is read as `completions() >= 1` rather than `is_finished()` precisely
-/// because a wrapping birth never "finishes" — the reference's latch fires at the first span end
-/// either way (`0x7194bc`, LOOP-flag-independent).
+/// Run each instance's completion callback, the `Hold` handover or the reap's `Decay`. The
+/// reference drains them at the end of the scene tick (`0x707595` in `0x7074b0`); run in `Update`,
+/// after `PreUpdate` advances the players, this fires in the frame the span ends. Completion is
+/// `completions() >= 1`, not `is_finished()`: a wrapping birth never finishes, and the reference
+/// latches at the first span end either way (`0x7194bc`).
 pub(crate) fn advance_fx_anim(
     mut commands: Commands,
     mut instances: Query<(
@@ -143,13 +82,12 @@ pub(crate) fn advance_fx_anim(
     for (root, mut life, mut player, anims, decaying) in &mut instances {
         if decaying {
             arm_decay(&mut player, life.armed(), anims);
-            // The lifecycle is over: the instance's expiry clock owns the despawn from here, and
-            // nothing may re-arm over the decay.
+            // The expiry clock owns the despawn now, and nothing may re-arm over the decay.
             commands.entity(root).try_remove::<FxAnimLife>();
             continue;
         }
         let FxAnimLife::Birth(armed) = *life else {
-            continue; // settled — no callback of this stage's changes anything on completion
+            continue; // settled: nothing changes on completion
         };
         // `0x719370`'s fire-once latch: one notification per authored span.
         if !player
@@ -158,10 +96,8 @@ pub(crate) fn advance_fx_anim(
         {
             continue;
         }
-        // `0x5ff170`: the birth is over. Iff the model authors Hold, arm it and keep it running —
-        // `0x5ff1d0` then re-arms it every span while the deadline `node+0x58` is unset, and that
-        // deadline is nonzero at stage 3 alone. Otherwise do nothing whatsoever: the model is left
-        // parked on its birth, which is both the reference's behaviour and what we already did.
+        // `0x5ff170`: arm `Hold` if the model authors it and keep it running (`0x5ff1d0`'s deadline
+        // `node+0x58` is set only at stage 3); otherwise stay parked on the birth.
         match anims.find(ANIM_HOLD) {
             Some(hold) => {
                 player.stop(armed);
@@ -177,14 +113,8 @@ pub(crate) fn advance_fx_anim(
     }
 }
 
-/// The lifecycle's instrument (`WOW_MOVE_TRACE=<path>`, tag `fx`) — one line per leg change, beside
-/// 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
-/// (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.
+/// The lifecycle's trace line (`WOW_MOVE_TRACE=<path>`, tag `fx`), one per leg change, beside the
+/// instance lane's `kit spawn` and `kit expire`.
 pub(super) fn trace_leg(leg: &str, root: Entity, anim_id: u16) {
     if !benilla_assets::trace::enabled() {
         return;
@@ -192,25 +122,22 @@ pub(super) fn trace_leg(leg: &str, root: Entity, anim_id: u16) {
     benilla_assets::trace::line("fx", &format!("leg {leg} e={root} anim={anim_id}"));
 }
 
-/// The reap's decay-out (`0x614150`, gates at `0x614187`–`0x6141a1`): arm `Decay` if the model
-/// authors it. When it does not, nothing is armed and the caller's immediate expiry stands — the
-/// reference's `je 0x6141d6` straight to the destructor.
+/// The reap's decay-out (`0x614150`, gates `0x614187`–`0x6141a1`): arm `Decay` if the model authors
+/// it; otherwise the caller's immediate expiry stands (`0x6141d6`, straight to the destructor).
 fn arm_decay(player: &mut AnimationPlayer, armed: AnimationNodeIndex, anims: &ModelAnimations) {
     let Some(decay) = anims.find(ANIM_DECAY) else {
         return;
     };
     player.stop(armed);
-    // Never repeated, whatever the sequence flags say: the instance is destroyed at this
-    // sequence's completion, and 61 of the corpus's 62 Decay sequences clamp anyway.
+    // Never repeated: the instance is destroyed at this sequence's completion.
     player
         .play(decay.node)
         .set_repeat(RepeatAnimation::Never)
         .replay();
 }
 
-/// The authored span of a model's `Decay` sequence — how long a reaped instance keeps rendering
-/// 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.
+/// How long a reaped instance keeps rendering (`0x6141f0`): its model's `Decay` span, or `None`
+/// when it authors none and is destroyed at once.
 pub(crate) fn decay_span(anims: Option<&ModelAnimations>) -> Option<f32> {
     anims?.find(ANIM_DECAY).map(|c| c.duration)
 }
@@ -221,7 +148,7 @@ mod tests {
     use benilla_assets::AnimClip;
     use bevy::animation::RepeatAnimation;
 
-    /// One clip of `anim_id`, with the M2 loop flag `looping`, on graph node `node`.
+    /// One clip of `anim_id` with the M2 loop flag `looping`, on graph node `node`.
     fn clip(anim_id: u16, node: usize, looping: bool) -> AnimClip {
         AnimClip {
             anim_id,
@@ -251,9 +178,7 @@ mod tests {
             .repeat_mode()
     }
 
-    /// A stage-2 instance opens on its birth and keeps a watcher: `0x5ff170` is the one callback
-    /// that has a handover to make. `IceShield_State`'s birth clamps, so it is armed unrepeated —
-    /// the freeze the whole fix is about is *correct* right up until the completion fires.
+    /// `IceShield_State`'s birth clamps: armed unrepeated, watching for `0x5ff170`'s handover.
     #[test]
     fn state_arms_the_birth_and_watches_for_the_handover() {
         let mut player = AnimationPlayer::default();
@@ -262,9 +187,7 @@ mod tests {
         assert_eq!(repeat(&player, 0), RepeatAnimation::Never);
     }
 
-    /// Stages 3/4 (`0x60ed00`) re-arm the completed id **unguarded** — the repeat does not consult
-    /// the sequence's own clamp bit, so a precast whose `Stand` clamps still repeats where a
-    /// loop-flag-only arm would freeze it. And there is nothing left to watch.
+    /// `0x60ed00` re-arms without reading the clamp bit, so a clamping precast repeats.
     #[test]
     fn relive_repeats_even_a_clamping_sequence() {
         let mut player = AnimationPlayer::default();
@@ -273,8 +196,7 @@ mod tests {
         assert_eq!(repeat(&player, 0), RepeatAnimation::Forever);
     }
 
-    /// A stage-0/1 one-shot plays its sequence exactly as the M2 sampler would — the clamp bit
-    /// decides — and self-terminates on the instance's span clock, not here.
+    /// The clamp bit decides; a one-shot ends on the instance's span clock, not here.
     #[test]
     fn oneshot_follows_the_sequence_flag_only() {
         let mut clamped = AnimationPlayer::default();
@@ -287,9 +209,7 @@ mod tests {
         assert_eq!(repeat(&wrapping, 0), RepeatAnimation::Forever);
     }
 
-    /// The reap's decay-out and its gate (`0x6141a1`): a model authoring `Decay` reports the span
-    /// the instance must keep rendering for; one that does not reports `None`, which is the
-    /// reference's straight-to-destructor branch.
+    /// The reap's gate (`0x6141a1`): no `Decay` is `None`, the straight-to-destructor branch.
     #[test]
     fn decay_span_is_the_gate_and_the_lifetime() {
         let with = test_anims(&[clip(0, 0, false), clip(ANIM_HOLD, 1, true), {
diff --git a/crates/benilla-app/src/entities/spell_fx/mod.rs b/crates/benilla-app/src/entities/spell_fx/mod.rs
index 41ea132f..04d21833 100644
--- a/crates/benilla-app/src/entities/spell_fx/mod.rs
+++ b/crates/benilla-app/src/entities/spell_fx/mod.rs
@@ -1,62 +1,15 @@
-//! Spell-visual **effect models** (decision 0099 phase 3): the attach-point `.mdx` glows a
-//! spell-visual kit hangs on a casting unit — Fireball's burning hands, a heal's golden sparkle.
-//! The **lootable-corpse sparkle** rides the same plumbing (the client hangs it on the same
-//! `Effect_C` node type): `creature_anim::spell_visual::arm_loot_fx` writes its Begin/Reap edges
-//! under a reserved key.
+//! Spell-visual effect models: the attach-point `.mdx` a kit hangs on a unit, and the
+//! lootable-corpse sparkle, which the client hangs on the same `Effect_C` node type.
 //!
-//! The router (`crate::creature_anim::spell_visual::route_cast_visuals`) resolves each cast edge's
-//! kit to `(M2 attachment id, model path)` pairs and emits [`SpellKitFx`] edges; this module owns
-//! 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 (`0x620be0`), re-resolved per frame off the live
-//! bone matrix (riding the joint entity gives us the same for free).
+//! Each instance root is parented once under the unit's attach joint and rides the bone through
+//! the transform tree, as the reference's `0x620be0` parents the effect model to the host once and
+//! its transform refresh `0x714000` carries it. Every instance takes `CMissile`'s attach cascade
+//! (`ATTACH_FALLBACKS`); the reference's kit effect has none, since `AddEffect 0x61fdd0` tests no
+//! attachment, so on a model lacking the tag `0x620be0` draws nothing and never retries.
 //!
-//! 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
-//! `0x614150`); a **self-terminating** one (cast release, kit push) despawns after one pass of
-//! its model's sequence 0 — the stage-0/1 completion callback's clock, which runs whether or not
-//! the sequence moves a bone (the eat/drink tankard is a 6.667 s sequence with zero bone keys,
-//! so it outlives the ~5 s kit-resend cadence and the jug is held continuously).
-//!
-//! Every spawn first runs the **same-slot replace** ([`replace_same_slot`], decision 2057): the
-//! reference's `0x6208e0`, which destroys any live instance of the same `SpellVisualEffectName`
-//! record at the same attach tag. It is what keeps a busy fight's effect count flat in the number
-//! of attackers, and it is also what swaps the tankard out on each resend.
-//!
-//! **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: `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
-//! authored `Stand` → `Hold` → `Decay` lifecycle ([`lifecycle`], which is where the Ice Barrier
-//! shield's pulse comes from), and run their **material
-//! animation**: each part's colour-alpha × transparency-weight loops sample per instance on the
-//! attach clock (a [`MatAnim`](benilla_world::doodad_anim::MatAnim) that owns the part's render-alpha
-//! tag — Battle Shout's staggered crescent pulses), an animated M2Color RGB ticks a
-//! **per-instance material clone**'s tint uniform ([`FxTintAnims`] — the white-hot flash cooling
-//! to red; per instance because one cast = one phase, unlike the doodad lane's shared-clock
-//! loops in [`benilla_world::doodad_anim::TintAnimMaterials`]), and a **texture transform** scrolls
-//! that same clone's UVs off the instance's own clip — translation, rotation and scale, through
-//! [`register_fx_uv`](benilla_world::doodad_anim::register_fx_uv)'s effect lane (decision 2282;
-//! the druid's claw trail is nothing but that scroll, so until it landed the trail did not draw
-//! at all).
-//!
-//! Effect instances **fire their model's event track** ([`fire_fx_anim_events`], decision 0304):
-//! the playing clip's `$SND`-family keyframes emit the same [`AnimSoundEvent`] stream creatures
-//! emit (spatialized at the host unit), so an effect whose sound lives in its own M2 — the
-//! level-up pillar's `$SND(888)` at t=0.033s — rings without any code-side kit. (The ding's
-//! WATCHER — the `UNIT_FIELD_LEVEL` edge that spawns the pillar — lives with its lootable-edge
-//! sibling in `creature_anim::spell_visual::arm_level_up_fx`, the SpellKitFx writers' home.)
-//!
-//! Approximations, named: a ground-anchored effect's flat quad parts carry no UV offset — their
-//! draw identity rides a `GroundFxDecal` record rather than a `WowModelMaterial` (0733), and no
-//! transform-animating effect model authors one, so the population is empty (`benilla-extract
-//! fxuvscan` is where that stays measured rather than remembered); the span-based
-//! self-termination stands in for the client's model-event completion callback; and the kit sound
-//! keeps playing unconditionally where the client gates it on no-visual-attached.
+//! A persistent instance lives until its spell's [`SpellKitFx::Reap`] (`0x614150`); a
+//! self-terminating one despawns after one pass of its model's sequence 0, a span clock standing in
+//! for the client's completion callback.
 
 mod lifecycle;
 
@@ -79,46 +32,24 @@ use super::{BoneAttach, DisplayModel, EntityPart, ModelHandle};
 pub(super) use lifecycle::advance_fx_anim;
 use lifecycle::{decay_span, FxAnimLife, FxDecay};
 
-/// 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.
+/// `CMissile`'s attach cascade (`0x61ceb0`) for a model lacking the requested point: `0xf`, then
+/// `0x13`, then the unit root.
 const ATTACH_FALLBACKS: [u16; 2] = [0xf, 0x13];
 
-/// The self-termination span when an effect model has no sequence table at all (the cube
-/// fallback and kin) — long enough to read as a flash, short enough never to linger. Shared
-/// with the dest-anchored lane's one-shots ([`super::dest_fx`]) — same completion-callback
-/// stand-in.
+/// The self-termination span of a model with no sequence table; [`super::dest_fx`] shares it.
 pub(crate) const FALLBACK_SPAN: f32 = 1.0;
 
-/// How long a self-terminating instance may wait unspawned (model/skeleton never loading — the
-/// cube-fallback caster) before it is dropped instead of pending forever.
+/// How long a self-terminating instance may wait for a model that never loads.
 const PENDING_TIMEOUT: f32 = 10.0;
 
-/// The effect-model cache: model path → its [`DisplayModel`] (the held-items pattern — the shell
-/// is created here on first use; `super::update_display_models` builds `parts` once the asset
-/// loads, shared by every instance of that path).
+/// The effect-model cache by path; `super::update_display_models` builds each entry's parts.
 #[derive(Resource, Default)]
 pub(crate) struct SpellFx {
     pub(crate) models: HashMap<String, DisplayModel>,
 }
 
-/// Get-or-insert this path's cache entry, starting its M2 load on the spot — **the only way any
-/// site may reach [`SpellFx::models`]**, read or write.
-///
-/// [`super::evict_display_caches`] clears every display cache on a `MapChange`, and its doc states
-/// the contract that makes that safe: *"these caches are get-or-insert at every use site, so a
-/// cleared entry rebuilds on the next spawn that wants it."* This cache was the one that broke it.
-/// Its three consumers looked entries up with a bare `get` and each carried a comment calling the
-/// miss unreachable — "created with the instance", "the spawn created the cache entry" — because
-/// the entry *is* created with the instance, one system earlier. What none of them could see is
-/// that an eviction lands **between** the two, and the entry is never re-created: only a fresh
-/// `SpellKitFx::Begin` inserts, and an aura already sitting in its slots never emits another.
-///
-/// The map flip that does it is the ordinary one: `world_map::announce_map_change` fires on the
-/// login `0 → 1`, ~0.4–1.7 s into every session, which is exactly when a body that entered the
-/// world already carrying an aura is arming that aura's state kit. A **persistent** instance
-/// stranded there is silent and permanent — the `PENDING_TIMEOUT` reaper is gated
-/// `!inst.persistent`, so it is never spawned, never expired, and never traced. Measured at 9 runs
-/// in 10 (decision 2085; bug: the stun swirl not showing).
+/// Get-or-insert this path's cache entry and start its load: the only way to reach
+/// [`SpellFx::models`], since a map change clears it and a standing aura never re-sends `Begin`.
 pub(super) fn ensure_model(fx: &mut SpellFx, asset_server: &AssetServer, path: &str) {
     fx.models
         .entry(path.to_string())
@@ -128,11 +59,8 @@ pub(super) fn ensure_model(fx: &mut SpellFx, asset_server: &AssetServer, path: &
         });
 }
 
-/// The live **per-instance tint clones**: an effect part whose M2Color RGB animates gets its own
-/// material clone at attach (one cast = one phase — the doodad lane's shared-clock registry
-/// [`benilla_world::doodad_anim::TintAnimMaterials`] would run every Battle Shout on one global pulse),
-/// keyed by the clone's asset id → `(RGB loop, attach-time clock origin)`. An entry drops with
-/// its material asset — the instance root's despawn releases the only strong handle.
+/// Per-instance tint clones, material id → `(RGB loop, attach time)`: one cast is one phase, so an
+/// animated M2Color cannot share the doodad lane's global clock. An entry drops with its material.
 #[derive(Resource, Default)]
 pub(crate) struct FxTintAnims(
     HashMap<
@@ -141,9 +69,8 @@ pub(crate) struct FxTintAnims(
     >,
 );
 
-/// Re-sample every live fx clone's tint on its instance clock. Deliberately NOT capture-gated
-/// (unlike the doodad lane's shared-clock ticks): the `fxview` instrument ages an effect inside a
-/// capture, and golden scenarios spawn no effects, so determinism is unaffected.
+/// Re-sample every live clone's tint on its instance clock. Not capture-gated: `fxview` ages an
+/// effect inside a capture, and no golden scenario spawns one.
 pub(crate) fn tick_fx_tint(
     time: Res<Time>,
     mut reg: ResMut<FxTintAnims>,
@@ -155,7 +82,7 @@ pub(crate) fn tick_fx_tint(
     let now = time.elapsed_secs();
     reg.0.retain(|id, (anim, origin)| {
         let Some(mat) = materials.get_mut(*id) else {
-            return false; // the instance despawned — its clone unloaded with it
+            return false; // the instance despawned, and its clone with it
         };
         let rgb = anim.sample(now - *origin);
         mat.extension.tint = Vec4::new(rgb[0], rgb[1], rgb[2], 1.0);
@@ -163,11 +90,7 @@ pub(crate) fn tick_fx_tint(
     });
 }
 
-/// The material side of an effect attach, in one parameter: the store a part's clone is made
-/// from, and the three places that clone can be registered for per-instance animation — the tint
-/// loop ([`FxTintAnims`], decision 0271), the UV scroll ([`UvAnimMaterials`]' effect lane,
-/// decision 2282) and the delta table both scrolls write their rows into. They always travel
-/// together, and a caller that threaded some of them silently dropped a channel.
+/// The material store and the per-instance animation registries a part's clone joins.
 pub(crate) struct FxMaterials<'a> {
     pub(crate) store: &'a mut Assets<WowModelMaterial>,
     pub(crate) tint: &'a mut FxTintAnims,
@@ -175,11 +98,8 @@ pub(crate) struct FxMaterials<'a> {
     pub(crate) table: &'a mut benilla_world::mat_anim_table::MatAnimTable,
 }
 
-/// Resolve one part's material for a NEW effect instance. The shared handle, unless a channel has
-/// to run **per instance** — an animated M2Color RGB (decision 0271) or a texture transform
-/// (decision 2282) — and then a clone of it, seeded at each live loop's first key and registered
-/// for the per-frame ticks. `host` is the instance root, whose `AnimationPlayer` the UV lane reads
-/// its clip off (the sequence source `MatAnim::following_host` takes beside it).
+/// One part's material for a new instance: the shared handle, or a per-instance clone when its RGB
+/// or texture transform animates. The UV lane reads `host`'s player.
 fn fx_part_material(
     part: &EntityPart,
     now: f32,
@@ -190,27 +110,19 @@ fn fx_part_material(
     if part.rgb_anim.is_none() && !loops.any() {
         return part.material.clone();
     }
-    // The shared steady may still be parked (`model_render::lazy`): this copy is made before
-    // anything binds it.
+    // The shared material may still be parked (`model_render::lazy`).
     benilla_world::model_render::lazy::realize(mats.store, part.material.id());
     let Some(mut mat) = mats.store.get(part.material.id()).cloned() else {
-        return part.material.clone(); // shared material not built yet — parts were checked ready
+        return part.material.clone(); // not built yet, though the parts were checked ready
     };
     if let Some(anim) = &part.rgb_anim {
         let t0 = anim.sample(0.0);
         mat.extension.tint = Vec4::new(t0[0], t0[1], t0[2], 1.0);
     }
-    // The clone must leave the shared mat-anim table (decision 1381): its channels are ticked per
-    // INSTANCE, and a carried world slot would add the shared delta on top — a double animation
-    // the old asset-mutating lane could never produce. `register_fx_uv` below hands it rows of
-    // its own.
+    // Off the shared mat-anim table, or its delta would add to the clone's own rows.
     mat.extension.anim_slots = Vec4::ZERO;
     if loops.any() {
-        // **Seed the clone at the loop's own t = 0**, not at the entity lane's flat zero
-        // (`entity_variants` builds every effect batch with `play_uv = false`, so the shared
-        // steady this was cloned from carries no offset at all). The delta table is measured from
-        // whatever `sun_scale.zw` holds at registration (1381), so seeding here is what makes the
-        // registration's own opening row land on the scroll's first frame.
+        // Seed at t = 0: the delta table measures from `sun_scale.zw` at registration.
         let t0 = loops.open_offset();
         mat.extension.sun_scale.z = t0[0];
         mat.extension.sun_scale.w = t0[1];
@@ -233,45 +145,17 @@ fn fx_part_material(
     handle
 }
 
-// (The ground-decal material clone died with 0733: a ground-quad part's draw identity —
-// texture, blend, fog policy, RGB/alpha loops — rides its `GroundFxDecal` record and the
-// effect stream's per-vertex tint instead of a per-instance `WowModelMaterial`.)
-
-/// Where an effect-model instance sits in the client's **model graph** — the two facts every
-/// caller of [`attach_effect_visuals`] states, together, because they are one fact seen from two
-/// sides and a lane that answered only the first is what left a weapon's enchant glow with no
-/// alpha source and no owner (decision 0833).
+/// Where an effect-model instance sits in the client's model graph.
 #[derive(Clone, Copy, Default)]
 pub(crate) struct EffectHost {
-    /// The model instance this one is **chained to** ([`benilla_world::model_fade::ParentModel`]): the
-    /// unit a kit effect is hung on, the item root a weapon glow rides. `None` for a model that
-    /// belongs to no other — a missile, the fixture preview — which is also what keeps the 0202
-    /// drain for the impacting trail.
+    /// The model this instance is chained to ([`benilla_world::model_fade::ParentModel`]), if any.
     pub parent: Option<Entity>,
 }
 
-/// Attach one effect model's full visual set to `root` — THE one body for every effect-model
-/// consumer (spell-kit instances, missiles, the `fxview` capture fixture): the authored rig
-/// ([`arm_effect_rig`]), the part meshes (skinned twins on a rigged model, `NoFrustumCulling` —
-/// a billboarded subtree renders wherever the camera is, so a bind-pose Aabb is wrong by
-/// construction), the billboard cards (riding their bone's joint on a rigged model, decisions
-/// 0153/0154), the emitters/ribbons on their host-bone joints (the 0130 rig identity), the
-/// **material animation** (module docs): per-part `MatAnim` alpha samplers on the attach clock
-/// (`now`) + per-instance tint clones for animated-RGB parts — and, on a **ground-anchored**
-/// instance (`ground_anchor`: the kit slot resolved to the base point `0x13` or the unit root),
-/// each flat ground-plane quad part as a projected surface decal ([`crate::ground_fx`]) riding
-/// its joint, so Battle Shout's crescents drape sloped terrain instead of being buried by it.
-/// `host` says where the instance sits in the model graph ([`EffectHost`]) — which decides its
-/// emitters' attach frame, whose render alpha they inherit, and what becomes of them when the
-/// instance goes. Returns `false` while the model's parts are still building — call again next
-/// frame.
-///
-/// `stage` is the instance's **animation lifecycle** ([`lifecycle`]): `Some` for a spell-visual
-/// `CEffect`, which advances `Stand` → `Hold` → `Decay` and therefore reads its per-sequence riders
-/// (each part's alpha loops, each emitter's rate/enable windows) off its own live `AnimationPlayer`
-/// rather than off a slot pinned at spawn. `None` for the lanes that are not `CEffect`s and never
-/// advance — a missile (the separate `CMissile` TU), an item glow, the `fxview` preview — which
-/// keep the pinned single-clip arm they have always had.
+/// Attach one effect model's visuals to `root`, for every effect consumer. Part meshes go unculled,
+/// since a bind-pose bound is wrong for a billboarded subtree; a `ground_anchor` instance's flat
+/// ground quads become projected decals ([`crate::ground_fx`]). Returns `false` while the model's
+/// parts still build.
 pub(crate) fn attach_effect_visuals(
     commands: &mut Commands,
     root: Entity,
@@ -286,29 +170,21 @@ pub(crate) fn attach_effect_visuals(
     preferred_anim: Option<u16>,
 ) -> bool {
     let Some(parts) = dm.parts.as_ref() else {
-        return false; // still loading — attach on a later pass
+        return false; // still loading
     };
-    // Chain this instance onto the model it hangs from, so its effects compose through the
-    // parent's computed alpha the way `0x714000` does — a weapon's glow through the item, the
-    // item through its wearer (decision 0833).
+    // Chained onto its host model, its alpha composes through the parent's, as `0x714000` does.
     if let Some(parent) = host.parent {
         commands
             .entity(root)
             .insert(benilla_world::model_fade::ParentModel(parent));
     }
-    // …and, from the same fact, what losing the owner means: an instance hung on another model is
-    // part of that model's tree, so its pool is freed with it (the reference's dtor) instead of
-    // being left to finish in world space — the ghost clouds a gear change used to strand at the
-    // body. A free-standing instance (a missile) keeps the 0202 drain.
+    // Freed with the host model (the reference's destructor); a free-standing missile drains.
     let on_owner_loss = if host.parent.is_some() {
         benilla_world::particles::OwnerLoss::Free
     } else {
         benilla_world::particles::OwnerLoss::Drain
     };
     let is_ground_decal = |part: &EntityPart| ground_anchor && part.ground_quad.is_some();
-    // Per-part materials for THIS instance (a tint clone where the RGB animates), resolved
-    // before the child-spawn closure so the material assets aren't borrowed inside it.
-    // Ground-decal parts keep the shared handle unused — their identity rides the decal record.
     let part_materials: Vec<Handle<WowModelMaterial>> = parts
         .iter()
         .map(|p| {
@@ -320,8 +196,6 @@ pub(crate) fn attach_effect_visuals(
         })
         .collect();
     let (joints, armed) = arm_effect_rig(commands, root, dm, preferred_anim, stage);
-    // The owned palette rig (decision 0720): allocated when the effect draws skinned parts; the
-    // hook frees the slot when the instance despawns (impact reap, missile arrival).
     let rig_slot = match (&dm.inverse_bindposes, joints.is_empty()) {
         (Some(ibp), false) => {
             benilla_world::rig_palette::RigSkin::allocate(palettes, joints.clone(), ibp.clone())
@@ -334,26 +208,18 @@ pub(crate) fn attach_effect_visuals(
         _ => 0,
     };
     let rigged = rig_slot != 0;
-    // The clip this instance OPENS on (the missile's InFlight, else the model's `Stand`) — the same
-    // pick `arm_effect_rig` armed. Its **file sequence slot** is the key into each batch's
-    // per-sequence material-alpha loops: an effect that plays a non-first sequence must read that
-    // sequence's authored batch visibility, not sequence 0's.
+    // The opening clip's file sequence slot keys each batch's per-sequence alpha loops.
     let played = dm
         .animations
         .as_ref()
         .and_then(|a| a.preferred_clip(preferred_anim));
     let played_seq = played.map(|c| c.seq_index);
-    // …and for a `CEffect`, that is only the OPENING slot: the instance advances to `Hold` and then
-    // to `Decay`, each with its own authored alpha loops and emitter windows (for IceShield the
-    // pulse is as much the transparency-weight tracks as the bone scale). So its per-sequence
-    // riders read the live sequence off this instance's own player each frame — the same
-    // `playing_seq` lane a creature's batches already use — instead of the slot they opened on.
-    // A lane with no rig has no player to ask and stays pinned, as before.
+    // A `CEffect`'s riders follow its player's live sequence; other lanes keep the opening one.
     let seq_host = (armed && stage.is_some()).then_some(root);
     commands.entity(root).with_children(|children| {
         for (part, material) in parts.iter().zip(&part_materials) {
             if part.billboard.is_some() {
-                continue; // spawned as a following card below (decision 0153)
+                continue; // spawned as a following card below
             }
             if is_ground_decal(part) {
                 continue; // spawned as a projected surface decal below
@@ -371,8 +237,7 @@ pub(crate) fn attach_effect_visuals(
                     kind: ModelKind::Creature,
                     blend: part.blend,
                 },
-                // The picker's triangles (decision 0857): the probe names fx batches through
-                // `ModelPart`, and the render meshes are `RENDER_WORLD`-only.
+                // The picker's triangles; the render meshes are `RENDER_WORLD`-only.
                 benilla_world::interact::PickMesh(part.geometry.clone()),
             ));
             if let (true, Some(_)) = (rigged, &part.skinned_mesh) {
@@ -381,9 +246,7 @@ pub(crate) fn attach_effect_visuals(
                     bevy::mesh::MeshTag(benilla_world::mesh_tag::spawn_tag(rig_slot, 1.0)),
                 ));
             }
-            // The part's colour-alpha × weight loops, on this instance's clock: the sampler owns
-            // the child's render-alpha tag (`drives_tag` — no other writer touches fx parts).
-            // The rig field rides the whole-tag seed (decision 0720).
+            // The alpha loops on this instance's clock; the sampler is the tag's only writer.
             if let Some(anim) = &part.alpha_anim {
                 let mat_anim =
                     benilla_world::doodad_anim::MatAnim::driving_tag(anim.clone(), now, played_seq)
@@ -419,12 +282,11 @@ pub(crate) fn attach_effect_visuals(
                 kind: ModelKind::Creature,
                 blend: part.blend,
             },
-            // The picker's triangles (decision 0857), pivot-centred by the caster like the bake.
+            // The picker's triangles, pivot-centred by the caster like the bake.
             benilla_world::interact::PickMesh(part.geometry.clone()),
             card,
         ));
-        // The card's build-time bound (decision 0834): `calculate_bounds` can no longer derive
-        // one from the `RENDER_WORLD`-only static form's data.
+        // The card's build-time bound: `calculate_bounds` cannot read the `RENDER_WORLD`-only mesh.
         if let Some(aabb) = part.aabb {
             spawned.insert(aabb);
         }
@@ -439,11 +301,9 @@ pub(crate) fn attach_effect_visuals(
             ));
         }
     }
-    // Ground-plane quad parts of a ground-anchored instance → projected surface decals
-    // ([`crate::ground_fx`]): each rides its own joint (posed through the bone's inverse
-    // bindpose, exactly the skinned-vertex path). The part's draw identity — texture, blend,
-    // the shared material's baked `0x70baf0` fog policy, its RGB loop — rides the decal record
-    // (0733); the alpha loop stays a `MatAnim` rider whose `current` the push samples.
+    // Ground quads as projected decals on their joints: texture, blend, fog policy (`0x70baf0`) and
+    // RGB loop ride the record. No UV scroll: no effect model with a texture transform has a ground
+    // quad (`benilla-extract fxuvscan`).
     let binds = dm.inverse_bindposes.as_ref().and_then(|h| ibps.get(h));
     for part in parts.iter() {
         let Some(quad) = part.ground_quad.filter(|_| is_ground_decal(part)) else {
@@ -459,8 +319,7 @@ pub(crate) fn attach_effect_visuals(
             ),
             None => (root, Mat4::IDENTITY), // boneless model: the quad rides the instance root
         };
-        // The material's packed fog byte, handed over raw — the lane owns what it maps to.
-        // `7` (Scene) is the no-material fallback the packer's own default agrees with.
+        // The material's packed fog bits, raw; Scene (7) with no material, the packer's default.
         benilla_world::model_render::lazy::realize(mats.store, part.material.id());
         let (texture, fog_bits) = match mats.store.get(part.material.id()) {
             Some(mat) => (
@@ -470,7 +329,7 @@ pub(crate) fn attach_effect_visuals(
             None => (None, u32::from(benilla_formats::FogPolicy::Scene as u8)),
         };
         let Some(texture) = texture else {
-            continue; // texture-less ground quad: nothing the stream could draw
+            continue; // no texture, nothing to draw
         };
         let decal = benilla_world::ground_fx::spawn_ground_fx_decal(
             commands,
@@ -500,28 +359,16 @@ pub(crate) fn attach_effect_visuals(
             Transform::IDENTITY,
             particles::EmitterFrames {
                 owner: Some(owner),
-                // The cloud SORTS at the instance root — the emitter's bone only composes births.
-                // Since 1585 that is all this is: a world-mode store is frozen at birth, so
-                // neither this root nor the bone can move a particle that already exists.
+                // The cloud sorts at the instance root; the bone only places births.
                 anchor: Some(root),
-                // Free with the model when this instance belongs to one, drain when it stands
-                // alone (the impacting missile's trail — 0202's case). See `on_owner_loss` above.
                 on_owner_loss,
-                // This instance IS the model these particles belong to; its chain (set above)
-                // carries the host's fade down to them — decision 0833.
+                // The particles' model is this instance, whose chain carries the host's fade.
                 alpha: Some(root),
-                // A spell effect has no light node wired: the whole `Spells\` corpus SETS the
-                // emitter unlit bit, so nothing here consumes one today. A lit one would fall
-                // back to the scene's light, which is what it takes now.
+                // Every `Spells\` emitter sets the unlit bit; a lit one would take the scene light.
                 light_node: None,
             },
-            // 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 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).
+            // Rate and enable windows follow the current sequence, as the animate kernel `0x714260`
+            // samples it; global sequences run on the instance's own age.
             match seq_host {
                 Some(h) => particles::EmitClock::Host(h),
                 None => particles::EmitClock::Effect(played_seq),
@@ -537,43 +384,22 @@ pub(crate) fn attach_effect_visuals(
             rb,
             owner,
             use_pivot,
-            // An effect-model instance is armed unscaled — its emitters take the same
-            // `Transform::IDENTITY` placement a few lines up, so both of a model's effect
-            // families land on the same draw-order rung, which is the property that matters.
+            // Unscaled, like the emitters' identity placement, so both land on one draw-order rung.
             1.0,
-            // The instance's own root carries the clip: an effect model that steps
-            // Stand -> Hold -> Decay re-answers the gate at each step, instead of freezing the
-            // birth clip's answer for the whole life.
+            // The visibility gate reads the root's live sequence, so it follows the lifecycle.
             benilla_world::ribbons::RibbonSeq::Host(root),
-            // This instance's own model alpha, chained to its host (0827/0833): a standalone
-            // instance has none above it and draws exactly as before.
+            // This instance's model alpha, chained to its host.
             Some(root),
-            // No fade sphere: an effect instance is not a placed model — it lives for its
-            // clip and is gated by its own model alpha one line up.
+            // No fade sphere: an effect instance is not a placed model.
             None,
         );
     }
     true
 }
 
-/// Arm an effect-model instance's **authored rig** under `root` (a missile entity / fx instance
-/// root): the joint hierarchy, an `AnimationPlayer` on the model's birth clip, and the
-/// free-running global-sequence channels. Effect models pose their emitter/ribbon/mesh bones with
-/// this rig — the fireball missile's constant bone keys turn its authored long-axis-up frame into
-/// flight-forward and set its two trail ribbons 90° apart, and its global-sequence bone tumbles
-/// the molten core. The clip plays regardless of the doodad content gate
-/// (`ModelAnimations::first_seq`, which skips constant-pose sequences as render-identical — true
-/// for skinned MESHES at bind pose, but an effect's emitters read the posed joints, so the
-/// constant keys are load-bearing here).
-///
-/// The clip is the reference's model-load bootstrap — **animation id 0 `Stand`**, not the
-/// file-order-first slot ([`benilla_assets::ModelAnimations::preferred_clip`]) — and for a
-/// `CEffect` (`stage` is `Some`) it is only the OPENING leg: [`FxAnimLife`] carries the completion
-/// callback that advances it to `Hold` and, at the reap, to `Decay` ([`lifecycle`]).
-///
-/// Returns the joint entities (empty for a boneless model — everything then rides `root` directly,
-/// as before) and whether an `AnimationPlayer` was actually armed, which is what decides whether
-/// the per-sequence riders have a live sequence to follow.
+/// Arm an effect instance's rig under `root`, returning the joints and whether a player was armed.
+/// The clip plays even with constant keys, unlike the doodad gate (`ModelAnimations::first_seq`),
+/// because emitters read the posed joints.
 pub(super) fn arm_effect_rig(
     commands: &mut Commands,
     root: Entity,
@@ -585,29 +411,22 @@ pub(super) fn arm_effect_rig(
         return (Vec::new(), false);
     }
     let joints = benilla_world::rig_palette::spawn_joints(commands, root, root, &dm.skeleton);
-    // Billboard bones face the camera at the PALETTE level, children inheriting (the frost-armor
-    // sheets skin to a lock-Z bone's child) — the joint pass needs the map.
+    // Billboard bones face the camera at the palette level, their children inheriting.
     if let Some(bb) = benilla_world::billboard::BillboardJointRig::new(&dm.skeleton, &joints, root)
     {
         commands.entity(root).insert(bb);
     }
     let mut armed = false;
     if let Some(anims) = dm.animations.as_ref() {
-        // A caller can name the sequence this instance should run (the thrown-weapon missile asks
-        // for InFlight, so its authored spin plays and its ribbon's per-sequence visibility keys
-        // ON); absent that — or when the model has no such sequence (an arrow, a fireball whose
-        // tumble is a global sequence) — the bootstrap's `Stand`.
+        // The caller's sequence (a thrown weapon's InFlight), else the bootstrap's `Stand`.
         if let Some(clip) = anims.preferred_clip(preferred_anim) {
             let mut player = AnimationPlayer::default();
-            // The stage owns the repeat policy, not the sequence flag alone: stages 3/4 re-arm
-            // unconditionally (`0x60ed00`), so a clamping precast still repeats.
+            // The stage owns the repeat policy (`0x60ed00` repeats a clamping precast).
             let life = FxAnimLife::arm(&mut player, clip, stage.unwrap_or(FxStage::OneShot));
             commands
                 .entity(root)
                 .insert((player, AnimationGraphHandle(anims.graph.clone())));
-            // The lifecycle watcher, and the `ModelAnimations` it (and the per-sequence riders)
-            // resolve the live sequence through — only on the `CEffect` lanes; a missile or an
-            // item glow neither advances nor is ever decay-reaped.
+            // The lifecycle watcher, on a `CEffect` only.
             if stage.is_some() {
                 commands.entity(root).insert((life, anims.clone()));
             }
@@ -621,9 +440,7 @@ pub(super) fn arm_effect_rig(
         if let Some(drive) =
             benilla_world::rig_anim::GlobalSeqDrive::new(&anims.global_bones, &joints)
         {
-            // Fresh anchor per play — the byte-verified effect lifecycle (0858): CreateModel
-            // always allocates+attaches, so every cast's gseq loops open at phase 0, exactly
-            // like the ref (the director's 3-cast trace: the flash at +16 frames every time).
+            // Fresh per play: the reference makes a model per cast, so global sequences open at 0.
             commands.entity(root).insert(drive);
         }
     }
@@ -632,35 +449,25 @@ pub(super) fn arm_effect_rig(
 
 /// One live (or pending) effect-model instance on a unit.
 struct FxInstance {
-    /// The spell that owns it — the reap key (the client stores it at `CEffect+0x18`). The
-    /// lootable-corpse sparkle reserves `u32::MAX` (`spell_visual::LOOT_FX_KEY` — not a spell).
+    /// The reap key (the client's `CEffect+0x18`); the lootable-corpse sparkle uses `u32::MAX`.
     spell_id: u32,
-    /// Precast/channel lifetime (reaped by spell id) vs cast-release (self-terminates).
+    /// Reaped by spell id (precast, channel) rather than self-terminating (cast release).
     persistent: bool,
-    /// Which owner's reap can kill a persistent instance (cast router vs aura watcher) — the
-    /// client's reap-walk discriminator next to the spell id ([`FxClass`]).
+    /// Which reap can end a persistent instance, the client's discriminator beside the spell id.
     class: FxClass,
-    /// Which animation lifecycle its model runs ([`FxStage`]) — a separate axis from `class`, and
-    /// carried per instance because the same `class` covers a stage-4 precast and a stage-2
-    /// channel.
+    /// The lifecycle, apart from `class`: one class covers a stage-4 precast and a stage-2 channel.
     stage: FxStage,
     /// The M2 attachment id to hang from ([`benilla_formats::KIT_SLOT_TAGS`]), or
-    /// [`benilla_formats::WORLD_EFFECT_TAG`] for the field-12 world-plant slot (0848/0850).
+    /// [`benilla_formats::WORLD_EFFECT_TAG`] for the field-12 world-plant slot.
     tag: u16,
-    /// The `SpellVisualEffectName` record id — with [`Self::tag`], the reference's same-slot
-    /// replace key (`0x6208e0`; [`replace_same_slot`], decision 2057).
+    /// The `SpellVisualEffectName` id; with `tag`, the same-slot replace key (`0x6208e0`).
     effect: u32,
-    /// The model-cache key.
     path: String,
-    /// The spawned instance root (a child of the attach joint), `None` while the model loads.
     root: Option<Entity>,
-    /// 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.
+    /// The self-termination deadline on `time.elapsed_secs()`, or a reaped instance's `Decay` end.
     expires: Option<f32>,
-    /// 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.
+    /// Reaped and playing its `Decay` out (`0x6141f0`). A reap or replace cannot reach it, as the
+    /// reference has moved it to its pending-destroy list.
     decaying: bool,
 }
 
@@ -670,28 +477,19 @@ pub(super) struct FxAttached {
     instances: Vec<FxInstance>,
 }
 
-/// 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. 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.
+/// A world-planted kit instance root (kit field 12): a free entity planted once at its owner
+/// (`0x620a90`), and re-planted on displacement for a root-aura spell (`0x620580`).
 #[derive(Component)]
 pub(super) struct WorldPlantFx {
-    /// The unit the instance belongs to — despawn tracking (the client's node dies with its
-    /// owner) and the re-plant source.
     owner: Entity,
-    /// Re-plant on owner displacement (the 0x4000 leg) — root-aura persistents only.
+    /// Re-plant on owner displacement (the client's flag `0x4000`): root-aura persistents only.
     follow: bool,
 }
 
-/// The client's re-plant displacement gate: distance² > 1e-3 (`0x620580`'s squared-distance
-/// compare; world units).
+/// The client's re-plant gate, distance² > 1e-3 in world units (`0x620580`).
 const REPLANT_EPS_SQ: f32 = 1e-3;
 
-/// The plant transform (`0x620a90`): `translate(owner position) × yaw(owner facing about the up
-/// axis) × scale(owner scale)` — yaw ONLY (a swimming or mount-tilted body plants level), baked
-/// at spawn.
+/// The plant transform (`0x620a90`): the owner's position, yaw only and scale.
 fn world_plant_transform(owner: &GlobalTransform) -> Transform {
     let (scale, rotation, translation) = owner.to_scale_rotation_translation();
     let (yaw, _, _) = rotation.to_euler(EulerRot::YXZ);
@@ -702,10 +500,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
-/// (`0x60f081`; only the column *name* is inferred).
-/// Exactly the field-12 state family: Frost Nova, Net, Web, Entangling Roots, Frostbite.
+/// Whether an `EffectApplyAuraName` slot is `SPELL_AURA_MOD_ROOT` (26): the client's
+/// `spellRec+0x16c[0..2] == 0x1a` scan that arms the re-plant flag `0x4000` (`0x60f081`).
 fn spell_has_root_aura(spells: Option<&crate::ui_action::Spells>, spell_id: u32) -> bool {
     const SPELL_AURA_MOD_ROOT: u32 = 26;
     spells
@@ -713,10 +509,8 @@ fn spell_has_root_aura(spells: Option<&crate::ui_action::Spells>, spell_id: u32)
         .is_some_and(|d| d.effect_apply_aura.contains(&SPELL_AURA_MOD_ROOT))
 }
 
-/// Tend the live world plants: despawn a plant whose owner is gone (a scene child would get this
-/// from the tree; a free root must be swept), and re-plant a `follow` instance whose owner was
-/// displaced past [`REPLANT_EPS_SQ`] — the client's `0x620580` per-frame leg, which re-bakes
-/// position, facing AND scale on displacement.
+/// Despawn a plant whose owner is gone, and re-plant a `follow` one whose owner moved past
+/// [`REPLANT_EPS_SQ`] (`0x620580`, per frame).
 pub(super) fn tend_world_plants(
     mut commands: Commands,
     mut plants: Query<(Entity, &WorldPlantFx, &mut Transform)>,
@@ -733,10 +527,8 @@ pub(super) fn tend_world_plants(
     }
 }
 
-/// Consume the router's [`SpellKitFx`] edges: `Begin` records instances (and creates their model
-/// cache entries), `Reap` despawns the matching spell's persistent instances. Ordered per unit —
-/// a GO's reap-then-begin lands in emission order, so the precast dies before the release flash
-/// spawns.
+/// Apply the router's [`SpellKitFx`] edges per unit in emission order: `Begin` records instances,
+/// `Reap` decays the spell's persistent ones, so a GO's precast dies before its release flash.
 pub(super) fn resolve_spell_fx(
     mut commands: Commands,
     mut events: MessageReader<SpellKitFx>,
@@ -748,7 +540,6 @@ pub(super) fn resolve_spell_fx(
 ) {
     let Some(mut fx) = fx else { return };
     let now = time.elapsed_secs();
-    // Group the edges per unit, preserving order, so each unit's instance list is written once.
     let mut ops: EntityHashMap<Vec<&SpellKitFx>> = EntityHashMap::default();
     for ev in events.read() {
         let entity = match ev {
@@ -757,7 +548,6 @@ pub(super) fn resolve_spell_fx(
         ops.entry(entity).or_default().push(ev);
     }
     for (entity, edges) in ops {
-        // A unit may have despawned between the edge and this frame — drop its edges.
         if commands.get_entity(entity).is_err() {
             continue;
         }
@@ -776,11 +566,8 @@ pub(super) fn resolve_spell_fx(
                     effects,
                     ..
                 } => {
-                    // A persistent Begin REPLACES the unit's live persistent instances of the
-                    // same (spell, class) — so an aura whose remove/add edges land across frames
-                    // (a re-apply) re-arms cleanly instead of stacking. The replaced instance
-                    // decays out exactly as a reaped one does: in the reference these are two
-                    // nodes, the old one dying on its own clock while the new one is born.
+                    // A persistent Begin first reaps the same (spell, class): a re-applied aura's
+                    // old node decays out while the new one is born, as in the reference.
                     if *persistent {
                         reap_matching(
                             &mut instances,
@@ -793,9 +580,7 @@ pub(super) fn resolve_spell_fx(
                         );
                     }
                     for FxSlot { tag, effect, path } in effects {
-                        // **The same-slot replace**, run per slot exactly where the reference
-                        // runs it: `CEffect::AddEffect 0x61fdd0` opens with
-                        // `0x6208e0(owner, rec, tag)` (decision 2057).
+                        // Per slot, as `AddEffect 0x61fdd0` opens with `0x6208e0(owner, rec, tag)`.
                         replace_same_slot(
                             &mut instances,
                             *effect,
@@ -842,23 +627,9 @@ 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.
-///
-/// 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
-/// — the draw path's own admission test is the live-particle count itself (`0x7b4b46 mov
-/// eax,[esi+0x64]`), which nothing in the teardown touches. Despawning the root outright, as this
-/// lane did before, cut every live particle at once: for `Strike_Impact_Chest` a replace landing
-/// mid-burst threw away up to 0.30 s of a 0.334 s effect, as a pop mid-ramp.
-///
-/// The meshes are right to go with the root: the reference drops the model off the MESH draw list
-/// the same frame (`0x719207` gates it on the visible flag the teardown clears) while the PARTICLE
-/// list is gated on the busy mask (`0x71922c`), which the survivors keep set.
-///
-/// Emitters are free entities carrying their instance root as [`ParticleEmitter::anchor`], so that
-/// is the identity here — a linear scan, run only when an instance actually ends (a few per second
-/// in a fight, against a pool the sim already walks every frame).
+/// Hand an ending instance's emitters to the drain, the half of the teardown `0x6203e0` that is not
+/// a despawn: emission stops and live particles age out, since the reference gates the particle
+/// draw on the live count (`0x7b4b46`) while the meshes leave the draw list at once (`0x719207`).
 fn drain_instance_emitters(
     emitters: &mut Query<&mut benilla_world::particles::ParticleEmitter>,
     root: Entity,
@@ -870,21 +641,9 @@ fn drain_instance_emitters(
     }
 }
 
-/// **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
-/// **flat in the number of attackers** rather than linear. It is a *destroy*, not the reap's
-/// decay — the node is gone the same frame, and the newcomer is born in its place.
-///
-/// Two exclusions, both the reference's own:
-/// - **`tag == -1`** ([`benilla_formats::WORLD_EFFECT_TAG`], the field-12 world plant) is skipped
-///   at `0x620913`, so successive world plants genuinely coexist.
-/// - an instance already **decaying** is not reachable: the reference has moved it off `+0xb4`
-///   onto the pending-destroy list, exactly as [`reap_matching`] documents.
+/// The same-slot replace (`0x6208e0`): destroy each live node with the same `SpellVisualEffectName`
+/// record at the same tag, without a decay, which keeps the effect count flat in the number of
+/// attackers. The world-plant tag (-1) is exempt (`0x620913`); a decaying instance is out of reach.
 fn replace_same_slot(
     instances: &mut Vec<FxInstance>,
     effect: u32,
@@ -900,9 +659,7 @@ fn replace_same_slot(
             return true;
         }
         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 (it ends the node through the shared
-            // teardown `0x6203e0`).
+            // Through the shared teardown `0x6203e0`, so its particles finish.
             drain_instance_emitters(emitters, root);
             commands.entity(root).despawn();
         }
@@ -910,14 +667,8 @@ fn replace_same_slot(
     });
 }
 
-/// The spell-id-keyed reap walk (`0x614150`): every live persistent instance of `(spell_id, class)`
-/// **plays its `Decay` out** and is torn down when that span ends — the reference's three gates in
-/// order (`0x614187`–`0x6141a1`: a model handle, a ready model, and a `Decay` the model actually
-/// authors), with an immediate destroy whenever any of them fails.
-///
-/// An instance already decaying is skipped: it is dying, and in the reference it has been moved off
-/// the unit's `+0xb4` list to the pending-destroy list, so a second reap cannot reach it either.
-/// One that never spawned a root has nothing to play and goes at once.
+/// The spell-id reap (`0x614150`): each persistent instance of `(spell_id, class)` plays `Decay`
+/// out, or goes at once without a model, a ready model or a `Decay` (`0x614187`–`0x6141a1`).
 fn reap_matching(
     instances: &mut Vec<FxInstance>,
     spell_id: u32,
@@ -937,8 +688,7 @@ fn reap_matching(
             .and_then(|dm| decay_span(dm.animations.as_ref()));
         let (Some(root), Some(span)) = (i.root, span) else {
             if let Some(root) = i.root {
-                // A reap with no `Decay` to play destroys at once — and that destroy is
-                // `0x6203e0` like any other, so its particles still drain.
+                // Destroyed at once, through `0x6203e0` like any other, so its particles drain.
                 drain_instance_emitters(emitters, root);
                 commands.entity(root).despawn();
             }
@@ -952,11 +702,8 @@ fn reap_matching(
     });
 }
 
-/// Spawn pending instances whose model finished building, and run the self-termination clock.
-/// The instance root is a child of the attach joint at the attachment offset (the cascade above),
-/// so the whole effect — meshes and particle emitters alike — rides the animating bone. The one
-/// exception is the kit's **world-plant slot** ([`benilla_formats::WORLD_EFFECT_TAG`], kit field
-/// 12): its root is a free world entity at the owner's position/facing/scale, [`WorldPlantFx`].
+/// Spawn pending instances whose model has built, and run the self-termination clock. A root hangs
+/// under its attach joint and rides the bone; a world plant ([`WorldPlantFx`]) stands free.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 pub(super) fn attach_spell_fx(
     mut commands: Commands,
@@ -964,11 +711,8 @@ pub(super) fn attach_spell_fx(
         Entity,
         &mut FxAttached,
         Option<&BoneAttach>,
-        // The unit's pose buffer: the attach joint spawns on first demand from the composed
-        // 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>>,
@@ -993,9 +737,7 @@ pub(super) fn attach_spell_fx(
             if let Some(expires) = inst.expires {
                 if now >= expires {
                     if let Some(root) = inst.root {
-                        // The flash ran its span — but its particles have their own clocks and
-                        // outlive it (`drain_instance_emitters`). This is the completion
-                        // callback's leg of the same `0x6203e0` teardown the replace takes.
+                        // The `0x6203e0` teardown: the particles outlive the flash.
                         drain_instance_emitters(&mut emitters, root);
                         commands.entity(root).despawn();
                     }
@@ -1008,20 +750,9 @@ pub(super) fn attach_spell_fx(
                     return false;
                 }
             }
-            // A root that died as **collateral**: [`FxAttached`] lives on the unit and outlives
-            // its model — exactly as the reference's per-CGUnit `+0xb4` effect list does — so a
-            // teardown of the unit's visual (a live display swap, `live_display`; before 0835 a
-            // gear change; before B199's fix a mount transition) leaves the instance holding a
-            // 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`. 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:
-            // it is the pending-morph latch's impact-kit REPLAY after the rebuild
-            // (`creature_anim::spell_visual::replay_morph_kit`), and a decaying instance was
-            // ending anyway.
+            // A root lost with the unit's visual: the reference's rebuild `0x60abe0` drains the
+            // effect list and re-creates what persists (`0x5ff130` auras, `0x612a30` channels), so
+            // a persistent instance re-arms here and a one-shot or decaying one goes.
             if let Some(root) = inst.root {
                 if commands.get_entity(root).is_ok() {
                     return true;
@@ -1046,44 +777,28 @@ pub(super) fn attach_spell_fx(
                     );
                 }
             }
-            // Still pending: a self-terminating instance gets a generous deadline so a unit whose
-            // model never materialises (the cube fallback) can't accumulate unspawnable flashes —
-            // persistent ones are reaped by their spell edge regardless. A successful spawn below
-            // overwrites this with the real clip span.
+            // Pending: unspawnable flashes time out; a spawn sets the real span.
             if !inst.persistent && inst.expires.is_none() {
                 inst.expires = Some(now + PENDING_TIMEOUT);
             }
             ensure_model(&mut fx, &asset_server, &inst.path);
             let Some(dm) = fx.models.get(&inst.path) else {
-                return true; // unreachable — just inserted
+                return true; // unreachable: just inserted
             };
             if dm.parts.is_none() {
-                return true; // model still loading — spawn on a later pass
+                return true; // model still loading
             }
-            // The world-plant slot (kit field 12, decisions 0848/0850): the client passes NO
-            // attach tag (`0x61fcf0` pushes −1), skips the bone pipeline entirely and plants the
-            // model once, world-space, at the owner's position × yaw × scale (`0x620c86` via
-            // `0x620a90`) — it does not ride a bone and does not turn with the unit afterwards.
-            // A root-aura spell's plant additionally re-plants on owner displacement
-            // ([`tend_world_plants`] — the client's 0x4000 flag leg).
+            // The world-plant slot (kit field 12): no attach tag (`0x61fcf0` pushes -1), planted
+            // once in world space (`0x620c86` via `0x620a90`), riding no bone.
             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.
+            // A bone-riding effect waits for the body: before it is built there are no attach
+            // points, and a live root is never re-seated. The reference re-arms after the rebuild
+            // sets the model (`0x60abe0` → `0x5ff130`); the cube fallback counts as built.
             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
-            // quads as ordinary geometry (the ProtectionFrom* chest shields author flat quads
-            // too — they must NOT decal to the ground).
+            // Ground-anchored: a world plant, or an instance on the base point (`0x13`) or the unit
+            // root. A chest-anchored one keeps its flat quads as geometry (`ProtectionFrom*`).
             let (root, ground_anchor) = if planted {
                 let follow =
                     inst.persistent && spell_has_root_aura(spells.as_deref(), inst.spell_id);
@@ -1096,14 +811,12 @@ pub(super) fn attach_spell_fx(
                             follow,
                         },
                     ))
-                    // Chain-only visibility (benilla_world::vis_chain) — the wrapper
-                    // renders nothing; the effect's parts are the children.
+                    // Chain-only visibility: the wrapper draws nothing, its children do.
                     .vis_chain_only()
                     .id();
                 (root, true)
             } else {
-                // The attach cascade: the slot's tag, the client's two fallbacks, else the unit
-                // root.
+                // `CMissile`'s cascade: the slot's tag, `0xf`, `0x13`, else the unit root.
                 let point = bones.and_then(|b| {
                     std::iter::once(inst.tag)
                         .chain(ATTACH_FALLBACKS)
@@ -1124,20 +837,16 @@ pub(super) fn attach_spell_fx(
                 commands.entity(parent).add_child(root);
                 (root, ground_anchor)
             };
-            // The one shared effect-visuals body — rig, skinned parts, joint-riding
-            // cards/emitters/ribbons, ground decals, material animation. Parts were checked
-            // ready above, so this always attaches.
+            // Parts were checked ready above, so this always attaches.
             attach_effect_visuals(
                 &mut commands,
                 root,
                 dm,
                 now,
                 ground_anchor,
-                // A kit instance on a unit is an attached model, chained to that unit: it fades
-                // with the body it is cast on, and it is freed with it (0833) — where before, a
-                // gear change that tore the unit's visual down left its cloud in the air.
+                // Chained to the unit: it fades and is freed with the body.
                 EffectHost { parent: Some(unit) },
-                // A kit effect IS a `CEffect`: it runs the stage's animation lifecycle.
+                // A kit effect is a `CEffect`: it runs the stage's lifecycle.
                 Some(inst.stage),
                 &mut FxMaterials {
                     store: &mut wow_materials,
@@ -1151,14 +860,9 @@ pub(super) fn attach_spell_fx(
             );
             inst.root = Some(root);
             if !inst.persistent {
-                // The client's completion-callback moment: one full pass of the sequence the
-                // instance arms — sequence 0, whether or not it moves a bone. Read from the raw
-                // sequence table, NOT the built clips: a sequence with zero bone keys builds no
-                // clip at all (the eat/drink tankard/sparkle models are exactly this), and the
-                // old clips-only read collapsed their span to the 1 s fallback — the jug lived
-                // 1 s of every 5 s kit resend instead of overlapping seamlessly. INFERRED at the
-                // loop boundary: a looping sequence is counted as one pass (a stage-0 effect that
-                // never completed would outlive the drink; the ref's tankard does not).
+                // One pass of sequence 0, from the raw sequence table: a sequence with no bone
+                // keys builds no clip (the eat/drink tankard). A looping one counts as one pass;
+                // the reference's loop boundary is untraced, but its tankard ends with the drink.
                 let span = dm.first_seq_span.unwrap_or(FALLBACK_SPAN);
                 inst.expires = Some(now + span);
             }
@@ -1178,17 +882,13 @@ pub(super) fn attach_spell_fx(
     }
 }
 
-/// Fire the event keyframes each live effect instance's playing clip crossed since last frame
-/// (module doc; decision 0304) — the same `(prev, cur]` window scan as the creature scanner
-/// ([`scan_events`]), emitting with the HOST UNIT as the event entity (the unit's transform is
-/// the world position; an instance root's own is joint-local). Unlike a streamed creature, an
-/// instance is born under our eyes at t = 0, so first sight fires the head window `[0, cur]` —
-/// the level-up pillar's `$SND(888)` sits at 0.033 s and depends on it.
+/// Fire the event keyframes each instance's clip crossed since last frame ([`scan_events`]), at the
+/// host unit, so a sound authored in the effect's own M2 plays. An instance is born at t = 0, so
+/// first sight fires `[0, cur]`: the level-up pillar's `$SND(888)` sits at 0.033 s.
 pub(super) fn fire_fx_anim_events(
     units: Query<(Entity, &FxAttached)>,
     players: Query<&AnimationPlayer>,
-    // The instance root's own world frame and rig — the effect MODEL's placement, which is the
-    // frame its event records are authored in. Decoupled from the emit entity below on purpose.
+    // The instance root's world frame and rig, the frame its event records are authored in.
     globals: Query<&GlobalTransform>,
     poses: Query<&benilla_world::rig_anim::RigPose>,
     fx: Option<Res<SpellFx>>,
@@ -1219,11 +919,8 @@ pub(super) fn fire_fx_anim_events(
             let cur = active.seek_time();
             seen.push(root);
             let prev = last.insert(root, cur).unwrap_or(-1.0);
-            // The emit entity is decoupled from the scanned track's owner by design — the fx
-            // scan fires at the unit, not the joint-local instance root. **The POINT is not**:
-            // the record's `position` is authored in the effect model's own space, so it composes
-            // through the instance root's world frame. `Spells\ArcaneShot_Area.m2` puts its
-            // `$SND` 30.5 yd off that model's origin — the largest `$SND` offset in the corpus.
+            // Fired at the unit, but the point composes through the root's frame, the space it is
+            // authored in (`ArcaneShot_Area.m2` puts a `$SND` 30.5 yd out).
             let Ok(root_world) = globals.get(root) else {
                 continue;
             };
@@ -1237,7 +934,6 @@ pub(super) fn fire_fx_anim_events(
             scan_events(clip, unit, prev, cur, &frame, &mut out);
         }
     }
-    // Roots despawn on reap/expiry — drop their seek memory with them.
     if last.len() > seen.len() {
         let live: bevy::ecs::entity::EntityHashSet = seen.iter().copied().collect();
         last.retain(|e, _| live.contains(e));
@@ -1250,7 +946,7 @@ mod tests {
     use bevy::asset::AssetPlugin;
     use bevy::mesh::skinning::SkinnedMeshInverseBindposes;
 
-    /// One recorded instance, spawned (`root`) and awaiting nothing.
+    /// One spawned instance of Ice Barrier's state model.
     fn instance(root: Entity, persistent: bool) -> FxInstance {
         FxInstance {
             spell_id: 13033, // Ice Barrier
@@ -1266,9 +962,7 @@ mod tests {
         }
     }
 
-    /// An app with just what `attach_spell_fx` reads, plus one unit carrying an instance per
-    /// entry of `persistent` — each with a freshly spawned root. Returns the app, the unit and the
-    /// roots in order.
+    /// An app running `attach_spell_fx`, and a unit with one spawned instance per `persistent`.
     fn standing(persistent: &[bool]) -> (App, Entity, Vec<Entity>) {
         let mut app = App::new();
         app.add_plugins((MinimalPlugins, AssetPlugin::default()))
@@ -1301,7 +995,6 @@ mod tests {
         (app, unit, roots)
     }
 
-    /// Each surviving instance's `(persistent, root)` after one pass.
     fn instances_of(app: &App, unit: Entity) -> Vec<(bool, Option<Entity>)> {
         app.world()
             .entity(unit)
@@ -1313,18 +1006,11 @@ mod tests {
             .collect()
     }
 
-    /// **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
-    /// flash goes exactly as the reference's drained Mount Poof does. The shapeshift cloud is
-    /// deliberately NOT this path's business — it is the morph latch's post-rebuild replay
-    /// (`creature_anim::spell_visual::replay_morph_kit`).
+    /// The reference's rebuild (`0x60abe0`) drains every effect node and re-creates what persists.
     #[test]
     fn a_persistent_instance_whose_root_died_as_collateral_is_re_armed() {
         let (mut app, unit, roots) = standing(&[true, false]);
-        // The teardown: a display swap despawns the unit's whole visual under them.
+        // A display swap despawns the unit's whole visual.
         for root in roots {
             app.world_mut().entity_mut(root).despawn();
         }
@@ -1336,10 +1022,7 @@ 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.
+    /// With the new body still loading, a re-armed instance waits rather than spawn at the root.
     #[test]
     fn a_re_armed_instance_waits_for_the_body_before_it_spawns() {
         let (mut app, unit, roots) = standing(&[true]);
@@ -1368,8 +1051,7 @@ mod tests {
         );
     }
 
-    /// 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).
+    /// A decaying instance was already ending, so the drain takes it too.
     #[test]
     fn a_decaying_instance_whose_root_died_as_collateral_is_dropped() {
         let (mut app, unit, roots) = standing(&[true]);
@@ -1384,7 +1066,6 @@ mod tests {
         assert_eq!(instances_of(&app, unit), vec![]);
     }
 
-    /// A live root is left strictly alone — the gate is "is it still there?", not "re-spawn me".
     #[test]
     fn a_live_root_is_never_disturbed() {
         let (mut app, unit, roots) = standing(&[true]);
@@ -1392,9 +1073,9 @@ mod tests {
         assert_eq!(instances_of(&app, unit), vec![(true, Some(roots[0]))]);
     }
 
-    // ---- the same-slot replace (`0x6208e0`, decision 2057) ----
+    // ---- the same-slot replace (`0x6208e0`) ----
 
-    /// The blood spurt's record and the two flank tags — the case the rule exists for.
+    /// The blood spurt's record and the two flank tags.
     const SPURT: u32 = 63;
     const FRONT: u16 = 0xf;
     const BACK: u16 = 0x10;
@@ -1435,7 +1116,6 @@ mod tests {
         app.update();
     }
 
-    /// Every live instance's `(effect, tag)`, in list order.
     fn slots_of(app: &App, unit: Entity) -> Vec<(u32, u16)> {
         app.world()
             .entity(unit)
@@ -1444,9 +1124,7 @@ mod tests {
             .unwrap_or_default()
     }
 
-    /// **The rule** (`0x6208e0`): a second play of the same record at the same tag DESTROYS the
-    /// first — five attackers' spurts on one flank are one instance, not five, which is why the
-    /// reference's effect count is flat in the number of attackers where ours was linear.
+    /// `0x6208e0`: a second play of the same record at the same tag destroys the first.
     #[test]
     fn a_replay_of_the_same_record_at_the_same_tag_replaces_rather_than_stacks() {
         let (mut app, unit) = resolving();
@@ -1472,8 +1150,7 @@ mod tests {
         );
     }
 
-    /// The tag is half the key: the same record at a different attach point coexists — Execute's
-    /// cast kit hangs one record on BOTH hands (`0x15` and `0x16`), and both must survive.
+    /// Execute's cast kit hangs one record on both hands (`0x15` and `0x16`), and both survive.
     #[test]
     fn the_same_record_at_a_different_tag_coexists() {
         let (mut app, unit) = resolving();
@@ -1482,8 +1159,7 @@ mod tests {
         assert_eq!(slots_of(&app, unit), vec![(SPURT, FRONT), (SPURT, BACK)]);
     }
 
-    /// The record is the other half: two different records at one tag coexist, and keying the
-    /// walk on the model PATH instead would wrongly collapse them (two rows may name one `.mdx`).
+    /// The key is the record, not the model path: two rows may name one `.mdx`.
     #[test]
     fn a_different_record_at_the_same_tag_coexists() {
         let (mut app, unit) = resolving();
@@ -1498,8 +1174,7 @@ mod tests {
         );
     }
 
-    /// The reference excludes `tag == -1` from the walk (`0x620913`), so successive world plants
-    /// genuinely stack — a second Thunder Clap ring does not eat the first.
+    /// The walk skips tag -1 (`0x620913`): a second Thunder Clap ring does not eat the first.
     #[test]
     fn the_world_plant_slot_is_excluded_from_the_replace() {
         let (mut app, unit) = resolving();
@@ -1509,18 +1184,7 @@ mod tests {
         assert_eq!(slots_of(&app, unit), vec![(SPURT, tag), (SPURT, tag)]);
     }
 
-    /// The stun swirl that never appeared (decision 2085): a kit instance whose cache entry was
-    /// wiped by the login `MapChange` between its `Begin` and its spawn pass.
-    ///
-    /// The fixture is the aftermath, not the race — an instance holding a path the cache no longer
-    /// knows, which is what a session that entered the world already carrying an aura looks like
-    /// ~0.4–1.7 s in. Before [`ensure_model`] guarded the read, the spawn pass returned "still
-    /// pending" for ever: nothing re-created the entry (only a fresh `SpellKitFx::Begin` inserts,
-    /// and a standing aura emits no second one), and a *persistent* instance is exempt from the
-    /// `PENDING_TIMEOUT` reaper, so it was never spawned, never expired and never traced.
-    ///
-    /// The assertions are the two halves of that: the entry comes back, **and** the instance is
-    /// still there to use it — reaping it instead would make the failure quiet rather than fixed.
+    /// A map change clears the cache: the spawn pass rebuilds the entry and keeps the instance.
     #[test]
     fn an_evicted_cache_entry_is_rebuilt_by_the_spawn_pass() {
         const PATH: &str = "Spells\\StunSwirl_State_Head.mdx";
diff --git a/crates/benilla-app/src/entities/wmo_props.rs b/crates/benilla-app/src/entities/wmo_props.rs
index 11a7ab34..674168de 100644
--- a/crates/benilla-app/src/entities/wmo_props.rs
+++ b/crates/benilla-app/src/entities/wmo_props.rs
@@ -1,53 +1,25 @@
-//! WMO-display GameObject doodad props — the ship's sails.
+//! The doodad props of a WMO-display GameObject: a transport's sail rig, rotor and cabin
+//! furniture. A GameObject has no MODF placement and so no selected extra set: its props are
+//! doodad set 0 (`Set_$DefaultGlobal`) alone, the only set either 1.12 transport authors (the ship
+//! 134 props, the zeppelin 1).
 //!
-//! A WMO's placed doodads (MODD — for the two 1.12 transports: the entire sail rig
-//! `TRANSPORTSHIP_SAILS.MDX`, the zeppelin's rotor `ZEPANIMATION.MDX`, and the cabin furniture)
-//! are M2 props the terrain path spawns for world-placed buildings but the gameobject path never
-//! did, so ships sailed bare (director, 2026-07-17). A gameobject carries no MODF placement, so
-//! there is no selected extra set: its props are doodad set 0 (`Set_$DefaultGlobal`, the
-//! always-shown set) alone — and both transport WMOs author exactly one set (verified from the
-//! extracted roots: ship 134 props / zeppelin 1, all in set 0).
+//! Each prop spawns through the shared placed-model assembler with its doodad-local transform,
+//! parented under the GameObject, so it rides the moving boat, despawns with it and inherits its
+//! off-map hide; animated props take the ordinary doodad animation host. A prop with a collision
+//! hull gets a body-less collider child, which avian attaches to the transport's kinematic body,
+//! and the mover's ride-attach walks the parent chain, so standing on a crate is standing on the
+//! boat; hull-less furniture is walk-through, as in the reference.
 //!
-//! Each prop spawns through the shared placed-model assembler
-//! ([`benilla_world::terrain_stream::spawn_model_entities`]) with its doodad-LOCAL transform, and the
-//! result is parented under the streamed gameobject entity: transform propagation carries the
-//! props with the moving boat, the entity's despawn cascades through them, and the transport's
-//! off-map hide (`Visibility` on the root) is inherited. The animated props (sails, rotors) get
-//! the ordinary doodad anim host — its joint/billboard/fade consumers all read propagated
-//! `GlobalTransform`s, so riding a moving parent needs nothing special. A boneless prop's glow
-//! card FOLLOWS an anchor child instead of baking a world pivot (`BillboardCard::following`).
+//! Its dressing is entity-owned, never the terrain path's world bake. Emitters ride their host bone
+//! and re-anchor to the prop's live position every frame, as the reference rebuilds its
+//! `translate(−emitterPos)` draw matrix, and take no `EmitterFade`, whose centre is a fixed world
+//! point; vmangos streams transports map-wide, so the far-clip wall in the particle sim is what
+//! bounds the deck lanterns. M2 point lights are children at the prop-local position.
 //!
-//! A prop with an authored collision hull is SOLID (0470): its collider spawns as a body-less
-//! child, which avian attaches to the nearest `RigidBody` ancestor — the transport's kinematic
-//! body — so the cargo's collision sails with the deck (the same collide-iff-hull law as world
-//! placements; hull-less furniture stays walk-through, exactly like the reference). The mover's
-//! ride-attach walks the support's parent chain, so standing on a crate is standing on the boat.
-//!
-//! The prop's live dressing (0474, closing the 0458 gaps) takes the ENTITY-owned shape, not the
-//! terrain path's world-baked one:
-//! - **Emitters** (the deck lanterns' flames) spawn with `owner` = the emitter's host-bone joint
-//!   (or the prop's root submesh for a boneless model) and `anchor` = the prop root — the sim
-//!   refreshes the placement from the owner's propagated `GlobalTransform` every frame and the
-//!   risen cloud re-anchors to the prop's live position (the reference's per-frame
-//!   `translate(−emitterPos)` draw-matrix rebuild: a moving model carries its flame). No
-//!   [`benilla_world::particles::EmitterFade`] — that gate's centre is a baked world point, and a mover has
-//!   none. The emitter entity parents under the gameobject, so the off-map hide reaches it and
-//!   despawn cascades.
-//!   ⚠ **This used to say the population is "bounded by server visibility instead". That was
-//!   wrong, and a transport is the exact counter-example** (decision 0678, bug B39): vmangos
-//!   streams transports **map-wide**, so a ship's deck lanterns are resident from anywhere on the
-//!   map. Measured from Durotar: 56 emitters ticking and drawing at 4853–7080 yd, this boat's
-//!   lanterns among them. The bound is now the far-clip wall, applied in
-//!   [`benilla_world::particles`]' sim to every world-lane emitter regardless of `EmitterFade`.
-//! - **M2 point lights** (the lantern's glow source) spawn as CHILDREN at the prop-local
-//!   position — propagation carries the source with the hull, and the hide/despawn follow.
-//! - **Interior cabin props** (an INDOOR-group MODD — ~118 of the ship's 133) take the interior
-//!   SH-probe lane, folded ONCE through the host's spawn pose. Fold-once stays exact on a mover:
-//!   the ambient word is directionless, the diffuse lobe rides the FIXED world axis (byte law —
-//!   it never turns with the model), and a MOLR lobe's gain is a pure relative distance. Every
-//!   1.12 transport WMO authors ZERO MOLT lights (verified from the four extracted roots), so
-//!   there is no frozen-lobe-direction residual either; a future MOLR-authored mover would
-//!   freeze its lobe directions at spawn — a noted residual, not worth live-refold machinery.
+//! An indoor-group prop takes the interior SH-probe lane, folded once through the host's spawn
+//! pose. That stays exact on a mover: the ambient word has no direction, the diffuse lobe rides a
+//! fixed world axis, and a MOLR lobe's gain is a relative distance. No 1.12 transport WMO authors a
+//! MOLT light, so no lobe direction freezes at spawn.
 
 use benilla_assets::coords::{wmo_doodad_local, wow_to_bevy};
 use benilla_assets::{DoodadBase, M2Model, WmoModel};
@@ -67,44 +39,38 @@ use benilla_world::terrain_stream::{
 
 use super::{GameObjects, ModelHandle, VisualAttached};
 
-/// Marks a streamed entity the prop resolver has visited — once, ever (units and M2 gameobjects
-/// included, so the resolve query never re-scans them). A WMO gameobject with props also gets
-/// [`WmoProps`].
+/// Marks an entity the prop resolver has visited, units and M2 GameObjects included, so it is
+/// never scanned again.
 #[derive(Component)]
 pub(super) struct WmoPropsResolved;
 
-/// The not-yet-spawned doodad props of one WMO-display gameobject. Each spawns as its M2 asset
-/// lands; the component is removed when the list drains (the per-frame query empties out).
+/// A WMO GameObject's props still waiting on their M2s; removed when the list drains.
 #[derive(Component)]
 pub(super) struct WmoProps(Vec<WmoProp>);
 
-/// One pending prop: its M2 (loading async), its WMO-local placement, and — for an INDOOR-group
-/// doodad — the interior-lane base to fold at spawn.
+/// One pending prop, with its WMO-local placement.
 struct WmoProp {
     handle: Handle<M2Model>,
     local: Transform,
-    /// `Some` iff the doodad belongs to an INDOOR group ([`DoodadBase::Interior`], MODR
-    /// ownership resolved at asset load); `None` = the deck lane (plain matte, like an exterior
-    /// terrain prop on lit ground — a boat is never MCSH-shadowed).
+    /// Set for a doodad of an indoor group (MODR ownership, [`DoodadBase::Interior`]); `None` is
+    /// the deck lane, lit as an exterior doodad.
     interior: Option<InteriorLane>,
 }
 
-/// An interior prop's committed-light inputs, kept WMO-LOCAL so the spawn-time fold can compose
-/// them through the host's live pose (the resolve and the spawn are frames apart on a mover).
+/// An interior prop's light inputs, kept WMO-local so the fold composes them through the host's
+/// pose at spawn, frames after the resolve.
 struct InteriorLane {
-    /// `cap96(MODD.colour)` — the ambient word.
+    /// `cap96(MODD.colour)`, the ambient word.
     ambient: [f32; 3],
-    /// `floor112(MODD.colour)` — the diffuse word, committed on the fixed interior axis.
+    /// `floor112(MODD.colour)`, the diffuse word on the fixed interior axis.
     diffuse: [f32; 3],
-    /// The owning group's MOLR omnis: (WMO-local Bevy position, colour × intensity, attenStart,
-    /// attenEnd). Empty on every 1.12 transport (zero MOLT authored — see the module doc).
+    /// The owning group's MOLR omnis as (WMO-local position, colour × intensity, attenStart,
+    /// attenEnd); empty on every 1.12 transport.
     lights: Vec<(Vec3, [f32; 3], f32, f32)>,
 }
 
-/// Resolve the MODD prop list of every freshly-attached WMO-display gameobject (set 0 — see the
-/// module doc for why there is never a selected extra set). Runs after `attach_entity_visuals`:
-/// `VisualAttached` on a modeled gameobject means its parts were built, which means the `WmoModel`
-/// asset is resident (the display holds a strong handle).
+/// Resolve the set-0 props of each newly attached WMO-display GameObject. Runs after
+/// `attach_entity_visuals`, whose `VisualAttached` means the `WmoModel` is resident.
 #[allow(clippy::type_complexity)] // the visit-once attach-gate query
 pub(super) fn resolve_wmo_gameobject_props(
     mut commands: Commands,
@@ -126,7 +92,7 @@ pub(super) fn resolve_wmo_gameobject_props(
                 _ => None,
             })
         else {
-            continue; // no display / M2 display / (shouldn't happen) asset gone
+            continue; // no display, an M2 display, or the asset gone
         };
         let Some(set) = wmo.doodad_sets.first() else {
             continue;
@@ -137,13 +103,12 @@ pub(super) fn resolve_wmo_gameobject_props(
             .enumerate()
             .skip(set.start as usize)
             .take(set.count as usize)
-            .filter(|(_, d)| !d.model.is_empty()) // MODN name offset didn't resolve
+            .filter(|(_, d)| !d.model.is_empty()) // the MODN name did not resolve
             .map(|(di, d)| WmoProp {
                 handle: asset_server.load(m2_url(&d.model)),
                 local: wmo_doodad_local(d.position, d.orientation, d.scale),
-                // Interior classification (MODR ownership, resolved at asset load) + the MODD
-                // colour words; the group's MOLR refs resolve here to WMO-LOCAL light data so
-                // the spawn-time fold needs the WMO asset no further.
+                // The indoor classification and MODD colour words; MOLR refs resolve here to
+                // WMO-local lights, so the spawn needs the WMO asset no further.
                 interior: match wmo.doodad_base.get(di) {
                     Some(DoodadBase::Interior(b)) => Some(InteriorLane {
                         ambient: b.ambient,
@@ -168,11 +133,8 @@ pub(super) fn resolve_wmo_gameobject_props(
             })
             .collect();
         if !props.is_empty() {
-            // Named by the ENTITY as well as the display: the resolver visits each entity once
-            // (`WmoPropsResolved` is inserted before any `continue`), so two identical lines mean
-            // two instances of one display — two ships of the same model — not a repeat of the
-            // work. Without the instance in the message that is unreadable, and it read as a
-            // caching bug on 2026-09-06.
+            // Named by entity as well as display: each entity is visited once, so two lines for
+            // one display are two ships of the same model.
             info!(
                 "wmo props: {} set-0 doodads resolved for display {} on {entity}",
                 props.len(),
@@ -183,9 +145,8 @@ pub(super) fn resolve_wmo_gameobject_props(
     }
 }
 
-/// Spawn each pending prop as its M2 lands, parented under the gameobject entity. The whole ship's
-/// set spawns within a few frames of the models landing — no per-frame budget (transports are a
-/// handful of instances per map, not a city's worth of placements).
+/// Spawn each pending prop under its GameObject as its M2 lands, with no per-frame budget: a map
+/// holds only a handful of transports.
 pub(super) fn spawn_wmo_gameobject_props(
     mut commands: Commands,
     m2s: Res<Assets<M2Model>>,
@@ -195,8 +156,7 @@ pub(super) fn spawn_wmo_gameobject_props(
     mut tint_reg: ResMut<benilla_world::doodad_anim::TintAnimMaterials>,
     mut anim_table: ResMut<benilla_world::mat_anim_table::MatAnimTable>,
     mut probes: ResMut<PropProbes>,
-    // The EXTERIOR prop's one-shot MCSH sample (2047) — the same resolver the terrain lane's
-    // placed props use, at the same one-shot cadence the reference's `0x698c50` queue drain has.
+    // An exterior prop's one-shot MCSH sample, as the reference's queue drain `0x698c50` takes it.
     streamer: Option<Res<TerrainStreamer>>,
     adt_tiles: Res<Assets<benilla_assets::AdtTile>>,
     time: Res<Time>,
@@ -206,44 +166,38 @@ pub(super) fn spawn_wmo_gameobject_props(
         return; // no shared light buffer yet
     };
     let light = &light;
-    // The animated-prop clock origin (decision 0130) — per-instance phase = spawn time.
+    // Animated props take their phase from their spawn time.
     let now = time.elapsed_secs();
     for (entity, host_gt, mut props) in &mut hosts {
-        // The host's pose THIS frame — the spawn-time composition base for the interior fold and
-        // the emitters' first-frame placement (both track the live pose from here on: the fold is
-        // rigid-motion invariant, the emitters follow their owner entity).
+        // The host's pose this frame, the base of the interior fold and the emitters' first
+        // placement; the fold is rigid-motion invariant and the emitters follow their owner.
         let host_world = host_gt.compute_transform();
         let (mut hulls, mut emitters, mut ribbons, mut lights, mut interior) =
             (0u32, 0u32, 0u32, 0u32, 0u32);
         props.0.retain(|prop| {
             let Some(m) = m2s.get(&prop.handle) else {
-                return true; // still loading — retry next frame
+                return true; // still loading; retry next frame
             };
-            // The prop's app-built render forms (decision 0834): a transport's cabin props are
-            // the entity lane — priority 0, same as any creature walking into view.
+            // Priority 0, the entity lane's, like any creature walking into view.
             let ready = if benilla_world::doodad_anim::wants_rig(m) {
                 forms.require_rigged(&prop.handle, 0)
             } else {
                 forms.require_static(&prop.handle, 0)
             };
             if !ready {
-                return true; // forms still building — retry next frame
+                return true; // forms still building
             }
-            // A boneless prop's glow card follows an ANCHOR child at the prop's placement (the
-            // card itself stays a world root the billboard pass writes absolutely). Only spawned
-            // when the model has billboard batches — one lantern per ship, not 134 empty entities.
+            // A boneless prop's glow card, a world root, follows an anchor child at the prop's
+            // placement, spawned only for a model with billboard batches.
             let card_owner = m.submeshes.iter().any(|s| s.billboard.is_some()).then(|| {
                 let anchor = commands.spawn((prop.local, Visibility::default())).id();
                 commands.entity(entity).add_child(anchor);
                 anchor
             });
-            // **An EXTERIOR prop's sun scale is the doodad law, not its host's** (2047). The
-            // reference samples MCSH once, at the doodad's OWN footprint, on the frame the
-            // pending-doodad queue drains it (`0x698c50` unlinks each entry), and freezes the
-            // verdict: 1.0 lit / 0.5 shadowed, never the host node's ramp. `doodad_ground_shade`
-            // already answers *lit* for a tile that is not resident — which is what the
-            // reference's own null-tile legs return, so a boat at sea needs no special case.
-            // An INTERIOR prop ignores the selector entirely (the probe lane reads it not at all).
+            // An exterior prop's sun scale is its own doodad's, not its host's: the reference
+            // samples MCSH once at the doodad's footprint as its pending queue drains it
+            // (`0x698c50`) and freezes 1.0 lit or 0.5 shadowed. A tile not resident answers lit, as
+            // the reference's null-tile legs do; the interior lane never reads the selector.
             let shade = if prop.interior.is_some() {
                 ShadeSel::Matte
             } else {
@@ -254,16 +208,13 @@ pub(super) fn spawn_wmo_gameobject_props(
                 {
                     Some(ShadeResolve::Ready(true)) => ShadeSel::Shaded,
                     Some(ShadeResolve::Ready(false)) | None => ShadeSel::Matte,
-                    // The tile is resident but still decoding — defer this prop a frame, exactly
-                    // as the terrain lane does. Not reachable at sea (no tile ⇒ `Ready(false)`).
+                    // A resident tile still decoding defers the prop a frame, as on the terrain.
                     Some(ShadeResolve::Pending) => return true,
                 }
             };
             let (radius, center) = m2_fade(&m.bounds, prop.local.scale.x);
             let anim_bound = m2_anim_bound(&m.bounds);
-            // The interior lane (0474): fold the cabin prop's committed light ONCE, composed
-            // through the host's current pose. Exact on a mover — see the module doc's
-            // invariance argument.
+            // Fold an interior prop's light once, through the host's current pose (module docs).
             let interior_slot = prop.interior.as_ref().and_then(|lane| {
                 let ref_point = host_world.mul_transform(prop.local).transform_point(center);
                 let world_lights: Vec<PropLobeLight> = lane
@@ -291,9 +242,8 @@ pub(super) fn spawn_wmo_gameobject_props(
                 }
                 slot
             });
-            // This path never diverts (below), so the identity only names the kind and what the
-            // parts are — the GameObject's own `WorldObject` is what a pick on the ship answers
-            // with, inserted by `entities::attach` on the parts it owns.
+            // The identity only names the kind and the parts: a pick on the ship answers with the
+            // GameObject's own `WorldObject`.
             let object = std::sync::Arc::new(benilla_world::interact::WorldObject {
                 kind: benilla_world::model_render::ModelKind::Doodad,
                 label: prop
@@ -302,11 +252,7 @@ pub(super) fn spawn_wmo_gameobject_props(
                     .map(|p| p.path().to_string_lossy().into_owned())
                     .unwrap_or_default(),
                 id: 0,
-                // The prop's LANE, the way a terrain-placed prop's identity names it
-                // (`PropLight::inspector_label`): a prop that looks wrong is almost always on the
-                // wrong lane or reading the wrong probe, and neither is visible from the model
-                // path. This lane's props were the ones the entity shade writer renamed out from
-                // under (B373), and a hover said nothing at all.
+                // The prop's lane and probe, as a terrain prop's identity names them.
                 detail: match (&prop.interior, interior_slot) {
                     (Some(lane), Some(slot)) => format!(
                         "WMO gameobject prop · interior amb {} dif {} · {} MOLR · probe slot {slot}",
@@ -331,14 +277,12 @@ pub(super) fn spawn_wmo_gameobject_props(
                 light,
                 &m.submeshes,
                 forms.slices(&prop.handle),
-                prop.local, // doodad-LOCAL — the parent composes the world pose
+                prop.local, // doodad-local; the parent composes the world pose
                 &object,
                 shade,
                 interior_slot,
-                // No draw-set gate: a transport's props ride a MOVING parent, and an `EmitterFade`
-                // measures from a baked world point that a mover has none of — the same reason
-                // their emitters carry none (module docs above). The assembler builds the bare
-                // sphere its mesh lane needs from `radius`/`center` instead.
+                // No draw-set gate, whose `EmitterFade` measures from a fixed world point; the
+                // assembler builds its sphere from `radius` and `center` instead.
                 None,
                 radius,
                 center,
@@ -347,32 +291,25 @@ pub(super) fn spawn_wmo_gameobject_props(
                 &mut uv_reg,
                 &mut tint_reg,
                 &mut anim_table,
-                true, // the entity-hosted lane: these props are lit by their own def (2047)
+                true, // the entity-hosted lane: these props are lit by their own def
                 card_owner,
-                // Never diverted into 1417's production merge nor 1429's static-gx: these
-                // props parent under a MOVING gameobject, and every divert lane bakes world
-                // transforms.
+                // Never diverted: every divert lane bakes world transforms.
                 None,
                 None,
             );
             commands.entity(entity).add_children(&ents);
-            // The slot frees itself when the prop despawns — the component hook returns it to
-            // the table whoever does the despawn (same shape as the terrain path).
+            // The slot's component hook returns it to the table whoever despawns the prop.
             if let (Some(slot), Some(&first)) = (interior_slot, ents.first()) {
                 commands.entity(first).insert(PropProbeSlot(slot));
                 interior += 1;
             }
-            // Solid cargo (0470): collide-iff-hull, the world-placement law. The hull bakes the
-            // prop-LOCAL placement into its vertices (the same object-frame the boat's own hull
-            // collider uses), and the child carries NO RigidBody — avian attaches a bare collider
-            // to the nearest body ancestor, the transport's kinematic body, so the collision
-            // sails with the deck. On a static WMO gameobject (Naxxramas) the ancestor is its
-            // `Static` body — same mechanism, no motion.
+            // Solid cargo: the hull bakes the prop-local placement into its vertices, and the
+            // child has no `RigidBody`, so avian attaches it to the nearest body ancestor, the
+            // transport's kinematic body (a static WMO GameObject's `Static` one).
             if let Some((verts, tris)) = placement_collider_data(m.collision.as_ref(), &prop.local)
             {
-                // No visibility components at all: a hull renders nothing and hosts nothing,
-                // and B0004 only checks the child→parent direction — a bare child under a
-                // visible parent is fine (benilla_world::vis_chain has the sweep-tax law).
+                // No visibility components: a hull draws nothing, and Bevy's hierarchy check only
+                // flags a visible child under a bare parent, never the reverse.
                 let hull = commands
                     .spawn((
                         Transform::IDENTITY,
@@ -382,15 +319,12 @@ pub(super) fn spawn_wmo_gameobject_props(
                 commands.entity(entity).add_child(hull);
                 hulls += 1;
             }
-            // The prop's live dressing (0474) — the entity-owned shape, never the terrain path's
-            // world bake; see the module doc. All of it needs a root entity to ride.
+            // The entity-owned dressing (module docs), which needs a root entity to ride.
             if let Some(&root) = ents.first() {
                 let placement = host_world.mul_transform(prop.local);
                 for em in &m.emitters {
-                    // The emitter rides its host bone's anchor when the prop animates (the
-                    // same ride as a terrain doodad — an unanimated chain reproduces the static
-                    // path exactly); a boneless prop follows its root. Either owner's propagated
-                    // global composes the moving hull.
+                    // The emitter rides its host bone's anchor when the prop animates, else the
+                    // prop root; either owner's propagated transform carries the hull's motion.
                     let owner = host
                         .as_ref()
                         .and_then(|h| h.anchor(em.def.bone))
@@ -401,37 +335,31 @@ pub(super) fn spawn_wmo_gameobject_props(
                         placement,
                         particles::EmitterFrames {
                             owner: Some(owner),
-                            // The cloud anchors at the PROP: the boat carries the risen flame (the
-                            // reference re-anchors every cloud to the emitter's live position),
-                            // while an animated bone still never drags it.
+                            // The cloud anchors at the prop, as the reference re-anchors every
+                            // cloud to the emitter's live position; a bone never drags it.
                             anchor: Some(root),
                             // A placed prop's model is destroyed when its placement unloads.
                             on_owner_loss: particles::OwnerLoss::Free,
-                            // A placed prop carries no fade component of its own; its emitters
-                            // take the doodad distance fade in the sim instead (0827).
-                            // A WMO prop is lit by the CMapDoodadDef provider (`0x6a8050`), not the
-                            // WENTITY one this edge feeds — its interior words come from its own MODD
-                            // colour and are folded at spawn (`PropLight::Interior`). Wiring that twin
-                            // into the emitter lane is a named residual, not this lane's node.
+                            // A WMO prop is lit by the `CMapDoodadDef` provider (`0x6a8050`), not
+                            // the `WENTITY` one this edge feeds; its interior words, folded at
+                            // spawn, do not reach its emitters.
                             light_node: None,
                             alpha: None,
                         },
-                        // A placed prop: the doodad law — which is NOT one arm for life. It re-rolls
-                        // its variation every play-window (decision 0768), so the emitter resolves
-                        // the slot + clip time off the host's live player each frame.
+                        // A placed prop re-rolls its variation every play window, so the emitter
+                        // reads the slot and clip time off the host's live player each frame.
                         match host.as_ref().and_then(|h| h.arm) {
                             Some(arm) => particles::EmitClock::Host(arm),
                             None => particles::EmitClock::Pinned,
                         },
                     ) {
-                        // Parented: the off-map hide reaches the flame, and despawn cascades
-                        // (the sim's direct GlobalTransform write runs post-propagation, so the
-                        // parent never disturbs the rendered anchor).
+                        // Parented, so the off-map hide and the despawn reach the flame; the sim
+                        // writes its transform after propagation, so the parent never moves it.
                         commands.entity(entity).add_child(e);
                         emitters += 1;
                     }
                 }
-                // Ribbon trails — the same host-bone ride; a trail self-despawns with its owner.
+                // Ribbon trails ride the host bone the same way and despawn with their owner.
                 for rb in &m.ribbons {
                     let (owner, use_pivot) = host
                         .as_ref()
@@ -444,21 +372,12 @@ pub(super) fn spawn_wmo_gameobject_props(
                         use_pivot,
                         placement.scale.max_element(),
                         benilla_world::ribbons::RibbonSeq::Host(entity),
-                        // No model-alpha source: a placed prop / effect instance is always drawn (0827).
+                        // No model-alpha source: a placed prop is always drawn.
                         None,
-                        // No fade sphere: a GameObject's props ride the GameObject, not a
-                        // baked world placement — that gate's centre is a fixed world point and a
-                        // mover would drag away from it (the same reason the emitters beside them
-                        // take none, stated at the top of this file), and nothing floods this WMO
-                        // to give it rooms. The far-clip wall still applies: `simulate_ribbons`
-                        // bounds a fade-less trail at the wall exactly as `simulate_particles`
-                        // bounds a fade-less emitter, which is what a map-wide-streamed transport
-                        // five kilometres away needs (decision 0678).
-                        //
-                        // Still open, and named rather than guessed at: a `Visibility`-hidden
-                        // transport trails. The trail reads its owner's render alpha, not its
-                        // `Visibility`, and the off-map hide writes the latter. No 1.12 transport
-                        // prop authors a ribbon, so nothing renders it today.
+                        // No fade sphere, as for the emitters; `simulate_ribbons` still bounds a
+                        // fade-less trail at the far-clip wall. A trail reads its owner's render
+                        // alpha, not the `Visibility` the off-map hide writes, but no 1.12
+                        // transport prop authors a ribbon.
                         None,
                     )
                     .is_some()
@@ -466,11 +385,11 @@ pub(super) fn spawn_wmo_gameobject_props(
                         ribbons += 1;
                     }
                 }
-                // M2 point lights (the lantern's glow source): a CHILD at the prop-local
-                // position — propagation carries the source with the hull.
+                // M2 point lights, children at the prop-local position, carried with the hull. A
+                // directional light feeds an ambient term, and a static 0 visibility key is dark.
                 for l in m.lights.iter().map(|l| &l.def) {
                     if !l.casts() {
-                        continue; // directional lights feed an ambient term; a static `0` visibility key is dark
+                        continue;
                     }
                     let glow = commands
                         .spawn((
@@ -485,14 +404,10 @@ pub(super) fn spawn_wmo_gameobject_props(
                     lights += 1;
                 }
             }
-            false // spawned — drop from the pending list
+            false // spawned; drop from the pending list
         });
         if hulls + emitters + ribbons + lights + interior > 0 {
-            // The instrument line the probe greps: what this host's props actually authored
-            // (zero anywhere is legal — collide-iff-hull, emit-iff-authored, indoor-iff-owned).
-            // The host is in the message for the same reason as above — and doubly here, because
-            // this line fires once per host per frame in which anything spawned, so ONE host's
-            // 134 props land over several batches and emit several honest lines.
+            // What this host's props authored; one host's props may log over several frames.
             info!(
                 "wmo props: {hulls} cargo hulls, {emitters} emitters, {ribbons} ribbons, \
                  {lights} lights, {interior} interior-lane props (riding host {entity})"
diff --git a/crates/benilla-app/src/go_anim.rs b/crates/benilla-app/src/go_anim.rs
index 2f72db46..239022a7 100644
--- a/crates/benilla-app/src/go_anim.rs
+++ b/crates/benilla-app/src/go_anim.rs
@@ -1,70 +1,20 @@
-//! 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 state machine.
+//! GameObject state animation: `GAMEOBJECT_STATE` drives a skeletal M2 sequence, so a door
+//! swings, a button depresses and a chest lid opens and closes.
 //!
-//! **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:
+//! The 1.12 client keeps one stored state per object (`go+0x27c`), set only through `SetGoState`
+//! (`0x5f8bd0`); [`GoAnim::state`] is that state. The server never flips a chest's wire state, so
+//! an open-lock cast and the loot release move its lid.
 //!
-//! 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.
-//! 2. **the open-lock spell-go** ([`open_go_lid`]) — `SMSG_SPELL_GO` for an open-lock cast targeting the
-//!    GO opens it (`SetGoState(ACTIVE)`). A chest's lid pops when the *Opening* cast goes off, not on the
-//!    click — the faithful timing. The server never flips a chest's wire state (its `Use(CHEST)` runs
-//!    scripts only; loot is spell-driven), so this — not the wire — is what opens a chest.
-//! 3. **the loot-release** ([`close_go_lid`]) — the loot window closing (`CMSG_LOOT_RELEASE`) drops the
-//!    state to READY, closing the lid, with no server round-trip (the client's loot-frame close handler).
+//! A state maps, with no inversion, to a held rest pose ([`rest_anim`]), and a change plays a
+//! one-shot motion onto it ([`motion_anim`]). Keyed by `AnimationData.dbc` id: the machine's
+//! internal index and the debug state names at `0x860850` are off by one.
 //!
-//! 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 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 loop bit (`flags` bit 0, `0x714585`) does not end a motion; the object layer's completion
+//! does, so every arm is one window ([`RepeatAnimation::Never`]) and [`retire_transient_anim`]
+//! advances the machine at its end.
 //!
-//! 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
-//! central trap; we key by id):
-//!
-//! | wire state | rest pose (held)      | entered by motion (one-shot) |
-//! |------------|-----------------------|------------------------------|
-//! | 1 READY    | `0x93` Closed         | `0x92` Close  (from open)     |
-//! | 0 ACTIVE   | `0x95` Opened         | `0x94` Open   (from closed)  |
-//! | 2 ALT      | `0x97` Destroyed      | `0x96` Destroy / `0x98` Rebuild |
-//!
-//! benilla reuses the creature skeletal path wholesale: an animated GameObject is instanced with the same
-//! joints + `AnimationPlayer` + graph + [`ModelAnimations`] a creature gets ([`crate::entities::attach`]),
-//! but tagged with [`GoAnim`] instead of `AnimDriver`, so this driver — not `creature_anim` — owns it.
-//! 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).
-//! 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
-//! at the arm's baked window end — span × replay, bit 0 ignored — and slot 14 `0x5f4120` advances
-//! the machine off the motion substate onto its rest one (2 Open → 3 Opened, 4 Close → 1 Closed,
-//! 5 Destroy → 6 Destroyed, 7 Rebuild → 1 Closed), arming that pose over the motion. So benilla
-//! arms a motion for exactly ONE window ([`RepeatAnimation::Never`]) and
-//! [`retire_transient_anim`] re-runs the state machine at its end — the same endpoint, and the
-//! same shape the Custom channel already uses (decisions 1099/1100). Honouring the loop bit
-//! instead is a chest lid that springs open and slams shut ~1.5×/s for ever, which is the report
-//! this record closes.
-//!
-//! 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`
-//! (`0x5f3c30`, `0x5f3ac5`); benilla reads
-//! only `GAMEOBJECT_STATE` and always plays from frame 0. And the mid-flight **reverse blend**
-//! (interrupting a half-open door).
+//! Not built: `GAMEOBJECT_ANIMPROGRESS`, which picks the motion at spawn and seeks it to
+//! `duration × progress / 100` (`0x5f3ac5`), and the reverse blend of an interrupted swing.
 
 use avian3d::prelude::{Collider, ColliderDisabled};
 use benilla_assets::ModelAnimations;
@@ -77,146 +27,76 @@ use crate::creature_anim::{advance_track, scan_events, AnimSoundEvent};
 use crate::net::{GuidIndex, ObjectStore};
 use benilla_world::schedule::WorldStage;
 
-/// `GO_STATE_ACTIVE` (vmangos `GOState`) — the **open** state (door swung, chest lid up). Passable.
+/// `GO_STATE_ACTIVE` (vmangos `GOState`): open, and passable.
 const GO_STATE_ACTIVE: u32 = 0;
-/// `GO_STATE_READY` (vmangos `GOState`) — the **closed / solid** state. A door/button blocks movement
-/// only in this state; `GO_STATE_ACTIVE` (0, open) and `GO_STATE_ACTIVE_ALTERNATIVE` (2) are passable.
+/// `GO_STATE_READY` (vmangos `GOState`): closed, the one state in which a door or button blocks.
 const GO_STATE_READY: u32 = 1;
 
-/// `AnimationData.dbc` **157 Despawn** — the id the one-shot channel's code 6 resolves to
-/// (`0x80b0e0[6]` = substate 12, `0x8607e4[12]` = 157). The
-/// object plays this once and *then* goes away; see [`DespawnAnimAnnounced`].
+/// `AnimationData.dbc` 157 Despawn, the one-shot channel's code 6 (`0x80b0e0[6]` = substate 12,
+/// `0x8607e4[12]` = 157): the object plays it once, then goes.
 const ANIM_DESPAWN: u16 = 157;
 
-/// Marker + client-side state for an animated GameObject (decisions 0242/2271). Instanced by
-/// [`crate::entities::attach`] on an animatable GO type whose model authors sequences; driven by
-/// [`drive_go_anim`]. Distinct from creatures' `AnimDriver` so the two drivers never touch one entity.
+/// An animated GameObject's client-side state, tagged by [`crate::entities::attach`] in place of a
+/// creature's `AnimDriver`, and driven by [`drive_go_anim`].
 #[derive(Component, Default)]
 pub(crate) struct GoAnim {
-    /// Client-authoritative `GAMEOBJECT_STATE` (the binary's stored `go+0x27c`) — the single source of
-    /// 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.
+    /// The stored `GAMEOBJECT_STATE` (`go+0x27c`), the one truth for animation and collision;
+    /// `None` until first sight.
     state: Option<u32>,
-    /// The state we last *animated* to — resolves which transition motion to play next. Distinct from
-    /// `state` so a caller can change the target while [`drive_go_anim`] still knows the pose we're
-    /// leaving (first sight settles the resting pose **silently** — a door that streams in already open
-    /// must not replay its swing).
+    /// The state last animated to, which picks the next motion; first sight settles silently, so a
+    /// door that streams in open does not swing.
     shown: Option<u32>,
-    /// A pending **one-shot** play, as an `AnimationData.dbc` id — the second, disjoint arm
-    /// 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:
-    ///
-    /// | code | substate | id | producer |
-    /// |------|----------|----|----------|
-    /// | 1    | 0        | 145 Spawn      | object CREATE on wire update-type 3 (**not built**) |
-    /// | 2..5 | 8..11    | 153..156 Custom0-3 | opcode `0xb3` (`anim_id >= 4` rejected) |
-    /// | 6    | 12       | 157 Despawn    | opcode `0x215` — [`DespawnAnimAnnounced`] |
-    ///
-    /// 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 remap (decisions 1086/1404).
+    /// A pending one-shot (an `AnimationData.dbc` id) on the reference's one slot, fed by
+    /// `0x5f8c50(GO, code)` (slot 15) through `0x80b0e0`: code 1 Spawn on an update type 3 create
+    /// (not built), 2..5 Custom0..3 from opcode `0xb3`, 6 Despawn from opcode `0x215`.
     one_shot: Option<u16>,
-    /// The clip armed for the current **TRANSIENT substate**, if any — the completion-retire's
-    /// 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 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).
+    /// The armed transient substate (a motion, or Custom0..3), the reference's one
+    /// `[handler+0x10]` slot; [`retire_transient_anim`] advances it at its window end.
     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 *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 already-playing check (`0x5f39fa`) has refused the re-arm and the
-    /// pose has settled for good.
+    /// The rest pose's armed clip while it is on the re-arm cycle; `None` while a transient owns
+    /// the model, on a frozen leg, and once the already-playing skip has refused a re-arm.
     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
-    /// re-resolve and that re-resolve is emphatically *not* a dispatch (slot 14 routes a resting
-    /// substate through `0x5f4167` → `0x5f3930`, straight past it). Only a genuine change of
-    /// [`Self::state`] — and the completion of a Spawn/Custom substate, slot 14's `0x5f4190` leg —
-    /// re-enters the dispatch, whose first act is `0x5f3cc8 call 0x5f40c0`: drop the object's
-    /// display-sound loop registration ([`GoStateDispatch`]).
+    /// The state last dispatched (`0x5f3cb0(old, new)`, [`GoStateDispatch`]); the retire's
+    /// re-resolve is not a dispatch.
     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 *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
-    /// between a prop that **settles** and one that **cycles** — see [`drive_go_anim`].
+    /// The requested id currently armed (`[block0+0xf8]`, written by op4 `0x71252f`, read by
+    /// `0x712090(model, -1)`), which the already-playing skip compares.
     armed_id: Option<u16>,
 }
 
-/// 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**. 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.
-///
-/// Emitted on a genuine `SetGoState` and on the completion of a **Spawn or Custom** substate
-/// (slot 14's `0x5f4190` leg re-enters the dispatch with `old == new`) — and deliberately *not*
-/// on a resting substate's own re-arm, which slot 14 sends to `0x5f4167` instead, past the
-/// dispatch entirely. That distinction is the whole reason a brazier's `TorchLoop` hums
-/// continuously instead of restarting every band pass.
+/// The dispatch `0x5f3cb0` ran on this entity; its first act (`0x5f3cc8 call 0x5f40c0`) releases
+/// the display-sound loop [`crate::sound::gameobject`] owns. A rest pose's own re-arm
+/// (`0x5f4167`) is no dispatch, so a brazier's `TorchLoop` hums on.
 #[derive(Message)]
 pub(crate) struct GoStateDispatch(pub(crate) Entity);
 
-/// Which completed substates re-enter the state dispatch — slot 14's table
-/// `[0]=0x5f4190 … [8..11]=0x5f4190`, i.e. **Spawn (145) and Custom0..3 (153..156)**, as
-/// `AnimationData.dbc` ids. Every other completed substate is either a transition motion (which
-/// advances to its rest pose through `0x5f413d`/`0x5f414b`/`0x5f4159`) or a rest pose re-arming
-/// itself (`0x5f4167`); neither touches the display-sound loop.
+/// Slot 14 sends a completed Spawn (145) or Custom0..3 (153..156) back through the dispatch
+/// (`0x5f4190`); a motion advances (`0x5f413d`, `0x5f414b`, `0x5f4159`) and a rest pose re-arms
+/// (`0x5f4167`) without it.
 fn completion_redispatches(id: u16) -> bool {
     matches!(id, 145 | 153..=156)
 }
 
-/// The **armed** transient clip — its `AnimationData.dbc` id *and* the graph node the arm actually
-/// landed on. The id alone was enough while every arm took a model's **head** variation; it stops
-/// being enough now that the GameObject arm rolls one (`variationIdx = -1`, see [`drive_go_anim`]),
-/// because two sequences sharing an id are two different nodes and only one of them is playing.
-/// [`retire_transient_anim`] must watch the node that was armed, or it retires against a sibling
-/// variation's (idle) player state and ends the substate on the wrong frame — immediately, for a
-/// variation that was never played.
+/// The armed transient clip. The arm rolls a variation, so [`retire_transient_anim`] watches the
+/// node that was armed, not the id's head.
 #[derive(Clone, Copy)]
 struct Transient {
-    /// The `AnimationData.dbc` id — the reference's `[handler+0x10]` substate identity, what the
-    /// inspector and the despawn pin compare against.
+    /// The `AnimationData.dbc` id, the reference's `[handler+0x10]` substate.
     id: u16,
-    /// The graph node of the clip actually armed: this id's *rolled* variation, not its head.
     node: AnimationNodeIndex,
 }
 
-/// The GameObject's **stored** state — the binary's `go+0x27c`, which is what every consumer reads
-/// (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.
+/// The stored state (`go+0x27c`) every consumer reads (the animation, `usable`, the lock chain's
+/// per-slot Action gate): [`GoAnim::state`] when animated, since it holds what the wire never
+/// sends, else the wire field, else `0`, ACTIVE, the value vmangos omits.
 pub(crate) fn go_state(anim: Option<&GoAnim>, store: &ObjectStore) -> u32 {
     anim.and_then(|a| a.state)
         .or_else(|| store.0.gameobject_state())
         .unwrap_or(GO_STATE_ACTIVE)
 }
 
-/// 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 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"
-/// and "the lid settles shut" are indistinguishable from every card line we had: the GO line said
-/// `state 1 closed(READY)`, which was **true**, while a `Forever` Close motion swung underneath
-/// it. `anim Close(146) · transition · loops` is that bug stated in one hover; `anim Closed(147) ·
-/// rest` is the fix, read the same way.
-///
-/// The newest arm is the **smallest seek** — a cross-fade's fading source is older by construction
-/// — the same pick [`fire_go_anim_events`] makes for the event scan.
+/// The inspector's readout: the armed id (the newest arm, the smallest seek), whether it is a
+/// transient, and its repeat mode; `None` for a static mesh or before any arm.
 pub(crate) fn armed_anim(
     go: &GoAnim,
     player: &AnimationPlayer,
@@ -234,35 +114,11 @@ pub(crate) fn armed_anim(
     ))
 }
 
-/// 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
-/// into `[GO+0x210]`. The handlers fall into exactly two families, and the split is legible in the
-/// **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 makes a naive census of `+0x88` report plausible nonsense).
-///
-/// So the machine is **20 of the 31 types**, not the three we had:
-///
-/// | on the machine | off it |
-/// |----------------|--------|
-/// | 0 DOOR · 1 BUTTON · 2 QUESTGIVER · 3 CHEST · 6 TRAP · 8 SPELL_FOCUS · 9 TEXT · 10 GOOBER · 12 AREADAMAGE · 16 DUELFLAG · 17 FISHINGNODE · 18 SUMMONING_RITUAL · 19 MAILBOX · 23 MEETINGSTONE · 24 FLAGSTAND · 26 FLAGDROP · 27 MINI_GAME · 28 LOTTERY_KIOSK · 29 CAPTURE_POINT · 30 | 4 BINDER · 5 GENERIC · 7 CHAIR · 11 TRANSPORT · 13 CAMERA · 14 MAP_OBJECT · 15 MO_TRANSPORT · 20 AUCTIONHOUSE · 21 GUARDPOST · 22 SPELLCASTER · 25 FISHINGHOLE |
-///
-/// Type **30** is past vmangos's enum but has a real family-A arm in the table, so it is included for
-/// completeness; type **21 GUARDPOST** has no `case` in the source at all and shares the out-of-range
-/// default, which points `[GO+0x210]` at a static placeholder and logs `"BADBASEGAMEOBJECT|%d"`.
-///
-/// The old `0 | 1 | 3` was wrong in both directions — far too narrow, and its stated reason for
-/// excluding GOOBER(10) ("also fires custom-anim + spells, so its path is unverified") was not a
-/// reason the binary recognises: the custom-anim opcode drives a *disjoint* substate family (8..11),
-/// never the lid. Measured against live world data, the narrowing left **1427 spawns** — books,
-/// traps, goobers, questgivers — rendering the loader seed's pose instead of their state's.
-///
-/// A model that doesn't author a skeleton/sequences still falls back to a static mesh (the attach
-/// gate also checks the joints/animations exist), so a lid-less chest simply stays static.
+/// Which types run the state machine: `CGGameObject::LoadBaseObject` switches on the type through
+/// the 31-entry table at `0x5f76cc` (`cmp ecx,0x1e`, unsigned `ja`) into a handler at
+/// `[GO+0x210]`; a `0x1c`-byte handler gets the real `0x5f3c30`/`0x5f3b50` arm, every other size
+/// the base's empty bodies. Type 30 is past vmangos's enum but has a real arm; 21 GUARDPOST has no
+/// case and takes the default, which logs `"BADBASEGAMEOBJECT|%d"`.
 pub(crate) fn go_animates(type_id: i32) -> bool {
     matches!(
         type_id,
@@ -270,62 +126,44 @@ pub(crate) fn go_animates(type_id: i32) -> bool {
     )
 }
 
-/// `GAMEOBJECT_TYPE_DOOR` — type id `0`, the one type a ghost's mover trace drops
-/// ([`publish_ghost_door_exclusions`]). Also the wire default: vmangos omits zero-valued fields, so
-/// an absent `GAMEOBJECT_TYPE_ID` means DOOR.
+/// `GAMEOBJECT_TYPE_DOOR`, the one type a ghost's mover trace drops; also what an absent
+/// `GAMEOBJECT_TYPE_ID` means, since vmangos omits zero-valued fields.
 const GO_TYPE_DOOR: i32 = 0;
 
-/// Which types drop their collision when open (decision 0249): **DOOR(0) / BUTTON(1)** only. A door's
-/// static hull can't swing with the mesh, so an open door is made walkable by disabling the collider —
-/// keyed off the server's wire state, which *is* the door's real passability. A **CHEST(3)** keeps its
-/// collider in every state (you don't walk through an "open" chest), so it is deliberately excluded even
-/// though it now animates.
+/// Types whose collider follows the state: DOOR and BUTTON. The static hull cannot swing with the
+/// mesh, so an open one disables it; a chest keeps its collider in every state.
 fn collision_follows_state(type_id: i32) -> bool {
     matches!(type_id, 0 | 1)
 }
 
-/// Whether a door/button's collider is solid, from its **wire** `GAMEOBJECT_STATE` (decision 0757).
-///
-/// The load-bearing case is `None`. An absent field is not "unknown" — it is the wire default `0`
-/// = `GO_STATE_ACTIVE` = **open**, because vmangos omits zero-valued fields from the create block
-/// (the same law `go_templates` already documents for an absent `GAMEOBJECT_TYPE_ID` meaning
-/// DOOR). Treating it as unknown and bailing left the collider enabled on **every door that spawns
-/// open**, which is the whole of "GameObjects that block passage while visually open": Zul'Gurub's
-/// Forcefield (180497) and Stratholme's `Doodad_SmallPortcullis03/04/08/09` are all `type 0`,
-/// `startOpen = 1`, spawned at `state = 0`. It also explains the GM workaround the reporter found
-/// — toggling the object twice un-sticks it — because the first toggle sends a *non-zero* state,
-/// so the field finally exists on the wire, and the trip back to `0` then reads as a real value.
+/// An absent wire state is `0`, ACTIVE, open: vmangos omits zero-valued fields, so a door that
+/// spawns open (Zul'Gurub's Forcefield 180497) sends none.
 fn collider_is_solid(wire_state: Option<u32>) -> bool {
     wire_state.unwrap_or(GO_STATE_ACTIVE) == GO_STATE_READY
 }
 
-/// A cast launched at a GameObject (`SMSG_SPELL_GO` carrying a `TARGET_FLAG_GAMEOBJECT`), bridged from the
-/// net apply layer to this module (decision 2271). [`open_go_lid`] opens the target's lid/door iff the
-/// spell carries an open-lock effect and the GO is an animated type — the client's `Spell_C` open path.
+/// A cast at a GameObject (`SMSG_SPELL_GO` with `TARGET_FLAG_GAMEOBJECT`), bridged from the net
+/// layer for [`open_go_lid`].
 #[derive(Message, Clone, Copy)]
 pub(crate) struct GoLidOpen {
     pub(crate) go_guid: u64,
     pub(crate) spell_id: u32,
 }
 
-/// A GameObject's one-shot Custom animation (`SMSG_GAMEOBJECT_CUSTOM_ANIM`, decision 1086), bridged
-/// from the net apply layer. The wire's `anim_id` is the Custom index (0..3 → AnimationData ids
-/// 153..156); the reference rejects `anim_id >= 4` in the handler and this side keeps that gate.
-/// The load-bearing sender is the fishing bobber's bite (`anim_id 0` — the splash, arriving beside
-/// the forced state flip and the server's own `SMSG_PLAY_OBJECT_SOUND` splash kit).
+/// `SMSG_GAMEOBJECT_CUSTOM_ANIM`, bridged from the net layer; the fishing bobber's bite sends
+/// `anim_id` 0 beside the forced state flip and the server's `SMSG_PLAY_OBJECT_SOUND`.
 #[derive(Message, Clone, Copy)]
 pub(crate) struct GoCustomAnim {
     pub(crate) go_guid: u64,
     pub(crate) anim_id: u32,
 }
 
-/// What to play for the current `GAMEOBJECT_STATE`: a held **rest** pose (first sight, or a state with no
-/// transition), or a one-shot transition **motion** (the swing) that lands on the new rest pose.
+/// What a `GAMEOBJECT_STATE` plays: a held rest pose, or a one-shot motion onto the new pose.
 #[derive(Clone, Copy, Debug)]
 enum Play {
-    /// Snap to a held pose — no swing (first sight / stream-in).
+    /// Snap to a held pose, no swing (first sight).
     Rest(u16),
-    /// Play a transition motion once, holding its end frame (= the destination rest pose).
+    /// Play a transition motion once, onto the destination rest pose.
     Motion(u16),
 }
 
@@ -337,35 +175,12 @@ impl Play {
     }
 }
 
-/// 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           |
-/// |------------|-------------------|----------------------------|
-/// | 146 Close  | owns Open         | 146 (op4 resolves onward)  |
-/// |            | else              | 147 Closed                 |
-/// | 147 Closed | owns Close        | 147 (op4 resolves onward)  |
-/// |            | else owns Open    | **148 Open, frozen**       |
-/// |            | else              | 0 Stand                    |
-/// | 148 Open   | owns Close        | 148 (op4 resolves onward)  |
-/// |            | else owns Destroy | 150 Destroy                |
-/// |            | else              | 149 Opened                 |
-/// | 149 Opened | owns Open         | 149 (op4 resolves onward)  |
-/// |            | else owns Close   | **146 Close, frozen**      |
-/// |            | else              | 151 Destroyed              |
-///
-/// The returned flag marks the two **frozen** legs, where the reference stands a *motion* clip in for
-/// a missing *rest* pose by arming it at playback rate `0`. That reads correctly because a motion's
-/// frame 0 IS the pose it departs from: Open's first frame is closed, Close's first frame is open —
-/// confirmed in the asset, `G_BookOpenMediumBrown`'s bone-0 rotation being identity at Open's first
-/// key and the full open angle at Close's. Ids outside the door group get no remap at all
-/// (`lea eax,[esi-0x92]; cmp eax,3; ja`).
-///
-/// Before this existed an unowned id simply played **nothing**: the `AnimationPlayer` was never armed
-/// and the skinned mesh sat at bind pose. `AHN_QIRAJ_DOORROOTS` (the Ahn'Qiraj gate's roots, GO type
-/// 1 BUTTON) authors only Stand and Open — no Closed — so it took exactly that path.
+/// The missing-sequence remap (`0x5f3930`): what the arm requests when the model does not own the
+/// id ([`ModelAnimations::owns`], the reference's `0x711960`), by `0x5f3972`'s jump table
+/// `0x5f3b40`, for 146..149 only (`lea eax,[esi-0x92]; cmp eax,3; ja`). Ids: 0 Stand, 146 Close,
+/// 147 Closed, 148 Open, 149 Opened, 150 Destroy, 151 Destroyed; a kept id is one op4 resolves
+/// onward. The flag marks the frozen legs: a motion armed at rate 0 holds its frame 0, the pose it
+/// departs from, in place of the missing rest pose.
 fn remap_missing(anims: &ModelAnimations, id: u16) -> (u16, bool) {
     if anims.owns(id) {
         return (id, false);
@@ -386,8 +201,7 @@ fn remap_missing(anims: &ModelAnimations, id: u16) -> (u16, bool) {
     }
 }
 
-/// The held rest-pose animation-id for a wire `GAMEOBJECT_STATE` (`0x5f3c30`). `None` for an
-/// unmapped state.
+/// The held rest pose for a wire `GAMEOBJECT_STATE` (`0x5f3c30`).
 fn rest_anim(state: u32) -> Option<u16> {
     match state {
         0 => Some(0x95), // ACTIVE  → Opened (held open)
@@ -397,31 +211,20 @@ fn rest_anim(state: u32) -> Option<u16> {
     }
 }
 
-/// 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`) 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
-/// **open** object going destructible (`0 → 2`) rests straight on Destroyed rather than playing the
-/// Destroy swing, because the reference's condition is `OLD == 1`, not "any OLD".
-///
-/// (The reference's conditions are each `OLD == x` **or** `ANIMPROGRESS < 100`. benilla does not read
-/// ANIMPROGRESS yet — see the module doc's deferral — so this is the settled column only, which is
-/// what every state-change we can observe today resolves to.)
+/// The motion for a `prev → cur` change. The reference (`0x5f3cb0`) dispatches on the new state and
+/// plays a motion from one old state only; each condition is also met by `ANIMPROGRESS < 100`,
+/// which benilla does not read.
 fn motion_anim(prev: u32, cur: u32) -> Option<u16> {
     match (prev, cur) {
-        (1, 0) => Some(0x94), // closed → open      : Open motion  (else NEW 0 rests Opened)
-        (0, 1) => Some(0x92), // open   → closed    : Close motion
+        (1, 0) => Some(0x94), // closed → open      : Open
+        (0, 1) => Some(0x92), // open   → closed    : Close
         (2, 1) => Some(0x98), // rebuilt → closed   : Rebuild
-        (1, 2) => Some(0x96), // closed → destroyed : Destroy      (else NEW 2 rests Destroyed)
+        (1, 2) => Some(0x96), // closed → destroyed : Destroy
         _ => None,
     }
 }
 
-/// Resolve the play for a state observation: first sight (`prev` None) snaps the rest pose; a change plays
-/// the transition motion if one exists, else snaps the new rest pose.
+/// First sight snaps the rest pose; a change plays its motion, else snaps the new rest pose.
 fn resolve(prev: Option<u32>, cur: u32) -> Option<Play> {
     match prev {
         None => rest_anim(cur).map(Play::Rest),
@@ -431,15 +234,8 @@ fn resolve(prev: Option<u32>, cur: u32) -> Option<Play> {
     }
 }
 
-/// 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),
-/// and the field EDGE on `GAMEOBJECT_STATE` for any later delta. An unrelated field change (position,
-/// dyn-flags) is not an edge on this dword, so a chest whose wire state is constant is never re-closed by
-/// one — its lid is owned by the loot callers below. That used to need a `last_wire` shadow on the
-/// component; the edge carries the old value itself.
+/// Caller 1, the wire (`0x5f89e0`): seeds the state at first sight, then follows the
+/// `GAMEOBJECT_STATE` edge, so an unrelated field change never re-closes a looted chest.
 #[allow(clippy::type_complexity)]
 fn sync_wire_go_state(
     mut edges: MessageReader<crate::net::FieldChanged>,
@@ -450,9 +246,7 @@ fn sync_wire_go_state(
     )>,
 ) {
     for (store, mut anim) in &mut gos.p0() {
-        // Absent ⇒ the wire default `0` = ACTIVE (decision 0757) — vmangos omits zero fields, so a
-        // door that spawns OPEN sends none. Reading that as "unknown" left `state` at `None`, and
-        // the object rested at its loader pose instead of Opened.
+        // Absent is `0`, ACTIVE: vmangos omits zero fields.
         anim.state = Some(store.0.gameobject_state().unwrap_or(GO_STATE_ACTIVE));
     }
     let mut live = gos.p1();
@@ -468,11 +262,8 @@ fn sync_wire_go_state(
     }
 }
 
-/// Caller 2 (the open-lock spell-go): open a chest lid / locked door when a cast with an open-lock effect
-/// launches at it (`SMSG_SPELL_GO` → [`GoLidOpen`]). Gated on the spell's open-lock effect (the client's
-/// `[spell+0xf4] ∈ {OPEN_LOCK, OPEN_LOCK_ITEM}` test) so a plain unit spell that merely names a GO can't
-/// open it; observer-safe (another player's cast opens the chest you can see, since it resolves the GO
-/// guid from the packet, not our own pending cast). Sets the client state to ACTIVE(0).
+/// Caller 2, the open-lock spell-go: a cast at an animated object opens it when the spell has an
+/// open-lock effect (`[spell+0xf4] ∈ {OPEN_LOCK, OPEN_LOCK_ITEM}`), whoever cast it.
 fn open_go_lid(
     mut opens: MessageReader<GoLidOpen>,
     spells: Option<Res<crate::ui_action::Spells>>,
@@ -496,13 +287,8 @@ fn open_go_lid(
     }
 }
 
-/// Caller 4 (the custom-anim opcode, decision 1086): queue the one-shot Custom play. This is the
-/// **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`]
-/// — a non-animated GO type, or one still streaming in — drops the play, matching
-/// [`open_go_lid`]'s posture.
+/// Caller 4, the custom-anim opcode: queues a one-shot on the separate `0x5f8c50` channel; a guid
+/// with no [`GoAnim`] drops it, and ownership is judged in [`drive_go_anim`].
 fn queue_custom_anim(
     mut plays: MessageReader<GoCustomAnim>,
     index: Res<GuidIndex>,
@@ -510,7 +296,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 (`0x5f8971`)
+            continue; // the reference handler's reject (`0x5f8971`)
         };
         let Some(&e) = index.0.get(&go_guid) else {
             continue;
@@ -521,88 +307,44 @@ 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` — `0x5f8971`: opcode `0xb3` byte `b`, reject
-/// `b >= 4`, substate `8+b`).
+/// The wire Custom index to its `AnimationData` id (`153 + n`); the reference handler (`0x5f8971`)
+/// rejects `anim_id >= 4` and plays substate `8 + n`.
 fn custom_anim_id(anim_id: u32) -> Option<u16> {
     (anim_id < 4).then(|| 153 + anim_id as u16)
 }
 
-/// The server announced this object's **despawn animation** (`SMSG_GAMEOBJECT_DESPAWN_ANIM`,
-/// opcode `0x215`) — the one-shot channel's code 6, [`ANIM_DESPAWN`]. Inserted by the net apply
-/// layer at packet time so it is on the entity *before* the `SMSG_DESTROY_OBJECT` that vmangos
-/// sends in the same server tick is processed: that ordering is the whole mechanism, and it is
-/// why this is a component rather than a message (a message is not read until later in the frame,
-/// by which time the destroy has already freed the entity).
-///
-/// It is **not** GameObject-only — `WorldObject::SendObjectDeSpawnAnim` also fires for a totem's
-/// death and a DynamicObject's expiry, and two vmangos boss scripts send it for objects that keep
-/// living. So this marker asserts nothing on its own: it arms [`GoAnim::one_shot`] if there is a
-/// [`GoAnim`] to arm, and it only defers a destroy that actually arrives ([`PendingDestroy`]).
+/// `SMSG_GAMEOBJECT_DESPAWN_ANIM` arrived: a component inserted at packet time, so it is on the
+/// entity before the same tick's `SMSG_DESTROY_OBJECT` frees it. It asserts nothing alone:
+/// `SendObjectDeSpawnAnim` also fires for totems, DynamicObjects and two boss scripts' living
+/// objects, so it only arms a [`GoAnim`] and defers a destroy that arrives.
 #[derive(Component)]
 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.
-/// 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
-/// after the server has already told the client it is gone.
+/// The reference's pending-destroy mark (`[GO+0xe4]` bit `0x10`), set by the destroy `0x464920` on
+/// a pinned object. Arming a non-resting substate pins (`0x5f3b27 call 0x4683e0`, refcount
+/// `[obj+0xe8]`), slot 14 unpins at the window end (`0x468410`), and the deferred destroy then runs
+/// (`0x46844a call 0x464920`). benilla pins only [`ANIM_DESPAWN`]; an object destroyed
+/// mid-transition still goes at once (not built).
 ///
-/// benilla takes the pin on the ONE substate that produces an observable — 12 / [`ANIM_DESPAWN`],
-/// where the whole play happens after the destroy — and [`release_despawn_pin`] is the release.
-/// A GO destroyed mid-transition (a door frozen half-open by a despawn) is the reference's other
-/// pinned case and still pops instantly here; named, not built (decision 1404).
-///
-/// One deliberate divergence: the reference's `0x464920` returns *before* removing the object from
-/// the manager, so a pinned object stays addressable by guid for the length of its play. benilla
-/// drops the guid from the index at destroy time and keeps only the entity, because a respawn that
-/// reused the guid would otherwise refresh an object already condemned to despawn. Nothing
-/// observable rides on it — the object still draws, and the server has stopped answering for that
-/// guid anyway.
+/// The reference keeps a pinned object addressable by guid while it plays; benilla drops the guid
+/// at destroy time, so a respawn reusing it cannot refresh a condemned object. Nothing observable
+/// differs: the object still draws, and the server no longer answers for that guid.
 #[derive(Component)]
 pub(crate) struct PendingDestroy;
 
-/// Caller 5 (the despawn-anim opcode): arm the one-shot [`ANIM_DESPAWN`] play on an object the
-/// server has announced as despawning — one arm per announcement, exactly as the reference's
-/// single `0x5f8c50(GO, 6)` call is one arm per packet.
-///
-/// `Changed`, not `Added`, and the difference is not pedantry: re-inserting a component that is
-/// already present marks it changed but **not** added, so an object announced a second time
-/// without having died in between (`SendObjectDeSpawnAnim` is a `WorldObject` method — two vmangos
-/// boss scripts call it on objects that go on living) would silently never arm again.
-///
-/// A marked entity with no [`GoAnim`] (a totem, a DynamicObject, a GO type off the machine) simply
-/// isn't matched, and [`release_despawn_pin`] then pops it on its first pass — the ordinary instant
-/// destroy. Model ownership is judged at play time by [`drive_go_anim`], as on the Custom channel.
+/// Caller 5, the despawn-anim opcode: one arm per announcement, as `0x5f8c50(GO, 6)` is one per
+/// packet. `Changed`, not `Added`: a re-inserted component is not added, and a boss script can
+/// announce the same living object twice.
 fn arm_despawn_anim(mut gos: Query<&mut GoAnim, Changed<DespawnAnimAnnounced>>) {
     for mut go in &mut gos {
         go.one_shot = Some(ANIM_DESPAWN);
     }
 }
 
-/// Release the pin: an object whose destroy was deferred ([`PendingDestroy`]) goes away as soon as
-/// it is no longer *playing* its despawn animation — the reference's `0x468410` decrement reaching
-/// zero with the pending-destroy bit set, which runs the deferred `0x464920`.
-///
-/// Runs AFTER [`drive_go_anim`], and that ordering is load-bearing in both directions. On the
-/// arming frame the drive has just set [`GoAnim::transient`], so the object is held; on the frame
-/// [`retire_transient_anim`] clears it (the window ended) nothing re-arms 157, so the release runs.
-/// An entity that never armed anything — no [`GoAnim`], a model that doesn't author 157 — fails the
-/// test on its very first pass and is released the same frame, which is the case for everything
-/// that isn't an egg.
-///
-/// **"Released" is a fade, not a pop** (decision 2198). What the deferred `0x464920` runs into is
-/// the base OnDeactivate `0x6145e0`, which hands the object's model to the `SWModelFadeout`
-/// 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`](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.
+/// Releases a [`PendingDestroy`] object once it is not playing its despawn animation (`0x468410`
+/// reaching zero), after [`drive_go_anim`] so the arming frame holds. Release is a fade, not a
+/// pop: `0x464920` reaches OnDeactivate `0x6145e0`, which hands the model to the `SWModelFadeout`
+/// scheduler `0x672df0`; here that is [`crate::net::tear_down`].
 fn release_despawn_pin(
     mut commands: Commands,
     pinned: Query<(Entity, Option<&GoAnim>), With<PendingDestroy>>,
@@ -618,11 +360,8 @@ fn release_despawn_pin(
     }
 }
 
-/// Caller 3 (the loot-release): close a chest lid when its loot window closes. The client sends
-/// `CMSG_LOOT_RELEASE` and immediately drops the state to READY(1) — no server round-trip. We watch the
-/// open loot source guid change (any close path: the player's close, or the server's release when the last
-/// item is looted) and close the lid iff the guid that just closed is an animated GO — a looted corpse or
-/// creature resolves to an entity without [`GoAnim`], so `get_mut` misses it and nothing happens.
+/// Caller 3, the loot release: the client drops the state to READY as it sends
+/// `CMSG_LOOT_RELEASE`, with no server round-trip, on any close of the loot source.
 fn close_go_lid(
     loot: Res<crate::ui_loot::LootState>,
     index: Res<GuidIndex>,
@@ -643,50 +382,21 @@ fn close_go_lid(
     *last_source = current;
 }
 
-/// 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:
+/// The substate advance. The completion callback registered at model attach (`0x5f7d43` →
+/// `[M2+0x70]`) fires once at the arm's window end, span × replay count, whatever the loop bit
+/// (`0x719370`; `0x719503` tests it after), and slot 14 (`0x5f4120`) dispatches on the substate:
+/// a motion advances to its rest pose (2 Open → 3 Opened, 4 Close → 1 Closed, 5 Destroy →
+/// 6 Destroyed, 7 Rebuild → 1 Closed); Spawn (0) and Custom0..3 (8..11) re-run the machine at the
+/// current state (`0x5f4190`); a rest pose (1/3/6) re-arms itself with a fresh roll (`0x5f4167`,
+/// calling `0x5f3930` past slot 34's change guard), every window for ever.
 ///
-/// | completed substate | advances to | i.e. |
-/// |--------------------|-------------|------|
-/// | 2 Open             | 3 Opened    | the swing settles open |
-/// | 4 Close            | 1 Closed    | the lid settles shut |
-/// | 5 Destroy          | 6 Destroyed | |
-/// | 7 Rebuild          | 1 Closed    | |
-/// | 0 Spawn, 8..11 Custom0-3 | re-run at the current state (`0x5f4190`) | |
-/// | 1/3/6 (a rest pose) | **itself** (`0x5f4167`) | the held pose re-arms, with a fresh variation roll |
-///
-/// **This — not the animation kernel — is what turns a transition clip into a resting state**, and
-/// it is why the kernel's loop bit is not the transition's duration: `G_Crate01`'s Close is
-/// `flags` bit 0 clear, so the *pose* would wrap for ever, and only this advance ends it. For the
-/// bobber's Custom0 the re-run resolves 149 → 151 → the lookup's all-fallback rows → **Stand**,
-/// landing one frame after the 1333 ms window — before the looping kernel's second `$GC0` crossing
-/// at 1533 ms. Net law: one splash per 0xB3, one swing per state change, then the state pose.
-///
-/// **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. 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
-/// state arm of [`drive_go_anim`] re-resolve the current state as a fresh rest pose — our
-/// state-machine re-run, and (for a motion) exactly the table above, since `rest_anim(state)` is
-/// the destination row of whichever motion that state's change armed. Runs before
-/// [`drive_go_anim`] in the chain so the re-arm lands the same frame. Reads never deref-mut, so a
-/// quiet GO stays out of the Changed stream.
+/// Clearing `shown` makes [`drive_go_anim`], next in the chain, re-resolve the state that frame.
+/// Reads never deref-mut, so a quiet object stays out of the `Changed` stream.
 fn retire_transient_anim(
     mut gos: Query<(Entity, &mut GoAnim, &AnimationPlayer)>,
     mut dispatch: MessageWriter<GoStateDispatch>,
 ) {
     for (entity, mut go, player) in &mut gos {
-        // The ARMED node, not `find(id)`'s head variation — see [`Transient::node`].
         let done = |n| {
             player
                 .animation(n)
@@ -695,25 +405,17 @@ fn retire_transient_anim(
         if let Some(t) = go.transient {
             if done(t.node) {
                 go.transient = None;
-                // The completion's state-machine re-run: forget the shown pose so the state arm
-                // re-resolves it (a silent rest snap — `resolve(None, state)`), exactly the
-                // reference's re-arm over the finished transient block.
+                // Forget the shown pose: the state arm re-resolves it as a silent rest snap.
                 go.shown = None;
-                // A Spawn/Custom completion re-enters `0x5f3cb0` with `old == new`, and that
-                // dispatch drops the object's display-sound loop — which is what ends the
-                // GnomeMachine's Custom0 hum at the end of its clip rather than leaving it
-                // droning. A transition motion's completion takes a different slot-14 row and
-                // does not.
+                // Re-enters `0x5f3cb0` with `old == new`: a GnomeMachine's Custom0 hum ends here.
                 if completion_redispatches(t.id) {
                     dispatch.write(GoStateDispatch(entity));
                 }
             }
             continue;
         }
-        // A REST pose completes too, and its completion re-arms *itself* — see [`drive_go_anim`]'s
-        // rest arm. Same device: forget the shown pose and the state arm re-resolves it, rolling a
-        // fresh variation. `rest_window` is cleared first so a refused re-arm settles instead of
-        // spinning.
+        // A rest pose re-arms the same way; `rest_window` clears first so a refused re-arm
+        // settles instead of spinning.
         if let Some(node) = go.rest_window {
             if done(node) {
                 go.rest_window = None;
@@ -723,19 +425,9 @@ 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 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:
-/// the per-sequence material lanes (2295) key their UV and tint loops by `seq_index`, so *which
-/// take is armed* is what decides whether a Blood of Heroes pool bubbles at all (slot 0 authors no
-/// texture transform, slot 1 does) and whether an Onyxia lava trap spurts. From outside, an arm
-/// that re-rolls every window and one that armed once and stalled look identical — both are "a
-/// still pool" for as long as you happen to watch — and the three legs that produce the difference
-/// (`0x5f39fa`'s already-armed skip, the collapse-to-0 leg that jumps past it, the completion that
-/// re-enters through slot 14) are invisible in a screenshot. One line per arm makes the cycle,
-/// its period and its distribution readable directly.
+/// The arm's trace (`WOW_MOVE_TRACE_TAGS=goa`): requested and remapped id, roll, and the sequence
+/// slot landed on, which picks the material lanes (keyed by `seq_index`) and shows whether an arm
+/// re-rolls every window or stalls (`0x5f39fa`'s skip).
 fn trace_arm(
     entity: Entity,
     lane: &str,
@@ -760,9 +452,8 @@ fn trace_arm(
     );
 }
 
-/// 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.
+/// Plays the sequence for a change of [`GoAnim::state`], first sight silent, as
+/// [`crate::sound::gameobject`] does for the audio.
 fn drive_go_anim(
     mut gos: Query<
         (
@@ -775,8 +466,7 @@ fn drive_go_anim(
         Changed<GoAnim>,
     >,
     mut dispatch: MessageWriter<GoStateDispatch>,
-    // The client's single `_rand` stream (`0x7400e5`), as `creature_anim` keeps
-    // one: op4's variation roll draws from it on every GameObject arm below.
+    // The client's single `_rand` stream (`0x7400e5`); op4's variation roll draws from it.
     mut rng: ResMut<benilla_assets::AnimRng>,
 ) {
     for (entity, mut go, mut player, mut tr, anims) in &mut gos {
@@ -785,55 +475,35 @@ fn drive_go_anim(
             if go.shown != Some(state) {
                 let prev = go.shown;
                 go.shown = Some(state);
-                // `0x5f3cb0` proper — announced before anything below can refuse the arm, because
-                // the reference releases the display-sound loop at the head of the dispatch and
-                // *then* picks a substate. A re-resolve driven by [`retire_transient_anim`]
-                // leaves `dispatched` alone and so announces nothing (see [`GoAnim::dispatched`]).
+                // Dispatch (`0x5f3cb0`) before anything below can refuse the arm; a re-resolve
+                // from the retire leaves `dispatched` alone and announces nothing.
                 if go.dispatched != Some(state) {
                     go.dispatched = Some(state);
                     dispatch.write(GoStateDispatch(entity));
                 }
-                // A fresh substate replaces whatever transient one was live — the reference keeps
-                // exactly ONE (`[handler+0x10]`), so an old motion's completion can never fire
-                // over the pose that superseded it.
+                // A fresh substate replaces the live transient (the reference keeps one,
+                // `[handler+0x10]`), so an old motion's completion never fires over it.
                 go.transient = None;
                 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 remap for a model that doesn't author
-                    // it — that is what keeps a lidless model on a real pose instead of bind.
+                    // Remap an unowned id, so a lidless model holds a real pose, not bind.
                     let (want, frozen) = remap_missing(anims, play.anim_id());
-                    // **`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
-                    // behaviour that never plays. Onyxia's lava traps are the case that named it:
-                    // `ONYZIASLAIRLAVATRAP.M2` authors Stand twice — seq 0 (`freq` 29491, looping,
-                    // silent) and seq 1 (`freq` 3276, one-shot) — and it is seq **1** that carries
-                    // 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 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
-                    // PAST the check). Only the other remap legs fall through `0x5f39fa`'s
-                    // `cmp esi,eax; je 0x5f3b32`, and there a re-arm requesting what is already
-                    // armed is refused — so a prop the remap sent to a *non-zero* substitute
-                    // settles on it (the fishing bobber), while one that owns its id or collapsed
-                    // to Stand re-arms, and re-rolls, every window (the lava trap).
+                    // The already-playing skip (`0x5f39fa: cmp esi,eax; je 0x5f3b32`) holds only
+                    // on the remap legs: an owned id (`0x5f396c jne`) and the collapse to Stand
+                    // (`0x5f3a54 jmp 0x5f3a0b`) jump past it. So the remapped fishing bobber
+                    // settles, and a lava trap that owns its id re-rolls every window.
                     let skip =
                         want != 0 && !anims.owns(play.anim_id()) && go.armed_id == Some(want);
                     if skip {
                         continue;
                     }
+                    // The arm rolls a variation (`0x5f3aee: push -1`); the loader seed takes 0
+                    // (`0x710189`).
                     let roll = rng.draw();
                     if let Some(clip) = anims.pick_variation(want, roll) {
                         trace_arm(entity, "state", play.anim_id(), want, frozen, roll, clip);
                         go.armed_id = Some(want);
-                        // Snap a rest pose (blend 0 — a stream-in must not swing); ease a motion
-                        // over its authored blend.
+                        // Snap a rest pose; ease a motion over its authored blend.
                         let blend = match play {
                             Play::Rest(_) => 0.0,
                             Play::Motion(_) => clip.blend_time.max(0.0),
@@ -841,35 +511,17 @@ fn drive_go_anim(
                         let node = clip.node;
                         let active = tr.play(&mut player, node, Duration::from_secs_f32(blend));
                         if frozen {
-                            // A motion standing in for a missing rest pose: the reference arms it
-                            // at playback rate 0, so it holds frame 0 forever — the pose that
-                            // motion departs from.
+                            // The reference arms a stand-in motion at rate 0, holding frame 0.
                             active.seek_to(0.0);
                             active.set_speed(0.0);
                             active.set_repeat(RepeatAnimation::Never);
                         } else {
-                            // Explicit, not defaulted: `AnimationTransitions::play` →
-                            // `AnimationPlayer::start` only `replay()`s the node, which rewinds the
-                            // clock but keeps `speed` — so re-arming a node a frozen leg previously
-                            // parked at rate 0 (the same Open clip serves both) would stay stuck.
+                            // Explicit: `AnimationTransitions::play` keeps a node's speed, so one
+                            // a frozen leg parked at rate 0 would stay stuck.
                             active.set_speed(1.0);
-                            // **ONE baked window, rest pose included** (decision 1151 for the
-                            // 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
-                            // slot 14's row for a resting substate, `0x5f4167`, calls `0x5f3930`
-                            // *directly*, past slot 34's change guard, on an unchanged substate.
-                            // The arm is therefore re-issued every ~`span` ms with a fresh
-                            // `variationIdx = -1` roll, for ever. For a single-variation id that
-                            // is the loop it always was, restarted at its own band start; for a
-                            // chain it is the whole point — Onyxia's traps re-roll every 867 ms at
-                            // 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 (`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.
+                            // One window, rest poses included: the period is `0x7126d8`'s, with
+                            // `R = 1` from a `(0,0)` replay pair (`0x7126c3`). Which per-frame
+                            // advance list a GameObject's model rides is untraced.
                             active.set_repeat(RepeatAnimation::Never);
                             match play {
                                 Play::Motion(_) => {
@@ -879,29 +531,18 @@ fn drive_go_anim(
                             }
                         }
                     }
-                    // else: nothing playable even after the remap — hold whatever the loader
-                    // seed armed.
+                    // Else nothing is playable after the remap, and the loader seed's arm holds.
                 }
             }
         }
-        // ── 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 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
-        // end (span × replay-count; the bobber's replay pair is 0..0 ⇒ one 1333 ms pass) and
-        // re-runs the state machine, overwriting the Custom block before a second pass begins.
-        // `RepeatAnimation::Never` + [`retire_transient_anim`] reproduce that endpoint exactly: one
-        // pass, one `$GC0` splash, then the state pose — never a churning loop.
-        // (`is_some` pre-check: an unconditional `take()` mut-derefs the `Mut` and re-marks the
-        // component Changed every frame, keeping this Changed-filtered query hot forever.)
+        // ── The one-shot Custom channel (`0x5f8c50`) ────────────────────────────────────────
+        // After the state arm, so the bobber's same-frame flip and splash end splash-on-top. Slot
+        // 15 needs the model to own the id (no remap); one window, so one `$GC0` splash.
+        // `is_some` first: `take()` through the `Mut` would mark the component changed every frame.
         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,
-                // so it rolls a variation for the same reason — a Custom0 with two authored
-                // takes alternates them.
+                // Slot 15 arms through the same `0x5f3930`, so it rolls a variation too.
                 let roll = rng.draw();
                 if let Some(clip) = anims.pick_variation(id, roll) {
                     trace_arm(entity, "custom", id, id, false, roll, clip);
@@ -922,28 +563,10 @@ fn drive_go_anim(
     }
 }
 
-/// Gate a door/button's collision on its state: solid when **closed** (`GO_STATE_READY`), passable when
-/// **open** (decision 0249). The model's collision is a single static hull (not bone-bound — it *can't*
-/// swing with the mesh), so an open door is made walkable by disabling the collider, not by moving it —
-/// the client's only option, and the faithful one. Keyed off the **wire** state (a door's real
-/// passability is the server's, and it holds for an animation-less door too — no [`GoAnim`] required), and
-/// scoped to the door/button types ([`collision_follows_state`]); a chest keeps its collider whatever its
-/// state.
-///
-/// **Reconciles on a `GAMEOBJECT_STATE` edge OR on the collider's arrival** (idempotent either way).
-/// The `Added<Collider>` half is load-bearing, not belt-and-braces (decision 0763): a streamed
-/// GameObject's descriptor lands with the create block, but its `Collider` is baked from the M2
-/// hull and inserted by `entities::attach` only when the **asset finishes loading**, frames later.
-/// Watching the descriptor alone meant the two conditions were never true in the same frame
-/// for a freshly streamed object — the descriptor changed while there was no collider, the collider
-/// arrived while the descriptor was quiet — so the reconcile never ran at all, and every door kept
-/// the enabled collider it was born with. A *closed* door is solid by default and looked correct;
-/// an **open** one stayed solid, which is the entire reported symptom. It also explains the
-/// reporter's workaround exactly: toggling the object from the GM panel changes the descriptor
-/// *after* the collider exists, so the reconcile finally fires.
-///
-/// The descriptor half is the field edge on the one dword this reads (decision 2297) — the same
-/// seed-plus-edge pair [`sync_wire_go_state`] uses.
+/// Gates a door or button's collider on its wire state, the server's passability: solid when
+/// READY, disabled when open, since the static hull cannot swing. Reconciles on a state edge or on
+/// the collider's arrival, which `entities::attach` inserts only once the M2 loads, frames after
+/// the descriptor.
 fn drive_go_collision(
     mut commands: Commands,
     gos: Query<(&ObjectStore, Has<ColliderDisabled>), With<Collider>>,
@@ -972,28 +595,10 @@ fn drive_go_collision(
     }
 }
 
-/// **A ghost walks through closed doors** — publish the door set the local mover's trace must
-/// drop, which is [`benilla_world::collision::MoverTraceExclusions`]' only producer.
-///
-/// The reference builds a per-trace collision mask, and the local mover's mask gains bit `0x8000`
-/// when the body it drives is a player carrying `PLAYER_FLAGS` bit `0x10` (GHOST) — `0x631658`,
-/// off `OBJECT_FIELD_TYPE & TYPEMASK_PLAYER` plus the flag, pinned against the `UnitIsGhost`
-/// 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
-/// (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
-/// creature has no block for answers false on its own, which is the same guard the byte order
-/// gives.
-///
-/// **DOOR only** — not BUTTON, which shares the state-driven collider lane in
-/// [`drive_go_collision`] but is a different type id, and the predicate is an equality against `0`.
-/// Note that an absent `GAMEOBJECT_TYPE_ID` *is* DOOR (vmangos omits zero-valued fields), which is
-/// why the scan is scoped by [`EntityKind::GameObject`]: read across every `ObjectStore` the same
-/// absence would make a DOOR of every unit in the world.
+/// A ghost walks through doors: the mover's mask gains bit `0x8000` for a player body with
+/// `PLAYER_FLAGS` ghost bit `0x10` (`0x631658`), and `CGGameObject_C`'s candidacy virtual
+/// (`0x5f85f0`, vtable `+0x50`) tests it at `0x5f85f6` to refuse type DOOR. Nothing else about a
+/// ghost's collision differs; the flag is the mover's, so a possessed creature never sets it.
 fn publish_ghost_door_exclusions(
     mut exclusions: ResMut<benilla_world::collision::MoverTraceExclusions>,
     mover: Query<&ObjectStore, With<crate::net::Embodied>>,
@@ -1001,8 +606,7 @@ fn publish_ghost_door_exclusions(
 ) {
     let ghost = mover.single().is_ok_and(|s| s.0.player_is_ghost());
     if !ghost {
-        // The overwhelmingly common frame. Clearing only when non-empty keeps this off the
-        // change-detection wire for the whole of a living session.
+        // Clear only when non-empty, so a living player's frames never trip change detection.
         if !exclusions.0.is_empty() {
             exclusions.0.clear();
         }
@@ -1017,19 +621,14 @@ fn publish_ghost_door_exclusions(
     );
 }
 
-/// Is this collider one a **ghost's** mover trace drops — a GameObject of type DOOR?
-///
-/// The kind test is not redundant with the type test, and that is the whole reason this is a named
-/// function. An absent `GAMEOBJECT_TYPE_ID` reads as `0` = DOOR (vmangos omits zero-valued fields,
-/// the law `go_templates` already documents), and a **unit** has no GameObject block at all — so a
-/// scan that asked only about the type id would answer DOOR for every creature and player in the
-/// world and quietly delete them from the mover's trace.
+/// Whether a ghost's mover trace drops this collider: a GameObject of type DOOR. The kind test
+/// matters: an absent `GAMEOBJECT_TYPE_ID` reads `0`, DOOR, and a unit has no GameObject block.
 fn ghost_passable(kind: benilla_protocol::EntityKind, type_id: i32) -> bool {
     kind == benilla_protocol::EntityKind::GameObject && type_id == GO_TYPE_DOOR
 }
 
-/// What the GameObject event scanner reads per object: its clock, its park state, and the frame
-/// its fired keys resolve in ([`crate::creature_anim::EventFrame`]).
+/// What the event scanner reads per object: its clock, its park state, and the frame its fired
+/// keys resolve in ([`crate::creature_anim::EventFrame`]).
 type ScannedGo = (
     Entity,
     &'static ModelAnimations,
@@ -1039,24 +638,11 @@ type ScannedGo = (
     Option<&'static benilla_world::rig_anim::RigPose>,
 );
 
-/// Fire the event keyframes an animated GameObject's playing clip crossed this frame — the GO
-/// 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`/
-/// `$DSL` audio arms apply as-is, and the GO-only display-slot family (`$GO0..5`/`$GC0..3` →
-/// `GameObjectDisplayInfo.Sound[0..9]`) is routed by [`crate::sound::gameobject`]. The
-/// load-bearing tenant: the fishing bobber's Custom0 clip authors `$GC0` at t≈3.87 s — the
-/// splash sound the real client plays from the *animation*, beside the server's explicit
-/// object-sound packet (the audible double, faithful to the reference on vmangos).
-///
-/// The playing clip is found as the creature scanner finds a variation track: of the clips with
-/// a live [`AnimationPlayer`] play, the smallest seek is the newest arm (a cross-fade's fading
-/// source is older by construction). The shared [`advance_track`]/[`scan_events`] helpers give
-/// the same arming rules — an arm frame fires nothing, the frame after it fires the clip's `t = 0`
-/// head, a loop wrap fires tail-then-head — and a frozen rate-0 leg never advances, so it never
-/// fires.
+/// Fires the event keys an animated object's clip crossed this frame. The reference registers an
+/// event callback per family-A object (`0x5f7d1f` → vtable `+0x30` → `0x5f3e20`), the [`GoAnim`]
+/// population; [`crate::sound::gameobject`] routes `$GO0..5`/`$GC0..3` to
+/// `GameObjectDisplayInfo.Sound[0..9]`. The bobber's Custom0 `$GC0` splash plays beside the
+/// server's object-sound packet, so on vmangos it sounds twice, as in the reference.
 fn fire_go_anim_events(
     gos: Query<ScannedGo, With<GoAnim>>,
     globals: Query<&GlobalTransform>,
@@ -1064,10 +650,8 @@ fn fire_go_anim_events(
     mut out: MessageWriter<AnimSoundEvent>,
 ) {
     for (entity, anims, player, parked, world, pose) in &gos {
-        // The election's tick half, GO twin (decision 1482): a parked GO's event track is not
-        // scanned — and there is no `MORE_AUDIBLE` exception here, because the flag lives on
-        // CREATURE templates only (the reference's re-link arm reads the creature query cache).
-        // Memory dropped so a wake re-arms instead of scanning the parked gap as one crossing.
+        // A parked object is not scanned (`MORE_AUDIBLE` is creature-only); its memory drops so
+        // a wake re-arms rather than scanning the gap as one crossing.
         if parked {
             last.remove(&entity);
             continue;
@@ -1089,10 +673,8 @@ fn fire_go_anim_events(
     }
 }
 
-/// Registration hook, mirrored on [`crate::sound::gameobject`]'s: the three state callers write
-/// [`GoAnim::state`], then the animation + collision consumers act on it, after the Net drain wrote this
-/// frame's descriptor deltas + queued the open-lock [`GoLidOpen`]. The event scanner runs last —
-/// it reads the clip/seek state the drive just settled.
+/// After the net drain, the state callers write [`GoAnim::state`], the animation and collision
+/// consumers act on it, and the event scanner reads what the drive settled.
 pub(crate) fn plugin(app: &mut App) {
     app.add_message::<GoLidOpen>()
         .add_message::<GoCustomAnim>()
@@ -1106,23 +688,20 @@ pub(crate) fn plugin(app: &mut App) {
                     close_go_lid,
                     queue_custom_anim,
                     arm_despawn_anim,
-                    // The completion retire reads last frame's finished flags and must clear
-                    // `shown` BEFORE the drive, so its state re-arm lands this frame — the
-                    // reference's own one-frame-after-window-end timing.
+                    // Clears `shown` from last frame's finished flags before the drive, so the
+                    // re-arm lands one frame after the window end, as in the reference.
                     retire_transient_anim,
                 ),
                 (drive_go_anim, drive_go_collision),
-                // The pin release reads what the drive just armed — see its doc for why AFTER.
+                // The pin release reads what the drive just armed.
                 release_despawn_pin,
                 fire_go_anim_events,
             )
                 .chain()
                 .in_set(WorldStage::Present),
         );
-    // Ahead of the mover, not with the GO drive above: the set it publishes is read by
-    // `WorldCollision::cast_mover` inside the player controller, which runs in `Input`.
-    // Publishing in `Present` would hand the mover the previous frame's doors — imperceptible,
-    // but there is no reason to owe it.
+    // In `Input`, ahead of the mover: `WorldCollision::cast_mover` reads the set inside the
+    // player controller, and `Present` would hand it the previous frame's doors.
     app.add_systems(
         Update,
         publish_ghost_door_exclusions.in_set(WorldStage::Input),
@@ -1134,12 +713,7 @@ mod tests {
     use super::*;
     use benilla_world::model_fade::DespawnFade;
 
-    /// **A ghost's mover drops DOOR GameObjects — and nothing else** (decision 1767).
-    ///
-    /// The third case is the one this test exists for. `GAMEOBJECT_TYPE_ID` is absent on a unit,
-    /// and an absent field reads `0`, which *is* DOOR — so the type id alone says "door" for every
-    /// creature and player in the world. Excluding those from the mover's trace would mean walking
-    /// through units while dead, from a change that never mentions them.
+    /// An absent `GAMEOBJECT_TYPE_ID` reads `0`, DOOR, on every unit, so the kind must be checked.
     #[test]
     fn a_ghosts_trace_drops_doors_and_only_doors() {
         use benilla_protocol::EntityKind;
@@ -1163,51 +737,43 @@ mod tests {
         );
     }
 
-    /// The wire default that let open doors block (decision 0757). `None` must read ACTIVE/open,
-    /// never "unknown" — vmangos omits the zero-valued field, so `None` IS the open state for
-    /// every door that spawns open (ZG's Forcefield, Stratholme's small portcullises).
+    /// vmangos omits the zero field, so `None` is ACTIVE, open, for every door that spawns open.
     #[test]
     fn an_absent_wire_state_is_open_not_unknown() {
         assert!(!collider_is_solid(None), "absent == ACTIVE(0) == passable");
         assert!(!collider_is_solid(Some(GO_STATE_ACTIVE)));
         assert!(collider_is_solid(Some(GO_STATE_READY)));
-        // ALTERNATIVE (destroyed) is passable too — only READY is solid.
+        // ALTERNATIVE (destroyed) is passable too; only READY is solid.
         assert!(!collider_is_solid(Some(2)));
     }
 
     #[test]
     fn rest_poses_match_the_verified_table() {
         assert_eq!(rest_anim(1), Some(0x93)); // READY  → Closed
-        assert_eq!(rest_anim(0), Some(0x95)); // ACTIVE → Opened (not the 0x94 Open *motion*)
+        assert_eq!(rest_anim(0), Some(0x95)); // ACTIVE → Opened (not the 0x94 Open motion)
         assert_eq!(rest_anim(2), Some(0x97)); // ALT    → Destroyed
         assert_eq!(rest_anim(7), None);
     }
 
     #[test]
     fn transitions_play_the_motion_then_settle() {
-        // closed → open swings the Open motion (0x94), open → closed the Close motion (0x92).
         assert!(matches!(resolve(Some(1), 0), Some(Play::Motion(0x94))));
         assert!(matches!(resolve(Some(0), 1), Some(Play::Motion(0x92))));
-        // First sight snaps the rest pose, never a motion (a door streamed in open must not swing).
+        // First sight snaps the rest pose: a door streamed in open must not swing.
         assert!(matches!(resolve(None, 0), Some(Play::Rest(0x95))));
         assert!(matches!(resolve(None, 1), Some(Play::Rest(0x93))));
-        // A change with no distinct motion snaps the destination rest pose.
         assert!(matches!(resolve(Some(2), 0), Some(Play::Rest(0x95))));
-        // The destructible row dispatches on OLD too: only a CLOSED object swings Destroy; an open
-        // one rests straight on Destroyed (`0x5f3cb0`'s condition is `OLD == 1`, not any OLD).
+        // Destroy swings only from closed (`0x5f3cb0`'s condition is `OLD == 1`).
         assert!(matches!(resolve(Some(1), 2), Some(Play::Motion(0x96))));
         assert!(matches!(resolve(Some(0), 2), Some(Play::Rest(0x97))));
-        // …and the rebuild leg stays the motion it always was.
         assert!(matches!(resolve(Some(2), 1), Some(Play::Motion(0x98))));
     }
 
-    /// 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.
+    /// The custom-anim handler (`0x5f8930`); the bobber's bite, index 0 → 153, is the second
+    /// sequence `G_FishingBobber.m2` authors.
     #[test]
     fn custom_anim_maps_the_wire_index_and_rejects_past_3() {
-        assert_eq!(custom_anim_id(0), Some(153)); // Custom0 — the bobber splash
+        assert_eq!(custom_anim_id(0), Some(153)); // Custom0, the bobber splash
         assert_eq!(custom_anim_id(1), Some(154));
         assert_eq!(custom_anim_id(2), Some(155));
         assert_eq!(custom_anim_id(3), Some(156));
@@ -1215,11 +781,8 @@ mod tests {
         assert_eq!(custom_anim_id(u32::MAX), None);
     }
 
-    /// The delta [`step_clock`] uses for the next frame — the same device as the creature
-    /// driver's harness (`creature_anim/driver/tests.rs`) and for the same reason: with
-    /// `TimePlugin` live, `Time`'s delta is the REAL gap between two `app.update()` calls, so a
-    /// stalled frame on a loaded machine runs a whole clip out in one step and the assertions
-    /// below become a coin flip. Here the clock is a number the test writes.
+    /// The delta [`step_clock`] uses next frame: with `TimePlugin` live a stalled frame would run
+    /// a whole clip out in one step, so the test writes the clock.
     #[derive(Resource, Default)]
     struct NextStep(Option<Duration>);
 
@@ -1233,19 +796,16 @@ mod tests {
         app.update();
     }
 
-    /// `G_Crate01`'s door family, as the bytes have it (pinned against the shipped asset by
-    /// `benilla-formats/tests/m2_go_crate_lid.rs`): Open/Opened/Close/Closed, **all four `looping`**
-    /// — `flags` bit 0 clear — with an empty replay range. Blend times are zeroed so the arm is a
-    /// cut and the assertions read the armed clip, not a fade.
+    /// `G_Crate01`'s door family as the asset has it (`benilla-formats/tests/m2_go_crate_lid.rs`):
+    /// all four `flags` bit 0 clear, empty replay range; blend zeroed so an arm is a cut.
     const CRATE_FAMILY: [(u16, f32, u16); 4] = [
-        (0x94, 0.666, 0),     // 148 Open   — the lid sweeps 0° → 75°
-        (0x95, 0.100, 0),     // 149 Opened — holds 75°
-        (0x92, 0.667, 0),     // 146 Close  — sweeps 75° → 0°
-        (0x93, 0.167, 29491), // 147 Closed — holds 0° (the chain HEAD, weighted like the traps')
+        (0x94, 0.666, 0),     // 148 Open: the lid sweeps 0° → 75°
+        (0x95, 0.100, 0),     // 149 Opened: holds 75°
+        (0x92, 0.667, 0),     // 146 Close: sweeps 75° → 0°
+        (0x93, 0.167, 29491), // 147 Closed: holds 0° (the chain head, weighted like the traps')
     ];
 
-    /// An app running the two systems this file's law lives in, plus one GameObject wearing a
-    /// crate's animation set: REAL `AnimationClip` assets and a real graph, so Bevy's own
+    /// One GameObject with a crate's animation set, real `AnimationClip`s and graph, so Bevy's
     /// `advance_animations` ticks the completions [`retire_transient_anim`] watches.
     fn crate_app(extra_ids: &[(u16, f32, u16)]) -> (App, Entity) {
         use bevy::animation::graph::{AnimationGraph, AnimationGraphHandle};
@@ -1259,10 +819,8 @@ mod tests {
         ));
         app.init_resource::<Time>();
         app.init_resource::<NextStep>();
-        // The client's ONE `rand()` stream (2301) — the arm rolls a variation off it.
         app.init_resource::<benilla_assets::AnimRng>();
-        // The state dispatch's audio consumer lives in `sound::gameobject`; here it is recorded
-        // instead, so a test can assert *which* edges re-enter `0x5f3cb0`.
+        // Recorded in place of the audio consumer.
         app.add_message::<GoStateDispatch>();
         app.init_resource::<Dispatched>();
         app.add_systems(bevy::app::First, step_clock);
@@ -1297,8 +855,8 @@ mod tests {
 
         let mut lookup = vec![0xffffu16; 160];
         for (slot, &(id, _, _)) in authored.iter().enumerate() {
-            // A variation chain shares one id, and `animationLookup` holds its HEAD — so only the
-            // first slot claiming an id writes here, exactly as the exporter bakes it.
+            // `animationLookup` holds a chain's head: only the first slot claiming an id writes,
+            // as the exporter bakes it.
             if lookup[id as usize] == 0xffff {
                 lookup[id as usize] = slot as u16;
             }
@@ -1312,8 +870,7 @@ mod tests {
                     anim_id: id,
                     seq_index: 0,
                     node,
-                    // The asset fact this whole record turns on: the crate's transitions are
-                    // bit-0-clear bands, i.e. the kernel loops them.
+                    // The crate's clips are bit-0-clear bands: the kernel loops them.
                     looping: true,
                     duration: dur,
                     move_speed: 0.0,
@@ -1337,7 +894,7 @@ mod tests {
             first_seq: None,
             pose: Default::default(),
         };
-        // First sight is a closed chest, exactly as it streams in.
+        // First sight is a closed chest, as it streams in.
         let go = app
             .world_mut()
             .spawn((
@@ -1354,8 +911,7 @@ mod tests {
         (app, go)
     }
 
-    /// Every [`GoStateDispatch`] the run has produced, in order — the audio consumer's input,
-    /// stood in for.
+    /// Every [`GoStateDispatch`] the run produced, in order, in place of the audio consumer.
     #[derive(Resource, Default)]
     struct Dispatched(Vec<Entity>);
 
@@ -1379,16 +935,8 @@ mod tests {
         ))
     }
 
-    /// **The report** (decision 1151): loot the crate, close the loot window, and the lid must
-    /// settle SHUT — not spring open and slam once a window, for ever.
-    ///
-    /// 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 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
-    /// wide, the crate must still be holding Closed.
+    /// The door family is `flags` bit 0 clear, so arming by the loop bit would swing Close for
+    /// ever; the reference ends it at the window (slot 14 `0x5f4120`: 4 Close → 1 Closed).
     #[test]
     fn the_looted_crate_settles_shut_instead_of_flapping_for_ever() {
         let (mut app, go) = crate_app(&[]);
@@ -1400,15 +948,12 @@ mod tests {
                 .state = Some(s);
         };
 
-        // 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
-        // (this corrects 1151's "nothing advances off a held
-        // pose"). What must hold across those windows is the armed ID, asserted below.
+        // Streamed in closed: the rest pose, snapped, one window that `0x5f4167` re-arms at its
+        // completion, so what must hold across windows is the armed id.
         app.update();
         assert_eq!(armed(&app, go), Some((0x93, RepeatAnimation::Never)));
 
-        // The open-lock cast lands: the lid swings open, ONE window.
+        // The open-lock cast lands: the lid swings open, one window.
         state(&mut app, GO_STATE_ACTIVE);
         app.update();
         assert_eq!(
@@ -1417,7 +962,7 @@ mod tests {
             "the Open motion is a transient substate — one window, whatever its loop bit says"
         );
 
-        // …and at its window end the machine advances 2 Open → 3 Opened on its own.
+        // At its window end the machine advances 2 Open → 3 Opened.
         advance(&mut app, 700);
         app.update();
         assert_eq!(
@@ -1426,15 +971,12 @@ mod tests {
             "the completion advance settles the swing onto the Opened rest pose"
         );
 
-        // The loot window closes (`CMSG_LOOT_RELEASE`): the lid swings shut, ONE window.
+        // The loot window closes (`CMSG_LOOT_RELEASE`): the lid swings shut, one window.
         state(&mut app, GO_STATE_READY);
         app.update();
         assert_eq!(armed(&app, go), Some((0x92, RepeatAnimation::Never)));
 
-        // 4 Close → 1 Closed, and then it STAYS there — through many completion re-arms of the
-        // Closed pose itself. Pre-1151 the Close *motion* was armed `Forever`, so this is the
-        // assertion the director's crate report failed at, and the re-arm cycle must not
-        // resurrect it.
+        // 4 Close → 1 Closed, and it stays there through the Closed pose's own re-arms.
         advance(&mut app, 700);
         app.update();
         assert_eq!(
@@ -1452,16 +994,9 @@ mod tests {
         }
     }
 
-    /// **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.
-    ///
-    /// The subject is Onyxia's lava traps in miniature: a Closed chain authored 29491 : 3276, where
-    /// the 10 %-weighted second take is the one that does something (there, a 300/s `LAVALUMP2`
-    /// burst — the lava spurting out of the lair floor; 208 trap GameObjects all played the silent
-    /// head). Spawning many objects makes the roll observable without a statistical test on one:
-    /// the count must be neither 0 (the bug) nor all (a broken walk), and near the authored tenth.
+    /// The arm rolls a variation (`0x5f3aee: push -1`), not the id's head; the loader seed takes
+    /// 0 (`0x710189`). Onyxia's lava traps in small: a Closed chain weighted 29491 : 3276, rolled
+    /// over many objects, whose second-take count must be neither 0 nor all, and near a tenth.
     #[test]
     fn the_arm_rolls_a_weighted_variation_not_the_head() {
         const N: usize = 400;
@@ -1524,15 +1059,7 @@ mod tests {
         );
     }
 
-    /// **A rest pose is ONE window, and its completion re-arms it — with a FRESH roll, for ever**
-    /// (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.
-    ///
-    /// This is the half that makes Onyxia's Lair a *continuous* ember field rather than one flurry
-    /// at stream-in: ~200 trap GameObjects each re-roll a 10 %-weighted Stand chain every 867 ms,
-    /// against a 5 s particle lifespan. One object, many windows, is the same law in the small.
+    /// `0x5f4167` re-arms a rest pose every window, whatever its loop bit, with a fresh roll.
     #[test]
     fn a_rest_pose_re_arms_every_window_and_re_rolls_its_variation() {
         let (mut app, go) = crate_app(&[(0x93, 0.866, 3276)]);
@@ -1568,31 +1095,23 @@ mod tests {
         assert!(matches!(armed(&app, go), Some((0x93, _))));
     }
 
-    /// **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,
-    /// because the dispatch's first act is `0x5f3cc8 call 0x5f40c0`.
-    ///
-    /// What *does* dispatch: a genuine `SetGoState`, and a Custom substate's completion (slot
-    /// 14's `0x5f4190` row, `old == new`) — which is what ends a Gnome machine's Custom0 hum.
+    /// A rest pose's re-arm is no dispatch (a brazier's `$GO2` `TorchLoop` hums on); a real
+    /// `SetGoState` and a Custom completion (`0x5f4190`, `old == new`) are.
     #[test]
     fn only_a_state_change_and_a_custom_completion_re_enter_the_dispatch() {
-        let (mut app, go) = crate_app(&[(153, 0.667, 0)]); // Custom0 — the crate authors one
+        let (mut app, go) = crate_app(&[(153, 0.667, 0)]); // Custom0, which the crate authors
         app.update();
         let seen = |app: &App| app.world().resource::<Dispatched>().0.len();
         assert_eq!(seen(&app), 1, "the spawn's own SetGoState is a dispatch");
 
-        // Fifty rest windows. The pose re-arms every one of them (the Onyxia law) and not one of
-        // those re-arms may announce a dispatch.
+        // Fifty rest windows: the pose re-arms in each, and none may announce a dispatch.
         for _ in 0..50 {
             advance(&mut app, 200);
         }
         assert!(matches!(armed(&app, go), Some((0x93, _))), "still Closed");
         assert_eq!(seen(&app), 1, "a rest pose's own re-arm is not a dispatch");
 
-        // A genuine SetGoState — the lid opens.
+        // A real SetGoState: the lid opens.
         app.world_mut()
             .entity_mut(go)
             .get_mut::<GoAnim>()
@@ -1600,9 +1119,8 @@ mod tests {
             .state = Some(GO_STATE_ACTIVE);
         app.update();
         assert_eq!(seen(&app), 2);
-        // …and the Open motion settling onto Opened is slot 14's `0x5f413d` row, not the dispatch.
-        // (Two ticks: the first runs the clip past its window, the next is where the retire sees
-        // the finished flag — the shape every completion test in this file uses.)
+        // The Open motion settling onto Opened is slot 14's `0x5f413d` row, not the dispatch.
+        // Two ticks: one runs the clip past its window, the next sees the finished flag.
         advance(&mut app, 700);
         app.update();
         assert_eq!(
@@ -1636,13 +1154,10 @@ mod tests {
         );
     }
 
-    /// The Custom channel shares the ONE transient slot with the motions (the reference's
-    /// `[handler+0x10]`), so 1100's bobber law has to keep holding through it: a Custom0 arms over
-    /// the state pose, runs exactly one window, and the completion re-runs the machine back onto
-    /// the state's own pose.
+    /// The Custom channel shares the one transient slot (`[handler+0x10]`) with the motions.
     #[test]
     fn a_custom_block_still_runs_one_window_and_hands_back_to_the_state() {
-        let (mut app, go) = crate_app(&[(153, 0.667, 0)]); // Custom0 — the crate authors one
+        let (mut app, go) = crate_app(&[(153, 0.667, 0)]); // Custom0, which the crate authors
         app.update();
         assert_eq!(armed(&app, go), Some((0x93, RepeatAnimation::Never)));
 
@@ -1663,14 +1178,8 @@ mod tests {
         );
     }
 
-    /// **B140** (decision 1404): UBRS's Rookery Eggs. Walk into a `TRAP`'s radius, the server
-    /// spends its last charge and sends `SMSG_GAMEOBJECT_DESPAWN_ANIM` immediately followed by
-    /// `SMSG_DESTROY_OBJECT` in the same tick — and the egg must **hatch before it pops**: 157
-    /// Despawn, one window (2.667 s on `G_DragonEggFreeze`, whose bone 8 swells 4.76×), with the
-    /// object held alive for exactly that long by the pin.
-    ///
-    /// The failing shape this pins is the whole report: the destroy freed the entity on arrival,
-    /// so 271 eggs blinked out with no animation at all.
+    /// UBRS's Rookery Eggs: vmangos sends `SMSG_GAMEOBJECT_DESPAWN_ANIM` then `SMSG_DESTROY_OBJECT`
+    /// in one tick, and the egg plays 157 Despawn (2.667 s on `G_DragonEggFreeze`) before it goes.
     #[test]
     fn an_announced_despawn_plays_its_window_before_the_object_pops() {
         let (mut app, go) = crate_app(&[(157, 2.667, 0)]);
@@ -1710,15 +1219,11 @@ mod tests {
         );
     }
 
-    /// The other half of the same rule: a model that doesn't author 157 (or an object with no
-    /// animation machine at all — a totem, a DynamicObject, both of which `SendObjectDeSpawnAnim`
-    /// also fires for) has nothing to play, so the pin never forms and the release runs on its
-    /// first pass — straight to the fade, with no animation in front of it. **This is the looted
-    /// chest** (decision 2198): `DeadmineCargoBoxes.m2` is a fully static model, so the announced
-    /// despawn resolves to nothing and the teardown fade is the whole observable.
+    /// A model without 157, or an object with no animation machine, never pins and goes straight
+    /// to the fade: a looted chest such as the static `DeadmineCargoBoxes.m2`.
     #[test]
     fn an_unownable_despawn_anim_goes_straight_to_the_fade() {
-        let (mut app, go) = crate_app(&[]); // the crate family only — no 157
+        let (mut app, go) = crate_app(&[]); // the crate family only, no 157
         app.update();
 
         app.world_mut()
@@ -1731,10 +1236,8 @@ mod tests {
         );
     }
 
-    /// The announcement **alone** kills nothing. `SendObjectDeSpawnAnim` lives on `WorldObject`,
-    /// and two vmangos boss scripts send it for objects that go on living (Sapphiron sends it for
-    /// *himself*); only a destroy that actually arrives marks [`PendingDestroy`]. So an announced
-    /// object with no destroy plays its window and returns to its state pose, still there.
+    /// `SendObjectDeSpawnAnim` is on `WorldObject`, and two vmangos boss scripts send it for
+    /// living objects (Sapphiron for himself); only an arriving destroy marks [`PendingDestroy`].
     #[test]
     fn an_announcement_without_a_destroy_never_despawns_anything() {
         let (mut app, go) = crate_app(&[(157, 2.667, 0)]);
@@ -1754,7 +1257,7 @@ mod tests {
         );
     }
 
-    /// A `ModelAnimations` that owns exactly `ids` — only the lookup table matters to the remap.
+    /// A `ModelAnimations` that owns exactly `ids`; only the lookup table matters to the remap.
     fn owning(ids: &[u16]) -> ModelAnimations {
         let hi = ids.iter().copied().max().unwrap_or(0) as usize;
         let mut lookup = vec![0xffffu16; hi + 1];
@@ -1783,44 +1286,34 @@ mod tests {
 
     #[test]
     fn a_missing_rest_pose_freezes_the_neighbouring_motion() {
-        // The Ahn'Qiraj gate roots: Stand + Open only, no Closed. The reference stands the Open
-        // motion in at rate 0 — its frame 0 IS the closed pose. Before this, benilla played nothing
-        // and the 42-bone root tangle rendered at bind pose.
+        // The Ahn'Qiraj gate roots own Stand and Open only: Open frozen at frame 0 is closed.
         let roots = owning(&[0, 148]);
         assert_eq!(remap_missing(&roots, 147), (148, true));
-        // The mirror leg: no Opened, no Open, but a Close motion → freeze Close at frame 0 (open).
+        // The mirror leg: only Close, frozen at frame 0, which is open.
         let no_open = owning(&[146]);
         assert_eq!(remap_missing(&no_open, 149), (146, true));
     }
 
     #[test]
     fn the_remap_falls_through_the_door_family_in_the_verified_order() {
-        // 146 Close missing: kept when Open exists (op4 resolves onward), else Closed.
         assert_eq!(remap_missing(&owning(&[148]), 146), (146, false));
         assert_eq!(remap_missing(&owning(&[147]), 146), (147, false));
-        // 147 Closed missing: kept when Close exists; else the frozen leg; else Stand.
         assert_eq!(remap_missing(&owning(&[146]), 147), (147, false));
         assert_eq!(remap_missing(&owning(&[0]), 147), (0, false));
-        // 148 Open missing: kept when Close exists; else Destroy if present; else Opened.
         assert_eq!(remap_missing(&owning(&[146]), 148), (148, false));
         assert_eq!(remap_missing(&owning(&[150]), 148), (150, false));
         assert_eq!(remap_missing(&owning(&[0]), 148), (149, false));
-        // 149 Opened missing with neither motion: Destroyed.
         assert_eq!(remap_missing(&owning(&[0]), 149), (151, false));
     }
 
-    /// Slot 14's dispatch table (`0x5f41e4`): rows 0 and 8..11 land at `0x5f4190`, which re-runs
-    /// the state machine **through `0x5f3cb0`** and so drops the object's display-sound loop; the
-    /// motion rows (2/4/5/7) advance to their rest pose and the rest rows (1/3/6) re-arm
-    /// themselves, neither of which touches it. Read as `AnimationData.dbc` ids, the key this
-    /// file uses everywhere.
+    /// Slot 14's table (`0x5f41e4`): rows 0 and 8..11 land at `0x5f4190`, re-running the machine
+    /// through `0x5f3cb0`; motion rows advance and rest rows re-arm without it.
     #[test]
     fn only_spawn_and_the_custom_block_re_enter_the_state_dispatch() {
         for id in [145, 153, 154, 155, 156] {
             assert!(completion_redispatches(id), "substate id {id}");
         }
-        // The four transition motions, the three rest poses — and Despawn (157), whose substate
-        // 12 is past slot 14's own `cmp 0xb` bound and dispatches nowhere at all.
+        // Motions, rest poses, and Despawn (157), whose substate 12 is past slot 14's `cmp 0xb`.
         for id in [146, 147, 148, 149, 150, 151, 152, 157] {
             assert!(!completion_redispatches(id), "substate id {id}");
         }
@@ -1828,7 +1321,7 @@ mod tests {
 
     #[test]
     fn ids_outside_the_door_group_get_no_remap() {
-        // `lea eax,[esi-0x92]; cmp eax,3; ja` — only 146..149 index the jump table.
+        // `lea eax,[esi-0x92]; cmp eax,3; ja`: only 146..149 index the jump table.
         let none = owning(&[0]);
         for id in [145, 150, 151, 152, 157] {
             assert_eq!(remap_missing(&none, id), (id, false));
@@ -1837,20 +1330,16 @@ mod tests {
 
     #[test]
     fn ownership_reads_the_lookup_table_not_the_clip_list() {
-        // The table is short — a model's `nAnimationLookup` stops just past its highest id, so an id
-        // beyond the end is the out-of-bounds sentinel. `clips` is deliberately empty here: a clip
-        // scan would answer "owns nothing" and take every remap's last leg.
+        // `nAnimationLookup` stops just past a model's highest id; `clips` is empty, so a clip
+        // scan would answer "owns nothing".
         let book = owning(&[146, 147, 148, 149]);
         assert!(book.owns(147) && !book.owns(0) && !book.owns(150));
     }
 
     #[test]
     fn chest_animates_but_keeps_its_collider() {
-        // A chest (3) is on the animation machine (2271) but off the collision gate (0249): you see the
-        // lid move, but you never walk through an open chest.
         assert!(go_animates(3));
         assert!(!collision_follows_state(3));
-        // Doors/buttons are on both.
         assert!(go_animates(0) && collision_follows_state(0));
         assert!(go_animates(1) && collision_follows_state(1));
     }
@@ -1863,16 +1352,15 @@ mod tests {
         ] {
             assert!(go_animates(t), "type {t} runs the machine");
         }
-        // The 11 family-B types, whose vtable slots are the abstract base's do-nothing bodies.
+        // The 11 family-B types, whose vtable slots are the base's empty bodies.
         for t in [4, 5, 7, 11, 13, 14, 15, 20, 21, 22, 25] {
             assert!(!go_animates(t), "type {t} keeps the loader seed");
         }
         // Past the table: the unsigned `ja` default, no handler.
         assert!(!go_animates(31) && !go_animates(99));
-        // The three that used to be the whole gate are still on it; the ones it wrongly excluded —
-        // TEXT (every book) and GOOBER — are the reported regressions this widening closes.
+        // TEXT (every book) and GOOBER.
         assert!(go_animates(9) && go_animates(10));
-        // Type 0 is also what an ABSENT type id reads as (decision 0248), so the default animates.
+        // Type 0 is also what an absent type id reads as, so the default animates.
         assert!(go_animates(0));
     }
 }
diff --git a/crates/benilla-app/src/player.rs b/crates/benilla-app/src/player.rs
index 3f69801e..65e4dd92 100644
--- a/crates/benilla-app/src/player.rs
+++ b/crates/benilla-app/src/player.rs
@@ -1,32 +1,15 @@
-//! Avatar + camera + input. Free-flies until the server reports our position, then takes third-person
-//! control of the avatar (WASD walks it, height-following the terrain) and streams our movement to the
-//! server as the confirmed mover. Owns the camera entity. The cursor itself is owned by the
-//! [`crate::cursor`] subsystem; this module only hides it during mouselook (`CursorOptions.visible`).
+//! The avatar, the camera and their input: free-fly until the server places us, then third-person
+//! control of our body, a kinematic capsule over avian's `MoveAndSlide`, streamed to the server as
+//! the active mover. The cursor is [`crate::cursor`]'s; this module only hides it for mouselook.
 //!
-//! Mouse control mirrors vanilla's two look modes (grounded in the WoW 1.12 camera CVars / mouselook
-//! API): **right-drag turns the character** (movement then
-//! follows the camera heading), **left-drag orbits the camera** around a stationary character; either
-//! locks + hides the cursor and restores it on release. **Both buttons held together run the character
-//! forward** (vanilla's "both-button move"), steering with the mouse like a right-drag. The **scroll
-//! wheel** zooms the third-person
-//! distance (clamped to the vanilla `cameraDistanceMax` range; the camera *glides* to the new
-//! distance). A left-drag orbit offset is reeled back in by the **auto-follow** — vanilla's
-//! `cameraSmoothStyle`, a real player setting since decision 1493 ([`camera::FollowStyle`]):
-//! Smart (the shipped default) chases while the character moves, Always chases always, Never
-//! leaves the camera exactly where the hand put it.
-//! The **dev chord + `F`** toggles free-fly (1043); the **dev chord + `G`** lands the avatar where
-//! the camera is ([`land`]).
+//! As in 1.12, right-drag turns the character, left-drag orbits the camera, both buttons run
+//! forward steering like a right-drag, and the wheel zooms within `cameraDistanceMax`; the
+//! auto-follow (`cameraSmoothStyle`, [`camera::FollowStyle`]) reels a left-drag orbit back in. The
+//! dev chord with `F` toggles free-fly, and with `G` lands the avatar at the camera ([`land`]).
 //!
-//! Movement is a thin kinematic capsule controller over avian's `MoveAndSlide` (decision 0009).
-//!
-//! **This file is the map, not the machine.** It holds the plugin and its ordering edges, the
-//! shared types the concern modules trade in ([`Player`], [`BodyQuery`], [`TransportQuery`],
-//! [`StandStateRequest`]), and the two `UNIT_FIELD_FLAGS` bits with more than one reader. The
-//! per-frame system itself is [`controller::control`], and every phase it runs that is a concern
-//! of its own has a file beside it: [`input`] decodes the keys, [`wire_in`] applies what the
-//! server said, [`ride`] carries us on a deck, [`posture`] holds the body, [`mover`]/[`swim`]
-//! move it, [`flags`] builds the move-flag word, [`gait`] + [`body_pose`] render it, [`camera`]
-//! seats the eye, [`movement_net`] streams it.
+//! This file holds the plugin and its ordering edges, the types the modules beside it share
+//! ([`Player`], [`BodyQuery`], [`TransportQuery`], [`StandStateRequest`]) and the
+//! `UNIT_FIELD_FLAGS` bits with several readers; the per-frame system is [`controller::control`].
 
 use bevy::input::mouse::AccumulatedMouseMotion;
 use bevy::prelude::*;
@@ -42,82 +25,58 @@ use benilla_world::schedule::WorldStage;
 
 mod arc;
 mod net;
-// Writing the frame onto the body we drive — pose, MovementState, the counter-twist gap.
+// Writes 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 (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;
-// The per-frame controller itself — the one system, split out so the root stays the map.
 mod controller;
 mod world_focus;
-// The remembered camera pose (decision 1131) — it lives inside `player/` so it can read the rig's
-// own `pub(super)` fields instead of widening them for a module outside.
+// The remembered camera pose, inside `player/` to read the rig's `pub(super)` fields.
 mod camera_saved;
 mod camera_water;
-// The five NAMED camera poses the player can jump between (decision 1745) — `camera_saved`'s
-// complement: that one remembers where you left the camera, this one where you decided it should
-// be able to go. Same reason for living inside `player/`: it writes the rig's `pub(super)` fields.
+// The five named camera views, inside `player/` to write the rig's `pub(super)` fields.
 pub(crate) mod camera_view;
 mod drunk;
-// Which single unit the client embodies (decision 1277) — the `Embodied` marker's owner.
 mod embody;
-// This frame's move-flag word — the one bitset the animation, the wire and the local gates all
-// read (decision 0056).
 mod flags;
 mod follow;
 
 mod gait;
-// This frame's decoded input — the netted movement axes and the camera's command word
-// (decisions 0056, 1502). Everything downstream reads the axes, never the keys.
 mod input;
-// The land-here affordance (free-fly's other half). `pub(crate)` for its `LandHere` message, which
-// the debug panel's button writes.
+// `pub(crate)` for its `LandHere` message, which the debug panel writes.
 pub(crate) mod land;
 mod move_trace;
 mod movement_net;
-// The stand state + the sheath toggle — how the body HOLDS itself (decisions 0080, 0881).
 mod posture;
-// The kinematic mover step. `pub(crate)` because the grounded walk resolve is **not** the local
-// player's alone: a remote mover's dead-reckon (`crate::net::motion::remote`) runs its extrapolated
-// step through the very same code, the way the reference runs every mover through one controller
-// (decision 0059's byte trail).
+// `pub(crate)`: a remote mover's dead-reckon (`crate::net::motion::remote`) steps through the same
+// walk resolve, as the reference runs every mover through one controller.
 pub(crate) mod mover;
-/// The spyglass zoom — aura 76, a client-local camera override with no wire half at all (B151).
 mod scoped_view;
-// Riding a transport — the platform-frame carry/attach (decisions 0438, 0470).
+// Riding a transport: the deck carry and attach.
 mod ride;
 mod server_ride;
 mod setup;
 mod state;
-/// The step-up diagnostic probe — the blocked-frame report behind the `stup` trace tag.
 pub(crate) mod step_probe;
 mod swim;
-/// What the camera orbits, when that is not our own body — the far-sight anchor (B151, and Mind
-/// Control's camera half in B211, which rides the same field).
 mod view_subject;
-/// The walk/run gait toggle (`TOGGLERUN`) — one latched bit and the reference's refusal chain.
 mod walk;
 mod wire_in;
 
-// `apply_self_model_fade` is `pub(crate)`-visible: it is the LAST writer of a self body part's
-// render-alpha field, so the unit-lane material-alpha compose (`entities::apply_unit_mat_alpha`)
-// orders itself before it and lets that documented override stand.
+// The last writer of a self body part's render alpha: `entities::apply_unit_mat_alpha` orders
+// itself before it.
 pub(crate) use camera::apply_self_model_fade;
-// The controller system, named unqualified here so the plugin's ordering edges (and the ones
-// sibling modules declare against it) read as they always have.
 use controller::control;
-// `/follow` (decision 0890): chat asks with the message, `crate::target` resolves the subject into
-// the state, and this module owns the motion.
+// The private camera and `state` items are re-imported for the modules beside this one, which
+// name them `super::X`.
 use camera::{
     apply_zoom_scroll, model_pivot_height, run_look_session, FlyCam, LookButton, CAM_DIST_DEFAULT,
 };
 pub(crate) use camera::{head_height, CameraControl, CameraPivot};
+// `/follow`: chat sends the request, `crate::target` resolves the subject into the state, and
+// `follow` owns the motion.
 pub(crate) use follow::{FollowRequest, FollowState};
-// The shared avatar state + movement constants live in [`state`]; the private re-imports below are
-// what lets this module and the concern modules beside it keep naming them `super::X` unchanged.
 use state::{
     MoveSpeed, PlayerRide, AIR_NUDGE_SPEED, FALL_FAR_DROP, FALL_FAR_TIME, FOOT_CONE_HEIGHT,
     GROUND_COS, GROUND_PROBE, JUMP_SPEED, LAND_PROBE, MOUSELOOK_PITCH_CLAMP, RUN_BACK_RATIO,
@@ -125,128 +84,75 @@ use state::{
     TURN_RATE, TURN_RATE_MOVING, WALK_RATIO, WATER_WALK_PITCH_FLOOR, WEDGE_MIN_FALL,
     WEDGE_STALL_RATIO, WEDGE_STILL_FRAMES,
 };
-// `SETTLE_TIMEOUT` is `pub(crate)`: the settle release lives in the terrain streamer (decision
-// 0737 — residency releases the hold, not ground contact), which owns the deadline push while the
-// resident world is still the departed map's (0710).
 pub(crate) use state::{
     Player, PlayerCapsule, CAPSULE_HEIGHT, CAPSULE_RADIUS, CREATURE_STEP_UP_HEIGHT,
     DEFAULT_COLLISION_HEIGHT, FEATHER_TERMINAL_VELOCITY, GRAVITY, HOVER_CLIMB_RATE, HOVER_HEIGHT,
     SETTLE_TIMEOUT, STEP_UP_HEIGHT, TERMINAL_VELOCITY,
 };
-/// The swim boundary `0.75·h` — and therefore the **wade ceiling**, since wading is the implicit
-/// in-liquid-but-not-swimming state and the two cannot be different numbers. Read by the creature
-/// swim marker and the footstep splash slot, which have no `Player` of their own.
+/// The swim boundary `0.75·h`, also the wade ceiling, for the creature swim marker and the
+/// footstep splash, which have no `Player`.
 pub(crate) use swim::{may_swim, swim_enter_depth};
-/// The camera's followed unit when that is not our own body — read by [`crate::camera_shake`] for
-/// the shake's body frame and its two suspend gates, which the reference takes off `[cam+0x88]`.
+/// The camera's followed unit when not our body; [`crate::camera_shake`] takes its body frame and
+/// two suspend gates from it, as the reference does from `[cam+0x88]`.
 pub(crate) use view_subject::ViewSubject;
 
-/// **`UNIT_FLAG_STUNNED`** — the `UNIT_FIELD_FLAGS` bit that freezes a character's *turning*
-/// (decision 0872). Not a movement flag and not an aura: the reference reads it straight off the
-/// descriptor block at `[[unit+0x110]+0xa0]` (predicate `0x5145b0` — note the inverted
-/// `not/shr/and` form, which a census grepping only `test …,0x40000` misses — consumed at
-/// `0x514755`, which skips both the turn and pitch emitters and force-stops either in flight).
+/// `UNIT_FLAG_STUNNED`, the `UNIT_FIELD_FLAGS` bit that stops turning. The reference reads it off
+/// the descriptor (`[[unit+0x110]+0xa0]`, predicate `0x5145b0`, an inverted `not/shr/and` test) at
+/// `0x514755`, which skips the turn and pitch emitters and stops either in flight. StartTurn
+/// (`0x602b20`) and StartPitch (`0x602b80`), the only two of the twelve relayed `MSG_MOVE_*`
+/// wrappers with a stun test, refuse on it, and it suppresses the auto-face smoothing
+/// (`0x600dd7`). No reader touches animation: its sites at `0x5eb4f2` and `0x5ec219` are in
+/// `ToggleSheath` (`0x5eb480`) and `CanLootNow` (`0x5ec110`).
 ///
-/// It is the **other half** of a stun. vmangos's `HandleModStun` sets this flag *and* calls
-/// `SetRooted(true)`, so `SPELL_AURA_MOD_STUN` grants both: root kills translation, this kills the
-/// pivot. A pure root (Frost Nova, Entangling Roots) sets only the first — which is why a rooted
-/// player can still turn and a stunned one cannot, the distinction B179 was reporting.
-///
-/// **It has no second consumer — the "idle/fidget" one was a misread, and this doc outlived the
-/// correction.** It used to say the idle/fidget selectors bail on the bit at `0x5eb4f2`/`0x5ec219`
-/// and pointed at a `MovementState::stunned` that decision **0889** had already deleted along with
-/// 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 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
-/// only two of twelve carrying a stun test), and the auto-face-target smoothing suppression at
-/// `0x600dd7`.
+/// vmangos's stun aura sets it (`SpellAuras.cpp:3523`) and roots (`SpellAuras.cpp:3542`), where a
+/// root aura only roots (`SpellAuras.cpp:3772`): a rooted player can still turn, a stunned one
+/// cannot.
 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.
+/// `IsSelfControlled` (`0x5fa550`, `test eax, 0xc00004` at `0x5fa566`): false while
+/// `DISABLE_MOVE` (`0x4`), `CONFUSED` (`0x400000`) or `FLEEING` (`0x800000`) is set; the stun and
+/// taxi bits are not in the mask. It is true for an ordinary player, so a gate on it fires in the
+/// normal case and is suppressed while feared. Its readers are the movement and collision layer
+/// and `DoEmote`.
 ///
-/// 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
-/// in the *normal* case and is suppressed while feared, not the other way round.
-///
-/// **One leg is deliberately unmodelled.** `POSSESSED` (`0x1000000`) does not refuse here: the
-/// reference redirects at `0x5fa582` to the charmer's GUID and **recurses** into itself, so the
-/// answer is the charmer's. Reproducing that needs the charmer's descriptor, and the only
-/// consumer that would notice is whether a red toast appears while mind-controlled. Named rather
-/// than invented (decision 1904).
+/// `POSSESSED` (`0x1000000`) is not handled: the reference recurses on the charmer's guid
+/// (`0x5fa582`) and answers with the charmer's flags, which needs the charmer's descriptor.
 pub(crate) fn self_controlled(unit_flags: u32) -> bool {
-    /// `DISABLE_MOVE | CONFUSED | FLEEING` — the reference's literal `0xc00004`.
+    /// `DISABLE_MOVE | CONFUSED | FLEEING`, the reference's literal `0xc00004`.
     const NOT_SELF_CONTROLLED: u32 = 0x0000_0004 | 0x0040_0000 | 0x0080_0000;
     unit_flags & NOT_SELF_CONTROLLED == 0
 }
 
-/// `UNIT_FLAG_IN_COMBAT` — the same `UNIT_FIELD_FLAGS` word, **bit 19** (vmangos
-/// `UnitDefines.h`; the client reads it as `shr reg,0x13; test rl,1`).
-///
-/// Its readers are deliberately unrelated to each other — the spell-usability walk's leg 8, the
-/// probe preflight banner, and `UnitAffectingCombat`'s snapshot field — which is exactly why the
-/// 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.** 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.
+/// `UNIT_FLAG_IN_COMBAT`, bit 19 of `UNIT_FIELD_FLAGS` (vmangos `UnitDefines.h:564`), read by the
+/// client as `shr reg,0x13; test rl,1`. The local player has no separate combat latch: its two
+/// hardcoded readers (`0x482f70`, `0x4d6038`) and `UnitAffectingCombat("player")` read this bit.
 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` — 20 independent sites
-/// of that idiom with no shared gate).
-///
-/// 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.
+/// `UNIT_FLAG_TAXI_FLIGHT`, bit 20 of `UNIT_FIELD_FLAGS` (vmangos `UnitDefines.h:565`), read by the
+/// client as `shr reg,0x14; test rl,1` at 20 sites with no shared gate, among them
+/// `SetStandState`'s third guard, the idle auto-AFK gate and `UnitOnTaxi`.
 pub(crate) const UNIT_FLAG_TAXI_FLIGHT: u32 = 0x0010_0000;
 
-/// Ask for a **stand state** — the client's `SetStandState(newState)` (`0x5ed430`: send
-/// `CMSG_STANDSTATECHANGE` + apply locally through `0x6127b0`), as a message so every path that
-/// wants a posture funnels through the ONE setter in [`posture`] (the [`crate::creature_anim::
-/// SheathRequest`] posture, decision 0080).
-///
-/// 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 (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.
-///
-/// The state values are `UnitStandStateType`: 0 STAND · 1 SIT · 3 SLEEP · 8 KNEEL.
+/// A stand-state request for [`posture`]'s one setter, the client's `SetStandState` (`0x5ed430`:
+/// send `CMSG_STANDSTATECHANGE` and apply locally through `0x6127b0`). The posture emotes (`/sit`,
+/// `/sleep`, `/kneel`, `/stand`, `/lay`) send it, as `DoEmote`'s `EmoteSpecProc == 1` branch calls
+/// the setter the `X` key does; the server sets no posture for a state text emote
+/// (`ChatHandler.cpp:729-733`). States are `UnitStandStateType`: 0 stand, 1 sit, 3 sleep, 8 kneel.
 #[derive(bevy::ecs::message::Message, Clone, Copy, Debug)]
 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`.
+/// `SMSG_STANDSTATE_UPDATE` for our body (the eat and drink sit, the stand on damage), applied by
+/// [`posture`] through the same local setter with no refusal and no packet back (`0x603e50` →
+/// `0x6127b0`).
 #[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
-/// via `MovementState`. Its model is attached by the entity renderer through the same path as any
-/// other unit (0041), which is exactly why a creature needs nothing special: everything downstream
-/// reads the body's own pivot, speeds, scale and descriptor off the entity.
-///
-/// An alias because three modules take it — [`control`], [`posture`] (read-only, for the sheath
-/// toggle's guard chain) and [`body_pose`] (the frame's one writer) — and one eleven-column tuple
-/// written out three times is how a query silently drifts from its readers.
+/// The body we drive: our own avatar, or a possessed creature. Everything reads its pivot, speeds,
+/// scale and descriptor off the entity, so a creature needs nothing special.
 pub(super) type BodyQuery<'w, 's> = Query<
     'w,
     's,
@@ -260,24 +166,18 @@ pub(super) type BodyQuery<'w, 's> = Query<
         Has<crate::creature_anim::Engaged>,
         Option<&'static crate::net::UnitSpeeds>,
         Option<&'static mut BodyTwist>,
-        // What is worn in each hand and in the ranged slot — the Z toggle's cycle reads it
-        // (the ref's three `GetWeapon(0/1/2)` calls before the state walk).
+        // Both hands and the ranged slot, for the `Z` toggle's cycle (the reference's
+        // `GetWeapon(0/1/2)`).
         Option<&'static crate::creature_anim::Wielded>,
-        // The **raw** `OBJECT_FIELD_SCALE_X`, for the camera pivot's target height — not the
-        // transform's, which is the 2 s-eased render scale (see [`camera::head_height`]).
+        // The raw `OBJECT_FIELD_SCALE_X` for the pivot height, not the transform's 2 s-eased scale.
         Option<&'static crate::net::NetEntity>,
     ),
     (With<Embodied>, Without<FlyCam>),
 >;
 
-/// The armed transports — the platform-frame carry/attach ([`ride`], decision 0438 phase 2). The
-/// `Without`s only disjoint the borrows against the body and the camera.
-///
-/// `ColliderAabb` rides along for the **ride trace only**, and it is the column that separates
-/// "the deck moved" from "the deck's collider moved": avian refreshes it in `PhysicsSchedule`
-/// (i.e. `FixedPostUpdate`, *before* `Update`), while `tick_transports` writes the deck's pose *in*
-/// `Update` — so the box the broad phase prunes against is always one frame behind the deck it
-/// belongs to, and the down-probe's candidate set is whatever that stale box still overlaps.
+/// The armed transports, for the deck carry ([`ride`]). `ColliderAabb` is for the ride trace:
+/// avian refreshes it in `FixedPostUpdate`, before `tick_transports` moves the deck in `Update`, so
+/// the broad-phase box lags its deck by a frame.
 pub(super) type TransportQuery<'w, 's> = Query<
     'w,
     's,
@@ -293,17 +193,12 @@ pub(super) type TransportQuery<'w, 's> = Query<
     ),
 >;
 
-/// The player controller's **ordering handle**. Anything that must write the aim or the camera rig
-/// before the controller reads them orders against this — the two scripted probe drivers do
-/// (`capture::probe_look` / `capture::probe_cam`, decision 1174). A set rather than the `control`
-/// symbol itself: an instrument may name the gameplay system it runs against, but exporting
-/// `control` would drag its private parameter types (`MoveSpeed`, `PlayerCapsule`, `PressGesture`)
-/// out with it, which is exactly the internals-publishing 1173 rejected a crate wall to avoid.
+/// The controller's ordering handle, for anything that writes the aim or the camera rig before
+/// `control` reads them (`capture::probe_look`, `capture::probe_cam`).
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct PlayerControlSet;
 
-/// The player/camera subsystem: spawns the camera + move/avatar resources at startup, drives the
-/// third-person/free-fly controller each frame. (The cursor is the [`crate::cursor`] subsystem.)
+/// The player and camera: spawns the camera and avatar resources, and runs the controller.
 pub(crate) struct PlayerPlugin;
 
 impl Plugin for PlayerPlugin {
@@ -312,18 +207,10 @@ impl Plugin for PlayerPlugin {
         follow::plugin(app);
         camera_saved::plugin(app);
         camera_view::plugin(app);
-        // 1160's wire (a), both directions (see `world_focus`): the game answers the world's
-        // "where do I stream from" before the stream stage, and reads the residency the world
-        // publishes after it to end its own post-snap hold.
-        //
-        // **Both ordering edges are load-bearing** (B263 round 3, decision 1336). `.before(Stream)`
-        // alone left the publish free to run before `control`'s teleport snap (conflicting access,
-        // no edge — the executor picks either order), and on the snap frame the streamer then
-        // streamed around the DEPARTURE position: residency read "world resident", the settle hold
-        // released on frame 0, and the body free-fell at the destination under the loading screen —
-        // every same-map `.tele` on the probe machine. `.after(Input)` pins the publish to the
-        // post-snap position; the schedule contract (snap → focus → stream → release → present)
-        // is only a contract if every arrow is an explicit edge.
+        // The stream focus is published after `control`'s teleport snap and before the stream
+        // stage, and the post-snap hold released after it. Both edges are needed: without
+        // `.after(Input)` the focus can precede the snap, the world streams around the departure,
+        // and the hold releases at once.
         app.add_systems(
             Update,
             (world_focus::publish_viewer, world_focus::publish_view_focus)
@@ -340,19 +227,16 @@ impl Plugin for PlayerPlugin {
         app.init_resource::<camera::ZoomLimit>();
         app.init_resource::<camera::FollowConfig>();
         app.init_resource::<camera_dynamics::CameraOptions>();
-        // Far sight: resolve `PLAYER_FARSIGHT` into a pose before `control` reads it to seat the
-        // camera. A separate system rather than another query on `control` for a hard reason —
-        // `control` already holds the self entity's `Transform` mutably, so it cannot also read an
-        // arbitrary unit's.
+        // Far sight resolves `PLAYER_FARSIGHT` to a pose before `control` seats the camera: a
+        // separate system, as `control` holds our `Transform` mutably and cannot read another's.
         app.init_resource::<view_subject::ViewSubject>()
             .init_resource::<scoped_view::ScopedView>()
             .add_systems(
                 Update,
                 (
                     view_subject::publish_view_subject,
-                    // The spyglass zoom (aura 76) — a different mechanism entirely, sharing only
-                    // the family name. Also before `control`, which reads the scope to hold the rig
-                    // in first person: the reference's camera lock.
+                    // The spyglass zoom (aura 76), before `control`, which reads it to hold the
+                    // rig in first person.
                     scoped_view::apply_scoped_view,
                 )
                     .in_set(WorldStage::Input)
@@ -361,21 +245,16 @@ impl Plugin for PlayerPlugin {
             );
         app.add_systems(
             Startup,
-            // AFTER the config fold, not merely after the assets: the camera reads `gxMultisample`
-            // once, at spawn (1629), so a player's setting has to be in the resource by now.
+            // After the config load: the camera reads `gxMultisample` once, at spawn.
             setup::setup_player
                 .after(AssetSet::Open)
                 .after(crate::cvars::CvarLoad),
         )
-        // The world camera renders only when the world can be seen (decision 0540): in world,
-        // or under the opaque loading screen (whose covered render is what compiles the
-        // world's pipelines before the first visible frame). At the glue screens the fully
-        // streamed world otherwise burns real GPU time behind an opaque fullscreen scene.
+        // The world camera renders only in world or under the loading screen, whose covered
+        // render compiles the world's pipelines before the first visible frame.
         .add_systems(Update, setup::gate_world_camera)
-        // In capture mode the harness ([`crate::capture`]) pins the camera (and thus the stream
-        // focus), so `control` must not also drive it — gate it off when capturing. In-world
-        // only (decision 0193): at the character-select glue screen the controller must not
-        // grab the cursor, fly the camera, or queue movement sends behind the overlay.
+        // Off in capture mode, where the harness pins the camera, and in world only, so the glue
+        // screens keep the cursor and send no movement.
         .add_systems(
             Update,
             control
@@ -384,14 +263,10 @@ impl Plugin for PlayerPlugin {
                 .run_if(not(resource_exists::<crate::run_mode::CaptureMode>))
                 .in_set(crate::char_select::InWorldGated),
         )
-        // The posture setter's queue (the `/sit` family — decision 0881; `control` is the sole
-        // executor, like the sheath queue).
+        // The posture queue (the `/sit` family), which `control` alone executes.
         .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.
+        // Land-here, before `control`, so the frame that applies the teleport takes control back.
         .add_message::<land::LandHere>()
         .add_systems(
             Update,
@@ -400,13 +275,8 @@ impl Plugin for PlayerPlugin {
                 .before(control)
                 .in_set(crate::char_select::InWorldGated),
         )
-        // (The two scripted probe drivers that used to sit here — `WOW_PROBE_LOOK`'s
-        // mouse-turn and `WOW_PROBE_CAM`'s camera park — are the harness's now, and register
-        // themselves against `control` from there: decision 1174 moved every instrument out of
-        // this module so a player build carries none of them.)
-        // A server-authored spline (Charge/knockback/taxi) driving our own player is mirrored into
-        // `Player` here, *before* `control` reads `pos` to seat the camera and skip input. Same
-        // gates as `control` (not while capturing; in-world only).
+        // A server spline driving us (Charge, knockback, taxi) is mirrored into `Player` before
+        // `control` reads `pos`; gated as `control` is.
         .add_systems(
             Update,
             server_ride::drive_self_ride
@@ -415,16 +285,13 @@ impl Plugin for PlayerPlugin {
                 .run_if(not(resource_exists::<crate::run_mode::CaptureMode>))
                 .in_set(crate::char_select::InWorldGated),
         )
-        // A session END releases the avatar — a confirmed `/logout`, or a lost session
-        // (decision 1262): the streamed entity is despawned by the net drain either way, and
-        // dropping `active` re-arms the take-control latch for the next login (possibly a
-        // different character). Ungated — the message lands as the state flips.
+        // A session end (a `/logout` or a lost session) drops `active`, re-arming the take-control
+        // latch for the next login; ungated, as the message lands while the state flips.
         .add_systems(
             Update,
             wire_in::release_on_session_end.in_set(WorldStage::Input),
         )
-        // Which body the client drives at all (decision 1277). Strictly before everything that
-        // reads the marker — the controller, and the collision-height mirror below.
+        // Embodiment, before every reader of the marker.
         .add_systems(
             Update,
             embody::maintain_embodiment
@@ -432,37 +299,26 @@ impl Plugin for PlayerPlugin {
                 .before(control)
                 .before(mirror_mover_collision_height),
         )
-        // Mirror the driven body's collision height onto `Player` for the swim arm (decision
-        // 0645). A *continuous* sync rather than a one-shot at take-control, for the reason the
-        // take-control branch itself records: a cross-map worldport re-streams the entity, so
-        // anything latched on that edge is lost on transfer — and a possession swaps it for a
-        // body of an entirely different size. Before `control`, which is where the swim depth
-        // lines are evaluated.
+        // Before `control`, which evaluates the swim depth lines.
         .add_systems(
             Update,
             mirror_mover_collision_height
                 .in_set(WorldStage::Input)
                 .before(control),
         )
-        // The camera shake (B298, decision 1540) lands on the camera AFTER `control` has
-        // seated it: the applier adds its offset to the pose `seat_camera` just wrote, so the
-        // eye it measures the distance falloff against is the un-shaken one. `control` is at
-        // Bevy's 16-param ceiling, so the offset cannot be threaded into it as a resource —
-        // and running after is the better shape anyway.
+        // The shake adds its offset after `control` seats the camera, so its distance falloff
+        // measures the unshaken eye.
         .add_systems(
             Update,
             crate::camera_shake::apply_camera_shake
                 .in_set(WorldStage::Input)
                 .after(control)
-                // Gated off in capture mode alongside `control`, and for the same reason a
-                // capture keeps the doodad rail static: a pinned camera that a passing kodo
-                // could nudge is not a regression baseline any more.
+                // Off in capture mode, where the camera is pinned.
                 .run_if(not(resource_exists::<crate::run_mode::CaptureMode>)),
         )
-        // **Which mouse buttons the world owns** (ledger B364) — decoded once, ahead of all
-        // three readers: `/follow`'s both-button cancel below, the look session, and the camera's
-        // input command word. `control` cannot own it, because `steer_follow` runs before
-        // `control` and would then read it a frame late.
+        // Which mouse buttons the world owns, decoded ahead of its three readers: `/follow`'s
+        // both-button cancel, the look session and the camera's command word. Not in `control`:
+        // `steer_follow` runs before it and would read the latch a frame late.
         .add_systems(
             Update,
             camera::latch_world_mouse
@@ -471,10 +327,8 @@ impl Plugin for PlayerPlugin {
                 .before(follow::steer_follow)
                 .in_set(crate::char_select::InWorldGated),
         )
-        // `/follow` (decision 0890): steer the facing and decide this tick's synthesized forward
-        // input immediately BEFORE the controller, which folds the flag into its forward axis.
-        // The player's own turn input therefore runs after us and wins, which is exactly what
-        // makes the turn-away cancel reachable.
+        // `/follow` steers before `control`, so the player's own turn input lands after it and
+        // wins over the follow's steering.
         .add_systems(
             Update,
             follow::steer_follow
@@ -482,15 +336,10 @@ impl Plugin for PlayerPlugin {
                 .before(control)
                 .in_set(crate::char_select::InWorldGated),
         )
-        // The self-avatar zoom-in fade rides the same `MeshTag`/material channel as the interior
-        // classifier + the appear/despawn fades, so it must run *after* both to win the frame while
-        // fading (and yield to them otherwise). It also writes `Visibility` (the first-person
-        // hide), so it must run after the model-`Visibility` authority
-        // (`debug_panel::apply_model_visibility`) too — otherwise whichever system Bevy's
-        // arbitrary sort ran last would win, and the authority could re-show the body in
-        // first-person. First-person correctness outranks the dev creature-toggle for these few
-        // submeshes. Gated off in capture mode alongside `control` (whose per-frame
-        // `self_fade_alpha` it consumes), so a pinned capture never hides the avatar.
+        // The self-avatar fade shares the `MeshTag` and material channel with the interior
+        // classifier and the appear and despawn fades, and writes `Visibility` for the
+        // first-person hide, so it runs after them and the model-visibility set; off in capture
+        // mode, like the `control` whose alpha it reads.
         .add_systems(
             Update,
             apply_self_model_fade
@@ -502,11 +351,9 @@ impl Plugin for PlayerPlugin {
     }
 }
 
-/// Mirror the driven body's [`crate::entities::CollisionHeight`] onto [`Player`] — its swim depth
-/// lines are fractions of it (decision 0645), and the swim arm runs off the resource, not the
-/// entity. One entity, one copy: no work until a body streams in, and it re-syncs itself after a
-/// worldport re-streams that entity under a new one — or after a possession puts a different-sized
-/// body in our hands.
+/// Mirror the driven body's [`crate::entities::CollisionHeight`] onto [`Player`], whose swim depth
+/// lines are fractions of it; continuous, since a worldport re-streams the body and a possession
+/// swaps it.
 fn mirror_mover_collision_height(
     mut player: ResMut<Player>,
     mover: Query<&crate::entities::CollisionHeight, With<Embodied>>,
diff --git a/crates/benilla-app/src/player/arc.rs b/crates/benilla-app/src/player/arc.rs
index 0f60521e..765b43c8 100644
--- a/crates/benilla-app/src/player/arc.rs
+++ b/crates/benilla-app/src/player/arc.rs
@@ -1,55 +1,27 @@
-//! The airborne-arc lifecycle bookkeeping — an `impl Player` block beside its concern (the
-//! `mover.rs`/`movement_net.rs` pattern): the per-frame jump/step-off arc advance
-//! ([`Player::advance_airborne_arc`]) and the wire lifecycle edges it reports ([`ArcEdges`]).
-//! `control` calls it once per non-swim frame after the mover has written this frame's pose; the
-//! `MSG_MOVE_*` opcode selection and the FALLINGFAR pose gate both read the edges. Decisions
-//! 0053/0058/0179.
+//! The airborne arc: the per-frame jump and step-off bookkeeping, and the wire edges it reports.
 
 use super::{Player, FALL_FAR_DROP, FALL_FAR_TIME};
 
-/// The airborne-arc lifecycle edges [`Player::advance_airborne_arc`] reports for the frame — what the
-/// live flags (`new_arc` re-seeds the frozen airborne direction bits) and the wire stream
-/// (`landed` selects the `MSG_MOVE_*` opcode) read.
+/// This frame's arc edges, read by the flag word and the wire stream.
 pub(super) struct ArcEdges {
-    /// This frame began a new airborne arc (a first airborne frame or a fresh jump, incl. a
-    /// same-frame land+relaunch) — the airborne direction flags re-seed from the current keys.
+    /// A first airborne frame or a fresh jump, a same-frame land and relaunch included.
     pub(super) new_arc: bool,
-    /// The arc ended this frame (airborne last frame, grounded now) — emit `MSG_MOVE_FALL_LAND`.
+    /// The arc landed this frame: send `MSG_MOVE_FALL_LAND`.
     pub(super) landed: bool,
 }
 
 impl Player {
-    /// Advance the airborne-arc bookkeeping one frame and return the wire lifecycle edges
-    /// (decisions 0053/0058/0179). Call once per non-swim frame, **after** the mover has written
-    /// this frame's `pos`/`vel_y`. `airborne` is this frame's airborne state; `jumped` whether a
-    /// fresh jump launched this frame; `launch_y` the ground height the mover started this frame at
-    /// (the pre-step feet Y) — the true takeoff height.
+    /// Advances the arc; call once per non-swim frame, after the mover wrote `pos` and `vel_y`.
+    /// `launch_y` is the pre-step feet Y, the true takeoff height.
     ///
-    /// A **new arc** is a first airborne frame OR any fresh `jumped`. The mover only raises
-    /// `jumped` on a *grounded* frame, so a land-and-relaunch inside a single frame — spamming
-    /// Space until its just-pressed edge lands on the touchdown frame, so `airborne` never drops —
-    /// is a brand-new jump, not a continuation. Keying the launch snapshot on that (rather than on
-    /// the airborne rising-edge alone) is what stops the relaunch from inheriting the previous
-    /// arc's launch height / far-latch and flashing Fall(40) for one jump.
+    /// A new arc (a first airborne frame, or any `jumped`, which the mover raises only when
+    /// grounded) snapshots the fall clock, the launch speed (`StartFalling`'s `+0xa0`: the jump
+    /// speed, or exactly 0 for a step-off's `StartFalling(0)`) and the launch height (`+0x7c`),
+    /// and clears the far latch. The height is `launch_y`, not the post-step `pos.y` a tick
+    /// higher, which would read a flat jump's descent as a far fall.
     ///
-    /// A new arc snapshots the launch state: the fall clock, the (constant) launch vertical speed —
-    /// the client's `StartFalling` argument `+0xa0`: `vel_y` (`JUMP_SPEED`) for a jump, **exactly
-    /// 0** for a step-off (the walk election calls `StartFalling(0)`, not the gravity-polluted
-    /// first tick), which the wire tail and the FALLINGFAR leg both key on — the launch height, and
-    /// clears the per-arc far latch. The height is `launch_y` (the client's `+0x7c` Z snapshot,
-    /// taken at takeoff), **not** the post-step `pos.y`: on the takeoff frame the mover has already
-    /// integrated one jump-tick upward (`pos.y ≈ ground + JUMP_SPEED·dt ≈ 0.13 yd at 60 fps`), so
-    /// snapshotting `pos.y` would seat the launch height a tick too high and the descent back to the
-    /// real ground would read as a `FALL_FAR_DROP` (1/9 yd) fall — Fall(40) for a frame near every
-    /// landing, worse the lower the frame rate (the bug the director hit spamming jumps). Landing
-    /// clears the clock.
-    ///
-    /// Then the FALLINGFAR latch (`0x633240`, decision 0179): the two legs are **exclusive on the
-    /// launch vz** — a jump (vz ≠ 0) latches by DESCENT [`FALL_FAR_DROP`] below its launch, a
-    /// step-off fall (vz = 0) by TIME [`FALL_FAR_TIME`] airborne. Latched once per arc (only a
-    /// landing clears `fall_far`, like the client's StopFalling). A flat jump returns exactly to its
-    /// launch ground, staying strictly above `launch_y − 1/9`, so it never latches — its hang stays
-    /// Jump(38).
+    /// FALLINGFAR (`0x633240`) splits on the launch speed: a jump latches [`FALL_FAR_DROP`] below
+    /// its launch, a step-off after [`FALL_FAR_TIME`] airborne; only a landing clears it.
     pub(super) fn advance_airborne_arc(
         &mut self,
         airborne: bool,
@@ -61,19 +33,14 @@ impl Player {
         let new_arc = airborne && (!was_airborne || jumped);
         if new_arc {
             self.airborne_since = Some(now);
-            // From `launch_vz`, NOT `vel_y` (decision 1740): the mover now integrates gravity on
-            // the take-off frame too, so `vel_y` has already moved `g·dt` down the parabola by the
-            // time this runs and would seat the arc's launch speed a step short — visible on the
-            // wire, where the jump tail sends this value on every packet of the arc, and in the
-            // FALLINGFAR leg split. The reference writes `+0xa0` once, in `StartFalling`.
+            // `launch_vz`, not `vel_y`, which the mover has already moved one `g·dt` down. The
+            // reference writes `+0xa0` once, in `StartFalling`, and the jump tail sends it all arc.
             self.jump_zspeed = if jumped { self.launch_vz } else { 0.0 };
             self.fall_start_y = launch_y;
             self.fall_far = false;
         } else if !airborne {
             self.airborne_since = None;
-            // The arc is over: its direction nibble and its knockback provenance go with it, so
-            // the next standstill jump gets its one steer back and the wire stops planting FORWARD
-            // (decision 1740). The reference's `StopFalling` is the same edge.
+            // The reference's `StopFalling` edge: the arc's steer nibble and knockback go with it.
             self.arc_dirs_set = false;
             self.knock_arc = false;
         }
@@ -90,17 +57,10 @@ impl Player {
         }
         ArcEdges {
             new_arc,
-            // A landing closes the arc (→ MSG_MOVE_FALL_LAND). A same-frame relaunch keeps
-            // `airborne` true, so no FALL_LAND fires — the bounce streams a fresh JUMP instead.
-            //
-            // **A root ends the arc without landing it** (decision 0880). `SetRoot`'s `StopFalling`
-            // clears FALLING wherever the body happens to be, and the reference *separately*
-            // suppresses the land packet while rooted (`0x602df3 test ah,0x10` gating opcode
-            // `0xc9`). Both halves matter here: without the suppression a stun caught mid-fall would
-            // report a touchdown in mid-air — a `MSG_MOVE_FALL_LAND` carrying the whole accumulated
-            // fall clock, which vmangos `Player::HandleFall` reads as a killing drop, plus the local
-            // wound grunt and dust puff of a landing that never happened. On release the fall
-            // restarts as a fresh arc from a zero clock, which is `ClearRoot`'s `StartFalling(0)`.
+            // A same-frame relaunch stays airborne and streams a JUMP. A root ends the arc in
+            // mid-air (`SetRoot`'s `StopFalling`) with no land packet (`0x602df3 test ah,0x10`
+            // before opcode `0xc9`), which would hand vmangos `Player::HandleFall` the whole fall
+            // clock; the release is a fresh arc, `ClearRoot`'s `StartFalling(0)`.
             landed: !airborne && was_airborne && !self.modes.rooted,
         }
     }
@@ -112,40 +72,27 @@ mod tests {
     use super::*;
     use bevy::prelude::Vec3;
 
-    /// One jump-tick of upward travel the mover integrates *within* the takeoff step (60 fps) — so
-    /// the post-step `pos.y` on the takeoff frame sits this far above the true launch ground.
+    /// The rise within a 60 fps takeoff step: the takeoff frame's post-step `pos.y` sits this high.
     const TAKEOFF_RISE: f32 = JUMP_SPEED / 60.0;
 
-    /// The bug's precondition, as a compile-time invariant: one takeoff tick of rise exceeds the
-    /// far-fall drop, so snapshotting the *risen* takeoff `pos.y` as the launch height (instead of
-    /// the pre-step ground) would latch FALLINGFAR on the descent back to ground at 60 fps — the
-    /// Fall(40) flash. The fix seats the launch height at the ground, defeating this.
+    /// A launch height from the risen `pos.y` would latch FALLINGFAR on a flat jump's descent.
     const _: () = assert!(TAKEOFF_RISE > FALL_FAR_DROP);
 
-    /// What a **real** step-off's first frame descends at 60 fps: the walk election launches at
-    /// vz 0, gravity gives it `g·dt`, and the step moves it `g·dt²`. Small — ~5 mm — and that is
-    /// the point: 1458's report edge asks only whether the body went down *at all*, so the margin
-    /// between a genuine walk-off and a body that went nowhere is this, not a threshold anyone
-    /// picked.
+    /// A step-off's first-frame descent at 60 fps, `g·dt²` from vz 0: about 5 mm.
     const FIRST_TICK_DROP: f32 = GRAVITY / (60.0 * 60.0);
 
-    /// A grounded player about to jump from ground height `ground`. `launch_y` passed to
-    /// `advance_airborne_arc` is this pre-step feet Y; the takeoff frame's post-step `pos.y` is
-    /// already `ground + TAKEOFF_RISE` (the mover moved up within the step).
+    /// A grounded player about to jump from `ground`, the `launch_y` its takeoff frame passes.
     fn grounded_at(ground: f32) -> Player {
         Player {
             vel_y: JUMP_SPEED,
-            // The mover records this the instant the take-off is decided, and the arc snapshot
-            // reads it rather than `vel_y` (decision 1740) — by the time the bookkeeping runs, the
-            // real mover has already stepped `vel_y` one `g·dt` down the parabola.
+            // Recorded at the takeoff; by the time the arc runs, `vel_y` is a `g·dt` lower.
             launch_vz: JUMP_SPEED,
             pos: Vec3::new(0.0, ground, 0.0),
             ..Default::default()
         }
     }
 
-    /// Run the takeoff frame of a jump from `ground`: `launch_y` = the pre-step ground, `pos.y`
-    /// already risen one tick (as the real mover leaves it). Returns the player mid-arc.
+    /// The takeoff frame of a jump from `ground`, leaving `pos.y` a tick risen as the mover does.
     fn take_off(ground: f32) -> Player {
         let mut p = grounded_at(ground);
         let edges = p.advance_airborne_arc(true, true, 0.0, ground);
@@ -154,17 +101,10 @@ mod tests {
         p
     }
 
-    /// **The launch speed on the wire is the LAUNCH's, not the post-step velocity** (decision
-    /// 1740). The mover integrates gravity on the take-off frame too, so `vel_y` is already
-    /// `g·dt` down by the time the arc bookkeeping runs; reading it would send observers a jump
-    /// tail one step short (0.32 yd/s at 60 fps, 0.64 at 30 — and frame-rate dependent, so two
-    /// clients watching the same jump would disagree). The reference writes `+0xa0` once, in
-    /// `StartFalling`, and never touches it again for the arc.
     #[test]
     fn the_arc_snapshots_the_launch_speed_not_the_already_integrated_one() {
         let mut p = grounded_at(100.0);
-        // What the mover leaves behind on the take-off frame: the launch recorded, `vel_y` already
-        // advanced one step by the exact fall step.
+        // The takeoff frame as the mover leaves it: the launch recorded, `vel_y` one fall step on.
         let dt = 1.0 / 60.0;
         p.vel_y = super::super::mover::fall_step(JUMP_SPEED, dt, 60.148_003).0;
         assert!(
@@ -179,9 +119,6 @@ mod tests {
         );
     }
 
-    /// The arc's direction nibble and its knockback provenance are **arc-scoped**: a landing
-    /// clears both, so the next standstill jump gets its one steer back and the wire stops
-    /// planting FORWARD (decision 1740 — the reference's `StopFalling` edge).
     #[test]
     fn landing_clears_the_arc_nibble_and_the_knockback_provenance() {
         let mut p = grounded_at(100.0);
@@ -197,8 +134,6 @@ mod tests {
     #[test]
     fn a_fresh_jump_snapshots_the_true_launch_ground_not_the_risen_pos() {
         let mut p = grounded_at(100.0);
-        // Takeoff: pos.y is already one tick up (mover integrated the jump within the step), but the
-        // launch height must be the pre-step ground, or the descent back to it reads as a far fall.
         p.pos.y = 100.0 + TAKEOFF_RISE;
         let edges = p.advance_airborne_arc(true, true, 0.0, 100.0);
         assert!(edges.new_arc);
@@ -212,12 +147,8 @@ mod tests {
 
     #[test]
     fn a_flat_jump_landing_back_on_its_ground_never_latches_falling_far() {
-        // The director's bug: a plain jump on flat ground, descending back to exactly the launch
-        // height. With the launch height seated at the ground (not one tick up), the descent stays
-        // strictly above ground − 1/9 yd, so FALLINGFAR never latches — the hang stays Jump(38).
+        // Rise, apex and back down to exactly the launch height.
         let mut p = take_off(100.0);
-        // Rise, apex, then descend all the way back to the ground (the last airborne frame clips to
-        // the floor at exactly the launch height).
         for (t, y) in [
             (0.10, 100.6),
             (0.20, 100.75),
@@ -236,16 +167,12 @@ mod tests {
 
     #[test]
     fn snapshotting_the_risen_pos_would_have_latched_a_flat_jump() {
-        // Locks in *why* the launch height is the pre-step ground: had we snapshotted the risen
-        // takeoff pos.y instead, the same flat jump WOULD latch — the regression this fix removes.
         let ground = 100.0;
         let risen = ground + TAKEOFF_RISE;
-        // The distance leg with the (wrong) risen launch height, evaluated at the touchdown ground.
         assert!(
             ground <= risen - FALL_FAR_DROP,
             "the risen launch height puts the far-fall threshold above the ground"
         );
-        // And with the (correct) ground launch height, it does not.
         assert!(
             ground > ground - FALL_FAR_DROP,
             "the ground launch height keeps the whole flat jump above the threshold"
@@ -254,10 +181,8 @@ mod tests {
 
     #[test]
     fn a_same_frame_land_and_relaunch_is_a_new_arc_not_a_far_fall() {
-        // Spamming Space so its just-pressed edge lands on the touchdown frame: the mover reports
-        // grounded+jumped in one frame, `airborne` never drops. The prior jump launched from a
-        // touch HIGHER (100.3) than the ground we relaunch off (100.0); a stale launch height would
-        // classify the relaunch as a far fall. The fix re-snapshots the new arc's ground.
+        // A jump from 100.3 lands and relaunches off 100.0 in one frame, so `airborne` never
+        // drops; the old launch height would read the relaunch as a far fall.
         let mut p = take_off(100.3);
         p.pos.y = 100.0; // descended to the ground, still airborne
         p.vel_y = -6.0;
@@ -267,7 +192,7 @@ mod tests {
             "precondition: against the OLD arc's launch height this reads as a far fall"
         );
 
-        // The touchdown+relaunch frame: grounded (launch_y = the 100.0 ground) and jumped.
+        // The touchdown and relaunch frame, `launch_y` the 100.0 ground.
         p.vel_y = JUMP_SPEED;
         let edges = p.advance_airborne_arc(true, true, 0.42, 100.0);
         assert!(edges.new_arc, "a land+relaunch in one frame is a new arc");
@@ -288,14 +213,12 @@ mod tests {
 
     #[test]
     fn a_stale_far_latch_does_not_bleed_into_the_relaunch() {
-        // A prior arc that genuinely latched FALLINGFAR must not carry the latch into a same-frame
-        // relaunch — else the new jump plays Fall(40) from its very first frame.
         let mut p = take_off(100.0);
         p.pos.y = 90.0; // a real long fall this arc
         p.advance_airborne_arc(true, false, 0.6, 100.0);
         assert!(p.fall_far, "the prior arc latched a far fall");
 
-        // Land+relaunch in one frame off the low ground.
+        // Land and relaunch in one frame off the low ground.
         p.vel_y = JUMP_SPEED;
         let edges = p.advance_airborne_arc(true, true, 0.62, 90.0);
         assert!(edges.new_arc);
@@ -304,10 +227,7 @@ mod tests {
 
     #[test]
     fn a_step_off_fall_latches_falling_far_by_time_not_distance() {
-        // A step-off (airborne, not jumped) launches at vz 0 — the walk election's StartFalling(0)
-        // — so it latches by TIME, not descent, even before dropping a full 1/9 yd.
-        // `pos.y` is the POST-step pose, so a real step-off's first frame is already one tick of
-        // gravity below its launch ground ([`FIRST_TICK_DROP`]).
+        // A step-off's first post-step `pos.y` is already a tick below its launch ground.
         let mut p = Player {
             pos: Vec3::new(0.0, 100.0 - FIRST_TICK_DROP, 0.0),
             vel_y: -0.5,
@@ -316,11 +236,9 @@ mod tests {
         let edges = p.advance_airborne_arc(true, false, 0.0, 100.0);
         assert!(edges.new_arc, "the step-off opens an arc");
         assert_eq!(p.jump_zspeed, 0.0, "a step-off launches at exactly 0");
-        // Barely descended, but not yet FALL_FAR_TIME airborne.
         p.pos.y = 99.95;
         p.advance_airborne_arc(true, false, 0.3, 100.0);
         assert!(!p.fall_far, "under FALL_FAR_TIME: not yet a far fall");
-        // Past the timer leg.
         p.advance_airborne_arc(true, false, FALL_FAR_TIME + 0.01, 100.0);
         assert!(
             p.fall_far,
@@ -328,12 +246,8 @@ mod tests {
         );
     }
 
-    /// A root or a stun caught mid-fall **ends the arc without landing it** (decision 0880). The
-    /// mover holds the body where it was (its anchor), so `airborne` goes false in mid-air — and the
-    /// reference suppresses the land packet on exactly that state (`0x602df3`). Were it not
-    /// suppressed, the frame the stun lands would report a touchdown 30 yd up carrying the whole
-    /// accumulated fall clock, which vmangos `Player::HandleFall` reads as a killing drop, and would
-    /// fire the local wound grunt + dust puff for a landing that never happened.
+    /// The mover's anchor holds a rooted body in mid-air, so `airborne` drops there; the reference
+    /// sends no land packet in that state (`0x602df3`).
     #[test]
     fn a_root_taken_mid_fall_ends_the_arc_without_landing_it() {
         let mut p = take_off(100.0);
@@ -345,8 +259,7 @@ mod tests {
         let edges = p.advance_airborne_arc(false, false, 1.2, 100.0);
         assert!(!edges.landed, "a root ENDS the arc; it does not land it");
         assert_eq!(p.airborne_since, None, "and the fall clock is cleared");
-        // The control that gives the assertion its teeth: the identical frame with no root is a
-        // landing. The gate is the root, not "any arc that ends".
+        // Control: the same frame without the root is a landing.
         let mut q = take_off(100.0);
         q.pos.y = 70.0;
         q.advance_airborne_arc(true, false, 1.0, 100.0);
@@ -356,9 +269,8 @@ mod tests {
         );
     }
 
-    /// Releasing the root in mid-air is `ClearRoot 0x7c7370`'s `StartFalling` — a **fresh** arc from
-    /// a zero clock, not a resumption of the one the root ate. That is what keeps the drop honest:
-    /// the fall damage the server assesses is measured from the release, not from before the stun.
+    /// A mid-air release is `ClearRoot`'s (`0x7c7370`) `StartFalling(0)`: a fresh arc from a zero
+    /// clock, so the server measures the fall from the release.
     #[test]
     fn releasing_the_root_mid_air_starts_a_fresh_fall_not_a_resumption() {
         let mut p = take_off(100.0);
diff --git a/crates/benilla-app/src/player/body_pose.rs b/crates/benilla-app/src/player/body_pose.rs
index e2e4fdfc..f397f84a 100644
--- a/crates/benilla-app/src/player/body_pose.rs
+++ b/crates/benilla-app/src/player/body_pose.rs
@@ -1,20 +1,12 @@
-//! **Writing the frame onto the body we drive** — the last thing the controller does to the
-//! avatar itself, after the mover has moved it and [`super::gait`] has decided where it faces.
-//!
-//! The driven entity is a streamed unit like any other (decision 0041), so this is not a special
-//! "player render" path: it writes the same transform and the same `MovementState` the entity
-//! renderer would, which is exactly why a *possessed creature* needs nothing extra here
-//! (decision 1277). It is also where the frame's landing is reported to the local hard-landing
-//! predictor, and where the camera-pivot target for this frame is read off the body — the one
-//! value that leaves this module, because the camera seat consumes it.
+//! Writes the frame onto the driven body after the mover and [`super::gait`]: the transform and
+//! `MovementState` any streamed unit carries, the landing report and the camera-pivot target.
 
 use bevy::prelude::*;
 
 use super::{model_pivot_height, wrap_pi, BodyQuery, CameraPivot, Player};
 
-/// Write this frame onto the driven body and return the camera-pivot **target** height it carries.
-/// `anim_flags` is [`super::gait::drive_body_heading`]'s verdict; `move_flags_now` is the live
-/// wire word, whose forward/back bits gate the swim body pitch.
+/// Writes this frame onto the driven body and returns its camera-pivot target height;
+/// `anim_flags` is [`super::gait::drive_body_heading`]'s result.
 pub(super) fn drive(
     player: &Player,
     body: &mut BodyQuery,
@@ -26,54 +18,33 @@ pub(super) fn drive(
     landed: bool,
     stand_now: u8,
 ) -> Option<f32> {
-    // Drive the streamed self entity: its transform is the avatar's pose (feet position + body
-    // heading, like every other streamed unit), and its `MovementState` is the live movement the
-    // animation selector reads. Scale is left untouched (the renderer baked the display scale on).
-    // `horiz_vel` is already the directional speed (runBack when backpedaling), so the backpedal
-    // clip scales by it and no longer drags.
-    // This frame's camera-pivot **target** — the model-local [`CameraPivot`] × the body's RAW
-    // scale, clamped (see [`super::camera::head_height`] for why raw and not the rendered scale).
-    // `None` while the body has no model yet: the channel holds rather than aiming at a
-    // placeholder, which is what makes a display swap one glide instead of two.
+    // Scale is left alone: the renderer bakes the display scale in.
     let mut cam_pivot_target = None;
     if let Ok((entity, mut t, motion, pivot, .., twist, _, net_entity)) = body.single_mut() {
         t.translation = player.pos;
-        // The swim body pitch — [`crate::creature_anim::swim_body_rotation`], the one law shared
-        // with every observed mover. The pitch presented is this frame's `swim_pitch` — the raw
-        // aim, except leveled by the 0499 surface redirect when the rest-line cap bites (the body
-        // swims flat along the surface, not pitched against it); the wire tail streams the same
-        // value, so what an observer renders for us is what we render for ourselves.
-        //
-        // `swimming` is not passed separately: it is `move_flags_now`'s own SWIMMING bit (the
-        // controller sets the wire word from the same state), and the law reads it there.
+        // The swim pitch law every observed mover shares. `swim_pitch` is the aim, leveled along
+        // the surface when the rest-line cap bites, and the wire tail streams the same value.
         t.rotation =
             crate::creature_anim::swim_body_rotation(player.model_yaw, move_flags_now, swim_pitch);
-        // Report every landing's fall height for the client-side landing predictor
-        // (`0x602d00`, decision 0412): its consumers gate on the descent and, past the HARD
-        // floor, play the wound grunt + a locally-predicted dust puff at THIS frame — the
-        // server's 0x1FC echo arrives ~an RTT later (the reference double-fires the dust the
-        // same way). `fall_start_y` still holds this arc's launch height here (it is only
-        // re-seeded at the next take-off).
+        // The landing predictor (`0x602d00`) plays a hard landing's grunt and dust this frame;
+        // the server's `SMSG_ENVIRONMENTALDAMAGELOG` dust follows a round trip later, as in the
+        // reference. `fall_start_y` still holds this arc's launch height.
         if landed {
             hard_landing.write(crate::creature_anim::HardLanding {
                 entity,
                 descent: player.fall_start_y - player.pos.y,
             });
         }
-        // The camera's framing-pivot target, taken off the same word the body pitch above reads:
-        // `0x50f880` selects the swim preset on the CAMERA TARGET's own MOVEFLAG_SWIMMING, and the
-        // camera target is this driven body (0041/1277). Reading the flag word rather than the
-        // `swimming` argument keeps the pitch and the pivot on one source, which is what stops them
-        // ever disagreeing about which frame the water started.
+        // `0x50f880` picks the swim pivot preset off the camera target's own SWIMMING bit, read
+        // from the pitch's word so the two agree on the frame the water starts.
         cam_pivot_target = pivot_target(
             pivot,
             net_entity,
             move_flags_now & crate::creature_anim::move_flags::SWIMMING != 0,
         );
         if let Some(mut motion) = motion {
-            // A swimmer's stroke rate takes the flag-scalar directional speed (full rate at
-            // any pitch — a vertical climb must not freeze the stroke); the ground gaits
-            // scale by the achieved horizontal speed as before.
+            // A swimmer strokes at the flag-scalar speed whatever its pitch; ground gaits take the
+            // achieved horizontal speed, already directional (run-back while backpedaling).
             motion.speed = if swimming {
                 player.swim_stroke_speed
             } else {
@@ -83,15 +54,8 @@ pub(super) fn drive(
             motion.flags = anim_flags;
             motion.stand_state = stand_now;
         }
-        // The counter-twist gap: how far the aim sits from the rendered body — the strafe
-        // offset while it lasts, unwinding to zero as `model_yaw` closes on `face_yaw`.
+        // The counter-twist gap: the aim's offset from the rendered body.
         if let Some(mut twist) = twist {
-            // `WOW_TWIST_GAP=<radians>` forces the gap — the counter-twist's A/B lever. The
-            // pass is inert at `yaw_gap == 0` and a scripted probe cannot open a real gap
-            // (`WOW_PROBE_CAM` turns the model with the camera, so the measured gap is float
-            // noise, ~1e-6 rad), which means "removing the twist changed nothing" has never
-            // yet been a measurement of the twist — only of a pass that never ran. This is
-            // what lets it actually be exercised.
             twist.yaw_gap =
                 twist_gap_override().unwrap_or_else(|| wrap_pi(player.face_yaw - player.model_yaw));
         }
@@ -99,22 +63,12 @@ pub(super) fn drive(
     cam_pivot_target
 }
 
-/// The camera pivot's **target** height for a driven body: its model-local [`CameraPivot`] × the
-/// body's raw `OBJECT_FIELD_SCALE_X`, clamped — or `None` before its model has attached.
-///
-/// `swimming` is the body's own MOVEFLAG_SWIMMING, and it picks the preset exactly as `0x50f880`
-/// does (`0x50f89e test [[unit+0x118]+0x40],0x200000` → `cam+0x124`): the framing pivot sits lower
-/// on a swimmer by the model's [`CameraPivot::swim_drop_local`]. Nothing here glides — the preset is
-/// a step function of the flag, and [`super::camera::PivotGlide`] is what walks the channel between
-/// two of them, so entering the water reads as one smooth dip for free.
-///
-/// `None` is the load-bearing half. The reference recomputes the pivot preset only on a model event
-/// and *skips the camera update entirely* while the model is unresolved (`0x50e907`), so a
-/// display swap reads as a brief hold and then one glide. Aiming the channel at a placeholder height
-/// during those frames instead would send the camera on a round trip nobody asked for.
-///
-/// The **raw** scale (not the transform's eased one) is the reference's own input — see
-/// [`super::camera::head_height`] for the byte citation and why the distinction is visible.
+/// The camera pivot's target height: the model-local [`CameraPivot`] times the body's raw
+/// `OBJECT_FIELD_SCALE_X`, not the eased render scale, clamped. `swimming` picks the preset as
+/// `0x50f880` does (`0x50f89e`, `cam+0x124`), lower by [`CameraPivot::swim_drop_local`];
+/// [`super::camera::PivotGlide`] glides between presets. `None` until the model attaches: the
+/// reference skips the camera update while the model is unresolved (`0x50e907`), so a display
+/// swap holds, then glides once.
 pub(super) fn pivot_target(
     pivot: Option<&CameraPivot>,
     net: Option<&crate::net::NetEntity>,
@@ -123,8 +77,7 @@ pub(super) fn pivot_target(
     pivot.map(|p| model_pivot_height(p, net.map_or(1.0, |n| n.scale), swimming))
 }
 
-/// `WOW_TWIST_GAP=<radians>`: pin the body counter-twist's yaw gap instead of deriving it from
-/// aim-minus-model. Zero-cost when unset: one env read, once.
+/// `WOW_TWIST_GAP=<radians>` pins the counter-twist's yaw gap; the env is read once.
 fn twist_gap_override() -> Option<f32> {
     static G: std::sync::OnceLock<Option<f32>> = std::sync::OnceLock::new();
     *G.get_or_init(|| {
diff --git a/crates/benilla-app/src/player/camera.rs b/crates/benilla-app/src/player/camera.rs
index 32a78a99..16114d8d 100644
--- a/crates/benilla-app/src/player/camera.rs
+++ b/crates/benilla-app/src/player/camera.rs
@@ -1,8 +1,5 @@
-//! The third-person camera rig: the two mouse-look modes (right-drag turns the character, left-drag
-//! orbits the camera), the wheel-zoom glide, the collision-swept boom that seats the camera behind the
-//! avatar's framing [`CameraPivot`], and the self-avatar zoom-in fade as the boom pulls into first
-//! person. Split out of the controller — this owns the camera's pose and input session, not the
-//! avatar/movement/networking [`super::control`] drives with it.
+//! The third-person camera rig: the two mouse-look modes, the wheel-zoom glide, the
+//! collision-swept boom on the framing pivot, and the self-avatar fade into first person.
 
 use bevy::ecs::entity::EntityHashSet;
 use bevy::input::mouse::AccumulatedMouseMotion;
@@ -20,50 +17,19 @@ use benilla_world::model_fade::{
     self_model_fade_alpha, FadeMaterials, PendingAppearFade, RenderFade, SELF_FADE_WINDOW,
 };
 
-/// The reference's up-edge click predicate, in **camera degrees and milliseconds** — the whole
-/// 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 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
-/// guess.
-///
-/// **A press under 200 world selects however far the mouse swept.** That arm is the entire bug report
-/// (ledger B226): flick the cursor across a mob and click on arrival with the hand still moving, and
-/// the reference targets it — the camera has been orbiting since the first motion sample and selects
-/// anyway. The two mechanisms are independent and share only the button state.
-///
-/// **The orbit has no threshold at all** — it engages on the *down* edge (`0x51491f`, guarded only by
-/// the 0→1 held transition) and the first motion sample already turns the camera. benilla deferred it
-/// behind 4 px of travel and, worse, *destroyed* the pending click on crossing; there is no such
-/// thing in the reference. The travel numbers below gate the **click**, never the orbit.
-///
-/// The literals in the binary are 8.0 event-units per axis against `Σ|0.8·Δx|` / `Σ|0.6·Δy|` of raw
-/// device counts. Copying those would bind us to the reference's device scaling, which is itself
-/// only INFERRED ("1 unit = 1 mouse count" is not established). So we copy the **angle** they mean,
-/// which is exact and device-independent: 8.0 event-units is `Σ|Δx| = 10.0` raw ⇒
-/// `cameraYawMoveSpeed·10/800` = **2.25°** of yaw at the shipped default 180; and `Σ|Δy| = 13.333`
-/// raw ⇒ `cameraPitchMoveSpeed·13.333/600` = **2.0°** of pitch at the default 90.
-///
-/// Per axis, independently, and **accumulated absolute travel** — not net displacement from the
-/// press point (`0x514400`: `fabs; fadd; fstp`, no subtraction and no stored origin). A shake that
-/// returns to where it started still spends the budget.
+/// The reference's up-edge click predicate (`0x514ae0`): a click is a release within 200 ms, or
+/// within 800 ms under 2.25° of yaw and 2.0° of pitch travel (ms from `GetTickCount`, `[0x7ff310]`,
+/// via `0x42c010` → `0x42b790`). The travel gates only the click; the orbit engages on the down
+/// edge (`0x51491f`). Travel sums absolute motion per axis (`0x514400`: `fabs; fadd; fstp`). The
+/// literals are 8.0 event-units against `Σ|0.8·Δx|`, `Σ|0.6·Δy|` of mouse deltas of untraced device
+/// scale; we hold the angles they mean at the default speeds (`180·10/800`, `90·13.333/600`).
 const CLICK_HOLD_CEILING: f32 = 0.800;
 const CLICK_FREE_WINDOW: f32 = 0.200;
 const CLICK_YAW_TRAVEL: f32 = 2.25 * std::f32::consts::PI / 180.0;
 const CLICK_PITCH_TRAVEL: f32 = 2.0 * std::f32::consts::PI / 180.0;
 
-/// A primary button's press, while it is still undecided — the reference's world-input state
-/// (`[0xbe1148]`): press instant `+0x14`, and the two independent motion accumulators zeroed at
-/// `0x514910`/`0x514913`. Our accumulators are in **radians of camera rotation** rather than device
-/// counts, for the reason in [`CLICK_HOLD_CEILING`]'s note.
+/// An undecided primary press: the reference's world-input state (`[0xbe1148]`), press time at
+/// `+0x14`, accumulators zeroed at `0x514910`/`0x514913`; ours are radians of camera rotation.
 #[derive(Clone, Copy)]
 pub(super) struct PressGesture {
     /// Seconds on the app clock when the button went down.
@@ -82,7 +48,6 @@ impl PressGesture {
         }
     }
 
-    /// `0x514ae0`, minimised: the free window first, then the bounded-travel window.
     fn is_click(&self, now: f32) -> bool {
         let elapsed = now - self.at;
         elapsed < CLICK_FREE_WINDOW
@@ -92,52 +57,30 @@ impl PressGesture {
     }
 }
 
-/// 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`) —
-/// the reference's, and since 1804 ours. This file shipped the factor fully raised (30 yd) from
-/// 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 (`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.
+/// The zoom floor, yd: at 0 the eye sits at the framing pivot, inside the head, and the avatar
+/// fades out. The reference clamps the orbit to `cameraDistanceMax × cameraDistanceMaxFactor`,
+/// capped at 50 (`0x5112d0`). Deviation: the starting zoom, [`CAM_DIST_DEFAULT`], is 15 yd where
+/// the reference's `cameraDistance` is 5.55 (`0x84f488`), for a wider view.
 pub(super) const CAM_DIST_MIN: f32 = 0.0;
-/// The reference's `cameraDistanceMax` — the BASE the factor multiplies (registrar default 15).
-/// Not exposed: 1.12's panel offers only the factor, so this stays the constant it is there.
+/// The reference's `cameraDistanceMax` (default 15); 1.12's panel offers only the factor.
 pub(super) const CAM_DIST_BASE_MAX: f32 = 15.0;
-/// `cameraDistanceMaxFactor`'s slider range — 1.12's own (MAX_FOLLOW_DIST: 1 … 2, step 0.1).
+/// `cameraDistanceMaxFactor`'s slider, MAX_FOLLOW_DIST (1 to 2 by 0.1, `UIOptionsFrame.lua:90`).
 pub(crate) const CAM_DIST_FACTOR_RANGE: std::ops::RangeInclusive<f32> = 1.0..=2.0;
-/// The orbit ceiling at the factor slider's **top** — the furthest any saved view or restored
-/// camera pose may sit. Not the shipped default any more (1804): [`ZoomLimit::default`] is the
-/// slider at rest, `1 × 15`. This is what a distance read back off disk is clamped to, which has
-/// to admit the whole slider range rather than only its resting point.
+/// The factor slider's top: the clamp for a distance read back off disk ([`ZoomLimit`] is live).
 pub(super) const CAM_DIST_MAX: f32 = CAM_DIST_BASE_MAX * 2.0;
 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` (`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
-/// nothing; lowering it re-clamps the live target on the next frame, so the view comes in rather
-/// than waiting for the next wheel notch.
+/// The max orbit distance: 1.12's `cameraDistanceMaxFactor` over [`CAM_DIST_BASE_MAX`], 15 yd at
+/// the reference's defaults (`cameraDistanceMax` "15.0" at `0x84fbd0`, `cameraDistanceMaxFactor`
+/// "1.0" at `0x82e92c`). Lowering the factor pulls the live target in on the next frame.
 #[derive(Resource)]
 pub(crate) struct ZoomLimit {
-    /// Max orbit distance in yards — `CAM_DIST_BASE_MAX × factor`, hard-capped like the client's 50.
     pub(crate) max: f32,
 }
 
 impl Default for ZoomLimit {
     fn default() -> Self {
-        // The slider at rest — `cameraDistanceMaxFactor` 1.0 × the 15 yd base, i.e. the reference's
-        // own out-of-box ceiling. `CAM_DIST_MAX` is the slider's TOP, and belongs to the clamps.
+        // Factor 1.0, the reference's default; `CAM_DIST_MAX` is the slider's top.
         Self {
             max: CAM_DIST_BASE_MAX,
         }
@@ -145,36 +88,28 @@ impl Default for ZoomLimit {
 }
 
 impl ZoomLimit {
-    /// Set from the CVar's factor, clamped to the reference's slider range first.
     pub(crate) fn set_factor(&mut self, factor: f32) {
         let f = factor.clamp(*CAM_DIST_FACTOR_RANGE.start(), *CAM_DIST_FACTOR_RANGE.end());
         self.max = CAM_DIST_BASE_MAX * f;
     }
 
-    /// The live factor — the inverse of [`Self::set_factor`], kept for the weld test (the
-    /// registry holds the string itself since 2303).
+    /// The live factor, the inverse of [`Self::set_factor`], for tests.
     #[cfg(test)]
     pub(crate) fn factor(&self) -> f32 {
         self.max / CAM_DIST_BASE_MAX
     }
 }
-/// Yards the wheel moves the target per notch — `CameraZoomIn`/`CameraZoomOut`'s default `amount`
-/// (VERIFIED 1.0 in `WoW.exe`).
+/// Yards per wheel notch, the stock bindings' `CameraZoomIn(1.0)` (`Bindings.xml:707`).
 const CAM_ZOOM_STEP: f32 = 1.0;
-/// Camera zoom speed in **yards/second** — `cameraDistanceMoveSpeed` (VERIFIED default 8.33). Vanilla
-/// glides the distance toward the wheel target at this *constant velocity* (linear, frame-delta-scaled
-/// — `FUN_005112d0` in `WoW.exe`), **not** an exponential ease.
+/// Zoom speed in yd/s, `cameraDistanceMoveSpeed`'s default: the reference glides the distance to
+/// the wheel target at this constant speed (`0x5112d0`), not an ease.
 const CAM_MOVE_SPEED: f32 = 8.33;
-/// Mouse-look sensitivity at the slider's neutral notch — radians of camera rotation per pixel of
-/// mouse motion. [`LookConfig::sensitivity`] scales it; this is the ×1.0 case, and it is what the
-/// client felt like before there was a slider at all (decision 1140).
+/// Radians of camera rotation per raw mouse unit at the default move speeds and `mousespeed` 1.0.
 const LOOK_SENSITIVITY: f32 = 0.003;
-/// The `mousespeed` slider's range — 1.12's own (UIOptionsFrameSliders' MOUSE_SENSITIVITY row:
-/// 0.5 … 1.5, step 0.05). A multiplier over [`LOOK_SENSITIVITY`], so the registered default 1.0
-/// reproduces the shipped feel exactly.
+/// `mousespeed`'s slider, MOUSE_SENSITIVITY (0.5 to 1.5 by 0.05, `UIOptionsFrame.lua:87`).
 pub(crate) const MOUSE_SPEED_RANGE: std::ops::RangeInclusive<f32> = 0.5..=1.5;
 
-/// The camera rows' change callback (decision 2303) — the look, zoom and follow knobs.
+/// The camera rows' change callback: the look, zoom and follow knobs.
 pub(crate) fn on_cvar(
     ev: On<crate::cvars::CvarChanged>,
     mut look: ResMut<LookConfig>,
@@ -184,14 +119,9 @@ pub(crate) fn on_cvar(
     let v = ev.num();
     match ev.key().as_str() {
         "mouseinvertpitch" => look.invert_pitch = v != 0.0,
-        // The 1.12 slider's own range; an off-grid hand-edit rides between stops, like the others.
         "mousespeed" => {
             look.sensitivity = v.clamp(*MOUSE_SPEED_RANGE.start(), *MOUSE_SPEED_RANGE.end());
         }
-        // The reference's `0x50b330` validator REJECTS an out-of-range value rather than clamping
-        // it: it prints `Value out of range (%f - %f)` and `CVar::Set` never stores, so the old
-        // value stands. That is a different posture from every clamping row, and it is the
-        // faithful one — a script writing 1e9 gets a refusal, not a silently pinned camera.
         "camerayawmovespeed" | "camerapitchmovespeed" => {
             if !CAMERA_SPEED_RANGE.contains(&v) {
                 warn!(
@@ -209,12 +139,9 @@ pub(crate) fn on_cvar(
             }
         }
         "cameradistancemaxfactor" => zoom.set_factor(v),
-        // The three stops are 1 Smart / 2 Always / 3 Never; anything else reads as the registrar
-        // default rather than as a dead camera (`FollowStyle::from_cvar`).
+        // The stock dropdown writes 1 Smart, 2 Always, 0 Never (`UIOptionsFrame.lua:518`).
         "camerasmoothstyle" => follow.style = FollowStyle::from_cvar(v),
-        // Its sibling selector — the one the reference swaps in for the externally-driven states.
         "camerasmoothtrackingstyle" => follow.tracking_style = FollowStyle::from_cvar(v),
-        // The auto-follow rate, clamped to 1.12's own AUTO_FOLLOW_SPEED slider range.
         "camerayawsmoothspeed" => {
             follow.yaw_speed = v.clamp(*FOLLOW_SPEED_RANGE.start(), *FOLLOW_SPEED_RANGE.end());
         }
@@ -222,68 +149,30 @@ 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 (`0x50fee0`):
-///
-/// ```text
-///   Δyaw_deg   = cameraYawMoveSpeed   × Δx / 800
-///   Δpitch_deg = cameraPitchMoveSpeed × Δy / 600
-/// ```
-///
-/// **800 × 600 is a screen, not a magic number** — the era's reference resolution. At the shipped
-/// `180`/`90` the law reads: a drag across the full screen width is a half-turn, and a drag up the
-/// 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*: 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,
-/// unaccelerated device units**. `deg per accelerated pixel` and `deg per raw unit` are different
-/// quantities, and the factor between them is a per-machine OS setting, not a fact about the
-/// client — so transplanting `180`/`90` as absolute numbers would be a confident guess on a
-/// load-bearing constant.
-///
-/// So we take the law's **shape** — per-axis, linear in the CVar — and anchor its **scale** to
-/// [`LOOK_SENSITIVITY`], the rate this client has shipped and the director has been looking at
-/// since 1140. The CVars therefore keep the reference's own defaults (1804: a setting's default is
-/// the reference's) and the divergence lands here, in a named constant, where it can be read.
-///
-/// **The one live divergence this leaves**, stated rather than buried: the reference is
-/// *anisotropic* at its defaults — `180/800 = 0.225` deg/px of yaw against `90/600 = 0.15` of
-/// pitch, so its yaw turns 1.5× faster than its pitch. Ours is isotropic, because
-/// [`LOOK_SENSITIVITY`] is one number. The **ratio** is unit-independent (both axes take the same
-/// acceleration curve), so unlike the absolute scale it *is* transferable — it is simply a feel
-/// change, and feel is the director's call, not a fidelity bug to fix quietly.
+/// The mouse-look rate law. The reference's (`0x50fee0`) is `Δyaw° = cameraYawMoveSpeed × Δx / 800`
+/// and `Δpitch° = cameraPitchMoveSpeed × Δy / 600` in screen pixels after Windows acceleration
+/// (`WM_MOUSEMOVE`, `0x42d31c`; its `mousespeed` sets the OS pointer speed); ours are raw device
+/// units. Deviation: the shape is kept, its scale anchored to [`LOOK_SENSITIVITY`] on both axes at
+/// the default speeds, because the unit factor is a per-machine OS setting and this keeps the
+/// shipped feel: both axes turn alike, where the reference's yaw turns 1.5× faster than its pitch.
 const LOOK_YAW_PER_SPEED: f32 = LOOK_SENSITIVITY / 180.0;
 const LOOK_PITCH_PER_SPEED: f32 = LOOK_SENSITIVITY / 90.0;
 
-/// The reference's validator range for all four `camera*MoveSpeed`/`SmoothSpeed` CVars
-/// (`0x50c000` → `0x50b330`). It **rejects rather than clamps**: out of range prints
-/// `"Value out of range (%f - %f)"` and `CVar::Set` skips the store, so the old value stands.
+/// The reference's validator range for the `camera*MoveSpeed`/`SmoothSpeed` CVars (`0x50c000` →
+/// `0x50b330`): an out-of-range value prints "Value out of range" and the old one stands.
 pub(crate) const CAMERA_SPEED_RANGE: std::ops::RangeInclusive<f32> = 0.1..=360.0;
 
-/// The mouse-look player knobs (decision 0961): `mouseInvertPitch` is 1.12's own Interface
-/// Options checkbox (UIOptionsFrame.lua index 1, CVar-backed), settable from the Options
-/// window's Controls page through the CVar store (0954). Inverted, moving the mouse up pitches
-/// the camera down — the delta.y term flips sign at the one apply site, both drag styles alike.
-///
-/// `sensitivity` is 1.12's `mousespeed` slider (1140), the same story one layer down: the rate was
-/// a frozen constant with no way to reach it. It multiplies [`LOOK_SENSITIVITY`] at BOTH apply
-/// sites — the rotation itself and the click-vs-drag travel budget — because the reference scales
-/// the device delta once, upstream of everything that reads it, and a budget measured in unscaled
-/// pixels would make a click's drag threshold drift as the slider moved.
+/// The mouse-look knobs. `invert_pitch` is 1.12's `mouseInvertPitch` checkbox
+/// (`UIOptionsFrame.lua:4`); `sensitivity` is `mousespeed`, scaling both the rotation and the click
+/// travel budget, as the reference's OS pointer speed scales the delta upstream of both.
 #[derive(Resource, Clone, Copy)]
 pub(crate) struct LookConfig {
     pub(crate) invert_pitch: bool,
     pub(crate) sensitivity: f32,
-    /// `cameraYawMoveSpeed` — the MOUSE_LOOK_SPEED slider (90…270 by 10). See
-    /// [`LOOK_YAW_PER_SPEED`] for why the number is the reference's and the scale is ours.
+    /// `cameraYawMoveSpeed`, the MOUSE_LOOK_SPEED slider (90 to 270 by 10).
     pub(crate) yaw_speed: f32,
-    /// `cameraPitchMoveSpeed` — no slider of its own; `UIOptionsFrame_Save` writes it as
-    /// `cameraYawMoveSpeed / 2` beside the yaw one, which is exactly the reference's 180/90 pair.
+    /// `cameraPitchMoveSpeed`: no slider; `UIOptionsFrame_Save` writes it as half the yaw speed
+    /// (`UIOptionsFrame.lua:356`).
     pub(crate) pitch_speed: f32,
 }
 
@@ -292,8 +181,7 @@ impl Default for LookConfig {
         Self {
             invert_pitch: false,
             sensitivity: 1.0,
-            // The reference's registered defaults, and with them the shipped feel: at these two
-            // values both axes land on `LOOK_SENSITIVITY` exactly.
+            // The reference's defaults; at these both axes land exactly on `LOOK_SENSITIVITY`.
             yaw_speed: 180.0,
             pitch_speed: 90.0,
         }
@@ -301,86 +189,56 @@ impl Default for LookConfig {
 }
 
 impl LookConfig {
-    /// Radians of camera rotation per pixel of mouse motion, this session. ONE function because
-    /// both readers must agree: the look rotation itself and the click-vs-drag travel budget that
-    /// decides whether a press was a click. Splitting them would let the slider move the drag
-    /// threshold out from under the gesture (decision 1140).
+    /// Radians of yaw per raw mouse unit, read by both the rotation and the click travel budget.
     pub(super) fn yaw_rate(self) -> f32 {
         self.yaw_speed * LOOK_YAW_PER_SPEED * self.sensitivity
     }
 
-    /// The pitch axis's rate — its own CVar, because the reference's law has its own divisor for
-    /// it (600, the reference screen's height) and its own default (90).
+    /// Radians of pitch per raw mouse unit: its own CVar and the law's divisor 600.
     pub(super) fn pitch_rate(self) -> f32 {
         self.pitch_speed * LOOK_PITCH_PER_SPEED * self.sensitivity
     }
 }
-/// The auto-follow's angular rate — 1.12's `cameraYawSmoothSpeed`, registrar default **180 °/s**
-/// (`WoW.exe` `[0xbe1070]`, read at `0x512d75`). It is not a slew rate but a *duration* divisor:
-/// the transition below lasts `|Δyaw| / rate × factor`, so 180 °/s is the **average** rate at
-/// factor 1, and the cosine profile peaks at π/2 × that. 1.12 exposes it as the AUTO_FOLLOW_SPEED
-/// slider (`UIOptionsFrameSliders`, 90 … 270 by 10), disabled while the style is Never.
+/// `cameraYawSmoothSpeed`, default 180°/s (`[0xbe1070]`, read at `0x512d75`): a duration divisor,
+/// as a return lasts `|Δyaw| / rate × factor`. The AUTO_FOLLOW_SPEED slider, greyed under Never.
 pub(crate) const FOLLOW_SPEED_DEFAULT: f32 = 180.0;
 /// The 1.12 slider's own range for [`FollowConfig::yaw_speed`].
 pub(crate) const FOLLOW_SPEED_RANGE: std::ops::RangeInclusive<f32> = 90.0..=270.0;
-/// `cameraSmoothTimeMin`/`Max` — the transition's duration floor and ceiling, **VERIFIED
-/// 0.1 s / 2.0 s** (`[0xbe105c]`/`[0xbe1038]`, clamped at `0x510f4d`). These are why the felt
-/// rate is *not* 180 °/s at the ends: a 5° correction still takes 0.1 s, and a lazy `Track`
-/// return (factor 10) is capped at 2 s however far it has to come.
+/// `cameraSmoothTimeMin`/`Max`: 0.1 s and 2.0 s (`[0xbe105c]`/`[0xbe1038]`, clamped at `0x510f4d`).
 const FOLLOW_TIME_MIN: f32 = 0.1;
 const FOLLOW_TIME_MAX: f32 = 2.0;
-/// The "already there / already arming this" epsilon — the reference's own `0.001`
-/// (`[0x801360]`, `0x512ce4`/`0x512d41`). A float-equality guard, not a perceptible deadzone.
+/// The reference's 0.001 already-there and same-arm epsilon (`[0x801360]`, `0x512ce4`/`0x512d41`).
 const FOLLOW_EPS: f32 = 1.0e-3;
 
-/// **Camera Following Style** — 1.12's `cameraSmoothStyle` (decisions 1493/1502): does the camera
-/// return to behind the character on its own?
-///
-/// benilla shipped the reference behaviour *removed* from the day the camera was written (the
-/// 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`** — 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
-/// (`0x50b330(v, 0, 3)`) but the terrain-tilt consumer does not bound-check and indexes 360 bytes
-/// past its table. So the reference's shipped UI writes an out-of-range value for Never, and a
-/// client must clamp to 0..2. We do: our own dropdown writes the engine's numbers, and a stray
-/// `3` is *read* as Never — what whoever wrote it meant.
+/// Camera Following Style, 1.12's `cameraSmoothStyle`: whether the camera returns behind the
+/// character on its own. The engine's enum is 0 Never, 1 Smart, 2 Always (`0x50b6f0` registers
+/// them in that order and the consumers index by `style × stride`), the values the stock dropdown
+/// writes (`UIOptionsFrame.lua:518`). The validator also accepts 3 (`0x50b330(v, 0, 3)`), which
+/// arms nothing (`0x510a89`) and reads past the terrain-tilt table (`0x50dbc0`); ours reads Never.
 #[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
 pub(crate) enum FollowStyle {
-    /// Never auto-adjust: the orbit offset stays exactly where the hand left it. This is what
-    /// benilla did unconditionally before 1493. It does **not** stop the rigid keyboard-turn
-    /// carry — in the reference that is a different mechanism entirely (the camera yaw is stored
-    /// *relative* to the followed unit's facing), and Never leaves it running.
+    /// The offset stays put. The keyboard-turn carry is a separate mechanism (the reference's
+    /// camera yaw is relative to the unit's facing) and keeps running.
     Never,
-    /// Stay where placed, *except* while the character is being driven — the reference's own
-    /// "(Recommended Mode)" and its registrar default.
+    /// Stays where placed except while the character is being driven; the reference's default.
     #[default]
     Smart,
-    /// Always prefer being behind the character: every input edge arms a return, standing still
-    /// included.
+    /// Every input edge arms a return, standing still included.
     Always,
 }
 
 impl FollowStyle {
-    /// From the CVar's number. `3` is the shipped-UI's Never (see the type doc); anything else off
-    /// the ladder reads as the registrar default rather than as a dead camera.
+    /// From the CVar: 3 reads as Never (see the type doc), anything else off the ladder as Smart.
     pub(crate) fn from_cvar(v: f32) -> Self {
         match v as i32 {
             0 => Self::Never,
             2 => Self::Always,
-            // The 1.12 dropdown's own Never. Out of range for the engine's tables — accepted here
-            // because a config or addon carrying it means Never, not "surprise me".
             3 => Self::Never,
             _ => Self::Smart,
         }
     }
 
-    /// The CVar string this style is — the inverse of [`Self::from_cvar`], kept for the
-    /// round-trip test (the registry holds the string itself since 2303).
+    /// The CVar string, the inverse of [`Self::from_cvar`], for the round-trip test.
     #[cfg(test)]
     pub(crate) fn cvar(self) -> &'static str {
         match self {
@@ -390,61 +248,48 @@ impl FollowStyle {
         }
     }
 
-    /// 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
-    /// `1.0` under Smart and Always and `0.0` under Never, and its delay is `0.0` at every style —
-    /// so for the yaw channel the composition is the identity and the table below is the answer.
+    /// The `cameraSmooth<Style><State>{Delay,Factor}` row (family A, `[0xbe0e70]`) at its
+    /// defaults; factor 0 cancels. Family B, `cameraSmoothViewData<Style>Yaw{Delay,Factor}`, is
+    /// delay 0 and factor 1 (0 under Never), the identity on yaw.
     fn row(self, state: FollowState) -> (f32, f32) {
         match self {
-            // Every row is 0/0 — and family B's Never Yaw factor is 0.0 as well, twice over.
+            // Every row is 0/0, and family B's Never factor is 0 as well.
             Self::Never => (0.0, 0.0),
             Self::Smart => match state {
-                // The two states that make Smart *smart*: nothing returns while you stand or stop.
+                // Nothing returns while standing or stopping.
                 FollowState::Idle | FollowState::Stop => (0.0, 0.0),
-                // Driven from outside (a taxi, a spline, a fear): a lazy return — 0.4 s of delay
-                // and factor 10, which is 18 °/s of average rate before the 2 s cap bites.
+                // Driven from outside (a taxi, a spline, a fear): 18°/s on average, 2 s at most.
                 FollowState::Track | FollowState::Fear => (0.4, 10.0),
                 FollowState::Move | FollowState::Strafe | FollowState::Turn => (0.0, 1.0),
             },
-            // Always is factor 1.0 in every state, Idle and Stop included.
             Self::Always => (0.0, 1.0),
         }
     }
 }
 
-/// 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`.
+/// The seven arming states of 1.12's auto-return classifier (`0x510960`), highest priority first,
+/// read off the camera's input command word, not the character's velocity.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum FollowState {
-    /// Driven by something that is not us and is not a spline — the reference's external-control
-    /// flag `[cam+0x90] & 0x1000`.
+    /// External control that is not a spline: the reference's `[cam+0x90] & 0x1000`.
     Fear,
     Turn,
     Strafe,
     Move,
-    /// Externally-driven movement (taxi / server spline) — `[cam+0x90] & 0x100`.
+    /// Externally driven movement (a taxi, a server spline): `[cam+0x90] & 0x100`.
     Track,
-    /// This edge released a movement input (the reference's `stopping` argument). Carries the same
-    /// `(0, 0)` / `(0, 1)` rows as [`FollowState::Idle`] at every shipped style, so the two are
-    /// currently indistinguishable in behaviour — kept apart because the *matrix* keeps them apart.
+    /// This edge released a movement input (the reference's `stopping` argument). Its rows equal
+    /// `Idle`'s at every style; the reference's matrix keeps the two apart.
     Stop,
     Idle,
 }
 
-/// 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.
+/// The camera's input command word, 1.12's `[InputControl+0x4]` bit for bit. PitchUp and
+/// PitchDown are not built, so their bits are never set.
 pub(super) mod follow_cmd {
-    /// `TurnOrAction` — right mouse / mouselook.
+    /// `TurnOrAction`: right mouse, mouselook.
     pub(in crate::player) const RIGHT_MOUSE: u32 = 0x1;
-    /// `CameraOrSelectOrMove` — left mouse.
+    /// `CameraOrSelectOrMove`: left mouse.
     pub(in crate::player) const LEFT_MOUSE: u32 = 0x2;
     pub(in crate::player) const FORWARD: u32 = 0x10;
     pub(in crate::player) const BACKWARD: u32 = 0x20;
@@ -453,30 +298,26 @@ pub(super) mod follow_cmd {
     pub(in crate::player) const TURN_LEFT: u32 = 0x100;
     pub(in crate::player) const TURN_RIGHT: u32 = 0x200;
     pub(in crate::player) const AUTORUN: u32 = 0x1000;
-    /// The union of bits 20/21/23, which the reference folds into the camera's `Track` flag —
-    /// externally-driven movement.
+    /// The union of bits 20, 21 and 23, which the reference folds into the camera's `Track` flag.
     pub(in crate::player) const TRACK: u32 = 0x100000;
-    /// External control (the reference's own `[cam+0x90] & 0x1000`, not an InputControl bit —
-    /// carried here so one word carries every edge the arming function reacts to).
+    /// External control, the reference's `[cam+0x90] & 0x1000`: not an InputControl bit, carried
+    /// so one word holds every edge that arms.
     pub(in crate::player) const FEAR: u32 = 0x2000_0000;
 
-    /// The bits `Move` reads: forward, backward, autorun.
     pub(in crate::player) const MOVE_BITS: u32 = FORWARD | BACKWARD | AUTORUN;
     pub(in crate::player) const STRAFE_BITS: u32 = STRAFE_LEFT | STRAFE_RIGHT;
     pub(in crate::player) const TURN_BITS: u32 = TURN_LEFT | TURN_RIGHT;
 }
 
-/// The knobs behind the auto-follow (decision 1502) — the style, the style the *externally-driven*
-/// states use instead, and the rate. All three are 1.12 CVars with the reference's own defaults.
+/// The auto-follow's knobs: three 1.12 CVars at the reference's defaults.
 #[derive(Resource, Clone, Copy, PartialEq, Debug)]
 pub(crate) struct FollowConfig {
     /// `cameraSmoothStyle`.
     pub(crate) style: FollowStyle,
-    /// `cameraSmoothTrackingStyle` — the selector the reference swaps in when the state mask so
-    /// much as *contains* `Track` or `Fear` (`0x510a51 test bl,0x44`, before the priority scan),
-    /// indexing the very same matrices. Registrar default `"1"` = Smart, like its sibling.
+    /// `cameraSmoothTrackingStyle`: the style the reference uses whenever the mask contains `Track`
+    /// or `Fear`, even when another state wins (`0x510a51 test bl,0x44`); default Smart.
     pub(crate) tracking_style: FollowStyle,
-    /// `cameraYawSmoothSpeed`, °/s — see [`FOLLOW_SPEED_DEFAULT`].
+    /// `cameraYawSmoothSpeed`, °/s.
     pub(crate) yaw_speed: f32,
 }
 
@@ -490,20 +331,17 @@ impl Default for FollowConfig {
     }
 }
 
-/// What [`seat_camera`] needs to run the auto-follow this frame: the knobs, where "behind" is, and
-/// the input word whose *edges* arm a return. Bundled because they are one question, and
-/// `seat_camera` is already at its argument ceiling.
+/// What [`seat_camera`] needs for the auto-follow: the knobs, the facing, and the input word.
 pub(super) struct FollowInput {
     pub(super) cfg: FollowConfig,
-    /// The character's own facing (same yaw convention as [`FlyCam::yaw`] — a right-drag couples
-    /// the two directly), so the camera's *offset* is `cam.yaw − face_yaw`.
+    /// The character's facing ([`FlyCam::yaw`]'s convention); the offset is `cam.yaw − face_yaw`.
     pub(super) face_yaw: f32,
     /// This frame's [`follow_cmd`] word.
     pub(super) command: u32,
 }
 
 impl FollowInput {
-    /// The winning state — the reference's descending priority scan, highest bit first.
+    /// The winning state: the reference's priority scan, highest first.
     fn state(&self, stopping: bool) -> FollowState {
         let mf = self.command;
         let held = |bits: u32| mf & bits != 0;
@@ -528,8 +366,7 @@ impl FollowInput {
         }
     }
 
-    /// Which style picks the row: the *tracking* style whenever the mask so much as contains
-    /// `Track` or `Fear`, even when a higher-priority state supplies the row.
+    /// The tracking style whenever the word holds `Track` or `Fear`, even if another state wins.
     fn style(&self) -> FollowStyle {
         if self.command & (follow_cmd::TRACK | follow_cmd::FEAR) != 0 {
             self.cfg.tracking_style
@@ -539,29 +376,25 @@ impl FollowInput {
     }
 }
 
-/// The armed yaw transition — the reference's descriptor `[+0x208 startMs, +0x20c dur,
-/// +0x210 target, +0x214 start]`, in seconds and in *offset* space.
+/// The armed yaw transition: the reference's descriptor `[+0x208 startMs, +0x20c dur,
+/// +0x210 target, +0x214 start]`, in seconds and offset space.
 #[derive(Clone, Copy, Debug)]
 struct FollowArm {
     /// The offset the transition started from, radians (camera yaw minus character facing).
     from: f32,
-    /// Where it is going. `0.0` — directly behind — at the shipped defaults, because
-    /// `cameraYawSmoothMin`/`Max` are both `0.0` and the reference *substitutes* the crossed bound
-    /// for the saved view yaw whenever the live offset is outside the band.
+    /// The target offset: 0, directly behind, at the defaults, since `cameraYawSmoothMin`/`Max`
+    /// are both 0 and the reference substitutes the crossed bound when the offset is outside them.
     to: f32,
     /// Seconds the move takes, already clamped to `[FOLLOW_TIME_MIN, FOLLOW_TIME_MAX]`.
     dur: f32,
     /// Seconds of dead time before it starts (`Track`/`Fear` under Smart: 0.4).
     delay: f32,
-    /// Seconds since it was armed.
     elapsed: f32,
-    /// What it was armed with — the reference's re-arm memo (`[+0x218, +0x21c]`), so a repeated
-    /// edge asking for the same transition is a no-op instead of restarting the swing.
+    /// The `(delay, factor)` it was armed with, the reference's re-arm memo (`[+0x218, +0x21c]`).
     armed_with: (f32, f32),
 }
 
-/// The auto-follow's own state on the rig: the input word we last saw (edges are what arm a
-/// return) and the transition in flight, if any.
+/// The auto-follow's state: the last input word (edges arm a return) and the transition in flight.
 #[derive(Default)]
 pub(super) struct FollowRig {
     last_command: Option<u32>,
@@ -569,13 +402,9 @@ 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 (`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.
+    /// Run the auto-follow for a frame; returns the camera yaw it wants, if any. As in the
+    /// reference (`0x510960`, `0x50f160`), a return is armed on an input edge from a snapshot and
+    /// then plays out unattended, not a per-frame chase: holding W changes nothing.
     fn advance(
         &mut self,
         input: &FollowInput,
@@ -586,21 +415,15 @@ impl FollowRig {
         let word = input.command;
         let previous = self.last_command.replace(word);
         // A held drag owns the camera: the yaw channel is frozen (`0x50f623`), arming is gated
-        // (`0x510850`'s `!([cam+0x90] & 1)`), and **entering** mouse-look cancels whatever was in
-        // flight outright (`0x50fe30` zeroes the descriptors). So the return does not resume when
-        // the button comes up — it begins at the next input edge after the release, which is
-        // usually the release itself (the mouse bits are part of the word).
+        // (`0x510850`, `!([cam+0x90] & 1)`), and entering mouse-look cancels the transition in
+        // flight (`0x50fe30`), so a return starts at the next edge, usually the release itself.
         if look_held {
             self.arm = None;
             return None;
         }
-        // The EDGE: any movement/camera binding changing state re-evaluates the transition. The
-        // reference re-evaluates on the binding call itself, not on a change of the classified
-        // state, which is why releasing the drag while standing still is an Idle *arming* under
-        // Always and an Idle *cancel* under Smart.
+        // Any change of the word re-evaluates, as the reference does on every binding call.
         if let Some(p) = previous.filter(|p| *p != word) {
-            // `stopping` — the reference's second argument, set by the Stop half of a movement
-            // binding. Our equivalent is the edge itself: a movement bit went away.
+            // `stopping`, the reference's second argument: a movement bit went away.
             let stopping = (p & !word)
                 & (follow_cmd::MOVE_BITS | follow_cmd::STRAFE_BITS | follow_cmd::TURN_BITS)
                 != 0;
@@ -618,41 +441,34 @@ impl FollowRig {
             self.arm = None;
             to
         } else {
-            // The reference's kernel `0x5b7bb0` — a **cosine** smoothstep, eased at both ends:
-            // `a + (b − a)·(1 − cos(πs))/2`.
+            // The reference's cosine smoothstep (`0x5b7bb0`): `a + (b − a)·(1 − cos(πs))/2`.
             let e = (1.0 - (std::f32::consts::PI * s).cos()) * 0.5;
             arm.from + (arm.to - arm.from) * e
         };
         Some(wrap_pi(input.face_yaw + offset))
     }
 
-    /// What the transition is doing, for `WOW_CAM_DUMP` — `None` when nothing is armed, else
-    /// `(elapsed, delay, duration)` in seconds. The auto-follow is the one camera behaviour with
-    /// no headless retest (nothing synthesizes a mouse drag), so the trace line is how a run says
-    /// what it armed and when.
+    /// `(elapsed, delay, duration)` of the armed transition in seconds, for `WOW_CAM_DUMP`.
     fn probe(&self) -> Option<(f32, f32, f32)> {
         self.arm.map(|a| (a.elapsed, a.delay, a.dur))
     }
 
-    /// The arming half (`0x510960` → `0x512c70`): pick the row, then either cancel outright or
-    /// snapshot a transition to the target offset.
+    /// The arming half (`0x510960` → `0x512c70`): pick the row, then cancel or snapshot a return.
     fn arm(&mut self, input: &FollowInput, cam_yaw: f32, stopping: bool) {
         let (delay, factor) = input.style().row(input.state(stopping));
         if factor == 0.0 {
-            // Cancel: the target becomes the live yaw and the channel disarms — the camera simply
-            // keeps the offset it has. This is Smart standing still, and it is all of Never.
+            // Factor 0 cancels, keeping the offset (Smart standing still, and all of Never).
             self.arm = None;
             return;
         }
-        // The target: directly behind, at the shipped defaults (see [`FollowArm::to`]).
+        // Directly behind, at the defaults ([`FollowArm::to`]).
         let to = 0.0;
         let from = wrap_pi(cam_yaw - input.face_yaw);
         let gap = (to - from).abs();
         if gap < FOLLOW_EPS {
-            return; // already there — the reference returns without arming
+            return; // already there: the reference does not arm
         }
-        // The re-arm memo: an edge asking for the transition already in flight is a no-op, so a
-        // second keypress mid-swing does not restart it from the current angle.
+        // The re-arm memo: an edge asking for the transition in flight does not restart it.
         if self.arm.is_some_and(|a| {
             a.to == to
                 && (a.armed_with.0 - delay).abs() < FOLLOW_EPS
@@ -673,57 +489,24 @@ impl FollowRig {
     }
 }
 
-/// 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.
+/// Camera pitch clamp, ±89° (`0x8089d8`/`0x8089dc`, 1.5533430576 rad, applied in `0x510120`), the
+/// same at every zoom: the reference has no separate first-person 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).
-/// Pull-*in* is instant (a wall must never sit between the camera and the character); only the
-/// push-*out* eases — the vanilla feel of the camera snapping close past an obstacle and easing back.
+/// Rate (1/s) at which the arm eases back out once clear; pulling in is instant.
 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):
-/// `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
-/// stops the camera under the ceiling — see `control`.
-///
-/// That height is one of the reference's **three** presets, rebuilt together by `0x50ca90` and
-/// chosen between per frame by `0x50f880`. benilla builds two of the three: the standing height
-/// above, and the **swim** preset `cam+0x124` — the same height less the model's
-/// [`CameraPivot::swim_drop_local`] — selected on MOVEFLAG_SWIMMING. The zoomed-in/zoomed-out pair
-/// (`cam+0x11c`/`cam+0x120`, split on `cam+0x198 < 1.8315`) is **not built**; see
-/// [`model_pivot_height`].
-///
-/// Floor (yd) on the world pivot height — VERIFIED `5/6` (`0x50ca90`'s per-preset clamp, and
-/// `0x50e570`'s corridor lower bound).
+/// Floor on the world pivot height, 5/6 yd (`0x50ca90`'s clamp, `0x50e570`'s corridor bound).
 pub(super) const CAM_PIVOT_FLOOR: f32 = 5.0 / 6.0;
-/// Ceiling (yd) on the world pivot height — VERIFIED `15.0` (`[0x8089c8]`, the upper arm of the same
-/// per-preset clamp in `0x50ca90`). A giant's scale cannot walk the framing pivot off into the sky.
+/// Ceiling on the world framing-pivot height, 15 yd (`[0x8089c8]`, the same clamp in `0x50ca90`).
 pub(super) const CAM_PIVOT_CEIL: f32 = 15.0;
-/// Pivot height used before the avatar model has attached (so `CameraPivot` isn't on the entity yet):
-/// a human's ~neck height, so the first frames of third-person don't ride high. Replaced by the exact
-/// model-derived value the moment the body attaches — as a **snap**, not a glide ([`PivotGlide`]).
+/// Head height before a model has attached: about a human's neck height.
 pub(super) const CAM_PIVOT_FALLBACK: f32 = 1.8;
 
-/// One modeled unit's world framing-pivot height: its model-local [`CameraPivot`] × the given scale,
-/// clamped to `[CAM_PIVOT_FLOOR, CAM_PIVOT_CEIL]` — the reference's per-preset clamp in `0x50ca90`.
-///
-/// **`swimming` selects the preset, per frame, the way `0x50f880` does**
-/// (`0x50f89e test [[unit+0x118]+0x40],0x200000` — MOVEFLAG_SWIMMING on the *camera target's*
-/// CMovement word): set, and the pivot drops by the model's own
-/// [`benilla_formats::M2Bounds::swim_pivot_drop`] before the clamp, which is the reference's
-/// `cam+0x124` preset. Clear, and it stays the standing height. The drop is a *model* constant
-/// (`StandSeq.max.z − SwimSeq.max.z`, `0x50ccf6`), so a body that authors no Swim sequence carries
-/// `0.0` and the two presets are the same number — correct for anything that cannot swim.
-///
-/// **What is deliberately not here:** the reference keeps a *third* preset. `0x50f880`'s non-swim
-/// leg picks `cam+0x11c` (zoomed-in) or `cam+0x120` (zoomed-out) on `cam+0x198 < 1.8315`
-/// (`[0x8089b0]`), and benilla builds neither — one standing height serves both zoom regimes. On a
-/// scale-1 human the reference computes those two presets *equal* (both 1.9002692), so nothing yet
-/// says what authors them apart; naming it beats stubbing a threshold we cannot justify (1203).
+/// A modeled unit's world framing-pivot height: [`CameraPivot`] × `scale`, clamped to
+/// `[CAM_PIVOT_FLOOR, CAM_PIVOT_CEIL]` (`0x50ca90`). `swimming` picks the preset per frame as
+/// `0x50f880` does (MOVEFLAG_SWIMMING, `0x50f89e`): the swim drop gives the reference's
+/// `cam+0x124`. Its third preset is not built: `cam+0x11c`/`cam+0x120`, split on
+/// `cam+0x198 < 1.8315` (`[0x8089b0]`), are both 1.9002692 on a scale-1 human, and what sets them
+/// apart is untraced.
 pub(super) fn model_pivot_height(pivot: &CameraPivot, scale: f32, swimming: bool) -> f32 {
     let local = if swimming {
         pivot.height_local - pivot.swim_drop_local
@@ -733,79 +516,40 @@ pub(super) fn model_pivot_height(pivot: &CameraPivot, scale: f32, swimming: bool
     (local * scale).clamp(CAM_PIVOT_FLOOR, CAM_PIVOT_CEIL)
 }
 
-/// 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, `0x457890`).
-///
-/// **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
-/// [`crate::net::NetEntity::scale`] and the pivot moves in **one** step per model event, which
-/// [`PivotGlide`] then walks; multiplying by the eased scale instead would stack a second, slower
-/// ease on top of the first and is what made a shapeshift snap *and* drift. The audio listener still
-/// passes the rendered scale — it tracks the drawn body, and nothing verified says otherwise.
-///
-/// **Always the standing preset.** Its two consumers are a *head*, not the camera's framing pivot:
-/// the 3D-audio listener sits at our own head, and the far-sight subject is a unit whose movement
-/// flags we do not carry. The swim preset is the framing pivot's alone — [`model_pivot_height`]
-/// with `swimming` — and the driven body's own target goes through
-/// [`super::body_pose::pivot_target`], not here.
+/// World head height above a unit's feet: the standing preset, or [`CAM_PIVOT_FALLBACK`] with no
+/// model. For the 3D-audio listener (`SoundListenerAtCharacter=1`, `0x457890`) and a far-sight
+/// subject, whose movement flags we do not carry. A camera pivot passes the raw
+/// `OBJECT_FIELD_SCALE_X`, as the reference reads it (`0x469f10`), not the 2 s-eased render scale
+/// only a selection ring uses (`0x4833d3`); the listener passes the rendered scale.
 pub(crate) fn head_height(pivot: Option<&CameraPivot>, scale: f32) -> f32 {
     pivot.map_or(CAM_PIVOT_FALLBACK, |p| model_pivot_height(p, scale, false))
 }
 
-/// `cameraHeightSmoothSpeed` (yd/s) — the pivot channel's rate, VERIFIED registrar default `"1.2"`.
-/// The duration of a move is `|Δh| / this` (`0x51276c`/`0x512777`), so it is an *average* rate: the
-/// cosine profile peaks at `π/2 ×` it in the middle and is zero at both ends. There is no duration
-/// clamp on this channel (unlike the yaw channel's `[0.1 s, 2.0 s]`).
+/// `cameraHeightSmoothSpeed`, default 1.2 yd/s: a move lasts `|Δh| / this`
+/// (`0x51276c`/`0x512777`), an average rate, with no duration clamp.
 const CAM_PIVOT_SMOOTH_SPEED: f32 = 1.2;
-/// **The camera's pivot-height channel** — the height the framing pivot actually rides, chasing
-/// 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 — 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
-/// simply *is* `cam+0xfc` — rising or falling.
-///
-/// Two structural facts, both load-bearing:
-/// - **The first arm of a camera's life snaps** (`0x5127d4`; the latch bit `0x80` is never cleared —
-///   image-wide census). So logging in establishes the height instantly, and everything after it
-///   glides. Nothing else re-snaps: a target-GUID change, a mount, a morph, `SetView` — all glide.
-/// - **A model that has not resolved yet holds the channel**, it does not re-aim it (the reference
-///   skips the whole camera update while the preset is stale, `0x50e907`). Ours is the `None` target:
-///   during the frames a swapped-in model is loading, the pivot stays where it is and one glide runs
-///   when the new height lands.
+/// The framing pivot's height channel, a [`SmoothChannel`]: the reference's live `cam+0xfc`
+/// chasing `cam+0x1c8`, armed by `0x5126b0` → `0x512790`, stepped in `0x50f160`
+/// (`[0x50f36a, 0x50f417)`). It glides both ways: `max(target, live)` (`0x50e5a9`) only seeds the
+/// collision corridor, and the far chain clamps back to the live value (`0x50e767`). Only the
+/// first arm snaps (`0x5127d4`), and an unresolved model holds it (`0x50e907` skips the update).
 #[derive(Default)]
 pub(super) struct PivotGlide {
-    /// The channel itself — **linear**, not angular: its live value is yards, so the armer's `2π`
-    /// rewrap must not run on it.
+    /// Linear, not angular: the live value is yards, so the armer's `2π` rewrap must not run on it.
     channel: SmoothChannel,
-    /// Has the channel ever been armed? The reference's latch bit `0x80` — false only until the
-    /// first model-derived height arrives, which is therefore a snap.
+    /// The reference's latch bit `0x80`, never cleared: false until the first height, which snaps.
     seeded: bool,
 }
 
 impl PivotGlide {
-    /// Arm the channel with this frame's model-derived target (`None` while the subject has no
-    /// model — hold), step whatever is in flight, and return the height to frame at.
-    ///
-    /// Called every frame, which is the reference's own cadence (`0x50f880` from the driver tail
-    /// `0x50f011`): the armer's own two epsilon refusals turn a steady target into a no-op, so
-    /// "arm per frame" and "arm on change" are the same thing except at the instant the target
-    /// actually moves.
+    /// Arm with this frame's target (`None` holds), step, and return the height. Called every
+    /// frame, as `0x50f880` is from the driver tail `0x50f011`; the armer's epsilon makes a steady
+    /// target a no-op.
     pub(super) fn advance(&mut self, target: Option<f32>, dt: f32) -> f32 {
         if let Some(target) = target {
             if self.seeded {
                 self.channel.arm(&Arm::at(target, CAM_PIVOT_SMOOTH_SPEED));
             } else {
-                // The latch: the first height a camera ever sees is established, not travelled to.
                 self.seeded = true;
                 self.channel.snap(target);
             }
@@ -813,85 +557,53 @@ impl PivotGlide {
         self.channel.advance(dt)
     }
 
-    /// What the channel is doing, for `WOW_CAM_DUMP`: `(live, target)`. A pivot question is a
-    /// *timing* question — "does it snap?" is answered by these two columns on a trace, never by
-    /// watching a capture (method: timing is measured, never eyeballed).
+    /// `(live, target)`, for `WOW_CAM_DUMP`.
     pub(super) fn probe(&self) -> (f32, f32) {
         self.channel.probe()
     }
 }
 
-/// Which mouse button is driving mouse-look, if any — the two vanilla look modes. While looking, the
-/// OS cursor is hidden + locked in place (relative motion drives the camera); `cursor_stash` is the
-/// position it's restored to on release so it reappears exactly where the user pressed. `pub(crate)`
-/// so the [`crate::cursor`] subsystem can hide the cursor while looking (`is_looking`).
+/// The camera rig's state: the zoom, the collided arm, the mouse-look session and the pose
+/// channels. `pub(crate)` so [`crate::cursor`] can hide the cursor while looking.
 #[derive(Resource, Default)]
 pub(crate) struct CameraControl {
-    /// Current third-person orbit distance (yards) — eased toward `target_distance` each frame so the
-    /// wheel zoom glides instead of snapping (like the real client).
+    /// Third-person orbit distance (yd), gliding toward `target_distance`.
     pub(super) distance: f32,
-    /// Where the wheel set the orbit distance; `distance` chases this.
     pub(super) target_distance: f32,
-    /// Effective length of the camera arm (from the head pivot out to the camera) after world
-    /// collision. Pulled in instantly when geometry intrudes (so a wall never sits between the camera
-    /// and the character), eased back out when it clears. Kept separate from the zoom `distance` so the
-    /// player's chosen zoom is preserved while obstructed and restored once the view is open again.
+    /// The arm's length from the head after world collision: pulled in instantly, eased back out,
+    /// and kept apart from `distance` so the chosen zoom survives an obstruction.
     pub(super) collision_distance: f32,
-    /// The button currently held for look, or `None`.
     pub(super) look: Option<LookButton>,
-    /// **Is the player in mouse-look right now?** — the reference's `[cam+0x90] & 1`, set at
-    /// `0x50fe41` and cleared at `0x50fddd`, identified at the bytes by the two mode strings
-    /// `"Camera FREELOOK"` / `"Camera NORMAL"`. Written by [`run_look_session`] and read the same
-    /// frame by [`seat_on_subject`], which is `cameraTerrainTilt`'s hand-off edge.
+    /// Mouse-look is on: the reference's `[cam+0x90] & 1` (set `0x50fe41`, cleared `0x50fddd`).
+    /// Written by [`run_look_session`], read the same frame for `cameraTerrainTilt`'s hand-off.
     pub(super) freelook: bool,
-    /// **Which mouse buttons the world owns** this frame ([`WorldMouse`]) — the player side's one
-    /// answer to "did the UI eat that press?", written by [`latch_world_mouse`] before anything
-    /// reads a button. The look session, the camera's input command word and the both-button run
-    /// all read it instead of `ButtonInput`.
+    /// The mouse buttons the world owns this frame, latched by [`latch_world_mouse`].
     pub(super) world_mouse: WorldMouse,
     /// Logical cursor position captured when look began, to restore on release.
     pub(super) cursor_stash: Option<Vec2>,
-    /// The self-avatar's render alpha for this frame, from the camera-to-pivot distance
-    /// ([`benilla_world::model_fade::self_model_fade_alpha`]): `1.0` third-person (opaque), ramping to `0.0` as
-    /// the camera zooms into the head (first-person). `control` computes it (it owns the pivot + camera
-    /// pose); [`apply_self_model_fade`] applies it to the body parts. Starts opaque.
+    /// The self-avatar's alpha from the camera-to-pivot distance, 1 in third person to 0 in first
+    /// (`self_model_fade_alpha`); applied by [`apply_self_model_fade`].
     pub(super) self_fade_alpha: f32,
-    /// The auto-follow's own state (decision 1502): the input word we last saw, and the armed
-    /// return in flight. It lives on the rig rather than beside the knob because it is *pose*, not
-    /// setting — a transition survives the frame, not the session.
+    /// The auto-follow's state; on the rig because it is pose, not setting.
     pub(super) follow: FollowRig,
-    /// The framing pivot's height channel — smoothed, not taken raw ([`PivotGlide`]). On the rig
-    /// for the same reason `follow` is, and for one more: it belongs to the **camera**, not to the
-    /// body, which is why it glides *through* a change of subject (a shapeshift, a far-sight
-    /// switch) instead of being reset by one.
+    /// The framing pivot's height channel ([`PivotGlide`]), on the camera rather than the body so
+    /// it glides through a change of subject (a shapeshift, a far-sight switch).
     pub(super) pivot: PivotGlide,
-    /// `cameraPivot`'s pitch-bias channel ([`SmartPivot`], decision 2149) — pose, like the two
-    /// above it.
+    /// `cameraPivot`'s pitch-bias channel ([`SmartPivot`]).
     pub(super) smart_pivot: SmartPivot,
-    /// `cameraTerrainTilt`'s ground-pitch channel and its 100 ms probe throttle ([`TerrainTilt`],
-    /// decision 2149).
+    /// `cameraTerrainTilt`'s ground-pitch channel and its 100 ms probe throttle ([`TerrainTilt`]).
     pub(super) terrain_tilt: TerrainTilt,
-    /// `cameraBobbing`'s session latch and eye offset ([`HeadBob`], decision 2149).
+    /// `cameraBobbing`'s session latch and eye offset ([`HeadBob`]).
     pub(super) head_bob: HeadBob,
-    /// **Did the collision sweep actually clip the camera on the frame just seated?** The
-    /// reference's `[cam+0x90] & 0x30000`, which nothing but the solver `0x50e570` writes and the
-    /// driver ORs in per frame — and which [`SmartPivot`]'s gate reads as its sixth conjunct, so
-    /// that an unobstructed camera never pivots. Written by [`seat_camera`]; read a frame later by
-    /// [`run_look_session`], exactly as the reference's input handler reads the flags the last
-    /// driver pass left (`0x50fee0`'s sole caller `0x514446` precedes the mover lookup).
+    /// The sweep clipped the camera on the frame just seated: the reference's
+    /// `[cam+0x90] & 0x30000`, written only by the solver `0x50e570`, [`SmartPivot`]'s sixth
+    /// conjunct; the look session reads it a frame later, as `0x50fee0` (from `0x514446`) does.
     pub(super) clipped: bool,
 }
 
 impl CameraControl {
-    /// Park the orbit distance at `d` — **both** the live value and the wheel target.
-    ///
-    /// Both, or the wheel glide eases `distance` back toward the old target every frame and a
-    /// parked shot drifts through the whole zoom while the burst is running.
-    ///
-    /// The scripted camera park (`capture::probe_cam`, decision 0653) is the only caller. It gets a
-    /// named method rather than `pub(crate)` fields because an instrument reaching into gameplay is
-    /// the allowed direction but not a licence to open gameplay's internals to the whole crate
-    /// (decision 1174) — this is the entire surface the probe needs.
+    /// Park the orbit distance at `d`, both the live value and the wheel target, or the glide
+    /// drifts back; for the scripted camera park (`capture::probe_cam`).
     pub(crate) fn park_distance(&mut self, d: f32) {
         self.distance = d;
         self.target_distance = d;
@@ -902,16 +614,14 @@ impl CameraControl {
         self.look.is_some()
     }
 
-    /// 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]`).
+    /// The self-avatar's render alpha this frame. The blob shadow multiplies it in, as the
+    /// reference's shadow diffuse rides the body's model fade slot (`[model+0x180]`).
     pub(crate) fn self_fade(&self) -> f32 {
         self.self_fade_alpha
     }
 }
 
-/// The active mouse-look mode. `Right` turns the character (movement follows the camera heading);
-/// `Left` orbits the camera around a stationary character (vanilla left-drag look).
+/// The mouse-look mode: `Right` turns the character with the camera, `Left` orbits around it.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub(super) enum LookButton {
     Right,
@@ -927,53 +637,34 @@ impl LookButton {
     }
 }
 
-/// **The mouse buttons the world owns**, latched at the press — where the player side asks
-/// about a primary *press*, instead of `ButtonInput<MouseButton>` (ledger B364). The raw buttons
-/// stay readable for the hold and release of a gesture already claimed, which is
-/// [`run_look_session`]'s business and no one else's.
-///
-/// 1.12 never reads the mouse for any of this. It reads two *bindings* — `TurnOrAction` (right)
-/// and `CameraOrSelectOrMove` (left) — and a press a UI frame captured never dispatches them: it
-/// sets neither of `[InputControl+0x4]`'s mouse bits, engages no look session, and classifies as
-/// no [`FollowState`]. That is the observable rule, and it is why a right-click in a bag has never
-/// turned anyone. Only the look session applied it here; the command word and the both-button run
-/// read the raw buttons, so a right-click on a Who-list row was a `Turn`, whose Smart row is
-/// `(0.0, 1.0)` — an immediate return that ran to completion and swung the camera round to behind
-/// the character (B364). The same raw read had both primaries over a bag running the avatar
-/// forward, through [`super::state::forward_axis`]'s both-button term.
-///
-/// **Latched, not re-tested each frame**, because the reference latches: the down that reached the
-/// world sets the bit, and that button's *up* clears it. A level test would hand the button back
-/// to the UI mid-gesture the moment a frame appeared under the (stationary, locked) cursor — an
-/// edge on the command word from nothing the player did.
+/// The mouse buttons the world owns, latched at the press. 1.12 reads the `TurnOrAction` and
+/// `CameraOrSelectOrMove` bindings, which a press a UI frame captured never dispatches: no mouse
+/// bit in `[InputControl+0x4]`, no look session, no [`FollowState`]. The world's down sets the bit
+/// and that button's up clears it, so a frame appearing under the locked cursor cannot steal it.
 #[derive(Default)]
 pub(super) struct WorldMouse {
     /// Held by the world right now, indexed by [`LookButton`].
     held: [bool; 2],
-    /// Took its DOWN edge from the world this frame, same index.
+    /// Took its down edge from the world this frame, same index.
     down: [bool; 2],
 }
 
 impl WorldMouse {
-    /// Is the world holding this button?
     pub(super) fn held(&self, b: LookButton) -> bool {
         self.held[b as usize]
     }
 
-    /// Did the world take this button's DOWN edge this frame?
     pub(super) fn down(&self, b: LookButton) -> bool {
         self.down[b as usize]
     }
 
-    /// Both primaries in the world's hand — vanilla's both-button run, minus the presses the UI ate.
+    /// Both primaries in the world's hand: the both-button run.
     pub(super) fn both(&self) -> bool {
         self.held(LookButton::Right) && self.held(LookButton::Left)
     }
 
-    /// Latch this frame. `world_press` says whether a DOWN edge *now* belongs to the world; the
-    /// held bits then ride to their own release, whatever the cursor is over by then — including
-    /// the release a cover synthesises by emptying the button planes, which is what keeps a
-    /// loading screen from stranding a latched bit.
+    /// Latch this frame; `world_press` says whether a down edge belongs to the world. A held bit
+    /// rides to its release, including a cover's emptying of the button planes.
     fn update(&mut self, buttons: &ButtonInput<MouseButton>, world_press: bool) {
         for b in [LookButton::Right, LookButton::Left] {
             let i = b as usize;
@@ -983,45 +674,19 @@ impl WorldMouse {
     }
 }
 
-/// Decide, once per frame, which mouse buttons the world owns — [`CameraControl::world_mouse`].
-///
-/// **Its own system**, ahead of every reader, rather than a call inside [`super::control`]: the
-/// readers are not all in the controller. The look session and the camera's command word are, but
-/// `/follow`'s both-button cancel ([`super::follow::steer_follow`]) is a system that runs *before*
-/// it — reading a latch the controller wrote would put that cancel a frame behind, and a frame
-/// late on an edge-driven cancel is the wrong frame entirely.
-///
-/// A press belongs to the world when it lands in the viewport off the UI — or whenever a look
-/// session already owns the (hidden, locked) cursor, because the second button of a chord joins a
-/// gesture the world already has.
+/// Decide once per frame which mouse buttons the world owns: a press in the viewport off the UI,
+/// or any press while a look session owns the cursor (a chord's second button). Its own system,
+/// ahead of `/follow`'s both-button cancel ([`super::follow::steer_follow`]), which runs before
+/// the controller and would otherwise read it a frame late.
 pub(super) fn latch_world_mouse(
     buttons: Res<ButtonInput<MouseButton>>,
-    // **The raw flag — a press that lands on a V-plate is the PLATE's, not the camera's** (decision
-    // 2233, reversing 2159's exception).
-    //
-    // 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 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
-    // the bus walk; and `CBindings::ExecuteBinding 0x4b7990` has exactly six call sites image-wide,
-    // every one inside a `CGWorldFrame` vtable handler. So with a plate under the cursor the
-    // binding that would start mouselook is never reached, and the release goes to the plate's own
-    // click slot (`0x7792d0` → `0x7cb910` → `0x4949f0`, mask 1 select / mask 4 interact — the same
-    // two terminals the world right-click's object leg reaches).
-    //
-    // What it costs is real and is the reference's own cost: **you cannot swing the camera by
-    // dragging off a nameplate.** Plates are small dead patches for turning, exactly as in 1.12.
-    // The one exception is the plate's own `+0x3c` veto (`0x7cba30`) — while a ground-targeted
-    // spell is armed the plates refuse the hit test, the WorldFrame wins the press, and the gesture
-    // *does* enter mouselook. That is built where it belongs, in the hit test itself
-    // ([`benilla_ui::script::UiScript::set_nameplate_hit_test_veto`]), so it arrives here for free
-    // as `PointerOverUi` simply being false over a vetoing plate.
-    //
-    // `PointerOverUiPanel` keeps its other reader — the wheel still zooms with the cursor on a
-    // plate, which is a different law (the wheel walks PAST a frame that merely takes the mouse).
+    // The raw flag: a press on a nameplate is the plate's, so dragging from a plate never turns the
+    // camera, as in 1.12. `0x7662c0` hands a mouse-down to one frame (capture at `0x7663e9`), and
+    // `CBindings::ExecuteBinding` (`0x4b7990`) runs only from `CGWorldFrame` handlers; the release
+    // goes to the plate's click slot (`0x7792d0` → `0x7cb910` → `0x4949f0`). Entering freelook
+    // disables plate input (`0x60f830`, from `0x483e80`) for a world drag across one. A plate's
+    // ground-targeting veto (`+0x3c`, `0x7cba30`) arrives through `PointerOverUi`
+    // (`UiScript::set_nameplate_hit_test_veto`). The wheel still zooms over a plate.
     pointer_over_ui: Res<crate::ui_script::PointerOverUi>,
     mut rig: ResMut<CameraControl>,
     cameras: Query<&Camera, With<FlyCam>>,
@@ -1036,8 +701,7 @@ pub(super) fn latch_world_mouse(
 }
 
 #[derive(Component)]
-// `pub(crate)` on the TYPE only — the scripted camera park has to name it in a query. Its fields
-// stay `pub(super)`; [`FlyCam::park`] is the whole surface an instrument gets (decision 1174).
+// `pub(crate)` for the scripted camera park's query; `FlyCam::park` is its one lever.
 pub(crate) struct FlyCam {
     pub(super) yaw: f32,
     pub(super) pitch: f32,
@@ -1045,44 +709,30 @@ pub(crate) struct FlyCam {
 }
 
 impl FlyCam {
-    /// Point the rig at an absolute world yaw/pitch — the scripted camera park's one lever
-    /// (`capture::probe_cam`, decision 0653). From here on this is the identical path a mouse-drag
-    /// takes.
+    /// Point the rig at an absolute world yaw and pitch, for `capture::probe_cam`.
     pub(crate) fn park(&mut self, yaw: f32, pitch: f32) {
         self.yaw = yaw;
         self.pitch = pitch;
     }
 }
 
-/// 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`). 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).
+/// A model's framing-pivot height in model-local yards before scale, the reference's camera-target
+/// height (`0x50cbc0`): `attach17.z + 0.0972` from M2 attachment 17 where the model has one, else
+/// `0.9 ×` the vertex box's Z extent; `0.0` for a display with no bounds. Stamped on every modeled
+/// unit at attach; [`model_pivot_height`] makes it the world pivot.
 #[derive(Component, Clone, Copy)]
 pub(crate) struct CameraPivot {
     pub height_local: f32,
-    /// How far that height drops while this body **swims**, model-local and pre-scale
-    /// ([`benilla_formats::M2Bounds::swim_pivot_drop`] — `StandSeq.max.z − SwimSeq.max.z`,
-    /// `0x50ccf6`). The reference builds the swim framing-pivot preset `cam+0x124` by subtracting
-    /// exactly this from the standing one before the shared clamp, and `0x50f880` picks it whenever
-    /// the camera target carries MOVEFLAG_SWIMMING. `0.0` for a model with no Swim sequence (every
-    /// non-character model) and for a bounds-less display — the two presets then coincide.
+    /// How far that height drops while swimming, model-local before scale
+    /// ([`benilla_formats::M2Bounds::swim_pivot_drop`], `StandSeq.max.z − SwimSeq.max.z`,
+    /// `0x50ccf6`); `0.0` with no Swim sequence, where the two presets coincide.
     pub swim_drop_local: f32,
 }
 
-/// Mouse-look session state machine — start/stop/hand-off between the two look buttons, cursor
-/// grab/stash/restore, and the two click tests that emit [`WorldClick`]/[`WorldRightClick`]. Also
-/// applies this frame's accumulated motion as look rotation while a button is held (right-drag syncs
-/// the character facing too). Called once per frame from [`super::control`]; `both_buttons` is
-/// vanilla's both-button run (steers like a right-drag without its own click test).
-///
-/// **Orbit and select are independent** (decision 1122): every primary press engages its look
-/// session immediately and *also* arms a click test, and the release decides the click on
-/// [`PressGesture::is_click`] alone. There is no "promotion" and nothing cancels the click for
-/// having moved — the pending click used to be destroyed the moment the cursor crossed a 4 px
-/// threshold, which is why a drag could never select (ledger B226).
+/// The mouse-look session: start, stop and hand-off between the buttons, cursor grab and restore,
+/// the look rotation, and the click tests behind [`WorldClick`]/[`WorldRightClick`]. Orbit and
+/// select are independent: each primary press engages its session at once and arms a click test,
+/// and the release decides on [`PressGesture::is_click`] alone.
 pub(super) fn run_look_session(
     buttons: &ButtonInput<MouseButton>,
     mouse_motion: &AccumulatedMouseMotion,
@@ -1093,9 +743,7 @@ pub(super) fn run_look_session(
     window: &mut Window,
     cursor_opts: &mut CursorOptions,
     inspect_enabled: bool,
-    // A left press this frame the UI already consumed as a cursor-payload world drop (0216 §3) —
-    // the left click test must yield to it exactly as it yields to a UI hover, so dropping a held
-    // item never also selects.
+    // A left press the UI consumed as a cursor-payload world drop, which must not also select.
     click_consumed: bool,
     world_click: &mut MessageWriter<WorldClick>,
     world_right_click: &mut MessageWriter<WorldRightClick>,
@@ -1103,34 +751,25 @@ pub(super) fn run_look_session(
     left_click: &mut Option<PressGesture>,
     right_click: &mut Option<PressGesture>,
     look_cfg: LookConfig,
-    // The camera-option knobs + this frame's gate facts (decision 2149). `cameraPivot`'s routing
-    // lives in the look session because the reference's does: `0x50fee0` IS the mouse-motion
-    // handler, and the whole decision is "does THIS motion event go into the pitch or the bias".
+    // `cameraPivot`'s routing lives here because the reference's does: `0x50fee0`, the mouse-motion
+    // handler, sends each motion event to the pitch or the bias.
     dynamics: &DynamicsInput,
-    // Seconds on the app clock — the press predicate's two time gates are measured against it.
+    // Seconds on the app clock, for the press predicate's two time gates.
     now: f32,
 ) {
-    // The right button's DOWN edge, before any click-vs-drag classification — the reference's
-    // WorldFrame OnMouseDown fires at the press whether it becomes a click or a turn. Whether the
-    // press was the world's at all is [`latch_world_mouse`]'s single answer, shared with the
-    // camera's command word: the viewport off the UI, or a right join into a left-orbit, whose
-    // session already owns the cursor. Ground-targeting's cancel reads this edge (decision 0792).
+    // The right button's down edge, before the press is judged a click or a drag: the reference's
+    // WorldFrame OnMouseDown fires at the press either way. Ground targeting's cancel reads it.
     if rig.world_mouse.down(LookButton::Right) {
         world_right_press.write(WorldRightPress);
     }
-    // A chord — both primaries down — is a both-button run, never a select. The reference kills the
-    // pending click on the *second* press and refuses to arm a new one while another primary is held
-    // (`0x514ac1`, `0x51481a`), so neither release of a chord can dispatch. Cancel both tests.
-    // The world's pair, not the device's: what those two sites test is the *binding* state, so a
-    // primary a UI frame is holding has never been half of a chord (ledger B364).
+    // A chord is a both-button run, never a select: the reference kills the pending click and arms
+    // none while another primary's binding is held (`0x514ac1`, `0x51481a`).
     if rig.world_mouse.both() {
         *left_click = None;
         *right_click = None;
     }
-    // Both tests just ride their session, accumulating the camera rotation the press has asked for;
-    // the release decides. The travel is charged from the *input* delta, before the pitch clamp —
-    // the reference accumulates raw device motion, so a drag pinned at the pitch limit still spends
-    // its budget.
+    // Both tests accumulate the rotation the press asked for, charged before the pitch clamp: the
+    // reference accumulates raw motion, so a drag pinned at the pitch limit still spends budget.
     let (yaw_rate, pitch_rate) = (look_cfg.yaw_rate(), look_cfg.pitch_rate());
     let dyaw = (mouse_motion.delta.x * yaw_rate).abs();
     let dpitch = (mouse_motion.delta.y * pitch_rate).abs();
@@ -1139,17 +778,11 @@ pub(super) fn run_look_session(
         test.pitch_travel += dpitch;
     }
 
-    // Mouse-look start/stop + cursor grab. **Both** buttons engage their look session on the DOWN
-    // edge — the reference has no deferral and no engage threshold (`0x51491f`), and the first
-    // motion sample already turns the camera. The click test is a separate rider decided at the
-    // release, which is exactly what lets one gesture orbit *and* select. Either button hides +
-    // locks the cursor in place (so it can't drift out of the window while we turn) and restores it
-    // where it was on release. A press that begins over the debug panel is egui's, not ours.
+    // Both buttons engage their session on the down edge, with no threshold (`0x51491f`); the click
+    // test rides along to the release. Looking hides and locks the cursor until the release.
     if let Some(active) = rig.look {
         if !buttons.pressed(active.button()) {
-            // The session's button went up: settle its click test against the reference predicate.
-            // A handoff release (the other button still held) never fires — the chord already
-            // cancelled both tests above.
+            // The button went up: settle its click test (a chord already cancelled both).
             let test = match active {
                 LookButton::Left => left_click.take(),
                 LookButton::Right => right_click.take(),
@@ -1166,11 +799,8 @@ pub(super) fn run_look_session(
                     }
                 }
             }
-            // The latched button went up. If the *other* look button is still held **by the
-            // world** (both-button run → single-button), hand the look session off to it rather
-            // than ending it — vanilla keeps turning/orbiting seamlessly on the remaining button,
-            // cursor staying hidden throughout. A primary the UI is holding is not a candidate:
-            // its binding never fired, so the reference has nothing to hand off to (B364).
+            // Hand off to the other button if the world holds it, as the reference keeps turning;
+            // a button the UI holds never fired its binding.
             let other = match active {
                 LookButton::Right => LookButton::Left,
                 LookButton::Left => LookButton::Right,
@@ -1180,7 +810,7 @@ pub(super) fn run_look_session(
             } else {
                 rig.look = None;
                 cursor_opts.grab_mode = CursorGrabMode::None;
-                // Show the cursor again (cross-platform; on macOS hiding is the cursor subsystem's job).
+                // Show the cursor again; on macOS hiding is the cursor subsystem's job.
                 cursor_opts.visible = true;
                 if let Some(pos) = rig.cursor_stash.take() {
                     window.set_cursor_position(Some(pos));
@@ -1188,11 +818,8 @@ pub(super) fn run_look_session(
             }
         }
     } else {
-        // A press over the egui dev UI (the overlaid debug panel, the perf pill), over a
-        // mouse-enabled player frame, or outside the world viewport is not ours — the whole content
-        // of [`WorldMouse`], and what keeps a slider-drag from grabbing the cursor into mouse-look.
-        // Right-drag turn. Arms its context-click test too; not armed when left is already down (a
-        // chord is never a click).
+        // `WorldMouse` has already dropped a press over the UI, the dev overlay or outside the
+        // viewport. Right-drag turns, and arms its click test unless left is held.
         if rig.world_mouse.down(LookButton::Right) {
             rig.look = Some(LookButton::Right);
             rig.cursor_stash = window.cursor_position();
@@ -1201,37 +828,32 @@ pub(super) fn run_look_session(
             *right_click =
                 (!rig.world_mouse.held(LookButton::Left)).then(|| PressGesture::new(now));
         } else if rig.world_mouse.down(LookButton::Left) && !inspect_enabled {
-            // Left-drag orbit — engaged on the press, exactly like right, because the reference
-            // engages on the press (`0x51491f`). The select is not deferred behind it; it rides
-            // along and settles at the release. While the inspector is armed left belongs to it
-            // (its own copy-on-click handler), so neither the orbit nor the test starts.
+            // Left-drag orbits, engaged on the press like right (`0x51491f`); the select settles
+            // at the release. While the inspector is armed, left belongs to it.
             rig.look = Some(LookButton::Left);
             rig.cursor_stash = window.cursor_position();
             cursor_opts.grab_mode = CursorGrabMode::Locked;
             cursor_opts.visible = false;
-            // A press the UI already consumed as a cursor-payload world drop (0216 §3) still orbits
-            // — the reference's orbit is unconditional on the down edge — but must not also select.
+            // A cursor-payload world drop still orbits (`0x51491f`) but must not also select.
             *right_click = None;
             *left_click = (!click_consumed && !rig.world_mouse.held(LookButton::Right))
                 .then(|| PressGesture::new(now));
         }
     }
 
-    // Apply this frame's accumulated motion as look rotation while a button is held. Right-drag also
-    // turns the character (its facing tracks the camera yaw); left-drag leaves the character facing.
+    // Look rotation; a right-drag also turns the character.
     if let Some(active) = rig.look {
         let delta = mouse_motion.delta;
         let d_yaw = -delta.x * yaw_rate;
         cam.yaw += d_yaw;
-        // `mouseInvertPitch` flips only the pitch axis (the 1.12 checkbox's whole meaning).
+        // `mouseInvertPitch` flips only the pitch axis.
         let dy = if look_cfg.invert_pitch {
             -delta.y
         } else {
             delta.y
         };
-        // **The pivot's fork** (`0x50fee0`, decision 2149): a pinned camera looking level-or-up,
-        // dragged mostly vertically, spends this delta on the view's pitch BIAS and leaves the
-        // arm alone. `None` is the reference's pure-pivot frame — the integrator does not run.
+        // The pivot's fork (`0x50fee0`): a pinned camera looking level or up, dragged mostly
+        // vertically, spends the delta on the pitch bias; `None` means the integrator does not run.
         let d_pitch = -dy * pitch_rate;
         if let Some(d_pitch) = rig.smart_pivot.route_pitch(
             d_pitch,
@@ -1247,48 +869,29 @@ pub(super) fn run_look_session(
             *face_yaw = cam.yaw;
         }
     }
-    // **The freelook latch.** Right-held is the reference's mouse-look; a left-drag is an orbit and
-    // is not freelook. A both-button run steers exactly as a right-drag does, which is the same
-    // "the world holds the right button" the `face_yaw` sync above tests — so it counts, and the
-    // two tests stay written the same way on purpose.
+    // Freelook is right-held mouse-look or a both-button run, which steers like it; a left-drag
+    // orbit is not. This test and the `face_yaw` sync above must stay alike.
     rig.freelook = rig.look == Some(LookButton::Right) || (rig.look.is_some() && both_buttons);
 }
 
-/// Wheel-zoom: the CAMERAZOOMIN/OUT bindings set a new target orbit distance, and the actual
-/// distance glides toward it at a constant `cameraDistanceMoveSpeed` (vanilla's linear,
-/// frame-delta-scaled glide — not an ease). Runs every frame regardless of active/detached state,
-/// mirroring the reference camera. `scroll` is this frame's net zoom-in amount (wheel notches in
-/// line-equivalents — the binding dispatch normalizes trackpad pixels — or the 1.12 key step of
-/// 1.0 per press; positive = closer), so a rebound zoom key feels exactly like a wheel notch.
+/// Wheel zoom, run every frame: `CAMERAZOOMIN`/`OUT` move the target, and the distance glides to it
+/// at a constant `cameraDistanceMoveSpeed`, as the reference's does. `scroll` is this frame's net
+/// zoom-in in notches (positive is closer).
 pub(super) fn apply_zoom_scroll(scroll: f32, dt: f32, rig: &mut CameraControl, max: f32) {
     if scroll != 0.0 {
         rig.target_distance =
             (rig.target_distance - scroll * CAM_ZOOM_STEP).clamp(CAM_DIST_MIN, max);
     }
-    // Re-clamp every frame, not just on a notch: lowering the Max Camera Distance slider has to
-    // pull a camera already sitting past the new ceiling back in, and the glide below then eases
-    // it there at the same yd/s a wheel notch would.
+    // Re-clamp every frame, so lowering the max-distance slider pulls the camera in.
     rig.target_distance = rig.target_distance.min(max);
-    // Glide the actual distance toward the wheel target at a constant `cameraDistanceMoveSpeed` yd/s,
-    // stopping exactly there — the verified vanilla behavior (linear, frame-delta-scaled; not an ease).
     let max_step = CAM_MOVE_SPEED * dt;
     rig.distance += (rig.target_distance - rig.distance).clamp(-max_step, max_step);
 }
 
-/// Seat the camera on **whatever the rig is orbiting this frame** — our own body, or a far-sight
-/// subject (B151: Mind Vision, Sentry Totem, and Mind Control's camera half in B211) while
-/// `PLAYER_FARSIGHT` names one. Three substitutions and then [`seat_camera`]: the orbit centre,
-/// the collision sweep's origin, and the pivot height's target.
-///
-/// It exists because the controller seats the camera from **two** places — the ordinary driving
-/// path, and the stand-down path where a spline, a possession or a reseat window owns the body —
-/// and far sight outlives all of those (Sentry Totem carries no interrupt flags at all, so you can
-/// board a taxi with your view still on the totem). Two copies of the substitution is how one of
-/// them silently stops honouring it.
-///
-/// `feet`/`head` are the caller's, because the head offset is the avatar capsule's and those
-/// constants are a movement concern; `body_pivot` is the target height read off the driven body
-/// this frame, used only when nothing else is being watched.
+/// Seat the camera on whatever it orbits: our own body, or the far-sight subject `PLAYER_FARSIGHT`
+/// names (Mind Vision, Sentry Totem, Mind Control), substituting the orbit centre, sweep origin and
+/// pivot target before [`seat_camera`]. Both of the controller's seat paths call it, as far sight
+/// outlives a spline or a possession (Sentry Totem has no interrupt flags).
 pub(super) fn seat_on_subject(
     dt: f32,
     turn_delta: f32,
@@ -1303,37 +906,23 @@ pub(super) fn seat_on_subject(
     follow: &FollowInput,
     dynamics: &DynamicsInput,
 ) {
-    // The sweep origin moves with the subject too; rooting it at our own head would cast the boom
-    // across the world and jam it on the first wall in between
-    // ([`super::view_subject::RemoteView::sweep_origin`]).
+    // The sweep origin moves with the subject: our own head would cast the boom across the world.
     let (orbit_pos, sweep_from) = match view.remote {
         Some(v) => (v.feet, v.sweep_origin()),
         None => (feet, head),
     };
-    // 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`], `0x50f160`). A
-    // far-sight subject supplies the target the same way the body
-    // does — one channel, whatever it is looking at.
+    // The framing height is the channel's, easing to the target over `|Δh| / 1.2` s
+    // (`0x50f160`); a far-sight subject feeds the same channel.
     let live_pivot = rig
         .pivot
         .advance(view.remote.map(|v| v.pivot_height).or(body_pivot), dt);
-    // **`cameraWaterCollision`'s corridor** — the half 2149 and 2170 each shipped without, and the
-    // reason the option is atomic. [`super::camera_water`] carries the block, the byte sites and
-    // the why; this is only the wiring.
-    //
-    // Classified against the channel's **target** (`[cam+0x1c8]`), never its live value — the
-    // 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
-    // (1203) — a low ceiling over a swimmer keeps the full reach, which is a pre-existing gap in
-    // the pivot rather than something the corridor introduces.
+    // `cameraWaterCollision`'s pivot corridor (`super::camera_water`), classified against the
+    // channel's target (`[cam+0x1c8]`), as the reference does. `headroom` is 1.0: the reference's
+    // vertical head-room probe (`0x50e6bd`) is not built, so a low ceiling keeps the full reach.
     let (_, pivot_target) = rig.pivot.probe();
     let (band, depth) = super::camera_water::classify(
-        // Our own body's cached surface, and only when the camera is watching our own body:
-        // `0x511ad0` reads the camera TARGET's liquid object and far sight carries none.
+        // Our own body's cached surface, only while watching our own body: `0x511ad0` reads the
+        // camera target's liquid object, and far sight carries none.
         view.remote
             .is_none()
             .then_some(dynamics.surface_y)
@@ -1347,31 +936,18 @@ pub(super) fn seat_on_subject(
         super::camera_water::corridor_off(live_pivot)
     };
     let orbit_pivot = super::camera_water::pivot_height(&corridor, pivot_target, live_pivot, 1.0);
-    // **And the corridor's floor lifts the SWEEP ORIGIN, which is the half that actually stops the
-    // pin.** The reference builds the boom's start from the clamped `*heightOut` itself
-    // (`0x50e786`), so in the surface band it sweeps from `surface + 2/9`; this client roots the
-    // boom at the capsule's top hemisphere centre instead, a pre-existing divergence that is
-    // harmless on land and decisive here. A surface-swimming human male's head sits
-    // `surface + 0.171`, and the camera probe has a `0.15` radius — so the probe starts **21 mm**
-    // clear of the water it is now allowed to hit, and a fraction of a degree of downward pitch
-    // collapses the arm from 15 yd to nothing.
-    //
-    // Measured, not reasoned: the end-to-end pitch sweep in `benilla_world::collision`
-    // (`a_surface_swimmers_arm_moves_smoothly_through_the_whole_pitch_range`) put that step at
-    // **6.65 yd** with the corridor applied to the framing pivot alone. Lifting the origin to the
-    // corridor floor takes it to a fraction of a yard. `max`, so this can only ever raise the
-    // origin: dry land and the submerge band are untouched, and nothing here can push the sweep
-    // start down into geometry.
+    // The corridor floor also lifts the sweep origin, which keeps the arm off the water. The
+    // reference starts the boom at the clamped pivot height (`0x50e786`), `surface + 2/9` in the
+    // surface band; ours starts at the head, `surface + 0.171` on a surface-swimming human male.
+    // `max` only raises it, so dry land and the submerge band are untouched.
     let sweep_from = Vec3::new(
         sweep_from.x,
         sweep_from.y.max(orbit_pos.y + corridor.floor),
         sweep_from.z,
     );
-    // **`cameraTerrainTilt`'s probe and channel.** The probe looks at the ground AHEAD of the
-    // subject, not under it: a horizontal ray along its facing from `feet + 5/3`, its hit pulled
-    // back `5/18`, then a `64/9` drop — so the slope is the rise of the ground you are walking
-    // ONTO over the run to it. Rooted at the subject, which is what makes far sight tilt to the
-    // totem's hill rather than to ours.
+    // `cameraTerrainTilt`'s probe looks at the ground ahead of the subject: a level ray along its
+    // facing from `feet + 5/3`, the hit pulled back `5/18`, then a `64/9` drop, so the slope is
+    // that of the ground being walked onto, the subject's own under far sight.
     let ground_probe = || {
         let origin = orbit_pos + Vec3::Y * super::camera_dynamics::PROBE_LIFT;
         let fwd = Quat::from_rotation_y(dynamics.subject.facing) * Vec3::NEG_Z;
@@ -1387,9 +963,8 @@ pub(super) fn seat_on_subject(
             .map_or(ahead.y - super::camera_dynamics::PROBE_DROP, |h| {
                 ahead.y - h.distance
             });
-        // `L = √(Δx² + Δy²)` is a length, so a hit closer than the backoff runs the probe
-        // *behind* the subject and still divides by a positive run — the reference's own
-        // arithmetic, not a guard added here.
+        // A hit closer than the backoff runs the probe behind the subject, and `L = √(Δx² + Δy²)`
+        // still divides by a positive run: the reference's own arithmetic.
         (ground_y - orbit_pos.y) / reach.abs().max(1.0e-3)
     };
     rig.terrain_tilt.advance(
@@ -1400,20 +975,17 @@ pub(super) fn seat_on_subject(
         &dynamics.options,
         dt,
     );
-    // **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.
+    // The mouse-look hand-off (`0x50d500` push, `0x50d520` pop), after the channel steps; the
+    // reference fires it from the input handler, at most one frame of channel motion apart (a
+    // fortieth of a degree at `cameraGroundSmoothSpeed`).
     let handed = rig.terrain_tilt.hand_off(rig.freelook);
     if handed != 0.0 {
         cam.pitch = (cam.pitch + handed).clamp(-CAM_PITCH_LIMIT, CAM_PITCH_LIMIT);
     }
 
-    // **`cameraBobbing`'s latch and kernel.** The session is armed off the input-command word, not
-    // off this gate, so it runs whatever the CVar says and only the OUTPUT is gated — which is what
-    // makes turning the CVar on mid-run start the bob at the phase the session has reached.
-    // `rig.distance` and not `collision_distance`: the reference's first conjunct is on the zoom
-    // (`[cam+0xec]`), so a camera squeezed against a wall is not thereby in first person.
+    // `cameraBobbing`: the session runs whatever the CVar says and only its output is gated. It
+    // reads the zoom, not the collided arm, as the reference's first conjunct is `[cam+0xec]`: a
+    // camera squeezed against a wall is not in first person.
     rig.head_bob
         .advance(rig.distance, &dynamics.subject, &dynamics.options, dt);
 
@@ -1432,19 +1004,12 @@ pub(super) fn seat_on_subject(
     );
 }
 
-/// Seat the third-person camera: orient it, orbit it behind the avatar's torso with a collision
-/// sweep from the head to the ideal seat (snap-in instantly, ease back out), write the resulting
-/// transform, and compute the self-avatar zoom-in fade from the realized camera-to-pivot distance.
-/// A **keyboard** turn (or the drunk veer, which rides `turn_delta` the same way — decision 1018)
-/// carries the camera rigidly — the character's own turns only: a transport
-/// deck turning under the rider is frame motion and is applied to `cam.yaw` at the ride block in
-/// [`super::control`], bypassing this function's look-session gate (routing it here was the
-/// right-drag drift bug — the gate ate the deck's share while a drag was held). A left-drag orbit
-/// offset is then reeled back in by the **auto-follow**, on the player's `cameraSmoothStyle`
-/// setting ([`FollowStyle`], decision 1493) — or kept forever, on Never.
-/// `head`/`player_pos` are precomputed by [`super::control`] (which owns the avatar capsule
-/// constants); `cam_pivot_height` is the world pivot height it derived from [`CameraPivot`] this
-/// frame.
+/// Seat the third-person camera: orient it, sweep the arm from `head` toward the ideal seat
+/// (snapping in, easing out), write the transform, and set the self-avatar fade. A keyboard turn
+/// (and the drunk veer on `turn_delta`) carries the camera rigidly; a transport deck's turn is
+/// applied in [`super::control`]'s ride block, outside the look-session gate here, which would
+/// drop it during a drag. `player_pos`, `head` and `cam_pivot_height` are [`seat_on_subject`]'s
+/// orbit centre, sweep origin and framing height.
 pub(super) fn seat_camera(
     dt: f32,
     turn_delta: f32,
@@ -1458,20 +1023,10 @@ pub(super) fn seat_camera(
     follow: &FollowInput,
     dynamics: &DynamicsInput,
 ) {
-    // A keyboard turn carries the camera RIGIDLY (char and camera rotate as one — the reference
-    // look, director's call closing 0050's open "camera follow on turn"): an eased chase of a
-    // continuously-turning facing lags by ω/rate, which read as the char angled on screen while
-    // run-turning and a release-snap landing off-camera. A drag (`rig.look` held) owns the camera
-    // — no INPUT-turn carry against the user's hand. (A transport deck's turn is not an input and
-    // never arrives here — the ride block applies it to `cam.yaw` directly, drag or no drag.)
-    //
-    // **The auto-follow** (1.12's `cameraSmoothStyle`, decisions 1493/1502) rides the same gate
-    // 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
-    // (`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).
+    // A keyboard turn carries the camera rigidly, as the reference's facing-relative yaw does; a
+    // held drag takes no carry. The auto-follow writes an absolute yaw, where the reference stores
+    // the offset and re-adds the facing at render time (`0x50f7f2`): the same picture, so Never
+    // leaves this carry running.
     let look_held = rig.look.is_some();
     if !look_held {
         cam.yaw += turn_delta;
@@ -1479,74 +1034,43 @@ pub(super) fn seat_camera(
     if let Some(yaw) = rig.follow.advance(follow, cam.yaw, dt, look_held) {
         cam.yaw = yaw;
     }
-    // Orient the camera, then orbit it behind the avatar's torso. The framing **pivot** is
-    // `feet + cam_pivot_height` (model-derived, ~neck height — [`CameraPivot`]); the camera looks at
-    // it and, at zoom 0, sits *on* it (first-person eye inside the head). Camera collision is a single
-    // sweep of the probe sphere from the player's *head* (the capsule's top hemisphere centre) out to
-    // the ideal camera seat (`pivot - fwd·zoom`). The camera rides along that sweep, stopping at the
-    // first surface (held off it by the probe radius). Rooting the arm at the head is what makes it
-    // robust: body collision keeps the head inside the room — even mid-jump it can't pass the ceiling
-    // — so the swept camera can never end up on the far side of a wall or ceiling. That is why a jump
-    // in a low room no longer pushes it through the roof: the sweep just stops under the ceiling
-    // instead of overshooting (the old min-distance floor used to force the camera *past* a too-close
-    // hit — gone; collision wins outright). `cast_move` ignores origin penetration, so a head grazing
-    // a surface still casts outward.
-    // **The seat is built from the UNBIASED pitch and the view from the biased one** — the whole
-    // of `cameraPivot` is that ordering (decision 2149). The reference computes the eye at
-    // `0x50edcc → 0x50de00` and stores it, and only *then* rotates the camera basis `[cam+0x14]`
-    // by `[cam+0x104]` at `0x50ee32`; so the arm never swings and the look direction does. The
-    // bias is zero at every default until a pinned camera is dragged, so `arm_rotation` and
-    // `rotation` are the same quaternion on almost every frame.
+    // The framing pivot is `feet + cam_pivot_height`; at zoom 0 the camera sits on it. One sweep
+    // runs from the head (the capsule's top hemisphere centre) to `pivot - fwd·zoom`, and body
+    // collision keeps the head inside the room, so the camera never ends up past a wall or ceiling.
+    // The cast ignores origin penetration, so a head grazing a surface still casts outward.
+    // The seat is built from the unbiased pitch and the view from the biased one: the reference
+    // stores the eye (`0x50edcc` → `0x50de00`) before rotating the basis `[cam+0x14]` by the bias
+    // `[cam+0x104]` (`0x50ee32`), so the arm never swings and the look does.
     let bias = rig.smart_pivot.bias();
-    // **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.
+    // The ground tilt is part of the arm's pitch, unlike the bias: `0x50f710` clamps
+    // `[cam+0xf4] + [cam+0x108]` to ±89° before the basis is built.
     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.
-    // 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.
+    // Not re-clamped: the bias is composed after that clamp (`0x50ee58`), bounded only by its own
+    // one-sided accumulate (`SmartPivot::route_pitch`) and ±89° at the body hand-off (`0x5103e0`).
     let rotation = if bias == 0.0 {
         arm_rotation
     } else {
         Quat::from_euler(EulerRot::YXZ, cam.yaw, arm_pitch + bias, 0.0)
     };
-    // `Transform::forward()` is exactly `rotation * -Z` (no renormalize), computed here from the
-    // local so the write below can be gated.
+    // `Transform::forward()` is exactly `rotation * -Z`; computed here so the write can be gated.
     let cam_fwd = arm_rotation * Vec3::NEG_Z;
     let pivot = player_pos + Vec3::Y * cam_pivot_height;
     let seat = pivot - cam_fwd * rig.distance;
     let boom = seat - head;
     let boom_len = boom.length().max(1.0e-3);
-    // The camera collides with the WMO *camera/LOS* faces (keeps DETAIL overhangs like forge pipes,
-    // drops NOCAMCOLLIDE) + terrain/doodads/GameObjects — its own audience, not the walking mesh.
-    //
-    // **And the waterline, under `cameraWaterCollision`** — registered `"1"`, so this is on out of
-    // the box. `0x50e5ec` ORs the `0xf0000` ADT-liquid nibble into the word all three of
-    // `0x50e570`'s queries carry, and it reaches `0x69cc13` through four direct calls, where it
-    // gates a Möller–Trumbore intersection (`0x7c2c40`, hit distance written at `0x7c2e5f`) over
-    // the chunk's four MCLQ slots. Two-sided, and with no near floor — which is precisely why the
-    // pivot corridor above is not optional: nothing in the trace itself stops a boom that starts
-    // on the water plane, so the *origin* is what has to be lifted clear.
-    //
-    // **And that water leg is a RAY, not this probe sphere** (decision 2185): `0x7c2c40` is a
-    // ray/triangle test and `0x672170` carries no radius, so the `2/9` yd the corridor lifts the
-    // origin by is a clearance budgeted for a point. The probe is `0.3` — it does not fit, and a
-    // level boom behind a surface swimmer was coming back pinned at zero. The split lives in
-    // [`benilla_world::collision::WorldCollision::cast_camera`], which owns the probe now; the
-    // sphere still sweeps the solid world, which is what it was always for.
+    // The camera collides with the WMO camera/LOS faces (DETAIL kept, NOCAMCOLLIDE dropped),
+    // terrain, doodads and GameObjects. Under `cameraWaterCollision` (default on) it also hits the
+    // waterline: `0x50e5ec` ORs the ADT-liquid nibble `0xf0000` into `0x50e570`'s query word,
+    // reaching a two-sided Möller–Trumbore test over the chunk's MCLQ slots (`0x69cc13`,
+    // `0x7c2c40`, hit at `0x7c2e5f`) with no near floor. That leg is a ray (`0x672170` has no
+    // radius), so `cast_camera` traces water as a ray and solids as a sphere.
     let hit = collide.cast_camera(head, boom, dynamics.options.water_collision);
-    // The solver's own clip verdict (`0x50e570`'s `0x30000` return, OR'd into `[cam+0x90]` by the
-    // driver) — [`SmartPivot`]'s sixth conjunct, and the reason an unobstructed camera never
-    // pivots. Written here because here is the only place that knows.
+    // The solver's clip verdict (`0x50e570`'s `0x30000`, OR'd into `[cam+0x90]` by the driver):
+    // [`SmartPivot`]'s sixth conjunct, so an unobstructed camera never pivots.
     rig.clipped = hit.is_some();
     let open = hit.unwrap_or(boom_len);
-    // Snap in instantly when geometry intrudes (a wall must never sit between camera and character);
-    // ease back out to the open arm length once it clears — the vanilla snap-close-then-glide-back.
+    // Snap in when geometry intrudes; ease back out once it clears.
     rig.collision_distance = if open < rig.collision_distance {
         open
     } else {
@@ -1555,17 +1079,12 @@ pub(super) fn seat_camera(
     };
     let frac = (rig.collision_distance / boom_len).clamp(0.0, 1.0);
     let seated = head + boom * frac;
-    // **The head bob is a pure world-space translation of the eye**, added last, into the same
-    // slot [`crate::camera_shake`] writes — which is exactly what the reference does (`0x50eb0f`
-    // folds the bob into the shake's accumulator and `0x50de00` applies the pair once). Zero on
-    // every frame nothing is bobbing, so the no-op write gate below still holds a parked camera
-    // bit-stable.
+    // The head bob is a world-space translation of the eye, added last into the slot
+    // [`crate::camera_shake`] writes, as the reference folds the bob into the shake's accumulator
+    // (`0x50eb0f`) and applies the pair once (`0x50de00`). Zero when nothing bobs.
     let translation = seated + rig.head_bob.offset();
-    // The no-op write gate (decision 1362 — 1355's clamp lesson, at the camera): a parked
-    // camera's pose is bit-stable once the collision ease settles, but writing it anyway marked
-    // the camera's transform changed every frame — which re-ran its propagation and told every
-    // camera-watching gate in the app that the view moved when it hadn't. Bit equality, not an
-    // epsilon: a real sub-epsilon drift must still land.
+    // Written only on a change, so a settled camera does not mark its transform changed every
+    // frame; bit equality, so a sub-epsilon drift still lands.
     {
         let t = cam_t.bypass_change_detection();
         if t.rotation != rotation || t.translation != translation {
@@ -1574,30 +1093,14 @@ pub(super) fn seat_camera(
             cam_t.set_changed();
         }
     }
-    // No waterline handling here — deliberately. The reference NEVER moves the eye for liquid
-    // (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
-    // said "the reference's 1/9" until the per-frame re-stamp at `0x511bd4` was read). 0905's eye
-    // snap — the local compensation for the old 1.0-yd near plane — is removed with its cause
-    // (its record is superseded; see the 0905-successor decision).
-    // `WOW_CAM_DUMP=frame`: the REALIZED pose, per frame, bit-exact — not the pose that was asked for.
-    //
-    // Every scripted probe sets `yaw`/`pitch`/`distance` and we then reason as though the camera is
-    // therefore where we put it. It is not: `collision_distance` is an exponentially-eased chase of a
-    // per-frame collision CAST, so a grazing hit that alternates gives an arm that snaps in and eases
-    // back out, and the camera keeps moving for as long as that lasts — with the scripted pose
-    // perfectly constant the whole time. B38's "the camera is static by construction, so nothing
-    // camera-derived can be the cause" (0671) rests entirely on that being untrue, and it was never
-    // measured. `open` is printed beside the eased arm so a hit/miss alternation in the CAST is
-    // visible even on a frame where the ease has not yet moved the camera far enough to see.
+    // The eye is never moved for liquid, as in the reference (no liquid-height query in
+    // `[0x7ac640, 0x7ae010)`): the submersion probe flips the frame once the lowest near-plane
+    // corner crosses the surface, a few inches at `nearclip`'s 0.1 (re-stamped at `0x511bd4`).
+    // `WOW_CAM_DUMP`: the realized pose per frame, bit-exact; `open` beside the eased arm shows a
+    // hit/miss alternation in the cast before the camera moves.
     if cam_dump_enabled() {
-        // `follow=` is the auto-follow's own reading (1502): the offset the return is animating,
-        // the state the input word classifies to, and — once armed — how far through the
-        // transition this frame is. `off` moving while `arm` reads `-` means something other than
-        // the follow moved the camera.
+        // `follow`: the offset, classified state, input word and `elapsed/dur+delay` (`-1`
+        // unarmed); `off` moving while unarmed means something else moved the camera.
         let (elapsed, delay, dur) = rig.follow.probe().unwrap_or((-1.0, -1.0, -1.0));
         eprintln!(
             "[cam] yaw {:.6} pitch {:.6} dist {:.6} open {:.6} coll {:.6} frac {:.6} \
@@ -1624,9 +1127,8 @@ pub(super) fn seat_camera(
         );
     }
 
-    // The pivot bias's own per-frame half (`0x50ed77` → `0x5107f0`): with the gate no longer true
-    // the bias eases back to zero at `cameraTargetSmoothSpeed`; with it true an ease in flight is
-    // cancelled where it stands. Runs after the sweep, so `rig.clipped` is this frame's.
+    // The pivot bias's per-frame half (`0x50ed77` → `0x5107f0`), eased to zero at
+    // `cameraTargetSmoothSpeed` once the gate is false; after the sweep, so `rig.clipped` is fresh.
     rig.smart_pivot.advance(
         cam.pitch,
         &dynamics.subject,
@@ -1636,14 +1138,8 @@ pub(super) fn seat_camera(
         dt,
     );
 
-    // Fade the avatar as the camera nears its pivot (zoom-in / a wall pulling the boom in): opaque
-    // in third-person, ramping to invisible in first-person. Keyed off the *realized* camera→pivot
-    // distance (collision-pulled), so backing into a wall also thins you — the faithful behavior.
-    // Off the SEATED eye, not the bobbed one: the fade is a statement about how far the boom was
-    // pulled in, and a 5 cm wobble is not that.
-    //
-    // The LIVE `nearclip`, not a constant (2163): the fade is defined as finishing where the near
-    // plane starts cutting, so a player who moves that plane has to move this with it.
+    // Fade by the realized camera-to-pivot distance from the seated eye, not the bobbed one, and
+    // the live `nearclip`: the fade finishes where the near plane starts cutting.
     rig.self_fade_alpha = self_model_fade_alpha(
         (seated - pivot).length(),
         dynamics.nearclip,
@@ -1651,42 +1147,12 @@ pub(super) fn seat_camera(
     );
 }
 
-/// Apply the self-avatar zoom-in fade ([`CameraControl::self_fade_alpha`], computed in [`control`]) to
-/// the player's own body parts **and every attach-model descendant** (held items, helm, shoulders —
-/// [`crate::entities::BoneAttach`] rides them several levels down through the joint hierarchy), so you
-/// go translucent then invisible — weapon and armor included — as the camera zooms into the head. Drives
-/// the same per-instance render-alpha channel as [`benilla_world::model_fade::apply_render_fade`] — the `MeshTag`
-/// alpha field on the blend-twin material — and hard-hides via [`Visibility`] at α 0 (true
-/// first-person; cheaper + cleaner than a ≈0-alpha head sitting on the camera).
-///
-/// Runs **after** the interior classifier + the appear/despawn fades so its override wins the frame; it
-/// overrides while fading (`α < 1`) and, on the frame the fade ends, **releases** the channel back
-/// (decision 0213): the classifier skips settled parts and rewrites only on a classification change, so
-/// without an explicit hand-back a fade episode that ends in a jump past 1 (a hitch frame closing the
-/// camera ease in one step, a pivot jump) left the avatar latched on the blend twin at its last low alpha
-/// — stuck translucent until the player happened to cross a room boundary. At steady `α ≥ 1` it does
-/// nothing, leaving the classifier the sole steady-state author. Parts mid appear/despawn fade
-/// (`RenderFade`/`PendingAppearFade`) are left to that fade — it's brief, owns the channel, and performs
-/// its own release on completion.
-///
-/// Walks the **full** descendant tree from the avatar root rather than just its direct children: body
-/// submeshes are direct children of the root, but a held item / helm / shoulder is a child of a joint
-/// entity (itself a descendant of the root, at varying depth) — an earlier direct-`Children`-only version
-/// silently skipped every attach model. The self-player entity is singular, so a per-frame tree walk over
-/// its handful of joints + submeshes is nil cost.
-///
-/// **The tree is not the whole model.** An M2's BILLBOARD batches can't be tree children — their mesh is
-/// centred on the bone pivot and their transform belongs to the billboard system, so every one of them is
-/// a world ROOT entity that merely *follows* an anchor inside the tree (decision 0153). The descendant
-/// walk therefore cannot see them, and the night-elf eye glow — two additive `…EYEGLOW.BLP` billboard
-/// quads at head height — went on burning in mid-air after the body it belongs to had gone (reported
-/// first-hand; ledger B71). Cards are picked up here by testing their follow-anchor against the walked
-/// set, and folded into the same α — the idiom [`crate::blob_shadow`] already uses for the other
-/// world-root follower of the self avatar ("the self first-person fade rides the same model-fade slot in
-/// the reference"). One multiply covers both halves: it feathers with the body, and at α 0 the additive
-/// compose (`wow_model.wgsl`: `out_rgb *= faded_alpha`) takes the card to black, which for an ADD blend
-/// is gone. That deliberately avoids `Visibility`, which the card's own hidden-owner mirror authors every
-/// frame in a different system.
+/// Apply the self-avatar fade ([`CameraControl::self_fade_alpha`]) to the body parts and every
+/// attach model under a joint, through the blend twin's alpha; α 0 hides them. Runs after the
+/// interior classifier and the appear/despawn fades, writes only while fading, and hands the
+/// channel back on the frame the fade ends. Billboard cards (the night-elf eye glow) are world
+/// roots following an anchor in the model: one whose anchor was walked takes the same α, with
+/// `Visibility` left to the card's hidden-owner mirror.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 pub(crate) fn apply_self_model_fade(
     rig: Res<CameraControl>,
@@ -1704,10 +1170,8 @@ pub(crate) fn apply_self_model_fade(
         (
             Without<RenderFade>,
             Without<PendingAppearFade>,
-            // Disjointness for the card query below (both want `&mut MeshTag`). A card carries
-            // `FadeMaterials` too since 0836, so this now genuinely diverts them — into the loop
-            // at the end, which applies the same law without touching `Visibility` (a card's own
-            // hidden-owner mirror authors that in a different system).
+            // Disjoint from the card query below (both take `&mut MeshTag`): cards carry
+            // `FadeMaterials` too, and the card loop fades them without touching `Visibility`.
             Without<benilla_world::billboard::BillboardCard>,
         ),
     >,
@@ -1720,8 +1184,8 @@ pub(crate) fn apply_self_model_fade(
         Option<&benilla_world::interior::InteriorLit>,
         Has<benilla_world::model_render::FarSideOfWater>,
     )>,
-    // The water-plane axis, composed into every pick below (`far_resolved`) like every other
-    // owner of the handle channel — the feather and the classifier converge, never re-swap.
+    // The water-plane twin, composed into every material pick below (`far_resolved`) as the
+    // classifier does, so the two never swap against each other.
     far_twins: Res<benilla_world::model_render::FarSideTwins>,
     mut reauthor: ResMut<benilla_world::interior::InteriorReauthor>,
     mut was_fading: Local<bool>,
@@ -1735,15 +1199,10 @@ pub(crate) fn apply_self_model_fade(
         *was_fading = false;
         return;
     };
-    // Our own live aura translucency (stealth, invisibility, ghost — `crate::aura_visual`) is a
-    // FACTOR of this fade, not a rival author: this system runs last on the self body and writes the
-    // alpha field verbatim, so a zoom-in while stealthed must carry the aura's term or the feather
-    // would silently re-opaque the character to 1.0 × the camera ramp. Folding it in here also makes
-    // the release edge honest — it releases at the *product*, so a fade ending while still stealthed
-    // hands the material back only if the body is genuinely opaque again.
+    // Our own aura translucency (stealth, invisibility, ghost) multiplies in, since this system
+    // writes the self body's alpha last; the release fires only once the product is opaque.
     let feather = rig.self_fade_alpha * crate::aura_visual::root_alpha(aura);
-    // The walked set doubles as "which anchors belong to this model" for the card pass — built only
-    // while fading, so the steady state (the early return above) never pays for it.
+    // The walked set names the anchors that belong to this model, for the card pass.
     let mut walked = EntityHashSet::default();
     apply_self_fade_to_descendants(
         root,
@@ -1762,21 +1221,15 @@ pub(crate) fn apply_self_model_fade(
         {
             continue;
         }
-        // The card's steady author is `entities::apply_unit_mat_alpha`, ordered before this system,
-        // which writes the batch's per-sequence factor every frame — so composing from `current`
-        // (not from the tag we'd read back) keeps that animation alive under the fade, and the
-        // release frame's `α = 1` write lands exactly on the value it would have had.
+        // From the card's authored factor (`MatAnim::current`, written first by
+        // `entities::apply_unit_mat_alpha`), not the tag, so the animation survives the fade.
         let authored = anim.map_or(1.0, |a| a.current);
         let bits = benilla_world::mesh_tag::with_alpha(tag.0, authored * alpha);
         if tag.0 != bits {
             tag.0 = bits;
         }
-        // …and the blend twin while feathering, exactly as a mesh part does. The alpha alone is
-        // enough for an ADDITIVE card (`wow_model.wgsl` folds it into the colour, so α 0 is black
-        // is gone), but an OPAQUE one — a pauldron's camera-facing trim, a chain link — ignores it
-        // entirely and stayed solid in first person until the card carried a twin to swap to
-        // (decision 0836). No `Visibility` here: that channel belongs to the card's hidden-owner
-        // mirror in another system.
+        // The blend twin too: an additive card fades by alpha alone (`wow_model.wgsl`), an opaque
+        // one only through the twin. `Visibility` is the card's hidden-owner mirror's.
         if let (Some(fm), Some(mut mat)) = (fm, mat) {
             let want = benilla_world::model_render::far_resolved(
                 fm.material_for(lit, alpha < 1.0),
@@ -1791,11 +1244,9 @@ pub(crate) fn apply_self_model_fade(
     *was_fading = fading;
 }
 
-/// Depth-first helper for [`apply_self_model_fade`]: apply the fade (or, at `α ≥ 1`, the release) to
-/// `entity` if it's a fadeable part, then recurse into its children regardless (a joint or an attach-model
-/// root carries no `FadeMaterials` itself but must still be descended through to reach the mesh leaves
-/// under 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.
+/// Apply the fade, or at `α ≥ 1` the release, to `entity` if it is a fadeable part, then recurse
+/// through its children (joints and attach roots carry no `FadeMaterials`). Every visited entity
+/// goes into `walked`, which names the anchors whose billboard cards follow this model.
 #[allow(clippy::type_complexity)]
 fn apply_self_fade_to_descendants(
     entity: Entity,
@@ -1823,12 +1274,8 @@ fn apply_self_fade_to_descendants(
     walked.insert(entity);
     if let Ok((fm, mut tag, mut mat, mut vis, lit, far_side)) = parts.get_mut(entity) {
         if alpha >= 1.0 {
-            // The release edge (runs once, on the frame the fade ends — decision 0213): un-hide,
-            // restore the alpha field this system owns, and hand the material back to the part's
-            // law. The alpha restore is unconditional: the classifier's payload writes carry the
-            // tag's alpha through since 0755 (that is what lets a part re-lane mid-fade), so
-            // leaning on its re-author to *also* re-opaque the avatar — as this used to — would
-            // leave it stuck translucent, the exact 0213 bug.
+            // The release edge: un-hide, restore the alpha and hand the material back. The alpha
+            // restore is ours: the classifier's writes carry the tag's alpha through.
             if *vis != Visibility::Inherited {
                 *vis = Visibility::Inherited;
             }
@@ -1844,8 +1291,8 @@ fn apply_self_fade_to_descendants(
             if mat.0 != *want {
                 mat.0 = want.clone();
             }
-            // A classifier-lit part is still enqueued so the next run re-asserts its full payload
-            // (probe slot / fog bit) over whatever this feather episode wrote — 0734's queue.
+            // A classifier-lit part is queued so the next run re-asserts its full payload (probe
+            // slot, fog bit) over this feather's writes.
             if lit.is_some() {
                 reauthor.0.push(entity);
             }
@@ -1858,18 +1305,14 @@ fn apply_self_fade_to_descendants(
             if *vis != Visibility::Inherited {
                 *vis = Visibility::Inherited;
             }
-            // Feathering: ride the blend twin with the alpha packed into the tag's alpha field
-            // (the cutout ignores α; `with_alpha` preserves the ground-shade byte so a shadowed
-            // avatar doesn't flash lit while zooming).
+            // Feathering: the blend twin, with the alpha in the tag's alpha field (`with_alpha`
+            // keeps the ground-shade byte, so a shadowed avatar does not flash lit).
             let bits = benilla_world::mesh_tag::with_alpha(tag.0, alpha);
             if tag.0 != bits {
                 tag.0 = bits;
             }
-            // A bake-classified part feathers on the PROBE-lit blend twin — the room light
-            // rides the fade (the tag re-lane keeps the slot alongside the alpha, 0355); the
-            // exterior twin at shade byte 0 read as full outdoor intensity deep indoors
-            // (director-caught, 2026-07-13). Shared with the appear/despawn ramp since 0755, so
-            // the two can never disagree about which twin a law wants.
+            // A bake-classified part feathers on the probe-lit blend twin, so the room light rides
+            // the fade; `material_for` is shared with the appear/despawn ramp, so both pick alike.
             let want = benilla_world::model_render::far_resolved(
                 fm.material_for(lit, true),
                 far_side,
@@ -1895,10 +1338,7 @@ fn apply_self_fade_to_descendants(
     }
 }
 
-/// True if the OS pointer is over the world camera's render area. The world camera now fills the window
-/// (the debug panel overlays rather than insetting), so this is really just "is the cursor inside the
-/// window?"; the panel itself is excluded by `PointerOverUi` at the call site. Kept viewport-aware in
-/// case anything insets the camera again.
+/// True if the OS pointer is over the world camera's viewport (the whole window when it has none).
 fn cursor_in_viewport(window: &Window, camera: &Camera) -> bool {
     let Some(cursor) = window.physical_cursor_position() else {
         return false;
@@ -1913,9 +1353,8 @@ fn cursor_in_viewport(window: &Window, camera: &Camera) -> bool {
     }
 }
 
-/// Free-fly (pre-connect or `F`-detached): aim from the look angles, move the camera directly —
-/// WASD in the camera basis, Space/C up/down, Ctrl 5× boost. The avatar stays frozen where it was;
-/// [`super::control`] parks the mover before calling so the wire never extrapolates a phantom walk.
+/// Free-fly (pre-connect or detached): WASD in the camera basis, Space/C up and down, Ctrl 5×.
+/// [`super::control`] parks the mover first, so the wire never extrapolates a phantom walk.
 pub(super) fn fly_free(
     dt: f32,
     keys: &ButtonInput<KeyCode>,
@@ -1925,7 +1364,7 @@ pub(super) fn fly_free(
     cam_t: &mut Transform,
 ) {
     let keys_pressed = |k: KeyCode| !typing && keys.pressed(k);
-    // Detached / pre-connect: keep the avatar fully opaque (you flew off to look at it — no fade).
+    // Detached, the avatar stays opaque.
     rig.self_fade_alpha = 1.0;
     cam_t.rotation = Quat::from_euler(EulerRot::YXZ, cam.yaw, cam.pitch, 0.0);
     let forward = *cam_t.forward();
@@ -1959,8 +1398,7 @@ pub(super) fn fly_free(
     }
 }
 
-/// `$WOW_CAM_DUMP` — the per-frame camera/turn dump (this file's seat and the controller's turn
-/// line share it). One read for the process: both sites sit on the every-frame path.
+/// `WOW_CAM_DUMP`: the per-frame camera and turn dump, read once per process.
 pub(crate) fn cam_dump_enabled() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_CAM_DUMP").is_some())
@@ -1976,8 +1414,7 @@ mod tests {
     use benilla_world::billboard::BillboardCard;
     use benilla_world::mesh_tag::alpha_bits;
 
-    /// Step a [`PivotGlide`] at 60 Hz for `secs`, holding the target, and return the heights it
-    /// passed through (one per frame).
+    /// Step a [`PivotGlide`] at 60 Hz for `secs`, holding the target; returns each frame's height.
     fn glide_run(g: &mut PivotGlide, target: Option<f32>, secs: f32) -> Vec<f32> {
         let dt = 1.0 / 60.0;
         (0..(secs / dt).round() as usize)
@@ -1985,17 +1422,13 @@ mod tests {
             .collect()
     }
 
-    /// **The report** (the director, on the reference vs ours): shifting form on the real client
-    /// *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.
+    /// A shapeshift glides the pivot both ways and never snaps: the far chain clamps back to the
+    /// live value (`0x50e767`).
     #[test]
     fn a_shapeshift_glides_the_pivot_both_ways_and_never_snaps() {
         // Tauren → cat: the heights measured off a live probe run.
         let (tauren, cat) = (2.4659_f32, 1.0552_f32);
         let mut g = PivotGlide::default();
-        // The first height a camera ever sees is established, not travelled to (`0x5127d4`).
         assert_eq!(
             g.advance(Some(tauren), 1.0 / 60.0),
             tauren,
@@ -2005,7 +1438,6 @@ mod tests {
         for (from, to) in [(tauren, cat), (cat, tauren)] {
             let expected = (to - from).abs() / CAM_PIVOT_SMOOTH_SPEED;
             let frames = glide_run(&mut g, Some(to), expected * 2.0);
-            // It arrives, and only at the end.
             assert!((frames.last().copied().unwrap() - to).abs() < CHANNEL_EPS);
             let arrived = frames
                 .iter()
@@ -2016,8 +1448,7 @@ mod tests {
                 (took - expected).abs() < 0.05,
                 "|Δh| / 1.2 yd/s = {expected:.3} s, took {took:.3} s ({from} → {to})"
             );
-            // No frame jumps: the biggest single step is the cosine's own midpoint rate, which
-            // for these Δ is far under half the total. A snap would put the whole Δ in one frame.
+            // No frame jumps: the biggest step is the cosine's midpoint rate, far under half of Δ.
             let biggest = frames
                 .windows(2)
                 .map(|w| (w[1] - w[0]).abs())
@@ -2030,10 +1461,8 @@ mod tests {
         }
     }
 
-    /// A model that has not resolved yet **holds** the channel — the reference skips the camera
-    /// update outright while the preset is stale (`0x50e907`), which is what makes a display swap
-    /// read as a pause and then one glide. Aiming at a placeholder in the meantime would send the
-    /// camera on a round trip.
+    /// A model not yet resolved holds the channel (the reference skips the camera update while the
+    /// preset is stale, `0x50e907`), so a display swap is a hold, then one glide.
     #[test]
     fn a_body_with_no_model_holds_the_pivot_instead_of_re_aiming_it() {
         let mut g = PivotGlide::default();
@@ -2048,9 +1477,7 @@ mod tests {
         assert!(frames[0] < 2.4659 && frames[0] > 2.4);
     }
 
-    /// The per-frame re-arm has to be a **no-op** in steady state (the setter's 0.001 epsilon,
-    /// `0x5126b0`). Restarting the move from its own midpoint every frame would stretch it
-    /// asymptotically and it would never arrive — the classic re-arm bug this epsilon prevents.
+    /// Re-arming the same target every frame is a no-op (`0x5126b0`'s 0.001 epsilon).
     #[test]
     fn re_arming_the_same_target_every_frame_does_not_stretch_the_glide() {
         let mut g = PivotGlide::default();
@@ -2062,9 +1489,7 @@ mod tests {
         );
     }
 
-    /// The pivot target is the model height × the **raw** scale, clamped to the reference's own
-    /// `[5/6, 15]` band (`0x50ca90`) — a giant's aura cannot walk the framing pivot into the sky,
-    /// and a shrink cannot bury it in the floor.
+    /// The pivot target is clamped to the reference's `[5/6, 15]` band (`0x50ca90`).
     #[test]
     fn the_pivot_target_is_clamped_to_the_references_band() {
         let p = CameraPivot {
@@ -2076,10 +1501,9 @@ mod tests {
         assert_eq!(model_pivot_height(&p, 100.0, false), CAM_PIVOT_CEIL);
     }
 
-    /// **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, measured off
-    /// the binary: standing 1.9002692, swimming 1.5120120.
+    /// The swim preset, `cam+0x124` (`0x50f880`, `0x50ccf6`): the standing height less
+    /// `StandSeq.max.z − SwimSeq.max.z`. The Human Male figures are computed from its shipped model
+    /// with the reference's formula: standing 1.9002692, swimming 1.5120120.
     #[test]
     fn swimming_takes_the_lower_pivot_preset() {
         let human = CameraPivot {
@@ -2088,8 +1512,7 @@ mod tests {
         };
         assert!((model_pivot_height(&human, 1.0, false) - 1.9002692).abs() < 1e-5);
         assert!((model_pivot_height(&human, 1.0, true) - 1.512_012).abs() < 1e-5);
-        // The preset multiplies the scale, then clamps — the swim leg shares the band with the
-        // standing one (`0x50ca90` clamps all three presets together).
+        // The preset scales, then clamps: `0x50ca90` clamps all three presets alike.
         assert!(
             (model_pivot_height(&human, 2.0, true) - 2.0 * 1.512_012).abs() < 1e-5,
             "the swim preset scales like its sibling"
@@ -2098,9 +1521,8 @@ mod tests {
         assert_eq!(model_pivot_height(&human, 100.0, true), CAM_PIVOT_CEIL);
     }
 
-    /// A model with **no Swim sequence** — every non-character model, and the reference's own
-    /// both-sequences-present guard (`0x711960` on ids 0 and 0x2a). Its drop is `0.0`, so the swim
-    /// preset degenerates to the standing one and a body that cannot swim never dips.
+    /// A model with no Swim sequence (the reference needs both ids 0 and 0x2a, `0x711960`) has a
+    /// drop of 0.0, so its swim preset is the standing one.
     #[test]
     fn a_model_that_cannot_swim_keeps_the_standing_preset() {
         let chicken = CameraPivot {
@@ -2114,7 +1536,7 @@ mod tests {
         assert_eq!(model_pivot_height(&chicken, 1.0, true), 1.2);
     }
 
-    /// A press that has travelled `yaw`/`pitch` **degrees** of camera rotation.
+    /// A press that has travelled `yaw`/`pitch` degrees of camera rotation.
     fn press(yaw_deg: f32, pitch_deg: f32) -> PressGesture {
         PressGesture {
             at: 0.0,
@@ -2123,34 +1545,21 @@ mod tests {
         }
     }
 
-    /// The report this whole change exists for (ledger B226, decision 1122): **a fast click
-    /// selects however far the mouse swept.** Under 200 world the reference asks nothing about
-    /// motion at all (`0x514ae0`'s first arm, `0x514b24`) — which is the gesture people actually
-    /// make, flicking the cursor at a mob and clicking on arrival with the hand still moving.
-    /// benilla used to destroy the pending click after 4 px of travel, so this case never fired.
+    /// Under 200 ms the reference ignores motion (`0x514ae0`'s first arm, `0x514b24`): flick the
+    /// cursor onto a mob, click on arrival with the hand still moving, and it selects.
     #[test]
     fn a_fast_click_selects_however_far_the_mouse_swept() {
-        // A whole screen's worth of sweep — orders of magnitude past the travel gate.
+        // A whole screen's worth of sweep, far past the travel gate.
         let swept = press(90.0, 45.0);
         assert!(
             swept.is_click(0.199),
             "under 200 world, travel is not consulted"
         );
-        // And the camera is expected to have orbited through all of it: the two are independent,
-        // which is the half that makes the reference's gesture possible at all.
     }
 
-    /// The `mousespeed` slider is a MULTIPLIER over the shipped per-pixel rate (decision 1140), and
-    /// the neutral notch has to reproduce the old constant exactly — the whole point of registering
-    /// the default at 1.0 is that nobody's feel changes until they move the slider. Both the look
-    /// rotation and the click-vs-drag travel budget read this one function, so the drag threshold
-    /// scales with the pointer instead of drifting away from it.
+    /// `mousespeed` multiplies the base rate, and its default 1.0 reproduces `LOOK_SENSITIVITY`.
     #[test]
     fn the_sensitivity_slider_is_a_multiplier_over_the_shipped_rate() {
-        // **The shipped feel is unchanged by the two move-speed CVars landing**: at the
-        // reference's own defaults BOTH axes come out at exactly the rate this client has always
-        // used. That is the whole point of anchoring the scale to `LOOK_SENSITIVITY` rather than
-        // transplanting the reference's deg-per-accelerated-pixel onto our raw device delta.
         let d = LookConfig::default();
         assert_eq!(d.yaw_rate(), LOOK_SENSITIVITY);
         assert_eq!(d.pitch_rate(), LOOK_SENSITIVITY);
@@ -2169,11 +1578,8 @@ mod tests {
         assert_eq!(slow.pitch_rate(), LOOK_SENSITIVITY * 0.5);
     }
 
-    /// **Each move-speed CVar scales its own axis, linearly, and only its own** — the reference's
-    /// law shape (`Δyaw_deg = value × Δx / 800`, `Δpitch_deg = value × Δy / 600`).
-    ///
-    /// The slider's own stops are the check: `UIOptionsFrameSliders`' MOUSE_LOOK_SPEED row runs
-    /// 90…270, so its ends are half and one-and-a-half times the shipped rate.
+    /// Each move-speed CVar scales its own axis linearly, the reference's law shape
+    /// (`Δyaw° = value × Δx / 800`, `Δpitch° = value × Δy / 600`).
     #[test]
     fn each_move_speed_cvar_scales_its_own_axis() {
         let doubled_yaw = LookConfig {
@@ -2194,9 +1600,8 @@ mod tests {
         assert_eq!(doubled_pitch.pitch_rate(), LOOK_SENSITIVITY * 2.0);
         assert_eq!(doubled_pitch.yaw_rate(), LOOK_SENSITIVITY);
 
-        // The MOUSE_LOOK_SPEED slider's two ends. Approximate, because the two sides multiply
-        // the same three factors in a different order and f32 is not associative — the property
-        // under test is the ratio, not the last bit.
+        // The MOUSE_LOOK_SPEED slider's ends (90, 270), compared approximately: the two sides
+        // multiply in a different order, and f32 multiplication is not associative.
         let near = |a: f32, b: f32| (a - b).abs() < 1e-9;
         for (speed, factor) in [(90.0_f32, 0.5_f32), (270.0, 1.5)] {
             let at = LookConfig {
@@ -2206,7 +1611,6 @@ mod tests {
             assert!(near(at.yaw_rate(), LOOK_SENSITIVITY * factor));
         }
 
-        // `mousespeed` still multiplies on top of both — the 1140 property, unchanged.
         let both = LookConfig {
             yaw_speed: 270.0,
             sensitivity: 1.5,
@@ -2215,13 +1619,8 @@ mod tests {
         assert!(near(both.yaw_rate(), LOOK_SENSITIVITY * 1.5 * 1.5));
     }
 
-    /// **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 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
-    /// is what "stays where you put it, except while you're moving" actually is.
+    /// The auto-follow (`0x510960`, `0x50f160`): edge-armed, then unattended, a cosine over
+    /// `|Δ| / rate × factor` clamped to [0.1 s, 2.0 s]; Smart's `Idle` and `Stop` rows cancel.
     #[test]
     fn the_auto_follow_is_armed_by_an_input_edge_and_eases_home() {
         const DT: f32 = 1.0 / 120.0;
@@ -2251,8 +1650,7 @@ mod tests {
             yaw
         }
 
-        // ── Smart: standing still with the camera dragged aside, nothing happens; the moment the
-        // W edge lands, one armed transition brings it home over |Δ|/180°/s = 0.5 s.
+        // ── Smart: standing still nothing happens; the W edge returns it in |Δ|/180°/s = 0.5 s.
         let mut rig = FollowRig::default();
         let c = cfg(FollowStyle::Smart);
         let parked = run(&mut rig, c, 0, OFFSET, 1.0);
@@ -2267,7 +1665,6 @@ mod tests {
         );
         let home = run(&mut rig, c, follow_cmd::FORWARD, half, 0.3);
         assert!(home.abs() < 1.0e-4, "arrived behind the character: {home}");
-        // And holding W changes nothing further — the transition is spent, not a standing chase.
         let still_home = run(&mut rig, c, follow_cmd::FORWARD, home + 0.4, 1.0);
         assert_eq!(
             still_home,
@@ -2275,14 +1672,13 @@ mod tests {
             "a HELD key re-arms nothing: only edges arm"
         );
 
-        // ── Smart: releasing W (an edge into Stop) cancels rather than arming, so a camera nudged
-        // while stopping stays nudged.
+        // ── Smart: releasing W (an edge into Stop) cancels, so a nudge while stopping stays.
         let mut rig = FollowRig::default();
         let held = run(&mut rig, c, follow_cmd::FORWARD, 0.0, 0.1);
         let released = run(&mut rig, c, 0, held + OFFSET, 0.5);
         assert_eq!(released, held + OFFSET, "Stop is a cancel under Smart");
 
-        // ── Always arms on that very same Idle edge — the one row where the two styles differ.
+        // ── Always arms on that same Idle edge, the one row where the two styles differ.
         let mut rig = FollowRig::default();
         let a = cfg(FollowStyle::Always);
         let held = run(&mut rig, a, follow_cmd::FORWARD, 0.0, 0.1);
@@ -2302,8 +1698,7 @@ mod tests {
             "Never never arms"
         );
 
-        // ── The duration floor: a 5° correction is 0.028 s of travel at 180 °/s, and the
-        // reference's 0.1 s minimum overrides it — so it is NOT finished after 0.05 s.
+        // ── The duration floor: 5° at 180°/s is 0.028 s, but the 0.1 s minimum holds.
         let mut rig = FollowRig::default();
         let small = 5.0_f32.to_radians();
         let _ = run(&mut rig, c, 0, small, DT);
@@ -2314,8 +1709,7 @@ mod tests {
         );
         assert!(run(&mut rig, c, follow_cmd::FORWARD, mid, 0.06).abs() < 1.0e-4);
 
-        // ── Track (a taxi, a spline): Smart takes it lazily — 0.4 s of dead time first, then a
-        // factor-10 return the 2 s ceiling caps.
+        // ── Track: Smart waits 0.4 s, then a factor-10 return the 2 s ceiling caps.
         let mut rig = FollowRig::default();
         let _ = run(&mut rig, c, 0, OFFSET, DT);
         let delayed = run(&mut rig, c, follow_cmd::TRACK, OFFSET, 0.3);
@@ -2340,9 +1734,7 @@ mod tests {
         assert!(rig.advance(&input, OFFSET, DT, true).is_none());
         assert!(rig.advance(&input, OFFSET, DT, true).is_none());
 
-        // ── …and entering the drag **cancels** what was in flight (`0x50fe30` zeroes the
-        // descriptors), so the return does not simply resume when the button comes up. Grab the
-        // camera mid-swing and it stays where the hand left it until the next input edge.
+        // ── Entering the drag cancels the swing in flight (`0x50fe30`) until the next edge.
         let mut rig = FollowRig::default();
         let _ = run(&mut rig, c, 0, OFFSET, DT);
         let mid = run(&mut rig, c, follow_cmd::FORWARD, OFFSET, 0.1);
@@ -2369,24 +1761,14 @@ mod tests {
             yaw
         };
         assert_eq!(parked, mid, "the cancelled transition does not resume");
-        // …and the release's own edge (the mouse bit leaving the word) is what starts a new one.
         assert!(
             run(&mut rig, c, follow_cmd::FORWARD, parked, 1.0).abs() < 1.0e-4,
             "the release edge arms a fresh return"
         );
     }
 
-    /// 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.
-    /// `RIGHT_MOUSE` alone is a [`FollowState::Turn`], and Smart's Turn row is `(0.0, 1.0)` — no
-    /// delay, full factor — so the return armed on the press edge and ran to completion.
-    ///
-    /// The decode is pinned end to end, from the latch to the row the classifier picks, because
-    /// each half was individually right: the classifier is the reference's (the test below), and
-    /// the look session's own gate was already there. What was missing was the word reading the
-    /// same gate.
+    /// A right-click the UI took (a Who-list row) sets no mouse bit in the camera's command word,
+    /// so it cannot arm Smart's `Turn` row, an immediate return; pinned from the latch to the row.
     #[test]
     fn a_press_the_ui_ate_never_reaches_the_camera_command_word() {
         let word = |world_press: bool| {
@@ -2410,7 +1792,7 @@ mod tests {
             .state(false)
         };
 
-        // The report: the press landed on a UI row.
+        // The press landed on a UI row.
         assert_eq!(word(false), 0, "a captured press sets no mouse bit");
         assert_eq!(classify(word(false)), FollowState::Idle);
         assert_eq!(
@@ -2425,13 +1807,8 @@ mod tests {
         assert_eq!(FollowStyle::Smart.row(FollowState::Turn), (0.0, 1.0));
     }
 
-    /// The latch's own law: a button is claimed at the DOWN edge and held to its own release.
-    ///
-    /// Level-testing "is the cursor over UI *right now*" instead would drop the bit mid-drag the
-    /// moment a frame appeared under the (stationary, locked) cursor — a phantom edge on the
-    /// command word, which is exactly what arms a return. And the second button of a chord has to
-    /// join: the reference's both-button run is both bindings held, and the second press lands on
-    /// a cursor the first one already hid.
+    /// A button is claimed at its down edge and held to its own release, so the UI arriving under
+    /// the locked cursor cannot drop it; a chord's second button joins the held gesture.
     #[test]
     fn the_world_holds_a_button_from_its_press_to_its_release() {
         let mut rig = CameraControl::default();
@@ -2470,8 +1847,7 @@ mod tests {
             "both primaries = the both-button run"
         );
 
-        // …and the release is what ends it — including the synthetic one a cover produces by
-        // emptying the button planes, which is a release of both without a `just_released`.
+        // …and the release ends it, including a cover's synthetic one (emptied button planes).
         buttons = ButtonInput::<MouseButton>::default();
         rig.world_mouse.update(&buttons, false);
         assert!(!rig.world_mouse.both());
@@ -2479,11 +1855,8 @@ mod tests {
         assert!(!rig.world_mouse.held(LookButton::Left));
     }
 
-    /// 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
-    /// priority order, which is what decides the row when several are true at once.
+    /// The classifier (`0x510960`) reads the camera's command word, not the character's velocity,
+    /// and its priority order decides when several states hold.
     #[test]
     fn the_follow_state_reads_the_camera_input_word_not_the_character() {
         let state = |command: u32, stopping: bool| {
@@ -2521,8 +1894,7 @@ mod tests {
             FollowState::Fear,
             "Fear outranks everything"
         );
-        // …and the tracking style is the selector the moment Track or Fear is merely PRESENT,
-        // even when a higher-priority state supplies the row.
+        // …and the tracking style selects whenever Track or Fear is present.
         let mixed = FollowInput {
             cfg: FollowConfig {
                 style: FollowStyle::Never,
@@ -2536,15 +1908,14 @@ mod tests {
         assert_eq!(mixed.state(false), FollowState::Move);
     }
 
-    /// The enum is the ENGINE's (0/1/2), not the 1/2/3 the reference's own dropdown writes — and
-    /// that stray `3` still has to mean Never, because that is what whoever wrote it meant.
+    /// The engine's 0/1/2, which the stock dropdown writes; the validator's 3 reads as Never.
     #[test]
     fn the_follow_style_enum_is_the_engines_and_tolerates_the_dropdowns_stray() {
         assert_eq!(FollowStyle::from_cvar(0.0), FollowStyle::Never);
         assert_eq!(FollowStyle::from_cvar(1.0), FollowStyle::Smart);
         assert_eq!(FollowStyle::from_cvar(2.0), FollowStyle::Always);
         assert_eq!(FollowStyle::from_cvar(3.0), FollowStyle::Never);
-        // Off the ladder entirely: the registrar default, not a dead camera.
+        // Off the ladder: the default, Smart.
         assert_eq!(FollowStyle::from_cvar(-1.0), FollowStyle::Smart);
         assert_eq!(FollowStyle::from_cvar(9.0), FollowStyle::Smart);
         for style in [FollowStyle::Never, FollowStyle::Smart, FollowStyle::Always] {
@@ -2557,9 +1928,8 @@ mod tests {
         assert_eq!(FollowStyle::default(), FollowStyle::Smart);
     }
 
-    /// The second arm: between 200 and 800 world the travel gate applies, per axis and independently
-    /// (`0x514ae0`'s `both accums < 8.0` arm). The thresholds are the reference's 2.25° of yaw and
-    /// 2.0° of pitch — see [`CLICK_HOLD_CEILING`] for why we hold the angle, not the raw literal.
+    /// Between 200 and 800 ms the travel gate applies per axis (`0x514ae0`'s `< 8.0` arm), at 2.25°
+    /// of yaw and 2.0° of pitch ([`CLICK_HOLD_CEILING`]).
     #[test]
     fn between_the_windows_a_steady_hand_still_clicks_but_a_drag_does_not() {
         assert!(press(2.0, 1.5).is_click(0.5), "inside both travel gates");
@@ -2576,10 +1946,8 @@ mod tests {
         );
     }
 
-    /// The 800 world ceiling (`0x514aeb lea eax,[edx-0x320]`) is absolute — a long hold is never a
-    /// click, however still the hand was. This is the arm that keeps a deliberate camera orbit from
-    /// re-targeting whatever it started on, and it is the reason the fix could not simply be
-    /// "always select on release".
+    /// The 800 ms ceiling (`0x514aeb lea eax,[edx-0x320]`) is absolute: a long hold is never a
+    /// click, so a deliberate orbit does not retarget what it started on.
     #[test]
     fn a_long_hold_is_never_a_click_however_still() {
         let motionless = press(0.0, 0.0);
@@ -2591,12 +1959,8 @@ mod tests {
         );
     }
 
-    /// The self-avatar's zoom-to-first-person fade reaches its BILLBOARD cards — the night-elf eye
-    /// glow (ledger B71: two additive quads left burning in mid-air after the body was hidden).
-    /// A card is a world ROOT following an anchor inside the model (decision 0153), so the fade's
-    /// descendant walk can only claim it through that anchor — and must claim ONLY its own: every
-    /// brazier and lamppost in the zone is a card too, and dimming those with the player's zoom
-    /// would be a far worse bug than the one being fixed.
+    /// The self fade reaches the avatar's billboard cards (the night-elf eye glow) through their
+    /// anchors, and only its own: every brazier in the zone is a card too.
     #[test]
     fn self_fade_reaches_the_avatars_billboard_cards_and_no_others() {
         let info = BillboardInfo {
@@ -2609,7 +1973,7 @@ mod tests {
         let mut app = App::new();
         app.init_resource::<CameraControl>();
         app.init_resource::<benilla_world::interior::InteriorReauthor>();
-        // The water-plane twin map the feather composes with (empty — no water in a fixture).
+        // The water-plane twin map the feather composes with, empty in a fixture.
         app.init_resource::<benilla_world::model_render::FarSideTwins>();
         app.add_systems(Update, apply_self_model_fade);
 
@@ -2636,7 +2000,6 @@ mod tests {
 
         let tag_of = |app: &App, e: Entity| app.world().entity(e).get::<MeshTag>().unwrap().0;
 
-        // Mid-feather: the glow rides the body's alpha down.
         app.world_mut()
             .resource_mut::<CameraControl>()
             .self_fade_alpha = 0.5;
@@ -2659,7 +2022,6 @@ mod tests {
         app.update();
         assert_eq!(tag_of(&app, eye_glow), alpha_bits(0.0));
 
-        // Back out to third person — the release frame hands the authored value back.
         app.world_mut()
             .resource_mut::<CameraControl>()
             .self_fade_alpha = 1.0;
diff --git a/crates/benilla-app/src/player/camera_channel.rs b/crates/benilla-app/src/player/camera_channel.rs
index c59e90aa..80425aff 100644
--- a/crates/benilla-app/src/player/camera_channel.rs
+++ b/crates/benilla-app/src/player/camera_channel.rs
@@ -1,69 +1,41 @@
-//! **The camera's smoothed-scalar channel** — the one template the reference instantiates four
-//! times, in one place instead of four.
+//! The camera's smoothed-scalar channel: one template the reference instantiates for pitch
+//! (armer/inner `0x512830`/`0x512980`), pitch bias (`0x512a50`/`0x512ba0`), ground tilt
+//! (`0x512490`/`0x5125e0`) and pivot height (`0x5126b0`/`0x512790`), stepped in one block of
+//! `0x50f160`.
 //!
-//! 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
-//! already had ([`super::camera::PivotGlide`]) — is a fourth. Their per-frame step is one block of
-//! one function (`0x50f160`).
+//! The armer rewraps the live value into `[target − π, target + π]`, refuses a request when the
+//! channel is already arming the same `{target, delay, factor}` or is within 0.001 of the target,
+//! and otherwise sets `duration = |target − live| / rate · factor`. The step eases by the cosine
+//! smoothstep `0x5b7bb0`, `a + (b − a)·(1 − cos πs)/2` with `s = elapsed / duration`, and lands on
+//! the target at `s ≥ 1`. The duration is seconds, not a rate, and the rate is in the live value's
+//! units: the angular channels convert their deg/s CVar with `π/180`, the height's is yd/s.
 //!
-//! | role | live | start | target | start ms | duration | armed bit | rate CVar |
-//! |---|---|---|---|---|---|---|---|
-//! | pitch | `+0xf4` | `+0x1e4` | `+0x1e0` | `+0x1d8` | `+0x1dc` | `0x2000000` | `cameraPitchSmoothSpeed` `45.0` |
-//! | bias | `+0x104` | `+0x1fc` | `+0x1f8` | `+0x1f0` | `+0x1f4` | `0x8000000` | `cameraTargetSmoothSpeed` `90.0` |
-//! | ground | `+0x108` | `+0x1b4` | `+0x1b0` | `+0x1a8` | `+0x1ac` | `0x10000000` | `cameraGroundSmoothSpeed` `7.5` |
-//! | height | `+0xfc` | `+0x1cc` | `+0x1c8` | `+0x1c0` | `+0x1c4` | `0x20000000` | `cameraHeightSmoothSpeed` `1.2` |
-//!
-//! The armer's contract, byte-derived and identical at all four: shortest-path-rewrap the live
-//! value into `[target − π, target + π]`; **refuse** the request if the channel is already arming
-//! the same `{target, delay, factor}` within `0.001`, or if the live value is already within
-//! `0.001` of the target; otherwise compute `duration = |target − live| / rate · factor` and hand
-//! the tween to the inner. The step is `s = elapsed / duration`, `s ≥ 1` → `live = target`, else
-//! the cosine smoothstep `0x5b7bb0` — `a + (b − a)·(1 − cos πs)/2`.
-//!
-//! **Two things a re-implementation gets wrong.** `+0x1dc`/`+0x1f4`/`+0x1ac`/`+0x1c4` are
-//! **durations in seconds**, not rates — the consumer *divides* elapsed seconds by them; and the
-//! rate is in the **live value's own units**, so the three angular channels convert their deg/s
-//! CVar with `π/180` while the height channel's `1.2` is already yd/s. [`Arm::rate`] is therefore
-//! stated in live-units/s and the conversion belongs to the caller, where the unit is known.
-//!
-//! **The delay is a HOLD here, and the reference's is not** — a named divergence. `0x512830` backs
-//! the start time up by `delay` (`now − (int)(p2 · −1000)`), so `0x50f160`'s `s` goes *negative*
-//! for that long; and because the profile is `cos(π·s)` — an even function — a negative `s`
-//! evaluates the ease as though `|s|`, which makes the live value jump away from `from` at the
-//! instant of arming and walk back. That is an unclamped divide, not an intent, and it is
-//! unreachable at every default this client reads: `Delay` is `0.0` on all thirty rows of the
-//! `cameraTerrainTilt<Style><State>` table, and both the bias and pitch arms pass `0` literally.
-//! benilla holds at `from` until the delay elapses — [`super::camera::FollowRig`] already does
-//! exactly that for the one family whose delay is genuinely nonzero (`Track`/`Fear` under Smart,
-//! `0.4`), so this is the house reading, not a new one.
+//! Deviation: a delay holds the channel at `from`, because the reference's `0x512830` backs the
+//! start time up by the delay, so `s` runs negative and the even cosine jumps the value away and
+//! back, an unclamped divide rather than a behaviour. No default reaches it: every
+//! `cameraTerrainTilt*` row's `Delay` is 0, and the pitch and bias arms pass 0.
 
-/// The channel's "already there / already arming this" epsilon — VERIFIED `0.001` (`[0x801360]`),
-/// shared by all four instantiations and by the `0x5107f0`/`0x5106f0` displacement predicates.
+/// The armer's "already there, already arming this" epsilon, 0.001 at `[0x801360]`, shared by all
+/// four channels and the `0x5107f0`/`0x5106f0` displacement predicates.
 pub(super) const CHANNEL_EPS: f32 = 0.001;
 
-/// What one `arm` call asks for — the armer's four arguments plus the one caller-side clamp.
+/// One `arm` request: the armer's four arguments plus the ground channel's duration clamp.
 #[derive(Clone, Copy, Debug)]
 pub(super) struct Arm {
-    /// Where the channel should end up, in the live value's units.
+    /// In the live value's units.
     pub(super) target: f32,
-    /// Dead time before the tween starts, seconds (the module doc's named divergence).
+    /// Seconds held before the tween starts (the module's deviation).
     pub(super) delay: f32,
-    /// Stretches the duration: `duration = |Δ| / rate · factor`. `1.0` is "at the rate".
     pub(super) factor: f32,
-    /// The channel's rate **in the live value's units per second** — `cvar.to_radians()` for the
-    /// three angular channels, the raw yd/s for the height one.
+    /// Live-value units per second: `cvar.to_radians()` for the angular channels, yd/s for height.
     pub(super) rate: f32,
-    /// The duration bound `(min, max)`, when the caller has one. Only the ground channel does:
-    /// `0x50dd29` clamps `[cam+0x1ac]` to `[Factor × cameraTerrainTiltTimeMin, Factor × …TimeMax]`
-    /// *after* the arm, which is why it is the armer's business and not the tween's.
+    /// The ground channel's bound: after the arm, `0x50dd29` clamps `[cam+0x1ac]` between
+    /// `Factor × cameraTerrainTiltTimeMin` and `Factor × cameraTerrainTiltTimeMax`.
     pub(super) duration: Option<(f32, f32)>,
 }
 
 impl Arm {
-    /// An arm with no delay, no stretch and no duration bound — the shape both the pitch
-    /// (`0x512830(target, 0, 1.0f, now)`) and bias (`0x512a50(cam, 0, 0, 1.0f, now)`) sites pass.
+    /// No delay, factor 1 and no bound, as the pitch (`0x512830`) and bias (`0x512a50`) sites arm.
     pub(super) fn at(target: f32, rate: f32) -> Self {
         Self {
             target,
@@ -75,52 +47,43 @@ impl Arm {
     }
 }
 
-/// A tween in flight — the reference's `{start, target, startMs, duration}` quadruple plus the
-/// `{p2, p3}` staleness memo, with the armed bit expressed as `Option<Flight>` rather than a bit.
+/// A tween in flight: the reference's `{start, target, startMs, duration}` plus its
+/// `{delay, factor}` memo; `Some` is the armed bit.
 #[derive(Clone, Copy, Debug)]
 struct Flight {
-    /// Seconds since the arm, and the dead time in front of the tween.
+    /// Seconds since the arm; `delay` is the hold in front of the tween.
     elapsed: f32,
     delay: f32,
-    /// The tween's own length, seconds — never a rate.
     duration: f32,
-    /// What it was armed with (`+0x1ec`/`+0x1e8`), so a repeat asking for the same move is a
-    /// no-op instead of restarting it from its own midpoint.
+    /// The armed `(delay, factor)` (`+0x1ec`/`+0x1e8`), so a repeated request is not a restart.
     memo: (f32, f32),
 }
 
-/// One smoothed scalar channel of the camera — see the module doc.
-///
-/// `Default` is the **linear** channel, because the one instantiation whose live value is not an
-/// angle is the pivot height (yards) — see [`SmoothChannel::angular`].
+/// One smoothed camera scalar. `Default` is linear, for the pivot height in yards;
+/// [`SmoothChannel::angular`] is the other three.
 #[derive(Clone, Copy, Debug, Default)]
 pub(super) struct SmoothChannel {
     live: f32,
     from: f32,
     to: f32,
     flight: Option<Flight>,
-    /// Does the armer's shortest-path rewrap apply? It is a **`2π` rewrap**, so it is meaningful
-    /// only on the three channels whose live value is an angle in radians; running it on the
-    /// height channel would fold yards around a circle.
+    /// Whether the armer's `2π` shortest-path rewrap applies: radians only, never yards.
     wrap: bool,
 }
 
-/// What an [`SmoothChannel::arm`] did — the reference's own three-way return, kept because the
-/// callers branch on it (`0x512a50` returns 1 for "already arming this", 0 for "already there").
+/// What [`SmoothChannel::arm`] did: the reference's three-way return (`0x512a50` returns 1 for
+/// already arming, 0 for already there).
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum Armed {
-    /// A tween was started.
     Started,
-    /// The channel is already arming this exact request — nothing changed.
+    /// Already arming this exact request; nothing changed.
     Already,
-    /// The live value is already within [`CHANNEL_EPS`] of the target — nothing changed, and
-    /// nothing is in flight afterwards either.
+    /// Already within [`CHANNEL_EPS`] of the target; nothing is in flight afterwards.
     AtRest,
 }
 
 impl SmoothChannel {
-    /// An **angular** channel — pitch, pitch-bias or ground tilt, whose live value is radians and
-    /// whose armer therefore rewraps it into `[target − π, target + π]` (`0x512abe`).
+    /// A radians channel (pitch, bias, ground tilt), which the armer rewraps (`0x512abe`).
     pub(super) fn angular() -> Self {
         Self {
             wrap: true,
@@ -128,20 +91,18 @@ impl SmoothChannel {
         }
     }
 
-    /// The value the camera uses this frame.
     pub(super) fn live(&self) -> f32 {
         self.live
     }
 
-    /// Is a tween in flight? (The reference's armed bit of `[cam+0x90]`.)
+    /// The reference's armed bit in `[cam+0x90]`.
     pub(super) fn in_flight(&self) -> bool {
         self.flight.is_some()
     }
 
-    /// Establish the channel at `v` with nothing in flight — the reference's **hard snap**, which
-    /// is a real leg of two of the four: the water band-crossing writes `[cam+0xf4]` *and*
-    /// `[cam+0x1e0]` directly when `[cam+0x90] & 1` (`0x50ed13`), and the height channel's first
-    /// arm of a camera's life snaps (`0x5127d4`).
+    /// Sets the channel to `v` with nothing in flight, the reference's hard snap: the water band
+    /// crossing writes the pitch's live `[cam+0xf4]` and target `[cam+0x1e0]` directly while
+    /// `[cam+0x90] & 1` (`0x50ed13`), and a camera's first height arm snaps (`0x5127d4`).
     pub(super) fn snap(&mut self, v: f32) {
         self.live = v;
         self.from = v;
@@ -149,11 +110,9 @@ impl SmoothChannel {
         self.flight = None;
     }
 
-    /// The armer (`0x512830`/`0x512a50`/`0x512490`/`0x5126b0`), in its own order.
+    /// The armer, in the reference's order.
     pub(super) fn arm(&mut self, arm: &Arm) -> Armed {
-        // The shortest-path rewrap: the live value is brought into `[target − π, target + π]`
-        // first, so a channel that has accumulated past a half-turn takes the short way round
-        // (`0x512abe fst` — it is stored back, not merely used for the compare).
+        // The rewrap is stored back, not only compared (`0x512abe`).
         if self.wrap {
             let two_pi = std::f32::consts::TAU;
             while self.live - arm.target > std::f32::consts::PI {
@@ -173,8 +132,7 @@ impl SmoothChannel {
         }
         let gap = (arm.target - self.live).abs();
         if gap < CHANNEL_EPS {
-            // Already there: park the target and disarm. This is the steady-state path, and it is
-            // what makes arming every frame identical to arming on change.
+            // Park the target and disarm, so arming every frame equals arming on change.
             self.to = arm.target;
             self.flight = None;
             return Armed::AtRest;
@@ -194,8 +152,7 @@ impl SmoothChannel {
         Armed::Started
     }
 
-    /// Step whatever is in flight and return the live value — `0x50f160`'s block, shared by all
-    /// four channels.
+    /// Steps the tween and returns the live value (`0x50f160`'s block).
     pub(super) fn advance(&mut self, dt: f32) -> f32 {
         if let Some(f) = self.flight.as_mut() {
             f.elapsed += dt;
@@ -206,7 +163,6 @@ impl SmoothChannel {
                     self.live = self.to;
                     self.flight = None;
                 } else {
-                    // `0x5b7bb0` — the cosine smoothstep, eased at both ends.
                     let e = (1.0 - (std::f32::consts::PI * s).cos()) * 0.5;
                     self.live = self.from + (self.to - self.from) * e;
                 }
@@ -215,24 +171,14 @@ impl SmoothChannel {
         self.live
     }
 
-    /// `(live, target)` — what a `WOW_CAM_DUMP` line prints. A channel question is a *timing*
-    /// question, and these two columns are how a trace answers it (method: timing is measured).
+    /// `(live, target)`, the columns of a `WOW_CAM_DUMP` line.
     pub(super) fn probe(&self) -> (f32, f32) {
         (self.live, self.to)
     }
 }
 
-/// **Sweep a regime switch and bound its step** — the check decision 2165 exists because this tree
-/// did not have one.
-///
-/// A mechanism that switches between *regimes* — liquid bands, a slope staircase, a state ladder,
-/// an eligibility gate — is not verified by point assertions inside each regime. Those are
-/// structurally blind to a cliff *between* them, which is how a pivot corridor that moved the
-/// camera's framing point 1.04 yd in one frame shipped behind five green tests, each correct.
-/// Walk the parameter across every boundary instead and bound the step.
-///
-/// Where a jump is intended, `max_jump` is where its size gets **written down** — which is the
-/// second reason to reach for this rather than eyeball a sweep: the bound is the claim.
+/// Walks `f` from `from` to `to` in `step`s and asserts no step moves the output more than
+/// `max_jump`: point tests inside each regime cannot see a cliff between regimes.
 #[cfg(test)]
 pub(super) fn assert_bounded_step(
     (from, to): (f32, f32),
@@ -269,8 +215,6 @@ mod tests {
             .collect()
     }
 
-    /// The template's duration law is `|Δ| / rate · factor`, and it is a **duration**, not a rate:
-    /// the tween takes exactly that long and the value arrives only at its end.
     #[test]
     fn the_duration_is_the_gap_over_the_rate_times_the_factor() {
         for (gap, rate, factor) in [
@@ -304,9 +248,6 @@ mod tests {
         }
     }
 
-    /// Arming every frame with a steady target is exactly arming once — the property the whole
-    /// per-frame-arm design rests on. A memo that only compared the target would still restart the
-    /// tween whenever the *factor* changed, so both are in the compare.
     #[test]
     fn a_per_frame_re_arm_neither_restarts_nor_stretches_the_tween() {
         let mut once = SmoothChannel::default();
@@ -320,15 +261,12 @@ mod tests {
             assert_eq!(every.arm(&arm), Armed::Already);
             assert_eq!(every.advance(dt), once.advance(dt));
         }
-        // …and once it is there, the re-arm reports rest rather than starting a zero move.
         run(&mut once, 1.5);
         run(&mut every, 1.5);
         assert_eq!(every.arm(&arm), Armed::AtRest);
         assert!(!every.in_flight());
     }
 
-    /// The rewrap takes the short way round: a channel sitting just under `+π` asked for a target
-    /// just over `−π` travels the small gap, not the long one.
     #[test]
     fn the_arm_rewraps_the_live_value_to_the_short_side() {
         let mut c = SmoothChannel::angular();
@@ -348,16 +286,14 @@ mod tests {
         assert!(frames
             .iter()
             .all(|v| *v >= wrapped - CHANNEL_EPS && *v <= target + CHANNEL_EPS));
-        // …and a LINEAR channel of the same numbers does not wrap: it travels the long way,
-        // because yards are not radians.
+        // A linear channel with the same numbers does not wrap: it travels the long way.
         let mut linear = SmoothChannel::default();
         linear.snap(3.1);
         linear.arm(&Arm::at(target, 1.0));
         assert!(run(&mut linear, 0.5).iter().any(|v| *v > 0.0));
     }
 
-    /// The delay holds at the start value and then runs the full tween — the module doc's named
-    /// divergence, pinned so it cannot silently become the reference's negative-`s` jump.
+    /// The module's deviation, pinned against the reference's negative-`s` jump.
     #[test]
     fn a_delay_holds_the_channel_before_the_tween_rather_than_jumping_it() {
         let mut c = SmoothChannel::default();
@@ -374,7 +310,6 @@ mod tests {
         assert!((frames[frames.len() - 1] - 1.0).abs() < CHANNEL_EPS);
     }
 
-    /// The ground channel's own clamp (`0x50dd29`): the duration, not the rate, is bounded.
     #[test]
     fn a_duration_bound_clamps_the_tween_not_the_gap() {
         let mut c = SmoothChannel::default();
diff --git a/crates/benilla-app/src/player/camera_dynamics.rs b/crates/benilla-app/src/player/camera_dynamics.rs
index c4ad7913..c11154c7 100644
--- a/crates/benilla-app/src/player/camera_dynamics.rs
+++ b/crates/benilla-app/src/player/camera_dynamics.rs
@@ -1,110 +1,66 @@
-//! **The 1.12 camera option toggles** — the four `UIOptionsFrame` checkboxes `FOLLOW_TERRAIN` /
-//! `HEAD_BOB` / `SMART_PIVOT` / `WATER_COLLISION` and the mechanisms behind them (decision 2149).
+//! The mechanisms behind the four `UIOptionsFrame` camera checkboxes (`UIOptionsFrame.lua:32-35`).
 //!
-//! 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.
-//!
-//! **The sign convention is the one thing to keep straight.** The reference's pitch is positive
-//! **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
-//! therefore transcribed with its comparison flipped, and the flip is written out at each site
-//! rather than hidden in a conversion, because a silently mirrored inequality is the failure mode
-//! this file exists to avoid.
+//! The reference's pitch is positive downward (`0x511f40`, `0x50de00`), benilla's
+//! [`super::camera::FlyCam::pitch`] positive upward, so every reference comparison is flipped.
 
 use bevy::prelude::*;
 
 use super::camera_channel::{Arm, SmoothChannel, CHANNEL_EPS};
 
-/// `cameraPivotDXMax`'s registered default — radians of **yaw** per motion event, above which a
-/// drag is not "mostly vertical" any more (`0.05` ≈ 2.86°, `[0xbe0f30]`).
+/// `cameraPivotDXMax` default (`[0xbe0f30]`): the yaw per motion event a vertical drag stays under.
 pub(crate) const PIVOT_DX_MAX_DEFAULT: f32 = 0.05;
-/// `cameraPivotDYMin`'s registered default — radians of **pitch** below which a drag does not
-/// engage the pivot at all (`0.0`, `[0xbe0cec]`: any vertical motion qualifies).
+/// `cameraPivotDYMin` default (`[0xbe0cec]`): the pitch per motion event a pivot drag exceeds.
 pub(crate) const PIVOT_DY_MIN_DEFAULT: f32 = 0.0;
-/// `cameraTargetSmoothSpeed`'s registered default, deg/s — the rate the pitch bias eases back to
-/// zero at once the pivot lets go (`90.0`, `[0xbe0fc8]`).
+/// `cameraTargetSmoothSpeed` default, deg/s (`[0xbe0fc8]`): the rate the pivot bias eases home at.
 pub(crate) const TARGET_SMOOTH_SPEED_DEFAULT: f32 = 90.0;
 
-/// `cameraGroundSmoothSpeed`'s registered default, deg/s — `[0xbe0fc0]`, `"7.5"`.
+/// `cameraGroundSmoothSpeed` default, deg/s (`[0xbe0fc0]`).
 pub(crate) const GROUND_SMOOTH_SPEED_DEFAULT: f32 = 7.5;
-/// `cameraTerrainTiltTimeMin`'s registered default, seconds — `[0xbe1050]`, `"3.0"`.
+/// `cameraTerrainTiltTimeMin` default, seconds (`[0xbe1050]`).
 pub(crate) const TILT_TIME_MIN_DEFAULT: f32 = 3.0;
-/// `cameraTerrainTiltTimeMax`'s registered default, seconds — `[0xbe1054]`, `"10.0"`.
+/// `cameraTerrainTiltTimeMax` default, seconds (`[0xbe1054]`).
 pub(crate) const TILT_TIME_MAX_DEFAULT: f32 = 10.0;
 
-/// `cameraBobbingLRAmplitude` / `cameraBobbingUDAmplitude`'s registered default — `[0xbe1064]` /
-/// `[0xbe10c8]`, both `"2.0"`. Scaled by [`BOB_AMPLITUDE_SCALE`] to yards.
+/// `cameraBobbingLRAmplitude`/`UDAmplitude` default, inches (`[0xbe1064]`, `[0xbe10c8]`).
 pub(crate) const BOB_AMPLITUDE_DEFAULT: f32 = 2.0;
-/// `cameraBobbingFrequency`'s registered default, Hz at unit speed factor — `[0xbe0cf8]`, `"0.8"`.
+/// `cameraBobbingFrequency` default, Hz at a unit speed factor (`[0xbe0cf8]`).
 pub(crate) const BOB_FREQUENCY_DEFAULT: f32 = 0.8;
-/// `cameraBobbingSmoothSpeed`'s registered default — `[0xbe10bc]`, `"0.8"`. **Not a bob rate**: it
-/// is the DECAY rate, and its one image-wide read is in the disarm (`0x51113a`).
+/// `cameraBobbingSmoothSpeed` default (`[0xbe10bc]`): the decay rate, read only by the disarm.
 pub(crate) const BOB_SMOOTH_SPEED_DEFAULT: f32 = 0.8;
-/// What the two amplitude CVars are in — `[0x7ff9d0] = 1/36`. The columns are inches; yards out.
+/// Inches to yards for the amplitude CVars (`[0x7ff9d0]`).
 const BOB_AMPLITUDE_SCALE: f32 = 1.0 / 36.0;
-/// The speed the bob's rate factor is measured against — `[0x808a08] = 7.2` yd/s.
+/// The speed the bob's rate factor divides by, yd/s (`[0x808a08]`).
 const BOB_SPEED_DIVISOR: f32 = 7.2;
-/// The rate factor's clamp — `[0x8089a0] = 0.5` (LOWER) and `[0x80899c] = 1.5` (upper). **Stored in
-/// the order a reader would not assume**: the lower bound sits at the higher address, and it is the
-/// substituting block at `0x5119be`, not the address order, that says which is which.
+/// The rate factor's clamp, `[0x8089a0]` and `[0x80899c]`: the lower bound is the higher address.
 const BOB_SPEED_CLAMP: (f32, f32) = (0.5, 1.5);
-/// Head bob's first conjunct — `[cam+0xec] <= [0x8089ac] = 1/6`, INCLUSIVE. It is a compare on the
-/// ZOOM distance, so "first person" here is the wheel being all the way in, not the renderer's own
-/// first-person switch (`dist − [cam+0x38] <= 1/360`).
+/// Head bob's inclusive first-person test, on the zoom distance (`[cam+0xec] <= [0x8089ac]`).
 pub(crate) const BOB_FIRST_PERSON_DISTANCE: f32 = 1.0 / 6.0;
 
-/// The camera option knobs — the CVar-backed half of this module (decision 1804: each default is
-/// the reference's registrar value, and [`crate::cvars`] carries the provenance per row).
+/// The camera option CVars; each default is the reference's registered value.
 #[derive(Resource, Clone, Copy, Debug)]
 pub(crate) struct CameraOptions {
-    /// `cameraPivot` — registered **"1"**, so this is ON out of the box and benilla was the
-    /// divergence until it was built.
     pub(crate) pivot: bool,
-    /// `cameraPivotDXMax` — see [`PIVOT_DX_MAX_DEFAULT`].
     pub(crate) pivot_dx_max: f32,
-    /// `cameraPivotDYMin` — see [`PIVOT_DY_MIN_DEFAULT`].
     pub(crate) pivot_dy_min: f32,
-    /// `cameraTargetSmoothSpeed` — see [`TARGET_SMOOTH_SPEED_DEFAULT`].
     pub(crate) target_smooth_speed: f32,
-    /// `cameraTerrainTilt` — registered **"0"**, so Follow Terrain is OFF out of the box.
     pub(crate) terrain_tilt: bool,
-    /// `cameraGroundSmoothSpeed`, deg/s — the ground channel's rate (`[0xbe0fc0]`, `"7.5"`).
     pub(crate) ground_smooth_speed: f32,
-    /// `cameraTerrainTiltTimeMin`/`Max`, seconds — the ground channel's duration bound, each
-    /// scaled by the row's `Factor` (`[0xbe1050]`/`[0xbe1054]`, `"3.0"`/`"10.0"`).
+    /// `cameraTerrainTiltTimeMin`/`Max`, seconds, each scaled by the matrix row's `Factor`.
     pub(crate) tilt_time_min: f32,
     pub(crate) tilt_time_max: f32,
-    /// `cameraBobbing` — registered **"0"**, so head bob is OFF out of the box.
     pub(crate) bobbing: bool,
-    /// `cameraBobbingLRAmplitude` / `cameraBobbingUDAmplitude`, in the CVars' own units.
     pub(crate) bob_lr_amplitude: f32,
     pub(crate) bob_ud_amplitude: f32,
-    /// `cameraBobbingFrequency`.
     pub(crate) bob_frequency: f32,
-    /// `cameraBobbingSmoothSpeed` — the DECAY rate, see [`BOB_SMOOTH_SPEED_DEFAULT`].
     pub(crate) bob_smooth_speed: f32,
-    /// **`cameraWaterCollision`** — registered **"1"** (`0x50bd63`, default string `0x82e748`), so
-    /// this is ON out of the box.
-    ///
-    /// **It is one CVar with two consumers, and shipping either alone is a visible defect.** The
-    /// read at `0x50e5ec` produces one register: its `0xf0000` nibble rides the trace mask to all
-    /// three of `0x50e570`'s queries (the boom hits a bare waterline), and `0x50e629` tests the
-    /// *same* register to admit the pivot floor/cap block ([`super::camera_water`]).
-    ///
-    /// This tree has shipped each half on its own and broken the camera both times — 2149 the
-    /// corridor without the trace, 2170 the trace without the corridor (2173 §1: a surface
-    /// swimmer's pivot sits 11 mm under the plane, so the boom straddles it every frame). The two
-    /// are inseparable: the corridor's surface arm is what lifts the sweep origin to
-    /// `surface + 2/9`, clear of the geometry the mask just switched on.
+    /// `cameraWaterCollision`: one read (`0x50e5ec`) adds liquid to the sweeps' trace mask and
+    /// admits the pivot floor and cap block (`0x50e629`, [`super::camera_water`]). Neither works
+    /// alone: that block lifts the sweep origin to `surface + 2/9`, clear of the solid waterline.
     pub(crate) water_collision: bool,
 }
 
-/// The camera options' change callback (2149, 2303). The numeric rows take the value
-/// straight: the reference's own validator on them is `0x50b330`'s range REFUSAL, which is the
-/// camera-speed rows' business ([`super::camera::on_cvar`]), not these.
+/// Applies a camera option CVar change. The numeric rows take any value, where the reference's
+/// `0x50b330` refuses an out-of-range smooth speed, tilt time or bob frequency.
 pub(crate) fn on_cvar(ev: On<crate::cvars::CvarChanged>, mut opts: ResMut<CameraOptions>) {
     let v = ev.num();
     match ev.key().as_str() {
@@ -147,124 +103,64 @@ impl Default for CameraOptions {
     }
 }
 
-/// The camera-dynamics inputs one frame hands the rig — the knobs, plus the facts about the
-/// *followed unit* that the mechanisms' gates need and the camera does not hold.
+/// One frame's camera-dynamics inputs: the options, and the followed unit's facts the gates read.
 #[derive(Clone, Copy, Debug)]
 pub(super) struct DynamicsInput {
     pub(super) options: CameraOptions,
-    /// `cameraSmoothStyle` **raw** — the terrain-tilt matrix indexes the un-remapped value
-    /// (`0x50dbc0`), so this is the knob and not the auto-follow's own
-    /// far-sight-adjusted copy.
+    /// Raw `cameraSmoothStyle`, which the tilt matrix indexes (`0x50dbc0`), not the follow's copy.
     pub(super) smooth_style: super::camera::FollowStyle,
-    /// `cameraSmoothTrackingStyle` — read by exactly one thing here, [`SmartPivot::advance`]'s
-    /// third release conjunct (`0x511010`). Separate from `smooth_style` because the reference
-    /// keeps two registrations (`[0xbe10c4]` vs `[0xbe1098]`) off the same default pointer.
+    /// `cameraSmoothTrackingStyle`, read only by the pivot release's third conjunct (`0x511010`).
     pub(super) tracking_style: super::camera::FollowStyle,
     pub(super) subject: SubjectState,
-    /// The live `nearclip` ([`benilla_world::view::ViewDistance::nearclip`]) — the self-avatar
-    /// fade's reference plane, carried on this bundle rather than as a fourteenth `seat_camera`
-    /// argument. It rides here because it is a camera CVar reaching a camera kernel, which is what
-    /// this struct is for (2163).
     pub(super) nearclip: f32,
-    /// **The liquid surface over the driven body's feet** (Bevy-Y), as the last movement tick
-    /// cached it — [`crate::player::state::Player::liquid_surface`]. Feeds
-    /// [`super::camera_water::classify`], the half of `cameraWaterCollision` that is not the trace
-    /// mask.
-    ///
-    /// Our own body's, so it is `None`-equivalent for a far-sight subject: `0x511ad0` reads the
-    /// camera TARGET's liquid object, and `view_subject` carries no movement state for a watched
-    /// unit — the same gap the swim framing preset has, recorded rather than papered over. A
-    /// totem watched across a lake gets the dry-land corridor.
+    /// The liquid surface over our own feet (Bevy Y), cached by the last movement tick. Unused
+    /// under far sight: the reference reads the watched unit's liquid (`0x511ad0`), absent here.
     pub(super) surface_y: Option<f32>,
 }
 
-/// What the four mechanisms' gates need to know about the **followed unit** — the conjuncts that
-/// are facts about the body rather than about the camera or a CVar. The movement word is the one
-/// the last update left, which is what the reference's own input handler reads (`0x50fee0`'s sole
-/// caller `0x514446` precedes the mover lookup).
+/// The followed unit's side of the gates. The movement word is last frame's, as the reference's
+/// input handler reads it (`0x50fee0`'s caller `0x514446` runs before the mover lookup).
 #[derive(Clone, Copy, Debug, Default)]
 pub(super) struct SubjectState {
-    /// This frame's `MOVEMENTFLAGS`, verbatim — the three mechanisms that read it read *different*
-    /// masks of the same word, so it is carried whole rather than pre-reduced to booleans.
+    /// `MOVEMENTFLAGS`, whole: the mechanisms read different masks of it.
     pub(super) move_flags: u32,
-    /// `UNIT_FIELD_FLAGS & 0x100000`, the taxi-flight bit — the terrain-tilt classifier's
-    /// highest-priority state (and head bob's ninth conjunct, when that lands).
+    /// `UNIT_FIELD_FLAGS & 0x100000`, taxi flight.
     pub(super) taxi: bool,
-    /// The camera's `Track` bit (`[cam+0x90] & 0x100`) — externally-driven movement.
+    /// The camera's `Track` bit (`[cam+0x90] & 0x100`): externally driven movement.
     pub(super) track: bool,
-    /// The camera's `Fear` bit (`[cam+0x90] & 0x1000`) — external control.
+    /// The camera's `Fear` bit (`[cam+0x90] & 0x1000`): external control.
     pub(super) fear: bool,
-    /// The subject's facing, radians in benilla's yaw convention — the direction terrain tilt
-    /// probes along, and the frame head bob's lateral sway is written in (`[obj+0xc98]`).
+    /// Facing, radians, in benilla's yaw convention (`[obj+0xc98]`).
     pub(super) facing: f32,
-    /// `UNIT_FIELD_MOUNTDISPLAYID > 0` — head bob's eighth conjunct.
+    /// `UNIT_FIELD_MOUNTDISPLAYID > 0`.
     pub(super) mounted: bool,
-    /// The mover's current speed in yd/s — `GetCurrentSpeed 0x7c4c90`, which benilla already has
-    /// as [`crate::net::current_speed`]. Head bob's rate factor is `clamp(speed / 7.2, [0.5,1.5])`.
+    /// Current speed, yd/s (`GetCurrentSpeed`, `0x7c4c90`).
     pub(super) speed: f32,
-    /// The camera's input-command word ([`super::camera::follow_cmd`]) — head bob's ARM is an edge
-    /// on this and nothing else (`0x511170`'s two callers).
+    /// The input-command word ([`super::camera::follow_cmd`]); its edges arm head bob (`0x511170`).
     pub(super) command: u32,
-    /// Is the spyglass scope up? `[cam+0x90] & 0x8`, the aura-76 (`SPELL_AURA_FAR_SIGHT`) FOV lock
-    /// — head bob's fourth conjunct.
+    /// The aura-76 FOV lock of the spyglass scope (`[cam+0x90] & 0x8`).
     pub(super) scoped: bool,
 }
 
 impl SubjectState {
-    /// `MOVEMENTFLAGS & 0xf` — MOVE (`0x1|0x2`) plus STRAFE (`0x4|0x8`). **TURN (`0x10|0x20`) is
-    /// deliberately not in the mask** (`0x5106b7`'s byte-lane `test byte ptr [eax+0x40],0xf`), so
-    /// turning in place still passes `cameraPivot`'s fourth conjunct.
+    /// `MOVEMENTFLAGS & 0xf`, move and strafe: turning in place is not translating (`0x5106b7`).
     pub(super) fn translating(&self) -> bool {
         self.move_flags & (mf::FORWARD | mf::BACKWARD | mf::STRAFE_LEFT | mf::STRAFE_RIGHT) != 0
     }
 }
 
-/// The movement-flag bits these gates read, by the names the wire uses
-/// ([`crate::creature_anim::move_flags`] is the one definition; re-exported here so the predicates
-/// below read as the reference's masks do).
 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*.
+/// `cameraPivot`, smart pivot: a camera the collision solver pinned tilts its view, through a bias
+/// channel (`[cam+0x104]`), instead of swinging its arm. The gate `0x510690` returns the solver's
+/// clip flags (`[cam+0x90] & 0x30000`), so only a camera clipped this frame pivots. The eye is
+/// seated from the unbiased pitch (`0x50ee32`-`0x50ee58`); the body's aim is the sum (`0x5103e0`).
 ///
-/// 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 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
-///   calling the ordinary pitch integrator `0x510120`. The clamp on that accumulate is a
-///   **one-sided floor** at `−89° − [cam+0xf4]`, applied only while `[cam+0xf4] < 0`; the
-///   symmetric ±89° pair belongs to the integrator, not here.
-/// - **The sink.** The driver computes the eye from the *unbiased* pitch
-///   (`0x50edcc → 0x50de00`, stored to `[cam+0x08..0x10]`) and only **then** rotates the camera
-///   basis at `[cam+0x14]` by the bias (`0x50ee32`–`0x50ee58`, `0x7be730` about `[0xbe0f20]` =
-///   `(0,1,0)`, skipped entirely while `|bias| < 0.001`). That ordering *is* the feature: the seat
-///   does not move and the look direction does. Corroborated by `0x5103e0`, the camera→body
-///   hand-off, which clamps **`[cam+0x104] + [cam+0xf4]`** to ±89° before passing the pitch on —
-///   i.e. the player's aim is the composite.
-/// - **The release `0x5107f0`**, run per frame from the driver at `0x50ed77`:
-///   `|bias| ≥ 0.001 ∧ 0x511010(cam) == 0 ∧ ¬gate` (the last negated) arms `+0x104` back to zero at
-///   `cameraTargetSmoothSpeed`; a false verdict snapshots and disarms instead.
-///
-/// **The third release conjunct, `0x511010`**, decoded: `[cam+0x90] & 0x100` — the camera's TRACK
-/// latch, the same bit that picks the tilt matrix's `Track` row, fed from `[inputState+4] &
-/// 0xf00000` (externally-driven movement, which is benilla's `server_riding`) — and then, only if
-/// that is set, `cameraSmoothTrackingStyle == Never` OR a move-type-**0** order in flight. A true
-/// answer BLOCKS the ease home, holding the bias while a tracking swing runs.
-///
-/// benilla builds the first disjunct and cannot build the second: `[0xc4d888]` is the
-/// click-to-move / auto-action move-type global, and this client has no click-to-move to put an
-/// order in flight. That half is inert at every state benilla can reach, so it is named here
-/// rather than stubbed — the day click-to-move exists, this is the line that needs the arm.
+/// The release's `0x511010` holds the bias while the Track latch is up and tracking is Never, or
+/// a move-type-0 click-to-move order is in flight (`[0xc4d888]`); benilla has no click-to-move,
+/// so only the first is built.
 pub(super) struct SmartPivot {
-    /// The pitch-bias channel `+0x104` — angular, so the armer's `2π` rewrap applies. Its armed
-    /// bit is the reference's `[cam+0x90] & 0x8000000`, which is read as a routing conjunct.
+    /// The bias channel `[cam+0x104]`; its armed bit is the reference's `[cam+0x90] & 0x8000000`.
     bias: SmoothChannel,
 }
 
@@ -277,24 +173,14 @@ impl Default for SmartPivot {
 }
 
 impl SmartPivot {
-    /// The bias the view is carrying this frame, radians, **benilla's sign** (positive = the view
-    /// tilted further up). Added to the pitch for the camera's *rotation* and for the body pitch
-    /// hand-off — never for the seat.
+    /// The bias, radians, positive up: part of the view and the body's aim, never the seat's.
     pub(super) fn bias(&self) -> f32 {
         self.bias.live()
     }
 
-    /// `0x50fee0`'s pitch routing, for one motion event.
+    /// `0x50fee0`'s pitch routing: the integrator's delta, or `None` on a pure-pivot frame.
     ///
-    /// Takes this event's pitch and yaw deltas (radians, benilla sign) and the camera's live pitch,
-    /// and answers **the pitch delta the ordinary integrator should apply** — `None` on the
-    /// reference's *pure-pivot frame*, where neither the ease nor the integrator runs and the drag
-    /// lives entirely in the bias.
-    ///
-    /// The three legs are the reference's, transcribed with every comparison flipped for benilla's
-    /// upward-positive pitch (see the module doc):
-    ///
-    /// | reference | here |
+    /// | reference | here (sign flipped) |
     /// |---|---|
     /// | `[cam+0xf4] < 0` (looking up) | `pitch > 0` |
     /// | floor `bias ≥ −89° − f4` | ceiling `bias ≤ +89° − pitch` |
@@ -308,38 +194,32 @@ impl SmartPivot {
         clipped: bool,
         cfg: &CameraOptions,
     ) -> Option<f32> {
-        // `0x510690`, conjuncts 3-6. (1 and 2 — a non-null UNIT-or-PLAYER subject — are structural
-        // here: the rig only ever follows one.)
+        // `0x510690`'s conjuncts 3-6; 1 and 2, a UNIT or PLAYER subject, always hold here.
         let verdict = cfg.pivot && !subject.translating() && pitch >= 0.0 && clipped;
-        // The selector `ecx`: an already-displaced bias with the ease NOT armed keeps routing, or
-        // a fresh verdict with a mostly-vertical drag starts it.
+        // A displaced bias with no ease armed keeps routing; a gated vertical drag starts it.
         let displaced = !self.bias.in_flight() && self.bias().abs() >= CHANNEL_EPS;
         let vertical_drag =
             verdict && d_pitch.abs() > cfg.pivot_dy_min && d_yaw.abs() < cfg.pivot_dx_max;
         if displaced || vertical_drag {
             let mut bias = self.bias() + d_pitch;
-            // The one-sided clamp: only while the camera is looking up, and only on the side that
-            // would take the composite past the pitch limit.
+            // One-sided: only while looking up, and only toward the pitch limit.
             if pitch > 0.0 {
                 bias = bias.min(super::camera::CAM_PITCH_LIMIT - pitch);
             }
             self.bias.snap(bias);
             if bias >= 0.0 && pitch > 0.0 {
-                // The pure-pivot frame (`0x5100c3`): the bias stands, the ease is disarmed, and
-                // the ordinary pitch integrator does not run at all.
+                // The pure-pivot frame (`0x5100c3`): the integrator does not run.
                 return None;
             }
         }
-        // The ordinary path (`0x51009a`): start the bias easing back to zero, then integrate the
-        // pitch as usual. Reached with the increment above already standing when the selector
-        // fired — the reference applies the delta to BOTH on this leg, and the ease then walks the
-        // bias off while the pitch keeps it.
+        // The ordinary path (`0x51009a`). After a routed delta it lands in both, as in the
+        // reference, and the ease walks it off the bias.
         self.release(cfg);
         Some(d_pitch)
     }
 
-    /// The per-frame half (`0x50ed77` → `0x5107f0`): with the gate false and the bias displaced,
-    /// ease it back to zero; otherwise hold it where it is. Then step whatever is in flight.
+    /// Per frame (`0x50ed77` → `0x5107f0`): a false gate eases a displaced bias home, a true one
+    /// holds it.
     pub(super) fn advance(
         &mut self,
         pitch: f32,
@@ -350,79 +230,39 @@ impl SmartPivot {
         dt: f32,
     ) {
         let verdict = cfg.pivot && !subject.translating() && pitch >= 0.0 && clipped;
-        // `0x511010`'s first disjunct — the TRACK latch up with tracking set to `Never`. A true
-        // answer blocks the ease home, so it joins the gate on the holding side rather than
-        // forming a third arm.
+        // `0x511010`'s first disjunct: tracking at Never holds the bias as the gate does.
         let tracking_hold = subject.track && tracking_style == super::camera::FollowStyle::Never;
         let holding = verdict || tracking_hold;
         if !holding && self.bias().abs() >= CHANNEL_EPS {
             self.release(cfg);
         } else if holding {
-            // The FALSE leg of `0x5107f0`'s caller (`0x50ed93`): snapshot and clear the armed bit,
-            // i.e. a re-engaged gate cancels an ease in flight rather than fighting it.
+            // `0x50ed93`: a held gate snapshots the bias and disarms, cancelling an ease in flight.
             let live = self.bias();
             self.bias.snap(live);
         }
         self.bias.advance(dt);
     }
 
-    /// `0x512a50(cam, target = 0, 0, 1.0f, now)` — arm the bias back to zero at
-    /// `cameraTargetSmoothSpeed`. A no-op when it is already there (the armer's own epsilon).
+    /// Arms the bias home at `cameraTargetSmoothSpeed` (`0x512a50(cam, 0, 0, 1.0f, now)`).
     fn release(&mut self, cfg: &CameraOptions) {
         self.bias
             .arm(&Arm::at(0.0, cfg.target_smooth_speed.to_radians()));
     }
 }
 
-/// **`cameraTerrainTilt` — "Follow Terrain"**: the camera pitches with the ground the character is
-/// walking onto, so cresting a hill does not put the view into the dirt.
-///
-/// 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:
-///
-/// **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
-/// hit pulled back `5/18`; then a `64/9` drop straight down from wherever that landed. The `5/3`
-/// is a probe LIFT, added going in and cancelled coming out, so the whole thing reduces to
-/// `slope = (groundY_ahead − feet.y) / horizontal_run` — rise over run, ahead of you. A missed
-/// horizontal ray means the full reach; a missed drop means `−64/9`, a slope of about `−1.78`,
-/// which the staircase and the clamp turn into the full downward tilt: **walking off a cliff edge
-/// pitches the camera all the way down**, which is the behaviour and not an accident. Throttled to
-/// 100 ms, and on a throttled frame the previous value STANDS (`0x50d956 js` leaves `[cam+0xa0]`
-/// alone) — only a failed gate zeroes it.
-///
-/// **The staircase (`0x808a40`), which is not a curve.** Ten `{key, angle}` records walked
-/// *downward* from index 9, taking the first `|slope| >= key` — a nearest-below step with no
-/// interpolation. The keys are `round(tan(5k°), 2)` and the angles `5k°`; but the ±20° clamp that
-/// follows equals record 4 exactly, and the table has one consumer image-wide, so **records 5–9
-/// are unreachable** and the shipped map is five steps: `0 / 5 / 10 / 15 / 20°` at
-/// `|slope| >= 0 / 0.09 / 0.18 / 0.27 / 0.36`. Uphill is a NEGATIVE angle in the reference, i.e.
-/// the camera looks up — which is `+` here (module doc).
-///
-/// **The arm (`0x50dbc0`)**, which is where `cameraSmoothStyle` gets a second job: a 10-state
-/// movement classifier indexes a `style × state` matrix of `{Absorb, Delay, Factor}`, the probe's
-/// angle is scaled by `Absorb`, and `Factor` decides what happens — negative is an explicit
-/// **disable sentinel** (the channel holds where it is), otherwise the ground channel `+0x108`
-/// arms toward `Absorb × angle`. The duration is clamped to `[3·Factor, 10·Factor]` seconds by
-/// `cameraTerrainTiltTimeMin`/`Max`, and since `20° / 7.5°/s` is only 2.67 s **that floor always
-/// binds**: every tilt takes at least three seconds. It is a lazy, deliberate lean, not a
-/// 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.
+/// `cameraTerrainTilt`, follow terrain: the camera pitches toward the slope of the ground ahead.
+/// The probe `0x50d900` reads its rise over run every 100 ms (a missed drop is the full downward
+/// tilt); the arm `0x50dbc0` eases the ground channel to the stepped angle over
+/// `[3, 10] × Factor` seconds, a floor that always binds (20° at 7.5°/s is 2.67 s), and the
+/// channel adds to the view pitch inside the ±89° clamp (`0x50f810`).
 pub(super) struct TerrainTilt {
-    /// The ground channel `+0x108` — angular, rate `cameraGroundSmoothSpeed`.
+    /// The ground channel `+0x108`, at `cameraGroundSmoothSpeed`.
     ground: SmoothChannel,
-    /// The probe's own output `[cam+0xa0]`, held between throttle ticks.
+    /// The probe's output `[cam+0xa0]`, held between runs.
     slope_pitch: f32,
-    /// Seconds since the probe last ran — the 100 ms throttle (`0x50d94f`).
+    /// Seconds since the probe ran, for the 100 ms throttle (`0x50d94f`).
     since_probe: f32,
-    /// **The mouse-look hand-off, `[cam+0xa8]`** — is the lean currently living inside the pitch
-    /// rather than being composed onto it? The reference keeps a signed REFCOUNT here and gates
-    /// the compose on `> 0` (`0x50f809 jg`); benilla has exactly one look session, so the count
-    /// can only ever be 0 or 1 and a bool carries it without pretending otherwise.
+    /// Mouse look holds the lean inside the pitch (the reference's refcount `[cam+0xa8]`).
     handed_off: bool,
 }
 
@@ -431,31 +271,19 @@ impl Default for TerrainTilt {
         Self {
             ground: SmoothChannel::angular(),
             slope_pitch: 0.0,
-            // The probe runs on the very first frame rather than 100 ms into the session.
+            // The probe runs on the first frame.
             since_probe: PROBE_THROTTLE,
             handed_off: false,
         }
     }
 }
 
-/// One row of the `cameraTerrainTilt<Style><State>` matrix — `{Absorb, Delay, Factor}`.
-///
-/// **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 of its
-/// default-string table `0x84f620`.
+/// An `{Absorb, Delay, Factor}` row, from `0x84f620`. Deviation: a code table, not the reference's
+/// ninety `cameraTerrainTilt<Style><State>` CVars, because the matrix is a law, not a setting.
 type TiltRow = (f32, f32, f32);
 
-/// The ten movement states `0x50dbc0` classifies into, in the reference's own index order (the
-/// `0x84f5e8` name table): `Fall, Fear, Idle, Jump, Move, Strafe, Swim, Taxi, Track, Turn`.
-///
-/// **`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. 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.
+/// The movement states `0x50dbc0` classifies into (names at `0x84f5e8`), less the reference's
+/// `Jump`, which is dead: `0x50dc28` and `0x50dc35` test the same bit, so state 3 is never set.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum TiltState {
     Fall,
@@ -470,7 +298,7 @@ pub(super) enum TiltState {
 }
 
 impl TiltState {
-    /// `0x50dbc0`'s classifier, as the priority ladder its branch order makes it.
+    /// `0x50dbc0`'s classifier, a priority ladder in its branch order.
     fn of(subject: &SubjectState) -> Self {
         if subject.taxi {
             Self::Taxi
@@ -493,12 +321,7 @@ impl TiltState {
         }
     }
 
-    /// This state's `{Absorb, Delay, Factor}` at `style`.
-    ///
-    /// `Never` is every state disabled. `Always` differs from `Smart` in exactly one row — `Idle`,
-    /// which `Smart` disables (so a standing camera holds its tilt rather than levelling) and
-    /// `Always` drives. `Swim` and `Taxi` absorb **0.0** at both live styles, i.e. they aim the
-    /// channel at LEVEL rather than at the ground.
+    /// This state's row at `style`; an `Absorb` of 0 aims the channel at level.
     fn row(self, style: super::camera::FollowStyle) -> TiltRow {
         use super::camera::FollowStyle;
         if style == FollowStyle::Never {
@@ -517,11 +340,9 @@ impl TiltState {
 }
 
 impl TerrainTilt {
-    /// The signed pitch the ground is contributing this frame, radians, benilla's sign — added to
-    /// the view pitch inside the ±89° clamp.
+    /// The ground's pitch this frame, radians, positive up.
     pub(super) fn pitch(&self) -> f32 {
-        // `0x50f809 test eax,eax / jg` — with the hand-off refcount up, the compose is SKIPPED,
-        // because the lean is already inside the pitch that `0x50d500` pushed it into.
+        // `0x50f809`: while handed off, the lean is already inside the pitch.
         if self.handed_off {
             0.0
         } else {
@@ -529,27 +350,16 @@ impl TerrainTilt {
         }
     }
 
-    /// **The mouse-look hand-off** (`0x50d500` push / `0x50d520` pop) — returns the delta the
-    /// pitch owes, which is `0x510120`'s argument and nothing else.
-    ///
-    /// It is a hand-off, not a suppression. On the freelook 0→1 edge the lean's *current* value is
-    /// added to the pitch and the compose stops, so the view does not move: the lean simply becomes
-    /// part of the angle the player is now dragging. The channel keeps tracking the terrain
-    /// underneath throughout — `0x50d900`/`0x50dbc0` are not gated by `+0xa8` — and on the →0 edge
-    /// the *then-current* value is subtracted back out and the compose resumes.
-    ///
-    /// 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 (`0x510120`), so here
-    /// it lands in one frame. Named, not smoothed over.
+    /// The mouse-look hand-off (`0x50d500` push, `0x50d520` pop): the delta the pitch owes. The
+    /// lean moves into the pitch at press and the then-current lean comes out at release, both
+    /// through `0x510120`, which writes the live pitch at once; a slope crossed mid-drag leaves the
+    /// difference in the pitch.
     pub(super) fn hand_off(&mut self, freelook: bool) -> f32 {
         if freelook == self.handed_off {
             return 0.0;
         }
         self.handed_off = freelook;
-        // Always the RAW channel value: `pitch()` answers zero once the flag is up, and the pop
-        // has to give back what the push took plus whatever the terrain moved in between.
+        // The raw channel value: `pitch()` reads zero while handed off.
         let live = self.ground.live();
         if freelook {
             live
@@ -558,14 +368,10 @@ impl TerrainTilt {
         }
     }
 
-    /// The probe's staircase (`0x50db37`'s downward walk over `0x808a40`, then the ±20° clamp),
-    /// given the ground's rise-over-run ahead of the subject. Uphill (`slope >= 0`) tilts the view
-    /// UP here, which is the reference's negative.
+    /// The staircase: `0x50db37` walks `0x808a40` down to the first key `|slope|` reaches, with no
+    /// interpolation, then clamps to ±20°. Uphill looks up: positive here, negative there.
     pub(super) fn slope_to_pitch(slope: f32) -> f32 {
-        // The five reachable steps, biggest first — the walk takes the first key the slope clears.
-        // The keys are `round(tan(5k°), 2)`, and each of these literals is bit-identical to the
-        // f32 the table holds (`0.36` IS `0.36000001430511475`), so writing them short costs no
-        // fidelity and keeps the derivation legible.
+        // Keys `round(tan(5k°), 2)`; each literal is bit-identical to the table's f32.
         const STEPS: [(f32, f32); 5] = [
             (0.36, 20.0),
             (0.27, 15.0),
@@ -585,10 +391,8 @@ impl TerrainTilt {
         }
     }
 
-    /// Run the probe if the throttle allows, then arm and step the ground channel.
-    ///
-    /// `probe` answers the *rise over run* of the ground ahead — `None` when the CVar's gate is
-    /// false, which is the one case that ZEROES the held value (`0x50d922`) rather than holding it.
+    /// Runs the probe (the ground ahead's rise over run) when the throttle allows, then arms and
+    /// steps the ground channel.
     pub(super) fn advance(
         &mut self,
         probe: impl FnOnce() -> f32,
@@ -600,8 +404,7 @@ impl TerrainTilt {
     ) -> f32 {
         self.since_probe += dt;
         if !gate {
-            // `0x5105a0` false: the kernel's second early exit writes an integer zero into
-            // `[cam+0xa0]` and returns, so the held value does NOT survive a switched-off CVar.
+            // A false gate (`0x5105a0`) zeroes the held value (`0x50d922`); the throttle keeps it.
             self.slope_pitch = 0.0;
         } else if self.since_probe >= PROBE_THROTTLE {
             self.since_probe = 0.0;
@@ -609,9 +412,7 @@ impl TerrainTilt {
         }
         let (absorb, delay, factor) = TiltState::of(subject).row(style);
         if factor < 0.0 {
-            // The disable sentinel (`0x50dcd1`): the target becomes the live value and the channel
-            // disarms — the camera keeps the lean it has. This is all of `Never`, and it is `Smart`
-            // standing still.
+            // The disable sentinel (`0x50dcd1`): the channel disarms and keeps the lean it has.
             self.ground.snap(self.ground.live());
         } else {
             let rate = cfg.ground_smooth_speed.to_radians();
@@ -627,77 +428,31 @@ impl TerrainTilt {
     }
 }
 
-/// The probe's re-run interval — `0x50d953 sub ecx,0x64` / `js`, i.e. 100 ms.
+/// The probe's rerun interval, seconds (`0x50d953`).
 const PROBE_THROTTLE: f32 = 0.1;
-/// The horizontal probe's reach, yd — `[0x808a34] = 10/3`.
+/// The horizontal ray's reach along the facing, yd (`[0x808a34]`).
 pub(super) const PROBE_REACH: f32 = 10.0 / 3.0;
-/// How far the horizontal hit is pulled back before the drop, yd — `[0x808ab8] = 5/18`.
+/// How far the horizontal hit is pulled back before the drop, yd (`[0x808ab8]`).
 pub(super) const PROBE_BACKOFF: f32 = 5.0 / 18.0;
-/// The probe LIFT, yd — `[0x808a38] = 5/3`. Added to the feet going in and cancelled coming out,
-/// so it never reaches the slope; it exists to start the horizontal ray above the ground.
+/// The height over the feet the horizontal ray starts at, yd (`[0x808a38]`); it cancels out.
 pub(super) const PROBE_LIFT: f32 = 5.0 / 3.0;
-/// The vertical drop's reach, yd — `[0x808ab4] = 64/9`.
+/// The vertical drop's reach, yd (`[0x808ab4]`).
 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.
+/// `cameraBobbing`, head bob: a figure-of-eight translation of the eye while moving, first person
+/// only. Edges of the input-command word arm a session (`0x511170`) and restart its phase; the
+/// disarm eases the offset to an exact zero (`0x511110`, `0x50f160`).
 ///
-/// 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*.
-/// 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
-/// second `test ch,0x20` on a bit the previous `jne` already proved clear. Not transcribed.)
-///
-/// **What arms a session is the movement-COMMAND word, not the gate.** `0x511170(cam, enable)` is
-/// an edge setter called from the input word's AddFlags/RemoveFlags (`0x5149d5`/`0x514cc1`), which
-/// recompute from the NEW word:
-///
-/// ```text
-/// armed = (f & (Fwd|Back|StrafeL|StrafeR|AutoRun|Track)) != 0
-///      || (RightMouse && (LeftMouse || TurnL|TurnR))
-/// ```
-///
-/// — the very word benilla already builds for the auto-follow ([`super::camera::follow_cmd`]). The
-/// arm stamps the epoch, so **the phase restarts at every session**; a redundant re-arm writes
-/// nothing. And the latch is **not** gated by `cameraBobbing`: a stock client runs it on every
-/// start and stop and renders nothing, which is why turning the CVar on mid-run starts the bob at
-/// the phase the session has already reached rather than from zero.
-///
-/// **The kernel `0x511920`.** `A = cameraBobbingFrequency × clamp(speed / 7.2, [0.5, 1.5])`,
-/// `t` = seconds since the epoch; horizontal `a = ampH · sin(2πAt)` laid along the subject's
-/// **left** axis (`φ + π/2`), vertical `ampV · sin(2π · 2A · t)` straight up — the horizontal
-/// traces a line and the vertical runs at double rate, which is the figure of eight. Both
-/// amplitudes are their CVar × 1/36. The rate factor's floor is `0.5`, so a session armed while
-/// standing still still bobs, at half rate.
-///
-/// **It is a pure TRANSLATION of the eye** and it lands in the same accumulator the camera shake
-/// uses, reaching the world position once; the look-at target is `eye + forward`, so it rides
-/// along and the view never rotates.
-///
-/// **The decay `0x5106f0` → `0x50f160`.** `cameraBobbingSmoothSpeed` is *not* in the kernel at all:
-/// its one image-wide read is in the disarm, where `|largest component| / speed` becomes the ramp
-/// DURATION. A residual offset with the gate false eases to zero over that, cosine, terminating on
-/// an exact zero — about 0.069 s at the shipped defaults.
-///
-/// **The named divergence:** the reference solves the camera collision against the *bobbed* trial
-/// eye (`0x50ed47`), so the camera pushes off geometry it bobs into. benilla adds the offset after
-/// the sweep, which is the same thing [`crate::camera_shake`] already does with the very same
-/// accumulator — one divergence, in one place, rather than a new one here.
+/// Deviation: the reference sweeps the camera collision against the bobbed eye (`0x50ed47`);
+/// benilla adds the offset after the sweep, because it shares camera shake's accumulator there.
 pub(super) struct HeadBob {
-    /// Is a session armed? `[cam+0x90] & 0x200`, latched on the command word's edges.
+    /// A session is armed (`[cam+0x90] & 0x200`).
     armed: bool,
-    /// The command word the last edge was computed from.
     last_command: Option<u32>,
-    /// Seconds since the last transition — `[cam+0x238]`, which serves the bob phase while armed
-    /// and the decay's clock while not, the two never overlapping.
+    /// Seconds since the last arm or disarm (`[cam+0x238]`): the phase, then the decay's clock.
     since_transition: f32,
-    /// The offset this frame, world axes.
     offset: Vec3,
-    /// The disarm snapshot and the ramp's duration — `[cam+0x240..0x248]` and `[cam+0x23c]`.
+    /// The disarm's snapshot (`[cam+0x240..0x248]`) and ramp duration (`[cam+0x23c]`).
     ramp_from: Vec3,
     ramp_duration: f32,
 }
@@ -710,21 +465,19 @@ impl Default for HeadBob {
             since_transition: 0.0,
             offset: Vec3::ZERO,
             ramp_from: Vec3::ZERO,
-            // The ctor's zero: a decay with nothing snapshotted lands on `s >= 1` immediately and
-            // writes the exact zero, which is the reference's behaviour and not a division to
-            // guard against.
+            // The ctor's zero: a decay with no snapshot lands on its exact zero at once.
             ramp_duration: 0.0,
         }
     }
 }
 
 impl HeadBob {
-    /// The eye offset this frame, world axes — [`Vec3::ZERO`] whenever nothing is bobbing.
+    /// The eye offset this frame, world axes; zero when nothing bobs.
     pub(super) fn offset(&self) -> Vec3 {
         self.offset
     }
 
-    /// The arm predicate, on the camera's own input-command word.
+    /// The arm predicate on the input-command word (`0x5149d5`, `0x514cc1`).
     fn arms(command: u32) -> bool {
         use super::camera::follow_cmd as c;
         const TRANSLATING: u32 =
@@ -734,10 +487,7 @@ impl HeadBob {
                 && command & (c::LEFT_MOUSE | c::TURN_LEFT | c::TURN_RIGHT) != 0)
     }
 
-    /// One frame: run the latch off the command word, then either the kernel or the decay.
-    ///
-    /// `zoom` is the wheel's distance (`[cam+0xec]`), NOT the collision-pulled arm — a camera
-    /// squeezed against a wall is not in first person.
+    /// One frame: the latch, then the kernel or the decay. `zoom` is the wheel's distance.
     pub(super) fn advance(
         &mut self,
         zoom: f32,
@@ -746,15 +496,14 @@ impl HeadBob {
         dt: f32,
     ) {
         self.since_transition += dt;
-        // The latch (`0x511170`), edge-triggered on the command word and NOT on `cameraBobbing`.
+        // The latch (`0x511170`): edges of the command word, ungated by `cameraBobbing`.
         let want = Self::arms(subject.command);
         if self.last_command.replace(subject.command) != Some(subject.command) && want != self.armed
         {
             if want {
                 self.armed = true;
             } else {
-                // The disarm (`0x511110`) snapshots the offset and turns its largest component
-                // into the ramp's duration.
+                // The disarm (`0x511110`): the largest component sets the ramp's duration.
                 self.armed = false;
                 self.ramp_from = self.offset;
                 let largest = self
@@ -769,9 +518,7 @@ impl HeadBob {
         if self.eligible(zoom, subject, cfg) {
             self.offset = self.kernel(subject, cfg);
         } else if (self.offset.x + self.offset.y + self.offset.z).abs() >= CHANNEL_EPS {
-            // `0x5106f0`'s displacement test is on the SIGNED SUM's magnitude, not on the vector's
-            // length — a detail worth keeping, because the two disagree whenever the components
-            // cancel.
+            // `0x5106f0` tests the signed sum's magnitude, not the length.
             let s = self.since_transition / self.ramp_duration.max(f32::EPSILON);
             self.offset = if s >= 1.0 {
                 Vec3::ZERO
@@ -784,7 +531,7 @@ impl HeadBob {
         }
     }
 
-    /// `0x5105e0`'s ten conjuncts, in its own order.
+    /// The gate `0x5105e0`, in its order; its UNIT-or-PLAYER conjuncts always hold here.
     fn eligible(&self, zoom: f32, subject: &SubjectState, cfg: &CameraOptions) -> bool {
         zoom <= BOB_FIRST_PERSON_DISTANCE
             && !subject.scoped
@@ -796,15 +543,13 @@ impl HeadBob {
             && self.armed
     }
 
-    /// `0x511920`, once the gate has passed.
+    /// The kernel `0x511920`: lateral at rate `A` and vertical at `2A`, the figure of eight.
     fn kernel(&self, subject: &SubjectState, cfg: &CameraOptions) -> Vec3 {
         let rate = cfg.bob_frequency
             * (subject.speed / BOB_SPEED_DIVISOR).clamp(BOB_SPEED_CLAMP.0, BOB_SPEED_CLAMP.1);
         let phase = std::f32::consts::TAU * rate * self.since_transition;
         let lateral = cfg.bob_lr_amplitude * BOB_AMPLITUDE_SCALE * phase.sin();
-        // `φ + π/2` in the reference's Z-up frame is the subject's LEFT — here, the same rotation
-        // about Bevy's +Y. The sway is a sine, so left and right differ only by half a period;
-        // the axis is what matters, and it is the body's, written out in world axes.
+        // The reference's `φ + π/2` is the subject's left: the same rotation about Bevy's +Y.
         let left = Quat::from_rotation_y(subject.facing) * Vec3::NEG_X;
         left * lateral
             + Vec3::Y * (cfg.bob_ud_amplitude * BOB_AMPLITUDE_SCALE * (2.0 * phase).sin())
@@ -816,8 +561,7 @@ mod tests {
     use super::*;
 
     const DT: f32 = 1.0 / 60.0;
-    /// A drag that is unambiguously "mostly vertical": well over `cameraPivotDYMin` on pitch and
-    /// well under `cameraPivotDXMax` on yaw.
+    /// A clearly vertical drag: over `cameraPivotDYMin` on pitch, under `cameraPivotDXMax` on yaw.
     const UP: f32 = 0.01;
 
     fn moving(translating: bool) -> SubjectState {
@@ -827,14 +571,10 @@ mod tests {
         }
     }
 
-    /// **The gate's whole point** (`0x510690`, conjunct 6): the verdict is the collision solver's
-    /// own clip flags, so a camera with nothing behind it never pivots however you drag it. Every
-    /// other conjunct is checked in the same shape — one at a time, against a case that would
-    /// otherwise pivot.
+    /// The gate `0x510690`: each conjunct removed alone from a case that pivots.
     #[test]
     fn only_a_clipped_camera_looking_level_or_up_and_not_translating_pivots() {
         let cfg = CameraOptions::default();
-        // The reference case: clipped, pitched up, standing still, CVar on -> the bias takes it.
         let mut p = SmartPivot::default();
         assert_eq!(
             p.route_pitch(UP, 0.0, 0.2, &moving(false), true, &cfg),
@@ -842,11 +582,10 @@ mod tests {
         );
         assert!(p.bias() > 0.0, "the drag went into the bias");
 
-        // …and each single conjunct removed hands the delta back to the ordinary integrator.
         for (name, opts, pitch, subject, clipped) in [
             ("unclipped", cfg, 0.2, moving(false), false),
             ("translating", cfg, 0.2, moving(true), true),
-            // Looking DOWN — the reference's `[cam+0xf4] <= 0`, mirrored (module doc).
+            // Looking down: the reference's `[cam+0xf4] <= 0`, mirrored.
             ("pitched down", cfg, -0.2, moving(false), true),
             (
                 "cvar off",
@@ -869,8 +608,7 @@ mod tests {
         }
     }
 
-    /// The drag-shape test (`0x50fff5`/`0x510004`): a mostly-HORIZONTAL drag is an ordinary orbit
-    /// even with every gate conjunct true — smart pivot is for looking up, not for turning.
+    /// The drag-shape test (`0x50fff5`/`0x510004`).
     #[test]
     fn a_mostly_horizontal_drag_is_never_a_pivot() {
         let cfg = CameraOptions::default();
@@ -881,13 +619,12 @@ mod tests {
             Some(UP)
         );
         assert_eq!(p.bias(), 0.0);
-        // Exactly at the threshold is still refused — the compare is `|dYaw| < DXMax`.
+        // The compare is `|dYaw| < DXMax`, so the threshold itself is refused.
         assert_eq!(
             p.route_pitch(UP, cfg.pivot_dx_max, 0.2, &moving(false), true, &cfg),
             Some(UP)
         );
         assert_eq!(p.bias(), 0.0);
-        // And a hair under it pivots.
         assert_eq!(
             p.route_pitch(
                 UP,
@@ -902,8 +639,7 @@ mod tests {
         assert!(p.bias() > 0.0);
     }
 
-    /// The one-sided clamp (`0x510065`–`0x510079`): the pivot may not take the composite aim past
-    /// the ±89° pitch limit, and the bound is on **that sum**, not on the bias alone.
+    /// The one-sided clamp (`0x510065`-`0x510079`) bounds the sum with the pitch, not the bias.
     #[test]
     fn the_bias_cannot_take_the_composite_past_the_pitch_limit() {
         let cfg = CameraOptions::default();
@@ -919,9 +655,7 @@ mod tests {
         );
     }
 
-    /// Dragging back DOWN unwinds the bias and, the moment it would carry the view below the
-    /// camera's own pitch, hands the axis back to the ordinary integrator — the reference's
-    /// `bias > 0 || f4 >= 0` fork at `0x510094`/`0x510045`, mirrored.
+    /// The reference's `bias > 0 || f4 >= 0` fork (`0x510094`/`0x510045`), mirrored.
     #[test]
     fn dragging_back_down_returns_the_axis_to_the_ordinary_pitch() {
         let cfg = CameraOptions::default();
@@ -934,7 +668,6 @@ mod tests {
         }
         let peak = p.bias();
         assert!(peak > 0.0);
-        // Down again, five times: the bias walks back to (about) zero and the axis is handed over.
         let mut handed_back = 0;
         for _ in 0..6 {
             if p.route_pitch(-UP, 0.0, 0.2, &moving(false), true, &cfg)
@@ -947,8 +680,7 @@ mod tests {
         assert!(p.bias() < peak, "and the bias unwound");
     }
 
-    /// The release (`0x50ed77` → `0x5107f0`): once any gate conjunct drops, the bias eases back to
-    /// zero at `cameraTargetSmoothSpeed` — not instantly, and not never.
+    /// The release (`0x50ed77` → `0x5107f0`).
     #[test]
     fn losing_the_gate_eases_the_bias_home_at_the_target_smooth_speed() {
         let cfg = CameraOptions::default();
@@ -956,7 +688,6 @@ mod tests {
         p.route_pitch(0.3, 0.0, 0.5, &moving(false), true, &cfg);
         let held = p.bias();
         assert!(held > 0.0);
-        // The gate still true: the bias sits exactly where it is, indefinitely.
         for _ in 0..120 {
             p.advance(
                 0.5,
@@ -968,7 +699,6 @@ mod tests {
             );
         }
         assert_eq!(p.bias(), held, "a held gate must not move the bias");
-        // Step out of the wall: it eases home over |bias| / 90°/s.
         let expected = held / cfg.target_smooth_speed.to_radians();
         let mut took = None;
         for frame in 0..600 {
@@ -991,9 +721,7 @@ mod tests {
         );
     }
 
-    /// The staircase, not a curve (`0x808a40` walked downward with no interpolation) — and the
-    /// **five** reachable steps, because the ±20° clamp equals record 4 and the table has one
-    /// consumer image-wide, so records 5–9 can never show through.
+    /// `0x808a40` walked down with no interpolation; the ±20° clamp hides records 5-9.
     #[test]
     fn the_terrain_staircase_is_five_signed_steps_and_nothing_between_them() {
         let deg = |slope: f32| TerrainTilt::slope_to_pitch(slope).to_degrees();
@@ -1008,7 +736,7 @@ mod tests {
             (0.35, 15.0),
             (0.36, 20.0),
             (1.0, 20.0),
-            // Records 5-9 would read 25/30/35/40/45° — the clamp makes them all 20°.
+            // Records 5-9 would read 25-45°; the clamp makes them 20°.
             (0.47, 20.0),
             (100.0, 20.0),
         ] {
@@ -1017,21 +745,16 @@ mod tests {
                 "slope {slope} -> {} °, wanted {want}",
                 deg(slope)
             );
-            // Symmetric in magnitude, opposite in sign: downhill tilts the view down.
             assert!(
                 (deg(-slope) + want).abs() < 1e-4,
                 "slope -{slope} -> {} °, wanted -{want}",
                 deg(-slope)
             );
         }
-        // The sign convention, stated as an assertion rather than a comment: UPHILL looks UP,
-        // which is positive here and negative in the reference.
+        // Uphill looks up: positive here, negative in the reference.
         assert!(TerrainTilt::slope_to_pitch(0.5) > 0.0);
     }
 
-    /// The `Factor < 0` disable sentinel holds the channel where it is — which at the shipped
-    /// `Smart` style is what a standing camera does, and what all of `Never` does. Every other
-    /// state drives, and `Swim`/`Taxi` drive it to LEVEL rather than to the ground.
     #[test]
     fn the_tilt_matrix_disables_smart_idle_and_levels_swim_and_taxi() {
         use super::super::camera::FollowStyle;
@@ -1067,9 +790,6 @@ mod tests {
         assert_eq!(TiltState::Fall.row(FollowStyle::Smart).2, 0.75);
     }
 
-    /// The classifier is a priority ladder, and the order is the reference's branch order — a taxi
-    /// outranks swimming, swimming outranks falling, and turning in place is its own state rather
-    /// than Idle.
     #[test]
     fn the_tilt_state_ladder_takes_the_highest_priority_flag_set() {
         let with = |f: fn(&mut SubjectState)| {
@@ -1086,7 +806,6 @@ mod tests {
         assert_eq!(with(|s| s.track = true), TiltState::Track);
         assert_eq!(with(|s| s.fear = true), TiltState::Fear);
         assert_eq!(with(|s| s.taxi = true), TiltState::Taxi);
-        // …and the ladder's order where several are set at once.
         assert_eq!(
             with(|s| {
                 s.taxi = true;
@@ -1105,9 +824,6 @@ mod tests {
         );
     }
 
-    /// The whole probe→channel round trip: the throttle holds the probe at 100 ms, the gate's
-    /// false leg ZEROES the held value (it does not hold it), and the duration floor binds so that
-    /// even the full 20° takes its three seconds.
     #[test]
     fn the_tilt_channel_is_throttled_gated_and_floored_at_three_seconds() {
         let cfg = CameraOptions {
@@ -1119,7 +835,6 @@ mod tests {
             move_flags: mf::FORWARD,
             ..SubjectState::default()
         };
-        // The probe runs on frame one, then not again for 100 ms.
         let mut t = TerrainTilt::default();
         let mut probes = 0;
         for _ in 0..6 {
@@ -1137,15 +852,13 @@ mod tests {
         }
         assert_eq!(probes, 1, "100 ms is six frames at 60 Hz, so one probe");
 
-        // The duration floor: 20° at 7.5 °/s is 2.67 s, and `cameraTerrainTiltTimeMin` is 3.
+        // 20° at 7.5°/s is 2.67 s, under the 3 s `cameraTerrainTiltTimeMin`.
         let mut t = TerrainTilt::default();
         let target = TerrainTilt::slope_to_pitch(0.5);
         let mut took = None;
         for frame in 0..600 {
             let p = t.advance(|| 0.5, true, &moving, FollowStyle::Smart, &cfg, 1.0 / 60.0);
-            // Exact equality, not an epsilon: the cosine's tail is flat, so `|p − target| < 0.001`
-            // lands a fifth of a second early and would hide a wrong duration. The step writes the
-            // target bit-exactly on the frame `s >= 1`, and that frame is the measurement.
+            // Exact: an epsilon passes on the cosine's flat tail a fifth of a second early.
             if took.is_none() && p == target {
                 took = Some(frame as f32 / 60.0);
             }
@@ -1155,10 +868,9 @@ mod tests {
             (took - cfg.tilt_time_min).abs() < 0.05,
             "the 3 s floor should bind, took {took:.2}s"
         );
-        // And the floor is doing the work: |Δ| / rate alone would be 2.67 s.
         assert!(target.abs() / cfg.ground_smooth_speed.to_radians() < cfg.tilt_time_min);
 
-        // The gate's false leg zeroes the held probe value rather than holding it (`0x50d922`).
+        // A false gate zeroes the held value (`0x50d922`).
         let mut zeroed = 0.0_f32;
         for _ in 0..600 {
             zeroed = t.advance(|| 0.5, false, &moving, FollowStyle::Smart, &cfg, 1.0 / 60.0);
@@ -1166,9 +878,6 @@ mod tests {
         assert!(zeroed.abs() < CHANNEL_EPS, "levels off, at {zeroed}");
     }
 
-    /// The arm predicate, which is the reference's own word and not a re-derivation of "moving":
-    /// autorun and externally-driven movement arm it with no key held, and right-mouse arms it only
-    /// in a chord.
     #[test]
     fn head_bob_arms_on_the_movement_command_word_and_on_the_mouse_chord() {
         use super::super::camera::follow_cmd as c;
@@ -1198,9 +907,6 @@ mod tests {
         }
     }
 
-    /// The ten conjuncts, one removed at a time from a case that otherwise bobs — including the
-    /// 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;
@@ -1216,7 +922,7 @@ mod tests {
         };
         let bobs = |zoom: f32, subject: &SubjectState, cfg: &CameraOptions| {
             let mut b = HeadBob::default();
-            // A first frame to take the arming edge, then a quarter period to leave zero.
+            // One frame for the arming edge, then half a second to leave zero.
             b.advance(zoom, subject, cfg, 1.0 / 60.0);
             for _ in 0..30 {
                 b.advance(zoom, subject, cfg, 1.0 / 60.0);
@@ -1295,9 +1001,6 @@ mod tests {
         }
     }
 
-    /// The kernel's shape: horizontal along the body's own left axis at `A`, vertical at `2A`, both
-    /// amplitudes scaled by 1/36 — and the rate factor's floor, which is why a session armed at a
-    /// standstill still bobs at half rate rather than stopping.
     #[test]
     fn the_bob_traces_a_figure_of_eight_at_the_scaled_amplitudes() {
         use super::super::camera::follow_cmd as c;
@@ -1308,7 +1011,7 @@ mod tests {
         let subject = SubjectState {
             command: c::FORWARD,
             move_flags: mf::FORWARD,
-            // 7.2 yd/s is exactly the divisor, so the rate factor is 1.0 and A = the frequency.
+            // The divisor itself: a rate factor of 1, so `A` is the frequency.
             speed: BOB_SPEED_DIVISOR,
             facing: 0.0,
             ..SubjectState::default()
@@ -1319,12 +1022,10 @@ mod tests {
         let (mut peak_lat, mut peak_up) = (0.0_f32, 0.0_f32);
         let (mut lat_crossings, mut up_crossings) = (0_i32, 0_i32);
         let (mut was, period) = (Vec3::ZERO, 1.0 / cfg.bob_frequency);
-        // Five periods, so the counts are large enough that where the window happens to end
-        // cannot move the ratio the assertion is about.
         for _ in 0..(5.0 * period / dt) as usize {
             b.advance(0.0, &subject, &cfg, dt);
             let o = b.offset();
-            // Facing −Z, so the body's left is world −X and the sway has no Z at all.
+            // Facing −Z, so the body's left is world −X and the sway has no Z.
             assert_eq!(o.z, 0.0, "the sway is lateral, never fore/aft");
             peak_lat = peak_lat.max(o.x.abs());
             peak_up = peak_up.max(o.y.abs());
@@ -1339,16 +1040,12 @@ mod tests {
         let amp = BOB_AMPLITUDE_DEFAULT * BOB_AMPLITUDE_SCALE;
         assert!((peak_lat - amp).abs() < 1e-3, "lateral peak {peak_lat}");
         assert!((peak_up - amp).abs() < 1e-3, "vertical peak {peak_up}");
-        // **The vertical runs at double the horizontal** — the figure of eight. Counted over five
-        // periods and compared with one crossing of slack, because where the window happens to end
-        // can leave the faster axis one crossing short of the exact 2:1 and that is a property of
-        // the ruler, not of the wave.
+        // Vertical at twice the lateral rate, with one crossing of slack for where the window ends.
         assert!(
             (up_crossings - 2 * lat_crossings).abs() <= 1 && lat_crossings >= 9,
             "vertical {up_crossings} crossings against lateral {lat_crossings}"
         );
 
-        // The rate floor: standing still (speed 0) still bobs, at half the unit rate.
         let still = SubjectState {
             speed: 0.0,
             ..subject
@@ -1364,8 +1061,6 @@ mod tests {
         );
     }
 
-    /// The decay: a session that ends eases the residual to zero over
-    /// `|largest component| / cameraBobbingSmoothSpeed` and terminates on an EXACT zero.
     #[test]
     fn releasing_the_key_ramps_the_bob_to_an_exact_zero() {
         use super::super::camera::follow_cmd as c;
@@ -1382,7 +1077,7 @@ mod tests {
         let dt = 1.0 / 600.0;
         let mut b = HeadBob::default();
         b.advance(0.0, &running, &cfg, dt);
-        // A quarter period in, so the offset is near its peak when the key comes up.
+        // A quarter second in, the lateral sway near its peak when the key comes up.
         for _ in 0..150 {
             b.advance(0.0, &running, &cfg, dt);
         }
@@ -1412,9 +1107,7 @@ mod tests {
         assert_eq!(b.offset(), Vec3::ZERO, "and terminates on an exact zero");
     }
 
-    /// A gate that comes back while the ease is in flight **cancels** it where it stands
-    /// (`0x50ed93`) rather than fighting it — so stepping back against the wall mid-return leaves
-    /// the view tilted, it does not snap.
+    /// `0x50ed93`: a gate back mid-return leaves the view tilted, without a snap.
     #[test]
     fn re_entering_the_gate_cancels_the_return_where_it_stands() {
         let cfg = CameraOptions::default();
@@ -1445,19 +1138,12 @@ mod tests {
         assert_eq!(p.bias(), mid, "the return was cancelled, not completed");
     }
 
-    /// **The sweep decision 2165 says every regime switch owes** — here across the staircase's own
-    /// four keys, in both signs.
-    ///
-    /// Two claims, and the pair is the point. The staircase itself steps by exactly 5° and never
-    /// more: that jump is the mechanism, and this is where its size is written down. What reaches
-    /// the *camera* steps by a fortieth of that, because the staircase arms a channel instead of
-    /// being rendered — which is precisely what the water corridor did not do.
+    /// The staircase jumps 5° at each key; the channel it arms reaches the camera smoothly.
     #[test]
     fn the_staircases_five_degree_jumps_reach_the_camera_as_a_smooth_lean() {
         use super::super::camera::FollowStyle;
         use super::super::camera_channel::assert_bounded_step;
 
-        // The mechanism's own jump, bounded at itself.
         assert_bounded_step(
             (-0.6, 0.6),
             0.0005,
@@ -1465,7 +1151,7 @@ mod tests {
             TerrainTilt::slope_to_pitch,
         );
 
-        // And what a player actually sees, walking terrain that sweeps every key in 20 s.
+        // Walking terrain that sweeps every key in 20 s.
         let cfg = CameraOptions {
             terrain_tilt: true,
             ..CameraOptions::default()
@@ -1481,13 +1167,7 @@ mod tests {
         });
     }
 
-    /// The same sweep across head bob's two edges — the arm and the disarm — which are the only
-    /// places its offset can move discontinuously.
-    ///
-    /// The arm is continuous by construction (`since_transition` resets, so the kernel's phase
-    /// starts at zero and both components with it); the disarm is the cosine ramp, whose peak rate
-    /// is what the bound is set from. A regression that armed at an arbitrary phase would put a
-    /// full amplitude into one frame and land here.
+    /// The arm starts at phase zero and the disarm is a cosine ramp, so neither edge steps the eye.
     #[test]
     fn arming_and_disarming_the_bob_never_steps_the_eye_by_a_visible_amount() {
         use super::super::camera::follow_cmd as c;
@@ -1497,7 +1177,7 @@ mod tests {
             bobbing: true,
             ..CameraOptions::default()
         };
-        // A full amplitude in one frame would be this; the two bounds are fractions of it.
+        // The bounds are fractions of a full amplitude in one frame.
         let amplitude = cfg.bob_ud_amplitude * BOB_AMPLITUDE_SCALE;
         let mut bob = HeadBob::default();
         let mut step = |now: f32| {
@@ -1518,18 +1198,12 @@ mod tests {
             );
             bob.offset().length()
         };
-        // Arming, and three seconds of bobbing.
+        // Arming and three seconds of bobbing, then the disarm's ramp.
         assert_bounded_step((0.0, 3.9), DT, amplitude * 0.25, &mut step);
-        // The disarm's own ramp, bounded at what `cameraBobbingSmoothSpeed` actually buys.
         assert_bounded_step((3.9, 6.0), DT, amplitude * 0.5, &mut step);
     }
 
-    /// **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
-    /// behind exactly the difference between the lean at press and the lean at release, which is
-    /// the reference's behaviour and the reason this is a hand-off rather than a suppression.
+    /// The hand-off (`0x50d500` push, `0x50d520` pop).
     #[test]
     fn mouse_look_hands_the_lean_into_the_pitch_and_takes_it_back() {
         use super::super::camera::FollowStyle;
@@ -1548,7 +1222,6 @@ mod tests {
         let lean = tilt.pitch();
         assert!(lean > 0.0, "uphill leans the view UP in benilla's sign");
 
-        // What the camera composes, across the press.
         let mut pitch = 0.2_f32;
         let composite = pitch + tilt.pitch();
         pitch += tilt.hand_off(true);
@@ -1561,10 +1234,9 @@ mod tests {
             (pitch + tilt.pitch() - composite).abs() < 1.0e-6,
             "the press must not move the view"
         );
-        // Idempotent while held — the reference's refcount does not double-push.
+        // Held: the reference's refcount does not push twice.
         assert_eq!(tilt.hand_off(true), 0.0);
 
-        // Released over the same terrain: the pitch gives back exactly what it took.
         pitch += tilt.hand_off(false);
         assert!((pitch - 0.2).abs() < 1.0e-6, "the pop returns the push");
         assert!(
@@ -1572,7 +1244,7 @@ mod tests {
             "and the release must not move the view either"
         );
 
-        // Now cross a slope change mid-drag: press on the hill, flatten, release.
+        // Press on the hill, flatten, release.
         pitch += tilt.hand_off(true);
         for _ in 0..900 {
             tilt.advance(|| 0.0, true, &moving, FollowStyle::Smart, &cfg, DT);
@@ -1589,14 +1261,12 @@ mod tests {
         );
     }
 
-    /// **`0x511010`'s first disjunct**: with the TRACK latch up and `cameraSmoothTrackingStyle` at
-    /// `Never`, the bias is HELD where it stands instead of easing home — the reference's way of
-    /// not fighting a tracking swing in flight. Both of the other two legs release as before.
+    /// `0x511010`'s first disjunct: the Track latch with `cameraSmoothTrackingStyle` at Never.
     #[test]
     fn a_never_tracking_swing_holds_the_bias_the_gate_would_have_released() {
         use super::super::camera::FollowStyle;
         let cfg = CameraOptions::default();
-        // Arm a bias through the pure-pivot leg, then drop the gate and run half a second.
+        // A bias from the pure-pivot leg, then half a second with the gate dropped.
         let run = |subject: &SubjectState, tracking: FollowStyle| {
             let mut p = SmartPivot::default();
             assert_eq!(p.route_pitch(UP, 0.0, 0.1, subject, true, &cfg), None);
diff --git a/crates/benilla-app/src/player/camera_saved.rs b/crates/benilla-app/src/player/camera_saved.rs
index bd86687a..6c6cf69b 100644
--- a/crates/benilla-app/src/player/camera_saved.rs
+++ b/crates/benilla-app/src/player/camera_saved.rs
@@ -1,44 +1,16 @@
-//! The **camera pose** the client remembers (decision 1131) — orbit distance and pitch, per
-//! character. The fourth resident of 0954's folder to be character-scoped, and the smallest: two
-//! floats.
-//!
-//! The reference keeps exactly these two, in `WTF/Account/<ACC>/<REALM>/<CHAR>/camera-settings.txt`
-//! — read out of a real 26-character tree (decision 1128's persistence-surface map):
+//! The per-character camera pose, as the reference keeps it in
+//! `WTF/Account/<ACC>/<REALM>/<CHAR>/camera-settings.txt`:
 //!
 //! ```text
 //! cameraDistance 16.068569
 //! cameraPitch 13.449968
 //! ```
 //!
-//! Two keys, LF, six decimals, trailing newline — VERIFIED at the writer (`0x50c4d0`) and reader
-//! (`0x50c5a0`), decision 1138. **No yaw**: the live heading is never persisted anywhere. (The
-//! `SaveView(2..5)` custom views *are* persisted, but as archived `config.wtf` CVars —
-//! `cameraYaw`/`cameraYawA..D` and their Distance/Pitch — not in this file. 1131 §3 said otherwise;
-//! 1138 corrects it. benilla has no `SaveView`, so nothing is owed here yet.)
-//!
-//! benilla writes the same two keys in the same order to
-//! `benilla-config/camera/<realm>-<character>.txt` ([`crate::local_state::camera_character_path`]) — a file
-//! that stays readable beside its ancestor.
-//!
-//! **Character-scoped, deliberately.** It is where the reference puts it, and it is what the setting
-//! means: a gnome and a tauren want different zooms, and a tank and a healer want different pitches.
-//! (The minimap's zoom, the other half of 1131, is install-scoped for the same reason the reference
-//! makes it a CVar: it is about the map widget, not the character in front of it.)
-//!
-//! **Written at the session edges** — `OnExit(InWorld)` (a `/logout`, a disconnect) and `AppExit`
-//! (quit) — the same two edges the saved variables use ([`crate::ui_saved`]), and the same posture
-//! the reference has for its caches: no autosave, no dirty bit. A camera pose is a thing you settle
-//! into once and leave; there is nothing an intermediate write would preserve. The reference's write
-//! set is the UI-shutdown root set at `0x490bd0`, which is *wider* than ours — it also fires on
-//! `/reload`, `/console reloadUI` and a UI-scale change, each of which then reads the file straight
-//! back (1138). benilla has no UI reload, so there is no edge here to miss; when one lands it joins
-//! this list.
-//!
-//! **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.
+//! Two keys, LF, six decimals, a trailing newline (writer `0x50c4d0`, reader `0x50c5a0`), no yaw.
+//! Ours is `benilla-config/camera/<realm>-<character>.txt`, written at logout, disconnect and
+//! quit; the reference's UI teardown (`0x490bd0`) also writes it on `ReloadUI` and a UI-scale
+//! change and reads it straight back, which ours does not. Read once per session, when the roster
+//! names the character; the pitch reaches the camera through the login seize.
 
 use std::path::PathBuf;
 
@@ -52,50 +24,33 @@ use super::camera::{
 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.
+/// The file's keys, the reference's spellings in its order.
 const KEY_DISTANCE: &str = "cameraDistance";
 const KEY_PITCH: &str = "cameraPitch";
 
-/// Which character's file we are on, and where it lives. `identity` doubles as the once-per-
-/// character latch (the macro/binding load's pattern), and it is what the *save* keys off — by the
-/// time `OnExit(InWorld)` fires, the roster may already have moved on.
+/// The loaded character and its file. `identity` is the once-per-character latch; the save uses
+/// `path`, since the roster may have moved on by `OnExit(InWorld)`.
 #[derive(Resource, Default)]
 pub(super) struct CameraPoseFile {
     identity: Option<(String, String)>,
     path: Option<PathBuf>,
 }
 
-/// The persisted `cameraPitch` → the live [`FlyCam::pitch`].
-///
-/// **Both halves VERIFIED** at the bytes (decision 1138; 1131 §2.1 had the right conversion for the
-/// wrong reason). The file is **degrees**, and the client's own reader is a pure unit conversion
-/// with **no sign flip**: `deg × 0.01745329238474369` at `0x50c6f9` on load, `× 57.295780181884766`
-/// at `0x50c54f` on save. The client's internal pitch is itself **positive = looking down** — its
-/// forward is `(cos y·cos p, sin y·cos p, −sin p)` with `eye = pivot − dist·forward`, so `p > 0`
-/// puts the eye above the pivot.
-///
-/// The negation below is therefore ours, not the file's: **[`FlyCam::pitch`] is positive = looking
-/// UP.** Our forward is `Quat::from_euler(YXZ, yaw, pitch, 0)` applied to `−Z`, whose Y component is
-/// `+sin(pitch)`, and `camera::control` seats the camera at `pivot − forward·distance`. Two opposite
-/// conventions meeting, which is exactly what these two functions exist to bridge.
-///
-/// **Two carriers, one encoding.** The saved camera views ([`super::camera_view`]) store their
-/// pitch in the same units through a different door — the archived `cameraPitch{,A..D}` CVars,
-/// whose writer `0x50f990` scales the *same* internal field by `180/pi` before its `"%f"`
-/// (`0x50f9dc`) and whose loader `0x50fb80` multiplies back by `pi/180` (`0x50fba3`). So these two
-/// functions are the app's single bridge for both, and "file" in their names is the first carrier,
-/// not the only one.
+/// A saved `cameraPitch` (degrees, positive looking down) as [`FlyCam::pitch`] (radians, positive
+/// looking up). The reference converts without a sign flip (`× π/180` at `0x50c6f9`, `× 180/π` at
+/// `0x50c54f` on save), its own pitch being positive-down; the flip is ours. The saved-view CVars
+/// carry pitch in the same units (writer `0x50f990`, loader `0x50fb80`), so
+/// [`super::camera_view`] converts through here too.
 pub(super) fn pitch_from_file(degrees: f32) -> f32 {
     (-degrees.to_radians()).clamp(-CAM_PITCH_LIMIT, CAM_PITCH_LIMIT)
 }
 
-/// The live [`FlyCam::pitch`] → the persisted `cameraPitch` (see [`pitch_from_file`]).
+/// The inverse of [`pitch_from_file`].
 pub(super) fn pitch_to_file(radians: f32) -> f32 {
     -radians.to_degrees()
 }
 
-/// Render the pose exactly as the reference's writer does: two keys, one per line, `%f`'s six
-/// decimals, LF, trailing newline.
+/// The pose as the reference writes it: `%f`'s six decimals, LF, a trailing newline.
 fn render(distance: f32, pitch_radians: f32) -> String {
     format!(
         "{KEY_DISTANCE} {distance:.6}\n{KEY_PITCH} {:.6}\n",
@@ -103,18 +58,13 @@ fn render(distance: f32, pitch_radians: f32) -> String {
     )
 }
 
-/// Parse the two keys out of the file, each independently optional — a file with only one line
-/// restores only that half, and an unknown key is skipped rather than failing the parse (a later
-/// build's third key must not cost this build its zoom). Returns `(distance, pitch_radians)`.
+/// `(distance, pitch_radians)`, each optional. As in the reference's reader (`0x50c5a0`), keys
+/// match case-insensitively (`SStrCmpI 0x64a4c0`), either line ending reads, and an unknown key
+/// is skipped.
 ///
-/// Permissive in the same three ways the reference's reader is (`0x50c5a0`, VERIFIED 1138): keys
-/// match **case-insensitively** (`SStrCmpI 0x64a4c0`), either line ending is fine (its tokenizer
-/// splits on `"\r\n"`; `str::lines` strips the `\r`), and an unrecognised key is silently skipped.
-///
-/// One deliberate divergence: **we clamp, the client does not.** Its load path writes the parsed
-/// float straight into the camera with no bound, so a hand-edited `cameraPitch 400` survives there
-/// until the next mouse-look re-clamps it. Ours lands somewhere legal instead — a file is not a
-/// gesture, and there is nothing to be faithful *to* in an unreachable pose.
+/// Deviation: both values clamp to the rig's range, because a hand-edited file should not land a
+/// pose play cannot reach; the reference stores them unbounded, the pitch until a mouse-look
+/// re-clamps it.
 fn parse(text: &str) -> (Option<f32>, Option<f32>) {
     let (mut distance, mut pitch) = (None, None);
     for line in text.lines() {
@@ -138,12 +88,8 @@ fn parse(text: &str) -> (Option<f32>, Option<f32>) {
     (distance, pitch)
 }
 
-/// Restore the pose once the roster names the character — the same identity the macro and binding
-/// loads key off, so all three land on the same character on the same frame it becomes knowable.
-///
-/// Sets the rig's three distances together (`distance`, `target_distance`, `collision_distance`):
-/// seeding only the target would make every login open with a visible glide out from the default 15,
-/// which is precisely the "we forgot" the file exists to end.
+/// Restores the pose once the roster names the character, the identity the macro and binding
+/// loads use. All three rig distances are set, so the login opens at the zoom, not gliding to it.
 fn load_camera_pose(
     roster: Res<crate::char_select::Roster>,
     mut file: ResMut<CameraPoseFile>,
@@ -158,7 +104,7 @@ fn load_camera_pose(
         return; // already restored for this character
     }
     let Ok(mut cam) = cam.single_mut() else {
-        return; // the camera entity is not up yet — try again next frame, identity unlatched
+        return; // no camera yet: retry next frame, the identity still unlatched
     };
     file.path = crate::local_state::camera_character_path(&id.0, &id.1);
     file.identity = Some(id);
@@ -169,11 +115,10 @@ fn load_camera_pose(
     player.login_pitch = None;
 
     let Some(path) = file.path.clone() else {
-        return; // hermetic capture, or no install — session-only, defaults stand
+        return; // a hermetic capture or no install: the defaults stand
     };
     let text = match std::fs::read_to_string(&path) {
         Ok(t) => t,
-        // Absent is the normal first-run case; anything else is worth a line.
         Err(e) if e.kind() == std::io::ErrorKind::NotFound => return,
         Err(e) => {
             warn!("camera pose: cannot read {}: {e}", path.display());
@@ -193,15 +138,12 @@ fn load_camera_pose(
     info!("camera pose: restored from {}", path.display());
 }
 
-/// Write the pose from the live rig. Keyed off the path the *load* resolved, not off the roster:
-/// on `OnExit(InWorld)` the roster is already unwinding, and the character whose pose this is is the
-/// one we logged in as.
+/// Writes the pose to the path the load resolved: by `OnExit(InWorld)` the roster is unwinding.
 fn save(file: &CameraPoseFile, rig: &CameraControl, pitch: f32) {
     let Some(path) = &file.path else {
-        return; // never loaded (glue-only run, hermetic capture) — nothing to write back
+        return; // never loaded: a glue-only run or a hermetic capture
     };
-    // `target_distance`, never `distance`: the live one is the collision-pulled arm, so quitting
-    // with your back to a wall would otherwise save the wall's zoom instead of your own.
+    // `target_distance`: the live `distance` is the arm a wall has pulled in.
     let body = render(rig.target_distance, pitch);
     if let Err(e) = crate::local_state::write_atomic(path, &body) {
         warn!("camera pose: cannot write {}: {e}", path.display());
@@ -217,16 +159,13 @@ fn save_on_session_end(
     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.
+    // The next login re-reads, a relog of this character included; without a path, a quit from
+    // the character screen cannot 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
-/// in-world never leaves `InWorld` ([`crate::ui_saved`]'s same reason).
+/// `AppExit`, read as a message because a quit from in-world never leaves `InWorld`.
 fn save_on_exit(
     file: Res<CameraPoseFile>,
     rig: Res<CameraControl>,
@@ -245,16 +184,12 @@ pub(super) fn plugin(app: &mut App) {
     app.init_resource::<CameraPoseFile>()
         .add_systems(
             Update,
-            // Before the controller reads the rig, so the restored pose is what the first in-world
-            // frame renders rather than something the player watches glide into place. Not gated on
-            // capture mode: a capture resolves no state path at all (0954's hermetic rule), so this
-            // is already inert there.
+            // Before the controller, so the first in-world frame renders the restored pose. A
+            // capture resolves no state path, so this is inert there.
             load_camera_pose.before(super::control).in_set(InWorldGated),
         )
         .add_systems(OnExit(ClientState::InWorld), save_on_session_end);
-    // The quit root goes on the exit edge, never `Update` (decision 1528): the close button's
-    // `AppExit` is not written until `PostUpdate`, so an `Update` reader watched the pose die with
-    // the process — a `/logout` saved it and quitting from in-world did not.
+    // On the exit edge, never `Update`: the close button's `AppExit` is written in `PostUpdate`.
     crate::shutdown::on_app_exit(app, save_on_exit.into_configs());
 }
 
@@ -262,19 +197,14 @@ pub(super) fn plugin(app: &mut App) {
 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` the reference
-    /// client wrote (`16.068569` / `13.449968`).
+    /// The values come from a `camera-settings.txt` the reference wrote.
     #[test]
     fn the_rendered_file_matches_the_references_shape() {
         let text = render(16.068_57, pitch_from_file(13.449_968));
         assert_eq!(text, "cameraDistance 16.068569\ncameraPitch 13.449968\n");
     }
 
-    /// Round trip: what we write parses back to what we had, through the sign flip and both clamps.
-    ///
-    /// The first assertion is the one 1138 settled: the file's positive pitch is the client's
-    /// *looking down*, and OUR pitch is positive-up, so the stored sign must invert on the way in.
+    /// The file's positive pitch looks down and ours looks up, so the sign inverts on the way in.
     #[test]
     fn the_pose_round_trips() {
         let pitch = pitch_from_file(24.2);
@@ -282,13 +212,11 @@ mod tests {
         let (d, p) = parse(&render(17.509_666, pitch));
         assert_eq!(d, Some(17.509_666));
         assert!((p.unwrap() - pitch).abs() < 1e-4, "{p:?} vs {pitch}");
-        // The reference's one negative sample survives too (camera slightly below, looking up).
+        // The reference's one negative sample, the camera slightly below and looking up.
         let (_, up) = parse("cameraPitch -4.749999\n");
         assert!(up.unwrap() > 0.0);
     }
 
-    /// A hand-edited or truncated file never lands an illegal pose: each key is independent, the
-    /// distance clamps to the zoom range, the pitch to ±89°, and junk is skipped rather than fatal.
     #[test]
     fn a_hand_edited_file_cannot_land_an_illegal_pose() {
         let (d, p) = parse("cameraDistance 999\ncameraPitch 400\n");
@@ -304,9 +232,7 @@ mod tests {
         assert_eq!((d, p), (None, None), "junk and unknown keys are skipped");
     }
 
-    /// The reference's reader is case-insensitive on the key (`SStrCmpI`) and takes either line
-    /// ending (1138). Only a hand edit can produce either — our own writer is exact — but matching
-    /// it costs nothing and a file we refuse to read is a pose silently lost.
+    /// The reference's reader matches keys case-insensitively (`SStrCmpI`) and takes CRLF.
     #[test]
     fn a_hand_written_file_may_shout_its_keys_and_use_crlf() {
         let (d, p) = parse("CAMERADISTANCE 12.5\r\ncamerapitch 10.0\r\n");
@@ -354,10 +280,6 @@ mod login_tests {
         )
     }
 
-    /// **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
diff --git a/crates/benilla-app/src/player/camera_view.rs b/crates/benilla-app/src/player/camera_view.rs
index d1601fd7..c398b170 100644
--- a/crates/benilla-app/src/player/camera_view.rs
+++ b/crates/benilla-app/src/player/camera_view.rs
@@ -1,102 +1,22 @@
-//! The **five camera views** — `SetView` / `SaveView` / `ResetView` / `NextView` / `PrevView`, and
-//! `FlipCameraYaw`. The engine half of [`benilla_ui::script::CameraViewRequest`]; the Lua half (and
-//! the argument ABI) is `benilla-ui`'s `script::camera_view`.
+//! The five camera views (`SetView`, `SaveView`, `ResetView`, `NextView`, `PrevView`) and
+//! `FlipCameraYaw`: the engine half of [`benilla_ui::script::CameraViewRequest`].
 //!
-//! [`super::camera_saved`]'s neighbour, and its complement: that file remembers the **one live
-//! pose** per character; this one remembers the **five named poses** the player can jump between.
-//! The reference splits them exactly the same way and for the same reason — one is where you left
-//! the camera, the other is where you decided it should be able to go.
+//! The reference's rows are `FIRST_PERSON` and `THIRD_PERSON_A`..`D` (names at `0x84f848`); Lua
+//! `SetView(n)` takes row `n - 1`. Pitch is in degrees down-positive, the opposite of
+//! [`FlyCam::pitch`], converted only by [`super::camera_saved::pitch_from_file`]. Row 0's distance
+//! `0.0` is real first person ([`CAM_DIST_MIN`] is `0.0`).
 //!
-//! # The five views, byte-real
+//! The views persist as the reference's archived CVars (registered at `0x50b9b0`). [`CameraViews`]
+//! is seeded from them once and writes every change back, so a live `SetCVar` does not reach the
+//! slots; the reference also loads them only at camera construction (`0x50fb80`). The live view is
+//! remembered, not applied at startup: [`super::camera_saved`]'s pose lands over it, as the
+//! reference's saved pose lands over `cameraView`'s row at UI load.
 //!
-//! The reference's camera ctor reads the `cameraView` CVar and indexes a five-row table of default
-//! *strings* at `0x84f488` (stride 12, three `const char*` per row — distance, pitch, yaw), with
-//! the row names at `0x84f848`. Read straight out of `WoW.exe` 5875 (decision 1138 §2 records the
-//! first two columns; the third is dumped here for the first time):
+//! Deviation: `ResetView` writes the CVars back to their defaults, because the CVar store is our
+//! persistence; the reference (`0x50fae0`) touches no CVar, so its reset reverts at next launch.
 //!
-//! | `SetView` arg | internal | name | distance | pitch | yaw |
-//! |---|---|---|---|---|---|
-//! | 1 | 0 | `FIRST_PERSON`   | `0.0`   | `0.0`  | `0.0` |
-//! | 2 | 1 | `THIRD_PERSON_A` | `5.55`  | `10.0` | `0.0` |
-//! | 3 | 2 | `THIRD_PERSON_B` | `5.55`  | `20.0` | `0.0` |
-//! | 4 | 3 | `THIRD_PERSON_C` | `13.88` | `30.0` | `0.0` |
-//! | 5 | 4 | `THIRD_PERSON_D` | `13.88` | `10.0` | `0.0` |
-//!
-//! The pitch column is **degrees, positive = looking DOWN** — the reference's own convention, which
-//! is the opposite of [`FlyCam::pitch`]'s. Decision 1138 is the whole story; the conversion is
-//! [`super::camera_saved::pitch_from_file`] and this module does not grow a second one.
-//!
-//! View 1 is `distance 0.0`, and that is **reachable, not a rounding of "very close"**:
-//! [`CAM_DIST_MIN`] is `0.0`, the eye sits on the framing pivot (inside the head) and the avatar
-//! fades out through [`benilla_world::model_fade::self_model_fade_alpha`]. `SetView(1)` is real
-//! first person, not a clamp to some near stop.
-//!
-//! # Persistence — the reference's own fifteen CVars
-//!
-//! 1138 §2 recorded that the saved views survive a restart as archived `config.wtf` CVars and left
-//! the name→view mapping unpinned. It is pinned now, at `0x50b9b0`'s 5x3 registration loop, and the
-//! names are the reference's:
-//!
-//! ```text
-//! 50b9c1  SStrCopy(buf, 0x84fdc0)              ; "camera"
-//! 50b9d3  SStrCat (buf, [esi+0x84f468])        ; "Distance" | "Pitch" | "Yaw"   (inner, esi 0..12)
-//! 50b9e1  SStrCat (buf, [ebx])                 ; ""  | "A" | "B" | "C" | "D"    (outer, per view)
-//! 50b9ec  default = [esi + edi + 0x84f488]     ; the SAME table as the ctor's, 12·view + 4·field
-//! 50ba07  record  -> [esi + edi + 0xbe0f7c]
-//! ```
-//!
-//! → `cameraDistance`/`cameraPitch`/`cameraYaw` for view 0, and `…A`/`…B`/`…C`/`…D` for views 1–4;
-//! the active view is `cameraView` (`0x84fdc8`, registrar default `"1"` — an *internal* index, so
-//! the shipped view is `THIRD_PERSON_A`, i.e. Lua `SetView(2)`). Verified by reading the tables out
-//! of the binary, not inferred from the loop shape. benilla registers exactly those sixteen names
-//! with exactly those defaults ([`crate::cvars::REGISTERED`], welded by test below) — 0954's CVar
-//! store *is* our persistence, so being faithful here costs nothing and buys a `config.toml` a
-//! player can read against a real `config.wtf`.
-//!
-//! **No host knob** — the `lastCharacterIndex`/`checkAddonVersion` posture in [`crate::cvars`]:
-//! [`CameraViews`] is the authority, seeded once from the persisted values at startup and writing
-//! every change back through `set_cvar_engine` (the minimap-zoom pattern, so the write dirties
-//! `config.toml`). A live `SetCVar("cameraPitchB", …)` therefore does *not* reach the in-memory
-//! slot — which is the reference's behaviour too: `0x50fb80` loads the slot array from the CVar
-//! records at camera construction and nothing re-reads them afterwards.
-//!
-//! # Three things the reference does that a reader will expect it not to
-//!
-//! - **`SaveView(1)` and `ResetView(1)` work.** All three indexed entry points take `1..=5`
-//!   (`0x50b5d2`/`0x50b626`/`0x50b666`: `test eax,eax; jle` then `cmp eax,5; jg`), and `0x50fa30`
-//!   — SaveView's body — has no view-0 gate. 1.12 ships no `SAVEVIEW1`/`RESETVIEW1` *binding*,
-//!   which is a `Bindings.xml` decision; a macro reaches what no key can.
-//! - **`NextView`/`PrevView` do not wrap.** `0x50faa0` is `eax = view + 1; cmp eax,5; jge <ret>`,
-//!   `0x50fac0` is `test eax,eax; jle <ret>; dec eax`. Holding `END` walks 1→2→3→4→5 and stops.
-//! - **The saved yaw is an OFFSET from the subject's facing, not a world angle.** The reference's
-//!   yaw channel `cam+0xf0` is relative while `cam+0xa4 == 0` and the final view resolver re-adds
-//!   the followed unit's facing every frame (`0x50f7f2`); `0x512e90` adds it explicitly on the
-//!   absolute-mode leg (`0x512fff`). Ours stores `wrap_pi(cam.yaw − face_yaw)` for the same reason.
-//!
-//! # The active view is remembered, and not applied at startup
-//!
-//! [`load_saved_views`] seeds [`CameraViews`] and stops — it never calls [`apply`]. So a
-//! `cameraView` of `2` means "`NextView` steps from there", not "open the camera at view 2"; the
-//! pose you actually get is the one [`super::camera_saved`] restores, which is where you left the
-//! camera. That is not a divergence in *effect*: the reference builds its camera from
-//! `cameraView`'s row at construction and then `camera-settings.txt`'s reader lands distance and
-//! pitch over the top of it at UI load (1138), so the remembered pose wins there too. It is stated
-//! because the two modules are neighbours and a reader will otherwise expect them to fight.
-//!
-//! # Two deliberate divergences, both stated
-//!
-//! - **`ResetView` writes the CVars back to their defaults; the reference does not.** `0x50fae0`
-//!   re-parses the default strings into the slot array and re-applies the view, and touches no
-//!   CVar — so in the real client a reset comes *back* at the next launch, out of the value
-//!   `SaveView` archived. Here the CVar store is the persistence (0954), so a reset that does not
-//!   persist is a bug rather than a quirk worth aping; writing the default string verbatim also
-//!   makes [`crate::cvars`]'s diff-shaped file drop the key entirely.
-//! - **`SetView` glides the distance and snaps pitch and yaw.** The reference arms all three of its
-//!   smooth channels (`0x513189`/`0x5131a3`/`0x5131b8`, on `cameraViewBlendStyle`'s default `1`).
-//!   benilla's rig has exactly one such channel — the wheel-zoom glide at `cameraDistanceMoveSpeed`
-//!   — and setting `target_distance` rides it for free; there is no pitch or yaw channel to arm, so
-//!   those land immediately. A second and a third channel is a real piece of work and a *look*
-//!   call; it is named here rather than half-built.
+//! `SetView` glides the distance and snaps pitch and yaw: the reference arms three glide channels
+//! (`0x513189`, `0x5131a3`, `0x5131b8`), the rig has only the distance one.
 
 use bevy::prelude::*;
 
@@ -109,19 +29,14 @@ use super::camera::{CameraControl, FlyCam, CAM_DIST_MAX, CAM_DIST_MIN, CAM_PITCH
 use super::camera_saved::{pitch_from_file, pitch_to_file};
 use super::Player;
 
-/// How many views there are — the reference's default table `0x84f488` is five rows, and every
-/// entry point is bounded by it. Named through the UI crate's constant so the two ends of the
-/// queue cannot disagree about the range the Lua side already checked.
+/// The reference's five views, through the UI crate's constant so the Lua range check agrees.
 const VIEW_COUNT: usize = CAMERA_VIEW_COUNT as usize;
 
-/// The registered CVar name of the active view — the reference's own (`0x84fdc8`), holding the
-/// **internal** index as `"%d"` (`0x512ef1`, format `0x835154`).
+/// The live view's CVar (`0x84fdc8`), holding the internal index as `"%d"` (`0x512ef1`).
 pub(crate) const CVAR_ACTIVE_VIEW: &str = "cameraView";
 
-/// The fifteen saved-view CVar names, `[view][field]` with field = distance, pitch, yaw —
-/// `"camera" + {"Distance","Pitch","Yaw"} + {"","A","B","C","D"}`, composed at `0x50b9b0` (see the
-/// module header). Written out rather than composed so [`crate::cvars::REGISTERED`] can hold the
-/// same `&'static str`s and a test can weld the two tables together.
+/// The fifteen saved-view CVars, `[view][field]` (distance, pitch, yaw), as `0x50b9b0` composes
+/// them; [`crate::cvars::REGISTERED`] must hold the same names (tested).
 pub(crate) const VIEW_CVARS: [[&str; 3]; VIEW_COUNT] = [
     ["cameraDistance", "cameraPitch", "cameraYaw"],
     ["cameraDistanceA", "cameraPitchA", "cameraYawA"],
@@ -130,10 +45,8 @@ pub(crate) const VIEW_CVARS: [[&str; 3]; VIEW_COUNT] = [
     ["cameraDistanceD", "cameraPitchD", "cameraYawD"],
 ];
 
-/// The shipped defaults, **as the reference's own strings** — `0x84f488`, read out of `WoW.exe`
-/// 5875. Strings, not floats, for two reasons: they are what the binary stores (its ctor calls
-/// `SStrToFloat` on them), and [`crate::cvars`]'s file is a diff against the registered default
-/// *string*, so a reset can only strip the key by writing this exact text back.
+/// The reference's default strings (`0x84f488`), kept as text: [`crate::cvars`]'s file is a diff
+/// against the registered default string, so a reset strips the key only by writing this text.
 pub(crate) const VIEW_DEFAULTS: [[&str; 3]; VIEW_COUNT] = [
     ["0.0", "0.0", "0.0"],
     ["5.55", "10.0", "0.0"],
@@ -142,13 +55,11 @@ pub(crate) const VIEW_DEFAULTS: [[&str; 3]; VIEW_COUNT] = [
     ["13.88", "10.0", "0.0"],
 ];
 
-/// The registrar default of [`CVAR_ACTIVE_VIEW`] — `"1"` (`[0x84f484]`), the *internal* index, so
-/// the client opens on `THIRD_PERSON_A`.
+/// [`CVAR_ACTIVE_VIEW`]'s default (`[0x84f484]`): internal index 1, `THIRD_PERSON_A`.
 pub(crate) const ACTIVE_VIEW_DEFAULT: &str = "1";
 
-/// One view's pose, in **benilla's** units: yards, and radians with [`FlyCam::pitch`]'s
-/// positive-is-UP sign. `yaw` is an offset from the subject's facing (see the module header), so a
-/// view whose yaw is `0.0` is "directly behind" whichever way the character is pointing.
+/// One view's pose: yards, radians with [`FlyCam::pitch`]'s up-positive sign, and `yaw` as an
+/// offset from the subject's facing, which the reference re-adds every frame (`0x50f7f2`).
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub(crate) struct ViewPose {
     pub(crate) distance: f32,
@@ -157,26 +68,18 @@ pub(crate) struct ViewPose {
 }
 
 impl ViewPose {
-    /// A pose out of the reference's three stored strings — the units the CVars (and the default
-    /// table) carry: yards, degrees-positive-down, degrees. Clamped on the way in, at this one
-    /// edge, so nothing downstream can be handed an unreachable view: the distance to the zoom
-    /// range and the pitch to +-89 deg (the reference's own CVar validators are `0x50b310`'s
-    /// `[0, 50]` and `0x50b380`'s +-89 deg; ours are the rig's, which is the tighter, honest pair).
-    ///
-    /// The **yaw is wrapped rather than range-checked**: the reference's validator is `[0, 360]`
-    /// (`0x50b3c0`) while the value its `SaveView` writes is a signed offset, so both encodings are
-    /// in the wild and `wrap_pi` reads either.
+    /// From the CVar units (yards, degrees down-positive, degrees), clamped to the rig's zoom range
+    /// and ±89° pitch (reference validators: `[0, 50]` at `0x50b310`, ±89° at `0x50b380`). Yaw is
+    /// wrapped, as the reference validates `[0, 360]` (`0x50b3c0`) but `SaveView` writes an offset.
     fn from_reference(distance: f32, pitch_deg: f32, yaw_deg: f32) -> Self {
         Self {
             distance: distance.clamp(CAM_DIST_MIN, CAM_DIST_MAX),
-            // The one bridge, shared with the per-character pose file (decision 1138).
             pitch: pitch_from_file(pitch_deg),
             yaw: wrap_pi(yaw_deg.to_radians()),
         }
     }
 
-    /// The three strings to persist, in the reference's own `"%f"` (`0x50f9f3`, format `0x835160`)
-    /// — six decimals, which is also what [`super::camera_saved`] writes for the same numbers.
+    /// The three CVar strings, in the reference's `"%f"` (`0x50f9f3`, format `0x835160`).
     fn to_reference(self) -> [String; 3] {
         [
             format!("{:.6}", self.distance),
@@ -185,7 +88,6 @@ impl ViewPose {
         ]
     }
 
-    /// The shipped default for one view, parsed from the reference's own default strings.
     fn shipped(view: usize) -> Self {
         let row = VIEW_DEFAULTS[view];
         let parse = |s: &str| {
@@ -196,12 +98,11 @@ impl ViewPose {
     }
 }
 
-/// The five views and which one is live — the reference's `[cam+0xb0 .. +0xdc]` slot array and its
-/// `[cam+0xac]` index, as a resource.
+/// The five views and the live one: the reference's `[cam+0xb0..+0xdc]` and `[cam+0xac]`.
 #[derive(Resource, Debug, PartialEq)]
 pub(crate) struct CameraViews {
     views: [ViewPose; VIEW_COUNT],
-    /// The live view, `0..VIEW_COUNT` — the reference's `cam+0xac`, persisted as [`CVAR_ACTIVE_VIEW`].
+    /// The live view, persisted as [`CVAR_ACTIVE_VIEW`].
     current: usize,
 }
 
@@ -217,37 +118,29 @@ impl Default for CameraViews {
 }
 
 impl CameraViews {
-    /// The pose of one view.
     fn pose(&self, view: usize) -> ViewPose {
         self.views[view]
     }
 
-    /// `SetView` — make `view` live and hand back the pose to seat. Returns whether the index
-    /// actually moved, which is the reference's own gate on writing [`CVAR_ACTIVE_VIEW`]
-    /// (`0x512ee6 cmp [esi+0xac],edi; je`).
+    /// `SetView`, and whether the index moved: the gate on writing the CVar (`0x512ee6`).
     fn set(&mut self, view: usize) -> (ViewPose, bool) {
         let moved = self.current != view;
         self.current = view;
         (self.views[view], moved)
     }
 
-    /// `SaveView` — store a live pose into `view`. The reference reads the camera's three *target*
-    /// fields here (`0x50fa30`: `+0x198` distance, `+0x1e0` pitch, `+0x210` yaw), never the live
-    /// ones — which is why a save made with your back to a wall keeps your chosen zoom and not the
-    /// collision-pulled arm.
+    /// `SaveView`: the reference stores the camera's target fields, not the live ones (`0x50fa30`).
     fn save(&mut self, view: usize, pose: ViewPose) {
         self.views[view] = pose;
     }
 
-    /// `ResetView` — put `view` back to its shipped default. `true` when it was the live view, in
-    /// which case the reference re-applies it on the spot (`0x50fb5b`) and so do we.
+    /// `ResetView`; `true` when `view` is live, which the reference re-applies (`0x50fb5b`).
     fn reset(&mut self, view: usize) -> bool {
         self.views[view] = ViewPose::shipped(view);
         self.current == view
     }
 
-    /// `NextView` / `PrevView` — the neighbouring view, or `None` at either end. **No wrap**:
-    /// `0x50faa0`'s `cmp eax,5; jge <ret>` and `0x50fac0`'s `test eax,eax; jle <ret>`.
+    /// `NextView`/`PrevView`, with no wrap at either end (`0x50faa0`, `0x50fac0`).
     fn step(&self, forward: bool) -> Option<usize> {
         if forward {
             (self.current + 1 < VIEW_COUNT).then(|| self.current + 1)
@@ -257,16 +150,11 @@ impl CameraViews {
     }
 }
 
-/// Startup: seed the five views (and the live index) from `config.toml`.
-///
-/// Reads the registry ([`crate::cvars::Cvars::get`]) rather than the VM's table for the reason
-/// 1622's remembered-character row does: the VM's mirror is a per-VM `Update` seed and does not
-/// exist yet, while the registry is a resource from `CvarLoad` onward and outlives every VM
-/// (2303). An absent key answers the shipped default, which is every first run.
+/// Startup: seed the views and the live index from the CVar registry, which exists from `CvarLoad`
+/// on while the VM's mirror does not yet; an absent key is the shipped default.
 fn load_saved_views(cvars: Res<crate::cvars::Cvars>, mut views: ResMut<CameraViews>) {
     for (view, slot) in views.views.iter_mut().enumerate() {
-        // Each field is independently optional, like the pose file's two keys: an absent or
-        // hand-mangled value costs that one number, not the whole view.
+        // Each field falls back on its own: a bad value costs that number, not the view.
         let field = |i: usize| {
             cvars
                 .get(VIEW_CVARS[view][i])
@@ -292,7 +180,7 @@ fn load_saved_views(cvars: Res<crate::cvars::Cvars>, mut views: ResMut<CameraVie
     }
 }
 
-/// Everything one drained request may write, fetched once (the app's bundled-param convention).
+/// Everything one drained request may write.
 #[derive(bevy::ecs::system::SystemParam)]
 struct ViewTargets<'w, 's> {
     views: ResMut<'w, CameraViews>,
@@ -301,10 +189,7 @@ struct ViewTargets<'w, 's> {
     player: Res<'w, Player>,
 }
 
-/// Per frame: drain the Lua queue and apply each request to the rig.
-///
-/// Ordered before [`super::control`] so a view taken this frame is the pose this frame's camera
-/// seat is computed from, exactly like the pose file's restore.
+/// Drain the Lua queue into the rig, before [`super::control`] seats this frame's camera.
 fn drain_view_requests(
     script: Option<NonSendMut<UiScript>>,
     mut cvars: ResMut<crate::cvars::Cvars>,
@@ -318,12 +203,10 @@ fn drain_view_requests(
         return;
     }
     let Ok(mut cam) = targets.cam.single_mut() else {
-        return; // no camera entity — the reference's `0x4818f0` miss, same silent drop
+        return; // no camera: a silent drop, as the reference's `0x4818f0` miss
     };
     let face_yaw = targets.player.facing();
-    // What to mirror into the CVar table once the batch is applied: the slots a save or a reset
-    // moved, and the live index if it changed. Collected rather than written inline because the VM
-    // handle is borrowed for the drain.
+    // Written to the CVars after the batch: the slots a save or reset moved, and the live index.
     let mut write_slots: Vec<usize> = Vec::new();
     let mut write_active = false;
 
@@ -343,9 +226,7 @@ fn drain_view_requests(
                 targets.views.save(
                     view,
                     ViewPose {
-                        // `target_distance`, never `distance`: the reference saves `cam+0x198`,
-                        // the chosen zoom, not the collision-pulled arm (`camera_saved`'s own
-                        // reason, one field over).
+                        // The target zoom, not the collision-pulled arm (`cam+0x198`).
                         distance: targets.rig.target_distance,
                         pitch: cam.pitch,
                         yaw: wrap_pi(cam.yaw - face_yaw),
@@ -379,27 +260,18 @@ fn drain_view_requests(
                 }
             }
             CameraViewRequest::FlipYaw(degrees) => {
-                // `cam[+0x100] += arg * pi/180` (`0x50b6a0`). **A named divergence**: the
-                // reference accumulates into a yaw field of its OWN, added to the resolved view
-                // yaw at `0x50f7de` *outside* the follow channel, so its flip survives the camera
-                // re-centring behind a moving character. benilla's rig stores one absolute yaw and
-                // has no second channel, so the flip lands there and the auto-follow will reel it
-                // back in on Smart/Always (never on Never). Adding that second channel touches
-                // `seat_camera`, the follow and the right-drag carry, and changes how the view
-                // reads — a look call, not a silent one.
+                // `cam[+0x100] += arg * pi/180` (`0x50b6a0`). The reference keeps the flip in its
+                // own yaw field, added outside the follow channel (`0x50f7de`), so it survives
+                // re-centring; the rig has one yaw, so auto-follow reels the flip back in on Smart
+                // and Always.
                 cam.yaw = wrap_pi(cam.yaw + degrees.to_radians());
             }
         }
     }
 
-    // Mirror into the registry so the change dirties `config.toml` and the view survives a
-    // restart — a host write (2303: the engine's own value moved, so the table follows and the
-    // VM's mirror learns it). The resource stays authoritative either way, so a run with no VM
-    // at all (a bare test app) still has working views.
+    // Mirror into the registry so the change reaches `config.toml`.
     for view in write_slots {
-        // A reset writes the reference's default STRING verbatim, not a re-rendered `%f` of it:
-        // `crate::cvars`'s file is a diff against the registered default, and only the exact text
-        // makes the key disappear again.
+        // A reset writes the default string verbatim, so the diff-shaped file drops the key.
         let reset_to_default = targets.views.pose(view) == ViewPose::shipped(view);
         let rendered = targets.views.pose(view).to_reference();
         for field in 0..3 {
@@ -416,12 +288,7 @@ fn drain_view_requests(
     }
 }
 
-/// Seat one view on the rig, and say whether the live index moved (the [`CVAR_ACTIVE_VIEW`] write's
-/// own gate).
-///
-/// Only `target_distance` is written: the rig's wheel glide then walks `distance` there at
-/// `cameraDistanceMoveSpeed`, which is the same channel the reference's `SetView` arms for the
-/// distance. Pitch and yaw land immediately (see the module header's second divergence).
+/// Seat one view; the distance glides through `target_distance`. `true` when the live index moved.
 fn apply(
     views: &mut CameraViews,
     rig: &mut CameraControl,
@@ -438,18 +305,15 @@ fn apply(
 
 pub(super) fn plugin(app: &mut App) {
     app.init_resource::<CameraViews>()
-        // After the config fold, for the same reason the camera's own spawn is: the persisted
-        // views have to be in the resource before anything can select one.
+        // After the config load, so the persisted views are in before anything selects one.
         .add_systems(Startup, load_saved_views.after(crate::cvars::CvarLoad))
         .add_systems(
             Update,
             drain_view_requests
-                // After the tick that queued them (`SetView`/`SaveView` are Lua's), before the
-                // control pass that seats the pose.
+                // After the Lua tick that queues them, before the control pass seats the pose.
                 .after(crate::ui_script::UiInput)
                 .before(super::control)
-                // Capture parks the camera itself (`capture::probe_cam`), and `control` is gated
-                // off there for the same reason; a queued view must not steal a parked pose.
+                // Capture parks the camera itself; a queued view must not move it.
                 .run_if(not(resource_exists::<crate::run_mode::CaptureMode>)),
         );
 }
@@ -458,12 +322,9 @@ pub(super) fn plugin(app: &mut App) {
 mod tests {
     use super::*;
 
-    /// Every shipped view lands the pose the reference's own default table carries — the numbers
-    /// out of `0x84f488`, through the one pitch bridge (decision 1138), clamped where the rig
-    /// clamps. This is the test that would catch a transcription slip in [`VIEW_DEFAULTS`].
     #[test]
     fn each_shipped_view_lands_its_recorded_pose() {
-        // (Lua arg, distance yd, reference pitch degrees — positive is looking DOWN.)
+        // (Lua arg, distance yd, pitch in degrees down-positive), from `0x84f488`.
         let table = [
             (1, 0.0_f32, 0.0_f32),
             (2, 5.55, 10.0),
@@ -485,7 +346,6 @@ mod tests {
                 pose.yaw, 0.0,
                 "SetView({lua_arg}) yaw is behind the character"
             );
-            // The sign 1138 exists for: the reference's positive pitch is OUR negative.
             assert!(
                 pose.pitch <= 0.0,
                 "a positive saved pitch looks DOWN for us"
@@ -493,25 +353,18 @@ mod tests {
         }
     }
 
-    /// **First person is reachable**, and view 1 is it: distance 0.0 survives the clamp because
-    /// [`CAM_DIST_MIN`] is `0.0` and the rig seats the eye on the framing pivot there.
     #[test]
     fn view_one_is_real_first_person_not_a_near_stop() {
         assert_eq!(CAM_DIST_MIN, 0.0);
         assert_eq!(CameraViews::default().pose(0).distance, 0.0);
     }
 
-    /// The shipped view is `THIRD_PERSON_A` — `cameraView`'s registrar default `"1"` is an
-    /// *internal* index, i.e. Lua `SetView(2)`.
     #[test]
     fn the_shipped_view_is_third_person_a() {
         assert_eq!(CameraViews::default().current, 1);
         assert_eq!(CameraViews::default().pose(1).distance, 5.55);
     }
 
-    /// Save → move the camera → set: the saved pose comes back. Then reset puts the shipped
-    /// default back. The round trip goes through the persisted *strings*, so it also pins that
-    /// what we write is what we can read.
     #[test]
     fn a_saved_view_round_trips_and_reset_restores_the_default() {
         let mut views = CameraViews::default();
@@ -521,7 +374,6 @@ mod tests {
             yaw: 0.75,
         };
         views.save(2, saved);
-        // The camera moves somewhere else entirely...
         views.save(
             3,
             ViewPose {
@@ -532,7 +384,6 @@ mod tests {
         );
         assert_eq!(views.pose(2), saved);
 
-        // ...and through the CVar text, which is the only form that survives a restart.
         let [d, p, y] = saved.to_reference();
         let reloaded =
             ViewPose::from_reference(d.parse().unwrap(), p.parse().unwrap(), y.parse().unwrap());
@@ -542,14 +393,12 @@ mod tests {
 
         assert!(!views.reset(2), "view 2 was not the live one");
         assert_eq!(views.pose(2), ViewPose::shipped(2));
-        // Resetting the LIVE view reports so — the reference re-applies it on the spot.
         views.set(3);
         assert!(views.reset(3));
     }
 
-    /// **`SaveView(1)`/`ResetView(1)` are real** — the engine's range is `1..=5` for all three
-    /// indexed entry points (`0x50b5d2`/`0x50b626`/`0x50b666`), and `0x50fa30` has no view-0 gate.
-    /// Only the *binding* table stops at 2; a macro does not.
+    /// The engine takes `1..=5` (`0x50b5d2`, `0x50b626`, `0x50b666`); the stock
+    /// `SAVEVIEW`/`RESETVIEW` bindings start at 2.
     #[test]
     fn view_one_is_saveable_and_resettable() {
         let mut views = CameraViews::default();
@@ -565,8 +414,6 @@ mod tests {
         assert_eq!(views.pose(0).distance, 0.0);
     }
 
-    /// **Next/Prev clamp; they do not wrap** — `0x50faa0`'s `jge` and `0x50fac0`'s `jle` are hard
-    /// stops. The walk is 1→2→3→4→5 and then nothing.
     #[test]
     fn next_and_prev_stop_at_the_ends() {
         let mut views = CameraViews::default();
@@ -578,7 +425,6 @@ mod tests {
             views.set(next);
         }
         assert_eq!(views.step(true), None, "NextView at view 5 is a no-op");
-        // ...and back down, one at a time, to the bottom.
         for expected in (0..VIEW_COUNT - 1).rev() {
             let prev = views.step(false).expect("a view below this one");
             assert_eq!(prev, expected);
@@ -587,8 +433,7 @@ mod tests {
         assert_eq!(views.step(false), None);
     }
 
-    /// `FlipCameraYaw(180)` twice is the identity, mod 2pi — the binding body 1.12 ships, applied
-    /// the way [`drain_view_requests`] applies it.
+    /// 180 is the stock binding's argument (`Bindings.xml:796`).
     #[test]
     fn flipping_the_yaw_twice_returns_the_original() {
         let flip = |yaw: f32, degrees: f32| wrap_pi(yaw + degrees.to_radians());
@@ -606,9 +451,6 @@ mod tests {
         }
     }
 
-    /// A hand-edited `config.toml` can never land an unreachable view: the distance clamps to the
-    /// zoom range, the pitch to +-89 deg, and any yaw encoding (the reference's `[0, 360]`
-    /// validator or `SaveView`'s signed offset) wraps into range.
     #[test]
     fn a_hand_edited_view_cannot_land_an_illegal_pose() {
         let wild = ViewPose::from_reference(999.0, 400.0, 720.0 + 90.0);
@@ -625,9 +467,6 @@ mod tests {
         );
     }
 
-    /// **The weld** ([`crate::cvars`]'s own convention): every one of the sixteen names is
-    /// registered, with the reference's default string. No observer watches them — this module
-    /// is their writer, and the registry persists a host write on its own (2303).
     #[test]
     fn the_view_cvars_are_registered_with_the_references_defaults() {
         let registered = |name: &str| {
diff --git a/crates/benilla-app/src/player/camera_water.rs b/crates/benilla-app/src/player/camera_water.rs
index ad69f025..4753a8d3 100644
--- a/crates/benilla-app/src/player/camera_water.rs
+++ b/crates/benilla-app/src/player/camera_water.rs
@@ -1,117 +1,54 @@
-//! **The water corridor** — `cameraWaterCollision`'s *other* consumer, and the reason the option is
-//! atomic.
+//! The water corridor: `cameraWaterCollision`'s floor/cap block, which re-bases the framing pivot
+//! against the waterline before the boom's origin is built from it (`0x50e786`).
 //!
-//! One CVar read at `0x50e5ec` produces one register, and that register has **two** consumers:
+//! The one CVar read (`0x50e5ec`) has two consumers: its `0xf0000` nibble rides the trace mask of
+//! all three `0x50e570` queries, so the boom hits the waterline ([`benilla_world::collision`]), and
+//! `0x50e629 test esi,0xf0000` gates this block. They ship together: without the floor, a surface
+//! swimmer's pivot sits 11 mm under the plane the trace makes solid, and the boom straddles it.
 //!
-//! * `esi`'s `0xf0000` nibble rides the trace mask to all three of `0x50e570`'s queries, so the
-//!   camera boom hits a bare waterline ([`benilla_world::collision`]); and
-//! * `0x50e629 test esi,0xf0000` admits the **floor/cap block** transcribed here, which re-bases the
-//!   framing pivot against the waterline *before* the boom's origin is built from it (`0x50e786`).
+//! Not built: the reference's catch-up pair `0x50eeb0` (pivot height) and `0x50ee5d` (distance),
+//! which hard-store a live channel more than 1/9 above the solved `H` to `H + 1/9 + 2⁻²⁰` and
+//! ease it for 2.0 s toward the untouched target. They are one mechanism (the shared duration is
+//! loaded once, at `0x50ee63`, in the distance block), neither is gated on this CVar, and both
+//! run after the eye is stored (`0x50ede5`), so here only the corridor's upper edge would move.
 //!
-//! **Shipping either half alone is a visible defect, and this client has now shipped each once.**
-//! 2149 built the corridor without the trace and put a discontinuity on screen; 2170 built the trace
-//! without the corridor and pinned the camera to the waterline, because a surface swimmer's framing
-//! pivot sits 11 mm *under* the water plane and the boom then straddles it every frame (2173 §1).
-//! 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 the reference. Constants: `[0x8089cc] = 5/6`, `[0x8089d0] = 2/9`,
-//! `[0x8089d4] = 5/9`, `[0x808a04] = 1/9`.
-//!
-//! **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:
-//! `live > H + 1/9` strictly (equality and NaN skip), then a **hard store** of `H + 1/9 + 2⁻²⁰`
-//! into the live field, plus an ease start at that value with duration **`2.0` s** — and the
-//! channel's *target* deliberately left alone, so the ease walks back to where the camera was
-//! always headed. Both can only ever decrease their field: `0x50e8bf` caps the arm at
-//! `[cam+0xec]`, so `live − H ≥ 0` always, and no mirror block exists.
-//!
-//! **They are absent together, on purpose.** Three reasons, in order of weight:
-//!
-//! 1. **They are one mechanism, not two.** `ecx = 2.0f` — the duration for *both* — is loaded once
-//!    at `0x50ee63`, inside the DISTANCE block's predicate. Lifting `0x50eeb0` alone stores
-//!    garbage for its duration. This module's entire history is shipping one half of a pair
-//!    (2149, 2170, 2173); a spec that opens by warning against it gets taken at its word.
-//! 2. **Neither is gated on `cameraWaterCollision`** — control reaches them on two edges with no
-//!    band bit, CVar or mode flag read anywhere in `0x50eeb0`–`0x50eef8`. They are general camera
-//!    behaviour that this option merely *exposes*, and the distance twin changes what zoom does
-//!    after any collision, on land as much as in water. That is its own change to a hot path,
-//!    with its own gate to earn.
-//! 3. Their only effect here is on the corridor's **upper** edge, and it makes an already-small
-//!    artifact smaller. The lower edge — the one you can actually see — is unaffected: the eye is
-//!    stored at `0x50ede5` before either block runs.
-//!
-//! Also underived, and flagged rather than guessed: whether the followed object's `z` is swept or
-//! pinned entering the submerge band. `CMovement::UpdateLiquid` (`0x6a7650`) hands the physics step
-//! a plane at exactly `z = liquidSurfaceZ`, which rules out a fixed offset but does not settle it,
-//! and it sits in unresolved tension with the `0x610520` buoyancy equilibrium `|depth − 0.75h| <
-//! 0.001`. This client builds the pinned reading.
+//! Untraced: whether the followed unit's z is swept or pinned entering the submerge band
+//! (`CMovement::UpdateLiquid` `0x6a7650`, the buoyancy equilibrium `0x610520`); ours is pinned.
 
-/// `[0x8089cc]` — the corridor's resting floor, and the depth the pivot is pinned to while the
-/// camera target is in the SUBMERGE band. Also the cap's own floor there.
+/// `[0x8089cc]`: the resting floor, and the pivot's depth under the surface in the submerge band.
 const REST: f32 = 5.0 / 6.0;
-/// `[0x8089d0]` — the SURFACE band's width, and the height above the waterline the floor lifts the
-/// pivot to inside it. **This is the number that makes the trace survivable**: 2/9 yd of clearance
-/// between the sweep origin and the plane it would otherwise start on top of.
+/// `[0x8089d0]`: the surface band's width, and the pivot's lift above the waterline inside it.
 const SURFACE_BAND: f32 = 2.0 / 9.0;
-/// `[0x8089d4]` — the SUBMERGE band's outer edge. Its **only** reference image-wide is `0x511b83`,
-/// in the classifier (three independent censuses) — it is emphatically *not* the constant in the
-/// corridor's arm B, which is [`REST`]. 2149 shipped `5/9` there and stepped `7/9` where the
-/// reference steps `19/18`; that single substitution is most of why its numbers came out at
-/// 1.036/0.293 instead of 1.0556/0.2778.
+/// `[0x8089d4]`: the submerge band's outer edge, read only by the classifier (`0x511b83`); arm B's
+/// constant is [`REST`], not this.
 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 `0x50eeb0`/`0x50ee5d` would pin their live field to.
+/// `[0x808a04]`: the least head-room the pivot keeps above the corridor floor.
 const MIN_HEADROOM: f32 = 1.0 / 9.0;
 
-/// **Which liquid band the camera target is in** — the two bits `0x511ad0` writes into `[cam+0x90]`
-/// (`0x100000` surface, `0x200000` submerge) and the only thing image-wide that writes either.
-///
-/// `0x511ae3` clears **both** unconditionally before any test, which is why there is no hysteresis
-/// anywhere in this mechanism: every frame re-derives the band from scratch. That matters for what
-/// can and cannot hide a step — see [`corridor`]'s note on the lower edge.
+/// The camera target's liquid band, the two bits `0x511ad0` writes into `[cam+0x90]`. Both are
+/// cleared before any test (`0x511ae3`), so every frame re-derives the band: no hysteresis.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum WaterBand {
-    /// Neither bit — no liquid, or deeper than [`SUBMERGE_EDGE`] past the pivot target.
+    /// Neither bit: no liquid, or deeper than [`SUBMERGE_EDGE`] past the pivot target.
     Clear,
-    /// `0x100000` — the target is at or near the surface. The floor lifts the pivot to
-    /// `surface + 2/9`.
+    /// `0x100000`: at or near the surface; the floor lifts the pivot to `surface + 2/9`.
     Surface,
-    /// `0x200000` — a 1/3 yd window below the surface band. The pivot is pinned to
-    /// `surface − 5/6`.
+    /// `0x200000`: a 1/3 yd window below the surface band; the pivot sits at `surface − 5/6`.
     Submerge,
 }
 
-/// **`0x511ad0`** — classify the camera target's depth, and return `d`.
-///
-/// `d = liquidSurfaceZ − targetObject.position.z`: the **followed unit's own origin** (feet), read
-/// through vtable slot `+0x14`, not the pivot and not `*heightOut`. `[ebp+0x8]` (the pivot base)
-/// comes from the same call at `0x50e9ce`, so both are measured from one origin — which is what
-/// lets `d` be compared against a pivot height at all.
-///
-/// **The surface height is cached, never queried here.** `0x670630` is a field accessor:
-/// `0x670637 test byte ptr [ecx+0x90],0x20` gates it and `0x670640 mov eax,[ecx+0x98]` returns it.
-/// 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** — 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,
-/// independently of any of the steps below.
+/// `0x511ad0`: the band, and `d = liquidSurfaceZ − z` of the followed unit's own origin (vtable
+/// slot `+0x14`), the origin the pivot base also comes from (`0x50e9ce`). The surface is a cached
+/// field (`0x670630`); with no valid liquid it returns `+0.0` with both bits clear. The band is
+/// judged against the pivot target (`[cam+0x1c8]`), not the live value (`[cam+0xfc]`) the cap
+/// seeds from; banding on the eased live value would chatter.
 pub(super) fn classify(surface_y: Option<f32>, feet_y: f32, target: f32) -> (WaterBand, f32) {
     let Some(surface_y) = surface_y else {
         return (WaterBand::Clear, 0.0);
     };
     let d = surface_y - feet_y;
     let excess = d - target;
-    // Equality at `2/9` lands in SUBMERGE (the low side) and equality at `5/9` in `Clear` (the high
-    // side) — the two edges' tie-breaks go opposite ways, which is the reference's own shape and
-    // not a symmetry worth tidying.
+    // A tie at 2/9 lands in Submerge and one at 5/9 in Clear: the reference's own tie-breaks.
     let band = if excess < SURFACE_BAND {
         WaterBand::Surface
     } else if excess < SUBMERGE_EDGE {
@@ -127,38 +64,23 @@ pub(super) fn classify(surface_y: Option<f32>, feet_y: f32, target: f32) -> (Wat
 pub(super) struct Corridor {
     /// `[ebp-0x4]`, seeded [`REST`] at `0x50e604`.
     pub(super) floor: f32,
-    /// `[ebp-0xc]`, seeded from the **live** pivot height at `0x50e615`.
+    /// `[ebp-0xc]`, seeded from the live pivot height at `0x50e615`.
     pub(super) cap: f32,
 }
 
-/// **`0x50e629`–`0x50e685`** — the floor/cap block, gated on the CVar's own nibble.
+/// `0x50e629`–`0x50e685`: the floor/cap block, gated on the CVar's own nibble.
 ///
 /// | arm | predicate | floor | cap |
 /// |---|---|---|---|
 /// | gate off | `0x50e629 test esi,0xf0000` → `je 0x50e687` | `5/6` | `live` |
-/// | **A** surface | `0x50e637 test eax,0x100000` | `d + 2/9` | `max(live, d + 2/9)` |
-/// | **B** submerge | `0x50e65f test eax,0x200000` | `5/6` (untouched) | `max(d − 5/6, 5/6)` |
-/// | **C** clear | both bits clear | `5/6` | `live` |
+/// | A surface | `0x50e637 test eax,0x100000` | `d + 2/9` | `max(live, d + 2/9)` |
+/// | B submerge | `0x50e65f test eax,0x200000` | `5/6` (untouched) | `max(d − 5/6, 5/6)` |
+/// | C clear | both bits clear | `5/6` | `live` |
 ///
-/// Arm A is the whole point: it pins the framing pivot at `surface + 2/9` while the target is at the
-/// waterline, which is what puts 2/9 yd between the boom's origin and the water plane the same CVar
-/// just made solid.
-///
-/// **The lower edge steps `−19/18` and that is the reference's own behaviour, not a defect.** At
-/// `excess = 2/9` the pivot leaves `surface + 2/9` for `surface − 5/6` in one frame: `2/9 + 5/6 =
-/// 19/18 ≈ 1.0556 yd`. Every candidate hiding mechanism was checked and refuted — no hysteresis
-/// (`0x511ae3` clears both bits before any test), `d` is not quantised, and band B is a reachable
-/// 1/3 yd window, and the reference's own catch-up cannot absorb it: `0x50eeb0` runs AFTER the
-/// eye is stored (`0x50ede5`), and the whole function has zero backward branches.
-///
-/// **What keeps it off screen in normal play is that it is never approached continuously.** `d` is
-/// the movement tick's pinned swim depth and the pivot target steps on the same swim flag, so
-/// `d − target` is piecewise constant while swimming: a surface-swimming human male sits `0.011238`
-/// into band A, `0.211` short of the edge. The corridor is crossed by **diving**, once — which is
-/// exactly the event the reference wants to move the camera for. This is why 2173 §2's rule is
-/// "compute where the camera lands", not "forbid every step": the step is real, intended, and
-/// [`assert_bounded_step`](super::camera_channel::assert_bounded_step) is where its size is written
-/// down rather than eyeballed.
+/// From A to B the pivot drops `2/9 + 5/6 = 19/18` yd in one frame, as in the reference, where
+/// nothing smooths it. Swimming never grazes that edge: `d − target` is piecewise constant while
+/// swimming (a surface-swimming human male sits `0.011238` into band A, `0.211` short of it), so
+/// a dive crosses it once.
 pub(super) fn corridor(band: WaterBand, d: f32, live: f32) -> Corridor {
     match band {
         WaterBand::Surface => {
@@ -179,9 +101,7 @@ pub(super) fn corridor(band: WaterBand, d: f32, live: f32) -> Corridor {
     }
 }
 
-/// The corridor the CVar's `off` state leaves behind — `0x50e629`'s `je` straight to `0x50e687`,
-/// with both seeds untouched. Identical to [`WaterBand::Clear`]'s arm, which is why turning the
-/// option off is indistinguishable from standing on dry land and not a second code path.
+/// The CVar off: `0x50e629`'s `je` to `0x50e687` leaves both seeds, the same corridor as dry land.
 pub(super) fn corridor_off(live: f32) -> Corridor {
     Corridor {
         floor: REST,
@@ -189,21 +109,12 @@ pub(super) fn corridor_off(live: f32) -> Corridor {
     }
 }
 
-/// **`0x50e756` then `0x50e767`** — the clamped pivot height the boom's origin is built from at
-/// `0x50e786`.
-///
-/// `FLOOR + max(max(target, live) − FLOOR, 1/9)`, then capped. The head-room sweep scales the
-/// bracketed term by its hit fraction, so `headroom` is `1.0` on a clear probe and the hit's `t`
-/// otherwise — a low ceiling pulls the pivot down toward the floor rather than through it.
-///
-/// **Floor first, cap second, so the cap wins on a crossed corridor** (`FLOOR + 1/9 > CAP`, which is
-/// arm A's normal state whenever the live pivot is below the waterline). That ordering is what
-/// actually delivers `surface + 2/9`: the floor sets the corridor and the cap collapses onto it.
-///
-/// Neither clamp fires on NaN — both `je`s need C0 and C3 clear, so a NaN takes the assigning
-/// fall-through and the seeds stand. Rust's `max`/`min` on `f32` return the non-NaN operand, which
-/// is the same outcome by a different route; a NaN `d` therefore yields the resting corridor rather
-/// than poisoning the pivot, and there is a test for it.
+/// `0x50e756` then `0x50e767`: the pivot height the boom's origin is built from (`0x50e786`),
+/// `floor + max(max(target, live) − floor, 1/9) × headroom`, then capped. `headroom` is the
+/// head-room probe's hit fraction, 1.0 when clear. The cap applies last, so it wins on a crossed
+/// corridor (arm A with the live pivot under the waterline), landing the pivot at `surface + 2/9`.
+/// On NaN the reference's compares leave the seeds standing, as Rust's `max`/`min` (returning the
+/// other operand) do, so a NaN `d` yields the resting corridor.
 pub(super) fn pivot_height(c: &Corridor, target: f32, live: f32, headroom: f32) -> f32 {
     let reach = (target.max(live) - c.floor).max(MIN_HEADROOM) * headroom;
     (c.floor + reach).min(c.cap)
@@ -214,23 +125,18 @@ mod tests {
     use super::*;
     use crate::player::camera_channel::assert_bounded_step;
 
-    /// A human male's two numbers, both already shipping elsewhere in this tree: the swim framing
-    /// pivot (`cam+0x124`, off the model's Stand/Swim sequence boxes) and the depth the movement
-    /// tick pins a surface swimmer's feet to (`0.75 · CollisionHeight`, `h = 2.0309999`).
+    /// A human male's swim framing pivot (`cam+0x124`, off the model's Stand and Swim sequence
+    /// boxes) and surface swim depth (`0.75 · CollisionHeight`, `h = 2.0309999`).
     const SWIM_PIVOT: f32 = 1.512_012;
     const SURFACE_DEPTH: f32 = 0.75 * 2.031;
 
-    /// The pivot's height **relative to the water plane** — what the player actually sees, and the
-    /// quantity every claim in this module is about. Feet at the origin, so `d` is the surface.
+    /// The pivot's height over the water plane, feet at the origin so `d` is the surface.
     fn pivot_over_surface(d: f32, target: f32, live: f32) -> f32 {
         let (band, dd) = classify(Some(d), 0.0, target);
         let c = corridor(band, dd, live);
         pivot_height(&c, target, live, 1.0) - d
     }
 
-    /// **The defect 2170 shipped, stated as a test.** In the surface band the pivot is lifted to
-    /// `2/9` above the waterline — so the boom's origin starts clear of the plane the same CVar
-    /// makes solid, instead of 11 mm underneath it.
     #[test]
     fn the_surface_band_lifts_the_pivot_clear_of_the_water() {
         let over = pivot_over_surface(SURFACE_DEPTH, SWIM_PIVOT, SWIM_PIVOT);
@@ -244,10 +150,6 @@ mod tests {
         );
     }
 
-    /// **Why the reference never shows the lower step in normal swimming.** `d` is the movement
-    /// tick's pinned depth and the pivot target steps on the same swim flag, so `d − target` is
-    /// piecewise constant: a human male sits 0.0112 into a band 0.2222 wide. The corridor is
-    /// crossed by diving, deliberately, once — not grazed at the surface.
     #[test]
     fn a_surface_swimmer_sits_far_inside_the_band_and_never_grazes_its_edge() {
         let excess = SURFACE_DEPTH - SWIM_PIVOT;
@@ -266,9 +168,6 @@ mod tests {
         );
     }
 
-    /// **The dive step, written down.** `2/9 + 5/6 = 19/18`. Not smoothed, not hidden — the
-    /// reference's own deliberate "the pivot drops under the water with you" event, and the number
-    /// 2149 got wrong (it shipped `5/9` in arm B and stepped 7/9).
     #[test]
     fn crossing_into_the_submerge_band_drops_the_pivot_by_nineteen_eighteenths() {
         let edge = SWIM_PIVOT + SURFACE_BAND;
@@ -289,11 +188,8 @@ mod tests {
         );
     }
 
-    /// The upper edge — `+5/18`. **This is also what this client ships**, because the reference's
-    /// 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.
+    /// Leaving the submerge band steps `+5/18` here; the reference's catch-up blocks (`0x50eeb0`,
+    /// `0x50ee5d`), not built here, hold it to `+1/9` at most, negative on a fast ascent.
     #[test]
     fn leaving_the_submerge_band_with_the_live_pivot_held_is_the_closed_forms_five_eighteenths() {
         let edge = SWIM_PIVOT + SUBMERGE_EDGE;
@@ -306,14 +202,10 @@ mod tests {
         );
     }
 
-    /// **The sweep 2165 §2 exists for, and the gate this feature ships behind.** Walk the water
-    /// depth across BOTH edges and bound the step. Inside every band the pivot is continuous to
-    /// well under a millimetre per 1 mm of depth; the only steps in the whole range are the two
-    /// pinned above.
     #[test]
     fn the_corridor_is_continuous_inside_every_band() {
         let t = SWIM_PIVOT;
-        // Band A's interior, approached from dry land and stopping short of the edge.
+        // Band A's interior, from dry land to short of the edge.
         assert_bounded_step((t - 1.5, t + SURFACE_BAND - 0.01), 0.001, 0.002, |d| {
             pivot_over_surface(d, t, t)
         });
@@ -330,9 +222,6 @@ mod tests {
         });
     }
 
-    /// And the whole range in one walk, with the largest intended jump as the bound — the form
-    /// `assert_bounded_step`'s doc asks for, so a NEW cliff anywhere cannot hide behind the known
-    /// one being larger.
     #[test]
     fn the_only_jump_in_the_whole_range_is_the_dive() {
         let t = SWIM_PIVOT;
@@ -341,9 +230,6 @@ mod tests {
         });
     }
 
-    /// Turning the option off is standing on dry land — the same arm, not a second path. This is
-    /// the assertion that keeps the two halves atomic: with the CVar clear there is no corridor
-    /// AND (at the call site) no liquid in the trace mask.
     #[test]
     fn the_option_off_is_indistinguishable_from_dry_land() {
         let off = corridor_off(SWIM_PIVOT);
@@ -353,8 +239,7 @@ mod tests {
         assert_eq!(off.floor, REST);
     }
 
-    /// No liquid object is `+0.0` with both bits clear (`0x511ad0`'s null return), and a NaN depth
-    /// takes the assigning fall-through rather than poisoning the pivot.
+    /// No liquid is `0x511ad0`'s null return, `+0.0` with both bits clear.
     #[test]
     fn a_missing_surface_is_clear_and_a_nan_depth_does_not_poison_the_pivot() {
         assert_eq!(classify(None, 0.0, SWIM_PIVOT), (WaterBand::Clear, 0.0));
diff --git a/crates/benilla-app/src/player/controller.rs b/crates/benilla-app/src/player/controller.rs
index 44818cb2..33f60779 100644
--- a/crates/benilla-app/src/player/controller.rs
+++ b/crates/benilla-app/src/player/controller.rs
@@ -1,133 +1,79 @@
-//! **The per-frame player controller** — [`control`], the one system that turns this frame's input
-//! into the avatar's pose, its animation state and the packets we owe the server.
-//!
-//! It reads as a spine of named phases, and every phase that is a *concern of its own* lives in a
-//! module beside this one: [`super::input`] decodes the keys, [`super::wire_in`] applies what the
-//! server said, [`super::ride`] carries us on a deck, [`super::posture`] holds the body,
-//! [`super::mover`]/[`super::swim`] move it, [`super::flags`] builds the word, [`super::gait`] and
-//! [`super::body_pose`] render it, [`super::camera`] seats the eye, and [`super::movement_net`]
-//! streams it. What is left here is the *order* — which is itself load-bearing, because the
-//! reference's own frame runs in this order and several of the gates below only work where they
-//! stand (the swim latch before the mover, the posture commit before the pose, the ack after the
-//! launch).
-//!
-//! Split out of the module root by the same rule the rest of `player/` follows: the root is the
-//! map (the plugin, the shared types, the ordering edges), the concerns are the files.
+//! The per-frame player controller, [`control`]: this frame's input to the avatar's pose, its
+//! animation state and the packets owed the server. The phases live in sibling modules; their order
+//! here is the reference's frame order and is load-bearing (the swim latch before the mover, the
+//! posture commit before the pose, the ack after the launch).
 
 use super::*;
 
-/// Camera + avatar controller. Free-flies until the server reports our position; then takes
-/// third-person control (WASD walks the avatar; right-drag turns it, left-drag orbits the camera,
-/// wheel zooms) and streams our movement to the server as the confirmed mover. The dev chord + `F`
-/// toggles free-fly (decision 1043).
+/// Free-flies until the server places us, then drives the avatar and streams its movement as the
+/// mover; the dev chord with `F` toggles free fly.
 #[allow(clippy::type_complexity)]
 pub(super) fn control(
     time: Res<Time>,
     keys: Res<ButtonInput<KeyCode>>,
     buttons: Res<ButtonInput<MouseButton>>,
-    // Nested into one param to stay within Bevy's 16-element system-param tuple limit. (The
-    // scroll wheel left this tuple with 0997: zoom reads the CAMERAZOOM bindings now.)
-    // The pointer's motion this frame + the camera knobs that scale what it does with it — the
-    // two look/zoom knobs and the auto-follow style (decision 1493). Bundled because a Bevy system
-    // takes at most 16 parameters and this one is at the ceiling — the grouping is the existing
-    // `mouse` tuple, widened rather than a seventeenth argument.
+    // Tupled parameters keep this system under Bevy's limit of 16.
     pointer: (
         Res<AccumulatedMouseMotion>,
         Res<camera::LookConfig>,
         Res<camera::ZoomLimit>,
         Res<camera::FollowConfig>,
-        // The four 1.12 camera option toggles and their numeric siblings (decision 2149).
         Res<camera_dynamics::CameraOptions>,
-        // `nearclip`/`farclip` (2163) — the camera's own clip pair. Only the near half is read
-        // here, for the self-avatar fade's reference plane; the far half is the wall's, read by
-        // the world.
+        // Only `nearclip` is read here, for the self-avatar fade.
         Res<benilla_world::view::ViewDistance>,
     ),
-    // The net bridge, bundled into one param (16-param limit): the outbound command channel + the
-    // inbound teleport/worldport messages `apply_net_updates` wrote earlier this frame
-    // (WorldStage::Net), + the sheath-setter queue (the Z toggle's request — decision 0080).
     mut net: (
         Res<NetCommands>,
         MessageReader<TeleportMessage>,
         MessageReader<WorldportMessage>,
         MessageWriter<crate::creature_anim::SheathRequest>,
         MessageReader<crate::net::SpeedChangeMessage>,
-        // The ack'd movement-mode family (decisions 0308, 0866): root / water-walk / feather-fall /
-        // hover, granted on our mover — applied to `player.modes` and acked here with the live pose.
+        // Root, water walk, feather fall and hover on our mover, acked with the live pose.
         MessageReader<crate::net::MoveModeMessage>,
-        // The landing report for the client-side hard-landing predictor (`0x602d00` — wound
-        // vocal + dust; the consumers gate on the threshold, `creature_anim::env_damage`).
+        // The hard-landing report (`0x602d00`: the wound vocal and the dust).
         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`.
+        // The move edges the reference hands `AbortCast` (`0x6e4940`), for the cast bar.
         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.
+        // The mounted Space flourish plays locally at send; the net drain drops its echo.
         MessageWriter<crate::creature_anim::MountFlourish>,
-        // A `MSG_MOVE_*` the server addressed to our OWN mover (decision 0725) — a pose it wrote,
-        // with no handshake and no ack owed. `wire_in` snaps to it.
+        // A `MSG_MOVE_*` for our own mover: a pose the server wrote, no ack owed.
         MessageReader<crate::net::SelfMoveMessage>,
-        // The posture queue (decision 0881): `/sit` and its family ask here; the X key is read
-        // inline in [`super::posture`]. One setter, either way.
         MessageReader<StandStateRequest>,
-        // The possession handoff (B211): control of a unit granted or revoked. Lands here rather
-        // than at the net drain because both answers it needs — the mover claim and the parting
-        // pose — are the controller's to give.
+        // Control of a unit granted or revoked: the mover claim and parting pose are ours to give.
         MessageReader<crate::net::ClientControlMessage>,
-        // A knockback the server aimed at our mover (decision 1702) — `wire_in` latches it, the
-        // take-off site below flies it, and the movement stream acks it with the post-launch pose.
+        // A knockback on our mover: latched by `wire_in`, flown below, acked after the launch.
         MessageReader<crate::net::KnockBackMessage>,
-        // The tutorial system's world-input sites (1976): Movement acknowledged + the 10 s
-        // Targeting popup on a movement input, Cameras acknowledged on a mouse-look.
         crate::tutorial::InputHooks,
-        // 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`.
+        // The loot window's move-start close (`0x60e990`).
         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.
+        // `SMSG_STANDSTATE_UPDATE`, applied locally and ungated, with 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: (
         Res<MoveSpeed>,
         Res<PlayerCapsule>,
         Res<InspectMode>,
         Res<crate::ui_script::UiKeyboardCapture>,
         Res<crate::ui_script::PlayerUiClickConsumed>,
-        // The binding dispatch (decision 0997): every rebindable input below reads command
-        // state from here — raw `keys` remain only for the dev chord's free-fly toggle
-        // (decision 1043) and the look-session mouse.
+        // Every rebindable input reads here; raw `keys` serve only free fly and its chord.
         Res<crate::bindings::BindingsState>,
-        // What the camera orbits, when that is not our body ([`view_subject`], B151). Resolved by
-        // a system ordered just before us, because `control` holds the self `Transform` mutably
-        // and so cannot also read the far-sight object's.
+        // The far-sight subject, resolved earlier since this system holds our `Transform` mutably.
         Res<view_subject::ViewSubject>,
-        // Our own guid — the control handoff (B211) is a statement about *some* unit, and telling
-        // "the server revoked my body" from "the server handed me a creature" is exactly this test.
+        // Tells a revoked body from a granted creature in the control handoff.
         Res<crate::net::SelfGuid>,
-        // The spyglass scope ([`scoped_view`]): while held, the rig is pinned to first person and
-        // the wheel cannot leave it.
         Res<scoped_view::ScopedView>,
-        // Is the loading cover up? The cover takes the whole input plane at the source
-        // (`loading_screen::input`), so nothing new arrives here — but a mouse gesture already in
-        // flight is retained state, and only its owner can unwind it. See the cancel below.
+        // The loading cover blanks input at the source; a gesture in flight is unwound below.
         Res<crate::loading_screen::LoadingScreen>,
     ),
     mut commands: Commands,
     mut player: ResMut<Player>,
     mut rig: ResMut<CameraControl>,
-    // Avian's kinematic move-and-slide: sweeps the capsule against the streamed colliders (decision 0009).
     collide: benilla_world::collision::WorldCollision,
     mut cameras: Query<(&mut Transform, &mut FlyCam), With<Camera>>,
-    // **The body in our hands** — see [`BodyQuery`] for what rides on it and why a possessed
-    // creature needs nothing special here.
+    // The body we drive, a possessed creature's included ([`BodyQuery`]).
     mut body: BodyQuery,
     window: Single<(&mut Window, &mut CursorOptions), With<PrimaryWindow>>,
-    // Clicks go out here — left for the target picker, right for the context action (attack) — and
-    // the third is the right button's raw DOWN edge (targeting's cancel, decision 0792). A press
-    // engages its camera look *and* arms a click test; the release settles that test on the
-    // reference's time/travel predicate, so one gesture can orbit and select both (decision 1122).
-    // The locals hold each button's pending [`camera::PressGesture`] (`None` = no press pending).
+    // A press starts a look and arms a click test, which the release settles on time and travel.
     mut world_clicks: (
         MessageWriter<WorldClick>,
         MessageWriter<WorldRightClick>,
@@ -137,11 +83,7 @@ pub(super) fn control(
         Local<Option<camera::PressGesture>>,
         Local<Option<camera::PressGesture>>,
     ),
-    // World context for the mover, bundled into one param (16-param limit): the world query the
-    // swim mode + buoyant float ask the liquid through (see [`swim`]), the armed transports (the
-    // platform-frame carry/attach — decision 0438 phase 2; `Without`s only disjoint the borrows),
-    // and the parent chain (the attach walk resolves a deck prop's collider child to the
-    // transport that owns it — solid cargo, 0470).
+    // The liquid query, the transports, and the parent chain from a deck collider to its transport.
     world_q: (
         benilla_world::world_point::WorldPoint,
         TransportQuery,
@@ -169,10 +111,7 @@ pub(super) fn control(
     let self_guid = speed_capsule.7 .0;
     let scoped = &speed_capsule.8;
     let covered = speed_capsule.9.covering();
-    // The auto-follow knobs (decisions 1493/1502), with far sight's one exception folded in here so
-    // both camera seats below agree: while the rig orbits somebody ELSE's body (Mind Vision, Sentry
-    // Totem), our own facing is not what "behind" means, so the return is forced off rather than
-    // reeling that camera toward a heading with nothing to do with the view.
+    // Far sight turns the auto-follow off: our facing is not "behind" for a body we only watch.
     let follow_cfg = camera::FollowConfig {
         style: if view_subject.remote.is_some() {
             camera::FollowStyle::Never
@@ -187,47 +126,29 @@ pub(super) fn control(
         ..*pointer.3
     };
     let dt = time.delta_secs();
-    // While a focused UI EditBox (the chat input, a mail field) owns the keyboard, keyboard reads see
-    // "no keys held" — so the avatar isn't also driven while typing (a `.tele` command). Mouse still
-    // works. The gate is `UiKeyboardCapture::typing`, which the focused chat EditBox drives —
-    // deliberately not its per-key `consumed` twin (2196): that one says a keyboard FRAME ate one
-    // key, whose business is that key's binding, not whether a dev free-cam may read WASD. The free-fly
-    // chord below is deliberately outside it, like every dev chord ([`modkeys::dev_chord`]).
+    // Free fly reads no keys while an EditBox is `typing` (not the per-key `consumed`, a binding's
+    // concern); `binds` applied that gate when it latched, and the dev chords ignore it.
     let typing = ui_capture.typing;
-    // The rebindable inputs all read `binds` (decision 0997): the dispatch already enforced the
-    // typing gate and 0585's exact-modifier law when it latched, so this module carries neither
-    // anymore. Nothing here reads a bare key any more (decision 1043) — the free-fly toggle is on
-    // the dev chord, and the Ctrl run boost is gone.
 
-    // Which mouse buttons the world owns this frame is [`camera::latch_world_mouse`]'s, decided
-    // in a system ahead of this one (ledger B364). Every *press* below is taken from that latch —
-    // the look session's engage, the camera's command word, the both-button run — so a press the
-    // UI ate reaches none of them. The raw buttons are still read below, but only for the hold and
-    // release of a gesture the world already owns.
-    // The both-button state and the camera's input command word ([`input::look_input`]) — read
-    // here, before the look session, because the not-driving path below seats its camera from the
-    // same word and returns without ever reaching the movement axes.
+    // Every press below comes from `camera::latch_world_mouse`, so one the UI ate reaches none of
+    // them; the raw buttons only hold and release a gesture the world already owns. Read before
+    // the look session: the not-driving path seats its camera from this word and returns early.
     let input::LookInput {
         both_buttons,
         follow_command,
     } = input::look_input(binds, &player, &rig);
 
-    // The camera-option inputs (decision 2149). `translating` is **last frame's** wire word, and
-    // deliberately: the reference's `0x50fee0` runs from the input handler `0x514446`, which
-    // precedes the mover lookup, so it reads the movement flags the previous update left. It is
-    // also all this path can read — `flags::this_frame` runs several hundred lines below, after
-    // the mover.
+    // Last frame's word, as `0x50fee0` reads it: its caller `0x514446` precedes the mover lookup.
     let dynamics = camera_dynamics::DynamicsInput {
         options: *pointer.4,
         nearclip: pointer.5.nearclip,
-        // Last frame's cached surface — the reference's own lag (`Player::liquid_surface`).
+        // Last frame's cached surface, the reference's own lag.
         surface_y: player.liquid_surface,
         smooth_style: pointer.3.style,
         tracking_style: pointer.3.tracking_style,
         subject: camera_dynamics::SubjectState {
             move_flags: player.move_flags,
-            // Off the DRIVEN body's descriptor (1277) — a possessed creature's taxi state is what
-            // the camera follows, not ours.
+            // The driven body's descriptor: a possessed creature's taxi state, not ours.
             taxi: body
                 .single()
                 .ok()
@@ -241,10 +162,7 @@ pub(super) fn control(
                 .ok()
                 .and_then(|(_, _, _, _, _, store, ..)| store)
                 .is_some_and(|s| s.0.unit_mount_display_id() > 0),
-            // `GetCurrentSpeed 0x7c4c90` on the mover's own speed set, against LAST frame's flag
-            // word — the same pairing the reference's bob kernel makes, and the only speed either
-            // camera seat below can ask for (the driving path's own is computed hundreds of lines
-            // later, and the stand-down path never computes one at all).
+            // `GetCurrentSpeed` (`0x7c4c90`) on the mover's speeds and last frame's word.
             speed: body
                 .single()
                 .ok()
@@ -255,34 +173,16 @@ pub(super) fn control(
         },
     };
 
-    // The look session gets a SHADOW copy of `CursorOptions`, written back only on a real change:
-    // handing it the component's `Mut` directly reborrowed mutably every frame, which marks it
-    // Changed regardless of writes — and bevy_winit's `changed_cursor_options` then re-applied
-    // cursor state to AppKit per frame, an OS call that intermittently stalls the main thread for
-    // milliseconds (the 0366 frame-tail hunt's second-biggest line).
+    // A shadow copy, written back only on change: a `Mut` each frame marks `CursorOptions` changed,
+    // and bevy_winit then re-applies the cursor to the OS every frame, which can stall.
     let mut opts_shadow = cursor_opts.bypass_change_detection().clone();
-    // Snapshot for the seated-turn stand-up ([`super::posture`]): a right-drag (or both-button) look session
-    // writes `face_yaw` directly — any change is a real mouse TURN of the character (a left-drag
-    // orbits the camera only and never touches it).
+    // The facing before the look session, restored below when the mouse may not turn the body.
     let yaw_before_look = player.face_yaw;
-    // **Stunned** (`UNIT_FIELD_FLAGS & 0x40000` — decision 0872): read once here, because the very
-    // first thing a stun suppresses is the mouse turn below. This is a descriptor bit, NOT a
-    // movement flag and NOT an aura: the reference's `0x5145b0` computes `!STUNNED` straight off
-    // `[[unit+0x110]+0xa0]` (`not eax; shr eax,0x12; and eax,1`) and `0x514755` consumes it to skip
-    // the turn and pitch emitters outright.
-    // **Dead** is read in the same pass and for the same reason: the reference's two movement-input
-    // predicates share a precondition (`0x5144e0`) whose second term is `[[mover+0x110]+0x40] > 0`
-    // — UNIT_FIELD_HEALTH, the `jle` at `0x5144f8` — so a body at zero health answers *no* to both
-    // "may I translate?" (`0x514560`) and "am I not stunned?" (`0x5145b0`). **A corpse is stunned**
-    // as far as the input tick is concerned, and that is the whole reason the reference will not
-    // let you spin your own body on the ground (decision 1753). Off the MOVER's descriptor, not
-    // ours — `esi` in `0x5144e0` is whatever we are driving (1277) — and a ghost is not dead by it,
-    // because the server puts a released player's health at 1 (0308).
-    // **The stand state** is read in the same pass for the mouse alone (decision 2025): the
-    // reference's camera→body hand-off predicate `0x5145e0` ends on `GetStandState() == 0`
-    // (`0x51460c`, the CGPlayer override `0x5ed570` = the client-predicted cache), so a seated
-    // body — sitting, in a chair, asleep — is never re-faced by a right-drag, and never stood up
-    // by one either. Predicted, not merely echoed: `stand_pending` is our `[player+0x1d68]`.
+    // Off the driven body's descriptor. Stunned is `UNIT_FIELD_FLAGS & 0x40000` (`0x5145b0`),
+    // which skips the turn and pitch emitters (`0x514755`). Dead fails the shared precondition
+    // `0x5144e0` (health above zero), so a corpse is stunned to the input tick; a ghost has
+    // health 1. The stand state gates the mouse alone: `0x5145e0` wants the predicted
+    // `GetStandState() == 0` (`0x5ed570`; `stand_pending` is `[player+0x1d68]`).
     let (stunned, dead, stand_byte) = body
         .single()
         .ok()
@@ -297,15 +197,9 @@ pub(super) fn control(
         })
         .unwrap_or((false, false, 0));
     let stand_state = player.stand_pending.unwrap_or(stand_byte);
-    // The shared precondition `0x5144e0`, assembled once for this tick the way the reference
-    // evaluates it once for the mover — health above, and the far-sight conjunct here.
-    //
-    // **Conjunct 5** is `!(IsActivePlayer(mover) && [mover+0x1c70] & 1)`: while your view is out on
-    // a far-sight object you may not drive your own body. Both halves matter. The latch half is the
-    // **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.
+    // The shared precondition `0x5144e0`, once per tick. Its far-sight conjunct,
+    // `!(IsActivePlayer(mover) && [mover+0x1c70] & 1)`, reads the resolved subject (`0x5ee290`
+    // latches only once resolved) and spares a possessed mover, which sets the same field.
     let mover = state::MoverInput {
         dead,
         view_is_out: state::view_is_out(
@@ -313,17 +207,12 @@ pub(super) fn control(
             view_subject.remote.is_some(),
         ),
     };
-    // `0x5145b0`, evaluated here because the first thing it suppresses is the mouse turn below. Its
-    // translate sibling waits until after `apply_server_moves`, where the root edge it reads lands.
+    // `0x5145b0` now, for the mouse turn; its translate sibling waits for this frame's root edge.
     let may_turn = mover.may_turn(stunned);
-    // `0x5145e0`, the mouse's own hand-off gate — `may_turn` plus the stand-state conjunct the
-    // keyboard path does not have (it stands you up instead; the mouse is refused).
+    // `0x5145e0`: `may_turn` and standing; a turn key stands a seated body up instead.
     let mouse_turns_body = mover.mouse_may_turn_body(stunned, stand_state);
-    // Drunkenness (B210): this frame's wobble angle, computed once — the facing veer and the
-    // swim-pitch porpoise ([`swim::drive_step`]) both read it. Zero while sober (`wobble` early-outs on a 0.0
-    // fraction), and zero whenever the turn predicate is down — the reference's wobble sits behind
-    // the same input-allowed chain as the turn emitters (`0x60aa47` → `0x5145b0`), so a stun stops
-    // it and, through the precondition that predicate shares, so does death.
+    // The drunk wobble, for the veer and the swim porpoise; zero when turning is refused, as the
+    // reference's sits behind `0x5145b0` (`0x60aa47`).
     let drunk_wobble = {
         let f = body
             .single()
@@ -336,16 +225,8 @@ pub(super) fn control(
             drunk::wobble(time.elapsed().as_millis() as u32, f)
         }
     };
-    // **A cover cancels a gesture; it never completes one.** The cover emptied the button planes
-    // in `PreUpdate`, so the look session below ends on its own this frame — and ending it also
-    // *settles* the click test the press armed, against `PressGesture::is_click`'s free window. A
-    // right-press 0.1 s before a portal would therefore have dispatched a `WorldRightClick` under
-    // the loading screen, acting on the pick latched in the world we just left. Dropping both
-    // tests first leaves the session to end with nothing to fire. This is the one place the cover
-    // has to be named by hand: taking the input away cannot rewind a state machine that is already
-    // mid-gesture, and this system owns the only such state the world side has (the UI's own armed
-    // press/drag is unwound by `UiScript::pointer_left_window`, which the blanked cursor already
-    // triggers).
+    // A loading cover cancels a gesture in flight: ending the look session would settle its click
+    // test and click the world we just left, so the tests are dropped first.
     if covered {
         *left_click = None;
         *right_click = None;
@@ -370,47 +251,11 @@ pub(super) fn control(
         &dynamics,
         time.elapsed_secs(),
     );
-    // A stun freezes the BODY, not the view. The look session has already moved `cam.yaw` (and, on
-    // a right-drag, coupled `face_yaw = cam.yaw`); putting the aim back leaves the camera orbiting
-    // a body that does not turn — which is what a stunned character looks like, and what the
-    // reference produces by never running the turn emitter at all. Restoring rather than gating
-    // inside the session keeps the approved camera path (0050/0366's right-drag coupling) untouched.
-    // (Nothing downstream can tell: the mouse turn no longer stands a seated player either — 1766.)
-    // Losing the reins has the same shape, and the binary says so explicitly: with the mover global
-    // zeroed, `0x514640` skips the whole tick at `51466c` — input is still *sampled*, the body turn
-    // is skipped at `514474` — while the camera rotate at `514444` happens BEFORE the mover lookup
-    // and so keeps working. A mind-controlled player can still look around; they just cannot turn
-    // or move their body. Same restore, for the same reason — and `reseat` is the same condition
-    // once more, the frames where the mover global would not resolve at all.
-    //
-    // Holding *somebody else's* reins is emphatically not in this set: the turn belongs to whatever
-    // we are driving, and once the marker has caught up that is the creature, whose `Transform` is
-    // the one this `face_yaw` writes.
-    //
-    // **Death enters through the same door** (decision 1753) — but by its own byte trail, not the
-    // keyboard's, and the two are worth keeping apart. The reference's right-drag lives in
-    // `0x514400`, off the mouse-MOVE handler `0x492c00`, and its body hand-off
-    // `0x51447b call 0x5103e0` is gated at `0x514474` by a THIRD predicate, `0x5145e0`, whose first
-    // act is to call the stun test `0x5145b0` — which fails the precondition `0x5144e0` it shares
-    // with the translate gate at zero health, and short-circuits the rest. The two commit gates
-    // 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.
-    //
-    // 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
-    // on the ground. Note the reference has **nothing to restore** — it never writes the facing at
-    // all, because `0x50fee0` (the camera rotate at `0x514446`) runs before any object lookup and
-    // the hand-off simply does not run. Ours writes and puts back, which is indistinguishable
-    // downstream and keeps the approved camera path intact — a shape difference, not a copy.
-    //
-    // **A seated body enters through the same door too** (decision 2025). `0x5145e0`'s last
-    // conjunct is `GetStandState() == 0` — the right-drag orbits the camera round a body that keeps
-    // facing its chair, sends nothing, and does not stand it up (1766 had already taken the stand
-    // off this gesture; this takes the turn off it). Stand up — X, a turn key, a flick — and the
-    // next motion sample hands the camera's yaw to the body again, which is the snap the reference
-    // shows too: `0x5103e0` commits the camera's own facing, not a delta.
+    // The mouse turns the view, but the body hand-off (`0x514474`) skips a body that is stunned,
+    // dead or seated (`0x5145e0`) or not ours to drive (`control_lost`, `reseat`), while the
+    // camera rotate (`0x514444`) still runs. The reference never writes the facing; writing and
+    // restoring is the same downstream. Standing up hands the camera's yaw back at the next
+    // motion sample, a snap, as `0x5103e0` commits the camera's facing rather than a delta.
     if !mouse_turns_body || player.control_lost || player.reseat {
         player.face_yaw = yaw_before_look;
     }
@@ -424,26 +269,18 @@ pub(super) fn control(
         }
     }
 
-    // Camera zoom rides the CAMERAZOOMIN/OUT bindings (0997; defaults = the wheel pair). The
-    // wheel-over-UI routing lives in the dispatch now — a wheel the quest log consumed never
-    // reaches these commands — and a rebound zoom KEY steps 1.0 per press, 1.12's own
-    // `CameraZoomIn(1.0)` argument.
+    // A rebound zoom key steps 1.0 per press, the stock `CameraZoomIn(1.0)` (`Bindings.xml:707`).
     let zoom = binds.amount(crate::bindings::cmd::CAMERA_ZOOM_IN)
         - binds.amount(crate::bindings::cmd::CAMERA_ZOOM_OUT);
     apply_zoom_scroll(zoom, dt, &mut rig, zoom_max);
 
-    // Free-fly is a dev instrument, so it sits on the dev chord, not a bare `F` (decision 1043).
-    // A bare `F` is a key the reference lets a player bind — our own store test binds it to JUMP —
-    // and a dev doesn't get to squat on the game's namespace (0585, the same rule that moved the
-    // perf HUD off bare `P`). Ungated on `typing` like every chord: it can't be mistaken for text.
+    // Free fly is a dev tool on the dev chord: a bare `F` is the player's to bind.
     if crate::run_mode::dev_chord(&keys, KeyCode::KeyF) {
         player.detached = !player.detached;
     }
 
-    // Server-authored movement edges + their mandatory acks (worldport/teleport snaps, root,
-    // water-walk, the take-control edge — [`wire_in`]). The returned forced-speed changes were
-    // already acked pre-control/detached; controlled, the movement stream below acks them with
-    // its live per-frame payload.
+    // The server's movement edges and their acks. Speed changes come back unacked while we drive,
+    // for the movement stream to ack with the live pose.
     let speed_acks = wire_in::apply_server_moves(
         &time,
         &mut commands,
@@ -466,46 +303,21 @@ pub(super) fn control(
 
     let flat = |v: Vec3| Vec3::new(v.x, 0.0, v.z).normalize_or_zero();
 
-    // The platform carry ([`ride::carry`], decision 0438 phase 2): while attached to a transport,
-    // recompose the whole rider — feet, aim, rendered body and camera — from the boat's THIS-frame
-    // pose, before any input integrates.
+    // On a transport, recompose the rider from the deck's pose this frame, before input integrates.
     ride::carry(&mut player, &mut cam, transports);
 
     if player.active && !player.detached {
-        // Server ride guard: a server-authored spline (Charge/knockback/taxi) owns the avatar this
-        // frame. `drive_self_ride` (ordered just before us) already synced `player.pos` + facing from
-        // the `sample_splines` transform and set the run animation; here we only carry the
-        // follow-camera onto the moving avatar. Input, physics, and the outbound movement stream all
-        // yield until the ride ends (where `drive_self_ride` acks `CMSG_MOVE_SPLINE_DONE` and resumes).
-        // **The three ways of not driving**, and they share every line of their answer: the camera
-        // keeps seating on the body, input and physics and the outbound stream all yield.
-        //
-        // - `server_riding` — a server-authored spline (Charge/knockback/taxi/a flee path) owns the
-        //   avatar. `drive_self_ride`, ordered just before us, has already mirrored the sampled
-        //   transform into `Player`, so there is nothing to sync and nothing to park: it is
-        //   reporting FORWARD on the wire on purpose.
-        // - `control_lost` (B211) — somebody else is driving our body, or the body in our hands has
-        //   been feared out of our control. It is NOT the free-fly branch below, which would fly
-        //   the camera off the body; and it is not root, which leaves turning live. Nothing else
-        //   will stop us: the server neither roots the victim nor validates their movement, so this
-        //   gate IS the immobility (see `Player::control_lost`).
-        // - [`Player::reseat`] — the window between mover guids where what we intend to drive and
-        //   what carries `Embodied` have not yet met: the frame a grant lands, and every frame
-        //   after it while the claimed unit has not streamed in. Driving during that window writes
-        //   one body's pose onto another, because outbound moves carry no guid of their own.
-        //   `apply_server_moves` above closes it the moment a pose is there to adopt, so this is
-        //   normally a single frame.
-        //
-        // Note the middle one is deliberately NOT "we are possessing": once the marker has caught
-        // up, possession runs the *ordinary* controlled path below, on the creature (decision 1277).
+        // Not driving, while the camera stays on the body and input, physics and the stream yield:
+        // - `server_riding`: a server spline (Charge, knockback, taxi, a flee path) owns the body;
+        //   `drive_self_ride` has mirrored it into `Player`, reporting FORWARD on purpose.
+        // - `control_lost`: someone else, or fear, drives our body. The server neither roots nor
+        //   validates the victim, so this gate is the immobility.
+        // - `reseat`: the mover guid is changing and the claimed unit has not streamed in; moves
+        //   carry no guid, so driving would write one body's pose onto another.
+        // Possession is none of these: it runs the ordinary path below, on the creature.
         if player.server_riding || player.control_lost || player.reseat {
-            // Whoever is moving the body, its transform is the truth and `Player` follows it
-            // (decision 1281). Skipping this is what stranded the camera during a fear: the body
-            // ran off on its spline while the orbit stayed at the pose the controller last wrote,
-            // which reads as the view detaching into free flight (director, 2026-08-13). A
-            // `reseat` window is excluded — there the resource still describes the body we are
-            // letting go of, and `apply_server_moves` owns the adoption.
-            //
+            // The moving body's transform is the truth; without this the camera stays behind
+            // during a fear. Not while reseating, when `Player` still holds the body let go.
             if player.control_lost && !player.reseat {
                 if let Ok((_, t, ..)) = body.single() {
                     let yaw = server_ride::yaw_of(t.rotation);
@@ -515,28 +327,16 @@ pub(super) fn control(
                 }
             }
             let head = player.pos + Vec3::Y * (CAPSULE_HEIGHT - CAPSULE_RADIUS);
-            // Far sight outlives all three, so it has to be honoured here too — Sentry Totem
-            // carries no interrupt flags at all, which means you can board a taxi with your view
-            // still on the totem. [`camera::seat_on_subject`] is the shared substitution, which is
-            // exactly why it is shared: skipping it here would read as far sight mysteriously
-            // dropping the moment a spline takes the body.
-            //
-            // The auto-follow still runs on this path — a taxi, a Charge, a knockback or a fear
-            // all translate the avatar while the controller stands down, and the reference has
-            // states for exactly those (`Track`, `Fear`: a 0.4 s delay and a lazy 18 °/s return
-            // under Smart). The word carries both flags, so the edge into and out of one of them
-            // is what arms it.
+            // Far sight outlives all three (Sentry Totem has no interrupt flags), and the
+            // auto-follow runs through the reference's `Track` and `Fear` states.
             camera::seat_on_subject(
                 dt,
                 0.0,
                 player.pos,
                 head,
                 body.single().ok().and_then(|(_, _, _, pivot, .., net)| {
-                    // Even while a spline/taxi/fear owns the body, the pivot preset follows
-                    // that body's own MOVEFLAG_SWIMMING (`0x50f880` reads the camera target's
-                    // CMovement word, not ours). On this path the controller builds no live
-                    // flag word, so the last-streamed one — which `wire_in` merges from the
-                    // server's own poses — is the body's state.
+                    // The pivot preset follows the body's own SWIMMING (`0x50f880`), here the
+                    // last streamed word, which `wire_in` merges from the server's poses.
                     body_pose::pivot_target(
                         pivot,
                         net,
@@ -555,19 +355,15 @@ pub(super) fn control(
                 },
                 &dynamics,
             );
-            // Flush a stale run once, so observers stop extrapolating it — but never under a ride,
-            // whose FORWARD report is deliberate and would be cancelled every frame.
+            // Flush a stale run once, but never under a ride, whose FORWARD is deliberate.
             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.
+            // After the park, so a fear's ack carries the stopped word.
             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
-        // latch with its verified cancel set — all of it decoded once in [`input::move_axes`].
-        // `0x514560`, evaluated now — after `apply_server_moves`, so a root edge that landed this
-        // frame is already in `player.modes` and not read a frame late.
+        // `0x514560`, after `apply_server_moves`, so this frame's root edge is already in `modes`.
         let may_translate = mover.may_translate(player.modes.rooted);
         let axes = input::move_axes(
             binds,
@@ -589,28 +385,21 @@ pub(super) fn control(
             turn_right,
             ..
         } = axes;
-        // The world-input tutorial sites (1976): a movement input, a mouse-look.
         if fwd_axis != 0 || side_axis != 0 {
             net.13.moved();
         }
         if mouselook {
             net.13.mouselooked();
         }
-        // **The mover's own** six speeds, read once here for the whole frame — the turn below and
-        // the run/backpedal selection further down. All six live on the driven unit's `CMovement`
-        // and nothing in the reference's applied-input path ever reads *our* speeds when the mover
-        // is a different object (VERIFIED, decision 1278), so a possessed creature moves and turns
-        // at its own numbers for free: the component was on its entity all along.
+        // The driven unit's own speeds: the reference's input path never reads ours for another
+        // mover, so a possessed creature moves and turns at its own.
         let mover_speeds = body.single().ok().and_then(|q| q.7).map(|s| s.0);
-        // The 6th speed. Zero is the ctor state, not a rate — the client keeps no default of its
-        // own, so a unit whose create block has not landed falls back rather than freezing solid.
+        // Zero is the ctor state, not a rate: a unit whose create block has not landed falls back.
         let turn_rate = mover_speeds
             .map(|s| s.turn_rate)
             .filter(|r| *r > 0.0)
             .unwrap_or(TURN_RATE);
-        // This frame's keyboard-turn rotation — `seat_camera` carries the camera by it rigidly
-        // (char and camera turn as one on the reference; director's call, closing 0050's open
-        // "camera follow on turn" feel item).
+        // This frame's own turn; `seat_camera` carries the camera by it, the two turning as one.
         let mut turn_delta = 0.0;
         if turning {
             let mut turn = 0.0;
@@ -620,23 +409,16 @@ pub(super) fn control(
             if turn_right {
                 turn -= 1.0;
             }
-            // 0.75× while translating **or falling** — the verified `flags & 0x200f` case, whose
-            // `0x2000` is FALLING (`0x7c5c73`). A jump mid-turn keeps the reduced rate.
+            // 0.75× while translating or falling (`flags & 0x200f`, `0x7c5c73`).
             let slowed = translating || player.airborne_since.is_some();
             let rate = turn_rate * if slowed { TURN_RATE_MOVING } else { 1.0 };
             turn_delta = turn * rate * dt;
             player.face_yaw += turn_delta;
         }
-        // The drunk veer (B210): while moving, the facing increments by the wobble angle every
-        // frame (`0x60aa70–0x60aab7`: `facing + wobble`, 2π-wrapped, committed via the normal
-        // facing pipeline `0x60de30` — so it streams on the wire like any turn). The slow sign
-        // oscillation of the pulse is what makes the walk meander. Skipped while a keyboard turn
-        // is held — the reference's `flags & 0x30` guard (`0x60aa5a`) — so deliberate turning
-        // stays crisp; both yaw conventions increase turning left, so the add maps sign-for-sign.
-        // The veer joins `turn_delta` so `seat_camera` carries the camera with it exactly like a
-        // keyboard turn (char and camera turn as one) — the reference's camera follows the drunk
-        // meander too (director's ref observation, decision 1018); without the carry the character
-        // staggers out from under a fixed camera.
+        // The drunk veer: while moving, the wobble adds to the facing every frame and commits
+        // through the facing setter, so it streams like a turn (`0x60aa70`-`0x60aab7`,
+        // `0x60de30`); a held keyboard turn skips it (`0x60aa5a`). Both yaw conventions grow
+        // leftward, and it joins `turn_delta`, so the camera follows the meander.
         if drunk_wobble != 0.0 && translating && !turning {
             player.face_yaw += drunk_wobble;
             turn_delta = drunk_wobble;
@@ -645,57 +427,34 @@ pub(super) fn control(
         let move_fwd = flat(face_rot * Vec3::NEG_Z);
         let move_right = flat(face_rot * Vec3::X);
         let mut dir = Vec3::ZERO;
-        // Forward/back comes from the net axis (W, S, both-button and autorun already summed) — one
-        // step in its sign, never a doubled push, exactly as the emitter issues one START in
-        // `sign(axis)`. (`mover::step` normalizes anyway, but the axis is the honest shape.)
+        // One step in the net axis's sign, as the emitter issues one START in `sign(axis)`.
         match fwd_axis.signum() {
             1 => dir += move_fwd,
             -1 => dir -= move_fwd,
             _ => {}
         }
-        // Strafe slides without turning, one step in the netted sign — never a doubled push, and a
-        // cancelled pair is genuinely no strafe (the same shape as the forward/back axis).
+        // Strafe likewise; a cancelled pair is no strafe.
         match side_axis.signum() {
             1 => dir += move_right,
             -1 => dir -= move_right,
             _ => {}
         }
-        // **The translate predicate down: translation intent dies here — and under a plain root,
-        // turning above stays live.** Confirmed at the bytes (decisions 0866/0872) and it is
-        // *authored*, not accidental: the reference's input
-        // tick consults an allow-list (`0x615c71` → the byte table at `0x618054`) which blocks the
-        // translation command ids and **explicitly permits** the turn ids 8/9/0xa, pitch, run/walk
-        // and SetFacing. A character who cannot even pivot is STUNNED, a separate `UNIT_FIELD_FLAGS`
-        // gate handled above — and vmangos's `HandleModStun` grants both at once, which is why Ice
-        // Block freezes completely while Frost Nova lets you turn. **Death is the third way this
-        // predicate goes down** (1753), and unlike the root it takes the pivot with it.
+        // Translation dies here, but a root leaves turning live: the reference's allow-list permits
+        // the turn, pitch, run/walk and SetFacing commands (`0x615c71`, `0x618054`). A stun, which
+        // vmangos applies with a root (`SpellAuras.cpp:3502`), or death stops the turn as well.
         if !may_translate {
             dir = Vec3::ZERO;
         }
         let moving = dir != Vec3::ZERO;
-        // The character's own KEYBOARD turn this frame (or the drunk veer, which rides `turn_delta`
-        // 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. 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
-        // **release**: a press-to-release under 200 ms with under 2.25° of yaw is dispatched as a
-        // right-CLICK (`0x514ae0`, which is [`camera::PressGesture::is_click`] here), and the
-        // click's INTERACT reaches `SetStandState(0)`. So the stand belongs to the click, and it
-        // lives in [`crate::target::click`] now — a deliberate turn-drag leaves you seated.
+        // A keyboard turn or the veer stands a seated body; a mouse turn does not, since the
+        // facing commit refuses a seated player (`0x51460c`, `0x51520a`) and the turn emitter
+        // skips its stand arm while the right button is held (`0x514f6d`). A right-click stands
+        // you instead (`0x514ae0`, `camera::PressGesture::is_click`; `crate::target::click`).
         let turned = turn_delta != 0.0;
-        // The gait toggle (`TOGGLERUN`) — the walk/run latch, run here so the speed select
-        // below reads the bit this frame's press left, which is the reference's own order
-        // (`ToggleRun` is an input-phase command; the mover reads `CMovement+0x40` after it).
-        // [`super::walk`] owns the latch and the refusal chain.
+        // `TOGGLERUN` before the speed select, which reads the bit this frame's press left: the
+        // mover reads `CMovement+0x40` after the input phase.
         walk::update(&mut player, &body, binds);
-        // Posture ([`posture`]) — the stand state (`X` and the `/sit` family) and the sheath
-        // toggle (`Z`), which interlock: the stow rider fires off the stand state this commits,
-        // and the toggle's guard chain refuses on it. Returns the **committed** state, which the
-        // body pose below streams to the animation selector.
+        // The stand state and the sheath toggle, which interlock; returns the committed stand.
         let stand_now = posture::update(
             &mut player,
             &body,
@@ -707,16 +466,10 @@ pub(super) fn control(
             moving,
             turned,
         );
-        // Backpedaling is slower: the backward move-flag selects the backward speed, dominating
-        // strafe (binary-VERIFIED — see RUN_BACK_RATIO). Net-backward = the S key held without a
-        // forward override (W or both-button run). The resulting (slower) speed also feeds jump
-        // takeoff, so a backward jump lands shorter for free.
+        // The backward flag selects the backward speed over strafe; a backward jump lands shorter.
         let net_backward = fwd_axis < 0;
-        // The mover's speed SET this frame: server-authoritative (`UnitSpeeds` — seeded by our
-        // create's LIVING block, moved live by SMSG_FORCE_*_SPEED_CHANGE, so `.modify speed`,
-        // mounts and slows actually move us at the server's number), or the `$WOW_MOVE_SPEED` dev
-        // override's synthetic set, which keeps the vanilla 2.5/4.5/7.0 ratios so that walking and
-        // backpedaling stay themselves under it. Pre-create frames take the same fallback.
+        // The server's speeds (the LIVING block, then `SMSG_FORCE_*_SPEED_CHANGE`), or before the
+        // create and under the `WOW_MOVE_SPEED` override, a set at the 2.5/4.5/7.0 ratios.
         let speeds = match mover_speeds {
             Some(s) if !move_speed.env_override => s,
             _ => benilla_protocol::MoveSpeeds {
@@ -726,16 +479,9 @@ pub(super) fn control(
                 ..Default::default()
             },
         };
-        // …turned into a yards/second by the ONE statement of the reference's
-        // `GetCurrentSpeed 0x7c4c90` ([`crate::net::current_speed`]), the same call the remote
-        // extrapolator makes — so our own body and every body we watch agree about the cascade,
-        // including the part that is easy to get backwards: **the walk arm is taken before the
-        // backward min**, so walking backwards is walk speed (2.5), not run-back (4.5).
-        //
-        // The flag word handed over is this frame's *gait intent*, not the wire word — that one is
-        // built later, after the mover has run ([`super::flags::this_frame`]). Only the three bits
-        // the ground cascade reads are needed and all three are known here; swimming never reaches
-        // this arm ([`super::swim`] owns its own leg of the same getter).
+        // `GetCurrentSpeed` (`0x7c4c90`), shared with the remote extrapolator: the walk arm comes
+        // before the backward min, so walking backwards is walk speed. It takes this frame's gait
+        // intent, since the wire word is built after the mover.
         let speed = crate::net::current_speed(
             &speeds,
             if net_backward {
@@ -748,72 +494,38 @@ pub(super) fn control(
                 0
             },
         );
-        // Root is refused HERE (the reference refuses it twice upstream of the handler: the Lua
-        // gate's `test ch,0x12` and the replay allow-list `0x615c71`/`0x618030`, where command
-        // id 7 is blocked). HOVER's refusal is NOT here — it belongs to the movement handler
-        // itself (`0x7c623a`, the breach term below and [`mover::step`]'s grounded arm), which
-        // is what keeps the mounted flourish reachable while hovering, as the reference has it.
-        //
-        // **And death is refused here too** — `may_translate` and not `!rooted`, which corrects
-        // 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.
+        // `Jump` (`0x513bd0`) inlines `0x5144e0` and `0x514560`, which is `may_translate` term for
+        // term: health, root and stand state 7. Hover's refusal is the movement handler's
+        // (`0x7c623a`), which keeps the mounted flourish reachable while hovering.
         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`,
-        // the verified `0x6030c0` boundary — B7 resolved, decision 0226) so wading the line
-        // doesn't flicker between the two physics regimes.
+        // Swim or walk, latched with hysteresis at the `0x6030c0` boundary against flicker.
         let surface_y = swim::surface_over_feet(world, player.pos);
-        // Cache it for the camera's water corridor, which reads it a frame later exactly as the
-        // reference's `0x670630` accessor does (see `Player::liquid_surface`).
+        // For the camera's water corridor, which reads it a frame late, as `0x670630` does.
         player.liquid_surface = surface_y;
         let swimming = swim::update_swimming(&mut player, surface_y, time.elapsed_secs());
         if let Some(surface) = surface_y {
             move_trace::swim(player.pos.y, surface, swimming, player.collision_height.0);
         }
-        // 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 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
-        // frame — the byte handler runs before the mover, clearing SWIMMING unconditionally —
-        // so the latch drops now and this frame's mover, flags, and wire all see the leap as a
-        // jump.
-        // 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. 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
-        // that gate is the point: `0x7c6236 test eax,eax; je 0x7c6243` skips the hover refusal when
-        // `force` is 0, so this leg jumps a body that is *already* hovering — which is every body
-        // that just got granted hover. The two refusals it keeps are ROOT and FALLING
-        // (`0x7c625c test ah,0x30`); the seed select at `0x7c6261` is shared, so the swim/land
-        // choice is made below by the same two take-off sites Space uses.
+        // Space while swimming is the Jump command (`0x7c6230`), once per press: it breaches at
+        // the surface and hops about 1.6 yd below it, re-latching swim once the launch halves
+        // (`0x7c5de0`). It clears SWIMMING before the mover, so this frame's mover, flags and wire
+        // see a jump. Hover refuses it (`0x7c623a`, ahead of the take-off select at `0x7c6261`),
+        // and hover does not stop swim entry (`0x6030c0` tests only LEVITATING).
+        //
+        // The `Jump(force = 0)` a hover grant owes: `force` 0 skips the hover refusal (`0x7c6236`),
+        // so it launches a body already hovering; root and falling still refuse it (`0x7c625c`).
         let wire_jump = player.take_wire_jump();
-        // **The knockback the server aimed at us** (decision 1702) — taken at the same site as the
-        // other two take-offs so all three enter the mover through one door. Resolved here from the
-        // wire quad into one Bevy launch velocity: the horizontal is `(cos, sin)·xy_speed` in
-        // **absolute world XY** (nothing to do with our facing or our keys), and the vertical is
-        // `−zspeed`, because the wire's take-off speed is DOWN-positive — the same convention the
-        // jump tail this quad is about to be echoed back as already uses (decision 0054).
+        // The knockback: horizontal `(cos, sin) · xy_speed` in absolute world XY, vertical
+        // `−zspeed`, since the wire's take-off speed is down-positive, as in the jump tail.
         let knockback = player.take_knockback();
         let knock_launch = knockback.map(|k| {
             let (c, sn, xy) = (k.launch.cos_angle, k.launch.sin_angle, k.launch.xy_speed);
             wow_to_bevy([c * xy, sn * xy, -k.launch.zspeed])
         });
 
-        // A knockback lifts a swimmer clear of the water like any other take-off — it sets FALLING,
-        // and FALLING and SWIMMING are exclusive. It is NOT routed through `breach_step`, though:
-        // that arm exists to seed `SWIM_JUMP_SPEED`, and a knockback brings its own seed on both
-        // axes, so it leaves the water here and is flown by the ordinary land mover below.
+        // A knockback sets FALLING, which excludes SWIMMING; it brings its own launch, so the land
+        // mover flies it, not `breach_step`.
         let breach = swimming && (want_jump && !player.modes.hover || wire_jump);
         let knock_breach = swimming && knock_launch.is_some();
         if breach || knock_breach {
@@ -821,26 +533,17 @@ pub(super) fn control(
         }
         let swimming = swimming && !breach && !knock_breach;
 
-        // The netted swim translation amounts ([`swim::translate_amounts`]) — read by the swim
-        // mover arm AND the flag build, so the two can never disagree (decision 0056).
+        // Read by both the swim mover and the flag build, so the two cannot disagree.
         let (swim_fwd, swim_side) = if swimming {
             swim::translate_amounts(&axes, !may_translate)
         } else {
             (0.0, 0.0)
         };
 
-        // 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
-        // (the `0x30` turn flags) → a silent no-op** — the press is consumed, nothing plays;
-        // airborne → silent no-op (the client's geometric ground-clearance test `0x605650`;
-        // 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
-        // (Space is the Jump command `0x513bd0`; it is NOT a pitch or ascend input) — and never
-        // reaches this walk-side gate.
+        // The mounted Space flourish, the jump-key handler `0x60dea0`: mounted, still and grounded
+        // plays MountSpecial (94) locally, then sends `CMSG_MOUNTSPECIAL_ANIM`; moving jumps;
+        // turning in place eats the press. Airborne, the press falls through and the mover drops
+        // it (the reference's ground-clearance test `0x605650`; the airborne arc stands in).
         if want_jump && !moving && !swimming && player.airborne_since.is_none() {
             if let Ok((e, .., store, _, _, _, _, _)) = body.single() {
                 if store.is_some_and(|s| s.0.unit_mount_display_id() != 0) {
@@ -853,50 +556,19 @@ pub(super) fn control(
             }
         }
 
-        // This frame's PRESENTED swim pitch — the persistent [`Player::mover_pitch`] while swimming
-        // (held even idle, the client's `CMovement+0x20`), except leveled by the 0499 surface
-        // redirect when the rest-line cap bites. Feeds the body pose and the wire pitch tail (one
-        // 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 (`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
-        // re-points travel the same frame, zero lag. (The ref's `fchs` negate is its own camera
-        // sign convention; ours maps aim-up to pitch-up already.) A left-drag camera orbit steers
-        // NOTHING — it moves the camera without turning the character (the walk rule at `move_fwd`
-        // above), so it must not bend the swim either (director-reported, 2026-07-18).
-        //
-        // 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.
-        // 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.
-        //
-        // The push is **per mouse-move, not per frame** ([`Player::aim_pitch_seen`]): the ref's
-        // enqueue hangs off the mouse-MOTION event `0x400500cb`, so a still mouse pushes nothing
-        // and the other writers of the field — the wobble, StopSwim's levelling — survive.
-        //
-        // **The aim is the COMPOSITE, not the camera's own pitch** (decision 2149): the reference's
-        // camera→body hand-off `0x5103e0` clamps `[cam+0x104] + [cam+0xf4]` to ±89° before passing
-        // the pitch on, so a smart-pivot frame — where the arm's pitch does not move and the view's
-        // does — still aims the body. The bias is zero except on those frames, so this reads as
-        // `cam.pitch` everywhere else.
+        // The mover pitch (`CMovement+0x20`), in every mode: held when unsteered (`0x7c4f80`) and
+        // set by mouse look to the aim through `SetPitch` (`0x7c6f70`), an unconditional store
+        // clamped ±89° (the ±π/2 clamp is the pitch keys'), whose write precedes its SWIMMING test
+        // (`0x7c6f91`). A left-drag orbit steers nothing. It is written per mouse motion (event
+        // `0x400500cb`), not per frame, so other writers survive a still mouse. The aim includes
+        // the pivot bias, as `0x5103e0` passes `[cam+0x104] + [cam+0xf4]`.
         let aim_pitch = cam.pitch + rig.smart_pivot.bias();
         if mouselook && aim_pitch != player.aim_pitch_seen {
             player.aim_pitch_seen = aim_pitch;
             player.mover_pitch = aim_pitch.clamp(-MOUSELOOK_PITCH_CLAMP, MOUSELOOK_PITCH_CLAMP);
         }
         let mut swim_pitch = 0.0_f32;
-        // The ground height the mover starts this frame at (pre-step feet Y). For a jump this is the
-        // true takeoff height — the mover integrates one jump-tick upward *within* the step, so the
-        // post-step `pos.y` is already ~0.13 yd (60 fps) above the ground and must not be used as
-        // the launch height (see [`Player::advance_airborne_arc`]).
+        // Pre-step feet Y, the true take-off height: the step already rises one jump tick.
         let launch_y = player.pos.y;
         let mover::Outcome {
             held,
@@ -906,20 +578,11 @@ pub(super) fn control(
             air_nudged,
             ground,
         } = if breach {
-            // 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
-            // the upward velocity halves (`update_swimming`'s verified `0x7c5de0` gate). The wire
-            // streams it as a normal JUMP: fall clock 0, the seeded zspeed in the tail —
-            // `advance_airborne_arc` snapshots it like any land jump ([`super::flags`]).
+            // Jump while swimming (`0x7c6230`): falls unconditionally, seeded about 14% over a land
+            // jump, and streams as a normal jump.
             swim::breach_step(&mut player, &time, &collide, capsule)
         } else if swimming {
-            // One swimming frame ([`swim::drive_step`]): the drunk porpoise, the pitched travel
-            // basis, the directional speed select, the stroke rate, and the float physics. It also
-            // decides this frame's PRESENTED pitch — the raw aim, except leveled by the 0499
-            // surface redirect when the rest-line cap bites.
+            // One swimming frame; it also picks the presented pitch, levelled at the surface cap.
             let frame = swim::drive_step(
                 &mut player,
                 &time,
@@ -936,20 +599,9 @@ pub(super) fn control(
             swim_pitch = frame.pitch;
             frame.outcome
         } else {
-            // The kinematic mover step — walk/fall physics + the step-down snap (decisions
-            // 0009/0182/0190); the mechanism lives in [`mover`].
-            // **Water walking** (decisions 0866 + 1611): hand the mover the liquid surface, which
-            // it treats as ordinary ground — the classify sees it, the grounded arm runs, and the
-            // clamp finalises Y ([`mover::step`], where the *why* of both halves lives). In the
-            // reference this is not a floor that gets handed anywhere: `MOVEFLAG_WATERWALKING` ORs
-            // the ADT liquid layers into the walk trace's class mask (`0x63162e`), so the surface
-            // simply *is* geometry. Passing it down is our stand-in for that, because liquid is
-            // queried rather than swept here.
-            //
-            // All three of the arm's gates live in [`mover::water_floor`], where each one's byte
-            // site and its consequence are written out — including the pitch gate that 1611 could
-            // only *name*, because the pitch was steered inside the swim branch until 1616's
-            // hoist put it above this call.
+            // Water walking hands the mover the liquid surface as ground ([`mover::water_floor`]),
+            // where the reference ORs the liquid layers into the walk trace's class mask
+            // (`0x63162e`); liquid is queried here rather than swept.
             let water_floor = mover::water_floor(
                 player.modes.water_walking,
                 swimming,
@@ -968,37 +620,22 @@ pub(super) fn control(
                 wire_jump,
                 knock_launch,
                 water_floor,
-                // **The air-control nudge speed is `min(MOVE_WALK, MOVE_RUN)`, read live**
-                // (decision 1740) — the walk override inside the reference's `0x7c4c90(1)`
-                // (`0x7c4d19`/`0x7c4d1b`), not a constant. `AIR_NUDGE_SPEED`'s 2.5 is the default
-                // `MOVE_WALK` and stays as the fallback for before the server has sent us speeds;
-                // once it has, a walk aura, a Slow or a daze moves this with them, and the min is
-                // why a *slowed* run still cannot out-steer a walk.
+                // The air nudge speed is `min(walk, run)`, live (`0x7c4c90(1)`, `0x7c4d19`), with
+                // the default walk speed until the server sends speeds.
                 mover_speeds.map_or(super::AIR_NUDGE_SPEED, |s| s.walk.min(s.run)),
             )
         };
 
-        // The knockback's own trace line (decision 1702) — flown or refused, with the quad. Emitted
-        // here because this is the first point where both halves are known: the latch we took, and
-        // the mover's verdict on it.
+        // Traced here, the first point that knows both the latch and the mover's verdict.
         if let Some(k) = knockback {
             move_trace::knockback(knocked, k.launch);
         }
 
         let now = time.elapsed_secs();
-        // Airborne is a walk-only concept — swimming never falls, so the body-heading / anim-flags
-        // logic below reads this hoisted value (false while swimming) instead of the walk branch's.
-        //
-        // **A root ends the arc outright** (decision 0880): `airborne` is our `MOVEFLAG_FALLING`,
-        // and `SetRoot 0x7c7340`'s second act is `StopFalling 0x7c6290`, which clears FALLING and
-        // FALLINGFAR together. So a root or a stun taken mid-air is not a body that lands — it is a
-        // body that is no longer falling, hanging where it was ([`mover::step`]'s anchor holds the
-        // position). Ground contact is left honest in `grounded` (the transport attach and the trace
-        // both want the truth); it is the *arc* that the root ends.
+        // Our FALLING: never while swimming, and a root ends it outright (`SetRoot` `0x7c7340`
+        // calls `StopFalling` `0x7c6290`), leaving the body hanging; `grounded` keeps true contact.
         let airborne = !swimming && !held && !player.modes.rooted && (!grounded || jumped);
-        // Transport attach/detach + the deck-local re-snapshot, and the `ride` trace ([`ride`],
-        // decision 0438 phase 2 / 0470's solid cargo). Airborne keeps the current attachment, so
-        // a jump above the deck is deck-frame ballistics and lands where it took off.
+        // Airborne keeps the attachment, so a jump above a deck lands where it took off.
         ride::update_attachment(
             &mut player,
             transports,
@@ -1007,9 +644,7 @@ pub(super) fn control(
             grounded,
             swimming,
         );
-        // This frame's two move-flag words + the wire's fall clock ([`flags::this_frame`]): the
-        // live word the wire and the local gates read, and the take-off-frozen one the animation
-        // does. The arc bookkeeping (snapshot / FALLINGFAR / the landing edge) runs inside.
+        // The live flag word, the take-off-frozen one the animation reads, and the fall clock.
         let flags::FrameFlags {
             wire: move_flags_now,
             pose: pose_flags,
@@ -1028,9 +663,6 @@ pub(super) fn control(
             now,
             launch_y,
         );
-        // The rendered body heading + the animation's view of the flags — the display-facing law
-        // lives in [`gait::drive_body_heading`] (strafe offset ease / moving snap / the standing
-        // FROZEN chase whose body-step latches the turn-in-place shuffle).
         let anim_flags = gait::drive_body_heading(
             &mut player,
             pose_flags,
@@ -1041,9 +673,6 @@ pub(super) fn control(
             turning || mouselook,
             turn_rate,
         );
-        // Write the frame onto the driven body — pose, `MovementState`, the counter-twist gap and
-        // the landing report ([`body_pose::drive`]) — and take back the camera-pivot target it
-        // read off that body.
         let cam_pivot_target = body_pose::drive(
             &player,
             &mut body,
@@ -1056,29 +685,16 @@ pub(super) fn control(
             stand_now,
         );
 
-        // The camera-collision sweep is rooted at the *head* (capsule top hemisphere centre), not the
-        // framing pivot — see `seat_camera`'s doc for why. Computed here (not in `camera`) because it
-        // depends on the avatar's own capsule constants, which are a movement concern.
+        // The camera sweep's root: the capsule's top hemisphere centre, not the framing pivot.
         let head = player.pos + Vec3::Y * (CAPSULE_HEIGHT - CAPSULE_RADIUS);
-        // The spyglass lock (aura 76): pin the rig to first person for as long as the scope is
-        // held. Parking BOTH the live distance and the wheel target is what makes it a lock rather
-        // than a nudge — the wheel writes `target_distance`, and re-parking here every frame is our
-        // equivalent of the reference's camera flag `0x8` making `SetCameraView` early-return.
+        // The spyglass lock (aura 76): re-parking each frame stands in for the reference's camera
+        // flag `0x8`, which makes `SetCameraView` return early.
         if scoped.active() {
             rig.park_distance(0.0);
         }
-        // Far sight (B151): while `PLAYER_FARSIGHT` names an object, the rig orbits IT instead of
-        // the body — the substitution is [`camera::seat_on_subject`]'s, and it is the entire
-        // feature. Everything else in this system runs untouched, which is the point: Mind Vision
-        // leaves you walking, streaming, hearing and sending movement as yourself while only the
-        // picture moves.
+        // Far sight moves only the picture: `seat_on_subject` orbits the object, all else runs.
 
-        // `WOW_CAM_DUMP`: the per-frame INPUT signal beside `seat_camera`'s realized-pose `[cam]`
-        // line — wall clock, frame dt, this frame's accumulated mouse delta, the active look mode,
-        // and the yaw/pos the frame produced. A turn-feel question ("keyboard turn smooth, mouse
-        // turn jittery") needs the input cadence and the output cadence on the same timeline: a
-        // bursty `dx` under a steady `dt` convicts event delivery; a steady `dx` with an uneven
-        // realized pose convicts everything downstream.
+        // `WOW_CAM_DUMP`: this frame's input beside `seat_camera`'s realized `[cam]` line.
         if crate::player::camera::cam_dump_enabled() {
             eprintln!(
                 "[turn] t={:.6} dt={:.6} dx={:.3} dy={:.3} look={} face={:.6} model={:.6} \
@@ -1097,18 +713,12 @@ pub(super) fn control(
                 player.pos.x,
                 player.pos.y,
                 player.pos.z,
-                // The pivot channel's live height and where it is heading — the two columns that
-                // answer "does the camera snap?" numerically (decision 0404: timing is measured).
+                // The pivot channel's live height and its target.
                 rig.pivot.probe().0,
                 rig.pivot.probe().1,
             );
         }
-        // `turn_delta` is the character's own turn this frame (keyboard turn, or the drunk veer)
-        // — the deck's yaw delta was already applied to `cam.yaw` at the ride block (frame motion
-        // carries the camera unconditionally; only input turns respect `seat_camera`'s
-        // look-session gate).
-        // The auto-follow's own three facts (decisions 1493/1502): the knobs, where "behind" is,
-        // and the input word whose edges arm a return.
+        // `turn_delta` is our own turn; the deck's yaw reached `cam.yaw` in the ride carry.
         let follow = camera::FollowInput {
             cfg: follow_cfg,
             face_yaw: player.face_yaw,
@@ -1129,30 +739,11 @@ pub(super) fn control(
             &dynamics,
         );
 
-        // 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 (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
-        // `setBool` as the new state, and the dispatcher short-circuits the whole interrupt block on a
-        // 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; 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
-        // channel holds, and the interrupt this feeds is the *caster's*: vmangos breaks a channel on
-        // `m_caster`'s own position moving (`Spell::update`), and a possessed creature's steps never
-        // touch it. Without this gate the first movement key after a Mind Control shipped
-        // `CMSG_CANCEL_CHANNELLING` for our own channel 23 ms later, ending the possession — and
-        // since the reins then came home mid-keypress, the still-held key ran our own character,
-        // which reads exactly like "moving my character cancelled the spell" (director, 2026-08-13;
-        // reproduced live, `WOW_CAST_TRACE`).
+        // The cast bar's self-cancel: a new directional start, a jump, or autorun's on edge (the
+        // interrupt mask `0x10f0` at `0x5150ce` is forward, back, strafe and autorun, and a clear
+        // edge returns early at `0x5150c8`); turning and pitch never cancel. Only our own
+        // character's moves count: vmangos breaks a channel on the caster's own movement
+        // (`Spell::update`), so a possessed creature's steps must not end Mind Control.
         let steering_ourselves = player.foreign_mover.is_none();
         if steering_ourselves
             && (move_flags_now & move_flags::ANY_MOVE & !player.move_flags != 0
@@ -1161,12 +752,9 @@ pub(super) fn control(
         {
             net.7 .0 = true;
         }
-        // The loot window's own walk-away (decision 2097) — the reference's movement-START guard
-        // `0x60e990`, called first by every player-initiated START emitter: forward/back, strafe,
-        // keyboard-turn and pitch START, pitch STOP, `SetPitch` and Jump pass `arg2 = 0` and close
-        // an open loot at distance zero; mouse-look `SetFacing` passes `arg2 = 1` and does not.
-        // A different mask from the cast's `0x10f0` above — TURN is in this one — and the same
-        // `IsActivePlayer(this)` gate: a possessed mover's steps close nothing of ours.
+        // The loot window's walk-away, the movement-start guard `0x60e990`: forward, back, strafe,
+        // keyboard turn, pitch and jump close it, mouse-look facing does not, and only for our
+        // own character.
         if steering_ourselves
             && (move_flags_now
                 & (move_flags::ANY_MOVE | move_flags::TURN_LEFT | move_flags::TURN_RIGHT)
@@ -1177,16 +765,10 @@ pub(super) fn control(
             net.14 .0 = true;
         }
 
-        // Stream this frame's movement to the server — a `MSG_MOVE_*` per movement-axis transition, the
-        // 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.
+        // Stream the movement: a `MSG_MOVE_*` per axis transition, the jump and fall edges and a
+        // 500 ms heartbeat, which vmangos relays to nearby players.
         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
-        // takes `player` mutably.
+        // A held frame is simulation time skipped; the mover named is the one we drive.
         let skip = movement_net::SkipClock {
             dt,
             held: player.settling,
@@ -1199,13 +781,8 @@ pub(super) fn control(
             swim_pitch,
             movement_net::ArcEdges {
                 jumped,
-                // **The wire's own take-offs announce themselves, and not with `MSG_MOVE_JUMP`**
-                // (decision 1702). `wire_jump` covers the hover grant's `CMovement::Jump(force = 0)`,
-                // whose handler `0x61a620` sends nothing at all — and it cannot be racing a keyboard
-                // jump, because the body it launches was granted HOVER in the same breath and hover
-                // is the first refusal Space takes (`0x7c623a`). `knocked` covers the knockback,
-                // which pushes its ack instead. This is the correction 1620 needed: benilla streamed
-                // a JUMP for the hover launch, and the reference streams nothing.
+                // Wire launches send no `MSG_MOVE_JUMP`: the hover grant's jump sends nothing
+                // (`0x61a620`) and a knockback sends its ack instead.
                 wire_launch: knocked || wire_jump,
                 air_nudged,
                 landed,
@@ -1213,21 +790,14 @@ pub(super) fn control(
             },
             now,
             &speed_acks,
-            // Owed only if the mover actually flew it: a launch the settle hold or the root anchor
-            // refused is dropped in silence, exactly as the reference discards an already-popped
-            // knockback record under `MOVEFLAG_ROOT` (`0x615c71 test ah,0x10` → the kind-28 table
-            // byte is 0 → `0x615c80 je 0x616539`: no apply, and no ack).
+            // Acked only if flown: under root the reference drops the record unacked (`0x615c71`).
             knockback.filter(|_| knocked),
             wire_transport,
             skip,
         );
     } else {
-        // Free fly (pre-connect or detached): aim from the look angles, move the camera directly
-        // ([`camera::fly_free`]). If we just detached mid-move, the controlled branch above (which
-        // owns the per-frame movement stream) has stopped running with our last move-flags still
-        // live on the wire — park the mover so the server clears them, else observers extrapolate a
-        // phantom walk/spin until we re-attach. No-op pre-connect / once already stopped (decision
-        // 0056). The avatar stays frozen at `player.pos`.
+        // Free fly. Park the mover first, so a detach mid-move leaves no stale flags for observers
+        // to extrapolate; a no-op once stopped.
         movement_net::park_mover(&net.0 .0, &mut player);
         camera::fly_free(dt, &keys, typing, &mut rig, &mut cam, &mut cam_t);
     }
diff --git a/crates/benilla-app/src/player/drunk.rs b/crates/benilla-app/src/player/drunk.rs
index 8b0d7bc6..41bfe758 100644
--- a/crates/benilla-app/src/player/drunk.rs
+++ b/crates/benilla-app/src/player/drunk.rs
@@ -1,67 +1,40 @@
-//! Drunkenness — the client-side inebriation math (B210).
-//!
-//! 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`) 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
-//!   veers left and right as it walks. Skipped while a keyboard turn is held (`flags & 0x30`,
-//!   non-mouselook) so deliberate turning stays crisp.
-//! - **swim pitch** `+= pulse × 4.0` (`_DAT_0080306c`), clamped, while the swim flag is up
-//!   (`0x200000`) — a drunk swimmer porpoises.
-//!
-//! 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.
-//! The three harmonics never phase-lock, so the stagger reads as aimless, not metronomic.
-//!
-//! Faithful-arithmetic note: the binary computes on the x87 stack at PC_53 (f64) and rounds to
-//! f32 only at explicit stores; the port widens each f32 operand to f64 and rounds back only
-//! where the binary stores (the mid-pulse `fst` of the phase is reproduced — the first cosine
-//! sees the unrounded phase, the second and third the f32-rounded one). Constants carry the
-//! binary's exact bit patterns.
+//! Drunkenness, from the drunk byte (`PLAYER_BYTES_3` byte 1). For the active player while moving
+//! (`flags & 0xf`, callers `0x60a984`–`0x60ab14`), the reference adds a wobble each frame to the
+//! facing, 2π-wrapped through `0x60de30`, unless a keyboard turn is held (`flags & 0x30`, not
+//! mouselook), and four times the wobble to the swim pitch, clamped, while swimming (`0x200000`).
+//! Its amplitude and frequency both scale with the fraction: ±0.75° a frame at full drunk.
+//! The binary computes on the x87 stack at 53-bit precision and rounds to f32 only at its stores,
+//! as the port does in f64, with the binary's constants bit for bit.
 
-/// `_DAT_008029d0` — 0.01 (bits `0x3c23d70a`): the inebriation byte → fraction scale (`0x5e2a90`).
+/// 0.01 at `0x8029d0`: the drunk byte's fraction scale (`0x5e2a90`).
 const DRUNK_SCALE: f32 = f32::from_bits(0x3c23_d70a);
-/// `_DAT_007ffaac` — π/180 (bits `0x3c8efa35`): the pulse phase's degrees→radians factor.
+/// π/180 at `0x7ffaac`: the phase's degrees-to-radians factor.
 const DEG2RAD: f32 = f32::from_bits(0x3c8e_fa35);
-/// The three harmonic frequency scales of the pulse (`_DAT_0080c5e0/dc/d8`).
+/// The three harmonic frequencies, at `0x80c5e0`, `0x80c5dc` and `0x80c5d8`.
 const PULSE_F1: f32 = f32::from_bits(0x3dbe_76c9); // 0.093
-/// See [`PULSE_F1`].
 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 this is that exact bit pattern.)
+/// The mean's 1/3 at `0x80c5d4`, 12 ULPs below the nearest f32 to 1/3.
 const PULSE_MEAN: f32 = f32::from_bits(0x3eaa_aa9f);
-/// `_DAT_0080c4bc` — π/240 (bits `0x3c567750`): the pulse amplitude-vs-fraction scale.
+/// π/240 at `0x80c4bc`: the amplitude per unit of fraction.
 const PULSE_AMP: f32 = f32::from_bits(0x3c56_7750);
-/// `_DAT_0080306c` — 4.0: the swim-pitch multiplier on the wobble (`0x60aaf1`).
+/// 4.0 at `0x80306c`: the wobble's swim-pitch multiplier (`0x60aaf1`).
 pub(super) const SWIM_PITCH_WOBBLE_SCALE: f32 = 4.0;
 
-/// The drunk fraction the reference stores for a raw inebriation byte: `min(byte, 100) × 0.01`
-/// (`0x5e2a90`: `cmp al,0x64; jb; mov al,0x64` then `fild; fmul 0.01; fstp dword`).
+/// The drunk fraction, `min(byte, 100) × 0.01` (`0x5e2a90`).
 pub(super) fn fraction(byte: u8) -> f32 {
     let clamped = byte.min(100);
     (f64::from(clamped) * f64::from(DRUNK_SCALE)) as 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 the
-/// reference's pulse — see the module doc for the formula and the x87 rounding subtlety.
+/// The frame's wobble in radians for the time in ms and the drunk fraction (`0x60ab20`).
 pub(super) fn wobble(now_ms: u32, fraction: f32) -> f32 {
     if fraction == 0.0 {
         return 0.0;
     }
-    // `fild qword` of the zero-extended 32-bit time — exact in f64.
+    // `fild qword` of the zero-extended time: exact in f64.
     let p = f64::from(now_ms) * f64::from(DEG2RAD) * f64::from(fraction);
-    // The binary's `fst [ebp-4]` rounds the phase to f32 for the 2nd/3rd cosines while the 1st
-    // consumes the unrounded st0.
+    // `fst [ebp-4]` rounds the phase to f32 for the second and third cosines only.
     let p_f32 = f64::from(p as f32);
     let c1 = (p * f64::from(PULSE_F1)).cos();
     let c2 = (p_f32 * f64::from(PULSE_F2)).cos();
@@ -70,15 +43,10 @@ pub(super) fn wobble(now_ms: u32, fraction: f32) -> f32 {
     (mean * (f64::from(PULSE_AMP) * f64::from(fraction))) as f32
 }
 
-// The binary also holds a drunk FOV lane (camera channel `+0x10c`, setter `0x511250`, target
-// `(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). 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.
+// Deviation: no drunk field-of-view lane, because the reference's is invisible in play: its
+// target `(179° − 90°)·fraction` (camera `+0x10c`, setter `0x511250`) eases at
+// `cameraFoVSmoothSpeed`, 0.5°/s, and restarts on every drunk-byte change, so it creeps under 1°.
+// Not built: entering the world already drunk, the reference snaps the full fisheye (`0x50d0f0`).
 
 #[cfg(test)]
 mod tests {
@@ -88,7 +56,6 @@ mod tests {
     fn fraction_scales_and_clamps() {
         assert_eq!(fraction(0), 0.0);
         assert_eq!(fraction(50), 0.5);
-        // 100 and everything above clamp to the same full-drunk fraction.
         assert_eq!(fraction(100), fraction(255));
         assert!((fraction(100) - 1.0).abs() < 1e-6);
     }
@@ -100,8 +67,7 @@ mod tests {
 
     #[test]
     fn wobble_phase_zero_is_full_amplitude() {
-        // At n = 0 every cosine is 1, so the pulse is exactly mean(1,1,1)·amp·t = amp·t — the
-        // amplitude anchor: ±(π/240)·fraction radians (≈0.75°/frame at full drunk).
+        // At 0 ms every cosine is 1, so the pulse is the amplitude times the fraction.
         let full = wobble(0, 1.0);
         assert!((full - PULSE_AMP).abs() < 1e-7, "got {full}");
         let half = wobble(0, 0.5);
@@ -110,8 +76,7 @@ mod tests {
 
     #[test]
     fn wobble_stays_within_amplitude_and_oscillates() {
-        // Sweep a minute of frames at full drunk: never beyond the amplitude, and both signs
-        // visited (the harmonics must actually oscillate).
+        // A minute at full drunk: never past the amplitude, and both signs visited.
         let (mut lo, mut hi) = (f32::MAX, f32::MIN);
         for ms in (0..60_000).step_by(16) {
             let w = wobble(ms, 1.0);
diff --git a/crates/benilla-app/src/player/embody.rs b/crates/benilla-app/src/player/embody.rs
index 272f934d..26284af0 100644
--- a/crates/benilla-app/src/player/embody.rs
+++ b/crates/benilla-app/src/player/embody.rs
@@ -1,41 +1,17 @@
-//! **What the client embodies** — which single unit it simulates, animates from input, and streams.
+//! Which unit the client simulates, animates from input and streams. The reference keeps apart
+//! the active player (`ds:0xb41414`, fixed under far sight and possession), the camera anchor
+//! (`camera+0x88`) and the active mover (`ds:0xc4da98`, set only by `SetActiveMover` `0x6006e0`;
+//! unresolved, the input applier `0x514640` skips its tick): [`SelfPlayer`] is the character,
+//! [`Embodied`] the attached body and camera anchor, [`ActiveMover`] the body we may move.
 //!
-//! Decision 0092 gave this client two answers to "where am I?": the **camera eye** and the
-//! **active-player character**. Possession forces a third, and the reference has had it all along
-//! as its own global: the **active mover** (`ds:0xc4da98`, written only by `SetActiveMover
-//! 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.
-//!
-//! 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`]
-//! means **the body I am attached to** (the reference's camera anchor, `camera+0x88`) and
-//! [`ActiveMover`] means **the body I may move** (those mover globals). Of ~150 `SelfPlayer` query
-//! sites the large majority are identity and are untouched by possession; the ones that changed are
-//! exactly those that simulate, animate from input, render the body the camera is inside, or
-//! stream it.
-//!
-//! Three properties of the placement carry the weight:
-//!
-//! - **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 (`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
-//!   until it arrives (`HandleMovementOpcodes`). A client that detaches while feared is frozen
-//!   server-side long after the fear ends.
-//! - **Unresolvable is nobody, never a fallback.** A claimed grant whose object has not streamed in
-//!   leaves the marker unplaced, because the alternative — quietly leaving it on our own body —
-//!   drives our body under the creature's mover, and outbound `MSG_MOVE_*` carry no guid: the
-//!   server writes our pose onto the creature. That is the sharpest trap in this family (decision
-//!   1269 §3), and here it is structurally impossible rather than guarded against.
-//! - **The reins change hands by GUID, not by entity.** A cross-map worldport despawns and
-//!   re-streams our own body under a fresh entity while we never stop driving it, so keying the
-//!   handover on the entity would re-seize (and re-settle) on every zone transfer.
+//! - Losing control removes only [`ActiveMover`]: `0x5fa600` zeroes the mover globals and keeps
+//!   the anchor, so the camera follows the feared body, smoothed (`0x50d810`). The spline ride
+//!   hangs off [`Embodied`], and vmangos drops all movement until the `CMSG_MOVE_SPLINE_DONE` it
+//!   awaits after a player's spline launch (`MoveSplineInit.cpp:131`, `MovementHandler.cpp:295`),
+//!   so detaching while feared would freeze us server-side.
+//! - An unstreamed claimed mover puts [`Embodied`] on nobody: outbound `MSG_MOVE_*` carry no guid,
+//!   so driving our own body would write our pose onto the creature.
+//! - The reins change hands by guid, not entity: a worldport re-streams our body under a new one.
 
 use bevy::prelude::*;
 
@@ -44,12 +20,8 @@ use super::state::Player;
 use crate::creature_anim::MovementState;
 use crate::net::{ActiveMover, Embodied, GuidIndex, RemoteMotion, SelfGuid, SelfPlayer};
 
-/// Keep [`Embodied`] on the one body we are attached to — the possessed unit while we hold its
-/// reins, our own otherwise, and nobody at all while neither is streamed — and [`ActiveMover`] on
-/// it for as long as that body is also ours to move.
-///
-/// Runs before the controller, which reads both to decide what — if anything — it is driving.
-// A Bevy system's parameter list, not an argument list.
+/// Keeps [`Embodied`] on the attached body (the possessed unit, else our own, else nobody) and
+/// [`ActiveMover`] on it while it is ours to move; runs before the controller.
 pub(super) fn maintain_embodiment(
     mut commands: Commands,
     mut player: ResMut<Player>,
@@ -61,17 +33,8 @@ pub(super) fn maintain_embodiment(
     mut held: Local<Option<u64>>,
 ) {
     let (self_guid, index) = (&guids.0, &guids.1);
-    // Which body we are attached to, and which entity that is. Two answers:
-    //
-    // - **A claimed foreign mover** answers by itself: either its object is streamed and it is the
-    //   body we inhabit, or nothing is.
-    // - Otherwise our own body.
-    //
-    // Being *forbidden to move it* is deliberately not a third answer (decision 1281). It is the
-    // narrow [`ActiveMover`] marker below that comes off, and `control`'s own gate that stops
-    // driving; detaching outright was decision 1279's mistake, and it took the camera, the
-    // collision height and — the expensive one — the self-spline ride and its mandatory
-    // `CMSG_MOVE_SPLINE_DONE` with it.
+    // A claimed foreign mover is the body if streamed, else nobody; otherwise our own body. Lost
+    // control is not a third answer: only [`ActiveMover`] comes off, below.
     let want_guid = player.foreign_mover.or(self_guid.0);
     let want = match player.foreign_mover {
         Some(guid) => index.0.get(&guid).copied(),
@@ -81,29 +44,20 @@ pub(super) fn maintain_embodiment(
     if *held != want_guid {
         *held = want_guid;
         if want_guid.is_some() {
-            // Whatever pose and momentum `Player` holds describe the body we just let go of, so the
-            // controller has to adopt the new one's before it drives anything. It also drives
-            // nothing at all until it has: see [`Player::reseat`].
+            // `Player` holds the old body's pose; the controller adopts the new one's first.
             player.reseat = true;
-            // The reference tears the same thing down on the outgoing mover — `SetActiveMover
-            // 0x6006e0` calls `0x6103a0` → `0x60fb60(0, 1)`, cancelling click-to-move and follow.
-            // A follow that survived would steer the creature toward whoever our *character* was
-            // walking behind.
+            // `SetActiveMover` `0x6006e0` cancels click-to-move and follow on the outgoing mover,
+            // through `0x6103a0` → `0x60fb60(0, 1)`.
             follow.stop();
         }
     }
 
-    // The narrow half: whether that body is ours to move *this frame*. It changes on its own edges —
-    // a fear lands and lifts without the reins ever changing hands — so it is maintained beside the
-    // hand-over below, not inside it.
+    // Steering has its own edges: a fear lands and lifts without a handover.
     let steer = want.filter(|_| !player.control_lost);
     for e in &steering {
         if Some(e) != steer {
-            // [`MovementState`] rides with it, because it is `unify`'s **top-precedence** leg: a
-            // body that keeps one while nothing is writing it animates from the last view we drove
-            // it with, whatever the server is actually doing to it. Dropping it hands the animation
-            // to the same source that now owns the motion — the relayed stream, or the spline the
-            // server is flee-pathing it along.
+            // `MovementState` goes too: it is `unify`'s top-precedence leg, so a stale one would
+            // hold the body's animation while the server moves it.
             commands.entity(e).remove::<(ActiveMover, MovementState)>();
         }
     }
@@ -122,10 +76,8 @@ pub(super) fn maintain_embodiment(
         commands.entity(e).remove::<Embodied>();
     }
     if let Some(e) = want {
-        // Drop whatever server-replay state the unit carried at the instant we took it. While we
-        // drive it the server sends us no relays for it (vmangos excludes the mover's own session
-        // from the broadcast), so nothing accumulates — but a move already queued for a future
-        // apply would otherwise fire after we let go and yank the unit back to a pose it left.
+        // Drop the unit's queued server replay, or it fires after we let go. No relays arrive
+        // while we drive it: vmangos excludes the mover's session (`MovementHandler.cpp:396`).
         commands.entity(e).insert(Embodied).remove::<RemoteMotion>();
     }
 }
@@ -163,7 +115,7 @@ mod tests {
         q.iter(app.world()).next()
     }
 
-    /// A remote unit's replay state, minimally populated — only its presence is under test.
+    /// A remote unit's replay state; only its presence is under test.
     fn replaying() -> RemoteMotion {
         RemoteMotion {
             wow_pos: [0.0; 3],
@@ -181,9 +133,6 @@ mod tests {
         }
     }
 
-    /// The whole handover, and the two states a casual version gets wrong: a claim we cannot yet
-    /// resolve must leave the marker on **nobody**, and coming home must hand the creature back to
-    /// the remote path intact.
     #[test]
     fn a_claim_we_cannot_resolve_yet_moves_the_marker_to_nobody_not_to_our_own_body() {
         let (mut app, me) = harness();
@@ -233,11 +182,6 @@ mod tests {
         );
     }
 
-    /// The controller-fed [`MovementState`] follows the reins — including all the way home. It is
-    /// `unify`'s top-precedence leg, so whoever holds it decides what the body looks like it is
-    /// doing; leaving one on a body we have let go of freezes its animation on the last view we
-    /// drove it with, and failing to give it back leaves our own avatar animation-dead for the rest
-    /// of the session, and only ever after a possession.
     #[test]
     fn our_own_body_gets_its_movement_view_back_when_the_reins_come_home() {
         let (mut app, me) = harness();
@@ -268,9 +212,7 @@ mod tests {
         assert!(!app.world().entity(boar).contains::<MovementState>());
     }
 
-    /// A cross-map worldport despawns and re-streams our own body under a fresh entity while we
-    /// never stop driving it. Keying the handover on the entity would re-seize — and re-settle —
-    /// on every zone transfer.
+    /// A cross-map worldport re-streams our body under a fresh entity while we keep driving it.
     #[test]
     fn re_streaming_our_own_body_moves_the_marker_without_calling_it_a_handover() {
         let (mut app, me) = harness();
@@ -296,12 +238,6 @@ mod tests {
              discard the worldport's own snap and re-run the settle"
         );
     }
-    /// **Forbidden to move it is not letting go of it** (decision 1281) — the split the two markers
-    /// exist for. Being feared hands the body's *motion* to the server, which is visible and must
-    /// be: a mind-controlled player is seen walking where their captor drives them. But it does not
-    /// hand back the body, and letting go was expensive in a way nothing on screen showed — the
-    /// self-spline ride goes with it, and with the ride the `CMSG_MOVE_SPLINE_DONE` the server
-    /// blocks every later movement packet on.
     #[test]
     fn a_body_we_may_not_move_stays_in_our_hands_and_only_stops_being_steered() {
         let (mut app, me) = harness();
@@ -325,7 +261,7 @@ mod tests {
              server drives it instead of standing frozen"
         );
 
-        // A possessed creature that has just been feared out of our control behaves the same way.
+        // A possessed creature feared out of our control behaves the same way.
         app.world_mut().resource_mut::<Player>().foreign_mover = Some(0xBB);
         let boar = app.world_mut().spawn(replaying()).id();
         app.world_mut()
diff --git a/crates/benilla-app/src/player/flags.rs b/crates/benilla-app/src/player/flags.rs
index 5d689afa..cd555c19 100644
--- a/crates/benilla-app/src/player/flags.rs
+++ b/crates/benilla-app/src/player/flags.rs
@@ -1,17 +1,7 @@
-//! **The move-flag word this frame carries** — the client's `CMovement+0x40`, rebuilt from state
-//! every frame and then read by three different consumers, which is the whole reason it is built
-//! in one place: the animation selector, the outbound `MSG_MOVE_*` stream, and the local gates
-//! (the sit refusal, the cast self-cancel) must never disagree about what the avatar is doing
-//! (decision 0056 — the wire mirrors the avatar's actual motion).
-//!
-//! Two words come out, and the difference between them is verified, not cosmetic: the **wire**
-//! word keeps the direction bits live mid-air (the 1.12.1 sniff proves the real client's do), while
-//! the **pose** word freezes them at take-off, because the anim layer plays the step-off gait off
-//! the takeoff-frozen flags until FALLINGFAR latches or the unit lands.
-//!
-//! The airborne arc's own bookkeeping — the snapshot, the FALLINGFAR latch, the landing edge —
-//! belongs to [`Player::advance_airborne_arc`]; this module only reads its verdict and the fall
-//! clock that rides the landing packet.
+//! This frame's move-flag word, the reference's `CMovement+0x40`, rebuilt from state every frame
+//! so the animation selector, the outbound `MSG_MOVE_*` stream and the local gates (the sit
+//! refusal, the cast self-cancel) read one answer. The wire word keeps the direction bits live in
+//! mid-air, as a 1.12.1 capture shows the reference's do; the pose word freezes them at takeoff.
 
 use crate::creature_anim::move_flags;
 
@@ -23,16 +13,15 @@ pub(super) struct FrameFlags {
     pub wire: u32,
     /// What the animation sees: direction bits frozen at take-off.
     pub pose: u32,
-    /// The airborne arc ended this frame — the `MSG_MOVE_FALL_LAND` edge.
+    /// The arc landed this frame: the `MSG_MOVE_FALL_LAND` edge.
     pub landed: bool,
-    /// Milliseconds since the arc began, snapshotted *before* the landing clears it — vmangos
-    /// gates fall damage on this field.
+    /// Milliseconds since the arc began, taken before the landing clears it; vmangos gates fall
+    /// damage on it.
     pub fall_time: u32,
 }
 
-/// Build this frame's two flag words. `swim` is `Some((fwd, side))` exactly while swimming — the
-/// netted swim amounts that actually drove the mover, so a rooted or key-cancelled swimmer cannot
-/// stream a phantom direction.
+/// Builds this frame's two flag words. `swim` is `Some((fwd, side))` while swimming, the netted
+/// amounts that drove the mover.
 pub(super) fn this_frame(
     player: &mut Player,
     axes: &input::MoveAxes,
@@ -41,53 +30,35 @@ pub(super) fn this_frame(
     jumped: bool,
     held: bool,
     air_nudged: bool,
-    // This frame's two movement-input predicates — what the reference's `0x514560` and `0x5145b0`
-    // answered ([`state::may_translate`], [`state::may_turn`]). Both go down on death (1753).
+    // The reference's input predicates `0x514560` and `0x5145b0` (`state::may_translate`,
+    // `state::may_turn`); death takes both down.
     may_translate: bool,
     may_turn: bool,
     now: f32,
     launch_y: f32,
 ) -> FrameFlags {
-    // The wire fall clock (ms since the airborne arc began), snapshotted HERE — before the arc
-    // bookkeeping below clears `airborne_since` on the landing frame — so the MSG_MOVE_FALL_LAND
-    // reports the *accumulated* fall time. vmangos `Player::HandleFall` gates fall damage on the
-    // land packet's fallTime ≥ 1229 ms (the free-fall time of the 14.57-yd damage threshold); a
-    // clock zeroed by the landing silently disables fall damage. The takeoff frame still sends 0
-    // (`airborne_since` is not yet set at this point in that frame).
+    // Taken before the arc bookkeeping clears `airborne_since` on the landing frame, so FALL_LAND
+    // carries the whole fall: vmangos `Player::HandleFall` charges no damage under 1229 ms.
     let wire_fall_time = if jumped {
-        // A jump launch starts a fresh arc — its fall clock is zero. This also covers a
-        // same-frame land+relaunch, where `airborne_since` still holds the *previous* arc's
-        // start; without this the bounce's JUMP would carry a stale (accumulated) fall time,
-        // and a long spam-jump chain could spuriously cross the server's fall-damage gate.
+        // A jump starts a fresh arc at zero, even a same-frame relaunch whose `airborne_since`
+        // is still the last arc's.
         0
     } else {
         player
             .airborne_since
             .map_or(0, |t0| ((now - t0) * 1000.0).max(0.0) as u32)
     };
-    // The CMovement move-flags this frame's input implies. The same bitset drives our avatar's
-    // animation *and* the movement stream we send the server, so the two can
-    // never disagree. Direction bits mirror the client's MOVEMENTFLAGS; FALLING marks the airborne
-    // arc (animation-only — it is masked off before going on the wire, see the send block).
-    // **Every granted mover mode rides every packet**, in or out of the water — the reference's
-    // builder reads the one `[cmov+0x40]` the server's merge wrote them into, so it echoes back
-    // whatever was granted for free (decisions 0726, 0866). Ours has to put them back
-    // explicitly, because this word is rebuilt from state each frame; drop one and the server
-    // forgets the mode, then the next server-authored move echoes a mode-less word back and
-    // clears it under us. Root rides too — moving bits are what must not accompany it, and
-    // rooted input can't produce any (the controller zeroes `dir`, jumps refused).
+    // Every granted mover mode rides every packet, root included: the reference's builder reads
+    // the `[cmov+0x40]` the server's merge wrote them into, and a mode dropped here is cleared by
+    // the server's next echo.
     let mut move_flags_now = player.modes.wire_flags();
-    // `landed` gates the wire's jump/fall lifecycle; the swim branch never sets
-    // them (leaving the water resumes the ground mover from rest, no airborne report).
+    // The swim branch never lands: leaving the water resumes the ground mover from rest.
     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 (`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 (`0x7c6230`). No FALLING, no airborne bookkeeping: the
-        // arc state is cleared so leaving the water starts a clean walk/fall from rest.
+        // SWIMMING (its pitch tail rides with it) and the direction bits of the netted swim
+        // amounts, which the swim gait selector cascades on (`0x5fd100`: turn 41, strafe 43/44,
+        // back 45, forward 42, idle 41). Space sets nothing: its swim role is the breach
+        // (`0x7c6230`). No FALLING, and the arc is cleared.
         move_flags_now |= move_flags::SWIMMING;
         if swim_fwd < 0.0 {
             move_flags_now |= move_flags::BACKWARD;
@@ -103,17 +74,13 @@ pub(super) fn this_frame(
         player.fall_far = false;
         landed = false;
     } else {
-        // Straight off the net axis, so a netted-to-zero press pair streams NO direction bit
-        // (the emitter's genuine STOP) rather than a phantom FORWARD we aren't actually moving
-        // in — decision 0056's law that the flags mirror the avatar's motion.
+        // Off the net axis: a pair that nets to zero streams no direction bit, the emitter's STOP.
         match axes.fwd.signum() {
             1 => move_flags_now |= move_flags::FORWARD,
             -1 => move_flags_now |= move_flags::BACKWARD,
             _ => {}
         }
-        // Straight off the netted strafe axis, so a cancelled press pair streams NO strafe bit —
-        // the two are mutually exclusive on the wire, and both-set is silently dropped by the
-        // server (decision 0622).
+        // Off the netted strafe axis: the server relays no packet carrying both strafe bits.
         match axes.side.signum() {
             -1 => move_flags_now |= move_flags::STRAFE_LEFT,
             1 => move_flags_now |= move_flags::STRAFE_RIGHT,
@@ -127,86 +94,53 @@ pub(super) fn this_frame(
                 move_flags_now |= move_flags::TURN_RIGHT;
             }
         }
-        // Airborne (a jump or a step-off a ledge) — the caller's hoisted value. The arc's
-        // snapshot / far-latch / landing edges live in [`Player::advance_airborne_arc`] (a
-        // fresh jump is always a NEW arc, even a same-frame land+relaunch — see there). FALLING
-        // also rides the wire (decision 0053), so observers replay it.
+        // The arc's edges; FALLING rides the wire too, so observers replay the arc.
         let arc = player.advance_airborne_arc(airborne, jumped, now, launch_y);
         landed = arc.landed;
         if airborne {
             move_flags_now |= move_flags::FALLING;
-            // Mid-air the direction flags stay LIVE — the real client's `CMovement+0x40` keeps
-            // tracking the keys while airborne, and the wire proves it (VERIFIED, vanilla-sniffs
-            // `dwarf_rogue_dun_morogh`: a strafe pressed mid-air rides the landing FALL_LAND as
-            // `(Forward, StrafeLeft)`; an S→W swap mid-air lands as `(Forward)`). What's frozen
-            // at takeoff is the *velocity basis* (the mover's momentum — `0x7c5a20` skips the
-            // basis recompute while FALLING), never the reported state; the landing-anim pick
-            // (`jump_land_pick`, the ref's `0x602c60`) keys on the flags *at touchdown*, so a
-            // frozen wire strands observers on stale flags and they play a locomotion anim
-            // instead of the landing. The ANIM path keeps the takeoff-frozen dirs (`pose_flags`
-            // below — the RE'd step-off gait freeze); a new arc (re)seeds them, and the
-            // standstill air nudge is the one mid-arc input that really moves us.
+            // In mid-air the wire's direction bits track the keys, as the reference's do (in a
+            // 1.12.1 capture a strafe pressed mid-air lands as `(Forward, StrafeLeft)`); only the
+            // velocity basis freezes (`0x7c5a20` skips it while FALLING), and observers pick the
+            // landing anim off the touchdown flags (`0x602c60`). The pose keeps the takeoff
+            // directions, re-seeded by a new arc and by the standstill air nudge.
             if arc.new_arc || air_nudged {
                 player.airborne_dirs = move_flags_now & move_flags::ANY_MOVE;
             }
-            // FALLINGFAR (latched by `advance_airborne_arc` above — the exclusive distance/timer
-            // legs, decision 0179) rides the live flags: the mid-air Fall(40) pose, the
-            // landing-anim gate, and the wire (heartbeats carry it; the axis differ ignores it).
+            // FALLINGFAR rides the live flags: the Fall(40) pose, the landing-anim gate, the wire.
             if player.fall_far {
                 move_flags_now |= move_flags::FALLING_FAR;
             }
         }
-        // While `held` (post-teleport/login settle) the avatar is frozen in place with gravity off,
-        // so it has no locomotion to report — clear the flags so we never stream a phantom walk/turn
-        // the server would extrapolate onto observers while we sit on the settle. The frozen position
-        // was already reported by the teleport Stop; a facing change still streams a harmless
-        // SET_FACING. The same bitset drives the local animation (0052), so this also keeps the
-        // held avatar idle rather than moonwalking in place. (Decision 0056 — the wire mirrors the
-        // avatar's actual motion.)
+        // The settle hold freezes the body with gravity off, so it reports no locomotion, on the
+        // wire or in the pose.
         if held {
             move_flags_now = 0;
         }
     }
-    // **The walk gait rides every packet** — `MOVEFLAG_WALK_MODE` `0x100`, latched by the
-    // `TOGGLERUN` keybind ([`super::walk`], decision 1752). Deliberately OUTSIDE the branches
-    // above, and after the settle's `move_flags_now = 0`: this is a MODE, not a motion. The
-    // settle's wipe exists so a frozen avatar reports no locomotion, and clearing the walk bit
-    // with it would tell the server we went back to running — a spurious SET_RUN_MODE, then a
-    // SET_WALK_MODE the frame the settle releases, on every teleport. Nothing below strips it
-    // either: `incapacitated_flags` touches only the direction and turn bits, which is the
-    // reference's own answer too — its input allow-list (`0x615c71` → the table at `0x618054`)
-    // blocks the translation commands while rooted and **explicitly permits run/walk**.
+    // `MOVEFLAG_WALK_MODE` (`0x100`) is a mode, not a motion, so it goes on after the settle's
+    // wipe and survives the root and stun suppressions: the reference's input allow-list
+    // (`0x615c71`, table `0x618054`) blocks translation under a root and permits run/walk.
     if player.walking {
         move_flags_now |= move_flags::WALK_MODE;
     }
-    // **A knockback arc streams FORWARD for its whole length** (decision 1740). The reference's
-    // apply plants it as part of the launch (`0x6179c0`'s `0x617a18 or edx,0x8001` — set bit 0,
-    // clear bit 1) and nothing clears it until the arc ends, and the send mask
-    // (`0x618909 and edx,0x75a07dff`) keeps bit 0, so observers see it. It is also the mechanism
-    // that makes the arc unsteerable, so the bit and the freeze are the same fact, set in one
-    // place. Ours never sent it at all: a knocked-back body streamed a bare FALLING and observers
-    // replayed it as a plain drop.
+    // A knockback streams FORWARD all arc: the reference's apply `0x6179c0` clears bit 1
+    // (`0x617a0f`) and sets bit 0 (`0x617a18 or edx,0x8001`) at launch, and the send mask
+    // (`0x618909 and edx,0x75a07dff`) keeps it; the same bit makes the arc unsteerable.
     if player.knock_arc {
         move_flags_now = (move_flags_now & !move_flags::BACKWARD) | move_flags::FORWARD;
     }
-    // The two incapacitate suppressions — the translate predicate down drops the direction bits,
-    // the turn predicate down drops the turn bits — applied to the whole word in one place,
-    // whichever branch built it, and with the reference's byte trail in
-    // [`state::incapacitated_flags`] (decision 0880). Death drops both, through the precondition
-    // the two predicates share (decision 1753), so a corpse streams a bare word.
+    // The translate predicate down drops the direction bits and the turn predicate the turn bits,
+    // whichever branch built the word; death drops both.
     move_flags_now = state::incapacitated_flags(move_flags_now, !may_translate, !may_turn);
-    // Riding a transport: the ON_TRANSPORT bit rides every packet with its local-pose tail
-    // (built at the send). Set from the POST-attach state so flag and tail agree the
-    // very frame we board or step off (decision 0438 phase 2).
+    // ON_TRANSPORT, whose local-pose tail is built at the send, from the post-attach state so
+    // the two agree on the frame we board or step off.
     if player.ride.is_some() && !held {
         move_flags_now |= move_flags::ON_TRANSPORT;
     }
 
-    // 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 (`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.
+    // In the air the pose keeps the takeoff directions: the reference's anim layer plays the
+    // takeoff flags until FALLINGFAR latches (`0x602c40`) or the unit lands.
     let pose_flags = if airborne {
         (move_flags_now & !move_flags::ANY_MOVE) | player.airborne_dirs
     } else {
@@ -241,18 +175,6 @@ mod tests {
         }
     }
 
-    /// **Walk mode is a MODE, so it survives everything that clears locomotion** (decision 1752).
-    /// Three states that each wipe or narrow the word, and the bit must be in both the wire and
-    /// the pose word out of every one of them:
-    ///
-    /// * the post-teleport/login **settle** (`held`), whose `move_flags_now = 0` exists so a
-    ///   frozen avatar reports no walking — clearing the gait with it would tell the server we
-    ///   went back to running, then re-announce a frame later: a SET_RUN_MODE/SET_WALK_MODE pair
-    ///   on every single teleport;
-    /// * **rooted**, which drops the direction bits — and the reference agrees the gait stays: its
-    ///   input allow-list (`0x615c71` → `0x618054`) blocks the translation commands while rooted
-    ///   and **explicitly permits** run/walk;
-    /// * **stunned**, which drops the turn bits.
     #[test]
     fn the_walk_gait_outlives_the_settle_the_root_and_the_stun() {
         let case = |held: bool, rooted: bool, stunned: bool| {
@@ -272,8 +194,7 @@ mod tests {
                 false,
                 held,
                 false,
-                // The two predicates, as this case's root and stun leave them — the body is alive,
-                // so each is simply its own term (decision 1753).
+                // Alive, so each predicate is its own term.
                 !rooted,
                 !stunned,
                 1.0,
@@ -300,14 +221,13 @@ mod tests {
                 f.pose
             );
         }
-        // The settle really is wiping the locomotion — the control that says the assertion above
-        // is about a mode surviving a wipe, not about there being no wipe.
+        // Control: the settle does wipe the direction bits.
         assert_eq!(
             case(true, false, false).wire & move_flags::ANY_MOVE,
             0,
             "the settle still clears the direction bits"
         );
-        // …and a runner never carries the bit.
+        // A runner never carries the bit.
         let mut runner = Player::default();
         let mut axes = still();
         axes.fwd = 1;
@@ -328,21 +248,13 @@ mod tests {
         assert_eq!(f.wire & move_flags::WALK_MODE, 0);
     }
 
-    /// **A knockback arc streams FORWARD for its whole length** (decision 1740). The reference's
-    /// apply plants the bit as part of the launch (`0x6179c0`'s `0x617a18 or edx,0x8001` — set bit
-    /// 0, clear bit 1) and only the arc's end clears it; the send mask
-    /// (`0x618909 and edx,0x75a07dff`) keeps bit 0, so observers get it on every packet of the
-    /// flight. We sent a bare FALLING instead, and observers replayed a knockback as a plain drop.
-    ///
-    /// It is the same bit that makes the arc unsteerable, which is why the two are one fact set in
-    /// one place — see [`super::mover`]'s air-control gate.
     #[test]
     fn a_knockback_arc_plants_forward_on_the_wire() {
         let mut player = Player {
             knock_arc: true,
             ..Default::default()
         };
-        // Airborne, no keys held at all — nothing else could produce a direction bit.
+        // Airborne with no keys held: nothing else sets a direction bit.
         let f = this_frame(
             &mut player,
             &still(),
@@ -368,7 +280,7 @@ mod tests {
         );
         assert!(f.wire & move_flags::FALLING != 0, "still an airborne arc");
 
-        // The same frame without the knockback provenance streams no direction at all.
+        // Without the knockback, the same frame streams no direction.
         let mut plain = Player::default();
         let f = this_frame(
             &mut plain,
diff --git a/crates/benilla-app/src/player/follow.rs b/crates/benilla-app/src/player/follow.rs
index d6eacb42..4f05bcc3 100644
--- a/crates/benilla-app/src/player/follow.rs
+++ b/crates/benilla-app/src/player/follow.rs
@@ -1,84 +1,20 @@
-//! `/follow` — the auto-follow movement mode (decisions 0890, 0893).
+//! `/follow`, the auto-follow movement mode. It synthesizes input through the setter the
+//! MoveForward binding drives (`0x60e790` sets move-forward `0x100000`, `0x60e7f0` clears it), so
+//! the controller moves the body and nothing goes on the wire (vmangos has no follow opcode). It
+//! beelines with no path (`0x610e40`; `0x670630` only reads click-to-move), ignores the followee's
+//! speed, and does not end on arrival.
 //!
-//! The finding that shapes this module: **follow synthesizes keyboard input.** It owns no
-//! translation of its own. Every state change in the reference funnels through the movement
-//! singleton's setter (`0x60e790` sets the move-forward bit `0x100000`, `0x60e7f0` clears it) — the
-//! same setter the MoveForward keybinding drives, one of ~40 stubs in the keybinding command table
-//! at `0x513de0`-`0x514273`. So follow is "hold W for me, and steer", and the right implementation
-//! reuses the controller wholesale rather than growing a second mover.
+//! A player's movement start cancels it on the key-down edge: the start emitters call `0x60e990`,
+//! which cancels at `0x60e9b5` unless bit 0 of `ds:0xc4da48` is set, and only follow's own emitters
+//! (`0x60e790`, `0x60e7f0`, `0x60e8a0`, `0x60e940`) set it; ours is a flag,
+//! [`Player::follow_forward`], so it never reaches the cancel. Jump survives (`0x60e990(0, 0)` at
+//! `0x60dea8`), as do key releases, sitting, the walk toggle, damage, combat, mounting, casting and
+//! the followee leaving range (`0x6107e5` skips follow's mode at `0x610749`, `0x610752`).
 //!
-//! It also sends **nothing on the wire** — corroborated against vmangos, which has no follow opcode
-//! in 1.12.1. The server only ever sees the ordinary movement stream our synthesized input produces.
-//!
-//! ## The motion law
-//!
-//! - **Facing is steered, never snapped** (`0x6103d0`/`0x6108xx`): turn toward the followee at
-//!   [`TURN_RATE`] = π rad/s (180°/s), clamped to `min(remaining, rate × elapsed)`, and stop turning
-//!   inside a [`TURN_DEADZONE`] of 0.001 rad. That rate limit is why follow *reads* like a character
-//!   running rather than a camera snapping.
-//! - **Beeline, re-aimed every tick** (`0x610e40`): the guid and both positions are re-resolved every
-//!   tick and nothing is cached. No path, no spline — `0x670630` is a *getter* over the click-to-move
-//!   order, which follow reads and never writes.
-//! - **It never reads the followee's speed** (VERIFIED negative, whole-graph scan). You move at
-//!   whatever a held forward key yields for *you*, which is why follow falls behind a faster runner.
-//! - **A hysteresis band, not a stop distance** — see [`should_move`]. Arrive is inclusive, resume is
-//!   one-directional. The gap between the two is why follow visibly starts and stops rather than
-//!   juddering on a single threshold. Arrival does **not** end the follow.
-//!
-//! ## The cancel set — what actually makes this a *mode*
-//!
-//! **Every player-initiated movement START cancels the follow, on the key-DOWN edge.** A key
-//! *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. 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.**
-//!
-//! We need no bracket of our own, because our synthesized input is [`Player::follow_forward`] — a
-//! flag the controller reads, never a key event — so it cannot reach the cancel at all.
-//!
-//! | action | benilla key | verdict |
-//! |---|---|---|
-//! | MoveForward / MoveBackward | `W` / `S` | **cancels** (key-DOWN) |
-//! | TurnLeft / TurnRight | `A` / `D` | **cancels** (key-DOWN) |
-//! | StrafeLeft / StrafeRight | `Q` / `E` | **cancels** (key-DOWN) |
-//! | ToggleAutoRun | `MouseButton::Forward` | **cancels**, on the ON edge only |
-//! | both-mouse-buttons run | `L`+`R` | **cancels**, on the both-held transition |
-//! | mouse-look turning | `R` held | **cancels** while held, however far the mouse moved |
-//! | **Jump** | `Space` | **survives** — the one emitter passing `0x60e990(0,0)` (`0x60dea8`) |
-//! | Sit / stand | — | **survives** (a `CMSG_STANDSTATECHANGE`, no guard call) |
-//! | walk/run toggle | — | **survives** |
-//! | any key release | — | **survives** |
-//!
-//! Plus the non-input cancels: **losing the mover** (death, stun, a taxi hand-off — the reference's
-//! second, rarer site at `0x5146d6`), the followee becoming unresolvable or **dying**, and the
-//! degenerate-bearing guard below.
-//!
-//! ## What is deliberately NOT here
-//!
-//! **The ~180° turn-away cancel is drunk-only, and is therefore absent.** 0890 shipped it as an
-//! INFERRED rule with a latch invented to make the 160°-220° band self-consistent. The band is
-//! real (`0x80c604` = 2.7925267 rad, `0x80c600` = 3.8397243 rad, both strict) — but its whole
-//! evaluation is gated at `0x610a3d` on an argument that is the **inebriation fraction**,
-//! `min([[unit+0xe68]+0x1d], 100) × 0.01`. That byte is proven to be drunkenness by two independent
-//! consumers of the identical expression: the `DRUNK_MESSAGE_SELF%d` formatter at `0x5e2ac3`, and
-//! `0x60001a` comparing the same fraction against 0.5 to pick an animation state. **On a sober
-//! character the band never executes**, so a client that does not model inebriation must not
-//! implement it — and benilla does not. (Its real arming trigger is turn-*convergence*, not "inside
-//! the band", with a stochastic disarm at `0x61092e`; recorded for whoever adds drunkenness.)
-//!
-//! Also refuted by census, each a real "surely this cancels follow?" candidate: taking damage,
-//! entering combat, mounting, beginning a cast, and the followee simply going out of range
-//! (`0x6107e5` explicitly excludes follow's mode at `0x610749`/`0x610752`).
-//!
-//! ## The start gate lives elsewhere
-//!
-//! Who you may begin following — a living, assistable **player**, and only while you are alive,
-//! unstunned and not casting — is [`crate::target::by_name`]'s, because that is where the subject
-//! is resolved. The refusals it raises are real error lines, not silence.
+//! The reference's turn-away cancel (160°-220°, `0x80c604`, `0x80c600`) runs only while drunk,
+//! gated at `0x610a3d` on the drunk fraction, armed as the turn converges and disarmed at random
+//! (`0x61092e`); it is not built. The start gate (who may be followed) is
+//! [`crate::target::by_name`]'s.
 
 use std::f32::consts::PI;
 
@@ -89,47 +25,33 @@ use crate::net::GuidIndex;
 use super::camera::{CameraControl, LookButton};
 use super::state::{MoveSpeed, Player};
 
-/// Follow's facing-turn rate, rad/s — `0xc4d93c`, seeded `0x40490fdb` = π at `0x6111f9`. Its own
-/// constant, distinct from the keyboard turn rate.
+/// Follow's turn rate in rad/s, its own (`0xc4d93c`, seeded at `0x6111f9`), not the keyboard's.
 const TURN_RATE: f32 = PI;
 
 /// Inside this many radians of the bearing, follow stops turning (`0x6108bb` → `0x60e920`).
 const TURN_DEADZONE: f32 = 0.001;
 
-/// The speed the distance thresholds are normalised by — `.rdata 0x80c4d0` = 7.0, which is also
-/// vanilla's base run speed, so at normal speed the band is exactly 3.0 / 4.5 yd.
+/// The speed the thresholds scale by (`0x80c4d0`), the base run speed.
 const SPEED_NORM: f32 = 7.0;
 
-/// The base stop distance — `.rdata 0x80c4c0` = 3.0, a compile-time constant (its three writers are
-/// CRT dynamic initializers behind `_initterm`), **not** a cvar.
+/// The base stop distance (`0x80c4c0`), a constant, not a CVar.
 const STOP_DISTANCE: f32 = 3.0;
 
-/// Resume is 1.5× the stop distance, and its speed scale is floored at 1.0 — so the band never
-/// closes below 3.0 / 4.5 yd however slowly you are moving.
+/// Resume sits at 1.5× the stop distance.
 const RESUME_FACTOR: f32 = 1.5;
 
-/// `cos(1°)`. The degenerate-bearing guard at `0x610d32` ends the follow once the followee sits
-/// within one degree of straight up or down (`|dy| / dist > cos 1°`) — at which point the
-/// horizontal bearing a beeline needs is numerically meaningless. Held in `0xc4d9d0`, seeded at
-/// `0x610c8d` from `.rdata 0x80c5f8`.
+/// `cos 1°` (`0xc4d9d0`, from `0x80c5f8`), the vertical guard's threshold (`0x610d32`).
 const VERTICAL_ALIGN_COS: f32 = 0.999_847_7;
 
-/// Who we are following, and the hysteresis latch — the reference's followed-guid pair `0xc4d980`
-/// (armed `0x6111c9`, cleared `0x60fc1e`; **exactly two writers each**, earned by an
-/// opcode-agnostic raw-byte scan for the little-endian addresses, not a literal-displacement grep).
+/// Who we follow; the reference's guid `0xc4d980` is set at `0x6111c9`, cleared at `0x60fc1e`.
 #[derive(Resource, Default)]
 pub(crate) struct FollowState {
-    /// The followee's guid, or `None` when not following.
     pub(crate) guid: Option<u64>,
-    /// The followee's name as it read at the moment the follow began — what
-    /// `AUTOFOLLOW_BEGIN`'s argument carries, and therefore what the status text says. Latched
-    /// rather than re-read so the line can't change under a rename or a cache eviction mid-follow.
+    /// The followee's name at the start, `AUTOFOLLOW_BEGIN`'s argument, latched for the status.
     pub(crate) name: String,
-    /// Whether the synthesized forward input is currently held. The band's latch: which threshold
-    /// applies depends on which side we are already on.
+    /// The band's latch: the synthesized forward input is held.
     moving: bool,
-    /// `WOW_FOLLOW_TRACE` bookkeeping: when the last trace line went out, and where we were.
-    /// `None` until a tick has seeded it.
+    /// `WOW_FOLLOW_TRACE` bookkeeping: the last trace line's time and position.
     traced_at: f64,
     traced_pos: Option<Vec3>,
 }
@@ -144,45 +66,34 @@ impl FollowState {
         self.traced_pos = None;
     }
 
-    /// Stop following. Returns whether we actually were.
+    /// Stop following; `true` if we were.
     pub(crate) fn stop(&mut self) -> bool {
         self.moving = false;
         self.guid.take().is_some()
     }
 }
 
-/// Start following — the app-side funnel every entry point converges on, whether it came from the
-/// chat parser (decision 0881 parses slash lines in Rust) or from the Era API globals the shipped
-/// UI calls ([`benilla_ui::script::FollowRequest`], via [`crate::ui_follow`]).
-///
-/// The two variants are the reference's own two bindings. They differ in how the subject is *found*
-/// — a name resolves players only and through the by-name resolver's filter mode 2, a token takes
-/// whatever it points at — but **not** in what is allowed: the start gate downstream applies to
-/// both alike, which is why `/follow` on a creature refuses either way.
+/// A start-following request: the chat input's `/follow`, or the UI's `FollowUnit`/`FollowByName`.
+/// A name finds players only; the start gate refuses a creature either way.
 #[derive(bevy::ecs::message::Message, Clone, Debug)]
 pub(crate) enum FollowRequest {
-    /// `FollowUnit(unit)` — the bare `/follow` is `FollowUnit("target")`.
+    /// `FollowUnit(unit)`; a bare `/follow` is `FollowUnit("target")`.
     Unit(String),
-    /// `FollowByName(name, exactMatch)`. `exact` is the second Lua argument: the unit popup's
-    /// Follow row passes `1` (it already knows the exact name and must not prefix-match onto a
-    /// bystander), `/follow <name>` passes nothing.
+    /// `FollowByName(name, exactMatch)`: the unit popup passes `1`, `/follow <name>` nothing.
     Name { name: String, exact: bool },
 }
 
-/// The distance at which follow **arrives** and lets go of the key (`0x610ad2`-`0x610b1b`):
-/// `(speed / 7.0) × 3.0`, tested inclusively (`test ah,0x41; jp` — the `<=` edge).
+/// Follow arrives and lets go of the key at this distance or closer (`0x610ad2`-`0x610b1b`).
 fn arrive_distance(speed: f32) -> f32 {
     (speed / SPEED_NORM) * STOP_DISTANCE
 }
 
-/// The distance at which a stopped follow **resumes** (`0x610bc4`-`0x610c2b`):
-/// `3.0 × 1.5 × max(speed / 7.0, 1.0)` = 4.5 yd at normal run speed. Only consulted while stopped.
+/// A stopped follow resumes at this distance or beyond (`0x610bc4`-`0x610c2b`).
 fn resume_distance(speed: f32) -> f32 {
     STOP_DISTANCE * RESUME_FACTOR * (speed / SPEED_NORM).max(1.0)
 }
 
-/// Should the synthesized forward key be held this tick? The band, as a pure function of which side
-/// we are already on — the whole reason follow starts and stops instead of juddering.
+/// Whether the forward key is held this tick: a hysteresis band, so follow does not judder.
 fn should_move(was_moving: bool, distance: f32, speed: f32) -> bool {
     if was_moving {
         // Arrive is inclusive, so we keep going only while strictly beyond it.
@@ -192,15 +103,8 @@ fn should_move(was_moving: bool, distance: f32, speed: f32) -> bool {
     }
 }
 
-/// Does this frame's input **destroy** the follow? See the module header's table for the census
-/// and for what is deliberately absent.
-///
-/// `move_start` is the key-DOWN **edge** of any movement start (W/S/A/D/Q/E), never held state —
-/// the reference cancels in the START emitters and its STOP siblings carry no guard call at all,
-/// which is why letting go of a key never resumes a follow you just broke. `autorun_engaged` is
-/// likewise the ON edge only (the OFF edge routes to the unguarded `0x60dc90`). `mouse_look` is a
-/// *level*, not an edge: the camera's facing commit re-enters the guard every frame the look is
-/// held, regardless of how far the mouse actually moved.
+/// `move_start` and `autorun_engaged` are key-down edges (the stop emitters and autorun's off edge,
+/// `0x60dc90`, have no guard call); `mouse_look` is a level, re-entering the guard every frame.
 fn follow_cancelled(
     move_start: bool,
     autorun_engaged: bool,
@@ -211,32 +115,26 @@ fn follow_cancelled(
     move_start || autorun_engaged || both_engaged || mouse_look || lost_mover
 }
 
-/// Wrap an angle into `(-π, π]`.
+/// Wrap an angle into `[-π, π)`.
 fn wrap_pi(a: f32) -> f32 {
     let t = std::f32::consts::TAU;
     let x = (a + PI).rem_euclid(t);
     x - PI
 }
 
-/// The `face_yaw` that points at a horizontal delta in **Bevy** space.
-///
-/// Derived from the controller's own forward vector rather than from a coordinate convention:
-/// `control` builds `move_fwd = Quat::from_rotation_y(face_yaw) * NEG_Z`, which expands to
-/// `(-sin y, 0, -cos y)`. Solving `(-sin y, -cos y) ∝ (dx, dz)` gives `y = atan2(-dx, -dz)`. Tied to
-/// the expression it must agree with, so it cannot drift out of sign with it.
+/// The `face_yaw` pointing at a horizontal Bevy-space delta, matching `control`'s forward
+/// `from_rotation_y(y) * NEG_Z = (-sin y, 0, -cos y)`: `y = atan2(-dx, -dz)`.
 fn bearing_to(delta: Vec3) -> f32 {
     (-delta.x).atan2(-delta.z)
 }
 
-/// Is the followee within one degree of straight up or down? `0x610d32`'s guard — at that point the
-/// horizontal bearing is numerically meaningless and the follow ends rather than spinning.
+/// The followee is within 1° of straight up or down, where the bearing means nothing (`0x610d32`).
 fn vertically_degenerate(delta: Vec3) -> bool {
     let dist = delta.length();
     dist > f32::EPSILON && delta.y.abs() / dist > VERTICAL_ALIGN_COS
 }
 
-/// Turn `face` toward `bearing` by at most this tick's budget, or leave it alone inside the
-/// deadzone. The reference's `min(remaining, rate × elapsed)` clamp.
+/// Turn toward `bearing` by at most `rate × dt`, not inside the deadzone (`0x6103d0`).
 fn steer(face: f32, bearing: f32, dt: f32) -> f32 {
     let remaining = wrap_pi(bearing - face);
     if remaining.abs() <= TURN_DEADZONE {
@@ -246,40 +144,24 @@ fn steer(face: f32, bearing: f32, dt: f32) -> f32 {
     face + remaining.clamp(-budget, budget)
 }
 
-/// Everything the cancel set reads. Bundled so [`steer_follow`]'s own parameter list stays about
-/// the motion.
+/// Everything the cancel set reads.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(super) struct FollowInput<'w, 's> {
     buttons: Res<'w, ButtonInput<MouseButton>>,
-    /// The binding dispatch (0997) — the movement commands' press edges, wherever they are bound.
-    /// It already carries the typing gate this struct used to hold `UiKeyboardCapture` for
-    /// (typing "we should go" in chat must not break the follow).
+    /// The movement commands' press edges, wherever bound; typing in chat does not reach them.
     binds: Res<'w, crate::bindings::BindingsState>,
-    /// The camera rig, for the mouse-look level and the world's own mouse buttons
-    /// ([`super::camera::WorldMouse`]). The look level is read one frame behind `control`'s own update,
-    /// which is deliberate and harmless: the cancel then lands on the frame *after* the look
-    /// begins, versus the reference's same-frame commit. The button latch is **not** behind —
-    /// [`super::camera::latch_world_mouse`] is ordered ahead of this system precisely so the both-button
-    /// cancel below sees this frame's edge.
+    /// The mouse-look level, read a frame behind `control`, so its cancel lands a frame after the
+    /// reference's; the world's mouse buttons are current ([`super::camera::latch_world_mouse`]
+    /// runs first).
     rig: Res<'w, CameraControl>,
-    /// The **mover's** descriptor block, for the terms of the cancel set that are not inputs:
-    /// its health and its stun. See [`FollowInput::input_torn_down`].
+    /// The mover's descriptor block, for the cancel terms that are state: health and stun.
     mover: Query<'w, 's, &'static crate::net::ObjectStore, With<crate::net::Embodied>>,
-    /// What the camera orbits ([`super::view_subject`]) — the resolved half of the shared
-    /// precondition's far-sight conjunct, which takes both predicates down and so reaches the
-    /// teardown leg on its own (decision 1761).
-    ///
-    /// Read possibly one frame behind, like `rig` above and for the same benign reason: the
-    /// publisher and this system are both merely `.before(control)` and are unordered against each
-    /// other, so a follow engaged and far-sighted on the very same frame ends on the next one.
+    /// What the camera orbits, for the far-sight term; possibly a frame behind its publisher.
     view_subject: Res<'w, super::view_subject::ViewSubject>,
 }
 
 impl FollowInput<'_, '_> {
-    /// The press edge of any movement command (0997: wherever the six are bound today). The turn
-    /// pair are turn commands normally and strafe under mouse-look; either way they are a
-    /// movement start and either way they cancel, so the distinction the controller draws does
-    /// not matter here.
+    /// The press edge of any of the six movement commands; turn and strafe both cancel.
     fn move_start(&self) -> bool {
         use crate::bindings::cmd;
         [
@@ -294,20 +176,9 @@ impl FollowInput<'_, '_> {
         .any(|&c| self.binds.just_pressed(c))
     }
 
-    /// Has the input tick reached its **teardown leg** — the one that cancels click-to-move and the
-    /// 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.
-    ///
-    /// 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
-    /// corpse's facing every frame — does. Ice Block, root and stun together, ends it as well.
-    ///
-    /// **Far sight ends it too**, and for the same structural reason death does rather than as a
-    /// case of its own: the far-sight conjunct sits in the precondition the two predicates *share*,
-    /// so engaging it takes both down at once and lands on this leg.
+    /// The input tick's teardown leg ([`super::state::MoverInput::torn_down`]), which the reference
+    /// takes (`0x5146d6 call 0x60fb60`) only with both predicates down (`0x5146c3`, `0x5146ce`):
+    /// death, far sight, or root and stun together end a follow, a root alone does not.
     fn input_torn_down(&self, rooted: bool, driving_own_body: bool) -> bool {
         self.mover.single().is_ok_and(|s| {
             super::state::MoverInput {
@@ -322,14 +193,9 @@ impl FollowInput<'_, '_> {
     }
 }
 
-/// Drive the follow: cancel if this frame's input says so, then re-resolve the followee, steer the
-/// facing, and decide whether the synthesized forward input is held this tick. Runs immediately
-/// **before** `control`, which reads [`Player::follow_forward`] as one more term of its forward
-/// axis — the reference's shape exactly, where follow pushes the same move-forward bit W does.
-///
-/// The cancel runs before the steer for the reference's own reason: it lives in the movement START
-/// emitters, which run ahead of the axis math (`0x5150a7` vs the emitter tail `0x5151a0`), so the
-/// frame you break a follow on is a frame the follow never steers.
+/// Cancel, re-resolve the followee, steer, and set [`Player::follow_forward`] for `control`. The
+/// cancel comes first, as the reference's start emitters run ahead of the axis math (`0x5150a7` vs
+/// the emitter tail `0x5151a0`).
 pub(super) fn steer_follow(
     time: Res<Time>,
     mut follow: ResMut<FollowState>,
@@ -343,24 +209,20 @@ pub(super) fn steer_follow(
     if follow.guid.is_none() {
         return;
     }
-    // ── The cancel set ── before anything else this frame (see the doc above).
-    // Off the WORLD's buttons ([`super::camera::WorldMouse`], ledger B364), not the device's: the
-    // reference's both-button run is its two bindings held, and a press a UI frame captured
-    // dispatches neither — so two primaries pressed over a bag are two clicks, not a cancel.
+    // ── The cancel set ──
+    // The world's buttons, not the device's: the both-button run is two bindings held, and a
+    // press a UI frame captured dispatches neither.
     let both_engaged = input.rig.world_mouse.both()
         && (input.rig.world_mouse.down(LookButton::Left)
             || input.rig.world_mouse.down(LookButton::Right));
     if follow_cancelled(
         input.move_start(),
-        // The ON edge only: `control` toggles `autorun` AFTER this runs, so the flag we read here
-        // is still the pre-toggle value, and "press while off" is exactly the engage.
+        // The on edge: `control` toggles `autorun` after this, so the flag is the pre-toggle value.
         input.buttons.just_pressed(MouseButton::Forward) && !player.autorun,
         both_engaged,
         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), and nothing known bears on it either way, so it
-        // is left exactly as it stood.
+        // The teardown leg, or the body handed to a server spline; the ride term is not one of the
+        // reference's conjuncts (`0x5144e0`), and its reference side is untraced.
         input.input_torn_down(player.modes.rooted, player.foreign_mover.is_none())
             || player.server_riding(),
     ) {
@@ -369,8 +231,7 @@ pub(super) fn steer_follow(
         return;
     }
     let Some(guid) = follow.guid else { return };
-    // Re-resolved every tick, nothing cached — a followee that streams out ends the follow
-    // (`0x610e40` → `0x6106e7`).
+    // A followee that streams out ends the follow (`0x610e40` → `0x6106e7`).
     let Some(target) = index
         .0
         .get(&guid)
@@ -382,8 +243,7 @@ pub(super) fn steer_follow(
         return;
     };
     let delta = target - player.pos;
-    // The degenerate-bearing guard (`0x610d32`), checked on the FULL 3D delta before the bearing is
-    // taken from the flattened one.
+    // On the full 3D delta, before the bearing flattens it.
     if vertically_degenerate(delta) {
         info!("follow: the followee is within 1° of straight overhead — follow ends");
         follow.stop();
@@ -406,15 +266,11 @@ pub(super) fn steer_follow(
             speed.value,
         );
     }
-    // `WOW_FOLLOW_TRACE=1` — the field instrument for "follow won't catch up / overshoots": one
-    // line a second carrying the closing distance and the ground we actually covered, so the
-    // travel rate is a measured number rather than an end-to-end guess (decision 0404: timing and
-    // feel are measured, never eyeballed). Gated because this one IS per-frame.
+    // `WOW_FOLLOW_TRACE=1`: once a second, the distance left and the ground covered.
     if follow_trace_on() {
         let now = time.elapsed_secs_f64();
         if now - follow.traced_at >= 1.0 {
-            // Quiet until a tick has seeded a reference point: an instrument whose opening line is
-            // garbage is worse than one that says nothing for a second.
+            // Silent until a first tick seeds the start point.
             if let Some(from) = follow.traced_pos {
                 let elapsed = now - follow.traced_at;
                 let moved = player.pos.distance(from);
@@ -432,14 +288,13 @@ pub(super) fn steer_follow(
     player.follow_forward = moving;
 }
 
-/// `WOW_FOLLOW_TRACE=1` — see [`steer_follow`]. One `OnceLock` read per tick when unset.
+/// Whether `WOW_FOLLOW_TRACE` is set, read once.
 fn follow_trace_on() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_FOLLOW_TRACE").is_some())
 }
 
-/// Register the follow mode. The steer runs in the input stage just before `control`, so the flag
-/// and the facing it writes are what the controller reads this same frame.
+/// Register the follow state and its request message.
 pub(super) fn plugin(app: &mut App) {
     app.init_resource::<FollowState>()
         .add_message::<FollowRequest>();
@@ -457,29 +312,23 @@ mod tests {
 
     #[test]
     fn resume_scales_with_speed_but_never_below_the_base_band() {
-        // Above base speed both thresholds stretch…
         assert_eq!(arrive_distance(14.0), 6.0);
         assert_eq!(resume_distance(14.0), 9.0);
-        // …below it, arrive shrinks but resume is FLOORED at the 1.0 scale (the `max` in `0x610bfd`),
-        // so the band can never invert.
+        // Below base speed, resume's scale is floored at 1.0 (`0x610bfd`).
         assert!(arrive_distance(3.5) < 3.0);
         assert_eq!(resume_distance(3.5), 4.5);
     }
 
     #[test]
     fn the_hysteresis_band_latches_on_both_edges() {
-        // Moving: keep going until strictly inside arrive (which is inclusive, so 3.0 stops).
         assert!(should_move(true, 3.001, 7.0));
         assert!(!should_move(true, 3.0, 7.0), "arrive is inclusive");
-        // Stopped: nothing happens until resume, so the gap between 3.0 and 4.5 is dead in BOTH
-        // directions — that gap is the whole point of the band.
         assert!(!should_move(false, 4.0, 7.0));
         assert!(should_move(false, 4.5, 7.0));
     }
 
     #[test]
     fn bearing_agrees_with_the_controllers_own_forward_vector() {
-        // The invariant that keeps this from drifting out of sign with `control`.
         for (dx, dz) in [
             (0.0, -1.0),
             (1.0, 0.0),
@@ -502,22 +351,18 @@ mod tests {
 
     #[test]
     fn the_turn_is_rate_limited_and_has_a_deadzone() {
-        // A quarter turn at 180°/s takes 0.5 s, so one 0.1 s tick covers 18°, not the whole 90°.
+        // 180°/s for a 0.1 s tick is 18° of the 90°.
         let after = steer(0.0, PI / 2.0, 0.1);
         assert!(
             (after - TURN_RATE * 0.1).abs() < 1e-6,
             "clamped to the budget"
         );
-        // Within the budget it lands exactly on the bearing rather than overshooting.
         assert!((steer(0.0, 0.05, 1.0) - 0.05).abs() < 1e-6);
-        // Inside the deadzone it does not move at all.
         assert_eq!(steer(1.0, 1.0 + TURN_DEADZONE / 2.0, 1.0), 1.0);
     }
 
     #[test]
     fn steering_takes_the_short_way_round() {
-        // Bearing just past -π from a facing just under π: the turn must be a small positive step,
-        // not a near-full sweep back the other way.
         let after = steer(PI - 0.05, -PI + 0.05, 1.0);
         assert!(
             wrap_pi(after - (PI - 0.05)) > 0.0,
@@ -525,40 +370,28 @@ mod tests {
         );
     }
 
-    /// The cancel set's table, in its own terms. Each argument is one row of the module header, and
-    /// the two that matter most are the FALSE ones: jump and a plain key release are VERIFIED
-    /// survivors, not oversights — they reach the guard with `realStart = 0` or never reach it.
+    /// Jump and key releases survive: they reach the guard with `realStart = 0` or never reach it.
     #[test]
     fn any_movement_start_cancels_but_jump_and_releases_do_not() {
-        // Nothing happening: a follow just keeps following, however long it runs.
         assert!(!follow_cancelled(false, false, false, false, false));
-        // Each start, alone, is enough.
         assert!(follow_cancelled(true, false, false, false, false));
         assert!(follow_cancelled(false, true, false, false, false));
         assert!(follow_cancelled(false, false, true, false, false));
         assert!(follow_cancelled(false, false, false, true, false));
-        // Losing the mover — death, stun, a taxi hand-off — is a LEVEL, not an edge.
         assert!(follow_cancelled(false, false, false, false, true));
-        // Jump and key releases never become any of those arguments (see `FollowInput::move_start`,
-        // which reads `just_pressed` and does not list Space at all), so the all-false row above IS
-        // the jump case — asserted here so deleting Space's absence breaks a test.
         assert!(
             !follow_cancelled(false, false, false, false, false),
             "a jump leaves every cancel input false"
         );
     }
 
-    /// The degenerate-bearing guard (`0x610d32`) — a followee straight overhead ends the follow,
-    /// one a degree off the vertical does not. The horizontal case must be nowhere near it.
     #[test]
     fn a_followee_straight_overhead_ends_the_follow() {
         assert!(vertically_degenerate(Vec3::new(0.0, 30.0, 0.0)));
         assert!(vertically_degenerate(Vec3::new(0.0, -30.0, 0.0)));
-        // 1° off vertical is outside the guard: tan(1°) ≈ 0.01746, so 30 yd up needs > 0.52 yd out.
+        // tan(1°) ≈ 0.01746, so 30 yd up needs more than 0.52 yd out.
         assert!(!vertically_degenerate(Vec3::new(0.6, 30.0, 0.0)));
-        // The ordinary case — a followee on roughly your own level — is untouched.
         assert!(!vertically_degenerate(Vec3::new(10.0, 2.0, 5.0)));
-        // A zero delta is not "degenerate": it is the arrived case, which the band owns.
         assert!(!vertically_degenerate(Vec3::ZERO));
     }
 }
diff --git a/crates/benilla-app/src/player/gait.rs b/crates/benilla-app/src/player/gait.rs
index 704da400..3f56bd14 100644
--- a/crates/benilla-app/src/player/gait.rs
+++ b/crates/benilla-app/src/player/gait.rs
@@ -1,42 +1,19 @@
-//! The rendered **body heading** + the animation's view of the flags — the client's display-facing
-//! 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.
+//! The rendered body heading and the animation's view of the flags, the reference's display facing
+//! (the `0x607ed0` tail). [`super::control`] calls [`drive_body_heading`] once per controlled
+//! frame, after the move flags are final.
 
 use crate::creature_anim::{ease_strafe_yaw, move_flags, strafe_body_offset, wrap_pi};
 
 use super::{Player, STATIONARY_CHASE_RATE};
 
-/// Advance `model_yaw` (the rendered body heading) one frame and return the **animation's** view of
-/// the move flags (the wire keeps the real key flags — observers integrate the facing from them):
-///
-///  · **strafing** — the root turns to `face_yaw ± 90°` (pure) / `± 45°` (diagonal, mirrored
-///    when backpedaling), eased a quarter of the remaining gap per frame **in aim-relative
-///    offset space** (a left↔right flip is an exact 180° tie in absolute yaw — offset space
-///    always swings it around the front); the SpineLow/Head counter-twist walks the upper
-///    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 (`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
-///    aim at 8× the turn rate (~63 ms for 90°). The lag mechanism is the freeze, not a slow
-///    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 (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
-/// the frozen chase holds the body under a leading head, the feet hold too, and a stationary
-/// MOUSE turn shuffles once the body steps (no key flag involved). A deck turning under the rider
-/// carries `model_yaw` rigidly at the ride block, so it never registers as a body step here —
-/// the shuffle (and its keyframed step sounds) only ever sees real turns (decision 0458/0466).
-// The eighth parameter arrived with the possessed mover's own turn rate (1278) and clippy's
-// default bound is seven. These are one frame of mover state, each read from a different one of
-// the caller's queries — bundling them into a struct would name nothing the call site does not
-// already say, and the gate is `-D warnings`, so the honest move is to say why, here.
+/// Advances `model_yaw` one frame and returns the animation's view of the move flags (the wire
+/// keeps the real key flags). Strafing eases the body toward `face_yaw ± 90°` (`± 45°` diagonal,
+/// mirrored backpedaling) by a quarter of the gap a frame in aim-relative offset space, so a
+/// left-right flip swings round the front. Moving forward or back or airborne (`flags & 0x2003`),
+/// or swimming, snaps it to the aim; standing runs the frozen chase (`0x6081bf`), holding the 90°
+/// ceiling while the aim is steered, then sweeping onto it at 8× the turn rate. The swim pitch is
+/// applied at the transform write (`0x60a110`). The turn-in-place shuffle keys on the body's own
+/// rotation (chase-step bits `0x800`/`0x1000`), not the turn keys, so a deck's turn never shuffles.
 pub(super) fn drive_body_heading(
     player: &mut Player,
     move_flags_now: u32,
@@ -45,8 +22,7 @@ pub(super) fn drive_body_heading(
     moving: bool,
     airborne: bool,
     steering: bool,
-    // The mover's own turn rate (rad/s) — the release sweep is a multiple of it, so a possessed
-    // creature's body settles onto its aim at the creature's pace (decision 1278).
+    // The mover's own turn rate in rad/s: a possessed creature settles at its own pace.
     turn_rate: f32,
 ) -> u32 {
     let strafe_offset = if swimming {
@@ -87,10 +63,6 @@ pub(super) fn drive_body_heading(
 mod tests {
     use super::*;
 
-    /// The release sweep is a multiple of the **mover's** turn rate, not of a constant. It is the
-    /// one place the rate reaches the *rendered* body rather than the aim, so a possessed creature
-    /// with a slow turn rate would otherwise snap its body around at a human's pace while its
-    /// facing crawled — the head and the body disagreeing about what they are attached to.
     #[test]
     fn the_standing_body_sweeps_back_at_the_movers_own_rate() {
         let sweep = |turn_rate: f32| {
@@ -102,7 +74,7 @@ mod tests {
             drive_body_heading(&mut player, 0, 0.01, false, false, false, false, turn_rate);
             player.model_yaw
         };
-        // Below the 90° ceiling, the whole step is the sweep — so it scales linearly with the rate.
+        // Below the 90° ceiling the whole step is the sweep, so it scales with the rate.
         let slow = sweep(std::f32::consts::PI / 4.0);
         let fast = sweep(std::f32::consts::PI);
         assert!(slow > 0.0 && fast > slow);
@@ -110,7 +82,7 @@ mod tests {
             (fast / slow - 4.0).abs() < 1e-3,
             "a 4× turn rate sweeps 4× as far in a frame: {slow} vs {fast}"
         );
-        // Steering freezes the chase whatever the rate — the byte rule, not a slow sweep.
+        // Steering freezes the chase whatever the rate.
         let mut player = Player {
             face_yaw: 1.0,
             model_yaw: 0.0,
diff --git a/crates/benilla-app/src/player/input.rs b/crates/benilla-app/src/player/input.rs
index 12afb6ba..e1b3bf26 100644
--- a/crates/benilla-app/src/player/input.rs
+++ b/crates/benilla-app/src/player/input.rs
@@ -1,20 +1,6 @@
-//! **This frame's decoded input**, in one place — the two things the controller derives from the
-//! keyboard, the mouse and the binding table before any of it means anything to the avatar:
-//!
-//! - [`look_input`] — the both-button state and the reference's own **camera command word**
-//!   (1.12's `[InputControl+0x4]`, decision 1502), which the auto-follow is armed by. Read
-//!   *before* the look session, because both camera seats want it — including the one on the
-//!   not-driving path, which returns before the axes below are ever computed. Its two mouse
-//!   terms come off [`camera::WorldMouse`], never `ButtonInput`: the reference's mouse bits are
-//!   two *bindings* the UI can eat, and reading the device instead swung the camera on every
-//!   right-click of a UI row (ledger B364).
-//! - [`move_axes`] — the **netted** forward/back and strafe axes plus the modes that select
-//!   between them (mouselook, keyboard turn), and the autorun latch with its cancel set. Netted
-//!   once here so that the direction we move, the speed we pick, the swim amounts and the flags we
-//!   stream can never disagree (decision 0056).
-//!
-//! Nothing here touches the avatar: `move_axes` writes exactly one field ([`Player::autorun`]),
-//! because the autorun latch *is* input state.
+//! This frame's decoded input: [`look_input`], the both-button state and the camera command word,
+//! and [`move_axes`], the netted axes with the autorun latch. Netting once keeps the direction,
+//! the speed, the swim amounts and the streamed flags in agreement.
 
 use bevy::prelude::*;
 
@@ -22,38 +8,26 @@ use super::{camera, state, CameraControl, LookButton, Player};
 
 /// What [`look_input`] read off the mouse and the bindings, before the look session runs.
 pub(super) struct LookInput {
-    /// Vanilla's "both-button run" state (either real button pair, or MOVEANDSTEER).
+    /// The both-button run: both mouse buttons held, or MOVEANDSTEER.
     pub both_buttons: bool,
-    /// The camera's input command word — see [`super::camera::follow_cmd`].
+    /// The camera's input command word ([`super::camera::follow_cmd`]).
     pub follow_command: u32,
 }
 
-/// The mouse/binding state the camera needs, built before the look session so the not-driving
-/// path (which returns without ever reaching [`move_axes`]) can seat its camera from the same word.
-///
-/// Takes the rig for one field only — [`camera::WorldMouse`], already latched this frame by
-/// [`camera::latch_world_mouse`]. There is deliberately no `ButtonInput` parameter left: every
-/// mouse fact here is one the UI gets first refusal on.
+/// Built before the look session, so the not-driving path, which never reaches [`move_axes`],
+/// seats its camera from the same word. The mouse terms come from [`camera::WorldMouse`], never
+/// the device: the reference's mouse bits are bindings, so a press the UI took sets neither.
 pub(super) fn look_input(
     binds: &crate::bindings::BindingsState,
     player: &Player,
     rig: &CameraControl,
 ) -> LookInput {
-    // Both mouse buttons held together = vanilla's "both-button run": the avatar runs forward while
-    // the character steers with the mouse (turns like a right-drag), regardless of which button went
-    // down first. Off the world-owned pair, not the device's: both primaries pressed over a bag are
-    // two clicks the UI took, and the reference's run is its two *bindings* held, neither of which
-    // a captured press dispatches.
-    // MOVEANDSTEER (default Middle Mouse) is the same state through a binding — 1.12's own body
-    // runs the identical CameraOrSelectOrMove + TurnOrAction pair a both-button press does.
+    // Both buttons held run forward and steer with the mouse, whichever went down first.
+    // MOVEANDSTEER is the same state: its 1.12 body runs CameraOrSelectOrMove and TurnOrAction.
     let steer_held = binds.pressed(crate::bindings::cmd::MOVE_AND_STEER);
     let both_buttons = rig.world_mouse.both() || steer_held;
 
-    // The camera's **input command word** (decision 1502) — 1.12's `[InputControl+0x4]`, bit for
-    // bit. The auto-follow is armed by *edges on this word* and its state is classified from it, so
-    // it is built once here, from the same binding state the movement code reads, and handed
-    // to both camera seats. MOVEANDSTEER sets both mouse bits because that is what the reference's
-    // binding does — it runs the identical CameraOrSelectOrMove + TurnOrAction pair.
+    // 1.12's `[InputControl+0x4]`, bit for bit: the camera's auto-follow arms on its edges.
     let follow_command = {
         use camera::follow_cmd as bit;
         let mut w = 0;
@@ -70,8 +44,7 @@ pub(super) fn look_input(
             rig.world_mouse.held(LookButton::Left) || steer_held,
             bit::LEFT_MOUSE,
         );
-        // `/follow` is the forward bit in the reference too — the same setter the W key drives
-        // (decision 0890), so it arms the camera exactly like a held W.
+        // `/follow` sets the forward bit through W's own setter, so it arms the camera like W.
         set(
             binds.pressed(crate::bindings::cmd::MOVE_FORWARD) || player.follow_forward,
             bit::FORWARD,
@@ -97,8 +70,8 @@ pub(super) fn look_input(
             bit::TURN_RIGHT,
         );
         set(player.autorun, bit::AUTORUN);
-        // The two externally-driven flags, which the reference folds into the camera's own
-        // Track/Fear bits rather than the input word — carried here so one word carries every edge.
+        // The reference keeps these two in the camera's own Track and Fear bits; here one word
+        // carries every edge.
         set(player.server_riding, bit::TRACK);
         set(player.control_lost, bit::FEAR);
         w
@@ -110,96 +83,66 @@ pub(super) fn look_input(
     }
 }
 
-/// This frame's **netted** movement axes and the modes that shape them. Every forward/back,
-/// strafe and turn consumer downstream reads these fields and not the keys.
+/// This frame's netted movement axes and modes; every consumer downstream reads these, not keys.
 #[derive(Clone, Copy)]
 pub(super) struct MoveAxes {
-    /// Net forward/back: `+1` forward, `-1` back, `0` for a cancelled pair (see
-    /// [`state::forward_axis`]).
+    /// Net forward/back ([`state::forward_axis`]): its sign is the direction, 0 a cancelled pair.
     pub fwd: i32,
-    /// Net strafe, `+` right — Q/E always, A/D only while mouse-looking.
+    /// Net strafe, positive right: Q/E always, A/D only while mouse-looking.
     pub side: i32,
     /// Right-mouse (or both-button) held: A/D strafe and the facing tracks the camera.
     pub mouselook: bool,
-    /// A keyboard turn is being held — and is allowed (a stun kills it).
+    /// A keyboard turn is held and allowed (a stun refuses it).
     pub turning: bool,
-    /// The reference's `flags & 0xf`, off the *net* axes: W+S neither streams nor moves.
+    /// The reference's `flags & 0xf`, off the net axes: W+S neither streams nor moves.
     pub translating: bool,
-    /// Autorun was toggled **on** this frame — 0445's fifth cast-interrupt term, which the
-    /// flag delta cannot see.
+    /// Autorun was toggled on this frame, a cast-interrupt term the flag delta cannot see.
     pub autorun_armed: bool,
-    /// The raw strafe/turn keys, for the consumers that need the pressed state rather than the
-    /// net axis: the swim amounts and the wire's turn bits.
+    /// The raw strafe and turn keys, for the swim amounts and the wire's turn bits.
     pub strafe_left: bool,
     pub strafe_right: bool,
     pub turn_left: bool,
     pub turn_right: bool,
 }
 
-/// Decode the movement keys into [`MoveAxes`], running the autorun latch and its cancel set on
-/// the way through.
+/// Decodes the movement keys into [`MoveAxes`], running the autorun latch and its cancel set.
 pub(super) fn move_axes(
     binds: &crate::bindings::BindingsState,
     buttons: &ButtonInput<MouseButton>,
     player: &mut Player,
     rig: &CameraControl,
     both_buttons: bool,
-    // The reference's two movement-input predicates this frame ([`state::may_translate`],
-    // [`state::may_turn`]) — `0x514560` and `0x5145b0`. Both go down on death (decision 1753).
+    // The reference's input predicates `0x514560` and `0x5145b0` (`state::may_translate`,
+    // `state::may_turn`); death takes both down.
     may_translate: bool,
     may_turn: bool,
 ) -> MoveAxes {
-    // ── Autorun ── TOGGLEAUTORUN through the binding table (0997; 1.12 defaults NUMLOCK +
-    // BUTTON4 — the latter is winit's `Forward`, the thumb button this toggle lived on before
-    // the table existed, kept by the codec's BUTTON4 mapping). A latched mode, not a held key:
-    // the keyboard chord is typing-gated at dispatch like every binding, the mouse chord is
-    // not — and the reference agrees, its **OS window-deactivate** handler releasing every
-    // direction bit while preserving `0x1000` (`0x514490`'s `and eax,0xfffff00f`, VERIFIED;
-    // "window-deactivate" and not "focus-loss", which read as *UI* focus and cost us 2196 —
-    // its sole caller `0x493058` hangs off the WM_ACTIVATE callback slot).
+    // ── Autorun ── TOGGLEAUTORUN, a latch (1.12 defaults NUMLOCK and BUTTON4, winit's
+    // `Forward`). The reference's window-deactivate handler (`0x514490`, called only from the
+    // WM_ACTIVATE slot at `0x493058`) releases every direction bit and keeps `0x1000`.
     let mut autorun_armed = false;
     if binds.fired(crate::bindings::cmd::TOGGLE_AUTORUN) {
         player.autorun = !player.autorun;
         autorun_armed = player.autorun;
     }
-    // A mouse whose extra buttons don't land on Back/Forward would otherwise fail silently, and
-    // "nothing happened" is the least debuggable report there is. Name what did arrive.
+    // Name an extra mouse button the bindings do not know, rather than fail silently.
     for b in buttons.get_just_pressed() {
         if let MouseButton::Other(n) = b {
             info!("mouse: unmapped button Other({n}) — bindings know BUTTON4/BUTTON5 as winit Forward/Back");
         }
     }
-    // ── 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:
-    //
-    // - **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`,
-    //   which does `and [MOVE+4],0xffffefff` under `test cl,0x30` (fwd `0x10` | back `0x20`) at
-    //   `0x514a5a`. A per-handler read answers "no" and is wrong about the behaviour. It runs
-    //   *before* the axis (`0x5150a7` vs the emitter tail `0x5151a0`), so the axis never sees the
-    //   combination. **Key-DOWN only**: the release path `0x514b70` restores nothing, which is why
-    //   letting go of S after reversing leaves you standing rather than running again.
-    // - **The transition INTO both-buttons-held** (`0x514a73`, the same helper) — engaging the
-    //   both-button run replaces autorun rather than stacking with it.
-    // - **Losing the mover** — death, or a root/stun. In the reference the emitter's gate
-    //   `0x514560` goes down (health `<= 0`, `MOVEMENTFLAGS & 0x1200`, stand state 7) and writer #4
-    //   `0x514748` clears the bit as a side effect of the next emit; a level test is the faithful
-    //   shape, not an edge. The `death` half of that sentence was prose only until decision 1753:
-    //   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 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.
-    //
-    // A chat box taking focus survives *more* than autorun, note: it releases nothing at all —
-    // the movement handlers simply become no-ops and the direction bits are frozen (2196), which
-    // is why holding W through an ENTER keeps you running.
+    // ── The cancel set ── What clears autorun is what makes it a mode, not a held forward. Of
+    // the reference's six writers, these have an analog here:
+    // - A W or S key-down, unconditionally: the directional handlers tail into the shared SET
+    //   helper `0x514840`, which clears `0x1000` under `test cl,0x30` at `0x514a5a`, before the
+    //   axis is built (`0x5150a7`, emitter tail `0x5151a0`). The release path `0x514b70` restores
+    //   nothing, so letting go of S after reversing leaves you standing.
+    // - The transition into both buttons held (`0x514a73`, the same helper).
+    // - Losing the mover, a level: the emitter gate `0x514560` down (health `<= 0`,
+    //   `MOVEMENTFLAGS & 0x1200`, stand state 7) makes writer `0x514748` clear the bit at the next
+    //   emit; ours is `state::may_translate`. The server-ride term is benilla's own.
+    // A jump, a chat EditBox taking focus and a zone change leave it set; mounting is untraced and
+    // leaves it set here. A focused chat box releases nothing, so W held through ENTER still runs.
     let both_buttons_engaged = (both_buttons
         && (rig.world_mouse.down(LookButton::Left) || rig.world_mouse.down(LookButton::Right)))
         || binds.just_pressed(crate::bindings::cmd::MOVE_AND_STEER);
@@ -212,40 +155,23 @@ pub(super) fn move_axes(
         player.autorun = false;
     }
     let autorun = player.autorun;
-    // ── The forward/back axis ── one net value ([`state::forward_axis`], whose tests pin the
-    // verified state table) read by every forward/back consumer downstream, so the direction we move,
-    // the speed we pick, the swim amounts and the flags we stream can't disagree (decision 0056).
-    //
-    // Zero is the state no "autorun = held forward" reading can produce, and it is reachable:
-    // hold S *first*, then toggle autorun — the toggle pushes X=`0x1000`, so `test cl,0x30` misses
-    // and the bit survives — and the client emits MSG_MOVE_STOP with S still held. The other order
-    // (autorun, then S) destroys the bit at key-down and walks you backward. Same two keys, two
-    // outcomes; that asymmetry is the whole shape of the feature.
-    // `/follow` enters as the FORWARD term, not a fifth source (decision 0890): the reference's
-    // follow pushes the very same move-forward bit `0x100000` the W key does, through the same
-    // setter, so it nets against a held S and diagonals with a strafe exactly like a held W. It
-    // rides the HELD state and not the key-DOWN edge, so it never trips the autorun cancel set
-    // above — which is right: synthesized input is not a keypress.
+    // ── The forward/back axis ── The order of S and autorun decides: S held, then autorun
+    // toggled, keeps both (the toggle pushes `0x1000`, so `test cl,0x30` misses) and the
+    // reference sends MSG_MOVE_STOP with S held; autorun, then S, clears the bit at key-down and
+    // walks you backward. `/follow` is a held forward, W's own bit `0x100000` through W's setter,
+    // so it nets against S like W and never trips the cancel set, which fires on key-down edges.
     let fwd_axis = state::forward_axis(
         binds.pressed(crate::bindings::cmd::MOVE_FORWARD) || player.follow_forward,
         binds.pressed(crate::bindings::cmd::MOVE_BACKWARD),
         both_buttons,
         autorun,
     );
-    // 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,
-    // so left-drag (camera-only orbit) doesn't change which way W walks.
+    // The 1.12 control model (`0x7c5360`): A/D turn the character unless right-mouse is held,
+    // when they strafe and the facing tracks the camera; Q/E always strafe. W walks along the
+    // character's facing, so a left-drag orbit does not change it.
     let mouselook = both_buttons || rig.look == Some(LookButton::Right);
-    // The strafe axis, **netted exactly like `fwd_axis`** — Q/E always strafe, A/D only while
-    // mouse-looking. Netting is not a nicety: the two bits are mutually exclusive on the wire.
-    // Holding both keys used to OR `STRAFE_LEFT | STRAFE_RIGHT` into the flags while the avatar
-    // stood still (the controller's `dir` sum cancels), and vmangos **silently drops** every movement
-    // packet carrying that pair — never relaying it to anyone (decision 0622). Measured: 48 such
-    // packets in one session, 0 received by a watching client, against 0 in the reference
-    // client's entire 1.12.1 capture. That is decision 0056's invariant — the wire mirrors the
-    // avatar's actual motion — violated on this one axis only; the swim branch already nets.
+    // The strafe axis nets like `fwd_axis`: vmangos relays no packet carrying both strafe bits,
+    // and the reference's 1.12.1 capture sends none.
     let strafe_left = binds.pressed(crate::bindings::cmd::STRAFE_LEFT);
     let strafe_right = binds.pressed(crate::bindings::cmd::STRAFE_RIGHT);
     let turn_left = binds.pressed(crate::bindings::cmd::TURN_LEFT);
@@ -256,18 +182,10 @@ pub(super) fn move_axes(
         } else {
             0
         };
-    // TURNLEFT/TURNRIGHT turn the facing when not mouse-looking (yaw increases turning left,
-    // matching mouse-left). …and never while [`state::may_turn`] is down: the reference skips the
-    // keyboard turn emitter `0x514f50` entirely (and force-stops an in-flight turn) behind the
-    // `0x514755` gate. Killing the turn here is also what ends B179's *second* half — the walk
-    // animation a stunned character was still playing was the turn-in-place shuffle, which
-    // `gait` derives from real yaw change. A **dead** body is down the same gate, through the
-    // precondition `0x5144e0` that both predicates share (decision 1753): health `<= 0` fails it,
-    // so as far as `0x5145b0` is concerned a corpse is stunned — which is why our corpses could
-    // be spun with A/D until 1753, and why one term fixes the keys and the mouse together.
+    // A keyboard turn yaws left-positive, like the mouse, and never while `may_turn` is down: the
+    // reference skips its turn emitter `0x514f50`, and stops one in flight, behind `0x514755`. A
+    // corpse fails the precondition both predicates share (`0x5144e0`), so it cannot turn either.
     let turning = !mouselook && may_turn && (turn_left || turn_right);
-    // The net translate state — the reference's `flags & 0xf` (its four move bits), read off
-    // the *net* axes, not the keys: W+S streams no direction bit and doesn't translate.
     let translating = fwd_axis != 0 || side_axis != 0;
 
     MoveAxes {
diff --git a/crates/benilla-app/src/player/land.rs b/crates/benilla-app/src/player/land.rs
index 8127284b..fa5ce9d0 100644
--- a/crates/benilla-app/src/player/land.rs
+++ b/crates/benilla-app/src/player/land.rs
@@ -1,25 +1,8 @@
-//! **Land here** — free-fly's missing other half: put the avatar where the camera is.
-//!
-//! `F` detaches the camera and the avatar freezes ([`super::camera::fly_free`]); the terrain
-//! streamer follows the *camera* while detached, so you can fly anywhere and the world loads
-//! around you — but there was no way to bring the body along. This is that: fly to a spot, ask to
-//! land, and the avatar arrives there. Unreal's eject → possess, in our shape.
-//!
-//! **The teleport is the server's, not ours.** The ask goes out as the GM command `.go xyz x y z
-//! <map>` (vmangos `HandleGoXYZCommand` → `HandleGoHelper`, which keeps the exact Z when one is
-//! given and saves the recall position on the way), and the answer comes back as the ordinary
-//! `MSG_MOVE_TELEPORT_ACK` this client already handles ([`super::wire_in`]) — so the destination
-//! is one the server agrees with, zone/area/grid bookkeeping included, and nothing here invents a
-//! pose on the wire. It also means the affordance needs the account's GM rights, which is the
-//! default for this project's characters (decision 0679); a refused command shows up as the
-//! timeout warning below rather than as silence.
-//!
-//! Two details worth stating, because both are choices:
-//! - **The feet land at the camera point**, not the eye — the camera translation IS the
-//!   destination, so you arrive standing where you were floating (a ~2 yd eye rise on arrival).
-//! - **Re-attach waits for the teleport**, rather than happening at the ask. Staying detached
-//!   through the round trip means the camera is already at the destination while the body flies
-//!   to it, so the tiles are resident before the landing instead of streaming in under it.
+//! Land here: moves the avatar frozen by free-fly ([`super::camera::fly_free`]) to the camera
+//! through the GM command `.go xyz x y z <map>` (vmangos `HandleGoXYZCommand`,
+//! `TeleportCommands.cpp:854`, which keeps the given Z and saves the recall position), answered by
+//! the ordinary teleport or worldport. Control re-attaches only then, so the destination's tiles
+//! are resident before the landing.
 
 use benilla_assets::coords::bevy_to_wow;
 use bevy::prelude::*;
@@ -30,19 +13,17 @@ use benilla_world::world_map::CurrentMap;
 use super::state::Player;
 use benilla_world::view::WorldCamera;
 
-/// Ask to land the avatar at the free-flying camera. Written by the debug panel's **land here**
-/// button; the dev chord's `G` is read directly by [`land_here`].
+/// Asks to land the avatar at the free-flying camera, from the debug panel's button; the dev
+/// chord's `G` is read directly by [`land_here`].
 #[derive(Message)]
 pub(crate) struct LandHere;
 
-/// How long to wait for the server's teleport before giving up on the ask and saying so. Generous
-/// next to a local round trip: the point is to name a *refused* command (no GM rights, coordinates
-/// off the map), not to race the network.
+/// Seconds to wait for the teleport before reporting the command refused (no GM rights,
+/// coordinates off the map).
 const LAND_TIMEOUT: f32 = 5.0;
 
-/// The land-here ask, and the re-attach that closes it. Runs before [`super::control`], so the
-/// frame that applies the teleport is the frame that takes third-person control again.
-// One system phase's input set, like the controller's own params.
+/// Sends the land-here ask and re-attaches when it lands. Runs before [`super::control`], so the
+/// frame that applies the teleport takes third-person control again.
 pub(crate) fn land_here(
     keys: Res<ButtonInput<KeyCode>>,
     time: Res<Time>,
@@ -53,12 +34,11 @@ pub(crate) fn land_here(
     net: Res<NetCommands>,
     mut teleports: MessageReader<TeleportMessage>,
     mut worldports: MessageReader<WorldportMessage>,
-    // The pending ask's give-up deadline. A `Local` rather than a resource because this system is
-    // the only writer AND the only reader — nothing else in the app has an opinion about it.
+    // The pending ask's give-up deadline.
     mut pending: Local<Option<f32>>,
 ) {
-    // Drain both teleport readers every frame (own cursors — `wire_in` reads the same messages
-    // through its own): any teleport while an ask is out is our landing.
+    // Both readers drain every frame on their own cursors; a teleport while an ask is out is the
+    // landing.
     let arrived = teleports.read().count() > 0 || worldports.read().count() > 0;
     let asked = asks.read().count() > 0 || crate::run_mode::dev_chord(&keys, KeyCode::KeyG);
 
diff --git a/crates/benilla-app/src/player/move_trace.rs b/crates/benilla-app/src/player/move_trace.rs
index 8749ea1a..5903a7a7 100644
--- a/crates/benilla-app/src/player/move_trace.rs
+++ b/crates/benilla-app/src/player/move_trace.rs
@@ -1,42 +1,20 @@
-//! The mover's side of the `WOW_MOVE_TRACE` debug trace ([`benilla_assets::trace`]):
+//! The mover's side of the `WOW_MOVE_TRACE` debug trace ([`benilla_assets::trace`]), one tag per
+//! question a live run answers in numbers:
 //!
-//! - **`move`** — one line per *interesting* frame of the player mover ([`frame`]): a step-down snap,
-//!   a grounded flip, an airborne frame, or any sizeable vertical delta — so a movement-feel report
-//!   ("it pops when I step off the fence") can be read back as per-frame numbers instead of
-//!   re-guessed from watching the screen.
-//! - **`swim`** — one line per frame *over liquid* ([`swim`]): the waterline, the feet, the depth
-//!   against the two latch thresholds, and which physics regime ran. A water-feel report ("it
-//!   jitters at the surface") is a question about the depth signal frame by frame, and no other
-//!   tag carries it: `move` is emitted by the walk arm only, so the swim frames of a flapping
-//!   latch are exactly the ones it drops (decision 0644).
-//! - **`mvr`** — one line per mover-claim packet ([`mover_claim`]): who we told the server we are
-//!   driving, which is what decides whether anything under `snd` is accepted.
-//! - **`sit`** — one line per **stand-state** decision ([`posture`]): every commit, and every press
-//!   the client's own sit-down gate refused, each with the movement word that decided it. B155's
-//!   reading instrument ("you can sit while swimming"): the refusal is silent in the reference and
-//!   therefore silent in ours, so without this the *whole* mechanism is invisible from a live run —
-//!   a granted sit and a refused one look identical on screen, and the granted-underwater bug and a
-//!   gate that refuses everything are the same picture. Covers the `X` key and the `/sit` family
-//!   alike, because both land on the one commit it is emitted from.
-//! - **`gait`** — one line per **walk/run toggle** decision ([`gait`]): the `TOGGLERUN` press and
-//!   what the reference's guard chain did with it. Same argument as `sit`, half applied: the
-//!   *granted* half is observable twice over (the body's gait changes and `snd` logs the
-//!   `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 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
-//!   symptom is *other players seeing nothing* (decision 1702).
-//! - **`snd`** — one line per outbound `MSG_MOVE_*` ([`sent`]), the send-side twin of `net::motion`'s
-//!   `rly`: it makes **our own wire cadence measurable** (decision 0617), which is the only way to
-//!   compare it against the reference's — the 1.12.1 sniff's client stream is a list of exactly these
-//!   fields, so `grep snd` on a run of mouse-turning and strafing is directly diffable against it.
+//! - `move`: an interesting frame of the player mover ([`frame`]): a step-down snap, a grounded
+//!   flip, an airborne frame or a sizeable vertical delta. The walk arm alone emits it.
+//! - `swim`: a frame over liquid ([`swim`]): the depth against the two latch thresholds.
+//! - `mvr`: a mover-claim packet ([`mover_claim`]), which decides whether the server accepts `snd`.
+//! - `sit`: a stand-state decision ([`posture`]), committed or refused, from `X` or `/sit`.
+//! - `gait`: a walk/run toggle decision ([`gait`]), committed or refused.
+//! - `knb`: a knockback ([`knockback`]), flown or refused.
+//! - `snd`: an outbound `MSG_MOVE_*` ([`sent`]), diffable against a 1.12.1 capture's client
+//!   stream; `net::motion`'s `rly` is the receive side.
+//! - `sett`: how the settle hold ended ([`settle`]) and the time it skipped ([`skipped_time`]).
+//! - `rid`: a frame of a self-spline ride ([`ride`]).
 //!
-//! The anim driver writes its own `anim` lines into the same file, on the same clock, and the
-//! transport carry writes `ride` from [`super::ride`] — beside the mechanism it measures, because
-//! reading it needs the deck's transform and the attach walk, neither of which belongs here.
+//! The anim driver writes `anim` lines into the same file on the same clock, and
+//! [`super::ride`] writes the transport carry's `ride`.
 
 use std::sync::atomic::{AtomicBool, Ordering};
 
@@ -46,38 +24,26 @@ use benilla_assets::trace;
 pub(super) struct Frame {
     /// Feet height entering the step (yd).
     pub y_in: f32,
-    /// Feet height leaving the step (yd) — after the slide *and* the step-down snap.
+    /// Feet height leaving the step (yd), after the slide and the step-down snap.
     pub y_out: f32,
-    /// 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 (`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.
+    /// Horizontal distance this frame (yd). With the drop it is the descent slope, which the
+    /// reference bounds at [`super::STEP_SLOPE_RATIO`] per unit of travel (`0x636dda`).
     pub dx: f32,
     pub grounded: bool,
     pub on_walkable: bool,
-    /// Whether the keys asked for any horizontal motion this frame. A frame that travelled with
-    /// **no** input is a body being moved by the resolve alone — a push-out, a slide off a
-    /// contact — and that is the whole shape of "I sat down and ended up beside the chair"
-    /// (B359), so it is interesting on its own even while grounded and level.
+    /// The keys asked for horizontal motion; travel without it is the resolve moving the body.
     pub moving: bool,
     pub vel_y: f32,
-    /// The step-down snap, when the walk-mode block ran: `(probe reach, what the probe found)`;
-    /// the inner pair is `(hit distance, hit normal.y)` — a steep hit is recorded too, so a lip
-    /// contact that killed the snap shows up in the trace.
+    /// The step-down snap when it ran: `(probe reach, Some((hit distance, hit normal.y)))`, a steep
+    /// hit included.
     pub snap: Option<(f32, Option<(f32, f32)>)>,
-    /// The atomic step-up's committed height gain this frame (yd), when the maneuver ran
-    /// (decision 0209).
+    /// The atomic step-up's committed height gain this frame (yd), when the maneuver ran.
     pub climb: Option<f32>,
-    /// The root's anchor ran this frame (decision 0880) — no gravity, no slide, no snap. Without it
-    /// on the line, a rooted hang and a genuinely stuck mover are the same column of `dy=+0.000`.
+    /// The root's anchor ran (no gravity, slide or snap), telling a rooted hang from a stuck mover.
     pub anchored: bool,
 }
 
-/// One `snd` line per outbound movement packet: the opcode we chose, the live move-flags it carries,
-/// and the facing. Read against the sniff's client stream (opcode + flags + orientation per line) this
-/// answers "does our wire look like the reference's?" without anyone squinting at a second window.
+/// One `snd` line per outbound movement packet: the opcode, the move flags, facing and position.
 pub(super) fn sent(kind: crate::net::MoveKind, flags: u32, facing: f32, pos: [f32; 3]) {
     if !trace::enabled() {
         return;
@@ -91,20 +57,10 @@ pub(super) fn sent(kind: crate::net::MoveKind, flags: u32, facing: f32, pos: [f3
     );
 }
 
-/// One `sit` line per **stand-state decision** — the commits and the refusals, with the movement
-/// word that decided each.
-///
-/// `what` is `commit` or `REFUSED`; `state` is the `UnitStandStateType` asked for (0 STAND · 1 SIT ·
-/// 2 SIT_CHAIR · 3 SLEEP · 8 KNEEL), `from` the state it was asked from, and `flags` the live
-/// `CMovement` word the client's gate reads (`[[this+0x118]+0x40]`) — with its two decisive
-/// sub-readings spelled out rather than left to be masked by eye, because "is `0x220000f` swimming?"
-/// is exactly the question a trace exists to stop anyone answering from memory.
-///
-/// Emitted for **both** outcomes on purpose. The reference refuses a sit-down silently — no error
-/// text, no sound — so a refusal has no observable of its own; and a *granted* sit is equally
-/// unreadable, since the pose that follows is identical whether the gate ran or was never there.
-/// One line per decision is what makes B155's fix falsifiable in a live run instead of assertable
-/// from a screenshot of a seated character.
+/// One `sit` line per stand-state decision. `what` is `commit` or `REFUSED`, `state` the
+/// `UnitStandStateType` asked for (0 STAND, 1 SIT, 2 SIT_CHAIR, 3 SLEEP, 8 KNEEL), `from` the
+/// current one, and `flags` the `CMovement` word the reference's gate reads
+/// (`[[this+0x118]+0x40]`), its swim and move bits spelled out. The reference refuses silently.
 pub(super) fn posture(what: &str, state: u8, from: u8, flags: u32) {
     if !trace::enabled() {
         return;
@@ -120,12 +76,8 @@ pub(super) fn posture(what: &str, state: u8, from: u8, flags: u32) {
     );
 }
 
-/// One `gait` line per **walk/run toggle** decision, granted or refused (decision 1752).
-///
-/// `what` is `commit` or `REFUSED`; `to` is the gait the press asked for, and the three flags are
-/// the reference's own guard chain at `0x513d8e`–`0x513dcd` spelled out one by one — because
-/// "why did nothing happen?" is exactly the question this tag exists to stop anyone answering from
-/// memory, and three silent gates share the same silence.
+/// One `gait` line per walk/run toggle: `commit` or `REFUSED`, the gait asked for, and the three
+/// silent gates of the reference's chain (`0x513d8e`–`0x513dcd`) one by one.
 pub(super) fn gait(what: &str, to: bool, dead: bool, rooted: bool, on_spline: bool) {
     if !trace::enabled() {
         return;
@@ -142,19 +94,10 @@ pub(super) fn gait(what: &str, to: bool, dead: bool, rooted: bool, on_spline: bo
     );
 }
 
-/// One `knb` line per **knockback**, whether we flew it or refused it (decision 1702).
-///
-/// The tag exists because a knockback is the one mover edge with **no observable of its own on
-/// either side of the failure**. Its ack is not a `MSG_MOVE_*`, so `snd` never shows it; its refusal
-/// is silent by design (the reference discards the record under a root, and vmangos logs
-/// `OnFailedToAckChange` server-side where we cannot see it); and if the ack's four floats are ever
-/// wrong the server drops it as `OnWrongAckData` and simply never relays the knockback — a bug whose
-/// entire symptom is *other people not seeing something*, which no local capture can show.
-///
-/// So the line carries the quad as it arrived, next to the verdict. `up` is the derived +Z take-off
-/// speed, printed beside the wire's own down-positive `zspeed` precisely because the sign flip
-/// between them is where a knockback that drives you into the ground would come from — the two must
-/// always read as negatives of each other.
+/// One `knb` line per knockback, flown or refused, with the launch quad as it arrived. Nothing else
+/// shows one: the ack is not a `MSG_MOVE_*`, the reference discards the record under a root, and
+/// vmangos drops a wrong ack (`OnWrongAckData`) without relaying the knockback. `up` is the +Z
+/// takeoff speed beside the wire's down-positive `zspeed`; the two always read as negatives.
 pub(super) fn knockback(flown: bool, launch: benilla_protocol::JumpInfo) {
     if !trace::enabled() {
         return;
@@ -173,12 +116,8 @@ pub(super) fn knockback(flown: bool, launch: benilla_protocol::JumpInfo) {
     );
 }
 
-/// One `mvr` line per **mover-claim** packet — `CMSG_SET_ACTIVE_MOVER` and
-/// `CMSG_MOVE_NOT_ACTIVE_MOVER`. Neither is a `MSG_MOVE_*`, so neither appears under `snd`, and yet
-/// the pair decides whether every packet that *does* is accepted at all: vmangos matches each
-/// against the session's confirmed mover and answers a mismatch with a server-side error log the
-/// client never sees. A possession that goes wrong is unreadable from `snd` alone — the stream looks
-/// perfect and lands nowhere (decision 1281; the gap cost a live probe round to notice).
+/// One `mvr` line per `CMSG_SET_ACTIVE_MOVER` or `CMSG_MOVE_NOT_ACTIVE_MOVER`. vmangos checks every
+/// movement packet against the confirmed mover and logs a mismatch only server-side.
 pub(super) fn mover_claim(what: &str, guid: u64) {
     if !trace::enabled() {
         return;
@@ -186,16 +125,9 @@ pub(super) fn mover_claim(what: &str, guid: u64) {
     trace::line("mvr", &format!("{what} guid={guid:#x}"));
 }
 
-/// One `swim` line per frame the avatar is over liquid: the waterline, the feet, the submersion
-/// depth and the two latch thresholds it is being compared against, plus the regime that ran. The
-/// `<` / `>` markers flag the frames where the depth crossed a threshold, so a latch that is
-/// flapping reads as a column of them rather than something to be inferred from a Z column.
-///
-/// `h` is the avatar's own collision height, and the thresholds are printed **derived from it**
-/// rather than from a constant (decision 0645) — a trace that quoted a human's 1.52 while a gnome
-/// latched at 0.86 would read as a bug in the latch instead of the height, which is precisely the
-/// misdirection that let the constant survive this long. It is echoed on the line so a capture says
-/// which body it was taken on.
+/// One `swim` line per frame over liquid: waterline, feet, depth, the two latch thresholds and the
+/// regime, `<` or `>` marking a depth past a threshold. The thresholds derive from `h`, the
+/// avatar's own collision height, which the line echoes.
 pub(super) fn swim(feet_y: f32, surface_y: f32, swimming: bool, h: f32) {
     if !trace::enabled() {
         return;
@@ -221,10 +153,7 @@ pub(super) fn swim(feet_y: f32, surface_y: f32, swimming: bool, h: f32) {
     );
 }
 
-/// One `sett` line per `CMSG_MOVE_TIME_SKIPPED` we send (decision 1935) — how many milliseconds
-/// of movement simulation the hold ran through without integrating, and for which mover. It rides
-/// the settle's own tag because it reports the settle's own cost: a `skipped` far larger than the
-/// `sett` line beside it means the hold outlived the stream it was waiting for.
+/// One `sett` line per `CMSG_MOVE_TIME_SKIPPED` we send: the ms the settle hold skipped, and whose.
 pub(super) fn skipped_time(guid: u64, lag_ms: u32) {
     if !trace::enabled() {
         return;
@@ -235,17 +164,10 @@ pub(super) fn skipped_time(guid: u64, lag_ms: u32) {
     );
 }
 
-/// How the post-teleport settle hold **ended** — the whole diagnosis of a fall-through report.
-///
-/// `resident` means the destination's world arrived (scene spawned + collider queue quiet —
-/// decision 0737's release) and the hold released onto it; `!resident` is the
-/// [`super::SETTLE_TIMEOUT`] backstop firing, which since decision 1303 (B263) means the stream
-/// made **no progress at all** for the whole budget — a genuinely dead stream, never a slow one —
-/// and gravity comes on with the world never having become resident. `waited` is measured from
-/// the snap either way. The distinction is invisible from inside the game (both look like "the
-/// loading screen went away") and it is the difference between a world that arrived and one that
-/// died, so the timeout end is also a `warn!` on the ordinary log — a reporter's paste can then
-/// name it without owning a trace.
+/// How the post-teleport settle hold ended: `resident`, the destination's world arrived (scene
+/// spawned, collider queue quiet); otherwise the [`super::SETTLE_TIMEOUT`] backstop, a stream with
+/// no progress for the whole budget. `waited` runs from the snap. The two look alike in game, so a
+/// timeout also warns on the ordinary log.
 pub(super) fn settle(resident: bool, waited: f32, pos: bevy::prelude::Vec3) {
     if !resident {
         bevy::log::warn!(
@@ -276,25 +198,10 @@ pub(super) fn settle(resident: bool, waited: f32, pos: bevy::prelude::Vec3) {
     );
 }
 
-/// One `rid` line per frame of a **self-spline ride** — the Charge/knockback/fear/taxi instrument,
-/// and the A/B that measured decision 1927.
-///
-/// It exists because the ride is the one mover in the client the `move` trace cannot see: the
-/// controller — and with it the mover's own per-frame line — is parked behind `control`'s ride
-/// guard for the whole ride, so a charge across a hillside left no record at all.
-///
-/// The three numbers, and why all three:
-/// - **`wire`** — the Z `sample_splines` put us at, i.e. the server's chord.
-/// - **`ground`** — the walkable surface under that XZ. `miss` is not a failure: nothing in reach
-///   is a genuinely airborne pose or ground that has not streamed in, and the ride keeps its own Z
-///   there, the same answer the creature clamp gives.
-/// - **`z`** — where the ride actually left us, and `gap` is `z − ground`: **the number that says
-///   whether the ride is riding the world or the wire.**
-///
-/// `chord` is `wire − ground` — the error the wire carried, which stays visible after the fix so
-/// the instrument still measures the defect it closed rather than reporting a flat zero. A charge
-/// down a gentle Elwynn slope reads `chord` rising to ~0.5 yd at mid-path while `gap` holds at 0;
-/// **before 1927 the two were the same number**, because `z` was `wire`.
+/// One `rid` line per frame of a self-spline ride (Charge, knockback, fear, taxi), during which the
+/// controller and its `move` line are parked. `wire` is the Z the spline put us at, `ground` the
+/// walkable surface under it (`miss`: nothing in reach, and the ride keeps its own Z), `z` where
+/// the ride left us; `gap` is `z − ground` and `chord` is `wire − ground`.
 pub(super) fn ride(
     spline_id: u32,
     grounded: bool,
@@ -339,8 +246,7 @@ pub(super) fn frame(f: Frame) {
         .and_then(|(_, hit)| hit)
         .map_or(0.0, |(dist, _)| dist);
     let flipped = f.grounded != PREV_GROUNDED.swap(f.grounded, Ordering::Relaxed);
-    // Input-less travel: the resolve moved a body nobody was steering. A millimetre a frame is
-    // the signature (1458's chair extrusion ran at 1–2 mm), so the floor is well under it.
+    // Travel with no input, the resolve moving the body; a chair push-out runs 1–2 mm a frame.
     let creep = !f.moving && f.dx > 1.0e-4;
     if !(flipped
         || !f.grounded
@@ -363,8 +269,7 @@ pub(super) fn frame(f: Frame) {
             }
         ),
     };
-    // The descent slope, printed only while actually going down and moving: `>cone` marks a frame
-    // steeper than the foot cone allows, which is the signature of a dive rather than a step-down.
+    // While descending and moving, `>cone` marks a frame steeper than the foot cone allows.
     let slope = if dy < -1.0e-4 && f.dx > 1.0e-4 {
         let s = -dy / f.dx;
         format!(
@@ -379,28 +284,14 @@ pub(super) fn frame(f: Frame) {
     } else {
         format!(" dx={:.3}", f.dx)
     };
-    // The dive's real signature, and it is not steepness — it is the *absence* of descent. A body
-    // that leaves the surface travels forward with `dy≈0` while the probe reports a steep face right
-    // beneath it; everything after that is a ballistic arc, and by the time the fall looks steep the
-    // frame that caused it is long gone. `>cone` was the first guess and the director's capture
-    // showed it never fires: the arc starts at slope 0.05 and only reaches 0.83. This is the marker
-    // that would have named it on the first read.
+    // A body leaving the surface travels forward with `dy ≈ 0` over a steep face below it; the
+    // arc that follows starts shallow (slope 0.05), so `>cone` misses the takeoff.
     let left = f
         .snap
         .and_then(|(_, hit)| hit)
-        // **A face the body is touching is not a face it left.** The steep hit must be at a
-        // *distance* — `d = 0.000` is the body resting flush against a bank, sliding along it, which
-        // is the ordinary rub the mover is built to do and which reads identically on every other
-        // term here (`dy = 0`, forward travel, a steep normal below). Eighteen of those in one
-        // hillside capture buried the one real signature this marker exists to name.
+        // The steep hit must be at a distance: `d = 0` is the body sliding flush along a bank.
         .is_some_and(|(dist, ny)| ny < super::GROUND_COS && dist > 1.0e-3)
-        // **Flat is the signature — not "anything that isn't descending".** A dive frame is one that
-        // travels forward and goes *nowhere* vertically while a steep surface sits below it. Written
-        // as `dy > -eps` this also swallows every frame that is climbing, where not descending is
-        // exactly right: first the atomic step-ups, then — once those were excluded — the ordinary
-        // walk up a hill, which rises through the slope ride and carries no `climb` at all. Three
-        // false-positive classes on three consecutive captures, the second of which buried nine real
-        // takeoffs under fifty-five phantoms. A window around zero admits none of them.
+        // Flat, not merely not descending: a window around zero keeps out step-ups and hill climbs.
         && dy.abs() < 1.0e-3
         && f.dx > 1.0e-4;
     let left = if left { " LEFT-SURFACE" } else { "" };
diff --git a/crates/benilla-app/src/player/movement_net.rs b/crates/benilla-app/src/player/movement_net.rs
index c0ec0fc1..d71f304b 100644
--- a/crates/benilla-app/src/player/movement_net.rs
+++ b/crates/benilla-app/src/player/movement_net.rs
@@ -1,30 +1,7 @@
-//! Outbound self-movement → the wire — the mirror of [`crate::net::motion`] (which integrates *remote*
-//! movers). [`stream_self_movement`] diffs this frame's CMovement move-flags against last frame's and
-//! emits a `MSG_MOVE_*` per movement-*axis* transition (start/stop forward-back, strafe, turn), the
-//! jump/fall lifecycle (JUMP launch, FALL_LAND — a jumpless fall opens with nothing, decision 1464),
-//! a periodic heartbeat while moving,
-//! and a SET_FACING every frame the facing changes off the turn axis — each carrying the live
-//! `MovementInfo` (decisions 0052 + 0053 + 0617). Split out of the controller: the wire stream is its
-//! own concern.
-//!
-//! **Invariant — the wire mirrors the avatar's *actual* local motion** (decision 0056). vmangos relays
-//! what we send verbatim and observers extrapolate it from the moveFlags, so any divergence strands them
-//! on stale state: a flag we set but never clear is a *phantom* walk/spin, and an out-of-range value is
-//! silently dropped before relay (vmangos rejects `|orientation| > 4π` in `VerifyMovementInfo`,
-//! regardless of anticheat). Three rules keep us honest, all enforced here at the wire boundary:
-//! - **Every outbound `orientation` is normalized into `[0, 2π)`** — `face_yaw`/`cam.yaw` are unbounded
-//!   accumulators, but the real client always sends a normalized facing and the server's validity gate
-//!   demands it.
-//! - **When the controller stops driving locomotion, the mover is *parked*** — [`park_mover`] flushes a
-//!   Stop and clears our flags on entering free-fly; the held frames of a post-teleport settle stream
-//!   zeroed flags (so [`stream_self_movement`]'s own diff emits the Stop) — so observers never
-//!   extrapolate motion that isn't happening locally.
-//! - **The server's copy of our *position* may never go stale** — the reconcile at the bottom of
-//!   [`stream_self_movement`] (decision 0907). A resting body whose resolver settles it a fraction
-//!   of a millimetre after the packet that reported the rest used to keep that to itself, and
-//!   vmangos — which compares positions with exact float equality — read the next packet's
-//!   accumulated delta as movement and cancelled the cast in flight. Drift at rest is news; it goes
-//!   out the frame it happens.
+//! Our own movement onto the wire: a `MSG_MOVE_*` per flag transition, the jump and the landing,
+//! a heartbeat while moving and a `SET_FACING` each frame the facing changes. The wire must mirror
+//! the avatar's actual motion: vmangos relays each packet verbatim and observers extrapolate from
+//! its flags, so a flag left set is a phantom walk on every other screen.
 
 use benilla_assets::coords::bevy_to_wow;
 use benilla_protocol::{JumpInfo, TransportPose};
@@ -35,20 +12,12 @@ use crate::net::{ClientCommand, MoveKind};
 
 use super::Player;
 
-/// 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.
+/// The `MSG_MOVE_HEARTBEAT` period (s) while moving: the reference arms its send deadline
+/// `[mgr+0x130]` to now + 500 ms (`0x615b80`).
 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
-/// set, so observers replay our jump as a ballistic arc (decision 0053) — **`FALLING_FAR`**
-/// (`MOVEFLAG_FALLINGFAR` 0x4000, latched mid-arc past the 1/9-yd descent): the real client's live
-/// flags carry it and vmangos reads it (anticheat, PointMovementGenerator), so ours does too; it
-/// changes no opcode (the axis differ below keys on direction bits only) and just rides whatever
-/// packets the arc sends — **and `SWIMMING`** (0x200000): the swim-pitch tail is now serialized
-/// symmetrically ([`MovementInfo`](benilla_protocol) — the decision-0052 swim follow-up), so setting
-/// the flag no longer desyncs the server's parse; the controller supplies the live pitch alongside it.
+/// The flag bits we send, each with its tail where it has one (`FALLING` the jump quad, `SWIMMING`
+/// the pitch, `ON_TRANSPORT` the deck pose). `FALLING_FAR` changes no opcode; it rides the arc's
+/// packets as the reference's live flags do.
 const OUTBOUND_FLAG_MASK: u32 = move_flags::FORWARD
     | move_flags::BACKWARD
     | move_flags::STRAFE_LEFT
@@ -59,94 +28,61 @@ const OUTBOUND_FLAG_MASK: u32 = move_flags::FORWARD
     | move_flags::FALLING
     | move_flags::FALLING_FAR
     | move_flags::SWIMMING
-    // …**and `LEVITATING`** (0x400, GM flight — decision 0726). Echoing it is not cosmetic: the
-    // reference's packet builder reads the same `[cmov+0x40]` the server's flags merged into, so a
-    // real client sends it straight back, and vmangos refreshes its `m_movementInfo` from whatever
-    // we report. Drop it from our stream and the server's copy loses the bit — then the next
-    // server-authored move (a `.go forward`, a forced speed change) echoes a LEVITATING-less word
-    // back at us, our merge clears the mode, and we fall out of the sky mid-flight.
+    // The granted modes echo back: the reference builds its packets from the flags word the
+    // server's merges land in. vmangos stores what we report, so a dropped `LEVITATING` returns
+    // cleared on the next server-authored move and ends GM flight.
     | move_flags::LEVITATING
-    // …**and the rest of the granted movement-mode family** (decision 0866) — root, water-walk,
-    // safe-fall, hover: the same reasoning one step stronger. These four are the *ack'd* modes, so
-    // the server holds an explicit record of granting each one and notices our stream disagreeing.
-    // `MOVEFLAG_ROOT` especially: vmangos re-adds it to anything it writes for a rooted mover
-    // (`MovementHandler.cpp:1064`), and its absence from an apply-ack is a kick.
+    // vmangos re-adds `ROOT` to a rooted mover's report (`MovementHandler.cpp:1064-1065`) and kicks
+    // a root-apply ack without it (`MovementHandler.cpp:715-722`).
     | move_flags::ROOT
     | move_flags::WATER_WALKING
     | move_flags::SAFE_FALL
     | move_flags::HOVER
     | move_flags::ON_TRANSPORT;
 
-/// The bits that mean **the body is genuinely in motion**, and so that its position is expected to
-/// change every frame: the direction bits, the airborne arc, swimming, and riding a transport. The
-/// position reconcile at the bottom of [`stream_self_movement`] fires only when NONE of them is set
-/// — at rest, a position change is news; in motion it is the whole point of the transition +
-/// heartbeat stream (0052/0053), which already carries it. Turning in place is deliberately absent:
-/// a keyboard turn moves nothing, so a drift under it is still news.
+/// The bits under which the position changes every frame and the move stream carries it; the
+/// position reconcile runs only with none set. Turning is absent: a turn in place moves nothing.
 const IN_MOTION: u32 = move_flags::ANY_MOVE
     | move_flags::FALLING
     | move_flags::FALLING_FAR
     | move_flags::SWIMMING
     | move_flags::ON_TRANSPORT;
 
-/// What this frame's **skipped-time report** ([`stream_skipped_time`]) needs: how long the frame
-/// was, whether the mover integrated it, and which mover to name.
+/// This frame's input to the `CMSG_MOVE_TIME_SKIPPED` report ([`stream_skipped_time`]).
 pub(super) struct SkipClock {
-    /// This frame's length in seconds — the budget the mover either integrated or did not.
+    /// The frame's length in seconds.
     pub(super) dt: f32,
-    /// **The mover held instead of stepping this frame** ([`super::Player::settling`]): the world
-    /// under us has not streamed in, so nothing integrated `dt`.
+    /// The mover held instead of stepping ([`super::Player::settling`]): nothing integrated `dt`.
     pub(super) held: bool,
-    /// The mover's own guid — a possessed unit's while we hold its reins, else our own body's.
-    /// `None` before the server has named one, which is also before anything could be skipped.
+    /// The active mover, a possessed unit or our own body; `None` until the server names one.
     pub(super) mover: Option<u64>,
 }
 
-/// This frame's **arc edges** — the airborne lifecycle as the send law reads it. One struct rather
-/// than four adjacent bools in the argument list, where a miscount is silent and the symptom is a
-/// wrong opcode on the wire.
+/// This frame's airborne edges, as the send rules read them.
 pub(super) struct ArcEdges {
-    /// A take-off launched this frame — the arc opened.
+    /// A take-off launched this frame.
     pub(super) jumped: bool,
-    /// …and it came from the **wire**, not the key: a knockback, or the jump a `SetHover(true)`
-    /// grant owes ([`super::Player::hover_launch`]). Suppresses `MSG_MOVE_JUMP`, which is the
-    /// *keyboard's* packet and nothing else's: `0x615ed1`, in the move-command drain's jump arm, is
-    /// its one live emission site image-wide, and neither wire door passes through it — the hover
-    /// handler `0x61a620` sends nothing at all, and the knockback's own arm of that same drain
-    /// pushes `0xf0`, its ack. (Decision 1702; this corrects 1620, which streamed a JUMP for the
-    /// hover launch.)
+    /// The take-off came from the server, a knockback or the jump a hover grant owes
+    /// ([`super::Player::hover_launch`]), so it sends no `MSG_MOVE_JUMP`: that packet's one
+    /// emission site is the move-command drain's jump arm (`0x615ed1`); the hover handler
+    /// `0x61a620` sends nothing and the knockback arm sends its ack (`0xf0`).
     pub(super) wire_launch: bool,
-    /// The standstill air nudge fired ([`super::mover::step`]) — the one mid-air press that really
-    /// moves us, and so the one that breaks the airborne send silence (decision 0627).
+    /// The standstill air nudge fired ([`super::mover::step`]): the one mid-air press that moves
+    /// us, so the one that breaks the airborne silence.
     pub(super) air_nudged: bool,
-    /// The arc ended this frame → `MSG_MOVE_FALL_LAND`.
+    /// The arc ended this frame: `MSG_MOVE_FALL_LAND`.
     pub(super) landed: bool,
-    /// ms since take-off — the caller's snapshot, because the landing frame's arc bookkeeping has
-    /// already cleared `airborne_since` and the FALL_LAND must still report the accumulated time.
+    /// Ms since take-off, the caller's snapshot: the landing frame has already cleared
+    /// `airborne_since`, and vmangos deals fall damage only from a landing `fallTime` of 1229 ms
+    /// (`Player.cpp:20954`).
     pub(super) fall_time: u32,
 }
 
-/// 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`:
-/// 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
-/// SET_FACING outnumbers every other client-sent movement opcode combined, moving or standing).
-/// vmangos relays it all to nearby players, who extrapolate from the flags — how they see us walk/turn/
-/// strafe. (We claimed the mover with CMSG_SET_ACTIVE_MOVER at login.) **Airborne is its own send law**
-/// (VERIFIED, vanilla-sniffs `dwarf_rogue_dun_morogh`): the fwd/back/strafe **transitions** go silent
-/// while FALLING — the live flag state rides the packets that do go out — so a jump is JUMP →
-/// \[heartbeats/turn/facing\] → FALL_LAND, with the landing flags telling observers what the keys say
-/// *now*. The one press that breaks the transition silence is the standstill air nudge (`air_nudged`,
-/// decision 0627): the case the reference's own deferral excludes, and the only mid-air input that
-/// actually moves us. **The periodic heartbeat is NOT part of that silence** and a jumpless fall opens
-/// with no packet at all — both corrected against the bytes and the same capture by decision 1464,
-/// which retired this module's two remaining 0053-era inventions. Sends are fire-and-forget; a down thread no-ops. Mutates `player`'s last-sent flags/facing/
-/// heartbeat so next frame can diff against them.
-// Eight, down from twelve: the arc edges are one struct now (`ArcEdges`). The rest are distinct
-// types the compiler can tell apart, so the remaining count is noise rather than a miscount risk.
+/// Streams this frame's movement as the reference does: a `MSG_MOVE_*` per axis transition (its
+/// broadcaster `0x61a820` picks the opcode from the flag delta, `0x619f00`), a `SET_FACING` each
+/// frame the facing changes off the turn axis, and a heartbeat every 500 ms while moving. Airborne,
+/// the forward, back and strafe transitions go silent and their live bits ride the packets that do
+/// go out. Sends are fire-and-forget; updates `player`'s last-sent flags, facing and heartbeat.
 pub(super) fn stream_self_movement(
     sender: &Sender<ClientCommand>,
     player: &mut Player,
@@ -168,42 +104,30 @@ pub(super) fn stream_self_movement(
     } = arc;
     stream_skipped_time(sender, player, skip);
     let wow_pos = bevy_to_wow(player.pos);
-    // Normalize the facing into [0, 2π) before it goes on the wire. `face_yaw` is an unbounded
-    // accumulator (mouse-look and A/D turning keep growing it), but the real client always sends a
-    // normalized orientation, and vmangos's `VerifyMovementInfo` → `IsValidMapCoord` rejects any
-    // movement packet with `|o| > 4π`. Past that bound every packet — including the Stop/StopTurn that
-    // ends a run or turn — is silently dropped, stranding observers on the last-relayed flags (a
-    // phantom spin or run-off that only clears once we turn back in range and emit a fresh transition).
+    // `face_yaw` is unbounded; the reference sends [0, 2π), and vmangos drops a packet with
+    // `|o| > 4π` unrelayed (`VerifyMovementInfo`, `GridDefines.h:203`), a stop included.
     let facing = player.face_yaw.rem_euclid(std::f32::consts::TAU);
     let wire_flags = move_flags_now & OUTBOUND_FLAG_MASK;
-    // The ballistic launch tail, sent on every airborne packet (decision 0053): `zspeed` is the
-    // constant take-off vertical speed, the horizontal is the frozen `horiz_vel` mapped to world XY,
-    // and `xyspeed` its magnitude. Present iff JUMPING is in `wire_flags` — the serializer gates the
-    // tail on the same bit, so the two never disagree. `fall_time` (ms since take-off) is the
-    // caller's snapshot: on the landing frame the arc bookkeeping has already cleared
-    // `airborne_since`, but the FALL_LAND must still report the accumulated fall time — vmangos
-    // `Player::HandleFall` deals fall damage only when the land packet's fallTime ≥ 1229 ms.
+    // The jump tail, on every airborne packet: the take-off vertical speed and the horizontal
+    // velocity frozen at take-off, in world XY.
     let wire_jump = (wire_flags & move_flags::FALLING != 0).then(|| {
         let v = bevy_to_wow(player.horiz_vel); // WoW velocity [vx, vy, 0] (the transform is linear)
         let xy = v[0].hypot(v[1]);
         let (cos_angle, sin_angle) = if xy > 1.0e-4 {
             (v[0] / xy, v[1] / xy)
         } else {
-            (facing.cos(), facing.sin()) // a standing jump: direction is moot (xy 0); use the facing
+            (facing.cos(), facing.sin()) // a standing jump has no direction: use the facing
         };
         JumpInfo {
-            // The wire zspeed is DOWN-positive (the real client sends -7.955547 for a rising jump —
-            // VERIFIED, vanilla-sniffs), so negate our +up `jump_zspeed`. A real-client observer reads
-            // the up-speed as `-zspeed`; sending +up here would make them see us sink (decision 0054).
+            // Down-positive on the wire: the 1.12 client sends -7.955547 (`0xc0fe93d8`) rising.
             zspeed: -player.jump_zspeed,
             cos_angle,
             sin_angle,
             xy_speed: xy,
         }
     });
-    // Forced speed changes owe their ack inside the server's ~4 s window: echo kind/guid/counter/
-    // speed with EXACTLY this frame's wire payload — the same flags/pose/tails a Move packet would
-    // carry, so the server's relocation and anticheat position tests see our honest live state.
+    // A forced speed change is acked within the server's 4 s window with this frame's live
+    // payload, which vmangos relocates us to and runs its anticheat position tests on.
     for ack in speed_acks {
         let _ = sender.send(ClientCommand::ForceSpeedAck {
             kind: ack.kind,
@@ -218,24 +142,15 @@ pub(super) fn stream_self_movement(
             jump: wire_jump,
             transport,
         });
-        // The ack's `MovementInfo` relocates the mover server-side exactly like a Move packet, so
-        // it is also a position report — the reconcile below must not re-send what it just told.
+        // The ack relocates us server-side, so it is a position report too.
         player.last_pos = wow_pos;
     }
 
-    // **The knockback ack** (decision 1702) — owed only if the mover actually took off this frame,
-    // and carrying the pose it took off from. `apply → send, inside one call` is the reference's own
-    // order (`0x61624d call 0x6179c0` → `0x616261 push 0xf0`), which is why this sits here and not
-    // back at the opcode: everything on the wire must describe the arc we are already flying.
-    //
-    // `launch` goes out verbatim rather than re-derived from `wire_jump` below, though the two agree
-    // exactly for every real knockback (the mover seeded its velocity from this quad, and the round
-    // trip through the coordinate basis is sign flips and a hypot). The reference copies its own
-    // live fields as plain dwords (`+0xa0`→`+0x3c`, `+0x68`→`+0x40`, `+0x6c`→`+0x44`,
-    // `+0x84`→`+0x48`) so its echo is bit-identical to what arrived, and vmangos's `0.01` tolerance
-    // is never exercised. Sending the quad itself is how we keep that true in the one case where a
-    // re-derivation could not: `xy_speed == 0`, where a direction has no length to recover and the
-    // tail below substitutes the facing.
+    // The knockback ack goes out on the take-off frame with the take-off pose, as the reference
+    // applies the launch and then sends (`0x61624d` call `0x6179c0`, then `0x616261` push `0xf0`).
+    // `launch` is echoed bit for bit, as the reference copies its live fields: vmangos matches the
+    // four floats within 0.01 (`Unit.cpp:7097-7100`), and a re-derived quad has no direction at
+    // `xy_speed == 0`.
     if let Some(k) = knock_ack {
         let _ = sender.send(ClientCommand::KnockBackAck {
             guid: k.guid,
@@ -246,7 +161,7 @@ pub(super) fn stream_self_movement(
             orientation: facing,
             transport,
         });
-        // Like a speed ack, this relocates us server-side — so it is a position report too.
+        // A position report too, like a speed ack.
         player.last_pos = wow_pos;
     }
     let prev = player.move_flags;
@@ -272,108 +187,54 @@ pub(super) fn stream_self_movement(
                 flags: wire_flags,
                 pos: wow_pos,
                 orientation: facing,
-                // The serializer writes the pitch iff SWIMMING is in `wire_flags`, so a non-swimming
-                // packet ignores this; while swimming it's the live swim heading pitch.
+                // Written only while SWIMMING is set.
                 pitch: swim_pitch,
                 fall_time,
                 jump: wire_jump,
-                // Written iff ON_TRANSPORT is in `wire_flags` — the rider's boat-local pose.
+                // Written only with ON_TRANSPORT: the rider's deck-local pose.
                 transport,
             });
             sent = true;
-            // What the server now believes, for the reconcile below — every packet in this family
-            // carries `wow_pos`, and vmangos relocates the mover to it (`HandleMoverRelocation`).
+            // vmangos relocates the mover to every one of these (`HandleMoverRelocation`).
             player.last_pos = wow_pos;
         }};
     }
     const FB: u32 = move_flags::FORWARD | move_flags::BACKWARD;
     const STRAFE: u32 = move_flags::STRAFE_LEFT | move_flags::STRAFE_RIGHT;
     const TURN: u32 = move_flags::TURN_LEFT | move_flags::TURN_RIGHT;
-    // Airborne, the fwd/back/strafe axes go SILENT on the wire while the flag state stays live —
-    // VERIFIED (vanilla-sniffs `dwarf_rogue_dun_morogh`): a strafe pressed mid-air emits no
-    // START_STRAFE yet the landing FALL_LAND carries `(Forward, StrafeLeft)`; an S→W swap mid-air
-    // emits no transition yet lands as `(Forward)`. The keys don't move an airborne avatar (the
-    // arc's momentum froze at takeoff), so their transitions aren't motion changes — the live bits
-    // simply ride every packet that does go out. The TURN axis is the exception (below): turning
-    // genuinely works mid-air, and the sniff shows START_TURN_RIGHT/STOP_TURN with `Falling` set.
-    //
-    // **The standstill air nudge is the other exception** (decision 0627), and it is the *same* rule,
-    // 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**" — 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
-    // direction pressed — the one input that genuinely re-seeds the arc's horizontal velocity), and
-    // it must go out: the packet carries the fresh `JumpInfo` tail, which is the only way an observer
-    // — integrating our arc from a JUMP that said `xy_speed = 0` — can ever learn we started moving
-    // before the FALL_LAND lands.
+    // Airborne, the forward, back and strafe transitions are silent: while FALLING the reference's
+    // `StartMove` (`0x7c6ae0`) defers a press into an inert latch (`0x20000`/`0x40000`), so the
+    // broadcaster `0x61a820` sees no flag delta. It defers nothing with nothing moving, so the
+    // standstill air nudge does send, carrying the re-seeded jump tail.
     let falling = wire_flags & move_flags::FALLING != 0;
-    // The airborne lifecycle, and it is exactly two opcodes: a JUMP launch (carrying the ballistic
-    // tail) and a FALL_LAND that closes the arc. A mid-air key release updated the flag state
-    // silently (above), so the landing frame's diff has no direction edge left and the FALL_LAND
-    // goes out alone — the real client sends no trailing Stop after it (sniff-verified).
-    //
-    // **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"; 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
-    // only `CMovement::Jump 0x7c6230` seeds the launch speed; and `MSG_MOVE_JUMP` has exactly one
-    // emission site image-wide, the move-command drain's jump arm. The 1.12.1 sniff agrees — three
-    // separate non-jump falls (a login settle, a forced unroot, and a post-near-teleport arrival)
-    // each show only the terminal `FALL_LAND`. The law is: **echo → heartbeats every 500 ms while
-    // the fall lasts → FALL_LAND**, and the parenthesis is empty for any fall shorter than the
-    // deadline.
-    //
-    // It was not a harmless invention. It is the only packet in the client that could put
-    // `MOVEFLAG_JUMPING` on the wire for a jumpless arc, and vmangos reads any reported moving flag
-    // as movement — `Unit::HandleInterruptsOnMovement` answers it with `SetStandState(STAND)`,
-    // with a source comment saying the test is there *because* sitting on a chair teleports you.
-    // A chair seats you inside the collider we bake for it, where the mover's down-shapecast can
-    // report nothing and the body reads airborne while moving `dy=+0.000` for six frames; this
-    // packet then told the server we were falling, and stood us up (B79, decision 1458).
-    // **…and a WIRE-driven take-off sends no JUMP at all** (decision 1702). Same law read the other
-    // way — `MSG_MOVE_JUMP` is the keyboard's packet ([`ArcEdges::wire_launch`] carries the bytes).
-    // For a knockback the server agrees from its own side: `CHEAT_TYPE_OVERSPEED_JUMP` is one of the
-    // few vmangos checks with **no** knockback exemption (`MovementAnticheat.cpp:650`), and a
-    // knockback's horizontal speed is over run speed by design — so a JUMP here would be a logged
-    // cheat on every single one.
+    // The arc is JUMP at a keyboard take-off and FALL_LAND at the end, with no trailing Stop, as a
+    // mid-air release only updated the flags. A jumpless fall opens with nothing: the broadcaster
+    // sends only on a locomotion-nibble change (`0x61a99d` test al,0xf), and vmangos would read
+    // the JUMPING bit as movement and stand a seated player up (`Unit.cpp:10398-10399`). A
+    // server-driven take-off sends no JUMP: vmangos flags a JUMP faster than run speed as a cheat,
+    // knockbacks included (`MovementAnticheat.cpp:650`).
     if jumped && !wire_launch {
         send_move!(MoveKind::Jump);
     } else if landed {
         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 (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.
+    // `START_SWIM` (0xca) and `STOP_SWIM` (0xcb) go out the frame `SWIMMING` flips, enqueued by
+    // the swim decision `0x6030c0`; airborne and swimming never overlap, so the arc cannot race.
     if added & move_flags::SWIMMING != 0 {
         send_move!(MoveKind::StartSwim);
     } else if removed & move_flags::SWIMMING != 0 {
         send_move!(MoveKind::StopSwim);
     }
-    // The gait toggle: `MSG_MOVE_SET_WALK_MODE` (0xc3) entering walk, `MSG_MOVE_SET_RUN_MODE`
-    // (0xc2) leaving it — the same "a dedicated opcode the frame the bit flips" shape as the swim
-    // pair above, and for the same reason. It sits OUTSIDE the `if !falling || air_nudged` axis
-    // block on purpose: a mode flip is not an axis transition, so the airborne silence (which
-    // exists because mid-air direction presses are deferred into an inert latch) does not apply —
-    // the reference's `ToggleRun` refuses nothing about being airborne and enqueues its event
-    // regardless. And it must fire while standing perfectly still, which is the whole reason the
-    // reference gives the toggle its own enqueue rather than letting the move-state broadcaster
-    // find it: that broadcaster gates on the locomotion nibble (`0x61a99d test al,0xf`) and would
-    // drop it. This differ has no such gate (decision 1752).
+    // `SET_WALK_MODE` (0xc3) and `SET_RUN_MODE` (0xc2) go out the frame the bit flips, airborne or
+    // standing still: the reference's `ToggleRun` enqueues its own event, since the broadcaster
+    // gates on the locomotion nibble (`0x61a99d` test al,0xf) and would drop it.
     if added & move_flags::WALK_MODE != 0 {
         send_move!(MoveKind::SetWalkMode);
     } else if removed & move_flags::WALK_MODE != 0 {
         send_move!(MoveKind::SetRunMode);
     }
-    // Forward/back axis — silent while airborne (the flag state rides the next packet instead),
-    // except on the nudge frame. The **stop** arms stay silent while falling no matter what: a
-    // mid-air release is the deferred-latch case, always, and the nudge frame is a press by
-    // definition — so this only keeps a same-frame release on the *other* axis from slipping out.
+    // The stop arms stay silent while falling even on the nudge frame: a mid-air release is always
+    // deferred, and this keeps one on the other axis from slipping out with the nudge.
     if !falling || air_nudged {
         if added & move_flags::FORWARD != 0 {
             send_move!(MoveKind::StartForward);
@@ -382,7 +243,6 @@ pub(super) fn stream_self_movement(
         } else if !falling && removed & FB != 0 && wire_flags & FB == 0 {
             send_move!(MoveKind::Stop);
         }
-        // Strafe axis — same airborne silence, same one exception.
         if added & move_flags::STRAFE_LEFT != 0 {
             send_move!(MoveKind::StartStrafeLeft);
         } else if added & move_flags::STRAFE_RIGHT != 0 {
@@ -391,7 +251,7 @@ pub(super) fn stream_self_movement(
             send_move!(MoveKind::StopStrafe);
         }
     }
-    // Turn axis (keyboard A/D when not mouse-looking).
+    // The turn axis sends airborne too: turning works mid-air.
     if added & move_flags::TURN_LEFT != 0 {
         send_move!(MoveKind::StartTurnLeft);
     } else if added & move_flags::TURN_RIGHT != 0 {
@@ -399,141 +259,52 @@ pub(super) fn stream_self_movement(
     } else if removed & TURN != 0 && wire_flags & TURN == 0 {
         send_move!(MoveKind::StopTurn);
     }
-    // The facing report: one `MSG_MOVE_SET_FACING` per frame in which the facing actually changed —
-    // **the single biggest thing our wire stream was missing** (decision 0617). **VERIFIED** against the
-    // real 1.12.1.5875 sniff (`dwarf_rogue_dun_morogh`): 179 of its 336 client-sent movement packets are
-    // 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 — `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
-    // comparison neither floods nor misses.)
-    //
-    // The one exclusion is the **turn axis**: not a single SET_FACING in the capture carries `TURN_LEFT`
-    // or `TURN_RIGHT`. A keyboard turn is already fully described by its flag — observers rotate the
-    // mover at the turn rate for as long as it's set — so the facing needs no separate carrier, and the
-    // STOP_TURN closes the arc with the final angle.
-    //
-    // Not gated on `sent`: the capture repeatedly shows a SET_FACING sharing a millisecond with a
-    // transition (`+1563` SET_FACING & STOP_STRAFE, `+3009` SET_FACING & STOP, `+4971` SET_FACING &
-    // START_STRAFE_RIGHT). They are two independent emitters in the reference — the input-phase facing
-    // report and the move-state broadcaster — not one prioritized channel.
+    // One `SET_FACING` per frame the facing changed, moving or not, with no rate limit: the
+    // reference drains each facing set into a send (`0x615fc6` push `0xda`). None while a turn bit
+    // is set, which already rotates the mover for observers, and not gated on `sent`: the facing
+    // report and the broadcaster are independent emitters.
     if wire_flags & TURN == 0 && facing != player.last_facing {
         send_move!(MoveKind::SetFacing);
     }
-    // Board/deboard: the ON_TRANSPORT flip has no axis opcode of its own, so if nothing else went
-    // out this frame, a heartbeat announces it promptly — the server learns the new frame (and its
-    // local-pose tail, or its absence) the frame it changes rather than on the next natural packet.
+    // Boarding or leaving a deck has no opcode of its own, so a heartbeat carries the flip that
+    // frame if nothing else went out.
     if !sent && (added | removed) & move_flags::ON_TRANSPORT != 0 {
         send_move!(MoveKind::Heartbeat);
     }
-    // Heartbeat keeps a moving/turning mover's position + facing flowing between transitions. While
-    // riding, ON_TRANSPORT alone keeps this stream alive — the deck carries us, so our world pose
-    // really is changing (decision 0056: the wire mirrors actual motion) and observers on reference
-    // clients keep a fresh compose anchor.
-    //
-    // **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 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
-    // sends is traced now, and it is *this deadline*: `[mgr+0x130]` is re-armed to `now + 500 ms`
-    // after **every** outbound packet (`0x600a30` → `0x615b80`), which is why one 892 ms jump shows
-    // no heartbeat at all — the player's own SET_FACING at `fallTime 460` pushed the deadline out
-    // to 960. Our `last_heartbeat` is already stamped on every send below, so dropping the gate
-    // reproduces the reference's cadence exactly rather than approximating it.
-    //
-    // This does not re-open B79: a chair arrival's stall is ~100 ms and the arrival's own reconcile
-    // packet re-arms the deadline, so nothing fires inside it. What FALLING must never do is open
-    // an arc with a packet of its own — that is the arm above, and it is gone.
+    // The heartbeat runs while any sent flag is set; the reference's (`0x616620`) runs only while
+    // `flags & 0x200f`, the directions and FALLING (`0x616725`). Every send re-arms its deadline
+    // (`0x600a30` → `0x615b80`), hence the stamp on any send below.
     if !sent && wire_flags != 0 && now - player.last_heartbeat >= HEARTBEAT_INTERVAL {
         send_move!(MoveKind::Heartbeat);
     }
-    // ── The position reconcile (decision 0907) ── **the server's copy of where we are may never go
-    // stale.** Our resolver settles a body that is already at rest by a fraction of a millimetre
-    // *after* the packet that reported the rest: a landing reports the touchdown pose and the next
-    // frame's step-down snap takes 2e-5 yd off it; a login/teleport lands on a server-authored
-    // position our own collision resolves a hair differently. Until 0617 nothing carried that
-    // difference, and while standing still nothing else goes out — so the client and the server
-    // silently held two different positions, and the next packet of ANY kind delivered the whole
-    // accumulated delta at once.
-    //
-    // vmangos reads that delta as movement, on an **exact float compare**: `Player::SetPosition`
-    // sets `positionChanged = old_x != x || old_y != y || old_z != z` and hands it to
-    // `Unit::HandleInterruptsOnMovement`, which runs `InterruptSpellsWithInterruptFlags(
-    // SPELL_INTERRUPT_FLAG_MOVEMENT)`. No epsilon: 2e-5 yd cancels a cast exactly as a yard would.
-    // (Verified in the deployed server's source, `Objects/Player.cpp` + `Objects/Unit.cpp`; the
-    // 0.5-yd tolerance elsewhere in `Spell::update` is a different, later test.)
-    //
-    // The observable was the director's: right-dragging to look around killed a cast. Mouse-look is
-    // the one thing that puts packets on the wire while standing still (SET_FACING at frame
-    // cadence), so it was the messenger — the first one after a run, a jump, or a login carried a
-    // stale-position "you moved" into the middle of the cast. Reporting the drift when it *happens*
-    // — at rest, so once per settle rather than per frame — keeps the two copies identical, and a
-    // cast then dies to real movement only.
+    // At rest, a position change goes out the frame it happens: the resolver settles a resting
+    // body by fractions of a millimetre after the packet that reported it, and vmangos compares
+    // positions exactly (`Player.cpp:6092`), so a stale copy arrives with the next packet as
+    // movement and interrupts the cast in flight (`Unit.cpp:10387`).
     if !sent && wire_flags & IN_MOTION == 0 && wow_pos != player.last_pos {
         send_move!(MoveKind::Heartbeat);
     }
     if sent {
         player.last_heartbeat = now;
     }
-    // The change detector's reference is the **previous frame's** facing, not the last one we reported:
-    // the reference compares the new facing against the unit's live facing cell, which its setter
-    // updates on every change whether or not a packet went out. So the turn-axis frames above, which
-    // deliberately send nothing, still leave no catch-up packet behind when the key releases.
+    // The facing compare is against the previous frame's facing, sent or not, so a keyboard turn
+    // leaves no catch-up `SET_FACING` behind.
     player.last_facing = facing;
     player.move_flags = wire_flags;
 }
 
-/// Park our mover on the wire: flush a single `MSG_MOVE_STOP` (flags cleared) so the server — and the
-/// observers extrapolating from it — drop whatever locomotion flags we last reported, then zero our
-/// bookkeeping. Called when the controller stops driving the avatar with stale flags still live on the
-/// **`CMSG_MOVE_TIME_SKIPPED` — the milliseconds the mover advanced through without integrating**
-/// (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. 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
-/// (`0x634154`) and the fall integrator's TOI kernel finding no contact (`0x635742`), each
-/// reporting the substep budget they could not spend. Across 79 sniffs of the reference,
-/// 1277 of 1278 packets carry `lag ≤ 250` — the clamped substep budget those two draw from —
-/// and an exact-build 36-minute session sent **three**, at world entry and after a teleport.
-///
-/// **benilla's no-geometry state is the settle hold**, and that is what this reports: the frames
-/// after a login, teleport or worldport where the destination's terrain and building colliders
-/// have not streamed in, so the mover freezes rather than falling through a city that isn't there
-/// (decision 0737). Same cause, same quantity, same moments the reference's own captures show it.
-///
-/// **The coalescing is ours, deliberately.** The reference sends once per firing, which for it is
-/// once per skipped substep — and its no-geometry window is a substep or two wide, because it
-/// loads the world before it places you. Ours is a live stream that can hold for seconds, so
-/// per-frame parity would put hundreds of packets on the wire where the reference puts one. The
-/// *quantity* is what the wire means and the quantity is preserved whole; the packet count is
-/// kept at the reference's. What is NOT copied is the send's `[mgr+0x130] += lag` side effect
-/// (the 500 ms heartbeat deadline pushed out by the skipped time): that deadline is only ever read
-/// while moving, and a held body streams zeroed flags with its mover parked, so there is no
-/// heartbeat inside a settle for it to delay. Applying a multi-second delay to the first heartbeat
-/// *after* one would be our invention, not the reference's.
-///
-/// 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, and need
-/// not be: a client implementing the other three sites matches every packet in the shipped
-/// captures.
+/// `CMSG_MOVE_TIME_SKIPPED`: the milliseconds the mover advanced through without integrating. The
+/// reference's common senders are its no-geometry pair (`0x634154`, `0x635742`), time with no
+/// world to resolve against, which is our settle hold; its long-frame site (`0x616642`) has no
+/// counterpart, as we integrate a long frame whole. Deviation: a hold is summed and sent once on
+/// release, without the send's `[mgr+0x130] += lag` heartbeat push, because ours lasts seconds
+/// where the reference's lasts a substep.
 fn stream_skipped_time(sender: &Sender<ClientCommand>, player: &mut Player, skip: SkipClock) {
     if skip.held {
         player.skipped_ms += skip.dt * 1000.0;
         return;
     }
-    // The release edge: report the whole hold at once, then disarm. Sub-millisecond residue is
-    // dropped rather than carried — the wire field is whole milliseconds and a `0` lag is a
-    // packet that says nothing.
+    // The release edge sends the whole hold in whole ms; the residue is dropped.
     let lag_ms = player.skipped_ms as u32;
     player.skipped_ms = 0.0;
     if lag_ms == 0 {
@@ -542,27 +313,21 @@ fn stream_skipped_time(sender: &Sender<ClientCommand>, player: &mut Player, skip
     let Some(guid) = skip.mover else {
         return;
     };
-    // The reference's `0x600be0` refuses unless the named mover IS the active mover
-    // (`0x600bec`/`0x600bfb` against `[0xc4da98]`/`[0xc4da9c]`); ours is the same statement, made
-    // by naming the mover the controller is driving and nothing else.
+    // The reference's builder `0x600be0` sends only for the active mover (`0x600bec`/`0x600bfb`
+    // against `[0xc4da98]`/`[0xc4da9c]`); we name only the one we drive.
     super::move_trace::skipped_time(guid, lag_ms);
     let _ = sender.send(ClientCommand::MoveTimeSkipped { guid, lag_ms });
 }
 
-/// wire — entering free-fly (`F`), where [`stream_self_movement`] no longer runs each frame, so nothing
-/// else would ever clear them and observers would extrapolate a phantom walk/spin until we re-attach.
-/// **Idempotent**: a no-op once we've already reported stopped, so it's safe to call every free-fly
-/// frame. The frozen pose + `[0, 2π)`-normalized facing follow the module invariant.
+/// Sends one flag-less `MSG_MOVE_STOP` when the controller stops driving the avatar (free-fly),
+/// as nothing else would clear the flags observers extrapolate from; a no-op once stopped.
 pub(super) fn park_mover(sender: &Sender<ClientCommand>, player: &mut Player) {
     if player.move_flags == 0 {
         return;
     }
     let facing = player.face_yaw.rem_euclid(std::f32::consts::TAU);
     let pos = bevy_to_wow(player.pos);
-    player.last_pos = pos; // the park is a position report too (decision 0907's reconcile)
-                           // Traced like every other outbound move: the park is a real `MSG_MOVE_STOP` on the wire, and
-                           // leaving it off `snd` made the trace lie by omission at exactly the edges it was wanted for —
-                           // the handover, the free-fly detach, the moment control is taken (decision 1281).
+    player.last_pos = pos; // the park is a position report too
     super::move_trace::sent(MoveKind::Stop, 0, facing, pos);
     let _ = sender.send(ClientCommand::Move {
         kind: MoveKind::Stop,
@@ -578,10 +343,8 @@ 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.
+/// The rider's deck-local pose for the `ON_TRANSPORT` tail, or `None` off a deck. `bevy_to_wow` is
+/// a pure rotation, so it converts the local offset too; the local facing is `face_yaw - boat_yaw`.
 pub(super) fn wire_transport(player: &Player) -> Option<TransportPose> {
     player.ride.as_ref().map(|r| {
         let local = bevy_to_wow(r.local_pos);
@@ -597,17 +360,11 @@ pub(super) fn wire_transport(player: &Player) -> Option<TransportPose> {
     })
 }
 
-/// **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.
+/// Acks forced speed changes on a frame the controller does not drive (a server spline, a fear, a
+/// mover hand-off), as the reference's per-mover drain acks whoever drives (`0x616142`,
+/// `0x61812d`). Unacked, vmangos enforces the change after 4 s, counts the miss for anticheat and
+/// holds the graveyard repop (`Player.cpp:1332`). The payload is our last reported flags minus the
+/// airborne pair, as no arc runs on these frames.
 pub(super) fn ack_speeds_undriven(
     sender: &Sender<ClientCommand>,
     player: &Player,
@@ -638,8 +395,6 @@ pub(super) fn ack_speeds_undriven(
 
 #[cfg(test)]
 mod tests {
-    /// A frame that integrated everything it was given — the skipped-time report's no-op input,
-    /// which is every frame in these tests but the one that exercises it.
     fn no_skip() -> SkipClock {
         SkipClock {
             dt: 0.0,
@@ -651,12 +406,6 @@ mod tests {
     use super::*;
     use std::f32::consts::TAU;
 
-    /// **The gait toggle announces itself standing perfectly still** — which is the whole reason
-    /// **The skipped-time report** (decision 1935): held frames accumulate, the release edge sends
-    /// the total ONCE, and nothing is sent for a frame that actually integrated. The three
-    /// properties together are the whole contract — a per-frame send would be hundreds of packets
-    /// per settle, a lost accumulator would tell the server nothing, and a send with no hold
-    /// behind it would be a lie about our own simulation.
     #[test]
     fn a_settle_hold_reports_its_skipped_milliseconds_once_on_release() {
         const MOVER: u64 = 0x0000_0000_0000_002a;
@@ -672,8 +421,7 @@ mod tests {
             held: false,
             mover: Some(MOVER),
         };
-        // Three held frames: 0.5 s of simulation advanced through, nothing integrated, and
-        // NOTHING on the wire yet — the report is one packet, not one per frame.
+        // Four held frames, 0.5 s in all.
         for _ in 0..3 {
             stream_skipped_time(&tx, &mut player, held(0.1));
         }
@@ -683,7 +431,6 @@ mod tests {
             "a hold in progress sends nothing — the reference's own captures show one packet per \
              skip, not one per frame"
         );
-        // The release: one packet, carrying the whole hold.
         stream_skipped_time(&tx, &mut player, released());
         match rx.try_recv().expect("the release edge reports") {
             ClientCommand::MoveTimeSkipped { guid, lag_ms } => {
@@ -692,7 +439,6 @@ mod tests {
             }
             other => panic!("expected MoveTimeSkipped, got {other:?}"),
         }
-        // …and the accumulator disarms: a second released frame reports nothing.
         stream_skipped_time(&tx, &mut player, released());
         assert!(
             rx.try_recv().is_err(),
@@ -700,12 +446,6 @@ mod tests {
         );
     }
 
-    /// the reference gives `ToggleRun` its own move-event enqueue instead of letting the
-    /// move-state broadcaster find the flag change: that broadcaster gates every send on the
-    /// locomotion nibble (`0x61a99d test al,0xf`), so a toggle with no direction bit set would
-    /// never leave the client through it. Ours rides the flag differ, which has no such gate.
-    /// Observers derive a walker's speed from the relayed bit, so a swallowed packet is a
-    /// remote body that keeps running at 7 yd/s while its owner walks (decision 1752).
     #[test]
     fn the_walk_toggle_sends_its_own_opcode_with_no_movement_at_all() {
         let (tx, rx) = crossbeam_channel::unbounded();
@@ -717,7 +457,7 @@ mod tests {
             landed: false,
             fall_time: 0,
         };
-        // Entering walk: MSG_MOVE_SET_WALK_MODE (0xc3), and it carries the bit it announces.
+        // Entering walk: MSG_MOVE_SET_WALK_MODE (0xc3).
         stream_self_movement(
             &tx,
             &mut player,
@@ -739,7 +479,7 @@ mod tests {
         assert_eq!(kind.opcode(), 0x00C3);
         assert_eq!(flags & move_flags::WALK_MODE, move_flags::WALK_MODE);
 
-        // …and leaving it is the OTHER opcode, not a repeat of the same one.
+        // Leaving it: MSG_MOVE_SET_RUN_MODE (0xc2).
         stream_self_movement(
             &tx,
             &mut player,
@@ -761,7 +501,6 @@ mod tests {
         assert_eq!(kind.opcode(), 0x00C2);
         assert_eq!(flags & move_flags::WALK_MODE, 0);
 
-        // A steady walk announces nothing further — it is an edge, not a per-frame report.
         stream_self_movement(
             &tx,
             &mut player,
@@ -795,9 +534,6 @@ mod tests {
         );
     }
 
-    /// The toggle is not an axis transition, so the airborne silence must not swallow it: a
-    /// mid-air press flips the bit and the packet goes out (the reference's `ToggleRun` refuses
-    /// nothing about being airborne, and the fall's own heartbeats would carry the bit anyway).
     #[test]
     fn a_walk_toggle_taken_mid_air_is_not_swallowed_by_the_airborne_silence() {
         let (tx, rx) = crossbeam_channel::unbounded();
@@ -838,13 +574,9 @@ mod tests {
 
     #[test]
     fn wire_orientation_is_normalized_into_0_2pi() {
-        // `face_yaw` is an unbounded accumulator, but vmangos's `VerifyMovementInfo` rejects any
-        // movement packet whose orientation has `|o| > 4π` (≈ 12.566) — so a large yaw must leave the
-        // controller wrapped into [0, 2π), matching the real client. A fresh FORWARD press emits a
-        // StartForward carrying the current orientation, so we can read back what went on the wire.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player {
-            face_yaw: 100.0, // ~15.9 turns — far past the 4π reject bound
+            face_yaw: 100.0, // ~15.9 turns, far past vmangos's 4π bound
             ..Default::default()
         };
         stream_self_movement(
@@ -884,18 +616,13 @@ mod tests {
 
     #[test]
     fn fall_land_reports_the_accumulated_fall_time() {
-        // The landing frame's FALL_LAND must carry the arc's accumulated fall clock — vmangos's
-        // `Player::HandleFall` only deals fall damage when the land packet's fallTime ≥ 1229 ms, so
-        // a zeroed clock silently disables fall damage. The controller snapshots the clock before
-        // its arc bookkeeping clears `airborne_since`; this pins that the snapshot — not a re-read
-        // of the (already-cleared) arc state — is what goes on the wire.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player::default(); // airborne_since already cleared, as on a landing frame
         stream_self_movement(
             &tx,
             &mut player,
             0,
-            // grounded again: no FALLING/FALLINGFAR on the land packet itself
+            // grounded: no FALLING on the land packet itself
             0.0,
             ArcEdges {
                 jumped: false,
@@ -904,7 +631,7 @@ mod tests {
                 landed: true,
                 fall_time: 1700,
             },
-            // the snapshot: ~1.7 s of fall (> the 1229 ms damage gate)
+            // 1.7 s of fall, past vmangos's 1229 ms fall-damage gate
             0.0,
             &[],
             None,
@@ -927,16 +654,12 @@ mod tests {
 
     #[test]
     fn airborne_direction_release_is_silent_and_the_landing_sends_only_fall_land() {
-        // The sniff-verified airborne send law: releasing W mid-air emits NO packet (the flag
-        // state updates silently and rides the next packet), and the landing then sends exactly
-        // one FALL_LAND — never a trailing Stop (the real client sends none; the extra Stop was
-        // what re-picked the observer's landing anim away).
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player {
             move_flags: move_flags::FORWARD | move_flags::FALLING, // last sent: the JUMP's flags
             ..Default::default()
         };
-        // Mid-air, W released: flags drop FORWARD but keep FALLING — silence.
+        // Mid-air, W released.
         stream_self_movement(
             &tx,
             &mut player,
@@ -961,7 +684,7 @@ mod tests {
             move_flags::FALLING,
             "the flag state still updated silently"
         );
-        // The landing frame: grounded, no keys — one FALL_LAND, flags 0, and nothing after it.
+        // The landing frame, no keys held.
         stream_self_movement(
             &tx,
             &mut player,
@@ -992,19 +715,10 @@ 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 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`
-    /// on the wire for a jumpless arc, and vmangos answers a reported moving flag with
-    /// `SetStandState(STAND)` — which is what un-seated a chair-sitter for six frames of
-    /// `dy=+0.000` inside the chair's own collider (B79, decision 1458).
     #[test]
     fn a_jumpless_fall_opens_with_nothing_and_heartbeats_on_the_deadline() {
         let (tx, rx) = crossbeam_channel::unbounded();
-        // Grounded last frame (flags 0), airborne now with no jump: the walk-off / arrival case.
+        // Grounded last frame, airborne now with no jump: a walk-off.
         let mut player = Player::default();
         let step_off = |now: f32, player: &mut Player| {
             stream_self_movement(
@@ -1038,12 +752,9 @@ mod tests {
             "the flag state still updated silently, to ride the next packet that does go out"
         );
 
-        // Still inside the 500 ms deadline: silent. A chair arrival's whole stall lives here.
         step_off(0.4, &mut player);
         assert!(rx.try_recv().is_err(), "inside the deadline, still silent");
 
-        // Past it: the ordinary heartbeat runs, carrying the live FALLING bit. This is the half the
-        // old `&& !falling` gate suppressed, and the sniff shows mid-air heartbeats plainly.
         step_off(0.7, &mut player);
         let ClientCommand::Move { kind, flags, .. } = rx
             .try_recv()
@@ -1061,11 +772,6 @@ mod tests {
 
     #[test]
     fn the_standstill_air_nudge_is_the_one_press_that_breaks_the_airborne_silence() {
-        // Decision 0627. The airborne silence is the reference's *deferral* (`StartMove 0x7c6ae0`
-        // latches a mid-air press instead of flipping the direction bit) and the deferral has one
-        // byte-verified exclusion: "unless nothing is currently moving". That case really flips the
-        // bit, so the broadcaster really sends — and it must, because it is the only case where the
-        // press changed our motion, and the observer is integrating an arc that says xy_speed = 0.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player {
             move_flags: move_flags::FALLING, // the standing jump: airborne, no direction
@@ -1108,8 +814,7 @@ mod tests {
         );
         assert!(rx.try_recv().is_err(), "one packet, not a burst");
 
-        // The other side of the same rule: a press that did NOT nudge (a jump taken with momentum —
-        // the reference defers it into an inert latch) stays silent, exactly as the sniff shows.
+        // A press mid-arc with momentum is deferred, so silent.
         let mut moving = Player {
             move_flags: move_flags::FORWARD | move_flags::FALLING,
             ..Default::default()
@@ -1140,10 +845,6 @@ mod tests {
 
     #[test]
     fn airborne_turn_transitions_and_facing_still_stream() {
-        // The two things that DO go out mid-air (sniff-verified): the turn axis (turning works
-        // airborne — START_TURN_RIGHT/STOP_TURN with Falling set) and SET_FACING for a mouse
-        // jump-turn — the capture's `8193 (Forward, Falling)` SET_FACINGs, which carry **no** turn
-        // bit. No heartbeats stream while FALLING, so the facing needs its own carrier.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player {
             move_flags: move_flags::FORWARD | move_flags::FALLING,
@@ -1175,9 +876,8 @@ mod tests {
         assert_eq!(kind, MoveKind::StartTurnLeft);
         assert_ne!(flags & move_flags::FALLING, 0, "the packet rides the arc");
         assert!(rx.try_recv().is_err(), "the turn axis carries the facing");
-        // Mid-air mouse-turn with the turn key released: the StopTurn transition is this frame's
-        // send, so the periodic arm does not add a second packet (it is `!sent`-gated, not
-        // FALLING-gated — 1464), and the facing streams via SET_FACING once the turn flag is gone.
+        // A mouse turn as the turn key releases, past the heartbeat deadline: the heartbeat is
+        // `!sent`-gated, so only the StopTurn and the SET_FACING go out.
         player.face_yaw = 1.0;
         stream_self_movement(
             &tx,
@@ -1213,11 +913,6 @@ mod tests {
 
     #[test]
     fn facing_streams_while_running() {
-        // **The regression this law exists for** (decision 0617). A mouse-turn while running used to
-        // put nothing on the wire until the next ~500 ms heartbeat, so observers dead-reckoned us in a
-        // stale direction for half a second and then watched us snap. The reference streams SET_FACING
-        // *while moving* — 116 of the capture's 179 carry a direction bit — so every frame the facing
-        // moves, one packet goes out carrying the live direction flags.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player {
             move_flags: move_flags::FORWARD, // already running: no transition this frame
@@ -1258,8 +953,7 @@ mod tests {
             rx.try_recv().is_err(),
             "exactly one packet per changed frame"
         );
-        // A frame that didn't move the mouse sends nothing: the detector is exact equality, not a
-        // rate limit — and the heartbeat deadline (0.5 s) has not come round.
+        // The same facing, inside the heartbeat deadline.
         stream_self_movement(
             &tx,
             &mut player,
@@ -1283,10 +977,6 @@ mod tests {
 
     #[test]
     fn the_turn_axis_carries_its_own_facing() {
-        // Not one SET_FACING in the capture carries TURN_LEFT/TURN_RIGHT: a keyboard turn is fully
-        // described by its flag (observers rotate at the turn rate while it's set), so the facing it
-        // sweeps needs no packet of its own — and, crucially, the suppressed frames leave no catch-up
-        // packet behind, because the change detector tracks the previous frame's facing regardless.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player {
             move_flags: move_flags::FORWARD | move_flags::TURN_RIGHT,
@@ -1317,8 +1007,7 @@ mod tests {
                 "the turn axis is silent (frame {i})"
             );
         }
-        // Release the turn key with the facing unchanged since the last swept frame: the STOP_TURN
-        // goes out and nothing follows it.
+        // Release the turn key, the facing unchanged since the last frame.
         stream_self_movement(
             &tx,
             &mut player,
@@ -1349,9 +1038,6 @@ mod tests {
 
     #[test]
     fn a_transition_does_not_swallow_the_facing_report() {
-        // The capture repeatedly shows both in one millisecond (`+4971` SET_FACING & START_STRAFE_
-        // RIGHT). They are two independent emitters in the reference, so a frame that both turns and
-        // changes axis puts both on the wire.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player {
             move_flags: move_flags::FORWARD,
@@ -1386,7 +1072,7 @@ mod tests {
         assert_eq!(kinds, vec![MoveKind::StartStrafeRight, MoveKind::SetFacing]);
     }
 
-    /// One idle frame at `pos`, nothing else happening — the shape every reconcile test needs.
+    /// One idle frame at `pos`.
     fn idle_frame(tx: &Sender<ClientCommand>, player: &mut Player, pos: bevy::prelude::Vec3) {
         player.pos = pos;
         stream_self_movement(
@@ -1411,13 +1097,6 @@ mod tests {
 
     #[test]
     fn a_resting_body_that_drifts_reports_it_once() {
-        // Decision 0907. Our resolver settles a body already at rest a fraction of a millimetre after
-        // the packet that reported the rest (a landing, a login, a teleport onto a server-authored
-        // pose), and standing still nothing else goes out — so the server's copy of our position went
-        // stale, and the next packet of any kind (in practice a right-drag's SET_FACING) delivered the
-        // whole delta at once. vmangos compares positions with EXACT float equality and reads any
-        // difference as movement, cancelling a movement-interrupt cast. So: at rest, a changed
-        // position IS the news, and one heartbeat carries it — then silence again.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player::default();
         idle_frame(&tx, &mut player, bevy::prelude::Vec3::new(1.0, 2.0, 3.0));
@@ -1430,13 +1109,12 @@ mod tests {
         assert_eq!(kind, MoveKind::Heartbeat);
         assert_eq!(flags, 0, "at rest — the reconcile invents no motion");
         assert_eq!(pos, bevy_to_wow(bevy::prelude::Vec3::new(1.0, 2.0, 3.0)));
-        // The same position again: the server's copy is current, so nothing goes out.
         idle_frame(&tx, &mut player, bevy::prelude::Vec3::new(1.0, 2.0, 3.0));
         assert!(
             rx.try_recv().is_err(),
             "an unchanged resting position is silent — one packet per settle, not per frame"
         );
-        // A settle that is one float wide still counts: vmangos's compare has no epsilon.
+        // One ULP still counts: vmangos's compare has no epsilon.
         idle_frame(
             &tx,
             &mut player,
@@ -1450,10 +1128,6 @@ mod tests {
 
     #[test]
     fn the_reconcile_never_fires_while_the_body_is_in_motion() {
-        // In motion the position changes every frame BY DESIGN, and the transition + ~500 ms
-        // heartbeat stream is what carries it (0052/0053) — a per-frame reconcile there would be a
-        // packet flood, and the reference sends nothing of the kind. The gate is the motion mask, so
-        // a runner mid-stride and a body mid-arc are both silent between their own packets.
         let (tx, rx) = crossbeam_channel::unbounded();
         for flags in [move_flags::FORWARD, move_flags::FALLING] {
             let mut player = Player {
@@ -1470,12 +1144,10 @@ mod tests {
 
     #[test]
     fn park_mover_flushes_a_stop_and_clears_stale_flags() {
-        // We were last streaming FORWARD when the controller stopped driving us (free-fly). Parking must
-        // send one Stop with flags cleared (so observers drop the phantom walk) and a normalized facing.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player {
             move_flags: move_flags::FORWARD,
-            face_yaw: -3.0, // out-of-range / negative — must still go out normalized
+            face_yaw: -3.0, // negative: must still go out normalized
             ..Default::default()
         };
         park_mover(&tx, &mut player);
@@ -1496,12 +1168,6 @@ 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();
@@ -1541,7 +1207,7 @@ mod tests {
         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.
+        // On a deck.
         let player = Player {
             move_flags: move_flags::ON_TRANSPORT,
             ride: Some(super::super::state::PlayerRide {
@@ -1563,23 +1229,11 @@ mod tests {
         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
-    /// single live emission site image-wide — `0x615ed1`, the move-command drain's jump arm — and
-    /// the knockback's own arm of that same drain pushes `0xf0`, its ack, instead. So a knockback
-    /// announces itself once, on the ack, whose `MovementInfo` is what the server turns into every
-    /// observer's `MSG_MOVE_KNOCK_BACK`.
-    ///
-    /// The regression this pins is not cosmetic: `CHEAT_TYPE_OVERSPEED_JUMP` is one of the few
-    /// vmangos checks with no knockback exemption, and it fires on any `MSG_MOVE_JUMP` whose
-    /// `xyspeed` exceeds run speed — which a knockback's does by design.
     #[test]
     fn a_knockback_acks_and_sends_no_jump() {
         let (tx, rx) = crossbeam_channel::unbounded();
-        // Mid-launch: the mover has seeded the arc from the quad below (Bevy −Z is WoW +X, so a
-        // due-west push of 25 yd/s lands as `horiz_vel.z = −25`), and `jump_zspeed` is +up where the
-        // wire's is down-positive.
+        // Mid-launch, the arc seeded from the quad below: Bevy −Z is WoW +X (north), so a 25 yd/s
+        // push north is `horiz_vel.z = −25`, and `jump_zspeed` is up-positive.
         let launch = benilla_protocol::JumpInfo {
             zspeed: -12.0,
             cos_angle: 1.0,
@@ -1597,7 +1251,7 @@ mod tests {
             move_flags::FALLING,
             0.0,
             ArcEdges {
-                jumped: true, // the arc really opened — the bookkeeping cannot tell the two apart
+                jumped: true, // the arc opened; only `wire_launch` tells a knockback apart
                 wire_launch: true,
                 air_nudged: false,
                 landed: false,
@@ -1648,8 +1302,6 @@ mod tests {
         }
     }
 
-    /// The other half of the same gate: an ordinary jump on an identical frame still sends its JUMP.
-    /// Without this, "no JUMP for a knockback" could be satisfied by never sending one at all.
     #[test]
     fn an_ordinary_jump_still_sends_its_jump() {
         let (tx, rx) = crossbeam_channel::unbounded();
@@ -1691,8 +1343,6 @@ mod tests {
 
     #[test]
     fn park_mover_is_a_noop_once_already_stopped() {
-        // Idempotent: with no stale flags there's nothing to clear, so no packet goes out — safe to call
-        // every free-fly frame.
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut player = Player::default(); // move_flags == 0
         park_mover(&tx, &mut player);
diff --git a/crates/benilla-app/src/player/mover.rs b/crates/benilla-app/src/player/mover.rs
index 5788a3ed..24aa74d5 100644
--- a/crates/benilla-app/src/player/mover.rs
+++ b/crates/benilla-app/src/player/mover.rs
@@ -1,36 +1,6 @@
-//! The kinematic mover step — the walk/fall physics and the step-down snap, split out of the
-//! `control` system ([`super::controller`] keeps the frame order; [`super`] the knob table this
-//! reads).
-//! One call per frame: [`step`].
-//!
-//! Thin kinematic controller (decision 0009) over the **one-sided** mirror of avian's
-//! `MoveAndSlide` (`benilla_world::collision::one_sided`, decision 0970: a face only blocks motion its
-//! authored winding opposes, the reference's `0x632700` law) — kept simple and robust on the
-//! triangulated heightmap:
-//!   - probe down to classify the ground (walkable iff its normal is within ~50° of up);
-//!   - "grounded" = on walkable ground AND not rising, so a jump cleanly leaves the ground (and
-//!     isn't re-grounded the next frame — the bug that ate most jumps). While airborne the probe
-//!     tightens to [`LAND_PROBE`], so the arc ends where the slide actually contacts the floor
-//!     rather than snapping the last fraction of a yard (decision 0190);
-//!   - grounded → move horizontally only, with NO gravity fed into the slide (gravity-slide was
-//!     the downhill creep on micro-sloped terrain), then snap onto the surface to follow it;
-//!   - a walkable slope never slows or deflects the walk: the real client's walk is
-//!     two-dimensional (speed·dt of *horizontal* distance), so an opposing walkable plane rides
-//!     instead of clipping ([`walkable_ride_velocity`]) — full 2D speed on every ≤50° surface;
-//!   - a steep face in the way is first *certified* by the atomic step-up ([`step_up`]):
-//!     rise–advance–settle onto a walkable floor, or nothing (decision 0209). What a certified
-//!     obstacle then costs is the reference's two-regime law (decision 1123): a rise inside the
-//!     foot cone ([`FOOT_CONE_HEIGHT`]) is **ridden** up the cone's 61.6° skirt over the frames the
-//!     gait needs ([`foot_cone_ride`]) — a kerb takes three at a run; only a rise above the cone is
-//!     the instant pop, committed whole within the frame. Uncertified, nothing rises at all;
-//!   - a steep face's response is **horizontal only** and the descent passes through it untouched
-//!     ([`steep_contact_shear`], the reference's own `0x635090`): the body follows the surface
-//!     down at full free-fall rate, no contact can manufacture lift at any angle, and a jump at a
-//!     hillside costs the jump instead of banking its height;
-//!   - airborne → gravity carries the arc, with a one-shot nudge to steer a standstill jump;
-//!   - a fall whose descent stalls (a capsule wedged between steep faces — the
-//!     tree-pinch funnel) *lands there*: standing, walking control live, instead of hanging in
-//!     the falling pose forever with mid-air control locked (decisions 0211/0212).
+//! The player's kinematic mover, one [`step`] a frame: ground classify, jump and fall, the slide,
+//! step-up and step-down, over avian's `MoveAndSlide` with one-sided faces (a face blocks only the
+//! motion its authored winding opposes, the reference's `0x632700`).
 
 use avian3d::character_controller::move_and_slide::MoveHitData;
 use avian3d::prelude::*;
@@ -43,33 +13,16 @@ use super::{
     WATER_WALK_PITCH_FLOOR, WEDGE_MIN_FALL, WEDGE_STALL_RATIO, WEDGE_STILL_FRAMES,
 };
 
-/// **The trace-mask arm `0x6315f0`, as a predicate** — the liquid surface [`step`] may stand on
-/// this frame, or `None` for "the water is not geometry right now". All three of the arm's gates,
-/// in the order the reference tests them, and none of them ours:
-///
-/// - **`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.
-/// - **`!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. 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
-///   wrong** (decision 1620, the director's report from the reference client). Levitate grants
-///   three auras, and the *hover* one launches you: `SetHover(true)`'s handler `0x61a620` runs
-///   `CMovement::Jump(force = 0)` before it ever sets the flag, which clears SWIMMING and seeds an
-///   upward take-off. Water walking is then what catches the body on the way down. The gate above
-///   is real and is not the whole story, which is the shape of that mistake: a verified mechanism
-///   answering a question one layer below the one being asked.
-/// - **`mover_pitch > `[`WATER_WALK_PITCH_FLOOR`]** — `0x63161e`, strictly greater (the emitted
-///   `jne` reads ZF, so −37.0° exactly is *excluded*). Aim below it and the layers leave the mask:
-///   the surface stops being ground and the body falls through into the swim. This is the
-///   reference's own way back **into** the water while water-walking.
+/// The trace-mask arm `0x6315f0` as a predicate: the liquid surface [`step`] may stand on this
+/// frame, or `None`. Its three gates, in the reference's order:
+/// - `water_walking` (`0x631610`) ORs the two ADT liquid layers into the walk trace's class mask
+///   (`0x63162e`), which is the whole of the flag: the surface is swept geometry at its raw Z.
+/// - `!swimming` (`0x631617`): the swim trace takes the same layers as a bound above (`0x6320fe`),
+///   so the grant does not eject a swimmer, who stands on the water once the depth compare ends
+///   SWIMMING under `0.75·h − 1/36` (`0x6030c0`). Levitate still lands a swimmer on the water:
+///   the hover grant jumps the body first (`0x61a620`), clearing SWIMMING.
+/// - `mover_pitch` strictly above [`WATER_WALK_PITCH_FLOOR`] (`0x63161e`): aiming lower drops the
+///   layers and sinks the body into the swim, the reference's way back into the water.
 pub(super) fn water_floor(
     water_walking: bool,
     swimming: bool,
@@ -81,35 +34,27 @@ pub(super) fn water_floor(
         .flatten()
 }
 
-/// What the step decided — read by the move-flags / wire logic that follows it in `control`.
+/// What [`step`] decided, for the move flags and the wire that follow it in `control`.
 pub(super) struct Outcome {
-    /// Settling (post-teleport world stream-in): frozen in place, gravity off.
+    /// The settle hold while the world streams in after a teleport: frozen, gravity off.
     pub held: bool,
-    /// On walkable ground and not rising this frame.
+    /// Supported and not rising this frame.
     pub grounded: bool,
     /// A jump took off this frame.
     pub jumped: bool,
-    /// 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 (`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
-    /// speed by design.
+    /// The take-off was a knockback's, which also sets [`Self::jumped`]; the wire answers it with
+    /// `CMSG_MOVE_KNOCK_BACK_ACK` alone. `MSG_MOVE_JUMP`'s one emission site is the jump arm
+    /// (`0x615ed1`), and vmangos flags a JUMP this fast as `CHEAT_TYPE_OVERSPEED_JUMP`, the jump
+    /// check it does not exempt during a knockback (`MovementAnticheat.cpp:650`).
     pub knocked: bool,
-    /// The standstill-jump air nudge fired (re-seeds the frozen airborne direction flags).
+    /// The standstill-jump air nudge fired, which re-seeds the frozen airborne direction flags.
     pub air_nudged: bool,
-    /// The collider entity of the walkable floor supporting us — the end-of-frame snap probe's
-    /// hit when it ran, else the classify probe's. `None` airborne, held, or wedged (a wedge
-    /// rests *between* steep faces, standing on nothing walkable). The transport attach keys
-    /// off this: support on a boat's collider enters its platform frame (decision 0438 phase 2).
+    /// The walkable floor's collider: the snap's hit when it ran, else the classify's. Standing on
+    /// a transport's collider attaches the mover to its frame.
     pub ground: Option<Entity>,
 }
 
-/// Advance the player mover one frame: settle hold, ground classify, the slide, and the
-/// step-down snap. Writes `player.pos`/`vel_y`/`horiz_vel` (the settle *release* is the terrain
-/// streamer's — decision 0737).
+/// Advance the player mover one frame, writing its position and velocities.
 pub(super) fn step(
     player: &mut Player,
     time: &Time,
@@ -132,18 +77,11 @@ pub(super) fn step(
     };
     let half_h = Vec3::Y * (CAPSULE_HEIGHT * 0.5);
     let mut center = player.pos + half_h;
-    // Player body collides with terrain/doodads/GameObjects + the WMO *walking* faces (not the
-    // camera-only ones); the camera sweep uses its own filter (see `benilla_world::collision`).
     let cast = |from: Vec3, disp: Vec3| world.cast_mover(capsule, from, disp, SKIN_WIDTH);
     let probe_down = |c: Vec3, dist: f32| cast(c, Vec3::NEG_Y * dist);
 
-    // While airborne, "on the ground" means where the slide actually contacts the floor
-    // ([`LAND_PROBE`], ~skin scale). The wider walking probe would end the arc up to 0.2 yd
-    // early and close the gap with a same-frame snap — the visible pop at every silent landing
-    // (decision 0190); the fall's own collision already stops the capsule exactly at contact.
-    // A hovering body rests [`HOVER_HEIGHT`] above the floor (decision 0866), so every downward
-    // reach that decides "am I standing on something" has to grow by the same amount — otherwise
-    // the float reads as airborne and it falls, which is the hover bit doing nothing at all.
+    // Airborne, the ground reach tightens to [`LAND_PROBE`] so the arc ends where the slide meets
+    // the floor. A hovering body rests [`HOVER_HEIGHT`] up, so every ground reach grows by it.
     let hover_offset = if player.modes.hover {
         HOVER_HEIGHT
     } else {
@@ -157,84 +95,32 @@ pub(super) fn step(
     let ground_reach = hover_offset + base_reach;
     let classify = probe_down(center, ground_reach);
     let on_walkable = classify.as_ref().is_some_and(|h| h.normal1.y >= GROUND_COS);
-    // **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`), 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).
-    //
-    // Liquid is not a collider on our side — it is queried, not swept — so `probe_down` cannot see
-    // it. Asking the probe's own question against the surface plane is what puts it back in the
-    // classification. 0866 answered it only *after* the step, as a position clamp, and that is
-    // exactly what B322's lost-control bug was: with no collider under a water-walker every frame
-    // classified **airborne**, so the grounded arm's `horiz_vel = input_horiz` never ran again —
-    // and an airborne frame's horizontal is *frozen* momentum. Walk off a quay at a run and the
-    // last grounded frame's full 7 yd/s is what freezes: the body keeps running, at running speed,
-    // through every turn and through the keys being released, while the clamp reports `grounded`
-    // at the end of each frame. (The `length_squared() < 0.01` air nudge below is not even
-    // reached; it only bites for a body that arrives at a standstill.) 0866's live proof arrived
-    // by *teleport*, at rest, with no input — the one case that cannot show any of this — and 0866
-    // named the gap itself: "the water-walk walk-on case is untested headlessly".
-    //
-    // The reach is [`ground_reach`], hover offset included, because **a hovering water-walker
-    // rests a full yard above the surface** — 1611 left that an open question and it is now
-    // **VERIFIED** (decision 1616): the walk resolver's finalize down-probe `0x636e45` calls
-    // `0x632ba0`, whose trace `0x632d29` is `0x631e70` — the query whose own head is the mask arm
-    // (`0x6320a0 call 0x6315f0`, `0x6320b1` the trace). So the distance `L` that probe reports is
-    // measured to the *water*, and `0x636e74`'s hover arm then leaves the body at
-    // `pos.z_before_snap − max(L − 1.0, 0)`: exactly 1.0 yd over whatever it found, water included,
-    // with no water-specific code on either side. A classify that stopped at [`base_reach`] would
-    // call that float airborne and drop it — the same disagreement, one rung up.
-    //
-    // A negative difference — the feet already under the surface — counts as support too: that is
-    // a body penetrating solid geometry, and the resolve below pushes it back out.
+    // Water walking makes the liquid surface ground (`0x63162e`). Liquid is queried here, not
+    // swept, so the classify asks the plane too, or a water-walker reads airborne and coasts. The
+    // reach includes the hover offset: the finalize probe (`0x636e45` → `0x632ba0` → `0x631e70`)
+    // measures to the water, so hover rests a yard over it. Feet under the surface count too.
     let on_water = water_floor.is_some_and(|s| center.y - half_h.y - s <= ground_reach);
-    // Who we stand on (frame start); the end-of-frame snap probe below refreshes it post-move.
     let mut ground_entity = if on_walkable {
         classify.map(|h| h.entity)
     } else {
         None
     };
-    // Settle hold (post-teleport/summon/login): the streamed world — terrain *and* WMO building
-    // floors + their colliders — arrives over several frames, so the ground under the snap isn't
-    // there yet. While settling, `held` keeps gravity OFF and freezes us in place, so we don't
-    // fall through the not-yet-loaded city/building (the loading screen stays up too). The
-    // *release* does not live here (decision 0737): it is the terrain streamer's, keyed on the
-    // destination's residency (scene + colliders, `WorldLoadProgress`) with the timeout backstop —
-    // never on ground contact, which only the walk mover could observe and which a flyer, a
-    // swimmer, or a genuinely airborne teleport never produces (the loading-screen-until-landing
-    // hang). The streamer runs every frame in every mover mode, so every mode releases the same way.
+    // The settle hold after a teleport or login: the world streams in over several frames, so the
+    // body is frozen with gravity off. The terrain streamer releases it on the destination's
+    // residency, never on ground contact, which a flyer or a swimmer never makes.
     let held = player.settling;
-    // **Rooted: the mover is ANCHORED — nothing advances the body, in any axis** (decision 0880).
-    // `SetRoot 0x7c7340` is three acts, not one: set `0x1000`, `call 0x7c6290` **StopFalling**
-    // (`and eax,0xffff9fff` — FALLING *and* FALLINGFAR together), then wipe the direction bits
-    // (`and 0xffe07f00`) and re-run the basis recompute `0x7c5c20`, which with no direction bit left
-    // to read builds a zero horizontal velocity. With FALLING clear the mode dispatcher `0x634040`
-    // routes the next substep to the WALK resolver `0x6367b0` rather than the fall integrator
-    // `0x635b00` — **the only place gravity lives** — and the walk resolver's own head gate returns
-    // immediately when the substep's horizontal distance is under `2^-20`, so no down-probe, no
-    // step-down snap and no fall election run either. Nothing is left that could move the body.
-    //
-    // That is why a root or a stun taken **mid-air leaves you hanging exactly where it caught you**,
-    // 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.
+    // Rooted, nothing moves the body: `SetRoot` (`0x7c7340`) clears FALLING (`0x7c6290`) and the
+    // direction bits, so the dispatcher (`0x634040`) skips the fall integrator (`0x635b00`) and the
+    // walk resolver returns on a step under `2^-20`. A root caught mid-air hangs until `ClearRoot`
+    // (`0x7c7370`) starts the fall (`0x7c61c0`, which refuses while rooted, `0x7c61d6`).
     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
-    // airborne — gravity would then undo the climb and the body would dwell on the face, the exact
-    // failure 0209's atomic commit was built to make impossible. The ride is re-earned from the
-    // certification every frame it continues, so this can hold nothing up that has not just proved
-    // it can be climbed.
+    // A body part-way up a foot cone stands: the straight-down probe sees only the riser it rides,
+    // and the ride is re-certified every frame it continues.
     let on_floor =
         !held && (on_walkable || on_water || player.steep_support) && player.vel_y <= 0.0;
 
-    // The wedged rest (decision 0211) stands until real ground takes over or the support
-    // vanishes — we walked off the funnel wall into open air, which resumes a normal fresh fall.
-    // Its own reach stays [`LAND_PROBE`] (not the classify reach above), plus the hover offset so a
-    // hovering wedge is not read as having lost its support the moment the mode lands.
+    // The wedge rest holds until real ground takes over or its support goes; its reach stays
+    // [`LAND_PROBE`], plus the hover offset.
     if player.wedged
         && (on_floor || held || probe_down(center, LAND_PROBE + hover_offset).is_none())
     {
@@ -245,29 +131,17 @@ pub(super) fn step(
     let mut jumped = false;
     let mut knocked = false;
     if held || anchored {
-        // Frozen: the settle's hold (no velocity until the ground loads under us) or the root's
-        // anchor. The mover cannot tell them apart — both mean no gravity and no carried momentum.
-        // **A knockback aimed at a frozen body is dropped here**, not deferred: the latch was already
-        // consumed by the caller, and `knocked` stays false so no ack goes out — we did not fly it.
-        // The root case is the reference's own law (`CMovement::Jump` refuses under `0x1000`, and
-        // `SetRoot`'s StopFalling means nothing can enter FALLING while rooted at all — 0880), and
-        // the server will not have sent one anyway (`Unit::KnockBack` returns early on
-        // `UNIT_STATE_STUNNED | UNIT_STATE_ROOT`).
+        // Frozen by the settle hold or the root: no gravity, no momentum. A knockback here is
+        // dropped, not deferred, and `knocked` stays false so no ack goes out; the reference drops
+        // one under root too (`0x615c71`), and vmangos sends none to a rooted unit.
         player.vel_y = 0.0;
         player.horiz_vel = Vec3::ZERO;
     } else if let Some(launch) = knockback {
-        // **The knockback launch** (decision 1702) — the server aims a jump and we fly it. It is the
-        // one take-off that seeds BOTH axes at once: the vertical is not `JUMP_SPEED` and the
-        // horizontal is not our input, they are the spell's, absolute in world XY and unrelated to
-        // where we are facing or which keys are down. Everything downstream is a jump's: the arc
-        // opens (`jumped`), the horizontal is frozen momentum for its whole flight, gravity carries
-        // it, and it closes with an ordinary `MSG_MOVE_FALL_LAND` — which is also what clears the
-        // server's own knockback grace (`IsFallEndOpcode` -> `m_knockBack = false`).
-        //
-        // It takes no hover refusal and no already-falling refusal. Hover's is
-        // `CMovement::Jump(force = 1)`'s alone (`0x7c623a`, skipped by the wire's `force = 0` door —
-        // 1620), and being knocked back mid-air is exactly what a knockback is for; the server's own
-        // gate (`Unit::KnockBack`) tests stun, root and a live spline, never FALLING.
+        // The knockback: the server aims the jump and we fly it, both axes absolute in world XY
+        // whatever the facing or keys; `MSG_MOVE_FALL_LAND` ends it, and with it vmangos's
+        // knockback grace (`MovementAnticheat.cpp:698`). Hover refuses only the keyboard jump
+        // (`0x7c623a`), and
+        // vmangos's gate tests stun, root and a live spline, never FALLING (`Unit.cpp:10192`).
         player.vel_y = launch.y;
         player.launch_vz = launch.y;
         player.horiz_vel = Vec3::new(launch.x, 0.0, launch.z);
@@ -275,64 +149,37 @@ pub(super) fn step(
         player.steep_support = false;
         jumped = true;
         knocked = true;
-        // **The launch plants the direction nibble, and that is what freezes the arc** — the
-        // reference's `0x617a18 or edx,0x8001` sets FORWARD and clears BACKWARD as part of the
-        // apply (decision 1740). It is set regardless of `xy_speed`, so a purely vertical knockback
-        // is just as unsteerable as a 25 yd/s one; reading the freeze off the *velocity* instead
-        // (what we did until 1740) let that case steer from the second frame. `knock_arc` also
-        // rides the wire for the arc's length, which is the half we were not sending at all.
+        // The launch plants FORWARD in the direction nibble (`0x617a18`) whatever its speed, so
+        // even a vertical knockback never steers, and `knock_arc` keeps FORWARD on the wire.
         player.arc_dirs_set = true;
         player.knock_arc = true;
     } else if grounded {
         player.vel_y = 0.0;
-        // **HOVER refuses the jump** — the FIRST test in `CMovement::Jump 0x7c6230`
-        // (`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
-        // latch, no cooldown. The mounted flourish is deliberately NOT gated on hover —
-        // `0x60dea0` diverts to MountSpecial before the command ever reaches this handler
-        // (`player::control`'s flourish block runs upstream of this call, same order).
-        // …and `wire_jump` is the leg that is NOT refused: the reference's own `Jump(force = 0)`
-        // skips the test above (`0x7c6236 test eax,eax; je 0x7c6243`) so a `SetHover(true)` can
-        // launch a body that is already hovering (decision 1620). Same seed select, same commit —
-        // it is the *same* jump, entered through the door the wire is given.
+        // Hover refuses the keyboard jump silently, the first test in `CMovement::Jump`
+        // (`0x7c623a`): the key's replay passes `Jump(1)` (`0x615eba`) and drops a refusal
+        // (`0x615ec5`), so no `MSG_MOVE_JUMP` and no retry. `wire_jump` is `Jump(0)`, which skips
+        // the test (`0x7c6236`), so a hover grant can launch the hovering body. The mount flourish
+        // is diverted upstream in `control` (`0x60dea0`), so hover does not gate it.
         if (want_jump && !player.modes.hover) || wire_jump {
             player.vel_y = JUMP_SPEED;
             player.launch_vz = JUMP_SPEED;
             player.wedged = false;
             player.steep_support = false;
             jumped = true;
-            // The arc's nibble starts as the keys are: a jump taken with a direction held is
-            // locked to its momentum, a jump from a standstill has one steer in hand (1740).
+            // A moving jump is locked to its momentum; a standing one may steer once.
             player.arc_dirs_set = moving;
         }
     } else if !player.airborne_prev {
-        // **A step-off — the arc nobody launched.** The walk election calls `StartFalling(0)`, so
-        // the launch speed is exactly 0 (not the gravity-polluted first tick), which is what the
-        // wire tail sends and what splits the FALLINGFAR legs (0179). The nibble seeds from the
-        // keys like any other take-off: you walked off this ledge, so you keep your momentum.
+        // A step-off: `StartFalling(0)` launches at exactly 0, which the wire tail sends and the
+        // FALLINGFAR legs split on; the nibble seeds from the keys.
         player.launch_vz = 0.0;
         player.arc_dirs_set = moving;
     }
 
-    // **The fall step, for every airborne frame INCLUDING the take-off's** (decision 1740). It used
-    // to sit inside the `else` above, which meant a launch frame moved a whole `v₀·dt` with no
-    // gravity at all while every later frame moved at its END-of-step speed — one overshoot
-    // followed by a systematic undershoot. The reference has no such seam: `StartFalling` anchors
-    // the arc and the closed form is evaluated from `t = 0`, the launch frame included.
-    //
-    // **Feather fall is a terminal-velocity substitution, and nothing else** (decision 0866). The
-    // reference's fall-velocity query `0x7c5d20` picks the clamp from one flag test
-    // (`0x7c5d23 test [ecx+0x40], 0x20000000`) — the ordinary 60.148 or 7.0 under
-    // `MOVEFLAG_SAFE_FALL`. Gravity itself is unchanged, so a Slow Fall still *accelerates*
-    // normally for the first ~0.36 s and only then rides the cap: the drop starts like any other
-    // and settles into a drift, which is what Slow Fall looks like.
-    //
-    // `player.vel_y` keeps the END-of-step speed (the state the next frame and the wire read);
-    // `fall_mean_vy` is what this frame actually MOVES at, and for constant acceleration the mean
-    // is exact — see [`fall_step`].
+    // The fall step runs on every airborne frame, the take-off's included: the reference evaluates
+    // its arc in closed form from `t = 0` at `StartFalling`. Feather fall swaps only the terminal
+    // speed (`0x7c5d20`). `vel_y` keeps the end-of-step speed that the next frame and the wire
+    // read; `fall_mean_vy` is the exact rate to move at ([`fall_step`]).
     let mut fall_mean_vy = player.vel_y;
     if !held && !anchored && (jumped || !grounded) {
         let terminal = if player.modes.feather_fall {
@@ -345,49 +192,24 @@ pub(super) fn step(
         fall_mean_vy = mean_vy;
     }
     let mut air_nudged = false;
-    // The anchor owns the horizontal too — the wipe leaves the basis recompute nothing to build a
-    // velocity from, so a body rooted mid-jump stops dead in the air instead of coasting on its
-    // frozen takeoff momentum. (Both arms below are already inert under a root — the caller zeroes
-    // `dir`, so `moving` is false and `input_horiz` is zero — but the anchor says it itself rather
-    // than inheriting it from a gate three functions away.)
+    // The `!anchored` terms keep a body rooted mid-jump stopped dead instead of coasting.
     if knocked {
-        // The launch owns both axes — a knockback fired from standing ground is still `grounded`
-        // this frame, and the walk arm below would hand our momentum straight back to the keys.
+        // The launch owns both axes: a knockback from standing is still `grounded` this frame, and
+        // the walk arm would hand the horizontal back to the keys.
     } else if grounded && !anchored {
         player.horiz_vel = input_horiz;
     } else if !held && !anchored && moving && !player.arc_dirs_set {
-        // Air control: one nudge to steer a jump that took off from a standstill (a moving jump
-        // keeps its momentum locked, because its nibble was already set at take-off). The pressed
-        // 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). `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
-        // question from "is my horizontal velocity ~zero". The two answers diverge on one input:
-        // a knockback launch plants FORWARD itself (`0x6179c0`'s `0x617a18 or edx,0x8001`), so on
-        // the reference an `xy_speed ≈ 0` knockback is STILL unsteerable, while here `knocked` is
-        // launch-frame-only and this guard sees a zero velocity and grants the nudge from frame 2.
-        // Fixing it means carrying the nibble as arc state and seeding it at the launch — 1736
-        // §Plan, deliberately not done in the round that found it.
-        //
-        // [`super::AIR_NUDGE_SPEED`] is likewise the right number for the wrong reason: the
-        // reference takes `min(MOVE_WALK, MOVE_RUN)` from the unit's live speeds (`0x7c4c90(1)`'s
-        // walk override), and 2.5 is merely the DEFAULT `MOVE_WALK` — so it is now the fallback
-        // `nudge_speed` the caller passes when the server has told us no speeds yet, not the law.
+        // Air control: one nudge for a jump taken standing, re-seeding the airborne direction
+        // flags. The reference opens it only while the direction nibble (`+0x40 & 0xf`) is clear
+        // (`0x7c6afc`, guarding the `arg = 1` openers of `0x7c5a20`/`0x7c5c20`); `nudge_speed` is
+        // the live `min(walk, run)` (`0x7c4c90(1)`).
         player.horiz_vel = dir.normalize_or_zero() * nudge_speed;
         air_nudged = true;
-        // The press sets the nibble, which is what makes this one-shot on the reference: the next
-        // press finds `+0x40 & 0xf` non-zero, `arg = 0` goes to the basis rebuild, and the bail
-        // fires. No second steer, and no drifting back toward the keys.
+        // The press sets the nibble, so there is no second steer.
         player.arc_dirs_set = true;
     }
 
     let pre_move = center;
-    // The grounded walk is the SHARED resolve ([`grounded_step`]) — step-up, slide, election
-    // snap — the same code every remote mover's dead-reckon runs. Held and airborne/jumping
-    // frames keep their own slide here: no step-up, no snap, and gravity in the velocity.
     let (mut climb, mut snap_probe) = (None, None);
     if !held && !anchored && grounded && !jumped {
         let g = grounded_step(
@@ -403,13 +225,9 @@ pub(super) fn step(
                 steep: player.steep_support,
             },
         );
-        // The step-up probe (this is the LOCAL mover; a remote's dead-reckon is not a report
-        // anyone is looking at): a walk frame that went nowhere writes the `stup` deep report —
-        // the surface profile ahead, the advance ladder, the candidate faces.
-        // **The local controller is the caller that HAS a fall** (decision 2174), so the no-floor
-        // drop is spent here: `pos.z -= achieved` before the classify, exactly as `0x636e45` does,
-        // and the frame that leaves a ledge starts its fall lower instead of flat. The two
-        // open-loop callers decline it — they have nothing that would ever end it.
+        // Only this mover has a fall to elect, so it spends the no-floor drop (`pos.z -= achieved`
+        // at `0x636e52`) and a ledge's first fall frame starts lower. A walk frame that went
+        // nowhere writes the `stup` report ([`super::step_probe`]).
         let resolved = g.center - Vec3::Y * g.unsupported.unwrap_or(0.0);
         super::step_probe::watch(
             world,
@@ -428,28 +246,17 @@ pub(super) fn step(
             ground_entity = Some(e);
         }
     } else {
-        // Held or anchored: zero velocity (no move) — both already zeroed the two terms, but say it
-        // outright. Jumping/airborne: gravity carries the arc.
         let velocity = if held || anchored {
             Vec3::ZERO
         } else {
-            // `fall_mean_vy`, not `player.vel_y` — the exact displacement rate for this step.
             player.horiz_vel + Vec3::Y * fall_mean_vy
         };
-        // The airborne slide is the OTHER shared resolve ([`airborne_step`]) — the same code a
-        // remote mover's arc runs, so a jump meets our walls whoever is jumping (decision 0627).
         center = airborne_step(world, capsule, center, velocity, time.delta());
-        // Nothing here can be riding a cone: this arm is the arc, the hold and the anchor.
         player.steep_support = false;
     }
-    // Wedge-rest detection (decisions 0211/0212): airborne, already falling fast, yet the
-    // descent achieved is a sliver of what gravity intended — [`WEDGE_STILL_FRAMES`] in a row
-    // is a capsule held between steep faces (a ball in a V-groove; the trunk-base funnel's
-    // walls lean, n.y ≈ +0.2, so there is no downward exit). Land it. Free fall achieves ~100%
-    // of its intent and a steep-slope slide ≥75%, and a jump apex is slower than
-    // [`WEDGE_MIN_FALL`], so neither can trip this; measuring against the intent (which keeps
-    // growing) catches the funnel's pinch-in as it happens — 0211's absolute-stillness test
-    // waited out the decelerating millimeter creep, a visible hang in the falling pose.
+    // The wedge rest: falling, yet achieving under [`WEDGE_STALL_RATIO`] of gravity's intent for
+    // [`WEDGE_STILL_FRAMES`] frames, is a capsule pinched between steep faces with no way down
+    // (a tree trunk's funnel), so it lands there.
     if !held
         && !anchored
         && !grounded
@@ -474,44 +281,17 @@ pub(super) fn step(
     } else {
         player.wedge_still = 0;
     }
-    // The frame that detects the wedge reports grounded immediately, so the falling pose ends
-    // and the wire sees a normal landing (`MSG_MOVE_FALL_LAND`) this frame, not next.
+    // The detecting frame is grounded, so the landing (`MSG_MOVE_FALL_LAND`) goes out this frame.
     let mut grounded = grounded || player.wedged;
 
-    // **The water floor, resolved** — the second half of the `on_water` classify above. It runs
-    // after the slide because the slide and the fall are what can carry the feet through: a body
-    // dropping onto the water crosses more than [`LAND_PROBE`] in a frame, so the landing frame
-    // classifies airborne, falls, and is caught here — exactly how a collider landing resolves.
-    //
-    // Two halves, and they are the reference's two, in its order. **Down** is `0x636e52`'s snap as
-    // corrected by `0x636e74`'s hover arm — `pos.z_final = pos.z_before_snap − max(L − 1.0, 0)`,
-    // i.e. descend only far enough to leave the hover clearance, and not at all when the floor is
-    // nearer than that. **Up** is never here: a rise is the rate-limited second pass just below
-    // (`0x636fa1`), so a hover granted over water floats up over ~0.14 s instead of popping. The
-    // one exception is **depenetration** — the body may not *end* the frame under the surface,
-    // which is not a rule of the reference's but a consequence of it not needing one: over there
-    // the surface is a swept solid and the sweep never lets the body through in the first place.
-    //
-    // The down half stands aside for a walkable collider: a pier deck three yards over the lake is
-    // the nearer floor, and in the reference both are hits in the same trace with the nearest
-    // winning. Depenetration stands aside for exactly one thing — **a body that is rising**. It is
-    // a floor, and a floor catches what falls onto it, never what is on its way up through it; the
-    // reference needs no such clause because over there the surface is a swept solid and the sweep
-    // is directional for free. Ours is a post-hoc push-out, and without the gate it would swallow
-    // the very launch a hover grant just seeded (decision 1620): cast Levitate a foot under the
-    // waterline and the `SWIM_JUMP_SPEED` take-off would be clamped flat to the surface with its
-    // velocity zeroed, a pop where the reference throws you clear. With `vel_y <= 0` it is still
-    // the water-walk *lift* it was built to be — wade in chest-deep, aura up, and this is the frame
-    // that puts you on top of the water, because a wader stands at rest.
-    //
-    // **Why there is no second kick for the standstill dive.** `SetPitch 0x7c6f70` fires an
-    // explicit zero-velocity `StartFalling` when a *standing*, non-falling water-walker aims below
-    // −37° (`0x7c6fb3`–`0x7c6fd3`), which reads like a mechanism we are missing. It is the
-    // reference compensating for its own walk resolver: `0x6367b0` early-returns when the substep's
-    // horizontal distance is under `2^-20`, so a body at rest never re-runs the ground query and
-    // would not notice the mask change until it moved. Our classify runs every frame in every
-    // state, so dropping the liquid layers is already the whole of the dive, standing or running.
-    // Building the kick as well would be a second path to the same fall.
+    // The water floor, after the slide: a body landing on water crosses more than [`LAND_PROBE`]
+    // in a frame. Down is the reference's snap with its hover arm, `z − max(L − 1, 0)`
+    // (`0x636e52`, `0x636e74`), yielding to a walkable collider, the nearer floor; up is the
+    // rate-limited climb below (`0x636fa1`). The one push up is ours: the body may not end the
+    // frame under the surface, which the reference's swept surface never lets it reach, and only
+    // a body that is not rising is caught, so a hover launch under the waterline flies clear.
+    // `SetPitch`'s standstill dive kick (`0x7c6f70`) is not built: it serves a walk resolver that
+    // skips a body at rest, and our classify runs every frame, so dropping the layers is the dive.
     if let Some(surface) = water_floor {
         let feet = center.y - half_h.y;
         let rest = surface + hover_offset;
@@ -528,16 +308,8 @@ pub(super) fn step(
         }
     }
 
-    // **The hover climb** (decision 0872): the snap above can only lower the body, so the *rise* to
-    // the 1.0-yd clearance is this separate rate-limited pass — the reference's second writer at
-    // `0x636fa1`–`0x6370f1`, which climbs toward the same clearance at [`HOVER_CLIMB_RATE`]. Without
-    // it the grant reads as an instant pop; with it the body floats up over ~0.14 s.
-    // (…and never while anchored: the climb is the walk resolver's own second pass, so the rooted
-    // mover's stationary early-return skips it exactly like the snap above.)
-    //
-    // The water is one more floor to hover over (decision 1616) and the only one `probe_down`
-    // cannot see, so it is measured against the plane and folded in as a candidate — nearest wins,
-    // which is what the reference's single trace does for free.
+    // The hover climb, the walk resolver's second pass (`0x636fa1`-`0x6370f1`), which a root's
+    // early return skips too. The water is one more floor under it, nearest wins.
     if hover_offset > 0.0 && !held && !anchored {
         let solid = probe_down(center, HOVER_HEIGHT + CAPSULE_HEIGHT).map(|h| h.distance);
         let water = water_floor.map(|s| (center.y - half_h.y - s).max(0.0));
@@ -563,13 +335,8 @@ pub(super) fn step(
         anchored,
     });
 
-    // The mover's own airborne record for the next step's arc-start test — see
-    // [`Player::airborne_prev`]. Held and anchored bodies are not airborne: the anchor ends the arc
-    // (0880) and the settle hold has no arc at all.
-    // `jumped ||`, not just `!grounded`: a launch frame IS the arc's first airborne frame even
-    // though the body is still standing on the floor it pushed off. Without that, the frame after a
-    // jump looks like a fresh step-off and re-seeds the arc state the launch just set — which is
-    // exactly how a standstill jump lost the one steer it is owed.
+    // The mover's own airborne record: a launch frame counts though the body still stands, or the
+    // next frame reads as a fresh step-off and re-seeds the arc.
     player.airborne_prev = !held && !anchored && (jumped || !grounded);
     Outcome {
         held,
@@ -585,45 +352,26 @@ pub(super) fn step(
     }
 }
 
-/// **What already holds the body up, entering the frame** — the two facts [`grounded_step`] cannot
-/// work out for itself, because both are carried from the *previous* frame's resolve.
-///
-/// They travel together because they are the same question asked twice: how far below the feet does
-/// "the ground" start, and does the thing under us count as a floor at all.
+/// The body facts [`grounded_step`] cannot work out for itself, passed in by its caller.
 #[derive(Clone, Copy)]
 pub(crate) struct Support {
-    /// **The mover's rise budget** — the reference's `H` (`0x617430`): how high the atomic step-up
-    /// may lift the body, and the yardstick of its certify reach (`H·tan50°`). [`STEP_UP_HEIGHT`]
-    /// for a player body — our own, and every watched one — and
-    /// [`super::CREATURE_STEP_UP_HEIGHT`] for a creature the server walks (decision 1125 has the
-    /// byte split: `0x5fa550`'s FALSE leg reads the constant `2.0`).
+    /// The rise budget, the reference's `H` (`0x617430`), which also scales the certify reach:
+    /// [`STEP_UP_HEIGHT`] for a player body, [`super::CREATURE_STEP_UP_HEIGHT`] for a creature
+    /// (`0x5fa550`'s false leg).
     pub(crate) rise: f32,
-    /// The body rests this far **above** the surface — HOVER's float (decision 0866),
-    /// [`super::HOVER_HEIGHT`] while the mode is up and `0.0` for everyone else, which is the
-    /// ordinary case.
+    /// How far above the floor the body rests: [`super::HOVER_HEIGHT`] while hovering, else 0.
     pub(crate) offset: f32,
-    /// **The liquid surface that counts as floor this frame** (Bevy Y), or `None` when the water is
-    /// not geometry — [`super::mover::water_floor`]'s answer, threaded down because the election
-    /// snap has to see it and cannot.
-    ///
-    /// Liquid is queried on our side, never swept, so `cast_body` is blind to it. The reference has
-    /// no such split: `MOVEFLAG_WATERWALKING` ORs the two ADT liquid layers into the walk trace's
-    /// class mask (`0x63162e or edi, 0x30000`), so the one trace that finds terrain finds the water
-    /// too and the election is over a single candidate set. Ours needs the plane handed in, and
-    /// **this is the third site that needed it** — 1611 put it in the classify, 1616 in the hover
-    /// climb, and the snap kept its own blindness until 1623 (B322). The shared shape of all three:
-    /// every question of the form "is there ground below me?" has to ask the plane as well as the
-    /// sweep, or the two disagree and the body oscillates between their answers.
+    /// The liquid floor this frame (Bevy Y), [`water_floor`]'s answer. Liquid is queried, not
+    /// swept, so every ground question asks this plane as well as the sweep, where the reference's
+    /// one masked trace sees both (`0x63162e`).
     pub(crate) water: Option<f32>,
-    /// The support entering the frame is a **certified steep contact**, not a walkable floor — the
-    /// reference's `0x4000000` (decision 1125). It is the sole gate on the step-down probe's deep
-    /// reach; see the reach in [`grounded_step`].
+    /// The support entering the frame is a certified steep contact, the reference's `0x4000000`,
+    /// which opens the step-down's deep reach.
     pub(crate) steep: bool,
 }
 
 impl Default for Support {
-    /// A player body on an ordinary frame: no hover, no liquid floor, a walkable support, and the
-    /// player's own rise budget.
+    /// A player body on an ordinary frame.
     fn default() -> Self {
         Self {
             rise: STEP_UP_HEIGHT,
@@ -634,61 +382,31 @@ impl Default for Support {
     }
 }
 
-/// What one grounded walk step resolved against the world came out as ([`grounded_step`]).
+/// What one [`grounded_step`] resolved.
 pub(crate) struct GroundedStep {
     /// The resolved capsule centre.
     pub(crate) center: Vec3,
-    /// The collider of the walkable floor the election snap settled onto, when it ran and hit one.
-    /// `None` means "keep whatever the caller already believed" — a step-up commit and a missed
-    /// snap both leave the support unchanged.
+    /// The walkable floor's collider the snap settled onto; `None` keeps what the caller believed.
     pub(crate) ground: Option<Entity>,
-    /// The height gain (yd) this frame's climb achieved — the atomic step-up's committed rise, or
-    /// the distance a foot-cone ride carried the body up its skirt.
+    /// The height (yd) this frame's pop or cone ride gained.
     pub(crate) climb: Option<f32>,
-    /// The body is **supported by a certified steep contact** rather than standing on a walkable
-    /// floor — climbing a foot-cone ride (1123) or following a surface down off a ledge (1127) —
-    /// so the caller must keep treating it as grounded until a walkable floor takes over. This is
-    /// the reference's `0x4000000` (decision 1125). `false` for an ordinary frame.
+    /// On a certified steep contact, the reference's `0x4000000`: riding a cone up, or following a
+    /// surface down off a ledge. The caller keeps it grounded until a walkable floor takes over.
     pub(crate) steep_support: bool,
-    /// The election snap's `(probe reach, what it found)` — trace fodder, `None` when the step-up
-    /// took the frame instead. The inner pair is `(hit distance, hit normal.y)`.
+    /// For the trace: the snap's reach and the `(distance, normal.y)` it found.
     pub(crate) snap: Option<(f32, Option<(f32, f32)>)>,
-    /// **The fall's opening drop, when the election found NO floor at all** — `Some(yd)` iff the
-    /// probe came back empty and the body is not mid-ride, `None` on every frame a surface was
-    /// found (including a step-up commit and a mid-ledge steep support, which both leave
-    /// [`Self::ground`] `None` for their own reasons and must not be confused with this).
-    ///
-    /// It is **not applied to [`Self::center`]** (decision 2174). The reference's finalize does
-    /// write `pos.z -= achieved` on its no-hit leg — and then *classifies*, electing a fall that
-    /// gravity finishes and a landing ends. That election is the **caller's**, and only one of this
-    /// function's three callers has one: the local controller ([`step`]) applies this drop and
-    /// falls. The creature ground clamp and the remote dead-reckon have no fall to elect and sweep
-    /// again next frame from their own answer, so for them the drop is not an opening — it is a
-    /// ratchet with no floor to end it, and it walked Stormwind's patrolling guards 31 yd down
-    /// through the world while their colliders were still streaming in. They read this as "our
-    /// world could not answer" and hold the server's pose instead, which is the law their idle
-    /// paths already obey ([`crate::net::motion::spline::grounded_y`]).
+    /// The no-floor drop, when the snap found nothing and no ride is in progress; not in
+    /// [`Self::center`]. The reference drops by it, then elects a fall (`0x636e52`), so only
+    /// [`step`], which has a fall to elect, spends it. The open-loop creature and remote callers
+    /// hold the server's pose instead, since spending it would ratchet them down through the world.
     pub(crate) unsupported: Option<f32>,
 }
 
-/// **One grounded walk step, resolved against the world** — step-up → slide → election snap, from
-/// a capsule centre and this frame's horizontal velocity. The single place a walking body meets the
-/// terrain, and deliberately so: the reference drives **every** mover through one controller (0059's
-/// byte trail — `0x616620` integrates any mover; the local-player GUID compare at `0x6166a9` gates
-/// only a timing budget; the grounded fork zeroes the vertical and commits through the swept world
-/// query `0x633840` + the WALK resolver `0x6367b0`, which reads Z off the surface). So does benilla:
-/// the local controller ([`step`]) calls this for its grounded frames, and every **remote** mover's
-/// dead-reckon calls it for its extrapolated step ([`crate::net::motion::remote`]).
-///
-/// Why a remote needs it at all: dead-reckoning between packets is *our invention*, and an invention
-/// that ignores the world walks a watched player into a hillside (they sink in, then the next packet
-/// pops them out) and leaves their height wherever the last packet put it while the ground under them
-/// rises or falls (they sink or float, and the height arrives as a 2 Hz snap). Both are one defect —
-/// the extrapolator never touched the world — and both are gone the moment the step is resolved
-/// through here.
-///
-/// Airborne and swimming frames are **not** this function's: a jump is a ballistic arc and a
-/// swimmer's Z is its depth, exactly as the reference's grounded fork excludes both.
+/// One grounded walk step against the world: step-up, slide, then the step-down snap. The
+/// reference runs every mover through one controller (`0x616620`, whose local-player compare at
+/// `0x6166a9` gates only a timing budget) and reads a grounded mover's Z off the surface
+/// (`0x633840`, `0x6367b0`), so our mover, the remote dead-reckon and the creature path clamp all
+/// walk through here; airborne and swimming frames do not.
 pub(crate) fn grounded_step(
     world: &benilla_world::collision::WorldCollision<'_, '_>,
     capsule: &Collider,
@@ -700,21 +418,10 @@ pub(crate) fn grounded_step(
     let surface_offset = support.offset;
     let cast = |from: Vec3, disp: Vec3| world.cast_mover(capsule, from, disp, SKIN_WIDTH);
     let speed = horiz_vel.length();
-    // The step-up (decision 0209): ATOMIC — a steep face in the way triggers rise →
-    // advance-this-frame's-travel-at-the-raised-height → settle onto a walkable floor, all
-    // committed inside this one frame, or nothing happens and the plain slide runs. There is
-    // no in-between state to be seen wedged or bouncing in (the 0191 ride dwelled mid-face;
-    // every stuck/bounce report of the step-up era was that dwelling). Grazing a face nets
-    // back onto the same floor (reads as sliding); a square push onto a low step lands on its
-    // top; anything taller than [`STEP_UP_HEIGHT`] never commits.
     let attempt = if speed > 1.0e-6 {
         let travel = speed * dt.as_secs_f32();
-        // The look-ahead is this frame's travel — "is there a steep face in my way *now*" is a
-        // question about this frame. The **advance** is not: how far forward the maneuver must
-        // reach to see the tread it would stand on is a property of the body, so it is at least
-        // [`STEP_UP_ADVANCE`] whatever the frame rate or the gait (decision 1121). Travel still
-        // wins when it is longer, so a very low frame rate never steps you less far than you asked
-        // to walk.
+        // The look-ahead is this frame's travel; the advance is the body's certify reach,
+        // `rise · tan 50°`, or the travel when a long frame covers more.
         step_up(
             &cast,
             center,
@@ -729,11 +436,6 @@ pub(crate) fn grounded_step(
             verdict: StepVerdict::NoFace,
         }
     };
-    // The certify trace (`WOW_MOVE_TRACE`, tag `step`): one line per attempt with every probe
-    // number and the world-space contact, so a feel report pins to the exact placement and probe —
-    // the instrument that broke the fence/tree cases, which reasoning alone could not. (The
-    // *blocked-frame* deep report — the advance ladder and the surface profile — is the `stup` tag
-    // in [`super::step_probe`], which the local mover fires when a walk frame goes nowhere.)
     if let Some((point, n)) = attempt.contact {
         if benilla_assets::trace::enabled_for("step") {
             let feet_y = center.y - CAPSULE_HEIGHT * 0.5;
@@ -753,28 +455,11 @@ pub(crate) fn grounded_step(
             );
         }
     }
-    // **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
-    // never meets a wall to be lifted over: it meets the slanted skirt, and the ordinary slide
-    // carries the body up it. Only an edge that clears the cone meets the box square, and that square
-    // meeting is the instant step-up. One law, two outcomes:
-    //   - edge inside the cone ⇒ **ride** the skirt at atan 1.8494 ≈ 61.6°, over as many frames as
-    //     the gait needs — smooth, and never a teleport;
-    //   - edge above the cone ⇒ the atomic pop of 0209, unchanged;
-    //   - no certification at all ⇒ neither: the plain slide, and the body never rises.
-    //
-    // **The certification is the gate, not the height** — a tall wall's contact against a *capsule*
-    // sits at the hemisphere centre, ≈0.33 yd up and squarely inside the band, so height alone would
-    // ride a cliff. Only "the settle found a walkable floor" separates the two.
-    //
-    // 1123 selected on the certified *rise* instead, which was indistinguishable while the advance was
-    // one body radius and became wrong the moment 1126 lengthened it: the rise then measures how high
-    // the ground is a yard further on, not how tall the thing in front of you is. Booty Bay's 0.40 yd
-    // step onto a rising ramp reads as a 0.755 yd obstacle under that rule and teleports; its blocking
-    // edge is 0.40 and rides. The edge is the quantity the reference's own cone band tests, and unlike
-    // the rise it does not move when the probe reaches further.
+    // The regime (`0x631be0`, `0x635c00`): the reference's solid is a cone below
+    // [`FOOT_CONE_HEIGHT`] and a box above it, so a certified obstacle whose blocking edge sits
+    // inside the cone is ridden up the 61.6° skirt, and one above it pops. The certification is
+    // the gate, since a wall's capsule contact also sits in the band; and the edge is measured,
+    // not the certified rise, which grows with the advance.
     let ride_to = match (attempt.verdict, attempt.contact) {
         (StepVerdict::Commit { landed, .. }, Some((p, _)))
             if p.y - (center.y - CAPSULE_HEIGHT * 0.5) <= FOOT_CONE_HEIGHT =>
@@ -783,30 +468,11 @@ pub(crate) fn grounded_step(
         }
         _ => None,
     };
-    // **The pop is a RISE, not a jump forward** (decision 1130). 0209 committed the whole maneuver as
-    // one position — rise, advance the probe's full [`STEP_UP_ADVANCE`], and land on the floor the
-    // probe found — which put a **1.19 yd horizontal teleport** in every step-up: ten frames' worth
-    // 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:
-    //   - `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
-    //     frame's **total horizontal is bounded by its own substep budget** — `dx = 1.19` where a
-    //     walking frame is 0.117 cannot arise on this path at all;
-    //   - all seven position writes in `[0x6367b0, 0x637140)` are **relative**. There is no absolute
-    //     snap anywhere in the walk resolver, so landing the body *on* a probe's floor was wrong in
-    //     kind and not merely in magnitude;
-    //   - what the certified arm commits is a free vertical segment of `H` (`0x635d5b` — the response
-    //     is always `(0,0,s)`), after which `0x63694d` restores **the caller's own heading** with the
-    //     budget that is left.
-    //
-    // So: rise in place, then let the ordinary slide and the ordinary settle below own the frame,
-    // exactly as they do on flat ground. The settle cannot strand the body up there — the reference
-    // sets `0x4000000` *before* computing the settle's reach and only clears it *after*
-    // (`0x636edf`, inside the settle), so the probe is always at least `H + 1/36` and always reaches
-    // back past the height just gained: it finds the obstacle's top, or the ground we left.
+    // The pop is a rise in place, never a lunge: the reference's certify distance is only a sweep
+    // length (`ebx` at `0x636193`, fed to `0x632ba0` alone), its walk resolver writes position
+    // only relatively (`0x6367b0`-`0x637140`), and the certified arm rises `(0, 0, H)`
+    // (`0x635d5b`) before `0x63694d` resumes the heading. The snap then reaches past the rise, as
+    // the reference keeps `0x4000000` set until its settle has sized the probe (`0x636edf`).
     let popped = match attempt.verdict {
         StepVerdict::Commit { up, .. } if ride_to.is_none() => Some(up),
         _ => None,
@@ -824,11 +490,8 @@ pub(crate) fn grounded_step(
                 *hit.velocity = ride;
                 return MoveAndSlideHitResponse::Accept;
             }
-            // The foot cone's skirt, on a certified low edge only. The ceiling is the
-            // certification's own landing: once the body is that high the obstacle is cleared, so
-            // the skirt has nothing left to ride and any further contact is an ordinary wall. Any
-            // overshoot inside a sub-step is taken back out by the election snap below, which only
-            // ever descends onto a walkable floor.
+            // The skirt, on a certified low edge only, up to the certification's landing height;
+            // the snap takes back any overshoot.
             if ride_to.is_some_and(|ceiling| hit.position.y < ceiling) {
                 if let Some(up) = foot_cone_ride(**hit.normal, *hit.velocity) {
                     *hit.velocity = up;
@@ -843,38 +506,10 @@ 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`): 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): `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
-    // `StartFalling(0)` election) — a short ledge drop reads as a quick, continuous, steep descent,
-    // which is what the director's eye confirmed against the reference (decision 0190; 0189's
-    // instant absorbed step read as a teleport and was reverted). At 2.028 yd we were absorbing
-    // nearly two body-heights of ledge in one frame, which is the same teleport by another route.
-    //
-    // Standing still the reach collapses to the slack alone, so an idle body is re-grounded only
-    // when it is genuinely resting on the floor; a body left floating above one falls the float and
-    // lands, rather than being pulled down through up to two yards of air.
-    //
-    // [`Support::offset`] is HOVER (decision 0866): the reference's WALK resolver `0x6367b0` adds
-    // `[0x7ff9d8]` = 1.0 to this same surface offset while `MOVEFLAG_HOVER` is set, and widens the
-    // step-down reach by the same yard (`0x633e35`) so the float still follows the ground down.
-    // Both halves are here: the reach grows by the offset, and the snap stops that far short of the
-    // floor. Zero for everyone not hovering, which is the ordinary case and unchanged.
+    // The step-down snap, the reference's step-vs-fall election (`0x6367b0`): it reaches
+    // `travel · slope + slack` below, plus `H` on a steep support (`0x636dfc`) or a pop, plus the
+    // hover offset (`0x633e35`), and settles only onto a walkable floor. A deeper drop is a fall,
+    // and a body at rest reaches only the slack, so it falls instead of being pulled down.
     let d = slid - start;
     let reach = d.x.hypot(d.z) * STEP_SLOPE_RATIO
         + STEP_SNAP_SLACK
@@ -885,12 +520,8 @@ pub(crate) fn grounded_step(
         }
         + surface_offset;
     let hit = cast(slid, Vec3::NEG_Y * reach);
-    // **The water is one more candidate in the same election** ([`Support::water`], decision 1623).
-    // The sweep above cannot see liquid, so the plane is measured against the same probe: feet to
-    // surface, in sight only within the same `reach`, and flat (`normal.y = 1.0`) because a liquid
-    // surface always is. Nearest wins — which is what the reference's single masked trace does for
-    // free. No entity: the water is not a collider, and `GroundedStep::ground`'s `None` already
-    // means "keep whatever the caller believed", which is exactly right for standing on a lake.
+    // The water is one more candidate within the same reach, flat, nearest wins, as in the
+    // reference's one masked trace; with no entity it keeps the caller's support.
     let water = support.water.and_then(|s| {
         let d = slid.y - CAPSULE_HEIGHT * 0.5 - s;
         (d <= reach).then_some(d.max(0.0))
@@ -904,115 +535,45 @@ pub(crate) fn grounded_step(
     let snap = Some((reach, floor.map(|(d, n, _)| (d, n))));
     let mut ground = None;
     let mut steep_support = false;
-    // The no-floor drop, measured here and spent by whoever has a fall to elect (see the field).
     let mut unsupported = None;
-    // **A ride's height is earned; the snap follows ground *down*, it never undoes a climb.**
-    //
-    // This is where our capsule and the reference's cone part company, and it has to be said out
-    // loud or the ride only works on bevels. Mid-ride the real client's foot cone is *resting on
-    // the very edge it is climbing* — its skirt is in contact, so its down-probe is blocked at zero
-    // and there is nothing to settle to. A capsule against a **vertical** riser touches it side-on
-    // and hangs clear of everything below, so the same down-probe sees the floor it is climbing
-    // away from, a full ride's height beneath it, and yanks it straight back down — every frame,
-    // forever. Booty Bay's 0.40 yd step is exactly that: certified `COMMIT dy=+0.439` on every
-    // frame, and stalled at +0.020.
-    //
-    // So while a ride is in progress the only floor that may end it is one **higher than the ride
-    // began on** — the tread it is certified to be climbing to. A floor at or below the start is
-    // the ground being left behind, and it gets no say.
-    // The height this frame's ride earned, read before the snap can spend any of it. (The two snap
-    // arms below are mutually exclusive — walkable or steep — so one value serves both.)
+    // A ride's height is earned. The reference's cone rests on the edge it climbs, but our capsule
+    // hangs clear of a vertical riser and the snap would find the floor it is leaving, so mid-ride
+    // only a floor above the ride's start may end it.
     let ride_rise = (slid.y - start.y).max(0.0);
-    // **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 (`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
-    // past the edge — then gravity took over. The director's capture is unambiguous: one frame of
-    // `dy=+0.000 dx=0.118` with the surface 0.162 below, then eighteen airborne frames landing 2.1 yd
-    // downrange. That is the dive.
-    //
-    // **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`): 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.
-    //
-    // 1129 read that literally and dropped 1127's separate cone cap. The director's eye caught what
-    // the reading missed: *"the pop down seems too instant while the ref seems more smoothed … the
-    // ref is def not diving forward of the fence, it's still stepping down."*
-    //
-    // **The reason is the shape, and it is 1123's divergence on the down side.** The reference's
-    // mover is a cone at the foot, so stepping off a fence its **skirt stays in contact with the
-    // edge** the whole way down — its `achieved` is never large, because something is always just
-    // beneath it. The descent comes out at the cone's own slope, `d_h·1.8494` a frame, without any
-    // cap being needed: the geometry is the cap. Our capsule touches the edge side-on and then hangs
-    // clear, so the identical instruction sees the entire remaining drop and spends it at once. Same
-    // law, different body, opposite look.
-    //
-    // So we port the cone's *effect*, which is what 1123 said we would do for the solid we do not
-    // have: **one cone's worth of descent per frame.** The deeper reach stays exactly as 1129 left
-    // it — it is what lets us see the ground and stay grounded on a face steeper than the cone,
-    // which is what keeps the dive gone. Seeing further and falling further are different questions,
-    // and only the second one is the director's "instant".
+    // The descent is capped at a cone's worth a frame, which the reference's finalize is not: it
+    // descends the whole sweep before classifying (`0x636e45`-`0x636e52`), but its foot cone keeps
+    // the skirt on the edge, so each sweep is short and the descent comes out at the cone's slope.
+    // Our capsule hangs clear and would spend the whole drop at once; the cap ports the cone's
+    // effect. A steep landing stays grounded with the steep bit set, as the reference's multipass
+    // returns (`0x636f21`), and the deep reach keeps the ground in sight.
     let cone_reach = d.x.hypot(d.z) * STEP_SLOPE_RATIO + STEP_SNAP_SLACK;
     if let Some((distance, normal_y, entity)) = floor {
         let drop = (distance - surface_offset).max(0.0);
         let walkable = normal_y >= GROUND_COS;
-        // A ride's height is earned (above): only a floor higher than the ride began on may end it.
         if !(rode && walkable && drop >= ride_rise) {
             slid.y -= drop.min(cone_reach);
             if drop > cone_reach {
-                // **Further down than the cone could rest, but in sight.** This is a step-down still
-                // in progress — the reference's `0x4000000` case exactly — so we stay grounded and
-                // keep the deep reach open, and the next frames finish it a cone's worth at a time.
-                // Without this the body would be left hanging and the fall would elect, which is the
-                // dive coming back through the cap.
+                // Further down than a cone's worth but in sight: a step-down in progress, so stay
+                // grounded with the deep reach open and finish it over the next frames.
                 steep_support = true;
             } else if walkable {
                 ground = entity;
             } else {
-                // **Support is earned by descending, not by touching.** Resting *on* a steep face
-                // gives a clearance of ~0, and standing still the bound is the slack alone — so a
-                // "within reach" test alone would perch a motionless body on a 60° bank forever
-                // instead of letting it slide off (1121's named hazard, and worse than the dive).
-                // Real downward progress states the actual condition: descending, not resting.
+                // Support is earned by descending, not by touching: within reach alone would perch
+                // a motionless body on a steep bank.
                 steep_support = drop > STEP_SNAP_SLACK;
             }
         }
     } else if !rode {
-        // **Nothing in sight: descend, then let the fall elect** — the same `pos.z -= achieved` runs
-        // on the no-hit leg with `achieved == L` ("no committed record: `pos.z` has ALREADY dropped
-        // by the full `L`"), so the frame that leaves a ledge starts its fall lower instead of flat.
-        // A ride is exempt: mid-ride the body legitimately hangs clear of everything below, and this
-        // would spend the climb.
-        //
-        // **And it takes the same cone cap as the hit legs, for the same reason.** Left uncapped it
-        // was harmless only while the reach was a cone's worth anyway — once the steep-support bit
-        // opens the deep reach, "descend the full `L`" is a 1.25 yd drop in one frame. That is what
-        // the director was still feeling after 1132 capped the other two legs: their fence
-        // step-downs came through *this* branch, `snap miss (reach 1.25) dy=-1.250`, five of them in
-        // one capture. The cap is a property of our body, not of which leg found the floor.
-        // **Measured, not applied** (decision 2174) — [`GroundedStep::unsupported`] is the whole
-        // story: this is the first frame of a fall, and only a caller that can finish one may
-        // spend it.
+        // Nothing in sight: the reference still descends the whole sweep, then elects a fall.
+        // Measured here under the same cap, and spent only by a caller with a fall to elect; a
+        // ride is exempt, since mid-ride the body hangs clear by design.
         unsupported = Some((reach - surface_offset).max(0.0).min(cone_reach));
     }
     GroundedStep {
         center: slid,
-        // A ride is a climb too, and so is a pop — the trace reads the same whichever regime
-        // moved the body, and all three are measured from the frame's entry height.
         climb: (rode || popped.is_some()).then_some(slid.y - center.y),
-        // **Supported by a certified steep contact** — the reference's `0x4000000`, whose meaning
-        // decision 1125 settled. Two ways to earn it and one meaning: mid-ride the body is held up
-        // by the edge under its skirt (climbing), and mid-step-down it is resting on the surface it
-        // is following off a ledge (descending). Either way the frame-start ground probe looks
-        // straight down and sees only a steep face, so without this the frame reads as airborne and
-        // gravity takes the body off the surface — the climb undone on the way up, the dive on the
-        // way down. A walkable floor ends it: ordinary grounding takes over from there.
+        // A ride or a pop that found no walkable floor is held up by the edge it climbs.
         steep_support: ((rode || popped.is_some()) && ground.is_none()) || steep_support,
         ground,
         snap,
@@ -1020,46 +581,19 @@ pub(crate) fn grounded_step(
     }
 }
 
-/// **One airborne step, resolved against the world** — the arc's slide and nothing else. No
-/// step-up and no election snap: the arc owns its own height (gravity carries it; the landing is
-/// next frame's ground probe to call), so the only thing the world may do here is *stop* it. Steep
-/// faces get [`steep_contact_shear`]'s treatment, exactly as they do on the ground.
-///
-/// The airborne twin of [`grounded_step`], and shared for the same reason (0059's one controller,
-/// every mover): the local controller ([`step`]) calls it for its held/airborne frames, and a
-/// **remote** mover's ballistic dead-reckon calls it for the arc it invents between packets
-/// ([`crate::net::motion::remote`]). Without that, a watched player who jumps into a building is
-/// drawn *inside* it for the length of the jump and pops back out on the landing packet — the
-/// airborne half of the very defect 0626 fixed on the ground (decision 0627).
-/// **One frame of the fall, integrated exactly** — the end-of-step vertical speed and the *mean*
-/// speed to move at, given the speed at the step's start.
-///
-/// Under constant acceleration the mean velocity over a step IS the exact displacement rate, so
-/// `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). Stepping at either
-/// endpoint's velocity instead of the mean loses `½·g·dt²` per frame — and both of ours did, in
-/// opposite directions:
-///
-/// - the local mover applied gravity *before* moving (semi-implicit), so it moved at the END-of-step
-///   speed and fell **low**: `½·g·dt·t` by elapsed time, = 0.066 yd at the 1.640 yd jump apex at
-///   60 fps (4.0%), 0.133 at 30 fps. The jump was exactly one frame short, and short by *more* the
-///   worse the frame rate — which a jump arc must never be;
-/// - the remote dead-reckon moved *before* applying gravity (explicit Euler), so it moved at the
-///   START-of-step speed and overshot by the same amount, floating every other player's jump.
-///
-/// The terminal clamp is handled piecewise rather than by clamping the mean, because a step that
-/// *reaches* terminal partway is two regimes: accelerating to `−terminal` at `t_c`, then coasting.
-/// Clamping the mean would under-move that one step by up to `½·g·dt²`.
+/// One frame of the fall, exactly: the end-of-step vertical speed and the mean speed to move at,
+/// whose `mean · dt` is the closed form `v₀·dt − ½g·dt²`. The reference evaluates its arc in closed
+/// form from the launch every substep (`+0x7c − D(+0x78)`, `0x7c5e70`), so it cannot drift with
+/// the frame rate, and nor can this. A step reaching terminal partway is split at `t_c`, since a
+/// clamped mean would under-move it.
 pub(crate) fn fall_step(v0: f32, dt: f32, terminal: f32) -> (f32, f32) {
     let unclamped = v0 - GRAVITY * dt;
     if unclamped >= -terminal {
-        // Wholly inside the clamp: mean of the endpoints, exact.
+        // Wholly inside the clamp: the mean of the endpoints, exact.
         return (unclamped, 0.5 * (v0 + unclamped));
     }
     if v0 <= -terminal {
-        // Already at (or past) terminal for the whole step — constant velocity.
+        // At terminal for the whole step: constant velocity.
         return (-terminal, -terminal);
     }
     // The clamp engages partway: accelerate for `t_c`, then coast the remainder.
@@ -1068,6 +602,9 @@ pub(crate) fn fall_step(v0: f32, dt: f32, terminal: f32) -> (f32, f32) {
     (-terminal, displacement / dt)
 }
 
+/// One airborne step against the world: the arc's slide alone, with steep faces sheared
+/// ([`steep_contact_shear`]); gravity owns the height and the next ground probe the landing.
+/// Shared with the remote dead-reckon's arcs ([`crate::net::motion::remote`]).
 pub(crate) fn airborne_step(
     world: &benilla_world::collision::WorldCollision<'_, '_>,
     capsule: &Collider,
@@ -1092,68 +629,31 @@ pub(crate) fn airborne_step(
         .position
 }
 
-/// **The overhang line is a tolerance, not zero** — and it has to be, or half the world's vertical
-/// walls behave differently from the other half for no physical reason.
-///
-/// Every "is this face steep-but-not-overhanging" test here is a range whose floor used to be `0.0`.
-/// An axis-aligned authored quad — a doorstep, a crate, a dock plank, most of Booty Bay — computes a
-/// normal whose `y` is `±0` decided by nothing but which way the cross product's rounding fell. The
-/// director's capture caught both halves of that coin on the *same* step: `n.y = −4.08e-5` refused to
-/// certify and refused to ride, where `+0.009` on the same geometry did both. A real overhang is a
-/// ceiling, nowhere near this line, so widening the floor by a ten-thousandth costs nothing and
-/// makes a vertical wall a vertical wall whichever way the rounding goes.
+/// The overhang line, just below zero: an axis-aligned wall's normal has `y = ±0` by rounding, and
+/// both signs must read as a wall.
 const OVERHANG_EPS: f32 = -1.0e-4;
 
-/// A face the mover meets side-on: too steep to stand on, not a ceiling. The shared gate behind the
-/// step-up's certification, the foot-cone ride and the wall flatten — one line, so the three can
-/// never disagree about what a vertical wall is (see [`OVERHANG_EPS`]).
+/// A face the mover meets side-on: too steep to stand on, not a ceiling.
 fn is_steep_face(ny: f32) -> bool {
     (OVERHANG_EPS..GROUND_COS).contains(&ny)
 }
 
-/// 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) — 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
-/// grounded slide meets an opposing *walkable* plane (`n.y ≥ GROUND_COS`), replace the clip
-/// with the vertical-lift projection: keep the horizontal velocity exactly, set the vertical so
-/// the motion rides along the plane (`v'·n = 0` — the plane's own clip then passes it
-/// untouched). Unreal's `bMaintainHorizontalGroundVelocity` is the same standard treatment.
-/// Steep faces stay with [`steep_contact_shear`], and any height the ride manufactures is
-/// bounded by the end-of-frame snap, which only ever settles onto a walkable floor.
+/// The ride up a walkable slope: keep the horizontal velocity and set the vertical so the motion
+/// lies in the plane. The reference's walk step is a horizontal distance (`0x6367b0`), so no
+/// walkable slope slows or bends it, where a plane clip would cut it to `h·cos²θ`.
 fn walkable_ride_velocity(n: Vec3, v: Vec3) -> Option<Vec3> {
     if n.y < GROUND_COS || v.dot(n) >= 0.0 {
         return None;
     }
-    // Walkability bounds n.y ≥ cos50° > 0; an opposing contact makes the recomputed vertical
-    // strictly positive and ≤ h·tan50°. A prior facet's ride vertical is discarded, not stacked:
-    // the grounded mover owns no vertical of its own.
+    // `n.y ≥ cos 50°` keeps the division safe; a prior facet's vertical is replaced, not stacked.
     Some(Vec3::new(v.x, -(v.x * n.x + v.z * n.z) / n.y, v.z))
 }
 
-/// **The foot cone's ride** — the smooth half of the reference's climb law (decision 1123).
-///
-/// 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 (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 `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
-/// mover owns no vertical of its own, so this *sets* the vertical rather than adding to it.
-///
-/// Only steep, non-overhanging, opposing faces ride — a walkable face already had its ride, and an
-/// overhang is a ceiling. **The caller owns the real gate:** this says only "here is what the skirt
-/// would do", never "the body may climb". Whether the obstacle can be cleared at all is the
-/// certification's call in [`grounded_step`], because a tall wall's contact point sits inside the
-/// cone band too and height alone cannot tell the two apart.
+/// The foot cone's ride: the reference's solid is a box over a cone whose bevels rise
+/// `radius · 1.8494` from the foot (`0x631440`), so a low edge meets the skirt and the slide runs
+/// the body up it. The lift is `0x635c00`'s `1.8494 · cosθ · len`, the closing speed times the
+/// slope, and it sets the vertical rather than adding to it. Whether the body may climb at all is
+/// the caller's certification, since a tall wall's contact sits in the cone band too.
 fn foot_cone_ride(n: Vec3, v: Vec3) -> Option<Vec3> {
     if !is_steep_face(n.y) {
         return None;
@@ -1167,49 +667,12 @@ fn foot_cone_ride(n: Vec3, v: Vec3) -> Option<Vec3> {
     Some(Vec3::new(v.x, into * STEP_SLOPE_RATIO, v.z))
 }
 
-/// The steep-contact response: **the descent is never touched, and the push-out is horizontal.**
-///
-/// 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
-/// `0.0`). So the residual is placed **exactly in the contact plane** (`Δ'·A = 0`) but reaches it by
-/// moving *only horizontally*: the **vertical-shear** projection onto the plane, not the orthogonal
-/// one every collide-and-slide library ships.
-///
-/// ```text
-/// v' = v − (v·n)/|n_h|² · n_h            n_h = (n.x, 0, n.z)
-/// ```
-///
-/// Decomposing an approach as `a` into the face, `b` across it and `c` descending, against a face of
-/// pitch θ:
-///
-/// | component | what survives |
-/// |---|---|
-/// | downhill | `c · cotθ` — exactly what following the surface requires |
-/// | across   | `b` — preserved in full, never scaled |
-/// | vertical | `−c` — **untouched** |
-///
-/// Three consequences, none of them a tuning choice:
-///
-/// - **No geometry can add upward motion, at any steepness or approach angle.** The predecessor
-///   rules here reconstructed that invariant twice — first by testing the *sign* of the clipped
-///   vertical (0970), then by stripping the into-face push before an orthogonal clip (1135). The
-///   reference gets it structurally, because the vertical is not an output.
-/// - **A fall against a steep face descends at the full free-fall rate**, so along-surface speed is
-///   `V/sinθ` — *faster* than free fall. This is the reference's slippery steep-slope slide. An
-///   orthogonal clip descends at `V·sin²θ` instead: the same path down the face, walked 1.2–1.7×
-///   slower, which is that much longer in contact and so that much further across (the director's
-///   *"we slide across it until we land … further than the ref"*, worst just past 50° — exactly
-///   where players engage slopes).
-/// - **How hard you press into the face leaves no trace in the residual** — the push-out cancels
-///   `a` exactly. It survives only through *where* the sweep stopped.
-///
-/// A **grounded** frame is unchanged by all of this: its velocity is horizontal, `c = 0`, and the
-/// formula collapses to "remove the into-face component" — which is what walking into a bank always
-/// did here. Walkable faces ride ([`walkable_ride_velocity`]) and overhangs are ceilings; neither
-/// reaches this. The reference's degeneracy guards (`|n_h|` under `2⁻²²`) cannot fire for us:
-/// [`is_steep_face`] bounds `|n_h|` below by `sin 50°`.
+/// The steep-contact response: a horizontal push-out, the descent untouched. The reference's
+/// `0x635090` writes only an x/y push-out along the normal's horizontal part (the vertical is
+/// zeroed at `0x635166`), which `0x635600` adds to `Δx`/`Δy` alone, so
+/// `v' = v − (v·n)/|n_h|² · n_h`. No contact can add lift, and a fall along a steep face keeps its
+/// full rate, sliding down it faster than an orthogonal clip would. [`is_steep_face`] bounds
+/// `|n_h|` below by `sin 50°`, so the reference's degeneracy guard is not needed.
 fn steep_contact_shear(n: Vec3, v: Vec3) -> Option<Vec3> {
     if !is_steep_face(n.y) {
         return None;
@@ -1223,15 +686,10 @@ fn steep_contact_shear(n: Vec3, v: Vec3) -> Option<Vec3> {
     Some(v - (vn / h.length_squared()) * h)
 }
 
-/// What one atomic step-up attempt decided — the structured form of the `step` trace line.
-///
-/// Structured rather than logged-and-forgotten because the diagnostic probe
-/// ([`super::step_probe`]) re-runs the *same* maneuver at a ladder of forward advances and reads
-/// the reason back off every rung. "Why did this step fail, and what would have made it succeed"
-/// is then one table in the trace, not a text parse of six different format strings.
+/// What one step-up attempt decided; [`super::step_probe`] reads it back off each rung it tries.
 #[derive(Clone, Copy, Debug)]
 pub(crate) enum StepVerdict {
-    /// Nothing steep and opposing within the look-ahead — not a step-up frame at all.
+    /// Nothing steep and opposing within the look-ahead: not a step-up frame.
     NoFace,
     /// The rise found no headroom above the capsule.
     NoHeadroom,
@@ -1244,8 +702,8 @@ pub(crate) enum StepVerdict {
         dist: f32,
         ny: f32,
     },
-    /// The maneuver gained no height — a graze, a too-tall wall, or a pinch's gap floor. The plain
-    /// slide owns the frame.
+    /// The maneuver gained no height (a graze, a too-tall wall, a pinch's gap floor): the plain
+    /// slide keeps the frame.
     NetZero {
         up: f32,
         fwd: f32,
@@ -1253,10 +711,8 @@ pub(crate) enum StepVerdict {
         ny: f32,
         dy: f32,
     },
-    /// Certified: the obstacle can be cleared. What the frame then *does* is
-    /// [`grounded_step`]'s — a foot-cone ride or a pop of `up`, never this probe's own advance
-    /// (decision 1130). `landed` is where the probe's settle found floor, kept for the trace: it is
-    /// a **diagnostic**, one full [`STEP_UP_ADVANCE`] downrange, and committing it was the teleport.
+    /// Certified: the obstacle can be cleared, by a ride or a pop of `up` ([`grounded_step`]).
+    /// `landed` is the settle's floor a full advance downrange, for the trace only.
     Commit {
         landed: Vec3,
         up: f32,
@@ -1294,36 +750,19 @@ impl std::fmt::Display for StepVerdict {
     }
 }
 
-/// One step-up attempt: the opposing face that triggered it (world contact point + its authored
-/// normal), and what the maneuver decided about it.
+/// One step-up attempt: the face that triggered it and the verdict.
 pub(crate) struct StepAttempt {
-    /// `None` when no steep opposing face was within the look-ahead — there was nothing to step.
+    /// The face's contact point and authored normal; `None` when there was nothing to step.
     pub(crate) contact: Option<(Vec3, Vec3)>,
     pub(crate) verdict: StepVerdict,
 }
 
-/// The atomic step-up (decision 0209) — the standard kinematic-controller maneuver, *not* the
-/// reference resolver's (that direction is closed, 0207): a steep opposing face within `look`
-/// triggers **rise → advance → settle**, committed whole inside this one frame, or nothing.
-///
-/// - **Rise** by the free headroom, at most [`STEP_UP_HEIGHT`] — the deliberately low ceiling
-///   that scopes this to stairs/doorsteps/low rocks and keeps fences and walls slide-only.
-/// - **Advance** by `advance` along the *input* direction at the raised height.
-/// - **Settle** back down by the walk election's own reach; commit **only onto a walkable
-///   floor that is actually higher**.
-///
-/// Case by case: a square push at a low step lands ON its top this frame; a grazing rub
-/// settles back onto the same floor — net zero, reads as *sliding along*; a face taller than
-/// the ceiling leaves no forward clearance at the raised height ⇒ the settle lands back on
-/// the origin floor ⇒ slide; a pinch between two tree trunks offers only steep landings ⇒
-/// **no commit, ever** — the wedge/bounce class of 0191–0195 is impossible by construction,
-/// because there is no intermediate mid-climb state to be caught in.
-///
-/// **`look` and `advance` are separate parameters only so the maneuver is measurable.** The live
-/// mover passes this frame's own travel for both (0209's design — never a probe-length lunge);
-/// the diagnostic probe ([`super::step_probe`]) sweeps `advance` to find the offset at which the
-/// settle probe would have cleared the obstacle's lip, which is the number a "it won't step up
-/// this curb" report is actually about.
+/// The step-up certification, a standard kinematic-controller probe rather than the reference
+/// resolver's: against a steep opposing face within `look`, rise by the free headroom (at most
+/// `rise`), advance by `advance` along the input, and settle by the snap's reach onto a walkable
+/// floor that is higher. A graze or a wall taller than `rise` lands no higher, and a pinch between
+/// trunks only on steep faces, so none commits and the plain slide keeps the frame.
+/// [`super::step_probe`] sweeps `advance` to find where a step would clear.
 pub(crate) fn step_up(
     cast: &impl Fn(Vec3, Vec3) -> Option<MoveHitData>,
     center: Vec3,
@@ -1336,8 +775,8 @@ pub(crate) fn step_up(
         contact: None,
         verdict,
     };
-    // A steep, non-overhanging face opposing the motion, within `look` (+skin).
-    // No incidence gate — the verified ref has none; grazing nets zero through the settle.
+    // A steep, non-overhanging face opposing the motion within `look`. The reference has no
+    // incidence gate; a graze nets zero in the settle.
     let Some(ahead) = cast(center, dir_h * look) else {
         return none(StepVerdict::NoFace);
     };
@@ -1350,7 +789,7 @@ pub(crate) fn step_up(
         verdict,
     };
 
-    // Rise: the free headroom, at most H — the mover's own budget (`Support::rise`).
+    // Rise: the free headroom, at most `rise`.
     let up = cast(center, Vec3::Y * rise).map_or(rise, |h| h.distance);
     if up < 1e-3 {
         return at(StepVerdict::NoHeadroom);
@@ -1359,8 +798,7 @@ pub(crate) fn step_up(
     let raised = center + Vec3::Y * up;
     let fwd = cast(raised, dir_h * advance).map_or(advance, |h| h.distance);
     let over = raised + dir_h * fwd;
-    // Settle: the walk election's reach below the advanced point — the rise undone, plus the
-    // travel-scaled step-down allowance (decisions 0182/0190) — onto a WALKABLE floor only.
+    // Settle: the rise undone plus the snap's reach, onto a walkable floor only.
     let reach = up + advance * STEP_SLOPE_RATIO + STEP_SNAP_SLACK;
     let Some(down) = cast(over, Vec3::NEG_Y * reach) else {
         return at(StepVerdict::NoFloor { up, fwd });
@@ -1371,9 +809,8 @@ pub(crate) fn step_up(
     }
     let landed = over + Vec3::NEG_Y * dist;
     let dy = landed.y - center.y;
-    // Commit only a landing that actually gained a floor. A net-zero maneuver (grazing a face,
-    // pushing a too-tall wall, the tree pinch's gap grass) belongs to the plain slide — its
-    // deflection is what "sliding along the fence" is; committing here would dead-stop it.
+    // Commit only a landing that gained height: a net-zero one belongs to the slide, whose
+    // deflection is what sliding along a fence is.
     if dy <= 0.05 {
         return at(StepVerdict::NetZero {
             up,
@@ -1399,30 +836,21 @@ mod tests {
     use crate::player::CAPSULE_RADIUS;
     use bevy::ecs::system::RunSystemOnce;
 
-    /// A headless physics world holding **the kerb the director's capture measured** — Stormwind
-    /// Trade District, decision 1121: a 0.28 yd sidewalk whose riser is a ~61° bevel, not a
-    /// vertical face. Profiled from the `stup` down-ray scan at the real spot (street out to
-    /// +0.20, the bevel's face normal `ny=+0.49`, flat tread `ny=+0.99` from +0.50 on), so the
-    /// fixture is the geometry, not an idea of it.
-    ///
-    /// The profile is a `(x, y)` polyline extruded across `z`, wound so every face's **authored**
-    /// normal points up and back at the approaching body — the one-sided law (0970) is live in
-    /// these casts, so a mis-wound fixture would silently be a hole to fall through.
+    /// A Stormwind Trade District kerb: a 0.28 yd sidewalk behind a ~61° bevel, profiled from a
+    /// `stup` scan at the spot.
     fn world_with_kerb() -> App {
         const PROFILE: [(f32, f32); 4] = [(-2.0, 0.0), (0.29, 0.0), (0.446, 0.28), (3.0, 0.28)];
         world_from_profile(&PROFILE)
     }
 
-    /// The fixture builder behind every profiled world here: a `(x, y)` polyline extruded across
-    /// `z`, wound so every face's **authored** normal points up and back at the approaching body.
+    /// A headless world from a `(x, y)` polyline extruded across `z`, wound so every face's
+    /// authored normal points up and back at the approaching body: faces are one-sided.
     fn world_from_profile(profile: &[(f32, f32)]) -> App {
         const W: f32 = 3.0;
         let mut app = App::new();
-        // `WorldCollision` takes the mover's trace exclusions (the ghost/DOOR set, 1767); the
-        // real one is initialised by the world plugins, which a headless harness does not run.
+        // `WorldCollision` needs the mover's trace exclusions, which the world plugins insert.
         app.init_resource::<benilla_world::collision::MoverTraceExclusions>();
-        // 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 without meshes.
         app.add_plugins((
             MinimalPlugins,
             bevy::transform::TransformPlugin,
@@ -1441,8 +869,8 @@ mod tests {
                 Vec3::new(x1, y1, W),
                 Vec3::new(x0, y0, W),
             ]);
-            // (a, c, b) / (a, d, c): normal = (-dy, dx, 0) — up for the flats, up-and-back for
-            // the riser. The reverse winding is a backface and blocks nothing at all.
+            // (a, c, b) / (a, d, c): normal = (-dy, dx, 0), up for the flats and up-and-back for
+            // the riser; the reverse winding would block nothing.
             tris.extend([[b, b + 2, b + 1], [b, b + 3, b + 2]]);
         }
         app.world_mut().spawn((
@@ -1458,9 +886,7 @@ mod tests {
         Collider::capsule(CAPSULE_RADIUS, CAPSULE_HEIGHT - 2.0 * CAPSULE_RADIUS)
     }
 
-    /// Walk the capsule into the kerb exactly as the mover does, then run one step-up attempt at
-    /// `advance`. Returns the verdict from where the slide actually left the body — not from a
-    /// hand-placed pose, which is how a fixture ends up testing a spot the mover never reaches.
+    /// Walk into the kerb until it stops the body, then run one step-up attempt at `advance`.
     fn step_at(advance: f32) -> StepVerdict {
         world_with_kerb()
             .world_mut()
@@ -1468,7 +894,6 @@ mod tests {
                 let capsule = player_capsule();
                 let cast =
                     |from: Vec3, disp: Vec3| world.cast_mover(&capsule, from, disp, SKIN_WIDTH);
-                // Approach from 1 yd back along +X at street level and stop where the kerb stops us.
                 let start = Vec3::new(-1.0, CAPSULE_HEIGHT * 0.5, 0.0);
                 let run = cast(start, Vec3::X).map_or(1.0, |h| h.distance);
                 let center = start + Vec3::X * run;
@@ -1485,13 +910,10 @@ mod tests {
             .unwrap()
     }
 
-    /// One frame's travel at a run (7.0 yd/s) and 60 fps — 0209's advance, and the number the
-    /// capture caught failing.
+    /// One frame's travel at a run (7.0 yd/s) and 60 fps.
     const TRAVEL_60FPS: f32 = 7.0 / 60.0;
 
-    /// Walk the capsule into the kerb and run `frames` consecutive **whole** grounded steps from
-    /// wherever the last one left it — the mover's own loop, so what these assert is the behaviour
-    /// on screen and not a single probe in isolation.
+    /// `walk_profile` on the kerb.
     fn walk_kerb(start_y: f32, frames: usize) -> Vec<Row> {
         walk_profile(world_with_kerb(), start_y, frames)
     }
@@ -1499,15 +921,12 @@ mod tests {
     /// One frame of a walked fixture: `(feet height, climb, steep support, walkable ground)`.
     type Row = (f32, Option<f32>, bool, bool);
 
-    /// Walk the capsule into `world` and run `frames` consecutive **whole** grounded steps from
-    /// wherever the last one left it — the mover's own loop, so what these assert is the behaviour
-    /// on screen and not a single probe in isolation. Rows are `(feet height, climb, ride latch)`.
+    /// Walk into `world` from `(-1, start_y)` along +X, then run `frames` whole grounded steps.
     fn walk_profile(world: App, start_y: f32, frames: usize) -> Vec<Row> {
         walk_from(world, Vec3::new(-1.0, start_y, 0.0), Vec3::X, frames)
     }
 
-    /// The general walker: place the **feet** at `start`, push in `dir`, and run `frames` whole
-    /// grounded steps from wherever the last one left the body.
+    /// Feet at `start`, walk in `dir` until blocked (a yard at most), then `frames` grounded steps.
     fn walk_from(mut world: App, start: Vec3, dir: Vec3, frames: usize) -> Vec<Row> {
         world
             .world_mut()
@@ -1519,9 +938,7 @@ mod tests {
                 let run = cast(start, dir).map_or(1.0, |h| h.distance);
                 let mut center = start + dir * run;
                 let dt = std::time::Duration::from_secs_f32(TRAVEL_60FPS / 7.0);
-                // The steep-support bit is carried frame to frame exactly as the driver carries it
-                // (`Player::steep_support`), so the deep step-down reach is gated here the way it is
-                // on screen — a fixture that reset it every frame would test a mover we do not ship.
+                // The steep bit carries between frames, as in the mover, gating the deep reach.
                 let mut support = Support::default();
                 (0..frames)
                     .map(|_| {
@@ -1540,14 +957,8 @@ mod tests {
             .unwrap()
     }
 
-    /// **Booty Bay's step** — a 0.40 yd *vertical* riser onto a ~22° ramp, profiled from the
-    /// director's steered capture at WoW `(-14314.3, 466.2, 18.5)`, collider `54046v0`: the wall
-    /// probe reads `n=(-0.96,+0.00,-0.27)` with the blocking edge `h=+0.40` above the feet, and the
-    /// surface ahead runs `+0.35:+0.40/+0.93` … `+1.40:+0.82/+0.93`.
-    ///
-    /// The riser is tilted by 0.002 yd across its 0.40 of rise for one reason: a *perfectly* axis-
-    /// aligned quad computes a normal whose `y` is ±0 on a float coin flip, and this fixture must
-    /// pin the ride, not that coin flip. `an_exactly_vertical_riser_still_certifies` owns the flip.
+    /// Booty Bay's 0.40 yd vertical riser onto a ~22° ramp, at WoW `(-14314.3, 466.2, 18.5)`,
+    /// leaning 0.002 yd so the sign of a `±0` normal cannot decide the test.
     fn world_with_vertical_step() -> App {
         const PROFILE: [(f32, f32); 4] = [(-2.0, 0.0), (0.30, 0.0), (0.302, 0.40), (3.0, 1.48)];
         world_from_profile(&PROFILE)
@@ -1555,18 +966,14 @@ mod tests {
 
     #[test]
     fn a_vertical_step_is_climbed_not_stalled() {
-        // The 1123 regression the capture caught. A 0.40 yd rise is inside [`FOOT_CONE_HEIGHT`], so
-        // it rides — and against a *vertical* riser a capsule hangs clear of everything below, so
-        // the election snap saw the street a full ride beneath it and pulled the body back down
-        // every frame. Certified `COMMIT dy=+0.439` on every one, and stalled at +0.020 forever.
+        // The 0.40 yd rise rides, and a capsule on a vertical riser hangs clear of the street, so
+        // the snap must not pull the ride back down.
         let frames = walk_profile(world_with_vertical_step(), 0.0, 6);
         let top = frames.last().unwrap().0;
         assert!(
             top > 0.40,
             "the body must finish on the step, not stalled below it: {frames:?}"
         );
-        // Monotone: a ride that is undone and re-earned reads as a judder, which is what the
-        // director would see even if the body eventually arrived.
         for w in frames.windows(2) {
             assert!(
                 w[1].0 >= w[0].0 - 1.0e-3,
@@ -1581,12 +988,8 @@ mod tests {
 
     #[test]
     fn a_tall_step_behind_an_unwalkable_face_is_climbed() {
-        // Stormwind, WoW `(-8427.4, 607.4, 95.1)`, collider `14282v1` — the director's second
-        // capture. A 0.91 yd step whose face is a 66° bevel for most of a yard before the flat top
-        // begins, so it defeated **both** of the old budgets at once: the top is above 0209's 0.7
-        // rise ceiling, and 1121's one-radius advance put the settle probe still over the bevel,
-        // where the walkable gate correctly refused it. The captured ladder is unanimous —
-        // `STEEP fwd0.31 ny+0.41` at every rung out to 1.20.
+        // A Stormwind step at WoW `(-8427.4, 607.4, 95.1)`: a 0.91 yd top behind a 66° bevel most
+        // of a yard deep, so the settle must reach past the bevel to find it.
         const P: [(f32, f32); 4] = [(-2.0, -0.02), (0.28, -0.02), (0.694, 0.91), (3.0, 0.91)];
         let frames = walk_profile(world_from_profile(&P), -0.02, 8);
         assert!(
@@ -1599,8 +1002,7 @@ mod tests {
                 "the climb must never go backwards: {frames:?}"
             );
         }
-        // The blocking edge is low on the bevel, inside the cone, so this rides — six frames of
-        // smooth diagonal rather than a yard-high teleport.
+        // The blocking edge is low on the bevel, inside the cone, so this rides rather than pops.
         assert!(
             frames[0].0 < 0.3,
             "a 0.91 yd gain in one frame is the teleport 1126 exists to avoid: {frames:?}"
@@ -1609,14 +1011,8 @@ mod tests {
 
     #[test]
     fn stepping_off_a_kerb_follows_the_surface_down() {
-        // Decision 1127, and the exact frame the director's capture caught: walking *off* the same
-        // Stormwind kerb the down-probe finds only its ~61° riser, and refusing that outright left
-        // the body at full height while its forward speed carried it past the edge — one frame of
-        // `dy=+0.000 dx=0.118` with the surface 0.162 below, then eighteen airborne frames landing
-        // 2.1 yd downrange. The dive.
-        //
-        // **Support** is the thing to assert, because losing it *is* the dive: the caller turns an
-        // unsupported frame into gravity, and everything after that is an arc no snap can undo.
+        // Walking off the kerb the probe finds only its ~61° riser. Every frame must stay
+        // supported, since the caller turns an unsupported frame into a fall.
         let frames = walk_from(world_with_kerb(), Vec3::new(1.6, 0.28, 0.0), Vec3::NEG_X, 8);
         for (i, f) in frames.iter().enumerate() {
             assert!(
@@ -1632,17 +1028,10 @@ mod tests {
 
     #[test]
     fn a_face_steeper_than_the_cone_still_descends_what_it_can() {
-        // The "only sometimes" case. A face steeper than the cone cannot be followed exactly, and the
-        // question is what the mover does with the part it *can* follow. The reference descends
-        // `min(clearance, cap)` unconditionally and only then decides it is falling; the first cut of
-        // 1127 descended the clearance **or nothing**, so a surface a hair steeper than the cone
-        // dived — eight takeoffs in one capture, each missing the bound by 0.001–0.019.
-        //
-        // 66° face (`ny ≈ 0.41`, the captured value), walked off at a run: the first frame past the
-        // lip must give up most of a cone's worth of height, not hold its own.
+        // A 66° face (`ny ≈ 0.41`) walked off at a run: past the lip the mover descends what it
+        // can follow, rather than holding its height until it falls.
         const P: [(f32, f32); 4] = [(-2.0, 0.0), (0.60, 0.0), (1.0, -0.91), (3.0, -0.91)];
-        // (`walk_from`'s approach cast falls back to a yard when nothing blocks — there is no wall
-        // to stop against here — so the start is placed a yard short of the lip on purpose.)
+        // Nothing blocks the approach, which then moves a full yard; the start allows for it.
         let frames = walk_from(
             world_from_profile(&P),
             Vec3::new(-0.6, 0.0, 0.0),
@@ -1663,15 +1052,8 @@ mod tests {
 
     #[test]
     fn a_ledge_deeper_than_the_probe_is_a_fall_not_an_absorbed_step() {
-        // **The pin on decision 1129's reach.** A 1.2 yd sheer drop — deeper than the step-down probe
-        // can see, shallower than the 2.028 yd of flat extra depth the probe used to carry. Under the
-        // old reach the snap found the lower floor from the top of the ledge and absorbed the whole
-        // drop in ONE frame, still walkably grounded the entire way: a downward teleport, and the
-        // step-up teleport's exact mirror.
-        //
-        // What must happen instead is what the reference does: the body leaves the ground before it
-        // reaches the bottom, and the gap is a fall. So — **an airborne frame must come first.**
-        // (This test fails on the pre-1129 reach, which is the only reason it is worth having.)
+        // A 1.2 yd sheer drop, deeper than the snap reaches: the body leaves the ground before the
+        // bottom, as the reference's does, instead of absorbing the drop in one grounded frame.
         const P: [(f32, f32); 4] = [(-2.0, 0.0), (0.60, 0.0), (0.62, -1.20), (3.0, -1.20)];
         let frames = walk_from(
             world_from_profile(&P),
@@ -1679,12 +1061,7 @@ mod tests {
             Vec3::X,
             12,
         );
-        // The measurable form: **no single frame may give up an unbounded amount of height.** A
-        // frame's descent is the slide's own drop plus the step-down snap's, each bounded by what
-        // the foot cone could rest on over one frame's travel — so two cone-reaches is a generous
-        // ceiling. The corrected mover clears it easily (its worst frame here gives up 0.257); the
-        // old reach blows straight through, holding height to the lip and then taking the remaining
-        // **1.126 yd in a single frame**, walkably grounded at both ends of it.
+        // A frame's descent is the slide's plus the snap's, each at most a cone's reach.
         let bound = 2.0 * (TRAVEL_60FPS * STEP_SLOPE_RATIO + STEP_SNAP_SLACK);
         let worst = frames
             .windows(2)
@@ -1698,10 +1075,7 @@ mod tests {
 
     #[test]
     fn an_idle_body_is_not_pulled_down_through_open_air() {
-        // The other half of the same reach. A motionless body a yard above flat ground: standing
-        // still the probe is the slack and nothing more, so it must find nothing, keep its height,
-        // and be handed to gravity. The old reach was `slack + 2.028` even at a dead stop — it found
-        // the floor a yard down and yanked the body onto it, one frame, no fall.
+        // Standing still the snap reaches only the slack, so a body a yard up keeps its height.
         const P: [(f32, f32); 2] = [(-2.0, 0.0), (3.0, 0.0)];
         let (dy, ground) = world_from_profile(&P)
             .world_mut()
@@ -1722,28 +1096,9 @@ mod tests {
 
     #[test]
     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 (`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
-        // as teleporty. The capture's pop reads `step hit h=+0.73 n=(-0.04,+0.00,+1.00) up=1.00
-        // fwd=1.19 dy=+0.737 -> COMMIT`, and the frame it produced was `dy=+0.737 dx=1.191`.
-        //
-        // The `h=+0.73` is the whole point and it is why this fixture is a **table and not a step**:
-        // against a capsule a plain vertical riser reports its contact at the hemisphere centre,
-        // ≈0.33 up, which is inside the foot cone and rides. Only a face whose *lowest* collidable
-        // part is already above the band contacts high — a top slab overhanging recessed legs, which
-        // is exactly what a tavern table is. Before this test **no fixture in the suite reached the
-        // pop regime at all**, which is how 0209's teleport survived every green run for a year.
-        //
-        //      0.737 ┌──────────────  table top
-        //      0.62  ├──┐             slab front face  ← the contact, above the cone (0.617)
-        //            ┆  └──┐          underside
-        //      0.0   ┆     │────────  leg, recessed by more than a body radius
-        //           0.60  0.95
+        // The reference's walk resolver holds `L / t_remaining` across every hit (`0x6367b0`), so a
+        // pop never lunges. A Goldshire table: a slab from 0.62 to 0.737 over legs recessed past a
+        // body radius, so the contact sits above the cone and the step pops rather than rides.
         const P: [(f32, f32); 6] = [
             (-2.0, 0.0),
             (0.95, 0.0),
@@ -1784,19 +1139,8 @@ mod tests {
 
     #[test]
     fn stepping_off_a_fence_hugs_the_edge_down_instead_of_dropping_at_once() {
-        // **The pin on decision 1132**, and the director's report: *"the pop down seems too instant
-        // while the ref seems more smoothed … the ref is def not diving forward of the fence, it's
-        // still stepping down."*
-        //
-        // A 0.72 yd fence with a ~53° chamfered lip — the geometry their Goldshire capture measured
-        // (`snap ny=0.628 STEEP` on the lip frame, then the drop). The reference's foot cone keeps
-        // its skirt on that edge the whole way down and descends at the cone's own slope; our capsule
-        // hangs clear and, uncapped, spends the entire remaining drop in one frame (0.644 in the
-        // capture, `reach 1.24`).
-        //
-        // Two things must hold together, and only together: **no frame gives up more than a cone's
-        // worth**, and **the body never leaves the ground on the way down** — a cap alone would just
-        // be the dive again, one frame later.
+        // A 0.72 yd Goldshire fence with a ~53° chamfered lip. No frame may descend more than a
+        // cone's worth, and none may lose support: a cap alone would fall one frame later.
         const P: [(f32, f32); 5] = [
             (-2.0, 0.72),
             (0.60, 0.72),
@@ -1837,17 +1181,8 @@ mod tests {
 
     #[test]
     fn a_frame_that_finds_nothing_still_spends_only_one_cone() {
-        // **The branch 1132's first cut missed.** When the probe finds nothing the reference still
-        // writes `pos.z -= achieved` with `achieved == L` — harmless while `L` is a cone's worth, and
-        // a **1.25 yd teleport** once the steep-support bit opens the deep reach. That is what the
-        // director was still feeling after the two hit legs were capped: their fence step-downs came
-        // through here, `snap miss (reach 1.25) dy=-1.250`, five of them in one capture.
-        //
-        // Stated at the branch rather than through a fixture, because reproducing the *miss* needs
-        // the body clear of the wall it just left, and a profiled fence puts its riser directly under
-        // the capsule (it hugs that riser down instead — which is `stepping_off_a_fence_hugs_the_edge
-        // _down…`, the case that does have geometry). Here: carrying the bit, moving, with the floor
-        // beyond even the deep reach, so the probe cannot hit anything.
+        // The no-hit leg with the steep bit set and the floor beyond even the deep reach, which a
+        // profiled fence cannot reach: its riser stays under the capsule.
         const P: [(f32, f32); 2] = [(-2.0, 0.0), (3.0, 0.0)];
         let dy = world_from_profile(&P)
             .world_mut()
@@ -1880,8 +1215,7 @@ mod tests {
 
     #[test]
     fn a_motionless_body_is_never_perched_on_a_steep_slope() {
-        // A 60° bank. Walk onto it, then STOP. Standing still the cone bound collapses to the slack,
-        // so does the steep support quietly keep a motionless body perched on it?
+        // A 60° bank, where a standing body's cone bound is the slack alone.
         const P: [(f32, f32); 3] = [(-2.0, 0.0), (0.0, 0.0), (3.0, -5.196)];
         let out = world_from_profile(&P)
             .world_mut()
@@ -1892,7 +1226,6 @@ mod tests {
                 let mut rows = Vec::new();
                 let mut support = Support::default();
                 for i in 0..4 {
-                    // Two frames walking, then two standing perfectly still.
                     let v = if i < 2 { Vec3::X * 7.0 } else { Vec3::ZERO };
                     let g = grounded_step(&world, &capsule, center, v, dt, support);
                     center = g.center;
@@ -1912,10 +1245,7 @@ mod tests {
 
     #[test]
     fn an_exactly_vertical_riser_still_certifies() {
-        // The other half of the same capture. An axis-aligned riser's normal has `y = ±0` depending
-        // on nothing but the cross product's rounding, and an overhang guard written as `n.y < 0.0`
-        // refuses the negative half — reading a plain vertical step as a ceiling. Half the world's
-        // risers, decided by a float sign.
+        // An axis-aligned riser's normal has `y = ±0` by rounding; either sign must climb.
         const PROFILE: [(f32, f32); 4] = [(-2.0, 0.0), (0.30, 0.0), (0.30, 0.40), (3.0, 1.48)];
         let frames = walk_profile(world_from_profile(&PROFILE), 0.0, 6);
         assert!(
@@ -1926,11 +1256,7 @@ mod tests {
 
     #[test]
     fn the_kerb_is_ridden_up_its_skirt_never_popped() {
-        // Decision 1123, the whole point: a 0.28 yd kerb is inside the foot cone
-        // ([`FOOT_CONE_HEIGHT`] ≈ 0.62), so the certified obstacle is *ridden* — a smooth diagonal
-        // over the frames the gait needs — instead of the body being teleported onto the tread in
-        // one frame. Both halves are asserted, because either alone is satisfiable by a bug: it
-        // must arrive on the tread, AND no single frame may deliver the whole rise.
+        // A 0.28 yd kerb is inside the foot cone: it must reach the tread, and not in one frame.
         let frames = walk_kerb(0.0, 4);
         let arrived = frames
             .iter()
@@ -1953,10 +1279,7 @@ mod tests {
 
     #[test]
     fn a_wall_is_never_ridden() {
-        // The certification is the gate, not the height (a tall wall's contact point sits inside
-        // the cone band too). Read the same geometry from a full kerb below — a 2.3 yd wall — and
-        // nothing may rise: no ride, no climb, no lift, just the slide. This is the check that
-        // stops the ride becoming a ladder up every cliff in the world.
+        // The kerb read from 2 yd below is a 2.3 yd wall, whose contact also sits in the cone band.
         for (y, climb, riding, _) in walk_kerb(-2.0, 4) {
             assert!(!riding, "a wall must never start a cone ride");
             assert!(climb.is_none(), "a wall must never register a climb");
@@ -1969,8 +1292,7 @@ mod tests {
 
     #[test]
     fn the_cone_ride_gains_the_reference_slope() {
-        // The reference's `T = 1.8494 · cosθ · len` (`0x635c00`). Head-on, the gain is the cone's
-        // own surface slope times the speed…
+        // `0x635c00`'s `T = 1.8494 · cosθ · len`: head-on, the slope times the speed…
         let head_on = foot_cone_ride(Vec3::new(-1.0, 0.0, 0.0), Vec3::X * 7.0).unwrap();
         assert!(
             (head_on.y - 7.0 * STEP_SLOPE_RATIO).abs() < 1e-4,
@@ -1980,8 +1302,7 @@ mod tests {
             head_on.x, 7.0,
             "horizontal speed is never touched by a ride"
         );
-        // …and meeting the same face at 60° gains exactly cos60° of it, which is the `cosθ` term
-        // falling out of the closing-speed projection rather than being applied by hand.
+        // …and at 60° off the face, exactly cos 60° of it.
         let oblique = foot_cone_ride(
             Vec3::new(-1.0, 0.0, 0.0),
             Vec3::new(7.0 * 0.5, 0.0, 7.0 * 0.866_025_4),
@@ -2006,9 +1327,7 @@ mod tests {
 
     #[test]
     fn the_kerb_is_out_of_reach_of_one_frames_travel() {
-        // The defect the capture pinned (decision 1121): the settle probe is still over the bevel
-        // at 0.117 yd, so it lands on a 61° face and the walkable gate — correctly — refuses it.
-        // The step-up is not wrong about the face; it never looked far enough to see the tread.
+        // At one frame's travel the settle lands on the bevel, which the walkable gate refuses.
         let v = step_at(TRAVEL_60FPS);
         assert!(
             matches!(v, StepVerdict::SteepFloor { .. }),
@@ -2018,9 +1337,7 @@ mod tests {
 
     #[test]
     fn a_body_scaled_advance_climbs_the_kerb() {
-        // …and a body radius ahead, the same probe is over the tread and commits onto it. `dy` is
-        // the kerb's real height, so this pins that we land ON the sidewalk, not part-way up its
-        // bevel.
+        // …and at the certify advance it is over the tread, with `dy` the kerb's height.
         let v = step_at(STEP_UP_ADVANCE);
         let StepVerdict::Commit { dy, .. } = v else {
             panic!("a body-radius advance should reach the tread, got {v}");
@@ -2033,18 +1350,14 @@ mod tests {
 
     #[test]
     fn the_advance_never_climbs_past_the_rise_ceiling() {
-        // The reach grew; what may be climbed did not (decision 1121). A wall taller than
-        // [`STEP_UP_HEIGHT`] clips the elevated sweep, so the settle falls back to the origin
-        // floor and the plain slide keeps the frame — the fence/trunk behaviour 0209 was built
-        // for, asserted at the advance that made the kerb work.
+        // The kerb read from 2 yd below is a wall taller than the rise budget: it clips the raised
+        // sweep, so the settle lands back on the origin floor.
         let v = world_with_kerb()
             .world_mut()
             .run_system_once(move |world: benilla_world::collision::WorldCollision| {
                 let capsule = player_capsule();
                 let cast =
                     |from: Vec3, disp: Vec3| world.cast_mover(&capsule, from, disp, SKIN_WIDTH);
-                // Stand the body a full kerb below the tread — the same geometry read as a 2.3 yd
-                // wall by dropping the approach to y = −2.0, where the tread is far overhead.
                 let start = Vec3::new(-1.0, CAPSULE_HEIGHT * 0.5 - 2.0, 0.0);
                 let run = cast(start, Vec3::X).map_or(1.0, |h| h.distance);
                 step_up(
@@ -2072,8 +1385,7 @@ mod tests {
 
     #[test]
     fn a_walkable_ramp_rides_at_full_horizontal_speed() {
-        // 45° uphill at run speed: the ride keeps the 2D velocity exactly (the true-plane clip
-        // would halve it to h·cos²45° = 3.5) and lies in the plane, so the clip passes it.
+        // A plane clip would cut 45° uphill to `h·cos²45°` = 3.5.
         let n = face(45.0);
         let v = Vec3::new(7.0, 0.0, 0.0);
         let ride = walkable_ride_velocity(n, v).expect("must ride");
@@ -2084,8 +1396,6 @@ mod tests {
 
     #[test]
     fn a_diagonal_approach_is_not_deflected() {
-        // Walking diagonally up a face rising toward +x: the true-plane clip bends the path
-        // toward across-slope; the ride keeps both horizontal components untouched.
         let v = Vec3::new(5.0, 0.0, 5.0);
         let ride = walkable_ride_velocity(face(40.0), v).expect("must ride");
         assert_eq!((ride.x, ride.z), (5.0, 5.0));
@@ -2093,8 +1403,7 @@ mod tests {
 
     #[test]
     fn a_prior_facet_ride_is_recomputed_not_stacked() {
-        // Crossing a facet boundary mid-slide: the incoming vertical (facet A's ride) is
-        // discarded and rebuilt for facet B — the grounded mover owns no vertical of its own.
+        // The incoming 3.0 is a prior facet's ride vertical.
         let n = face(45.0);
         let ride = walkable_ride_velocity(n, Vec3::new(7.0, 3.0, 0.0)).expect("must ride");
         assert_eq!((ride.x, ride.z), (7.0, 0.0));
@@ -2104,18 +1413,13 @@ mod tests {
     #[test]
     fn steep_flat_and_receding_planes_never_ride() {
         let push = Vec3::new(7.0, 0.0, 0.0);
-        // Steep (>50°) is the wall rule's, not the ride's.
         assert!(walkable_ride_velocity(face(60.0), push).is_none());
-        // Flat floor underfoot: no opposition, nothing to rewrite.
         assert!(walkable_ride_velocity(Vec3::Y, push).is_none());
-        // A receding walkable plane (walking downhill away from it) keeps the plain move + snap.
         assert!(walkable_ride_velocity(face(40.0), -push).is_none());
     }
 
     #[test]
     fn the_ride_covers_the_walkable_range_up_to_the_gate() {
-        // Just inside the gate (49.9°) still rides at full speed; just outside (50.1°) does not
-        // ride — it falls to the steep-wall rule instead.
         let v = Vec3::new(7.0, 0.0, 0.0);
         let ride = walkable_ride_velocity(face(49.9), v).expect("must ride");
         assert_eq!((ride.x, ride.z), (7.0, 0.0));
@@ -2126,8 +1430,6 @@ mod tests {
 
     #[test]
     fn walking_into_a_steep_face_spends_the_push_along_it() {
-        // The grounded case, unchanged in outcome by the strip: a run straight at a 60° face
-        // keeps nothing pointing into it, and manufactures no vertical of its own.
         let v = Vec3::new(7.0, 0.0, 0.0);
         let out = steep_contact_shear(face(60.0), v).expect("must strip");
         assert!(out.x.abs() < 1e-6 && out.y == 0.0);
@@ -2135,10 +1437,8 @@ mod tests {
 
     #[test]
     fn a_fall_against_a_face_keeps_the_whole_of_its_descent() {
-        // The ratchet's engine, and the slide's, in one place. Falling at 4.9 yd/s into a 55° face
-        // with a run held into it, an orthogonal clip leaves the body descending — so 0970's
-        // `v'.y > 0` flatten declined — at ~1% of what gravity intended, which the wedge rest reads
-        // as a landing. The reference never touches the vertical at all.
+        // Falling at 4.9 yd/s into a 55° face with a run held into it, an orthogonal clip keeps ~1%
+        // of the descent, which the wedge rest would read as a landing.
         let (n, v) = (face(55.0), Vec3::new(7.0, -4.9, 0.0));
         let orthogonal = v - v.dot(n) * n;
         assert!(
@@ -2153,8 +1453,7 @@ mod tests {
             out.y,
             v.y
         );
-        // …and the horizontal is exactly what following the surface costs: `cotθ` per unit of drop,
-        // downhill. The push held into the face leaves no trace (`a` cancels exactly).
+        // The horizontal is `cot θ` per unit of drop, downhill; the push into the face cancels.
         let cot = 1.0 / 55.0_f32.to_radians().tan();
         assert!(
             (out.x - v.y * cot).abs() < 1.0e-3,
@@ -2167,11 +1466,7 @@ mod tests {
 
     #[test]
     fn a_plumb_fall_is_carried_down_the_face_at_full_speed() {
-        // A body dropping straight onto a steep face has no push to remove — and is still the
-        // response's business, because following the surface *is* horizontal motion. It keeps every
-        // bit of its 10 yd/s and gains the surface's own drift. (Under 1135's strip this returned
-        // `None`, and the orthogonal clip then slowed the descent instead — the same error seen
-        // from the other side.)
+        // A plumb fall has no push to remove, yet following the surface is horizontal motion.
         let out = steep_contact_shear(face(60.0), Vec3::new(0.0, -10.0, 0.0))
             .expect("a plumb fall still follows the surface");
         assert!(
@@ -2191,8 +1486,6 @@ mod tests {
 
     #[test]
     fn a_rising_jump_keeps_its_own_lift() {
-        // A jump rising along the face: the strip spends the push against the hill and the
-        // mover's own +vy passes through untouched — the face adds nothing to it.
         let v = Vec3::new(7.0, 8.0, 0.0);
         let out = steep_contact_shear(face(60.0), v).expect("boost must strip");
         assert!((out.y - v.y).abs() < 1e-6);
@@ -2201,16 +1494,12 @@ mod tests {
         assert!(out.dot(n) >= -1e-6);
     }
 
-    /// **B322, the swim half — the three gates of `0x6315f0`, including the one 1611 could only
-    /// name.** The pitch gate is what lets a water-walker back *into* the water, and it is a strict
-    /// `>`: the reference's `jne` reads ZF, so −37.0° exactly is on the falling side of the line.
+    /// The three gates of `0x6315f0`; the pitch gate is strict, so −37.0° exactly sinks.
     #[test]
     fn the_water_is_geometry_only_while_all_three_gates_hold() {
         const SURFACE: f32 = 12.5;
         let eps = 1.0e-4;
-        // Granted, dry-shod, aim level: the water is a floor.
         assert_eq!(water_floor(true, false, 0.0, Some(SURFACE)), Some(SURFACE));
-        // Aiming down, either side of the line — and *on* it.
         assert_eq!(
             water_floor(true, false, WATER_WALK_PITCH_FLOOR + eps, Some(SURFACE)),
             Some(SURFACE),
@@ -2226,7 +1515,7 @@ mod tests {
             None,
             "aim past -37 deg and the liquid layers leave the mask: the dive"
         );
-        // Aiming *up* never costs the floor — the arm has no upper bound.
+        // The arm has no upper bound.
         assert_eq!(
             water_floor(true, false, 1.5, Some(SURFACE)),
             Some(SURFACE),
@@ -2235,26 +1524,16 @@ mod tests {
         // Swimming excludes it (`0x631617`), and so does not having the aura.
         assert_eq!(water_floor(true, true, 0.0, Some(SURFACE)), None);
         assert_eq!(water_floor(false, false, 0.0, Some(SURFACE)), None);
-        // No liquid under the feet is no floor, whatever the gates say.
         assert_eq!(water_floor(true, false, 0.0, None), None);
     }
 
-    /// **B322, the height half** (decision 1616): Levitate is hover **and** water walking, and the
-    /// two compose — the body rests a full yard *above* the waterline, not with its feet in it.
-    ///
-    /// 1611 left this open. It is settled at the bytes: the walk resolver's finalize down-probe
-    /// (`0x636e45`) is `0x632ba0`, whose trace (`0x632d29`) is `0x631e70` — the query whose own head
-    /// is the mask arm (`0x6320a0 call 0x6315f0`). So the distance `L` the probe reports is measured
-    /// to the *water*, and `0x636e74` then leaves the body at `pos.z_before_snap − max(L − 1.0, 0)`.
-    ///
-    /// Three things at once, because they are one mechanism: the rise off the waterline is
-    /// **rate-limited** (the reference's second pass `0x636fa1`, not a pop), it **settles at
-    /// exactly** [`HOVER_HEIGHT`], and a body dropped in from above **stops there** instead of
-    /// sinking to the surface.
+    /// Levitate's hover and water walking compose: the finalize probe's trace (`0x632d29`) is
+    /// headed by the mask arm (`0x6320a0`), so it measures to the water and the body rests a yard
+    /// over it, reached at the climb rate (`0x636fa1`) from below and stopped there from above.
     #[test]
     fn a_hovering_water_walker_floats_a_yard_over_the_waterline() {
         const SURFACE: f32 = 0.0;
-        // No land at all: open water, so nothing but the liquid plane can hold the body up.
+        // Open water: nothing but the liquid plane can hold the body up.
         const OPEN: [(f32, f32); 2] = [(-3.0, -40.0), (3.0, -40.0)];
         let (first, rest, dropped) = world_from_profile(&OPEN)
             .world_mut()
@@ -2286,7 +1565,6 @@ mod tests {
                     }
                     player.pos.y
                 };
-                // Granted while standing on the water: climbs, it does not pop.
                 let mut player = Player {
                     modes: levitate,
                     pos: Vec3::new(0.0, SURFACE, 0.0),
@@ -2294,7 +1572,6 @@ mod tests {
                 };
                 let first = idle(&mut player, 1);
                 let rest = idle(&mut player, 60);
-                // Dropped in from well above: the fall stops at the hover line, not the waterline.
                 let mut faller = Player {
                     modes: levitate,
                     pos: Vec3::new(0.0, SURFACE + 8.0, 0.0),
@@ -2319,15 +1596,12 @@ mod tests {
         );
     }
 
-    /// **B322, the lift** (decision 1616): the director's *"it doesn't bring you to surface when
-    /// used in water"*, for the case the reference actually surfaces — a body standing in liquid
-    /// too shallow to swim in. The surface is solid geometry over there, so a body inside it is a
-    /// body inside a wall that the swept resolve keeps on top. Ours is a queried plane with no
-    /// sweep, so the resolve has to say it.
+    /// A wader in liquid too shallow to swim is lifted onto the surface, which the reference's
+    /// swept surface keeps a body on top of.
     #[test]
     fn water_walking_lifts_a_wader_out_of_the_water() {
         const SURFACE: f32 = 0.0;
-        // A lakebed 1.4 yd under the surface — wading depth for a human (swim starts at ~1.52).
+        // A lakebed 1.4 yd under the surface: wading depth for a human (swim starts at ~1.52).
         const BED: [(f32, f32); 2] = [(-4.0, -1.4), (4.0, -1.4)];
         let (walker, levitator) = world_from_profile(&BED)
             .world_mut()
@@ -2387,23 +1661,8 @@ mod tests {
         );
     }
 
-    /// **B322, the lost-control half** (decision 1611): a body walking off land onto water with
-    /// `MOVEFLAG_WATERWALKING` up must keep steering and must stop when the keys are released.
-    ///
-    /// Before 1611 it did neither, and the reason was structural rather than numeric: the liquid
-    /// surface was applied only as a position clamp *after* the step, so the classify — which
-    /// looks for colliders and finds nothing over open water — called every water-walking frame
-    /// **airborne**, and an airborne frame's horizontal is frozen momentum — so the last *grounded*
-    /// frame's velocity, taken on the land behind you, is what the body carries out over the water
-    /// for good. This fixture measured it before the fix: 60 frames east at 7 yd/s put the body at
-    /// x = 6.0; 30 frames pressing **north** moved it another 3.5 yd **east** and 0.0 north; 30
-    /// frames with **no keys at all** moved it 3.5 yd east again. The director's words: *"when you
-    /// step onto over water with it it won't let you control the char anymore, just keeps
-    /// running."*
-    ///
-    /// The three observables, in one drive: it reaches the water at all, a new direction actually
-    /// turns it, and releasing the keys stops it dead. The control that must not change is the
-    /// height — the feet stay on the surface throughout, which is what 0866 shipped and measured.
+    /// A water-walker walking off land keeps steering and stops when the keys go: over water the
+    /// classify must see the plane, or every frame reads airborne and coasts on frozen momentum.
     #[test]
     fn a_water_walker_steers_and_stops_instead_of_coasting() {
         const SURFACE: f32 = 0.0;
@@ -2450,7 +1709,6 @@ mod tests {
             })
             .unwrap();
 
-        // Walked off the quay and out over open water, on the surface.
         assert!(
             east.x > 1.0,
             "the walk onto the water must actually travel: {east:?}"
@@ -2461,7 +1719,6 @@ mod tests {
                 "the feet must stay on the liquid surface ({label}): {p:?}"
             );
         }
-        // Steering: a new direction moves the body that way, and the abandoned one stops growing.
         assert!(
             north.z - east.z > 1.0,
             "a water-walker must steer: z {} -> {}",
@@ -2474,7 +1731,6 @@ mod tests {
             east.x,
             north.x
         );
-        // Release: dead stop, no coast. This is the assertion the report is about.
         assert!(
             idle.distance(north) < 1.0e-3,
             "released keys must stop a water-walker dead: {north:?} -> {idle:?}"
@@ -2483,11 +1739,8 @@ 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 (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.
+        // Hover is the first test in `CMovement::Jump` (`0x7c6230`, at `0x7c623a`); the press with
+        // hover off is the control.
         let flat: [(f32, f32); 2] = [(-3.0, 0.0), (3.0, 0.0)];
         let rows = world_from_profile(&flat)
             .world_mut()
@@ -2532,11 +1785,8 @@ mod tests {
         );
     }
 
-    /// **The jump hover cannot refuse** (decision 1620, B322) — the same handler, entered through
-    /// the wire's door. `0x7c6236 test eax,eax; je 0x7c6243` skips the hover test above whenever
-    /// `force` is 0, and the sole `force = 0` call site is `0x61a62e`, inside the `SetHover(true)`
-    /// handler. So the body that is hovering — the one the test above proves Space cannot move — is
-    /// exactly the body this leg launches, because it was granted hover a moment ago.
+    /// `Jump(0)` skips the hover test (`0x7c6236`), and its one caller is the hover grant
+    /// (`0x61a62e`), so it launches the very body the keyboard cannot.
     #[test]
     fn the_wire_jump_launches_the_hovering_body_the_keyboard_cannot() {
         let flat: [(f32, f32); 2] = [(-3.0, 0.0), (3.0, 0.0)];
@@ -2586,13 +1836,8 @@ mod tests {
         );
     }
 
-    /// **The fall step is EXACT, not merely close** (decision 1740). Under constant acceleration
-    /// the mean of the endpoint velocities is the true displacement rate, so one step of `dt` and
-    /// `n` steps of `dt/n` must land on the same height — that is the whole property the reference
-    /// gets for free by evaluating a closed form, and the one both of our integrators lacked.
-    ///
-    /// The old semi-implicit form fails this: it lost `½·g·dt²` per step, so a coarser step landed
-    /// lower, which is a jump arc that changes shape with the frame rate.
+    /// One step of `dt` and `n` steps of `dt/n` land on the same height, as the reference's closed
+    /// form does.
     #[test]
     fn the_fall_step_is_frame_rate_independent() {
         let total = 0.5_f32;
@@ -2606,7 +1851,6 @@ mod tests {
             }
             y
         };
-        // The analytic height after `total`: v₀·t − ½g·t².
         let analytic = JUMP_SPEED * total - 0.5 * GRAVITY * total * total;
         for steps in [1_u32, 2, 8, 30, 120] {
             let got = drop(steps);
@@ -2617,9 +1861,7 @@ mod tests {
         }
     }
 
-    /// The jump apex is the reference's, to the millimetre: `v₀²/2g` = 1.640 yd. The old
-    /// integrator undershot it by 4.0% at 60 fps and 8% at 30 — visible as a jump that could not
-    /// quite clear what it should (decision 1740).
+    /// The jump apex is `v₀²/2g` = 1.640 yd at any frame rate.
     #[test]
     fn the_jump_apex_is_the_analytic_one_at_any_frame_rate() {
         let apex = JUMP_SPEED * JUMP_SPEED / (2.0 * GRAVITY);
@@ -2632,8 +1874,7 @@ mod tests {
                 high = high.max(y);
                 v = end;
             }
-            // Within one step's worth of sampling — the apex falls between frames, and that is
-            // sampling, not drift.
+            // The apex falls between frames: a step's worth of sampling, not drift.
             assert!(
                 (high - apex).abs() < 0.5 * GRAVITY * dt * dt + 1.0e-4,
                 "at {fps} fps the apex should be ~{apex}, got {high}"
@@ -2641,13 +1882,10 @@ mod tests {
         }
     }
 
-    /// **Terminal is a piecewise clamp, not a clamped mean** (decision 1740). A step that reaches
-    /// terminal partway is two regimes, and clamping the mean instead would under-move it by up to
-    /// `½·g·dt²`. Below terminal the clamp must not perturb the exact answer at all.
+    /// A step reaching terminal partway is two regimes; below terminal the clamp changes nothing.
     #[test]
     fn the_terminal_clamp_is_exact_on_the_step_that_reaches_it() {
         let dt = 1.0 / 60.0;
-        // Well below terminal: untouched by the clamp.
         let (end, mean) = fall_step(0.0, dt, TERMINAL_VELOCITY);
         assert!((end - -GRAVITY * dt).abs() < 1.0e-6);
         assert!((mean - -0.5 * GRAVITY * dt).abs() < 1.0e-6);
@@ -2661,27 +1899,15 @@ mod tests {
             (mean - want).abs() < 1.0e-6,
             "piecewise, not a clamped mean"
         );
-        // Already at terminal: constant velocity, no acceleration at all.
         let (end, mean) = fall_step(-TERMINAL_VELOCITY, dt, TERMINAL_VELOCITY);
         assert_eq!((end, mean), (-TERMINAL_VELOCITY, -TERMINAL_VELOCITY));
     }
 
-    /// **A knockback is unsteerable because its launch plants a direction bit — not because it is
-    /// 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
-    /// (`0x7c6afc test al,0xf` guarding the only two `arg = 1` openers), and `0x6179c0`'s
-    /// `0x617a18 or edx,0x8001` plants FORWARD as part of every knockback apply — *regardless of
-    /// `speedXY`*. We tested `horiz_vel.length_squared() < 0.01` instead, a velocity proxy that
-    /// agrees for every ordinary jump and disagrees for exactly this input: a knockback with no
-    /// horizontal component at all, which the proxy reads as "standing still, may steer". Since
-    /// `Outcome::knocked` is true on the launch frame only, nothing else covered it either — the
-    /// player got 2.5 yd/s of free steering from the second frame of a purely vertical toss.
+    /// Every knockback apply plants FORWARD (`0x6179c0`, at `0x617a18`) whatever its speed, and air
+    /// control opens only while the nibble is clear (`0x7c6afc`), so a vertical toss never steers.
     #[test]
     fn a_vertical_knockback_is_no_more_steerable_than_a_fast_one() {
         let flat: [(f32, f32); 2] = [(-3.0, 0.0), (3.0, 0.0)];
-        // Straight up, no horizontal at all — the input the old velocity proxy could not see.
         const STRAIGHT_UP: Vec3 = Vec3::new(0.0, 12.0, 0.0);
         let horiz = world_from_profile(&flat)
             .world_mut()
@@ -2707,7 +1933,7 @@ mod tests {
                 );
                 assert!(out.knocked && out.jumped, "the toss opened an arc");
                 assert_eq!(player.horiz_vel, Vec3::ZERO, "and it is purely vertical");
-                // Frames 2..6: airborne, and now the player leans on a movement key.
+                // Frames 2..6: airborne, with a movement key held.
                 let mut nudged = false;
                 for _ in 0..5 {
                     let out = step(
@@ -2737,11 +1963,8 @@ mod tests {
         );
     }
 
-    /// **The air-control nudge is `min(MOVE_WALK, MOVE_RUN)` off the unit's live speeds, not a
-    /// constant** (decision 1740). `0x7c5c20(1)` → `0x7c4c90(1)`, whose non-zero argument is a walk
-    /// override returning `min(+0x88, +0x8c)`. `AIR_NUDGE_SPEED`'s 2.5 is merely the *default*
-    /// `MOVE_WALK`, so the constant is right until a walk aura, a Slow or a daze moves either
-    /// speed — and the `min` is why a slowed run still cannot out-steer a walk.
+    /// The nudge is the live `min(walk, run)`: `0x7c5c20(1)` calls `0x7c4c90(1)`, whose walk
+    /// override returns `min(+0x88, +0x8c)`.
     #[test]
     fn the_standstill_nudge_takes_the_speed_it_is_given() {
         let flat: [(f32, f32); 2] = [(-3.0, 0.0), (3.0, 0.0)];
@@ -2753,7 +1976,7 @@ mod tests {
                     let mut time = Time::default();
                     time.advance_by(std::time::Duration::from_secs_f32(1.0 / 60.0));
                     let mut player = Player::default();
-                    // Jump from a dead standstill: the nibble is clear, so one steer is in hand.
+                    // A standing jump: the nibble is clear, so one steer is in hand.
                     step(
                         &mut player,
                         &time,
@@ -2768,7 +1991,6 @@ mod tests {
                         None,
                         nudge,
                     );
-                    // Airborne, and now a key goes down.
                     let out = step(
                         &mut player,
                         &time,
@@ -2783,7 +2005,7 @@ mod tests {
                         None,
                         nudge,
                     );
-                    // …and a second press must change nothing: the nibble is set now.
+                    // A second press finds the nibble set and changes nothing.
                     step(
                         &mut player,
                         &time,
@@ -2809,31 +2031,22 @@ mod tests {
             "at the speed given: {v:?}"
         );
         assert!(v.x < 0.0, "and in the pressed direction: {v:?}");
-        // A walk aura: the same jump steers slower, because the law reads the live speeds.
+        // A walk aura lowers the live speed.
         let (fired, v) = steer(1.0);
         assert!(fired);
         assert!(
             (v.length() - 1.0).abs() < 1.0e-4,
             "a slowed body steers slower — the constant is not the law: {v:?}"
         );
-        // One-shot in both cases: the second press found the nibble set and did nothing.
         assert!(
             v.z.abs() < 1.0e-4,
             "the second press must not steer again: {v:?}"
         );
     }
 
-    /// **The knockback launch seeds BOTH axes, overrides the keys, and is refused only by the
-    /// anchor** (decision 1702).
-    ///
-    /// The three things that make it a different take-off from every other one, in one fixture. Its
-    /// vertical is not `JUMP_SPEED`; its horizontal is the server's, not `input_horiz` — the arm
-    /// that would otherwise hand our momentum straight back to whatever key is held, because a
-    /// knockback fired from standing ground is still `grounded` on its launch frame; and the refusal
-    /// is `MOVEFLAG_ROOT`, which is the *only* thing the reference's drain tests before applying one
-    /// (`0x615c71 test ah,0x10` → the kind-28 table byte is 0 → the popped record is discarded, so
-    /// no apply and no ack). The control is the same launch, unrooted, on a body running the other
-    /// way.
+    /// The launch seeds both axes from the server, not the keys, and only ROOT refuses it: the
+    /// reference's drain tests nothing else before applying one, and discards it under root with
+    /// no apply and no ack (`0x615c71`).
     #[test]
     fn a_knockback_launch_overrides_the_keys_and_only_a_root_refuses_it() {
         let flat: [(f32, f32); 2] = [(-3.0, 0.0), (3.0, 0.0)];
@@ -2896,17 +2109,12 @@ mod tests {
         );
     }
 
-    /// **The wire's down-positive `zspeed` becomes upward lift, and comes back out unchanged.**
-    ///
-    /// The one place a sign error would be silent in both directions at once: the launch quad's
-    /// `zspeed` is negative for a *rising* knockback (`0x7c61f0` stores it verbatim into the same
-    /// `CMovement+0xa0` a jump seeds with `0xc0fe93d8` = −7.955547), our mover works in +up, and the
-    /// ack has to echo the original value. Flip the convention anywhere along that path and the
-    /// body is driven into the ground while the server is told we rose.
+    /// The wire's `zspeed` is down-positive: a rising knockback's is negative (`0x7c61f0` stores it
+    /// in `CMovement+0xa0`, where a jump seeds `0xc0fe93d8` = −7.955547), and the ack echoes it.
     #[test]
     fn a_rising_knockback_carries_negative_wire_zspeed_and_positive_lift() {
         let launch = benilla_protocol::JumpInfo {
-            zspeed: -12.0, // down-positive: negative IS upward
+            zspeed: -12.0, // down-positive: negative is upward
             cos_angle: 1.0,
             sin_angle: 0.0,
             xy_speed: 25.0,
@@ -2919,15 +2127,12 @@ mod tests {
         ]);
         assert_eq!(bevy_launch.y, 12.0, "a negative wire zspeed lifts the body");
 
-        // …and the round trip back out, as `stream_self_movement` builds the tail: `jump_zspeed` is
-        // the mover's +up take-off speed, and the wire negates it again.
+        // Back out as `stream_self_movement` builds the tail, negating the +up `jump_zspeed`.
         let jump_zspeed = bevy_launch.y;
         assert_eq!(
             -jump_zspeed, launch.zspeed,
             "the echo must be bit-identical — the server matches it within 0.01 before relaying"
         );
-        // The horizontal survives the basis round trip exactly, which is what lets the ack's tail
-        // and the mover's live state agree without either being re-derived from the other.
         let back = benilla_assets::coords::bevy_to_wow(bevy_launch.with_y(0.0));
         assert_eq!(
             [back[0], back[1]],
@@ -2939,12 +2144,8 @@ mod tests {
         );
     }
 
-    /// **The waterline is a floor, and a floor does not catch a body on its way up** (decision
-    /// 1620, B322). The depenetration half of the water resolve is ours, not the reference's — over
-    /// there the surface is a swept solid and the sweep is directional for free — so it needs the
-    /// clause the sweep gets for nothing. Without it, casting Levitate a foot under the waterline
-    /// would have the launch clamped flat to the surface with its velocity zeroed on the very next
-    /// step: a pop where the reference throws you clear.
+    /// The waterline push-out stands in for the reference's swept surface, so like a sweep it
+    /// catches a sinking body and lets a rising one through.
     #[test]
     fn the_waterline_catches_a_sinking_body_and_lets_a_launched_one_through() {
         const SURFACE: f32 = 0.0;
@@ -3005,23 +2206,8 @@ mod tests {
         assert_eq!(rest_vy, 0.0, "and the floor takes its velocity");
     }
 
-    /// **A Levitating walker holds its line over water, moving or still** (decision 1623, B322) —
-    /// the director's report: *"when I start walking it drop a bit lower and then when I stop it
-    /// goes up again, over land it's fine somehow."*
-    ///
-    /// The "somehow" is the whole bug. On land the election snap finds a collider and places the
-    /// body at its own reach; over water it found nothing, took the **step-off-a-ledge** leg
-    /// (`slid.y -= (reach − surface_offset).min(cone_reach)`) and walked the body down a full cone's
-    /// worth every frame, which the hover climb then hauled back at [`HOVER_CLIMB_RATE`]. The two
-    /// settle at an equilibrium — measured at `+0.117` against a `+1.000` line, i.e. **0.88 yd low**
-    /// — and it is speed-dependent, because `cone_reach` is `travel · STEP_SLOPE_RATIO + slack`.
-    /// Standing still the same leg still bit, just at the slack alone (`1/36` per frame), so the
-    /// idle float was climbing 0.117 and losing 0.028 forever instead of resting.
-    ///
-    /// Both are one cause and it is not the hover: **liquid is queried, never swept, so the snap's
-    /// `cast_body` is blind to it** — the third site to need the plane handed in after 1611's
-    /// classify and 1616's climb. A plain water-walker hid it, because with no hover offset the
-    /// descent lands under the surface and the depenetration push-out undoes it in the same frame.
+    /// A hovering water-walker holds the hover line walking and standing: the snap must see the
+    /// water plane, or it takes the no-floor leg every frame and the climb fights it.
     #[test]
     fn a_levitating_walker_holds_its_line_over_water_moving_or_still() {
         const SURFACE: f32 = 0.0;
@@ -3074,7 +2260,6 @@ mod tests {
             .unwrap();
 
         let line = SURFACE + HOVER_HEIGHT;
-        // The climb is the rate and nothing else — no per-frame descent quietly eating into it.
         assert!(
             (first_rise - 2.0 * HOVER_CLIMB_RATE / 60.0).abs() < 1.0e-5,
             "two frames of climb are exactly two frames of the rate, with nothing pulling back \
@@ -3098,10 +2283,8 @@ mod tests {
         );
     }
 
-    /// **The Elwynn hillside the director jump-climbed** — a 55° face (`ny = +0.574`, the normal
-    /// the capture read off the real slope at WoW `(-9236.8, -341.9, 101.6)`) rising out of flat
-    /// ground. Too steep to walk by a wide margin, so nothing here may ever end with the body
-    /// standing part-way up it.
+    /// An Elwynn hillside out of flat ground, a 55° face (`ny = +0.574`, read at WoW
+    /// `(-9236.8, -341.9, 101.6)`), too steep to stand on anywhere.
     fn world_with_steep_hillside() -> App {
         const P: [(f32, f32); 3] = [(-3.0, 0.0), (0.0, 0.0), (2.5, 3.570)];
         world_from_profile(&P)
@@ -3111,10 +2294,7 @@ mod tests {
     /// gravity intended that the frame actually achieved)`.
     type AirRow = (f32, f32, f32);
 
-    /// Jump into `world` from `start_feet` and fly the arc exactly as the mover flies it —
-    /// gravity into `vel_y`, then [`airborne_step`] — holding `dir` at a run the whole way.
-    /// This is the *airborne* half of the mover's loop, the half no fixture here exercised
-    /// before: every other walker in this module drives [`grounded_step`].
+    /// Jump from `start_feet`, flying the bare arc through [`airborne_step`] at a run along `dir`.
     fn jump_into(mut world: App, start_feet: Vec3, dir: Vec3, frames: usize) -> Vec<AirRow> {
         world
             .world_mut()
@@ -3148,10 +2328,6 @@ mod tests {
 
     #[test]
     fn a_jump_into_a_steep_hillside_banks_no_height() {
-        // **The climbing ratchet the director caught** (their capture: ten jumps up an Elwynn
-        // hillside, +1.2 yd banked each, 100.0 -> 104.6 in half a minute). Jumping at a face too
-        // steep to walk must cost the jump and return the body where it started: the face may
-        // convert the body's own descent into a slide down itself, and nothing else.
         let arc = jump_into(
             world_with_steep_hillside(),
             Vec3::new(-0.6, 0.0, 0.0),
@@ -3169,10 +2345,7 @@ mod tests {
             "the arc must end back at the foot of the slope, not banked part-way up it: \
              ended at {end:.3} (peak {peak:.3})"
         );
-        // …and it must never *read* as a landing on the way down, which is how the height gets
-        // banked on screen: [`WEDGE_STILL_FRAMES`] consecutive frames under [`WEDGE_STALL_RATIO`]
-        // of gravity's intent is what the mover calls a wedge rest, and it stands the body up
-        // wherever it is. Above the foot of the slope there is nothing here to rest on.
+        // Nor may the descent stall into a wedge rest, which would stand the body up part-way.
         let (mut run, mut worst_run) = (0u8, 0u8);
         for r in arc.iter().filter(|r| r.0 > 0.2) {
             run = if r.1 < -WEDGE_MIN_FALL && r.2 < WEDGE_STALL_RATIO {
@@ -3191,24 +2364,15 @@ mod tests {
 
     #[test]
     fn a_steep_face_never_cancels_a_fall() {
-        // The ratchet's engine, stated where it lives. Collide-and-slide's true-plane clip turns a
-        // horizontal push into upward motion (`v'.y - v.y = -(v·n)·n.y`), and against a 55° face a
-        // run into the hill very nearly cancels gravity: the capture's stalled frames descended
-        // 1-7% of what gravity intended, three in a row, which is what tripped the wedge rest into
-        // "landed standing" (decisions 0211/0212) part-way up an open hillside.
-        //
-        // What geometry may take is bounded: a body sliding down a face of pitch θ keeps
-        // `sin²θ` of its descent (0.67 at 55°). Anything under that is the push holding the body
-        // up, not the slope carrying it down.
+        // A plane clip turns a run into the hill into lift (`v'.y - v.y = -(v·n)·n.y`), which all
+        // but cancels a fall against a 55° face.
         let arc = jump_into(
             world_with_steep_hillside(),
             Vec3::new(-0.6, 0.0, 0.0),
             Vec3::X,
             150,
         );
-        // Frames clear of the flat ground only: once the body is back at the foot of the slope it
-        // is *standing*, and a standing frame achieving none of gravity's intent is the floor
-        // doing its job. (This harness is the bare arc — it has no ground probe to tell it that.)
+        // Only frames clear of the flat ground, which the bare arc has no ground probe to stand on.
         let worst = arc
             .iter()
             .filter(|r| r.1 < -WEDGE_MIN_FALL && r.0 > 0.2)
@@ -3224,18 +2388,14 @@ mod tests {
     #[test]
     fn walkable_and_overhanging_faces_are_untouched() {
         let push = Vec3::new(7.0, 0.0, 0.0);
-        // Walkable floor: the slide's ordinary uphill walk.
         assert!(steep_contact_shear(face(40.0), push).is_none());
-        // Overhang: the ceiling clip stands as-is.
+        // An overhang keeps the plain ceiling clip.
         assert!(steep_contact_shear(Vec3::new(-0.5, -0.7, 0.0).normalize(), push).is_none());
-        // A receding face never opposes the motion.
         assert!(steep_contact_shear(face(60.0), -push).is_none());
     }
 
     #[test]
     fn a_vertical_wall_takes_the_whole_push_and_no_more() {
-        // A true vertical face manufactures no lift under either rule — the strip removes the
-        // push, and there is no vertical left for the plane to take.
         let v = Vec3::new(7.0, -4.0, 0.0);
         let out = steep_contact_shear(face(90.0), v).expect("must strip");
         assert!(out.x.abs() < 1e-6 && (out.y - v.y).abs() < 1e-6);
diff --git a/crates/benilla-app/src/player/net.rs b/crates/benilla-app/src/player/net.rs
index 605c0351..b2f580b1 100644
--- a/crates/benilla-app/src/player/net.rs
+++ b/crates/benilla-app/src/player/net.rs
@@ -1,7 +1,5 @@
-//! 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`.
+//! The player's packet handlers: `SMSG_STANDSTATE_UPDATE` goes to [`super::posture`] as a
+//! [`ServerStandState`], applied in `control`, which holds the body query and sheath queue.
 
 use benilla_protocol::{SessionEvent, SessionEventKind};
 use bevy::prelude::*;
@@ -9,7 +7,7 @@ use bevy::prelude::*;
 use super::ServerStandState;
 use crate::net::NetHandlerApp;
 
-/// Register the handler — called from [`super::PlayerPlugin`].
+/// Registers the handlers; called from [`super::PlayerPlugin`].
 pub(super) fn register(app: &mut App) {
     app.net_handler(SessionEventKind::StandStateUpdate, on_stand_state_update);
 }
diff --git a/crates/benilla-app/src/player/posture.rs b/crates/benilla-app/src/player/posture.rs
index faf33272..d93104bc 100644
--- a/crates/benilla-app/src/player/posture.rs
+++ b/crates/benilla-app/src/player/posture.rs
@@ -1,22 +1,15 @@
-//! **Posture** — the two things the controller does to how the body *holds* itself, as opposed to
-//! where it goes: the **stand state** (the `/sit` family and the `X` key) and the **sheath**
-//! toggle (`Z`). One module because they are one mechanism in the reference and they interlock
-//! here: entering a stand state ∉ {0 STAND, 2 SIT_CHAIR} force-stows drawn weapons through the
-//! same anim-layer setter the `Z` key drives, and the sheath toggle's own guard chain refuses on
-//! the stand state this frame just committed.
-//!
-//! Both halves are **silent-refusal** mechanisms — the reference builds no packet and says
-//! nothing when a press is rejected — which is why the stand half writes the `sit` trace tag
-//! ([`super::move_trace::posture`]) at every commit *and* every refusal: on screen a granted sit
-//! and a refused one are the same picture (decisions 0080, 0881; bug B155).
+//! Posture: the stand state (the `/sit` family and `X`) and the sheath toggle (`Z`), one
+//! mechanism in the reference. A stand state other than 0 or 2 stows drawn weapons through the
+//! setter `Z` drives (2 inferred to be the chair sit, vmangos's `UNIT_STAND_STATE_SIT_CHAIR`), and
+//! the toggle refuses on the stand state this frame committed. Both refuse silently, with no
+//! packet, so the `sit` trace tag ([`super::move_trace::posture`]) records each commit and refusal.
 
 use bevy::prelude::*;
 
 use super::{move_trace, state, BodyQuery, ClientCommand, NetCommands, Player, StandStateRequest};
 
-/// Run this frame's stand-state decision and the sheath toggle, and return the **committed**
-/// stand state — the local commit overlaid on the server's echoed byte, which is what the body
-/// pose and the sheath guard both read (decision 0080c).
+/// Runs this frame's stand-state decision and sheath toggle, and returns the committed stand
+/// state: the local commit over the server's echoed byte, which the pose and sheath guard read.
 pub(super) fn update(
     player: &mut Player,
     body: &BodyQuery,
@@ -28,21 +21,14 @@ pub(super) fn update(
     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 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.
+    // The echo into `UNIT_FIELD_BYTES_1` drives every observer's pose; `stand_pending`, the local
+    // commit ([`apply_locally`]), overlays it until it lands.
     let (stand_byte, reads_dead) = body
         .single()
         .ok()
         .and_then(|(.., store, _, _, _, _, _)| {
-            // `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 (`0x5ed4a9`–`0x5ed4bd`; decision 1753).
+            // `SetStandState`'s first guards, health ≤ 0 or `UNIT_DYNAMIC_FLAGS & 0x20` (feigning),
+            // without `unit_reads_dead`'s stand state 7 (`0x5ed4a9`–`0x5ed4bd`).
             store.map(|s| {
                 (
                     s.0.unit_stand_state(),
@@ -54,44 +40,26 @@ 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.
+    // `SMSG_STANDSTATE_UPDATE` reaches the local apply directly, with no refusal gate and no
+    // `CMSG_STANDSTATECHANGE` back, before the volunteered logic below; the last packet wins.
     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,
-    // the key is read now. The last writer wins, and every one of them lands on the single
-    // commit-and-send below.
+    // The queued asks (the `/sit` family) ran in the reference's message pass, before the X key
+    // is read; the last writer wins, and all land on the single commit below.
     let mut request_stand = asks.read().last().map(|r| r.state);
     if binds.fired(crate::bindings::cmd::SIT_OR_STAND) {
         request_stand = Some(u8::from(stand_state == 0));
     }
-    // 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: 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).
-    // 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
-    // sub-200 ms RELEASE being dispatched as a right-CLICK, so the stand belongs to the click's
-    // action and not here.
-    // **A knockback stands you up too** (decision 1702) — the one entry here that is nobody's
-    // input. The reference's knockback apply carries it as a side effect of the launch (the
-    // `0x60e139` block, whose indirect `call [edx+0xa4]` resolves to `GetStandState 0x60be50`),
-    // which is the same guarded wrapper every trigger above reaches. Read off the armed latch
-    // rather than the take-off, because this block runs before the mover: the latch was written
-    // by [`super::wire_in::apply_server_moves`] at the top of the frame and is still there.
+    // Movement stands us up, volunteered, as the server never does: translation, a keyboard turn
+    // and jump reach the stand wrapper `0x60be30(0)` from any nonzero state; a left-drag orbit
+    // does not, nor a right-drag turn (`0x514f50` skips its stand arm while the button is held),
+    // though a release within 200 ms is a right-click, whose action stands you. A knockback's move
+    // event stands us too (`0x60e139`: `GetStandState` `0x60be50`, then `0x60be30(0)`), read off
+    // the latch [`super::wire_in::apply_server_moves`] armed this frame, as the mover runs later.
     let knocked_out_of_it = player.knockback.is_some();
     if (moving || turned || knocked_out_of_it || binds.fired(crate::bindings::cmd::JUMP))
         && stand_state != 0
@@ -99,17 +67,10 @@ pub(super) fn update(
     {
         request_stand = Some(0);
     }
-    // The sit-down gate — the client's own, inside the ONE setter `0x5ed430`
-    // ([`state::stand_state_refused`], bug B155): a body the movement layer is already driving
-    // cannot be seated, and **swimming is one of the driving states**, so the press is refused
-    // for as long as we are in the water — and a body that reads dead is refused in EITHER
-    // direction, which is the setter's own first guard (decision 1753). Silently, and before the packet — like the reference,
-    // which returns from `SetStandState` without building `CMSG_STANDSTATECHANGE` at all.
-    // Placed on the shared commit below rather than on the X key, so it covers the posture
-    // emotes (`/sit`, `/sleep`, `/kneel`) in the same stroke — their own `Emotes.dbc` gate
-    // does NOT carry the swim bit (`ui_chat::tests::the_posture_emotes_carry_no_swim_suppression_flag`).
-    // The word is the live outbound one, a frame old — the same `[[this+0x118]+0x40]` the cast
-    // gates read (decision 1056), so all three refusals can never disagree about "am I moving".
+    // `SetStandState` `0x5ed430`'s gate ([`state::stand_state_refused`]), silent and before the
+    // packet: no sitting while translating or swimming, no change at all while dead. It covers
+    // the posture emotes too, whose `Emotes.dbc` gate has no swim bit. The flags word is the live
+    // outbound one, a frame old, the `[[this+0x118]+0x40]` the cast gates read.
     if let Some(s) =
         request_stand.filter(|&s| state::stand_state_refused(reads_dead, player.move_flags(), s))
     {
@@ -123,31 +84,21 @@ 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());
-        // 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).
+        // `0x5ed430` sends at `0x5ed501`, then calls the local apply at `0x5ed53f`.
         let _ = net.0.send(ClientCommand::StandStateChange {
             state: u32::from(s),
         });
         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
-    // ([`crate::creature_anim::SheathRequest`], decision 0080): walk the *committed*
-    // 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 `0x5eb480` sites).
-    // No body model yet (no driver) drops the toggle, the client's own refusal.
+    // The sheath toggle (Z) cycles the anim layer's committed sheath state through its one setter
+    // ([`crate::creature_anim::SheathRequest`]), which sends `CMSG_SETSHEATHED`; only it plays the
+    // ceremony (`bInstant = 0` in `ToggleSheath` `0x5eb480`). No body model yet drops the press.
     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
-            // 12-deep silent-refusal chain (`ToggleSheath` `0x5eb480`) whose states exist
-            // 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`, wired with
-            // 0441's mounts). Stunned / channeling join when those states exist. A refused
-            // press is simply dropped — no message, like the client.
+            // Of `ToggleSheath`'s 12 silent guards: dead, in combat, any nonzero stand state,
+            // mid-ceremony (clip 89/90) and mounted; its stunned and channeling guards are not
+            // tested here.
             let dead = store.is_some_and(|s| s.0.unit_is_dead());
             let mounted = store.is_some_and(|s| s.0.unit_mount_display_id() != 0);
             let refused =
@@ -159,13 +110,10 @@ pub(super) fn update(
                     drv.sheath_ceremony_active()
                 );
             } else {
-                // The cycle proper ([`crate::creature_anim::toggle_sheath_next`], byte-read):
-                // melee → ranged → stowed, gated on what is actually worn — never a
-                // two-state flip. `None` = the ref makes no call at all (nothing equipped).
+                // Melee, ranged, stowed, skipping what is not worn; `None` makes no call at all.
                 let w = wielded.copied().unwrap_or_default();
-                // `0x5eb5f0`/`0x600`/`0x610` are `GetWeapon(slot, 0)` (1863): a disarmed hand
-                // is not "worn" to the cycle, so the press walks past melee — and with nothing
-                // else equipped makes no call at all, exactly like the ref's unarmed branch.
+                // `GetWeapon(slot, 0)` at `0x5eb5f0`, `0x5eb600` and `0x5eb610`: a disarmed hand
+                // is not worn.
                 let worn = (
                     w.armed_main().is_some() || w.armed_off().is_some(),
                     w.ranged.is_some(),
@@ -186,20 +134,11 @@ 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.
+/// The stand state's local apply, the reference's `0x6127b0`, reached from `SetStandState` after
+/// its send and from `SMSG_STANDSTATE_UPDATE` (`0x603e50`); it sends nothing. A change writes the
+/// prediction (`[player+0x1d68]`); any call stows a drawn weapon for a state but 0 or 2
+/// (`0x6127cc`). Not built: its loot release and attack stop on a sit (`0x5f0790` → `0x48f200`,
+/// `0x5ecac0`), movement re-run on a stand, and follow-camera re-acquire each call (`0x48ec90`).
 fn apply_locally(
     player: &mut Player,
     s: u8,
@@ -221,8 +160,8 @@ fn apply_locally(
     }
 }
 
-/// `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.
+/// `0x5f0790`'s early-out (`0x5f0799`): the predicted stand state is written only on a change.
+/// Returns whether it was.
 fn predict(pending: &mut Option<u8>, s: u8, stand_now: u8) -> bool {
     if s == stand_now {
         return false;
diff --git a/crates/benilla-app/src/player/ride.rs b/crates/benilla-app/src/player/ride.rs
index fc9bf243..9eeaca7a 100644
--- a/crates/benilla-app/src/player/ride.rs
+++ b/crates/benilla-app/src/player/ride.rs
@@ -1,47 +1,18 @@
-//! **Riding a transport** — the boat/zeppelin/tram platform frame (decision 0438 phase 2, widened
-//! by 0470's solid cargo). Three acts, in the order the controller runs them:
-//!
-//! 1. [`carry`] — *before* any input integrates, recompose the rider from the deck's THIS-frame
-//!    pose. The deck's motion carries a standing player and its yaw delta turns the whole rider
-//!    assembly with it.
-//! 2. [`update_attachment`] — *after* the mover has stepped, decide whether we are still aboard,
-//!    and re-snapshot the deck-local pose the next frame's [`carry`] recomposes from.
-//! 3. The `ride` **trace** tag, emitted inside (2) because it needs the same three reads. The
-//!    deck's own motion lives in the boat's transform and the rider's in world space; the
-//!    difference between them is the only thing that says whether the carry composed, and no other
-//!    instrument records it.
+//! Riding a transport (boat, zeppelin, tram). [`carry`] recomposes the rider from the deck's pose
+//! before any input integrates; [`update_attachment`] decides after the mover whether we are still
+//! aboard, re-snapshots the deck-local pose and writes the `ride` trace tag.
 
 use bevy::prelude::*;
 
 use super::{wrap_pi, FlyCam, Player, PlayerRide, TransportQuery};
 
-/// Recompose the rider from the deck's this-frame pose, before any input integrates.
+/// Recomposes the rider from the deck's this-frame pose.
 pub(super) fn carry(player: &mut Player, cam: &mut FlyCam, transports: &TransportQuery) {
-    // The platform carry (decision 0438 phase 2): while attached to a transport, recompose the
-    // feet from the boat's THIS-frame pose (the transport tick runs on the Net→Input edge, so it's
-    // fresh) before any input integrates — the deck's motion carries the standing player, and its
-    // per-frame yaw delta turns them with it (applied incrementally so it composes with whatever
-    // mouse-look already wrote to `face_yaw` this frame). A despawned boat (streamed out) detaches
-    // into an ordinary fall from the last world pose.
-    //
-    // The carry is rigid for the WHOLE rider — aim (`face_yaw`), rendered body (`model_yaw`), and
-    // camera (`cam.yaw`) take the same delta, all HERE. Carrying only the aim leaves the standing
-    // body-chase to close the gap frame after frame, and that chase-step is exactly what latches
-    // the turn-in-place foot-shuffle (whose keyframes fire step sounds): a sailing boat's spline
-    // yaw drifts continuously, so the rider shuffled and clacked the whole voyage (director,
-    // 2026-07-17). The deck turning under you is not you turning — the chase and its shuffle only
-    // see input turns.
-    //
-    // The camera's share is unconditional — a deck turn is FRAME motion, not an input turn, so it
-    // never routes through `seat_camera`'s look-session gate (that gate protects the camera from
-    // *keyboard* turns while a drag owns it). Routing it there was the right-drag drift bug
-    // (director, 2026-07-18): during a look session the gate ate the camera's share, and the
-    // right-drag coupling `face_yaw = cam.yaw` (which runs first next frame) then yanked the aim
-    // back to the world-fixed camera — undoing the deck carry, so with the mouse still the scene
-    // swung across the screen and the rider visibly spun against the deck. Carrying all three here
-    // keeps the drag's orbit offset (`cam.yaw − face_yaw`) exactly as the hand left it while the
-    // whole rider assembly turns with the boat — the reference's camera rides the transport-local
-    // player rig the same way.
+    // The transport tick runs on the Net→Input edge, so the deck pose is this frame's; a
+    // streamed-out boat detaches into a fall. The yaw delta goes to aim, body and camera alike, on
+    // top of this frame's mouse-look, as the reference's camera rides the transport-local rig: a
+    // deck turn must reach neither the body chase, whose steps latch the turn-in-place shuffle,
+    // nor `seat_camera`'s look-session gate.
     if let Some(ride) = player.ride.as_ref() {
         match transports.get(ride.entity) {
             Ok((boat, _, _)) => {
@@ -64,8 +35,8 @@ pub(super) fn carry(player: &mut Player, cam: &mut FlyCam, transports: &Transpor
     }
 }
 
-/// Attach/detach against this frame's walkable support, then re-snapshot the deck-local pose.
-/// `ground` is the mover's resolved support entity ([`super::mover::Outcome::ground`]).
+/// Attaches or detaches against this frame's walkable support, then re-snapshots the deck-local
+/// pose. `ground` is the mover's resolved support ([`super::mover::Outcome::ground`]).
 pub(super) fn update_attachment(
     player: &mut Player,
     transports: &TransportQuery,
@@ -74,16 +45,9 @@ pub(super) fn update_attachment(
     grounded: bool,
     swimming: bool,
 ) {
-    // Transport attach/detach (decision 0438 phase 2). Attach when the walkable support is a
-    // transport's collider — the boat's own hull, OR a deck prop's collider child (solid
-    // cargo, 0470): the walk resolves the support upward through the parent chain to the
-    // Transport that owns it, so standing on a crate is standing on the boat. Detach when
-    // support resolves to world geometry or we enter the water. Airborne keeps the current
-    // attachment — [`carry`] keeps composing, so a jump above the deck is deck-frame
-    // ballistics and lands where it took off (jumping off the side detaches at whatever it
-    // lands on). Then re-snapshot the local pose from this frame's FINAL world pose against
-    // the boat's (unchanged-this-frame) transform, which is what next frame's carry
-    // recomposes from.
+    // Attach on a transport's hull or a deck prop's collider child, found up the parent chain;
+    // detach on world geometry or in water. Airborne keeps the attachment, so a jump above the
+    // deck is deck-frame ballistics.
     let owning_transport = |mut e: Entity| {
         for _ in 0..4 {
             if let Ok((t, g, _)) = transports.get(e) {
@@ -118,13 +82,8 @@ pub(super) fn update_attachment(
         }
     }
     let feet = player.pos;
-    // **The ride trace** (`WOW_MOVE_TRACE_TAGS=ride`) — one line per frame while attached, plus
-    // the frame after a detach, because "what happened on the boat" is otherwise unanswerable:
-    // the deck's own motion is in the boat's transform, the rider's in world space, and the
-    // difference between them is the only thing that says whether the carry composed. The
-    // director's report — *stepped off a ledge on a boat and it threw me back across the boat
-    // until I landed* — is a statement about the DECK-relative path, which no other instrument
-    // here records.
+    // The `ride` trace (`WOW_MOVE_TRACE_TAGS=ride`): the deck-relative path, which no other
+    // instrument records, a line a frame while attached.
     if benilla_assets::trace::enabled_for("ride") {
         let boat_pose = player
             .ride
@@ -141,15 +100,9 @@ pub(super) fn update_attachment(
             let local = Quat::from_euler(EulerRot::YXZ, byaw, 0.0, 0.0)
                 .inverse()
                 .mul_vec3(feet - bpos);
-            // The deck's **broad-phase box**, and the gap from its underside to the feet. The
-            // candidate enumeration every mover probe rides
-            // (`SpatialQuery::aabb_intersections_with_aabb`) tests exactly this component —
-            // and avian refreshes it in `PhysicsSchedule` (`FixedPostUpdate`, *before*
-            // `Update`), while `tick_transports` writes the deck's pose *in* `Update`. So the
-            // box is always one frame of deck travel behind the deck, and on a long frame it
-            // is left behind entirely: a positive `gap` means the down-probe cannot even see
-            // the deck the feet are standing on, which is the difference between
-            // `support=deck` and `support=NONE` while `local` still reads (0, 0.05, 0).
+            // The deck's broad-phase box, which the mover probes' candidate query tests, trails the
+            // deck by a frame: avian refreshes it in `FixedPostUpdate`, before `tick_transports`
+            // moves the deck in `Update`. A positive `gap` hides the deck from the down-probe.
             let aabb_col = match baabb {
                 Some(a) => format!(
                     " | aabbY[{:8.2},{:8.2}] gap{:+7.2}",
@@ -185,8 +138,7 @@ pub(super) fn update_attachment(
                 ),
             );
         } else if !swimming {
-            // Not riding: only worth a line when something under us *is* a transport, i.e. the
-            // frames where an attach should have happened and did not.
+            // Not riding: a line only when standing on a transport, a missed attach.
             if let Some((_, _, guid)) = ground.and_then(owning_transport) {
                 benilla_assets::trace::line(
                     "ride",
diff --git a/crates/benilla-app/src/player/scoped_view.rs b/crates/benilla-app/src/player/scoped_view.rs
index 4ef170b1..3febad7c 100644
--- a/crates/benilla-app/src/player/scoped_view.rs
+++ b/crates/benilla-app/src/player/scoped_view.rs
@@ -1,29 +1,13 @@
-//! **The spyglass zoom** — `SPELL_AURA_FAR_SIGHT` (aura 76), which is not far sight at all.
+//! The spyglass zoom, `SPELL_AURA_FAR_SIGHT` (aura 76): a client-local camera override, unlike the
+//! server's `SPELL_AURA_BIND_SIGHT` far sight ([`super::view_subject`]), so no packet carries it.
+//! For the local player only (`0x5fa6d0`), the aura watcher `0x604d00` routes to `0x5ff350` (add)
+//! and `0x612320` (remove), which match each effect's `EffectApplyAuraName` (`SpellRec+0x16c`)
+//! against 76 and call `0x50d320(camera, EffectMiscValue[i])`: first person, locked (camera flag
+//! `0x8` makes `SetCameraView` return early), with `[camera+0x40] = n × π/180`; removal restores
+//! `π/2` and unlocks. The Ornate Spyglass (item 5507, spell 12883) passes 15, a 6× zoom.
 //!
-//! The Ornate Spyglass (item 5507 → spell 12883 "Longsight") reads like a member of the far-sight
-//! family and is filed with it in the bug ledger, but the two share only a name. Mind Vision and
-//! Sentry Totem are `SPELL_AURA_BIND_SIGHT`, a *server* mechanism: the server moves its own
-//! viewpoint and names the object in `PLAYER_FARSIGHT` ([`super::view_subject`]). Aura 76 is a
-//! **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.
-//!
-//! 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
-//! (`|= 0x8`) that makes `SetCameraView` early-return — so the view is *locked* — and writes
-//! `[camera+0x40] = n × π/180`. On removal it restores `π/2` and unlocks.
-//!
-//! So the spyglass is a locked first-person view at a **6× zoom**: `EffectMiscValue = 15` against a
-//! stored default of 90.
-//!
-//! **We copy the ratio, not the number, and that is deliberate.** The reference's `[camera+0x40]`
-//! and our [`CAM_FOVY`] are different quantities: theirs defaults to 90°, while ours is the
-//! *effective vertical* field of view and is 45° (≈ the reference's measured 44.1°). Writing 15°
-//! straight into our projection would be a third again too narrow. `15/90` is exact, dimensionless,
-//! and survives whatever our FOV constant is — the same reasoning `camera.rs` uses for the
-//! click-travel constants, where copying the reference's raw device units would have bound us to
-//! its mouse scaling.
+//! The ratio is applied, not the degrees: `[camera+0x40]` defaults to 90°, while our [`CAM_FOVY`]
+//! is the effective vertical field of view, 45° against the reference's measured 44.1°.
 
 use bevy::camera::{PerspectiveProjection, Projection};
 use bevy::prelude::*;
@@ -32,34 +16,29 @@ use crate::net::{ObjectStore, SelfPlayer};
 use crate::ui_action::Spells;
 use benilla_world::view::{WorldCamera, CAM_FOVY};
 
-/// `SPELL_AURA_FAR_SIGHT` — `0x4c`, the value the reference's effect walk compares against.
+/// `0x4c`, the aura name the reference's effect walk matches.
 const SPELL_AURA_FAR_SIGHT: u32 = 76;
 
-/// The reference's unzoomed `[camera+0x40]`, in degrees (`π/2`, its ctor default at `0x50a706`).
-/// Only ever a **denominator** here — see the module note on why we take the ratio.
+/// The reference's unzoomed `[camera+0x40]` in degrees (`π/2`, its constructor's value at
+/// `0x50a706`), used only as a denominator.
 const REFERENCE_DEFAULT_DEGREES: f32 = 90.0;
 
-/// The scope currently held, as a fraction of the normal field of view (`1.0` = unzoomed).
-///
-/// `None` is the overwhelmingly common case and means "no override at all" — distinct from
-/// `Some(1.0)`, which would still lock the camera into first person.
+/// The held scope as a fraction of the normal field of view. `None` is no override;
+/// `Some(1.0)` would still lock first person.
 #[derive(Resource, Default)]
 pub(crate) struct ScopedView {
     pub(crate) zoom: Option<f32>,
 }
 
 impl ScopedView {
-    /// True while a scope is held — the camera is locked into first person for as long as it is.
+    /// While a scope is held the camera is locked in first person.
     pub(crate) fn active(&self) -> bool {
         self.zoom.is_some()
     }
 }
 
-/// Read our own aura slots for aura 76 and drive the projection from it.
-///
-/// Local player only, exactly as the reference gates it: aura 76 on somebody *else* is none of our
-/// camera's business, and the field is public, so we would otherwise zoom whenever a nearby player
-/// raised a spyglass.
+/// Drives the projection from aura 76 in our own aura slots only, as the reference gates it: the
+/// aura field is public, so another player's spyglass must not zoom ours.
 pub(super) fn apply_scoped_view(
     self_q: Query<&ObjectStore, With<SelfPlayer>>,
     spells: Option<Res<Spells>>,
@@ -75,9 +54,7 @@ pub(super) fn apply_scoped_view(
             store.0.unit_auras().find_map(|slot| {
                 let rec = catalog.get(slot.spell_id)?;
                 (0..3).find_map(|i| {
-                    // The misc value is read from the SAME effect index that carries the aura
-                    // name — the reference indexes both by `i`. A spell whose aura 76 sits in
-                    // effect 2 would otherwise be read against effect 0's unrelated misc value.
+                    // The reference reads the misc value from the aura name's own effect index.
                     (rec.effect_apply_aura[i] == SPELL_AURA_FAR_SIGHT)
                         .then(|| rec.effect_misc_value[i] as f32)
                 })
@@ -102,8 +79,6 @@ pub(super) fn apply_scoped_view(
 mod tests {
     use super::*;
 
-    /// The ratio, and the two ways a naive port gets it wrong: writing the reference's 15 straight
-    /// into a projection whose default is 45°, or restoring to the reference's 90° instead of ours.
     #[test]
     fn the_spyglass_narrows_our_own_field_of_view_six_fold() {
         let scoped = ScopedView {
diff --git a/crates/benilla-app/src/player/server_ride.rs b/crates/benilla-app/src/player/server_ride.rs
index c197e54c..88826e67 100644
--- a/crates/benilla-app/src/player/server_ride.rs
+++ b/crates/benilla-app/src/player/server_ride.rs
@@ -1,26 +1,8 @@
-//! The self-spline ride: when a server-authored spline drives our own player — an `SMSG_MONSTER_MOVE`
-//! addressed to our guid — input yields, we ride it out, and we acknowledge `CMSG_MOVE_SPLINE_DONE`
-//! so the server hands control back. Warrior **Charge** is the first case (decision 0260); knockback,
-//! taxi flight, and fear reuse the same path.
-//!
-//! The mechanic, pinned live against vmangos: Charge is neither a teleport nor a knockback — the
-//! server moves the *caster* with the same `MoveSpline` machinery as any creature (a ground spline at
-//! run×4-capped-24 yd/s, facing the target), broadcasts it to the caster too, and for a player mover
-//! waits on `CMSG_MOVE_SPLINE_DONE` (the `MovementInfo` at the endpoint + the `splineId`) before it
-//! stops treating us as spline-controlled.
-//!
-//! Division of labour each frame while riding:
-//! - [`crate::net`]'s `sample_splines` (Net stage) advances the [`Spline`] into the entity
-//!   `Transform` — the horizontal authority for the ride. **Its Z is not authoritative** and never
-//!   was (decision 1927): the reference discards a grounded spline's vertical exactly as it does a
-//!   creature's, and [`ride_z`] re-derives it from the ground under us.
-//! - [`drive_self_ride`] (Input stage, *before* `control`) owns the *whole* pose while the ride
-//!   lasts: it mirrors that transform into [`Player`] (`pos`/`face_yaw`/`model_yaw`), drives a
-//!   forward-run animation via [`MovementState`], unwinds the strafe counter-twist ([`BodyTwist`]),
-//!   and — the frame the spline ends — emits the ack and clears the ride so `control` resumes from
-//!   the endpoint at rest.
-//! - `control`'s ride guard carries the follow-camera onto the moving avatar and skips input,
-//!   physics, and the outbound movement stream.
+//! The self-spline ride: a server spline driving our own player (an `SMSG_MONSTER_MOVE` naming our
+//! guid) owns the pose until it ends, then we ack `CMSG_MOVE_SPLINE_DONE` so the server hands
+//! control back. Charge, taxi flights and fear take this path; a charge is a ground spline at run
+//! speed × 4, capped at 24 yd/s (`PointMovementGenerator.cpp:278-281`). `sample_splines` advances
+//! the [`Spline`] into the entity `Transform`, and [`drive_self_ride`] owns the rest of the pose.
 
 use benilla_assets::coords::bevy_to_wow;
 use bevy::prelude::*;
@@ -30,9 +12,8 @@ use crate::net::{ClientCommand, Embodied, NetCommands, Spline, SplineStopped};
 
 use super::Player;
 
-/// The walkable surface under a ride's pose, measured the way every other mover's ground is —
-/// a one-sided down-ray through the same window `net::motion::spline`'s clamp uses, from the
-/// server's own Z rather than from any answer of ours. `None` = nothing in reach.
+/// The walkable surface under a ride's pose: a one-sided down-ray from the server's own Z, through
+/// the same window as `net::motion::spline`'s clamp.
 fn ride_ground(world: &benilla_world::collision::WorldCollision, pos: Vec3) -> Option<f32> {
     const UP: f32 = 2.5;
     const DOWN: f32 = 4.0;
@@ -42,31 +23,12 @@ fn ride_ground(world: &benilla_world::collision::WorldCollision, pos: Vec3) -> O
         .map(|h| origin.y - h.distance)
 }
 
-/// **The Z the body we are attached to rides at** — the ground under the spline's XZ, not the
-/// spline's own vertical (decision 1927).
-///
-/// 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`, 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
-///   the flight path;
-/// - **`SWIMMING`** (`[CMovement+0x40] & 0x200000`, one of the two bits at `0x616cfa`) — in liquid
-///   the wire Z *is* the depth, the same exemption the creature clamp takes;
-/// - a probe **miss** — nothing walkable in reach, so the body stays where the server put it.
-///
-/// The other bit at `0x616cfa` (`0x800`) has no expression here: our ride carries no live
-/// CMovement flag word of its own, and a knockback — the airborne case that would want it — is not
-/// a spline at all on this build (`SMSG_MOVE_KNOCK_BACK` is a ballistic launch through
-/// [`super::mover`], decision 1702), so it never reaches this function.
-///
-/// The arithmetic itself is [`crate::net::grounded_y`], shared with the creature clamp so the two
-/// cannot drift; hover and water-walking come from **our** state, not the granted-mode word — the
-/// avatar's modes live on [`super::state::MoveModes`], and the wire family the clamp reads is inert
-/// on us.
+/// The Z the ride stands at: the ground under the spline's XZ, not its vertical. The reference
+/// treats every mover alike: `0x616de0` hands the spline's displacement to `0x616cb0`, which zeroes
+/// the vertical for `0x634040`'s swept resolve. It keeps the vertical (`0x616cec`-`0x616d03`) for
+/// a flying spline (`MI.flags & 0x200`) and a swimmer (`[CMovement+0x40] & 0x200000`); the other
+/// bit it tests at `0x616cfa`, `0x800`, has no counterpart, as a knockback is not a spline here.
+/// Hover and water walking come from our [`super::state::MoveModes`], not the wire's mode word.
 fn ride_z(
     player: &Player,
     points: &benilla_world::world_point::WorldPoint,
@@ -89,34 +51,27 @@ fn ride_z(
     crate::net::grounded_y(pos.y, floor, water, player.modes.hover)
 }
 
-/// Extract the Bevy Y-yaw of a facing quaternion. The net bridge and `sample_splines` both write
-/// the self entity's rotation as `Quat::from_rotation_y(facing)` (a pure Y turn), and benilla's
-/// Bevy yaw equals the WoW orientation (decision 0002), so this recovers both the controller's
-/// `face_yaw` and the wire orientation. Shared with the take-control edge (`wire_in`), which adopts
-/// the streamed spawn pose's facing the same way.
+/// The yaw of a pure-Y facing rotation, as the net bridge and `sample_splines` write it; Bevy yaw
+/// equals the WoW orientation, so this is both `face_yaw` and the wire orientation.
 pub(super) fn yaw_of(rotation: Quat) -> f32 {
     rotation.to_euler(EulerRot::YXZ).0
 }
 
-/// Mirror an in-progress self-spline into [`Player`], and ack it when it ends. Runs in
-/// [`benilla_world::schedule::WorldStage::Input`] just before `control`, so the pose it publishes is what the
-/// camera seats on and the animation reads this frame.
+/// Mirror an in-progress self-spline into [`Player`] and ack it when it ends; runs just before
+/// `control`, so the camera and the animation read this frame's pose.
 #[allow(clippy::type_complexity)] // a Bevy query's component tuple
 pub(super) fn drive_self_ride(
     net: Res<NetCommands>,
     mut commands: Commands,
     mut player: ResMut<Player>,
-    // The world under the ride: the surface it stands on ([`ride_z`]) and the liquid a
-    // water-walker stands on instead.
+    // The ground and the liquid under the ride, for `ride_z`.
     world: benilla_world::collision::WorldCollision,
     points: benilla_world::world_point::WorldPoint,
     mut q: Query<
         (
             Entity,
-            // **Written, not just read**: the ride's Z is re-derived here ([`ride_z`]) and the
-            // entity transform is where it has to land. `control`'s ride guard returns before
-            // `body_pose::drive`, so nothing downstream would carry a correction made only to
-            // `Player` — the camera and the wire would move and the rendered body would not.
+            // Written: the corrected Z must land on the entity, as `control`'s ride guard returns
+            // before `body_pose::drive` would carry it.
             &mut Transform,
             Option<&Spline>,
             Option<&SplineStopped>,
@@ -126,8 +81,7 @@ pub(super) fn drive_self_ride(
         With<Embodied>,
     >,
 ) {
-    // Only while we hold control (post-login). A free-fly detach (`F`) abandons any ride rather than
-    // yanking the parked camera — rare, and the spline still finalizes server-side.
+    // Only while we hold control; a free-fly detach abandons the ride (the server still ends it).
     if !player.active || player.detached {
         player.server_riding = false;
         return;
@@ -135,13 +89,9 @@ pub(super) fn drive_self_ride(
     let Ok((entity, mut transform, spline, stopped, motion, twist)) = q.single_mut() else {
         return;
     };
-    // A teleport landed since last frame: the server relocated us, voiding any in-progress ride
-    // (the taxi flight-end teleport beats our own spline end by ~latency — vmangos's spline-done
-    // handler ignores acks while its teleport is pending, so the relocation IS the hand-back; no
-    // `CMSG_MOVE_SPLINE_DONE` is owed, and the teleport ack + position report already went out).
-    // Mirroring the still-present spline this frame would clobber the snap back to the stale
-    // flight pose — the 4-yd hover whose settle probe then missed the ground for the full 6 s
-    // timeout at every taxi landing (decision 0501).
+    // A teleport since last frame (a taxi landing beats our spline's end) voids the ride and owes
+    // no ack: vmangos ignores a spline-done while teleporting (`MovementHandler.cpp:819-820`), and
+    // mirroring the stale spline would undo the snap.
     if std::mem::take(&mut player.ride_abort) {
         if spline.is_some() {
             commands.entity(entity).remove::<Spline>();
@@ -169,37 +119,22 @@ pub(super) fn drive_self_ride(
                     spline.speed(),
                     spline.duration.as_millis(),
                 );
-                // **A spline re-authors the walk gait, and its RUNMODE bit is inverted** (decision
-                // 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
-                // did NOT mark as a run leaves the body in walk mode when the ride ends, and a path
-                // it did mark clears any walk the player had toggled. The two `0x100`s are inverses.
-                //
-                // On the START edge only, matching the byte site: the commit runs once per spline,
-                // not per sampled frame. It writes the same latch the keybind does, so the wire
-                // announces it through the ordinary flag differ on the frame the ride hands back.
+                // Each spline sets the walk gait from its `SPLINEFLAG_RUNMODE`, inverted: the
+                // reference passes the bit to `SetRunMode` (`0x7c6ac2` → `0x7c71c0`), whose
+                // argument is run. Once per spline, into the keybind's latch.
                 player.walking = !spline.run_mode;
                 super::move_trace::gait("spline", player.walking, false, player.modes.rooted, true);
             }
             let yaw = yaw_of(transform.rotation);
             let wire_y = transform.translation.y;
-            // One probe, one meaning: the floor found from the SERVER's own pose feeds both the
-            // law and the line that reports it. Measuring again from the corrected pose would be a
-            // different question, and would report the correction as if it were the ground.
+            // One probe from the server's pose feeds both the Z and its trace line.
             let floor = ride_ground(&world, transform.translation);
             let y = ride_z(
                 &player,
                 &points,
-                // **A deck path re-derives its Z exactly like any other** (decision 1936's
-                // correction). The tempting exemption — "there is no terrain under a boat" — is
-                // refuted: the transport guid appears in neither `0x616cb0`'s predicate nor
-                // `0x634040`'s dispatch, so a grounded deck spline takes the same fork, and the
-                // probe does not miss because it runs at the **composed world position** against
-                // a class mask that admits GameObject meshes. This system is in `WorldStage::Input`
-                // and `transport::compose_riders` in the stage before it, so the translation read
-                // here is already composed — nothing else is needed for the deck case.
+                // A deck path grounds like any other (the transport guid is in neither
+                // `0x616cb0`'s predicate nor `0x634040`'s dispatch); `transport::compose_riders`
+                // has already composed the world pose, and the probe admits GameObject meshes.
                 spline.grounded,
                 transform.translation,
                 floor,
@@ -207,8 +142,7 @@ pub(super) fn drive_self_ride(
             if y != wire_y {
                 transform.translation.y = y;
             }
-            // Traced with the answer in hand, not the question: a line logged before the correction
-            // measures the wire and reads identically whether the law above runs or not.
+            // Traced after the correction, so the line shows it.
             super::move_trace::ride(
                 spline.id,
                 spline.grounded,
@@ -222,8 +156,7 @@ pub(super) fn drive_self_ride(
             player.server_riding = true;
             player.ride_spline_id = spline.id;
             player.ride_grounded = spline.grounded;
-            // A forward run — the charge reads as a fast run (the gait selector keys on the FORWARD
-            // flag + speed). It also gives a sane baseline for the resume and for observers.
+            // A forward run: the gait selector keys on FORWARD and speed.
             player.move_flags = move_flags::FORWARD;
             if let Some(mut motion) = motion {
                 motion.speed = spline.speed();
@@ -231,25 +164,17 @@ pub(super) fn drive_self_ride(
                 motion.flags = move_flags::FORWARD;
                 motion.stand_state = 0;
             }
-            // The ride is a forward run, and the display-facing law's moving-forward case (the
-            // `flags & 0x2003` snap — decisions 0101/0103) puts the body ON the aim: no gap, no
-            // counter-twist — the same one-frame unwind as releasing a strafe key while running.
-            // `control`, the normal gap owner, is parked behind the ride guard, so without this
-            // write a charge engaged mid-strafe rode the whole spline with the spine/head frozen
-            // ±90° off the run (the director's strafe-engage report).
+            // Moving forward puts the body on the aim (the `flags & 0x2003` snap), so no
+            // counter-twist; `control`, the gap's normal owner, is parked behind the ride guard.
             if let Some(mut twist) = twist {
                 twist.yaw_gap = 0.0;
             }
         }
-        // The ride just ended: `sample_splines` wrote the endpoint transform this frame and then
-        // dropped the `Spline`. Sync to that exact endpoint, ack the server — it holds us as
-        // spline-pending until this arrives, then relocates us and broadcasts a stop to observers —
-        // and clear the ride so `control` resumes its own stream from rest.
+        // The ride ended: `sample_splines` wrote the endpoint and dropped the `Spline`. On the ack,
+        // vmangos relocates us and broadcasts a stop (`MovementHandler.cpp:830-841`).
         None if player.server_riding => {
-            // The endpoint is grounded by the same law as every frame before it: this pose is what
-            // `CMSG_MOVE_SPLINE_DONE` reports and what `control` resumes from, and a ride that ends
-            // a hair off our terrain is exactly what decision 0501's settle-probe hunt was about.
-            // `grounded` is read off the path that just finished — the last spline seen this ride.
+            // The endpoint grounds by the same law: it is what the ack reports and `control`
+            // resumes from. `ride_grounded` is the last spline's, as the `Spline` is gone.
             let floor = ride_ground(&world, transform.translation);
             let y = ride_z(
                 &player,
@@ -267,17 +192,12 @@ pub(super) fn drive_self_ride(
             player.server_riding = false;
             player.move_flags = 0;
             player.airborne_since = None;
-            // "Resumes from the endpoint at rest" (decision 0260) — including the velocities. The
-            // mover re-derives them only when it reads grounded; a ride ending a hair above our
-            // terrain (navmesh Z vs ours) would otherwise inherit the pre-ride momentum — e.g. a
-            // strafe-engaged charge sliding sideways out of its landing.
+            // At rest, velocities too: the mover re-derives them only when grounded, so a ride
+            // ending a hair above our terrain would inherit the pre-ride momentum.
             player.vel_y = 0.0;
             player.horiz_vel = Vec3::ZERO;
-            // **Whose id?** The one the server is actually waiting on. A ride that ran to its own
-            // end leaves the path's id as the newest, but a ride the server *cut short* was cut by
-            // launching a fresh stop spline, and vmangos checks the ack against that newest id
-            // (`HandleMoveSplineDone`) — so an interrupted flee or charge acked with the path's id
-            // is silently rejected, and every movement packet after it is dropped (decision 1281).
+            // The newest spline id: a cut-short ride ended in a fresh stop spline, and vmangos
+            // ignores an ack for an older one (`MovementHandler.cpp:807`), then drops our movement.
             let spline_id = stopped.map_or(player.ride_spline_id, |s| s.0);
             if stopped.is_some() {
                 commands.entity(entity).remove::<SplineStopped>();
@@ -289,9 +209,8 @@ pub(super) fn drive_self_ride(
                 spline_id,
             });
         }
-        // A stop with no ride behind it — the server halting a body it was already holding still
-        // (the fear that ends between flee paths, the possession's opening `StopMoving`). It arms
-        // the same wait and owes the same answer.
+        // A stop with no ride behind it (a fear ending between flee paths, a possession's opening
+        // `StopMoving`) arms the same wait and owes the same ack.
         None if stopped.is_some() => {
             let id = stopped.expect("checked above").0;
             commands.entity(entity).remove::<SplineStopped>();
@@ -318,16 +237,12 @@ mod tests {
         ride_app_with(true, false)
     }
 
-    /// …parameterised by the spline's `SPLINEFLAG_RUNMODE` and the walk gait the player had
-    /// toggled before the ride took over.
     fn ride_app_with(
         run_mode: bool,
         walking: bool,
     ) -> (App, Entity, crossbeam_channel::Receiver<ClientCommand>) {
         let mut app = App::new();
-        // The ride reads the world under it (the `rid` probe, and the ground the Z law stands on),
-        // so the harness has to be a world — an empty one, which answers "no ground in reach" and
-        // leaves every assertion below about the ride's own bookkeeping, as they were.
+        // An empty world, whose probes answer "no ground in reach".
         app.init_resource::<benilla_world::collision::MoverTraceExclusions>();
         app.add_plugins((
             MinimalPlugins,
@@ -374,24 +289,16 @@ mod tests {
         (app, entity, rx)
     }
 
-    /// **The ride's Z law** (decision 1927) — the local half of B357, measured live at +0.47 yd on
-    /// a 16-yd Elwynn charge before it landed, and 0.000 after.
-    ///
-    /// The world is one flat floor and the ride is seated a chord's height above it, which is the
-    /// whole of the defect: a two-point server path holds its endpoints' Z across everything
-    /// between them, so on any concave ground the body flies. The reference does not: `0x616de0`
-    /// hands the spline path's displacement to the same `0x616cb0` the physics path uses, which
-    /// zeroes the vertical and lets the swept resolve read Z off the surface.
+    /// The ride's Z on one flat floor, with the body seated a chord's height above it.
     mod ground {
         use super::*;
         use avian3d::prelude::{Collider, RigidBody};
 
         const FLOOR_Y: f32 = 7.5;
-        /// Where the server's chord holds the body — a body-height over the floor, inside the
-        /// probe's own reach so what is measured is the law and not the window.
+        /// A body-height over the floor, inside the probe's reach.
         const CHORD_Y: f32 = 9.4;
 
-        /// A 20×20 up-wound floor at [`FLOOR_Y`] — the one-sided down-ray stands only on those.
+        /// A 20×20 up-wound floor at [`FLOOR_Y`]; the one-sided down-ray hits only up-wound faces.
         fn floor(app: &mut App) {
             let v = vec![
                 Vec3::new(-10.0, FLOOR_Y, -10.0),
@@ -406,10 +313,7 @@ mod tests {
             ));
         }
 
-        /// Seat the body on the chord, with the collider trees built. The seating `update` runs a
-        /// ride frame too — harmlessly, from `Transform::default()`, where the probe cannot reach a
-        /// floor 7.5 yd overhead — so each test below sets its own condition and then takes
-        /// **exactly one** frame, which is the frame it asserts about.
+        /// Seat the body on the chord, colliders built; each test then takes exactly one frame.
         fn seat(app: &mut App, entity: Entity) {
             app.update();
             app.world_mut()
@@ -420,7 +324,6 @@ mod tests {
                 .y = CHORD_Y;
         }
 
-        /// The ride app with ground under it (or deliberately without) and the body on the chord.
         fn world(with_floor: bool) -> (App, Entity) {
             let (mut app, entity, _rx) = ride_app();
             if with_floor {
@@ -443,9 +346,6 @@ mod tests {
             );
         }
 
-        /// **The report's shape, on our own body.** The chord is discarded; the ground is the Z —
-        /// and `Player::pos` carries the same answer, because the camera and the outbound position
-        /// report read it, not the transform.
         #[test]
         fn a_grounded_ride_stands_on_the_world_not_the_chord() {
             let (mut app, entity) = world(true);
@@ -457,9 +357,7 @@ mod tests {
             );
         }
 
-        /// **A flying path owns its own altitude** — the reference keeps the vertical when the
-        /// spline carries FLYING (`0x616cec` reads the MI flag word). A taxi must not be walked
-        /// into the hillside it passes over.
+        /// The reference keeps a flying spline's vertical (`0x616cec`).
         #[test]
         fn a_flying_ride_keeps_its_altitude() {
             let (mut app, entity) = world(true);
@@ -472,9 +370,7 @@ mod tests {
             assert_eq!(y_of(&app, entity), CHORD_Y, "a flight is not grounded");
         }
 
-        /// **In liquid the wire Z IS the depth** — the same exemption the creature clamp takes, and
-        /// the reference's own: `[CMovement+0x40] & 0x200000` SWIMMING keeps the vertical at
-        /// `0x616cfa`. A feared swimmer must not be dragged to the lakebed.
+        /// SWIMMING keeps the vertical (`0x616cfa`), so a feared swimmer stays off the lakebed.
         #[test]
         fn a_swimming_ride_keeps_its_depth() {
             let (mut app, entity) = world(true);
@@ -483,9 +379,6 @@ mod tests {
             assert_eq!(y_of(&app, entity), CHORD_Y, "swimming keeps the wire Z");
         }
 
-        /// **A probe miss leaves the body where the server put it** — nothing walkable in reach is
-        /// a genuinely airborne pose or ground that has not streamed in, and an unclamped body
-        /// belongs at its seat. Same answer the creature clamp gives.
         #[test]
         fn a_ride_with_no_ground_in_reach_keeps_the_servers_pose() {
             let (mut app, entity) = world(false);
@@ -493,18 +386,15 @@ mod tests {
             assert_eq!(y_of(&app, entity), CHORD_Y, "no floor, no correction");
         }
 
-        /// **The endpoint is grounded too, and it is the pose the ack carries.** The frame a ride
-        /// ends has already lost its `Spline` (`sample_splines` drops a finished path), so the law
-        /// reads `Player::ride_grounded` there — without it the last frame of every charge would
-        /// hand the server the chord's Z and resume the controller from mid-air.
+        /// The end frame has no `Spline`, so the law reads `Player::ride_grounded`.
         #[test]
         fn the_endpoint_the_ack_reports_is_grounded() {
             let (mut app, entity, rx) = ride_app();
             floor(&mut app);
             seat(&mut app, entity);
-            app.update(); // one riding frame — arms `server_riding` + `ride_grounded`
+            app.update(); // one riding frame: arms `server_riding` and `ride_grounded`
             app.world_mut().entity_mut(entity).remove::<Spline>();
-            // Put it back on the chord, as the finished path's last sample leaves it.
+            // Back on the chord, as the finished path's last sample leaves it.
             app.world_mut()
                 .entity_mut(entity)
                 .get_mut::<Transform>()
@@ -528,31 +418,22 @@ mod tests {
         }
     }
 
-    /// **A spline re-authors the walk gait, inverted from its own RUNMODE bit** (decision 1758).
-    /// The reference does this in the `SMSG_MONSTER_MOVE` commit `0x7c6a50`, unconditionally for
-    /// every incoming spline: `0x7c6ac2 and edi,0x100` takes `SPLINEFLAG_RUNMODE` and `0x7c6acb`
-    /// hands it to `SetRunMode 0x7c71c0`, whose argument is *run*. The two `0x100`s are inverses,
-    /// which is the whole reason this is a test and not an obvious line of code — reading it the
-    /// natural way round gets the behaviour exactly backwards in both directions.
+    /// `SPLINEFLAG_RUNMODE` and `MOVEFLAG_WALK_MODE`, both `0x100`, are inverses (`0x7c6a50`).
     #[test]
     fn a_spline_re_authors_the_walk_gait_from_its_inverted_runmode_bit() {
-        // A path the server did NOT mark as a run leaves the body walking — even though the
-        // player was running when it took over.
         let (mut app, _e, _rx) = ride_app_with(false, false);
         app.update();
         assert!(
             app.world().resource::<Player>().walking,
             "a spline without RUNMODE forces walk mode ON"
         );
-        // …and a run path clears a walk the player had toggled.
         let (mut app, _e, _rx) = ride_app_with(true, true);
         app.update();
         assert!(
             !app.world().resource::<Player>().walking,
             "a spline WITH RUNMODE clears the toggled walk"
         );
-        // The start edge only: the commit runs once per spline, not once per sampled frame, so a
-        // toggle taken mid-ride survives the rest of it.
+        // Once per spline: a toggle taken mid-ride survives.
         let (mut app, _e, _rx) = ride_app_with(true, true);
         app.update();
         app.world_mut().resource_mut::<Player>().walking = true;
@@ -565,9 +446,6 @@ mod tests {
 
     #[test]
     fn engaging_a_ride_mid_strafe_unwinds_the_counter_twist() {
-        // The ride owns the pose: `control` (the normal gap owner) is parked behind the ride
-        // guard, so the ride itself must zero the strafe counter-twist — frozen at ±90°, the
-        // avatar charged the whole spline with its spine/head twisted off the run direction.
         let (mut app, entity, _rx) = ride_app();
         app.update();
         assert!(app.world().resource::<Player>().server_riding);
@@ -578,9 +456,6 @@ mod tests {
         );
     }
 
-    /// The landing teleport voids the ride (decision 0501): the server relocates us at ITS
-    /// flight end, before our own spline finishes — the mirror must not clobber the snap, the
-    /// spline drops, and no `CMSG_MOVE_SPLINE_DONE` goes out (vmangos ignores it mid-teleport).
     #[test]
     fn a_teleport_aborts_the_ride_without_an_ack() {
         let (mut app, entity, rx) = ride_app();
@@ -593,7 +468,7 @@ mod tests {
             app.world().get::<Spline>(entity).is_none(),
             "the spline is dropped with the ride"
         );
-        app.update(); // and the ride-end arm must NOT fire afterwards (server_riding cleared)
+        app.update(); // the ride-end arm must not fire after it
         assert!(
             rx.try_recv().is_err(),
             "no MoveSplineDone — the teleport relocation superseded the ride"
diff --git a/crates/benilla-app/src/player/setup.rs b/crates/benilla-app/src/player/setup.rs
index a0b422ee..3b3e137f 100644
--- a/crates/benilla-app/src/player/setup.rs
+++ b/crates/benilla-app/src/player/setup.rs
@@ -1,6 +1,4 @@
-//! Startup: spawn the camera and seed the avatar resources the [`super::control`] system then drives.
-//! Split from the controller because it's a one-shot `Startup` system (a distinct schedule phase), not
-//! the per-frame loop — the plugin remains the stable face that wires both.
+//! Startup: spawns the world camera and seeds the avatar resources [`super::control`] drives.
 
 use avian3d::prelude::*;
 use bevy::camera::{CameraOutputMode, PerspectiveProjection, Projection};
@@ -19,19 +17,12 @@ use super::{
     CAPSULE_RADIUS,
 };
 
-/// Default avatar speed in yards/second — the **VERIFIED** vanilla run speed (`MOVE_RUN` 7.0). Ctrl
-/// sprints 2.5× (≈17.5) for getting around; `$WOW_MOVE_SPEED`
-/// overrides. (Was 60.0 as a fly-around convenience before collision; the faithful default now that
-/// the character controller is in.)
+/// The stock run speed, `MOVE_RUN` 7.0 yd/s, until the server's speeds stream in.
 const DEFAULT_MOVE_SPEED: f32 = 7.0;
 
-/// The world camera's `Camera` — output mode `Skip` (decisions 2206 and 2234,
-/// [`benilla_world::final_pass`]): nothing writes this camera's target, and bevy's `upscaling`
-/// blit — a pure copy of the finished frame into it — is skipped. The world's final pass, the
-/// FFXGlow combine, is the first draw of the player-UI camera's main pass now
-/// (`benilla_world::ffx_glow::FfxBackdrop`), reading this view's finished main texture straight
-/// into the interface's byte buffer; the target the camera carries is a size-carrier only
-/// ([`crate::world_backdrop`]).
+/// The world camera's `Camera`, output mode `Skip` ([`benilla_world::final_pass`]): no upscaling
+/// blit, as the player-UI camera's first draw, the FFXGlow combine, reads this view's main texture.
+/// The target only carries the size ([`crate::world_backdrop`]).
 fn world_camera_output() -> Camera {
     Camera {
         output_mode: CameraOutputMode::Skip,
@@ -43,9 +34,7 @@ fn spawn_fallback_camera(commands: &mut Commands, msaa: Msaa) {
     commands.spawn((
         Camera3d::default(),
         WorldCamera,
-        // The same level the real camera takes — this one used to name nothing at all, which
-        // (`Camera` requires `Msaa`, defaulting to `Sample4`) meant a data-less free-fly quietly
-        // ran four samples no matter what the player had set. Decision 1629.
+        // The player's level: `Camera` requires `Msaa`, which would default to `Sample4`.
         msaa,
         Hdr,
         Tonemapping::None,
@@ -60,15 +49,13 @@ fn spawn_fallback_camera(commands: &mut Commands, msaa: Msaa) {
     ));
 }
 
-/// Startup: insert the move speed + avatar state, and spawn the camera. With client data present the
-/// camera sits above the spawn with the scene `AmbientLight`/`DistanceFog` (driven each frame by
-/// `update_time_lighting`) + a radius-derived far plane; without it, a plain free-fly fallback camera.
+/// Inserts the move speed and avatar state and spawns the world camera above the spawn, or a plain
+/// free-fly camera without client data.
 pub(super) fn setup_player(
     mut commands: Commands,
     config: Option<Res<RenderConfig>>,
     world_assets: Option<Res<WorldAssets>>,
-    // The pending `gxMultisample` (decision 1629), already resolved: this system is ordered after
-    // [`crate::cvars::CvarLoad`], so `config.toml` has been folded in before the camera is born.
+    // `gxMultisample` with `config.toml` folded in: this runs after [`crate::cvars::CvarLoad`].
     msaa: Res<benilla_world::view::MsaaSetting>,
 ) {
     let env_speed = std::env::var("WOW_MOVE_SPEED")
@@ -79,8 +66,7 @@ pub(super) fn setup_player(
         env_override: env_speed.is_some(),
     });
     commands.insert_resource(Player::default());
-    // The character capsule swept by avian's `MoveAndSlide` (length = cylinder segment between the
-    // hemisphere centres, so total height is `length + 2·radius`).
+    // Avian's capsule length is the segment between the hemisphere centres.
     commands.insert_resource(PlayerCapsule(Collider::capsule(
         CAPSULE_RADIUS,
         CAPSULE_HEIGHT - 2.0 * CAPSULE_RADIUS,
@@ -89,108 +75,68 @@ pub(super) fn setup_player(
         distance: CAM_DIST_DEFAULT,
         target_distance: CAM_DIST_DEFAULT,
         collision_distance: CAM_DIST_DEFAULT,
-        // Start opaque so the avatar never flashes invisible before `control`'s first fade computation.
+        // Opaque until `control` first computes the fade.
         self_fade_alpha: 1.0,
         ..default()
     });
 
-    // No client data → free-fly an empty scene.
+    // No client data: free-fly an empty scene.
     let (Some(_), Some(_)) = (config, world_assets) else {
         spawn_fallback_camera(&mut commands, msaa.level());
         return;
     };
 
-    // Camera starts above the spawn (terrain streams in around it); `control` repositions it
-    // third-person once we're in the world. The projection far is the horizon plane
-    // (`view::CAM_FAR`); the detailed world ends at `farclip`, by the wall, not by this plane.
+    // Above the spawn until `control` seats it. The far plane is the horizon (`view::CAM_FAR`); the
+    // detailed world ends at `farclip`, by the wall.
     let spawn = wow_to_bevy([SPAWN_XY.0, SPAWN_XY.1, 100.0]);
     let cam_far = CAM_FAR;
     let mut world_cam = commands.spawn((
         Camera3d::default(),
-        // THE world camera (the portrait booths are further `Camera3d`s — every "where is the viewer"
-        // consumer filters on this marker, never on bare `Camera3d`; see its doc).
+        // The portrait booths are `Camera3d`s too: viewer queries filter on this marker.
         WorldCamera,
-        // The player's `gxMultisample` (decision 1629), read ONCE here and never again — the
-        // reference registers this CVar *latched* and its callback echoes "set pending gxRestart",
-        // so a change is pending until the next launch. Which is also the only thing we could do:
-        // swapping MSAA live leaves our post passes (glow/egui) MSAA-mismatched and freezes the
-        // view. `$WOW_MSAA` still overrides it session-only, through the resource's `Default`.
+        // `gxMultisample` is read once: the reference latches it, pending until the next launch,
+        // and a live swap would mismatch our post passes. `$WOW_MSAA` overrides it for a session.
         msaa.level(),
         Projection::from(PerspectiveProjection {
             far: cam_far,
-            // The registered default, and only for frame zero: `view::stamp_near_clip` re-stamps
-            // this from the live `nearclip` every frame, exactly as `0x511bc0` overwrites whatever
-            // the reference's camera ctor left in `[cam+0x38]` (2163).
+            // Frame zero only: `view::stamp_near_clip` re-stamps the live `nearclip` every frame,
+            // as `0x511bc0` overwrites the reference camera's `[cam+0x38]`.
             near: NEARCLIP_DEFAULT,
             fov: CAM_FOVY,
             ..default()
         }),
-        // HDR render target (linear `Rgba16Float`) — the prerequisite for Bevy's `Bloom`. `Hdr` is a
-        // marker component (`Bloom` requires it; added explicitly for clarity). Option 1 keeps the
-        // vanilla look: `Tonemapping::None` (no filmic curve — the shaders still light in clamped gamma
-        // space and output the same values), so the HDR pipeline reproduces the LDR look while letting
-        // Bevy's bloom replace the hand-rolled `glow.rs`. (Option 2, on a branch, swaps in a filmic
-        // tonemapper + scene-referred lighting for a modern look.)
+        // A linear `Rgba16Float` target without tonemapping: the shaders light in clamped gamma
+        // space, so the output matches an 8-bit target.
         Hdr,
         Tonemapping::None,
-        // The faithful FFXGlow pass (decision 0158/0161): the byte-pinned `scene + glow·blur²`.
-        // This view runs its blur; its combine is the UI camera's own ground pass (2234).
+        // FFXGlow, `scene + glow·blur²`: the blur here, the combine in the UI camera's ground pass.
         benilla_world::ffx_glow::FfxGlow::WORLD,
         world_camera_output(),
         Transform::from_translation(spawn + Vec3::new(0.0, 60.0, 60.0)).looking_at(spawn, Vec3::Y),
-        // PHASE 0: no PBR ambient fill, no distance fog — pitch-black clean slate. The faithful scene
-        // light is rebuilt in-shader from Light.dbc (terrain/model WGSL), not via Bevy PBR lights.
+        // No Bevy ambient or fog: the scene light is computed in-shader from Light.dbc.
         FlyCam {
             yaw: 0.0,
             pitch: -0.5,
             speed: 100.0,
         },
     ));
-    // `WOW_NO_INDIRECT=1` — opt the world camera out of indirect draws + GPU culling. An
-    // EXPERIMENT knob (the full-picture sizing): wgpu 27 dropped MULTI_DRAW_INDIRECT from
-    // bevy's gate, so 0.18 is the first release where Metal reaches `Culling` mode — silently.
-    // This knob restores the pre-0.18 mode for an A/B. It must ride the SPAWN: the phase
-    // cache latches the preprocessing mode the first time it sees the view.
+    // `WOW_NO_INDIRECT=1` opts out of indirect draws and GPU culling for an A/B; it rides the
+    // spawn, as the phase cache latches the preprocessing mode on first sight of the view.
     if std::env::var_os("WOW_NO_INDIRECT").is_some() {
         world_cam.insert(bevy::render::view::NoIndirectDrawing);
     }
-    // Bevy's clustered-forward light assignment is OFF on the world camera by default (the
-    // 1370 bracket surfaced the lane; the 3-round SW split then measured the skip at −0.28
-    // cpu_ms): every world shader takes its point-light term off OUR storage buffer
-    // (`lighting::global_light` — bevy's clusterable buffer is fragment-only in the view
-    // layout and nothing of ours imports `apply_pbr_lighting`; the WDL far ring is unlit), so
-    // the whole assign/extract/prepare cluster lane is dead work proportional to the resident
-    // `PointLight` population (794 at the SW pin). `ClusterConfig::None` short-circuits
-    // `assign_objects_to_clusters` per view and starves the light extract/prepare downstream;
-    // the `Clusters` component stays, so the view bind group still builds. Scoped to THIS
-    // camera: the booth/pane cameras keep bevy's default.
-    // `WOW_CLUSTERS=1` restores bevy's upstream default (the A/B lever back).
+    // No clustered light assignment here: world shaders take point lights from our own buffer
+    // (`lighting::global_light`). `Clusters` stays so the view bind group builds; other cameras
+    // keep bevy's default, and `WOW_CLUSTERS=1` restores it on this one.
     if std::env::var_os("WOW_CLUSTERS").is_none() {
         world_cam.insert(bevy::light::cluster::ClusterConfig::None);
     }
 }
 
-/// The world camera's demand gate (decision 0540): active in world or under the opaque loading
-/// screen — never behind the glue screens, where the streamed world (25 tiles, tens of thousands
-/// of entities, MSAA 4×) otherwise renders unseen behind an opaque fullscreen glue scene every
-/// frame. The loading-screen case is load-bearing: that covered render is what compiles the
-/// world's pipelines, so the first visible in-world frame doesn't hitch on shader builds.
-/// Capture runs boot straight `InWorld` (`CharSelectPlugin::start`) — always active there.
-///
-/// This gate stays deliberately WIDER than [`benilla_world::schedule::world_is_live`], which decides
-/// whether the world is *loaded* at all (decision 0777): the camera must also render while the
-/// cover is up, which is exactly the window in which the world is streaming in.
-///
-/// **…but not on the frame the cover owes the glass.** 0962's rule, third consumer: on world
-/// entry the state flips a frame after the raise, so the flip frame is the first whose render can
-/// draw the loading screen — and this gate turned the world camera on for that exact frame, which
-/// then rendered a three-thousand-entity world with every pipeline cold *before* it could present
-/// the cover. Measured: 57 of that frame's 60 ms, and what stayed on the glass throughout was the
-/// character-select screen, frozen (the director's report). Held off until
-/// [`EntryCover::presented`], the camera loses three frames of warm-up out of the seconds it gets
-/// and the cover reaches the glass on the frame it was drawn for. Nothing is *shown* by the
-/// deferral — the loading root is an unconditional fullscreen black node, so a frame with no
-/// world camera is the same picture the cover would have drawn over anyway.
+/// Runs the world camera in world or under the opaque loading screen, never behind the glue
+/// screens; the covered render compiles the world's pipelines before the first visible frame. It
+/// is wider than `world_is_live`, as the world streams in under the cover, but waits until the
+/// cover is presented, so the cover's first frame is not spent on a cold world render.
 pub(super) fn gate_world_camera(
     state: Res<State<crate::char_select::ClientState>>,
     loading: Res<crate::loading_screen::LoadingScreen>,
diff --git a/crates/benilla-app/src/player/state.rs b/crates/benilla-app/src/player/state.rs
index 26547cc2..2adbcaf2 100644
--- a/crates/benilla-app/src/player/state.rs
+++ b/crates/benilla-app/src/player/state.rs
@@ -1,417 +1,166 @@
-//! The avatar's shared state + the movement constants — [`Player`] (the controller's resource),
-//! its transport attachment ([`PlayerRide`]), the capsule/speed resources, and every binary-derived
-//! movement constant the controller family reads. Pure state, no systems: [`super::control`] and
-//! the concern modules beside it (`mover`, `swim`, `arc`, `movement_net`, …) all borrow from here.
+//! The avatar's state, [`Player`] and its resources, and the movement constants; no systems.
 
 use avian3d::prelude::*;
 use benilla_protocol::{JumpInfo, MoveMode};
 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** —
-/// 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
-/// ~36% shorter — no separate constant.
+/// Backpedal over run, the stock 4.5 / 7.0, for the synthetic speed set used under a
+/// `$WOW_MOVE_SPEED` override or before the create block brings the server's speeds.
 pub(super) const RUN_BACK_RATIO: f32 = 4.5 / 7.0;
 
-/// Walk speed as a fraction of run: vanilla `MOVE_WALK` 2.5 / `MOVE_RUN` 7.0 — the sibling of
-/// [`RUN_BACK_RATIO`], and used the same way and only for the same reason: `$WOW_MOVE_SPEED`
-/// replaces the server's speed set outright, and the walk gait has to stay a walk under it
-/// rather than becoming a second run. The live number is always the server's (`MoveSpeeds::walk`,
-/// seeded by the create block and moved by `SMSG_FORCE_WALK_SPEED_CHANGE`); this ratio never
-/// reaches a real session (decision 1752).
+/// Walk over run, the stock 2.5 / 7.0, for the same synthetic speed set as [`RUN_BACK_RATIO`].
 pub(super) const WALK_RATIO: f32 = 2.5 / 7.0;
 
-/// Turn rate (rad/s) **fallback** — how fast A/D rotate the facing when not mouse-looking, used
-/// only until the mover's own sixth movement speed arrives.
-///
-/// The live rate is per-unit and server-authoritative: `CMovement+0x9c`, last of six consecutive
-/// speed floats on the **mover's own** `CMovement`, set by `0x7c6ff0` (which acks with
-/// `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.
-/// (`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
-/// the held-*pitch* rate — that integrator's keys are default-unbound, so we never bind it.
-/// Decision 0050.
+/// Turn rate (rad/s) until the mover's own arrives: the live rate is its sixth speed,
+/// `CMovement+0x9c` (set by `0x7c6ff0`, read by `GetYawRate` `0x7c5c50`), which the ctor `0x7c4850`
+/// zeroes, so π is the server's value and the client keeps no default.
 pub(super) const TURN_RATE: f32 = std::f32::consts::PI;
 
-/// 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.
+/// The mouse-look pitch clamp, ±89° (`0x8089d8`, on the camera-to-`SetPitch` path); the ±π/2 clamp
+/// belongs to the pitch-key integrator `0x7c4f80`, whose keys are unbound by default.
 pub(super) const MOUSELOOK_PITCH_CLAMP: f32 = 1.553_343;
 
-/// The **shallowest mover pitch that still lets water walking see the water** (radians) —
-/// **VERIFIED** −37.0° = −0.6457718 (`[0x80dfe8] = 0xbf25514d`, read from the image), the third
-/// gate of the trace-mask arm `0x6315f0`:
-///
-/// ```text
-/// 63161e d9 46 20        fld   dword ptr [esi + 0x20]     ; the mover pitch
-/// 631621 d8 1d e8 df 80  fcomp dword ptr [0x80dfe8]       ; -37.0 deg
-/// 631627 df e0 / f6 c4 41  fnstsw ax ; test ah, 0x41
-/// 63162c 75 06           jne   0x631634                   ; ZF form -> skip the arm
-/// 63162e 81 cf 00 00 03  or    edi, 0x30000               ; liquid layers 0-1 into the mask
-/// ```
-///
-/// The emitted `jne` reads **ZF**, so the liquid layers are added only when `ah & 0x41 == 0`, i.e.
-/// **pitch strictly greater** than −37°; at exactly −37° the arm is skipped. Aim down past it and
-/// the water stops being geometry, which is how a water-walker gets back *into* the water.
-/// (`SetPitch 0x7c6f70`'s own complement at `0x7c6fb3` is the standstill half of the same move —
-/// see the note in [`super::mover::step`] on why we need no second kick.) Decision 1616.
+/// Water walking sees the water only while the mover pitch is strictly above −37° (`[0x80dfe8]`,
+/// the third gate of the trace-mask arm `0x6315f0`); aiming lower sinks a water-walker in.
 pub(super) const WATER_WALK_PITCH_FLOOR: f32 = -0.645_771_8;
-/// Turn-rate scale while also translating (moving/strafing) — the verified `×0.75` (`flags & 0x200f`).
+/// Turn-rate scale while translating or falling (`flags & 0x200f`).
 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
-/// (`0x60818a`–`0x6081bf`, decision 0106).
+/// Once steering stops, the rendered body closes on the aim at `turnRate × 8` rad/s, clamped to the
+/// gap (`0x607ed0`); while steering, only the 90° ceiling moves it (`0x60818a`-`0x6081bf`).
 pub(super) const STATIONARY_CHASE_RATE: f32 = 8.0;
 
-// ── Character-controller feel knobs (decision 0009) ──────────────────────────────────────────────
-// These are binary-derived values kept because they give the WoW feel cheaply — *tunables*, not
-// fidelity targets. The mechanism is a thin kinematic controller over avian's `MoveAndSlide`; further
-// refinements (accel/decel curves, partial air control beyond the one-shot nudge) dial up from here.
+// ── Character controller ─────────────────────────────────────────────────────────
 
-/// Player capsule radius (yd) — the vanilla `CMovement` ctor's ±1/3 half-width, and a *tunable* per
-/// the block header above, not a fidelity target.
-///
-/// 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** (decision 1125). Adopting them is the same
-/// movement-fidelity question [`CAPSULE_HEIGHT`] describes below, and this radius is its other
-/// half.
+/// Capsule radius (yd), the `CMovement` ctor's placeholder 1/3. The reference overwrites it per
+/// model from `CreatureModelData` (`0x6174b0`: human male 0.30555, female 0.20835); not built here.
 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
-/// ([`DEFAULT_COLLISION_HEIGHT`]), but it is not the same quantity and no longer stands in for one:
-/// a unit's real collision height is per-model and lives on [`crate::entities::CollisionHeight`]
-/// (decision 0645). This one is a *feel knob* per the block header above — it feeds the swept box,
-/// the step-vs-fall election's reach and the head/feet offsets, where going per-race would change
-/// where every short race can walk, step and fit. That is a movement-fidelity question of its own
-/// (our kinematic capsule vs the reference's k-DOP), not the depth-line question 0645 settled, so
-/// the two are kept apart on purpose rather than by oversight.
+/// Capsule total height (yd), one for every body: the swept shape and the head and feet offsets.
+/// Numerically [`DEFAULT_COLLISION_HEIGHT`], but a unit's depth lines use its per-model
+/// [`crate::entities::CollisionHeight`] instead.
 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`, 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`).
-///
-/// It is **not** a stand-in for a real unit's height: see [`crate::entities::CollisionHeight`].
+/// The `CMovement` ctor's collision height (`0x616fd8`), before `0x6174b0` sets the model's: the
+/// depth lines' fallback for a unit whose display id has no `CreatureModelData` row.
 pub(crate) const DEFAULT_COLLISION_HEIGHT: f32 = 2.027_777_7;
-/// Downward gravity (yd/s²) — binary-VERIFIED vanilla value (set on avian's `Gravity` too; matches
-/// vmangos `Movement::gravity` exactly). Shared with the remote dead-reckoner ([`crate::net`]), which
-/// integrates a relayed jump's arc under the same gravity so an observer's view matches the mover's.
+/// Gravity (yd/s²), the reference's and vmangos's `Movement::gravity`; also avian's `Gravity`, and
+/// [`crate::net`] replays relayed jump arcs under it so an observer's arc matches the mover's.
 pub(crate) const GRAVITY: f32 = 19.291_105;
-/// Jump take-off speed (yd/s) — binary-VERIFIED vanilla value.
+/// Jump take-off speed (yd/s), the reference's.
 pub(super) const JUMP_SPEED: f32 = 7.955_547;
-/// Terminal fall speed (yd/s) — binary-VERIFIED vanilla value (matches vmangos `terminalVelocity`).
-/// Shared with [`crate::net`]'s ballistic integration (caps a long fall's vertical speed).
+/// Terminal fall speed (yd/s), `[0x87d894]` and vmangos's `terminalVelocity`; [`crate::net`]'s arc
+/// replay caps at it too.
 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. `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`) —
-/// it is matching this clamp.
+/// Terminal fall speed under feather fall (yd/s), the whole of Slow Fall: `0x7c5d20` and
+/// `0x7c5f50` pick `[0x87d898]` over `[0x87d894]` while `MOVEFLAG_SAFE_FALL` is set (vmangos's
+/// `terminalSavefallVelocity`).
 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: a **direct write to
-/// `CMovement.pos.z`** (`0x636e81`–`0x636ea9`) rather than a probe widening.
+/// Hover's clearance (yd), the whole of Hover: the walk resolver probes `[0x7ff9d8]` further down
+/// (`0x636dd2`) and writes the body's z a yard clear of the floor (`0x636e81`-`0x636ea9`).
 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
-/// is already within a yard — so the rise is a second, rate-limited pass at `0x636fa1`–`0x6370f1`
-/// whose rate comes from `0x7c61b0` returning `[0x87d898]`: the very same 7.0 the feather-fall clamp
-/// reads. Without it a granted hover reads as an instant pop instead of a float.
+/// Hover's rise rate (yd/s): the snap only lowers the body (`0x636e52`), so the rise is a separate
+/// rate-limited pass (`0x636fa1`-`0x6370f1`) at `0x7c61b0`'s `[0x87d898]`, the feather-fall 7.0.
 pub(crate) const HOVER_CLIMB_RATE: f32 = 7.0;
-/// Standability gate: a surface is walkable iff its normal is within ~50° of straight up (cos 50° —
-/// the vanilla threshold). Steeper than this you can't climb and you slide back down.
+/// Walkable iff the surface normal is within 50° of up, the reference's limit; steeper slides back.
 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): 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),
-/// frame-rate independent; the collision-height term (our [`CAPSULE_HEIGHT`] — decision 0182) is
-/// what absorbs a discrete ledge: a fence-height drop is a silent straight-down step, only a deeper
-/// floor becomes a fall. That term is a **known deviation** on two counts — the reference's `H` is
-/// 1.0, not 2.028, and its extension is `0x4000000`-gated rather than always-on (decision 1125).
-///
-/// 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.
+/// The snap's slope ratio, `[0x80c740]` (atan ≈ 61.6°): the reference's step-vs-fall election
+/// `0x6367b0` probes `travel · ratio + slack` below the moved body, plus the rise budget `H` only
+/// on a steep support (`0x4000000`, `0x636dfc`). The foot cone's waist (`0x631c0b`) shares it.
 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.
+/// The snap reach's fixed slack (yd), `[0x7ff9d0]` = 1/36.
 pub(super) const STEP_SNAP_SLACK: f32 = 0.027_777_8;
-/// The step-up **rise ceiling** (yd): how tall an obstacle the atomic step-up can walk you onto —
-/// the reference's own `H`, VERIFIED (decision 1126).
-///
-/// 0209 set this to 0.7 as a deliberately modest tunable, on the understanding that the reference's
-/// budget was a ~2 yd body height we did not want. That understanding was wrong on its central fact:
-/// `0x617430` returns `CMovement+0xb8`, which is **not a height** but the dimensionless ratio
-/// `max(SCALE_X / CreatureModelScale, 1)`, and a complete writer census puts it at **1.0** for a
-/// clean local player (decision 1125). The reference's rise budget was never 2 — it was 1.0, and the
-/// gap we were preserving was 0.7 vs 1.0, not 0.7 vs 2.
-///
-/// 0209's invariant is untouched by closing it: a fence's collision top is 1.8–2.3 yd, so fences,
-/// trunks and walls still slide at exactly the height they always did. What changes is the class
-/// 0209's note invited us to fix — "one number to nudge if a real spot feels too restrictive" —
-/// which the director's captures found twice: a 0.91 yd Stormwind step (`14282v1`, a 66° face onto a
-/// flat top) and 1121's deferred 1.04 yd ledge.
+/// The step-up rise ceiling (yd), the reference's `H`: `0x617430` returns `CMovement+0xb8`, the
+/// ratio `max(SCALE_X / CreatureModelScale, 1)`, which is 1.0 for the local player.
 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): `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.
+/// The rise ceiling of a body the reference does not treat as player-controlled, `[0x801628]` on
+/// `0x5fa550`'s false leg of `0x617430`: a creature, a pet, or a charmed, possessed, feared,
+/// confused or rooted player.
 pub(crate) const CREATURE_STEP_UP_HEIGHT: f32 = 2.0;
-/// The step-up **certify advance** (yd): how far ahead the maneuver looks for the tread it would
-/// stand on. A property of the BODY, never of the frame (decision 1121).
-///
-/// 0209 advanced by this frame's own travel, which made every kerb in the game a frame-rate
-/// lottery: at 60 fps a run is 0.117 yd of travel, at 144 fps it is 0.049, and walking is 0.041 —
-/// while the capsule's own radius is [`CAPSULE_RADIUS`]. A settle probe that far forward is still
-/// over the riser, so it lands on the riser's face and the walkable gate rejects it. Measured at
-/// Stormwind's Trade District kerbs (decision 1121): the live 0.117 rung fails, 0.20 and beyond
-/// commit onto the tread, at every one of the seven captured contacts. Sidewalks 0.28 yd tall
-/// refused to be stepped onto because the probe never reached them.
-///
-/// A body radius was the principled *guess* — exactly the distance at which the capsule's footprint
-/// has cleared the lip it is standing against, and the same number whatever the frame rate or the
-/// gait. It is now superseded by the measured one (decision 1126): the reference steps
-/// `max(H·tan50°, radius + 1/720)` square into the certified face, which with the verified `H` of 1.0
-/// is **1.1918 yd** — three and a half times our radius. 1121 reached for a body-scaled number in the
-/// absence of this one and got the *shape* of the answer right; the magnitude was never ours to
-/// invent. The frame's travel still wins when it is longer, so this remains a floor, not a fixed
-/// reach.
-///
-/// It does not widen what may be climbed, and that argument is what makes the larger reach safe: the
-/// rise ceiling is still [`STEP_UP_HEIGHT`], the settle must still find a *walkable* floor higher
-/// than the feet, and — the load-bearing part — **the elevated forward sweep is clipped by anything
-/// in the way**, so the advance only ever reaches as far as there is clear air at the raised height.
-/// A fence, a trunk and a two-trunk pinch still block at the same body height, with a clipped advance
-/// and a net-zero settle. What the longer reach buys is the case the director's capture found: a step
-/// whose *face* is unwalkable for most of a yard before the flat top begins, where a probe that stops
-/// at one radius is still over the face and reads it as a steep floor.
+/// The step-up certify advance (yd), a floor under the frame's travel: the reference steps
+/// `max(H·tan50°, radius + 1/720)` into the face, 1.1918 yd at `H` = 1.0. The raised forward sweep
+/// is clipped by anything in the way, so the advance reaches only clear air.
 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`).
-/// [`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.
+/// The certify reach per yard of rise budget, `tan 50°` (`0x636147`-`0x636190`); a creature's 2.0
+/// reaches 2.38 yd.
 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
-/// narrower than its full radius — and therefore the band within which a blocking edge is *ridden
-/// up* rather than stepped onto (decision 1123).
-///
-/// The real client's movement solid is not a capsule. Its lower half is a **cone**: the k-DOP build
-/// 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.
-///
-/// 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 (`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.
-///
-/// Not a new tunable: it is our own two constants multiplied, so it is *our* mover's cone — the band
-/// is a property of the body's radius, and ours is [`CAPSULE_RADIUS`].
-///
-/// It is **not** the real client's band, and the gap is recorded rather than papered over (decision
-/// 1125, correcting 1123's claim that it matched exactly). Because [`CAPSULE_RADIUS`] is the ctor
-/// placeholder, ours comes out at 0.616 against a live human male's **0.565** and a human female's
-/// **0.385** — ~9% and ~60% generous. It only decides ride-vs-pop for obstacles *between* the two
-/// bands, so the cost is a narrow slice of over-smooth rides on tall-ish steps; closing it properly
-/// means per-model mover extents, which moves far more than this constant.
+/// The foot cone's height (yd). The reference's solid (`0x631440`) is a box over a cone whose
+/// bevels rise `radius · [0x80c740]` from a point at the foot, so an edge below this is ridden up
+/// the 61.6° skirt (`0x635c00`) and one above meets the box and takes the step-up. With the
+/// placeholder [`CAPSULE_RADIUS`] ours is 0.616 yd; a live human male's is 0.565, female's 0.385.
 pub(super) const FOOT_CONE_HEIGHT: f32 = CAPSULE_RADIUS * STEP_SLOPE_RATIO;
-/// The landing probe (yd): while airborne, walk mode resumes only this close to the floor, so
-/// the arc ends where the slide actually contacts (skin scale) instead of [`GROUND_PROBE`]
-/// early — which cut the last ~0.2 yd of every fall into a same-frame snap, the visible pop at
-/// every silent landing (decision 0190).
+/// The landing probe (yd): airborne, walk mode resumes only this close to the floor, so the arc
+/// ends where the slide contacts rather than [`GROUND_PROBE`] early.
 pub(super) const LAND_PROBE: f32 = 0.05;
-/// Wedge-rest detection (decisions 0211/0212): a "fall" that is no longer falling. A capsule can
-/// come to rest held between two steep faces — the flaring trunk bases at the Northshire trees
-/// form exactly this funnel (contact normals ~0.2 up) — where gravity feeds the slide, the
-/// opposing contacts cancel it, and with mid-air control locked (vanilla momentum rules) the
-/// falling pose is permanent. This many consecutive *stalled* frames (see
-/// [`WEDGE_STALL_RATIO`]) is unambiguously a rest — land there: the fall ends, walking control
-/// returns, and stepping off the support resumes a normal fall. Nothing becomes walkable or
-/// climbable by this.
+/// Stalled airborne frames (see [`WEDGE_STALL_RATIO`]) that count as resting wedged between two
+/// steep faces: the fall ends there, and nothing becomes walkable by it.
 pub(super) const WEDGE_STILL_FRAMES: u8 = 3;
-/// A frame counts as stalled when the achieved descent is under this fraction of the descent
-/// gravity intended (`vel_y·dt`), already falling faster than [`WEDGE_MIN_FALL`]. Free fall
-/// achieves ~100% and a steep-slope slide ≥75% (the steeper the face, the *freer* the
-/// vertical), so only opposing contacts hold an arc under this — and because the intent keeps
-/// growing while the funnel eats the motion, the pinch-in registers the frame it starts
-/// instead of after a visible millimeter-creep tail in the falling pose (0211's absolute
-/// stillness test — decision 0212).
+/// A frame stalls when its descent is under this fraction of gravity's intended `vel_y·dt` while
+/// falling faster than [`WEDGE_MIN_FALL`]: free fall achieves ~100%, a steep slide at least 75%.
 pub(super) const WEDGE_STALL_RATIO: f32 = 0.15;
-/// Fall speed (yd/s) the arc must exceed before stalled frames count: a jump apex hovers near 0
-/// and never qualifies; a wedge accumulates gravity while frozen and passes within a few frames.
+/// Fall speed (yd/s) before stalled frames count: a jump apex never qualifies, a wedge soon does.
 pub(super) const WEDGE_MIN_FALL: f32 = 1.0;
-/// One-shot air-control nudge (yd/s): a jump from a standstill can be steered this much in the pressed
-/// direction; a jump taken with momentum keeps it locked (vanilla feel). Less than a walking jump.
-///
-/// **VERIFIED as behaviour, but this constant is data, not a binary constant** (decision 1736): the
-/// reference's nudge speed is `min(MOVE_WALK, MOVE_RUN)`, the walk override inside `0x7c4c90(1)`
-/// (`0x7c4d19`/`0x7c4d1b`), read from the unit's live speeds. `2.5` is the *default* `MOVE_WALK`, so
-/// this agrees with the reference right up until a walk aura, a Slow or a daze moves either speed.
+/// The one-shot air nudge (yd/s) a standstill jump may steer by. The reference's is the live
+/// `min(walk, run)` (`0x7c4c90(1)`, `0x7c4d19`); this is the default walk speed, not the live one.
 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. 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).
+/// The FALLINGFAR distance leg (yd): a jump arc (launch vz ≠ 0) latches it once this far below
+/// its launch height (`0x633240`, `[0x80dff8]`), and the anim swaps to Fall(40); a flat jump never
+/// does.
 pub(super) const FALL_FAR_DROP: f32 = 0.111_11;
-/// The FALLINGFAR **timer leg** (s): a *step-off fall* (launch vz = 0 — the walk election's
-/// `StartFalling(0)`) latches once airborne this long — `0x633240`'s accumulator test,
-/// `0x1f4` = 500 ms. Free-falling from rest that is ≈ 2.41 yd of descent. Since the election
-/// absorbs anything up to ~collision height as a step (decision 0182), elected step-off falls
-/// start just under this: a wagon-height drop crosses it a frame or two before the floor.
+/// The FALLINGFAR timer leg (s): a step-off fall (launch vz = 0) latches it after 500 ms airborne
+/// (`0x633240`, `0x1f4`), about 2.41 yd of free fall from rest.
 pub(super) const FALL_FAR_TIME: f32 = 0.5;
 /// Skin width (yd) kept between the capsule and geometry on casts.
 pub(super) const SKIN_WIDTH: f32 = 0.02;
 
-/// Seconds of **stalled** streaming before the post-snap hold gives up (see [`Player::settling`]).
-/// A *stall* budget, not a load budget: the deadline is pushed forward while the resident world is
-/// still the departed map's (0710's fail-closed law) **and while the destination is visibly still
-/// arriving** (any load-progress counter moved — B263, decision 1303). It can therefore only fire
-/// against a stream that has made no progress at all for this long — missing data, dead IO — never
-/// against a slow machine. As a fixed load budget it was measured 0.01 s from firing on a *fast*
-/// machine (a Stormwind arrival consumed 5.99 s of the 6.00 s), which is B263: on any slower
-/// machine it released gravity mid-stream and the body fell through the not-yet-collided city.
+/// Seconds of stalled streaming before the post-snap hold gives up: the streamer pushes the
+/// deadline on while the world is stale or any load counter moves, so only a dead stream hits it.
 pub(crate) const SETTLE_TIMEOUT: f32 = 6.0;
 
-/// The player body's collision capsule, built once at startup and swept by avian's `MoveAndSlide`
-/// each frame. Its origin is the capsule centre; the player's `pos` is its feet (centre −
-/// half-height·Y).
-///
-/// **Every player body, not only ours.** A remote mover's dead-reckon sweeps this same capsule
-/// against the same colliders ([`super::mover::grounded_step`]) — the reference drives non-local
-/// units through the *same* movement controller as the local player (decision 0059's byte trail:
-/// `0x616620` integrates any mover; the local-player GUID compare gates only a timing budget). The
-/// reference reads each unit's own collision height (`[unit+0xb8]`); we use the one player capsule
-/// for every player body, which the 1.12 races are close enough to share.
+/// The player body's collision capsule, swept by avian's `MoveAndSlide`: origin at its centre, the
+/// player's `pos` at its feet. Every player body sweeps it, remote ones too, as the reference runs
+/// every mover through one controller (`0x616620`); the reference sizes each from its model.
 #[derive(Resource)]
 pub(crate) struct PlayerCapsule(pub(crate) Collider);
 
-/// The avatar run-speed fallback + dev override. `value` is `$WOW_MOVE_SPEED` when set
-/// (`env_override` — the absolute dev knob, backpedal scaled by [`RUN_BACK_RATIO`] under it), else
-/// the vanilla 7.0 used only until the server's own speeds stream in: the self create's `LIVING`
-/// block seeds [`crate::net::UnitSpeeds`], and every `SMSG_FORCE_*_SPEED_CHANGE` updates it live —
-/// the controller reads those as the authoritative run/runback/swim speeds.
+/// The run-speed fallback, the stock 7.0 until the server's speeds stream in, or the
+/// `$WOW_MOVE_SPEED` dev override (`env_override`), which replaces the server's speeds outright.
 #[derive(Resource)]
 pub(super) struct MoveSpeed {
     pub(super) value: f32,
     pub(super) env_override: bool,
 }
 
-/// **The granted mover modes — one system, five bits** (decision 0866).
-///
-/// A *mode* is a `MOVEMENTFLAGS` bit the **server grants** that changes how our mover behaves rather
-/// than where it is heading. They live here as typed fields, not as bits in
-/// [`Player::move_flags`], for the reason decision 0726 first hit: `move_flags` is last-streamed
-/// wire bookkeeping, rebuilt from state every frame, so a mode parked there alone would be gone
-/// before the mover ever read it. The flag word is *rebuilt from these fields* each frame instead —
-/// which is also what keeps the server's copy of our mode alive (drop the bit from our stream and
-/// the next server-authored move echoes a mode-less word back and clears it under us).
-///
-/// **Two arrival routes, and the difference matters.** Four of the five come through the *ack'd*
-/// family ([`benilla_protocol::MoveMode`]) — an addressed opcode we must answer with the echoed
-/// counter or the grant never lands. [`Self::levitating`] does not: it arrives merged out of a
-/// server-authored `MSG_MOVE_*` (the `SERVER_AUTHORED` mask), unhandshaked.
-///
-/// **Each one's effect is the reference's, byte-verified** — the addresses are in
-/// [`benilla_protocol::MoveMode`]'s table; here is where each is consumed:
-///
-/// - [`rooted`](Self::rooted) — translation and jumps die; **turning stays live** ([`super::control`]).
-/// - [`feather_fall`](Self::feather_fall) — terminal fall speed becomes [`FEATHER_TERMINAL_VELOCITY`]
-///   ([`super::mover::step`]).
-/// - [`hover`](Self::hover) — ground contact rises by [`HOVER_HEIGHT`] ([`super::mover::step`]).
-/// - [`water_walking`](Self::water_walking) — the liquid surface becomes ordinary ground, in the
-///   classify and in the resolve alike ([`super::mover::step`]).
-/// - [`levitating`](Self::levitating) — the swim/depth decision is suppressed entirely
-///   ([`super::swim::update_swimming`]).
-///
-/// **Levitate (spell 1706) grants three at once** — feather fall + hover + water walk — which is why
-/// they are one struct rather than four unrelated booleans.
+/// The mover modes the server grants, as typed state: the outbound flag word is rebuilt from these
+/// every frame, and a mode missing from it is cleared by the server's next echo. Four arrive
+/// through the acked [`benilla_protocol::MoveMode`] opcodes, `levitating` unacked in a
+/// server-authored move; Levitate (spell 1706) grants three at once.
 #[derive(Default, Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) struct MoveModes {
-    /// The server rooted our mover (`SMSG_FORCE_MOVE_ROOT` — death until release, and every root or
-    /// stun; decision 0308). Translation input and jumps are dead — the faithful "can't move between
-    /// death and release" — but **turning stays live, and by design rather than by omission**
-    /// (corrected by decision 0872): the reference's input tick consults an allow-list
-    /// (`0x615c71` → the byte table at `0x618054`) that blocks the translation command ids and
-    /// **explicitly permits** turn, pitch, run/walk and SetFacing. `SetRoot 0x7c7340` additionally
-    /// clears the direction bits once, at apply. A character who cannot even pivot is *stunned* —
-    /// a separate `UNIT_FIELD_FLAGS` gate ([`crate::player::UNIT_FLAG_STUNNED`]).
+    /// Rooted (`SMSG_FORCE_MOVE_ROOT`): translation and jumps die but turning stays live, since the
+    /// input tick's allow-list (`0x615c71`, table `0x618054`) permits turn, pitch and facing. A
+    /// stun, which takes the pivot too, is [`crate::player::UNIT_FLAG_STUNNED`].
     pub(crate) rooted: bool,
-    /// Water-walking (`SMSG_MOVE_WATER_WALK`, `SPELL_AURA_WATER_WALK` — Water Walking, Levitate, and
-    /// the ghost form): the liquid surface counts as ordinary walkable ground, so we stand on it
-    /// instead of sinking ([`super::mover::step`] — the classify and the clamp, decision 1611).
-    ///
-    /// **It does NOT stop the swim latch arming**, and the claim that it did stood here until
-    /// decision 1611 read the bytes: `0x6030c0`'s only mode test is `test ah,4` — LEVITATING
-    /// (`0x400`) — and it never looks at `0x10000000` at all. The exclusion runs the other way and
-    /// lives one layer down, in the trace-mask arm at `0x631617`: *swimming* turns water-walking
-    /// off, not the reverse. So a swimmer who gains *this* bit keeps swimming, by construction —
-    /// but a swimmer who casts **Levitate** does not, because Levitate also grants
-    /// [`hover`](Self::hover), whose handler jumps the body out first (decision 1620).
+    /// Water walking (`SMSG_MOVE_WATER_WALK`): the liquid surface is ground. It does not stop the
+    /// swim latch (`0x6030c0` tests only LEVITATING); swimming turns it off instead (`0x631617`).
     pub(crate) water_walking: bool,
-    /// Feather fall (`SMSG_MOVE_FEATHER_FALL`, `SPELL_AURA_FEATHER_FALL` — Slow Fall, Levitate): the
-    /// fall integrator's terminal velocity drops to [`FEATHER_TERMINAL_VELOCITY`]. Nothing else
-    /// changes — the arc, the flags and the landing report are the ordinary ones.
+    /// Feather fall (`SMSG_MOVE_FEATHER_FALL`): the terminal velocity drops to
+    /// [`FEATHER_TERMINAL_VELOCITY`], and nothing else changes.
     pub(crate) feather_fall: bool,
-    /// Hover (`SMSG_MOVE_SET_HOVER`, `SPELL_AURA_HOVER` — Levitate): ground contact sits
-    /// [`HOVER_HEIGHT`] above the surface, so the body floats and walks along a yard up. It also
-    /// refuses the jump outright — the first test in `CMovement::Jump 0x7c6230`, live for the
-    /// keyboard press ([`super::mover::step`], and the swim breach in [`super::control`]).
-    ///
-    /// **And the grant itself jumps you** — the one granted mode that moves the body, and the whole
-    /// of why Levitate looks like a launch ([`Player::hover_launch`], decision 1620).
-    ///
-    /// **Composed with [`water_walking`](Self::water_walking), those two gates leave a swimmer
-    /// with no way to the surface** (B322's first symptom, decision 1611): water-walking is off
-    /// while SWIMMING, and SWIMMING only clears on the depth compare or on a breach that HOVER
-    /// refuses. Both gates are individually VERIFIED; the *composition* is inferred, and it is the
-    /// one part of the Levitate lane still open.
+    /// Hover (`SMSG_MOVE_SET_HOVER`): ground contact sits [`HOVER_HEIGHT`] up and the jump is
+    /// refused (the first test in `CMovement::Jump` `0x7c6230`); the grant itself jumps the body
+    /// ([`Player::hover_launch`]). With water walking it seems to leave a swimmer no way up, since
+    /// swimming turns water walking off and hover refuses the breach: each gate is traced, the sum
+    /// is not.
     pub(crate) hover: bool,
-    /// **Free flight** (`MOVEFLAG_LEVITATING`, GM `.cheat fly` — decision 0726). The one mode that
-    /// arrives *unhandshaked*, merged out of a server-authored move ([`super::wire_in`]).
-    ///
-    /// It does exactly one thing, and it does it by suppression: while set, the water/depth swim
-    /// decision does not run at all ([`super::swim::update_swimming`] — the reference's
-    /// `0x6030d2 test ah,4` bail). So a [`Player::swimming`] the server switched on stays on with no
-    /// water under it — which *is* GM flight — and, symmetrically, real water can no longer put us
-    /// into swim while it is set.
+    /// `MOVEFLAG_LEVITATING` (GM `.cheat fly`), merged unacked from a server-authored move: the
+    /// swim decision does not run while it is set (`0x6030d2`), so a server-set swim is flight.
     pub(crate) levitating: bool,
 }
 
 impl MoveModes {
-    /// Grant or revoke one ack'd mode. [`Self::levitating`] is deliberately unreachable here — it
-    /// has no opcode of its own and arrives through the server-authored flag merge instead.
+    /// Grant or revoke one acked mode; `levitating` has no opcode and arrives by the wire merge.
     pub(crate) fn set(&mut self, mode: MoveMode, apply: bool) {
         match mode {
             MoveMode::Root => self.rooted = apply,
@@ -421,14 +170,9 @@ impl MoveModes {
         }
     }
 
-    /// The granted modes as `MOVEMENTFLAGS` bits — **what every outbound packet must carry**.
-    ///
-    /// This is the half that is easy to skip and expensive to skip: the reference has one
-    /// `[cmov+0x40]` that is both the live state and the wire word, so a real client echoes back
-    /// whatever the server granted for free. Ours rebuilds the word from state each frame, so
-    /// dropping a mode here makes the server's copy forget it — and the next server-authored move
-    /// echoes a mode-less word back, our merge clears the mode, and the aura silently stops working
-    /// (decision 0726 hit exactly this with GM flight).
+    /// The granted modes as `MOVEMENTFLAGS` bits, which every outbound packet must carry: the
+    /// reference's wire word is its live state (`[cmov+0x40]`), and a mode we drop is cleared by
+    /// the server's next echo.
     pub(crate) fn wire_flags(&self) -> u32 {
         use crate::creature_anim::move_flags as f;
         let mut flags = 0;
@@ -450,19 +194,11 @@ impl MoveModes {
         flags
     }
 
-    /// Lift the granted modes **out of a server-authored flag word** into typed state (decision
-    /// 0726's step, now the whole family's). All five bits sit inside the reference's
-    /// `SERVER_AUTHORED` merge mask (`0x75a0_7dff`), so a bare `MSG_MOVE_*` the server writes for
-    /// our mover can grant or revoke them with no handshake — `.cheat fly` is the case that proved
-    /// it, and it is why LEVITATING has no opcode of its own.
-    ///
-    /// **Root is a deliberate divergence, and not because the mask excludes it** — bit 12 is inside
-    /// the mask, so the reference *does* merge root from a server-authored pose. We don't: in this
-    /// client the ack'd opcode is root's only grant path, and letting a bare pose clear it would put
-    /// a locally-unrooted body against a server that still has us rooted — which streams moving bits
-    /// and trips `CHEAT_TYPE_ROOT_MOVE`. The reference gets away with it because vmangos re-adds
-    /// `MOVEFLAG_ROOT` to anything it writes for a rooted mover (`MovementHandler.cpp:1064`), so its
-    /// merge is a no-op in practice. Revisit if a case ever needs the wire to unroot.
+    /// Lift the granted modes out of a server-authored flag word; the reference's merge mask
+    /// `0x75a0_7dff` holds all five. Deviation: root is not merged, because a bare pose unrooting
+    /// us while the server still roots us streams motion into `CHEAT_TYPE_ROOT_MOVE`; vmangos keeps
+    /// a rooted mover's root bit (`MovementHandler.cpp:1064`), so the reference's merge of it is a
+    /// no-op anyway.
     pub(crate) fn merge_from_wire(&mut self, wire: u32) {
         use crate::creature_anim::move_flags as f;
         self.water_walking = wire & f::WATER_WALKING != 0;
@@ -472,215 +208,67 @@ 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"*.
-/// 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 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]` 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`. It contributes nothing while dead;
-/// 5. `!(IsActivePlayer(mover) && [mover+0x1c70] & 1)` — the **far-sight ENGAGED latch**, the
-///    [`MoverInput::view_is_out`] field.
-///
-/// **Conjuncts 1, 3 and 4 have no field here.** Conjunct 1 is structural:
-/// [`super::controller::control`] returns before the axes on `control_lost` and on `reseat`, the
-/// frames where the mover would not resolve. Conjunct 3 has no benilla analog yet. Conjunct 4 is
-/// named, verified and unbuilt — its own behaviour with its own retest — and this struct is where
-/// it lands when it is built.
-///
-/// Carried as a **value** rather than as loose booleans threaded through each predicate because
-/// that is the reference's own shape (one precondition, evaluated once for the mover, handed to
-/// both), and because two same-typed terms passed positionally would transpose silently.
+/// The precondition both movement-input predicates test first, the reference's `0x5144e0`. Of its
+/// five terms, health ([`MoverInput::dead`]) and the far-sight latch
+/// ([`MoverInput::view_is_out`]) are here; the mover resolving is structural (the controller
+/// returns early on `control_lost` and `reseat`), and the aux gate `[[mover+0x118]+0xa4]`
+/// (`0x514516`) and the Knockdown animation lockout `0x60f5b0` are not built.
 #[derive(Clone, Copy, Debug, Default)]
 pub(crate) struct MoverInput {
-    /// **Conjunct 2, the health term** — health `== 0` off the **mover's** descriptor
-    /// ([`benilla_protocol::messages::update_object::ObjectFields::unit_is_dead`]). The mover's and
-    /// not ours, because `0x5144e0` reads `[esi+0x110]` where `esi` is whatever we are driving
-    /// (decision 1277's possessed creature).
-    ///
-    /// **This is the term the struct exists for.** benilla modelled the server's root on death
-    /// (0308) and nothing else, and a root deliberately leaves turning live (0872), so a corpse on
-    /// the ground could still be spun with the turn keys or a right-drag — decision 1753.
-    ///
-    /// **A ghost is not dead by this test:** the server puts a released player's health at 1
-    /// (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 (`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.
+    /// The health term: the driven mover's health is not above 0 (`0x5144fd`, off `[mover+0x110]`).
+    /// A released ghost has health 1 from the server, so it passes and keeps every input.
     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.
-    ///
-    /// **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
-    /// conjunct satisfied the moment they differ (`0x51453e je 0x514550`), so the latch is only
-    /// ever read for our own body. Mind Control rides the same `PLAYER_FARSIGHT` field the camera
-    /// does ([`super::view_subject`]), so during a possession the latch is engaged — and without
-    /// this half the victim would freeze solid, which is the one body the whole spell exists to
-    /// walk around. It is also why the latch is never read off a creature's descriptor, where
-    /// `+0x1c70` is not a field at all.
-    ///
-    /// **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.
-    /// 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.
+    /// The far-sight term, held true while our view is out on a far-sight object and we drive our
+    /// own body: `[mover+0x1c70] & 1`, read only when the mover is the active player (`0x514537`).
+    /// The latch sets only once the subject resolves (`0x5ee3f6`), so this follows the resolved
+    /// [`super::view_subject::ViewSubject`], not the raw `PLAYER_FARSIGHT` field.
     pub(crate) view_is_out: bool,
 }
 
-/// **Conjunct 5's two halves, composed** — `IsActivePlayer(mover) && [mover+0x1c70] & 1`, the
-/// value [`MoverInput::view_is_out`] carries and the field's doc explains in full.
-///
-/// A named function and not an inline `&&` at the one call site, because the half that is easy to
-/// lose is `driving_own_body`: drop it and Mind Control freezes its victim, which is a bug nothing
-/// about far sight would lead you to look for.
-///
-/// - `driving_own_body` — the mover is our own character, i.e. no possession is in force
-///   (`0x514537 call 0x5fa6d0`, the active-player test on the *mover*).
-/// - `far_sight_engaged` — our view is out on a far-sight object we have actually **resolved**
-///   (`[mover+0x1c70] & 1`, which the machine `0x5ee290` sets only on its post-resolve ENGAGE leg).
+/// The far-sight term: the view is out and the body is our own. Mind Control sets the same field,
+/// so without `driving_own_body` (the active-player test `0x5fa6d0`) it would freeze the victim.
 pub(crate) fn view_is_out(driving_own_body: bool, far_sight_engaged: bool) -> bool {
     driving_own_body && far_sight_engaged
 }
 
 impl MoverInput {
-    /// `0x5144e0` itself — every conjunct we model, and the answer both predicates start from.
+    /// `0x5144e0`, over the terms modelled here.
     fn ready(self) -> bool {
         !self.dead && !self.view_is_out
     }
 
-    /// **`0x514560` — "may this unit translate?"**, the ROOT predicate. Consumed by the input tick
-    /// at `0x5146c1` (`test bl,bl`), the sole gate on the forward/back emitter `0x514da0` and the
-    /// strafe emitter `0x514e80`. Its own terms past the shared precondition are `MOVEMENTFLAGS &
-    /// 0x1200` (`0x51458c test dh,0x12` — our `rooted`) and stand state `!= 7` (`0x514591`), which
-    /// vmangos never writes and which is therefore inert here.
-    ///
-    /// Note the health term is tested **twice** — once inside `0x5144e0` and again at `0x51457c` on
-    /// the predicate's own path. Death is not a corner of this gate; it is its first question.
+    /// `0x514560`, the gate on the forward/back and strafe emitters (`0x5146c1`): the precondition
+    /// and no root (`MOVEMENTFLAGS & 0x1200`); its stand-state-7 term is one vmangos never sets.
     pub(crate) fn may_translate(self, rooted: bool) -> bool {
         self.ready() && !rooted
     }
 
-    /// **`0x5145b0` — "is this unit not stunned?"**, the STUN predicate. Consumed at `0x514755`
-    /// (`je 0x51479c`), which skips the turn emitter `0x514f50` and the pitch emitter `0x515010`
-    /// 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**.
-    ///
-    /// 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** (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
-    /// arrives through `0x5145b0` → `0x5144e0` and short-circuits before `0x5145e0` reaches its own
-    /// remaining conjuncts (`[input+4] & 1`, and `GetStandState() == 0` via the CGPlayer vtable slot
-    /// `0x5ed570`). The refusal is then **triple-redundant**: the two downstream commit gates
-    /// `0x5151b0` (yaw, at `0x5151e6`) and `0x515250` (pitch, at `0x515283`) each carry their own
-    /// health test. A closed census of all nine call sites of the body-facing setters
-    /// `0x60de30`/`0x60de70` — neither of which has any dword reference image-wide — finds every one
-    /// health-gated.
-    ///
-    /// So one term in one place really does fix the keys and the mouse together, but not because
-    /// they share `0x514755`: they share `0x5144e0`.
+    /// `0x5145b0`, the gate on the turn and pitch emitters (`0x514755`): the precondition and no
+    /// stun (`UNIT_FIELD_FLAGS & 0x40000`). The mouse's gate `0x5145e0` calls it first, so a corpse
+    /// turns by neither keys nor mouse.
     pub(crate) fn may_turn(self, stunned: bool) -> bool {
         self.ready() && !stunned
     }
 
-    /// **`0x5145e0` — "may the MOUSE hand the camera's facing to the body?"** (decision 2025). The
-    /// third predicate, consumed at `0x514474` (`je 0x514480`) in the mouse-MOVE handler `0x514400`
-    /// to gate the camera→body hand-off `0x51447b call 0x5103e0`, and again at `0x51495a` for the
-    /// both-button site. Its conjuncts, in the binary's order: the stun predicate above
-    /// (`0x5145eb call 0x5145b0`, which carries the shared precondition), the mouse-look input bit
-    /// (`0x5145fa test byte [esi+4],1` — the session's own right-button condition, which is the
-    /// 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`.
-    ///
-    /// 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
-    /// wire. It does not stand the body up either: the turn emitter `0x514f50` skips its stand arm
-    /// while the RMB bit is held (`0x514f6d`), and `MSG_MOVE_SET_FACING` is exempt from the
-    /// emitter's stand table. Standing up is the keyboard's (`turned`), the X key's, or a flick's
-    /// (1766); the moment the predicted stand state reads 0 again, the next motion sample hands
-    /// the camera's yaw to the body like any other right-drag.
-    ///
-    /// `stand_state` is the **predicted** value — our `stand_pending` overlaid on the descriptor
-    /// byte — because that is what `0x5ed570` returns for the active player.
+    /// `0x5145e0`, the gate on the mouse's camera-to-body hand-off (`0x514474`, `0x51495a`): the
+    /// stun predicate and a standing body (`0x51460c`). A right-drag while seated turns only the
+    /// camera and does not stand you up; `stand_state` is the predicted one `0x5ed570` returns.
     pub(crate) fn mouse_may_turn_body(self, stunned: bool, stand_state: u8) -> bool {
         self.may_turn(stunned) && stand_state == 0
     }
 
-    /// **The input tick's teardown leg** — `0x5146d6 call 0x60fb60(0, 1)`, which cancels
-    /// 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`). 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).
+    /// The input tick's teardown leg (`0x5146d6`, ending click-to-move and `/follow`), taken only
+    /// with both predicates down: death, far sight, or a root and a stun together.
     pub(crate) fn torn_down(self, rooted: bool, stunned: bool) -> bool {
         !self.may_translate(rooted) && !self.may_turn(stunned)
     }
 }
 
-/// **The two incapacitate suppressions, applied to a freshly built move-flag word** (decision 0880)
-/// — the last step of [`super::control`]'s per-frame rebuild, before the word drives the animation
-/// and goes on the wire.
-///
-/// The reference never needs this: its `[cmov+0x40]` is written *only* by emitters that already
-/// refuse, so the bits are absent by construction. Ours rebuilds the word from raw input every
-/// frame, so a suppression not re-applied here streams motion the body is not performing (decision
-/// 0056's law) and feeds the same lie to the anim layer.
-///
-/// - **Rooted → no direction bits.** The input tick's allow-list (`0x615c71` → the byte table at
-///   `0x618054`) DROPS command ids 0–5 — StartMove/StopMove/StartStrafe — while `0x1000` is set, so
-///   a key pressed under a root never reaches `0x7c6ae0`/`0x7c6c50` and never sets a bit; `SetRoot
-///   0x7c7340`'s own `and 0xffe07f00` wipes whatever was set, at apply. With the low nibble clear
-///   the movement-anim resolver `0x5fd100` takes its not-moving exit at `5fd10c test al,0xf` before
-///   it can reach any locomotion id — **that** is why a rooted character shows no walk/run
-///   animation, and why ours was still showing one: it kept building FORWARD out of the raw axis
-///   while the mover ignored it.
-/// - **Stunned → no turn bits.** `0x514755` skips the turn emitter `0x514f50` outright and
-///   force-stops one already in flight, so `0x7c6d90 StartTurn` never runs. Decision 0872 stopped
-///   the *rotation* (`control` restores the aim) but left the bits streaming, which still told every
-///   observer to play the turn-in-place shuffle.
-///
-/// 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. 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).
-///
-/// The two arguments are therefore not "rooted" and "stunned" but **the two predicates being down**
-/// ([`may_translate`], [`may_turn`]) — a wider set by exactly one member: **death drops both**,
-/// through the precondition they share ([`MoverInput`], decision 1753). A corpse streams
-/// neither a direction bit nor a turn bit.
+/// Strip from a freshly built flag word what a gated mover cannot hold: the direction bits while
+/// translation is gated (the allow-list `0x618054` drops the move commands and `SetRoot` `0x7c7340`
+/// masks `0xffe07f00`, so the anim resolver's `0x5fd10c` sees no motion) and the turn bits while
+/// turning is gated (`0x514755`). The reference's emitters refuse at the source; ours rebuilds the
+/// word each frame. Modes and SWIMMING ride on.
 pub(crate) fn incapacitated_flags(flags: u32, translate_gated: bool, turn_gated: bool) -> u32 {
     use crate::creature_anim::move_flags as f;
     let mut out = flags;
@@ -693,572 +281,264 @@ pub(crate) fn incapacitated_flags(flags: u32, translate_gated: bool, turn_gated:
     out
 }
 
-/// Our controllable avatar. Until `active`, the camera free-flies; once the server reports our
-/// position we take control (third-person) and drive movement. Toggle free-fly with the dev
-/// chord + `F` (decision 1043).
-/// `active`/`pos`/`detached` are `pub(crate)` so terrain streaming can center the loaded block on the
-/// avatar in third-person and on the free-flying camera while detached.
-/// `PartialEq` is here for one assertion, and it is the assertion that keeps this type honest:
-/// the session boundary returns the whole resource to `Player::default()`
-/// ([`super::wire_in::release_on_session_end`], decision 1542), and its test says exactly that
-/// rather than re-listing the fields a hand-picked reset would have to remember.
+/// Our avatar: until `active` the camera free-flies, then we drive the body the server placed.
+/// `PartialEq` serves the test that the session end resets the whole of it to `Player::default()`.
 #[derive(Resource, Default, PartialEq)]
 pub(crate) struct Player {
     pub(crate) active: bool,
-    /// **The granted mover modes** — what the server has switched on for our mover, as typed state
-    /// rather than raw bits. See [`MoveModes`].
+    /// The modes the server has granted our mover.
     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).
-    ///
-    /// 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
-    /// and diagonals with a strafe, exactly like the both-button run. Ours folds in at the same
-    /// places the other forward sources do — the direction vector, the wire flags, the swim
-    /// amounts, and the turn-rate's "am I translating" test.
+    /// Autorun: the reference's input bit `0x1000` at `[MOVE+4]`, flipped by `ToggleAutoRun`
+    /// `0x513de0`. The emitter `0x514da0` adds it to the forward axis, but a W or S key-down clears
+    /// it first ([`autorun_cancelled`]), so it is not a held W: autorun then S walks backward.
     pub(super) autorun: bool,
-    /// **Walk mode latched on** — the reference's `MOVEMENTFLAGS` bit `0x100`
-    /// (`CMovement+0x40`), flipped by `ToggleRun 0x513d50` → `0x60e080`, which reads the CURRENT
-    /// bit out of the cached word (`0x60e083 mov eax,[ecx+0x9e8]; 0x60e08c and eax,0x100`) and
-    /// hands it down to be inverted. The other true *toggle* in the movement family, beside
-    /// [`autorun`](Self::autorun) — and unlike it, this one is a real wire bit rather than an
-    /// input-word bit, so it rides every outbound packet ([`super::flags`]) and observers read our
-    /// gait straight off it.
-    ///
-    /// **Typed state, not the flag word.** [`Player::move_flags`] is last-streamed wire
-    /// bookkeeping, rebuilt from state every frame, so a latch parked only there is gone by the
-    /// next frame — the same trap [`MoveModes`] exists to avoid. It is *also* inside the
-    /// `SERVER_AUTHORED` merge mask, so a server-authored move for our mover can flip it; that
-    /// merge lands here, in [`super::wire_in`], not in the word.
-    ///
-    /// It is **not** a [`MoveModes`] entry: that family is the four ack'd server grants, each with
-    /// its own SMSG/ack pair. This one owes no ack, is granted by nobody, and is ours to set.
+    /// Walk mode, `MOVEFLAG_WALK_MODE` (`0x100`), toggled by `ToggleRun` `0x513d50` from the word's
+    /// current bit (`0x60e080`). Observers read our gait off it, and it is in the server-authored
+    /// merge mask, so a server move can flip it ([`super::wire_in`]); it owes no ack.
     pub(super) walking: bool,
-    /// **`/follow` is holding the forward key this frame** (decision 0890). Not a mode of its own:
-    /// the reference's follow owns no translation and simply pushes the same move-forward bit the W
-    /// key does (`0x60e790`), so this folds into [`forward_axis`] beside `autorun` and the
-    /// both-button run rather than driving the mover itself. Rewritten every frame by
-    /// [`super::follow::steer_follow`], which runs just before the controller reads it.
+    /// `/follow` holding forward this frame: the reference's follow pushes W's own bit
+    /// (`0x60e790`), so this is a [`forward_axis`] term. Rewritten each frame by
+    /// [`super::follow::steer_follow`] just before the controller reads it.
     pub(super) follow_forward: bool,
     /// Free-fly (`F`): the camera moves on its own and the avatar/server position is frozen.
     pub(crate) detached: bool,
-    /// **The body in our hands may not be moved** — `SMSG_CLIENT_CONTROL_UPDATE` with
-    /// `allowMove = 0` about whatever we are currently driving.
-    ///
-    /// Two cases, one meaning (decision 1279). The packet names **us** while somebody is
-    /// mind-controlling us (B211); it names **the creature we are possessing** when that creature
-    /// becomes feared or confused, which vmangos sends from the fear/flee movement generators
-    /// without ending the possession at all. Both say the same thing — the reins are still where
-    /// they were, and nothing may move — and the reference collapses them the same way, by zeroing
-    /// the mover global for whichever unit the packet names when it is the one already being
-    /// driven.
-    ///
-    /// So this is **not** "someone is controlling me"; reading it that way is what made the second
-    /// case clear [`Player::foreign_mover`] and walk our own body around under a creature's mover.
-    ///
-    /// This is the *whole* of what stops a mind-controlled player walking away, and that is a
-    /// verified property of the server rather than an assumption: vmangos never roots the victim,
-    /// sends it no speed change, its `StopMoving()` is a documented no-op for a possessed player,
-    /// and `HandleMovementOpcodes` carries no charm check — so it will accept and apply any
-    /// movement we choose to send. Nothing else is coming; if the client does not stop itself,
-    /// nothing stops.
-    ///
-    /// Deliberately **not** a [`MoveModes`] entry. That family is the four ack'd server modes
-    /// (decision 0866), each with its own SMSG/ack pair and its own movement-flag bit; this owes no
-    /// ack, carries no flag, and suppresses turning too — which root explicitly does not.
+    /// `SMSG_CLIENT_CONTROL_UPDATE` with `allowMove = 0` named the unit we drive: us, while someone
+    /// mind-controls us, or our possessed creature when feared or confused, the possession
+    /// standing. The reference zeroes its mover; vmangos neither roots a charmed player nor refuses
+    /// its movement, so nothing else holds the body. Unlike a root, it stops turning too.
     pub(crate) control_lost: bool,
-    /// **We hold somebody else's reins** — a unit the server handed us and we claimed as our mover
-    /// (mind-controlling a creature, Eye of Kilrogg). `None` whenever the mover is our own body.
-    ///
-    /// While this holds, the controller must not drive our own body onto the wire, and the reason
-    /// is sharper than tidiness: outbound `MSG_MOVE_*` carry **no guid** — the server attributes
-    /// them to whatever we last claimed — so streaming our body's pose under a claimed creature's
-    /// mover would teleport that creature onto us. Suppressing our body is also simply what
-    /// possession looks like: your own character stands still while you drive the other thing.
-    ///
-    /// While this holds, [`crate::net::Embodied`] sits on that unit's entity — or on nothing at
-    /// all until it streams — and the controller drives *it*. Our own body then simulates nothing,
-    /// animates from nothing, and sends nothing, which is both the fix and what possession looks
-    /// like from the outside (decision 1277).
+    /// The unit we drive in place of our body (a mind-controlled creature, Eye of Kilrogg), `None`
+    /// for our own. Our body must then send nothing: outbound `MSG_MOVE_*` carry no guid, so the
+    /// server applies them to whatever we last claimed.
     pub(crate) foreign_mover: Option<u64>,
-    /// **The reins are between hands** — the body we drive has changed, and we drive *nothing*
-    /// until we have adopted its pose.
-    ///
-    /// Set when the mover guid changes (the control handshake in [`super::wire_in`], and
-    /// [`super::embody::maintain_embodiment`] when the marker follows it); cleared at the same
-    /// take-control edge that seizes our own body on login, once a streamed pose is actually there
-    /// to seize. Both halves matter:
-    ///
-    /// - **Adopt before driving** — the resource's `pos`/facing still describe the body we were
-    ///   driving a moment ago, so the first streamed frame would otherwise report the creature
-    ///   standing wherever we left our character.
-    /// - **Drive nothing while pending** — the handshake runs *inside* the controller, a frame
-    ///   ahead of the marker that follows it, and the claimed unit may not have streamed in at all.
-    ///   Either way there is a window where what we intend to drive and what carries the marker
-    ///   disagree, and driving during it means writing one body's pose onto another.
-    ///
-    /// A flag rather than a direct write because the pose lives on the entity and the seize needs
-    /// the camera too — both of which the controller already holds and the marker's owner does not.
+    /// The driven body changed, and we drive nothing until its streamed pose is adopted, since
+    /// `pos` and the facing still describe the last one. Set when the mover guid changes, cleared
+    /// at the take-control edge.
     pub(crate) reseat: bool,
-    /// Feet position in **Bevy** coords (converted to raw WoW only when sending to the server).
+    /// Feet position in Bevy coords, converted to WoW coords only for the wire.
     pub(crate) pos: Vec3,
-    /// Vertical velocity (yd/s, Bevy +Y up) for gravity/jump/fall. Integrated each frame; zeroed while
-    /// grounded. Fed into avian's `MoveAndSlide`.
+    /// Vertical velocity (yd/s, Bevy +Y up), zeroed while grounded.
     pub(super) vel_y: f32,
-    /// Current horizontal velocity (yd/s). Live (from input) while grounded; while airborne it's the
-    /// take-off momentum (a moving jump keeps its trajectory — the WoW feel), except a jump from a
-    /// standstill gets one [`AIR_NUDGE_SPEED`] steer in the pressed direction. Zero when standing still.
+    /// Horizontal velocity (yd/s): from input while grounded, the frozen take-off momentum while
+    /// airborne, bar one [`AIR_NUDGE_SPEED`] steer after a standstill jump.
     pub(super) horiz_vel: Vec3,
-    /// The CMovement `moveFlags` we last streamed to the server (directional + turn bits, see
-    /// [`crate::net::move_flags`]). Diffed against this frame's flags to emit a `MSG_MOVE_*` per
-    /// movement-axis transition — the way the real client announces its movement.
+    /// The movement flags we last streamed; this frame's are diffed against them to emit a
+    /// `MSG_MOVE_*` per axis transition.
     pub(super) move_flags: u32,
-    /// The facing (WoW orientation) as of **last frame** — the reference's facing-change detector
-    /// (`0x617170`, exact equality against the unit's live facing cell). Any change off the turn axis
-    /// streams a `MSG_MOVE_SET_FACING` that frame, moving or standing, so observers see us aim
-    /// (decision 0617). Updated every frame whether or not a packet went out.
+    /// Last frame's facing: any change off the turn axis streams `MSG_MOVE_SET_FACING`, moving or
+    /// not (the reference's detector `0x617170`, exact equality).
     pub(super) last_facing: f32,
-    /// The **position we last told the server** (WoW coords, exactly the floats that went on the
-    /// wire). Diffed against this frame's live position to catch a drift we would otherwise never
-    /// report: our resolver settles a resting body a fraction of a millimetre after the packet that
-    /// reported the rest (a landing, a login, a teleport onto a server-authored pose), and while
-    /// standing still nothing else goes out. vmangos compares an incoming position to its stored one
-    /// with EXACT float equality and interrupts a movement-interrupt cast on any difference, so a
-    /// stale copy turns the next packet — in practice the first `MSG_MOVE_SET_FACING` of a
-    /// right-drag — into a mid-cast "you moved". Decision 0907; the reconcile lives in
-    /// [`super::movement_net::stream_self_movement`].
+    /// The exact position floats we last sent (WoW coords). vmangos interrupts a cast on any change
+    /// to its stored position (`Player.cpp:6092`), so the resolver's tiny settle after a reported
+    /// rest is sent on its own ([`super::movement_net::stream_self_movement`]) before the next
+    /// facing change can carry it as a move.
     pub(super) last_pos: [f32; 3],
-    /// 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.
+    /// A stand state committed locally, sent or from `SMSG_STANDSTATE_UPDATE`, whose echo into
+    /// `UNIT_FIELD_BYTES_1` has not landed: the reference's predicted cache `[player+0x1d68]`
+    /// (`0x6127b0`).
     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
-    /// isn't there the instant we snap to it. While settling the movers hold the avatar in place
-    /// with gravity **off** — otherwise it falls through the not-yet-loaded city/building floor —
-    /// and the loading screen waits for the release. **Released by the terrain streamer** (decision
-    /// 0737) once the destination is resident — scene spawned and collider queue quiet
-    /// ([`crate::loading_screen::WorldLoadProgress`]) — or at [`SETTLE_TIMEOUT`]; **never by ground
-    /// contact**, which a flyer, a swimmer, or a genuinely airborne teleport never produces (the
-    /// old probe release ran only in the walk mover, and each other mover mode needed — and got —
-    /// its own leak patch before 0737 deleted the class).
+    /// Holding the body still, gravity off, after a teleport, summon or login until the
+    /// destination's colliders stream in. Released by the terrain streamer on residency or at
+    /// [`SETTLE_TIMEOUT`], never by ground contact, which a flyer or a swimmer never makes.
     pub(crate) settling: bool,
-    /// `Time::elapsed_secs` deadline to give up settling and release (see [`Player::settling`]).
-    /// Pushed forward by the streamer while [`Player::world_stale`] (0710's fail-closed law) and
-    /// while any load-progress counter is still moving (B263, decision 1303) — so it measures
-    /// *stall*, and a slow arrival can never exhaust it.
+    /// When to give up settling (`Time::elapsed_secs`), pushed on while the world is stale or
+    /// still loading.
     pub(crate) settle_deadline: f32,
-    /// `Time::elapsed_secs` when the current settle hold began (the snap) — what the `sett` trace
-    /// reports the wait against. The deadline above stopped measuring this the moment it became a
-    /// stall budget: it is re-pushed all through a live stream, so "deadline minus timeout" names
-    /// the last push, not the arrival.
+    /// When the current settle hold began (`Time::elapsed_secs`), which the `sett` trace reports.
     pub(crate) settle_since: f32,
-    /// **The colliders under our feet may still belong to the map we just left.** Set at every
-    /// snap, cleared by the terrain streamer once the destination's own world is resident.
-    ///
-    /// The snap runs a whole `WorldStage` *before* the streamer swaps maps — so on the arrival
-    /// frame the physics world is still entirely the old map's, and its despawn is a deferred
-    /// command on top of that. Any settle judgement made in that window would be about the wrong
-    /// world — and an **instance entrance sits within a yard of its own outdoor portal**
-    /// (Zul'Gurub's pad is z 92.53 against the Stranglethorn ground you left at 92.30), which is
-    /// how the pre-0710 ground probe declared the floor found on frame 0 and dropped the body
-    /// 15 yd through the ZG city WMO. While this flag is set the streamer makes no release
-    /// judgement and pushes [`Player::settle_deadline`] forward, so the timeout budget measures
-    /// time waiting for the *destination's* world (decisions 0710 + 0737).
+    /// The colliders under us may still be the map we left: the snap runs a whole `WorldStage`
+    /// before the streamer swaps maps. Set at every snap, cleared once the destination is resident;
+    /// while set, the streamer judges no release and pushes [`Player::settle_deadline`] on.
     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.
+    /// The camera pitch the login seize seats: the saved pose's `cameraPitch` when
+    /// [`super::camera_saved`] restored one, else the stock opening pitch.
     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
-    /// is pending, so the relocation IS the hand-back. `drive_self_ride` takes this flag first:
-    /// it drops the ride + spline without mirroring the stale flight pose over the snap (the
-    /// 4-yd-hover + full-6s-settle landing bug, decision 0501) and owes no `CMSG_MOVE_SPLINE_DONE`.
+    /// A same-map teleport voided the self server-ride: vmangos ignores the spline-done ack while
+    /// the teleport is pending (`MovementHandler.cpp:819`), so `drive_self_ride` drops the ride
+    /// without mirroring its stale pose and sends no `CMSG_MOVE_SPLINE_DONE`.
     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
-    /// (`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
-    /// (0455) never settles and acks immediately, as before.
+    /// A `MSG_MOVE_WORLDPORT_ACK` owed at the settle release: the reference sends it only after its
+    /// blocking load returns (`0x401cae`, after `0x66fbe0`), and vmangos has no load timeout. A
+    /// riding crossing never settles and acks at once.
     pub(crate) owes_worldport_ack: bool,
     /// `Time::elapsed_secs` when we last sent a heartbeat.
     pub(super) last_heartbeat: f32,
-    /// **Milliseconds of movement simulation this client advanced through without integrating** —
-    /// the quantity `CMSG_MOVE_TIME_SKIPPED` reports (decision 1935). Accumulated while
-    /// [`Self::settling`] holds the mover (the world under us has not streamed in, so no step
-    /// runs), drained and sent by [`super::movement_net::stream_self_movement`] on the release
-    /// edge. Fractional because it accumulates a frame `dt` at a time; the wire takes whole ms.
+    /// Milliseconds of movement the settle hold skipped, sent as `CMSG_MOVE_TIME_SKIPPED` on the
+    /// release edge; fractional because it accrues a frame `dt` at a time.
     pub(super) skipped_ms: f32,
-    /// `Time::elapsed_secs` when the current airborne phase (jump or step-off) began, else `None` on the
-    /// ground. Drives the wire `fall_time` (ms airborne) and detects the take-off / landing transitions
-    /// that emit `MSG_MOVE_JUMP` / `MSG_MOVE_FALL_LAND` (decision 0053).
+    /// When the current airborne phase began (`Time::elapsed_secs`): the wire `fall_time`, and the
+    /// take-off and landing edges that emit `MSG_MOVE_JUMP` and `MSG_MOVE_FALL_LAND`.
     pub(super) airborne_since: Option<f32>,
-    /// At rest wedged between steep faces ([`WEDGE_STILL_FRAMES`] stalled airborne frames):
-    /// treated as standing — the fall is over, walking control is live — while a close down-probe
-    /// still finds support. Cleared by real ground, by jumping, or by walking off the support into
-    /// open air (a fresh fall). Decisions 0211/0212.
+    /// At rest wedged between steep faces: standing while a close down-probe still finds support,
+    /// until real ground, a jump or walking off into open air.
     pub(super) wedged: bool,
     /// Consecutive stalled airborne frames (see [`WEDGE_STALL_RATIO`]).
     pub(super) wedge_still: u8,
-    /// **Supported by a certified steep contact, not a walkable floor** — the reference's
-    /// `0x4000000`, whose meaning decision 1125 settled from the bytes. Two ways to earn it, one
-    /// meaning: climbing the slanted skirt of a low edge already certified clearable (the foot-cone
-    /// ride, 1123), or resting on the surface being followed down off a ledge (1127).
-    ///
-    /// Counts as standing. The frame-start ground probe looks straight down and sees only the steep
-    /// face, so without this the frame reads as airborne and gravity takes the body off the surface:
-    /// the climb undone into the mid-face dwelling 0209 exists to prevent, and on the way down the
-    /// dive past the edge the director reported. Re-earned every frame from the certification going
-    /// up and from the cone's descent bound coming down — neither can hold a body that has not just
-    /// proved it is on a surface — and cleared the moment a walkable floor takes over.
+    /// On a certified steep contact rather than a walkable floor, the reference's `0x4000000`:
+    /// riding a low edge's foot cone up, or following a surface down off a ledge. Counts as
+    /// standing, since the straight-down ground probe sees only the steep face; re-earned each
+    /// frame.
     pub(super) steep_support: bool,
-    /// **A `SetHover(true)` owes a jump** — the reference's hover wire handler `0x61a620` does not
-    /// merely set the flag: its enable arm is `61a62e push 0; 61a630 call 0x7c6230`, i.e.
-    /// `CMovement::Jump(force = 0)`, and only *then* `61a646 call 0x7c7310` sets `0x40000000`.
-    /// The disable arm is the mirror — `61a637 call 0x7c61c0` (`StartFalling`). Neither of the
-    /// other two granted modes does anything of the kind: `SetWaterWalk`'s handler `0x61a3d0` is
-    /// four instructions around `call 0x7c7280`, and `SetFeatherFall`'s `0x61a4e0` only refreshes
-    /// the fall clamp. **Hover is the one mode that moves the body**, and that is the whole of why
-    /// Levitate (spell 1706, which grants all three) visibly launches you (decision 1620, B322).
-    ///
-    /// `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. 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,
-    /// while our mover re-derives contact from probes every frame and would zero the velocity again
-    /// on the next step. Consumed at the two take-off sites in [`super::control`], where the
-    /// keyboard jump is consumed, so the seed is picked by the same code that picks it for Space.
+    /// A hover grant owes a jump: the reference's handler `0x61a620` calls `CMovement::Jump(0)`
+    /// (`0x61a630`) before setting the flag, and its disable arm calls `StartFalling` (`0x61a637`).
+    /// Latched for the take-off site, since our mover re-derives ground contact every frame and
+    /// would cancel a jump committed here.
     pub(super) hover_launch: bool,
-    /// **The knockback waiting to be flown** — one [`PendingKnockback`], armed by
-    /// [`super::wire_in`] the frame `SMSG_MOVE_KNOCK_BACK` lands and consumed by the take-off site in
-    /// [`super::control`] (the same place the keyboard jump and the hover launch are consumed, so
-    /// all three enter the mover through one door). `None` the rest of the time.
+    /// The knockback waiting to be flown, armed by `SMSG_MOVE_KNOCK_BACK` and taken at the take-off
+    /// site with the jump and the hover launch.
     pub(super) knockback: Option<PendingKnockback>,
-    /// The take-off vertical speed (yd/s, WoW +Z up) snapshotted when the airborne phase began — the
-    /// client's `StartFalling` argument (`+0xa0`, constant per arc) and the `zspeed` we send in the
-    /// jump tail: `JUMP_SPEED` for a jump, **exactly 0** for a step-off (the walk election calls
-    /// `StartFalling(0)`). Observers replay the parabola from it, and the FALLINGFAR latch splits
-    /// its distance/timer legs on it (decision 0179); held constant while `fall_time` advances.
+    /// The arc's take-off vertical speed (yd/s, WoW +Z up), the client's `StartFalling` argument
+    /// (`+0xa0`) and the jump tail's `zspeed`: [`JUMP_SPEED`] for a jump, exactly 0 for a step-off.
     pub(super) jump_zspeed: f32,
-    /// **The launch vertical speed, recorded the instant a take-off is decided** — before this
-    /// frame's gravity touches it. [`super::arc`] snapshots [`Self::jump_zspeed`] from *this*, not
-    /// from `vel_y`: the mover now integrates gravity on the take-off frame too (decision 1740), so
-    /// by the time the arc bookkeeping runs `vel_y` is already one step down the parabola and would
-    /// seat a launch speed `g·dt` short. The reference has no such ambiguity — `+0xa0` is written
-    /// once by `StartFalling` and never touched again for the arc.
+    /// The launch vertical speed, recorded before this frame's gravity: [`Self::jump_zspeed`] is
+    /// seeded from this, since `vel_y` is already a step down the arc when [`super::arc`] runs.
     pub(super) launch_vz: f32,
-    /// **The arc's direction nibble — the reference's `[CMovement+0x40] & 0xf`** (decision 1740).
-    /// Air control opens exactly while this is CLEAR: `0x7c5a20`/`0x7c5c20` bail on
-    /// `FALLING && arg == 0`, and the only two openers that pass `arg = 1` sit behind
-    /// `0x7c6afc test al,0xf`. So a jump from a standstill can be steered once, a jump taken with a
-    /// direction already held cannot, and a **knockback never can** — its launch plants FORWARD
-    /// itself (`0x6179c0`'s `0x617a18 or edx,0x8001`), which is the real freeze mechanism and has
-    /// nothing to do with the arc's speed. Seeded at take-off, set by the one nudge that fires,
-    /// cleared when the arc ends.
-    ///
-    /// This replaced a `horiz_vel.length_squared() < 0.01` proxy that agreed with the reference for
-    /// every ordinary jump and disagreed for one input: a knockback with `xy_speed ≈ 0`, which the
-    /// proxy read as "standing still, may steer".
+    /// Whether the arc's direction nibble (`[CMovement+0x40] & 0xf`) is set: air control opens only
+    /// while it is clear (`0x7c6afc`), so a knockback, which plants FORWARD (`0x617a18`), never
+    /// steers. Seeded at take-off, set by the nudge, cleared when the arc ends.
     pub(super) arc_dirs_set: bool,
-    /// This airborne arc was launched by a **knockback**, so its planted FORWARD bit rides the wire
-    /// for the arc's whole length (decision 1740) — the reference's `0x617a18` sets FORWARD and
-    /// clears BACKWARD, and the send mask `0x618909 and edx,0x75a07dff` keeps bit 0. Distinct from
-    /// [`super::mover::Outcome::knocked`], which is true on the launch frame only.
+    /// This arc is a knockback's, so its planted FORWARD rides the wire the whole arc (`0x617a18`;
+    /// the send mask `0x75a07dff` keeps bit 0).
     pub(super) knock_arc: bool,
-    /// **Was the body airborne at the end of the previous mover step** — the mover's own record,
-    /// so the arc-start seeding does not have to read [`Self::airborne_since`] (decision 1740).
-    /// That field belongs to the *wire* lifecycle in [`super::arc`] and is written by
-    /// [`super::flags`], which runs AFTER the mover: reading it here made a physics decision
-    /// depend on a system further down the frame, so a step-off's launch state was seeded a frame
-    /// late whenever the mover ran on its own. Separate owners, separate fields.
+    /// Airborne at the end of the last mover step: the mover's own record, since
+    /// [`Self::airborne_since`] is written by [`super::flags`], which runs after the mover.
     pub(super) airborne_prev: bool,
-    /// The translation-direction move-flag bits ([`crate::creature_anim::move_flags::ANY_MOVE`]) the
-    /// current airborne arc launched with. Mid-air these are the *actual* motion — momentum is frozen at
-    /// takeoff, so held keys move nothing — and the live flags (animation, pose, wire) read them instead
-    /// of the keys (decision 0056: the flags mirror the avatar's motion, never raw key state). Re-seeded
-    /// by the standstill-jump air nudge, the one input that really moves us mid-air. Stale while grounded.
+    /// The direction bits the current arc launched with: mid-air they are the actual motion, so the
+    /// live flags read them instead of the keys; re-seeded by the air nudge, stale while grounded.
     pub(super) airborne_dirs: u32,
-    /// Launch height (Bevy Y) snapshotted when the airborne arc began — the client's StartFalling
-    /// `+0x7c = +0x18` Z snapshot; the FALLINGFAR distance leg measures descent below it.
+    /// Launch height (Bevy Y), the client's `StartFalling` z snapshot (`+0x7c`): the FALLINGFAR
+    /// distance leg measures descent below it.
     pub(super) fall_start_y: f32,
-    /// MOVEFLAG_FALLINGFAR latched for this arc: a jump descended [`FALL_FAR_DROP`] below its
-    /// launch, or a step-off fall lasted [`FALL_FAR_TIME`] (the legs are exclusive on the launch
-    /// vz — decision 0179). Latched once per arc (only landing clears it, like the client's
-    /// StopFalling); sets [`crate::creature_anim::move_flags::FALLING_FAR`] on the live flags — the
-    /// mid-air Fall(40) pose, the landing-anim gate, and the wire.
+    /// `MOVEFLAG_FALLINGFAR` latched for this arc ([`FALL_FAR_DROP`], [`FALL_FAR_TIME`]); only
+    /// landing clears it, as the client's `StopFalling` does.
     pub(super) fall_far: bool,
-    /// The character's facing (Bevy yaw, radians). Right-drag and movement keep this in sync with the
-    /// camera; left-drag (camera-only orbit) leaves it alone, so it can diverge from the camera yaw —
-    /// and that offset now persists (no auto-follow back behind while moving). Sent to the server as
-    /// orientation, and the basis WASD move in. This is the *aim*/facing — distinct from the rendered
-    /// body heading.
+    /// The facing (Bevy yaw, radians): the aim sent as orientation and the basis WASD move in.
+    /// Right-drag and movement sync it to the camera, left-drag does not; the body is `model_yaw`.
     pub(super) face_yaw: f32,
-    /// In **swim mode** ([`super::swim`]): the water over the feet crossed the swim-enter depth, so
-    /// the avatar floats and swims in 3D instead of walking, sets `MOVEFLAG_SWIMMING` (lighting the
-    /// swim gait and streaming it), and pitches its body to the swim heading. Hysteresis-latched
-    /// (see [`super::swim::update_swimming`]) so wading the boundary doesn't flicker.
+    /// Swimming (`MOVEFLAG_SWIMMING`): the water over the feet crossed the swim-enter depth,
+    /// latched with hysteresis ([`super::swim::update_swimming`]).
     pub(crate) swimming: bool,
-    /// **Our own collision height** — the avatar's copy of [`crate::entities::CollisionHeight`],
-    /// mirrored onto this resource because the swim arm runs off it and never touches the ECS
-    /// entity. Every swim depth line is a fraction of it, which is why a gnome floats with her head
-    /// out and a night elf sits 0.3 yd deeper (decision 0645). Kept as the component's own type
-    /// rather than a bare `f32` precisely so `Player::default()` cannot seed it to **zero** — at
-    /// zero every depth line collapses to 0 and the avatar swims on dry land. It defaults to
-    /// [`DEFAULT_COLLISION_HEIGHT`] and is replaced once our body's display id resolves.
+    /// Our body's collision height, of which every swim depth line is a fraction. The component's
+    /// own type, so `Player::default()` gives [`DEFAULT_COLLISION_HEIGHT`] rather than 0, which
+    /// would swim on dry land.
     pub(crate) collision_height: crate::entities::CollisionHeight,
-    /// **The liquid surface over our feet, as the last movement tick left it** — Bevy-Y, `None`
-    /// when there is no liquid there.
-    ///
-    /// Cached rather than re-queried, because that is what the reference reads. `0x511ad0`'s depth
-    /// comes through `0x670630`, which is a **field accessor** and not a query: `0x670637 test
-    /// byte ptr [ecx+0x90],0x20` gates it and `0x670640 mov eax,[ecx+0x98]` returns whatever the
-    /// movement tick last stored. The camera's water corridor
-    /// ([`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).
+    /// The liquid surface over our feet as the last movement tick stored it (Bevy Y). The camera's
+    /// water corridor reads this a frame late, as the reference's camera reads the tick's cache
+    /// through the field accessor `0x670630`; the lag keeps its depth off a band edge.
     pub(crate) liquid_surface: Option<f32>,
-    /// The **mover pitch** (radians, +up) — the client's persistent per-unit pitch
-    /// (`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°; 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
-    /// orbit steers nothing (it doesn't turn the character, so it must not bend the swim);
-    /// Space never touches the pitch (it is the Jump command, 0487).
-    ///
-    /// **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 (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
-    /// (the `Ry` law of `0x60a110`, see the render block in [`super::control`]).
+    /// The mover pitch (radians, +up), `CMovement+0x20`, live in every mode: mouse-look sets it
+    /// straight to the camera pitch within ±89° (`SetPitch` `0x7c6f70`, which stores before any
+    /// swim test), and it holds when unsteered; only stop-swim and teleport zero it (`0x7c6e80`).
+    /// Swimming reads it for travel, pose and the wire; on land, water walking does (`0x63161e`).
     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. 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
-    /// leaves their value alone. Re-asserting the camera angle every frame would overwrite the
-    /// swim-exit levelling on the very next one, and a water-walker who left the water nose-down
-    /// would fall straight back through the surface.
+    /// The camera pitch the last pitch push carried: the reference pushes only on mouse motion
+    /// (`0x514400`), so a push here needs the aim to differ, and a still mouse leaves the drunk
+    /// wobble and the stop-swim levelling (`0x7c6e80`) in place.
     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: `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.
+    /// This frame's flag-derived swim speed (yd/s), 0 without swim input: the stroke's playback
+    /// numerator, as `0x5fe2f0` divides `GetCurrentSpeed` by the clip's speed. Stale on land.
     pub(super) swim_stroke_speed: f32,
-    /// The rendered **body** heading (Bevy yaw, radians) — the client's display-facing pose: while
-    /// strafing it eases toward `face_yaw ± 90°/45°` ([`crate::creature_anim::strafe_body_offset`])
-    /// with the
-    /// SpineLow/Head counter-twist walking the upper body back onto the aim
-    /// ([`crate::creature_anim::BodyTwist`]); moving without a strafe it snaps to `face_yaw`;
-    /// standing it chases at [`STATIONARY_CHASE_RATE`] × turn rate.
+    /// The rendered body heading (Bevy yaw): eased to the strafe offset while strafing
+    /// ([`crate::creature_anim::strafe_body_offset`]), snapped to `face_yaw` while otherwise
+    /// moving, and chasing at [`STATIONARY_CHASE_RATE`] while standing.
     pub(super) model_yaw: f32,
-    /// A server-authored spline owns the avatar this frame (Charge, and later knockback/taxi/fear):
-    /// the server sent an `SMSG_MONSTER_MOVE` for our own guid, so `sample_splines` drives the
-    /// transform and [`super::server_ride::drive_self_ride`] mirrors it into `pos`/facing while input,
-    /// physics, and the outbound movement stream all yield. Set the frame the ride's [`Spline`]
-    /// appears, cleared the frame it ends — where we send `CMSG_MOVE_SPLINE_DONE` and resume.
+    /// A server spline drives the body (`SMSG_MONSTER_MOVE` for our guid: a charge, a taxi):
+    /// input, physics and the movement stream yield, and its end sends `CMSG_MOVE_SPLINE_DONE`.
     pub(super) server_riding: bool,
     /// The `splineId` of the ride in progress (echoed in `CMSG_MOVE_SPLINE_DONE` when it ends).
     pub(super) ride_spline_id: u32,
-    /// Was the ride in progress a **ground** path? — the `FLYING` bit of the [`crate::net::Spline`]
-    /// that drove it, kept because the frame the ride *ends* has already lost the spline
-    /// (`sample_splines` drops a finished path) and the endpoint still has to be grounded by the
-    /// same law as every frame before it (decision 1927). A taxi's endpoint keeps its own altitude.
+    /// Whether the ride is a ground path (no `FLYING`), kept because its last frame has lost the
+    /// spline and must still be grounded; a taxi's endpoint keeps its altitude.
     pub(super) ride_grounded: bool,
-    /// Standing on a transport (boat/zepp): the mover lives in that platform's frame (decision
-    /// 0438 phase 2). Attached when the ground support is a [`crate::transport::Transport`]
-    /// collider; kept through jumps above the deck (deck-frame ballistics — a jump on a moving
-    /// boat lands where it took off); detached on world-ground support, on entering the water,
-    /// or when the boat despawns. See the carry/attach blocks in [`super::control`].
+    /// Standing on a transport, the mover in its frame: attached on a
+    /// [`crate::transport::Transport`] support, kept through deck jumps, detached on world ground,
+    /// in water or when the transport despawns.
     pub(super) ride: Option<PlayerRide>,
 }
 
-/// The player's attachment to a transport's platform frame — see [`Player::ride`].
+/// The player's attachment to a transport's frame ([`Player::ride`]).
 #[derive(PartialEq)]
 pub(super) struct PlayerRide {
-    /// The transport's ECS entity (its collider is the ground support that attached us).
+    /// The transport's entity, whose collider is the support that attached us.
     pub(super) entity: Entity,
-    /// The transport's guid — the wire tail names the boat by guid, not entity.
+    /// The transport's guid, which the wire's transport tail carries.
     pub(super) guid: u64,
-    /// Feet position in the transport's local frame (Bevy axes), snapshotted at frame end;
-    /// next frame's carry recomposes `world = boat_transform × local` before input integrates.
+    /// Feet in the transport's frame (Bevy axes), snapshotted at frame end; the next frame's carry
+    /// recomposes the world position from it before input integrates.
     pub(super) local_pos: Vec3,
-    /// The boat yaw (Bevy, radians) at the snapshot — the carry applies the per-frame delta to
-    /// `face_yaw` (the deck turns the standing player with it), and the wire's local orientation
-    /// is `face_yaw − boat_yaw`.
+    /// The transport's yaw at the snapshot: the carry turns `face_yaw` by its per-frame delta, and
+    /// the wire's local orientation is `face_yaw − boat_yaw`.
     pub(super) boat_yaw: f32,
 }
 
-/// **A knockback the server has aimed at our mover, latched until the mover flies it**
-/// (`SMSG_MOVE_KNOCK_BACK`, decision 1702). A latch and not a direct write for [`Player::hover_launch`]'s
-/// reason: the reference commits the launch inside its handler and `MOVEFLAG_FALLING` then keeps the
-/// walk resolver off the body, while our mover re-derives ground contact from probes every frame and
-/// would zero the velocity again on the next step. So the take-off is taken where every other
-/// take-off is taken — inside [`super::mover::step`], by the same code that seeds a jump.
-///
-/// It carries the handshake with it because the two are inseparable: the ack is owed *only* if the
-/// launch actually happened, and it must echo `launch` back verbatim as the `MovementInfo` jump tail
-/// (the server matches all four floats within `0.01` before it will relay the knockback to anyone).
+/// A knockback aimed at our mover (`SMSG_MOVE_KNOCK_BACK`), latched until the mover flies it. The
+/// ack is owed only if the launch happened and echoes `launch` as its jump tail: vmangos matches
+/// all four floats within 0.01 (`Unit.cpp:7096-7100`).
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub(super) struct PendingKnockback {
-    /// Our own mover guid, echoed in the ack (a **full** u64 there, packed on the way in).
+    /// Our mover guid, echoed in the ack as a full u64 (it arrives packed).
     pub(super) guid: u64,
-    /// The server's movement counter for this change — echoed, or the ack is a logged cheat.
+    /// The server's movement counter, echoed or the server rejects the ack.
     pub(super) counter: u32,
-    /// The launch quad: world-XY direction + horizontal speed + the take-off vertical speed in the
-    /// jump tail's **down-positive** convention (negative is upward — decision 0054).
+    /// The launch: world-XY direction, horizontal speed and vertical speed, down-positive
+    /// (negative is up).
     pub(super) launch: JumpInfo,
 }
 
 impl Player {
-    /// **Take the jump a `SetHover(true)` owes**, consuming the latch — the reference's
-    /// `CMovement::Jump(force = 0)` at `0x61a630`, minus the seed select and the commit, which are
-    /// the caller's because they are shared with Space (decision 1620).
-    ///
-    /// The two refusals are `0x7c625c test ah, 0x30` — **ROOT** (`0x1000`) and **FALLING**
-    /// (`0x2000`), our [`Self::airborne_since`]. The one it does *not* take is the hover refusal at
-    /// `0x7c623a`, which `force == 0` skips at `0x7c6236`; that is the entire reason this leg
-    /// exists, since the body it is about to launch was granted hover in the same breath.
-    ///
-    /// It is a take-and-clear rather than a level read because the reference's handler fires once
-    /// per opcode, not once per frame: a `SetHover` that lands on a rooted or already-falling body
-    /// is *dropped*, not deferred until the refusal lifts (`0x7c6288 xor eax,eax; ret` — the
-    /// refusal returns failure and nothing retries it).
+    /// Take the jump a hover grant owes, clearing the latch: `Jump(0)` refuses only ROOT and
+    /// FALLING (`0x7c625c`), skipping the hover test (`0x7c6236`), and a refused jump is dropped,
+    /// not retried.
     pub(super) fn take_wire_jump(&mut self) -> bool {
         let fire = self.hover_launch && !self.modes.rooted && self.airborne_since.is_none();
         self.hover_launch = false;
         fire
     }
 
-    /// **Take the knockback the server aimed at us**, consuming the latch (decision 1702).
-    ///
-    /// Unconditional here, unlike [`Self::take_wire_jump`]: the refusals that matter are the mover's
-    /// own — the settle hold and the root anchor, both of which freeze *every* axis and are already
-    /// the reason a rooted body cannot be launched by anything. Taking it here and letting the mover
-    /// decline keeps one refusal in one place, and keeps the ack honest: the caller sends
-    /// `CMSG_MOVE_KNOCK_BACK_ACK` only if the launch actually happened, because that ack's whole
-    /// content is a claim about the arc we are now flying.
-    ///
-    /// Take-and-clear, not a level read, for the same reason the hover launch is: the reference's
-    /// handler fires once per opcode. A knockback that arrives on a frozen body is *dropped*, never
-    /// deferred until the freeze lifts.
+    /// Take the knockback, clearing the latch; the mover may still decline it (the settle hold, a
+    /// root), and then it is dropped, not deferred, and no ack is sent.
     pub(super) fn take_knockback(&mut self) -> Option<PendingKnockback> {
         self.knockback.take()
     }
 
-    /// Turn the avatar's **aim** by `radians` — the scripted mouse-turn's one lever
-    /// (`capture::probe_look`, decision 0621). Writing `face_yaw` is deliberately the whole of it:
-    /// from here on this is the identical path a real mouse-turn takes, and it is the same value
-    /// `stream_self_movement` diffs to decide on a `MSG_MOVE_SET_FACING`. A named method rather
-    /// than a `pub(crate)` field for decision 1174's reason — an instrument may reach into
-    /// gameplay, but not by opening gameplay's internals to the whole crate.
+    /// Turn the aim by `radians`, the scripted mouse turn (`capture::probe_look`): the same
+    /// `face_yaw` a real mouse turn writes and the facing stream diffs.
     pub(crate) fn turn_aim(&mut self, radians: f32) {
         self.face_yaw += radians;
     }
 
-    /// Aim the avatar's **mover pitch** — the scripted dive's one lever (`capture::probe_pitch`),
-    /// the twin of [`Self::turn_aim`] and for the same reason.
-    ///
-    /// The only writer of this field in gameplay is the mouse-look push in
-    /// `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) 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°
-    /// [`MOUSELOOK_PITCH_CLAMP`], so from here on this is the identical path a real mouse-aimed
-    /// dive takes: the swim frame's travel basis, the body pose, and the wire tail all read this
-    /// 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).
-    /// 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.
-    /// Returns what was actually stored, which is the clamped value — so an instrument reports the
-    /// aim the mover *has* rather than the one it asked for. A sweep that runs past ±89° otherwise
-    /// logs a number the body never held.
+    /// Set the mover pitch, the scripted dive (`capture::probe_pitch`), under `SetPitch`'s ±89°
+    /// clamp (`0x7c6f70`) but without its 2^-20 deadband (`[0x8026bc]`); returns the value stored.
     pub(crate) fn aim_pitch(&mut self, radians: f32) -> f32 {
         self.mover_pitch = radians.clamp(-MOUSELOOK_PITCH_CLAMP, MOUSELOOK_PITCH_CLAMP);
-        // The mouse-look push is edge-triggered on the camera pitch it last saw; parking that at
-        // the value we just wrote keeps a *real* mouse-look from re-pushing an unchanged camera
-        // over the top of the script on the next frame.
+        // Mouse-look pushes on a camera-pitch edge; parking the edge here keeps a still camera
+        // from overwriting the script next frame.
         self.aim_pitch_seen = self.mover_pitch;
         self.mover_pitch
     }
 
-    /// 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 (the listener forward is the character facing, not the camera: `0x483430`).
+    /// The facing (Bevy yaw) sent as orientation, not the rendered `model_yaw`; the 3D-audio
+    /// listener faces it, not the camera (`0x483430`).
     pub(crate) fn facing(&self) -> f32 {
         self.face_yaw
     }
 
-    /// End the post-snap settle hold (decision 0737) — called by the terrain streamer, the only
-    /// system that knows the destination's residency. `resident` = the world arrived (scene +
-    /// colliders); `false` = the [`SETTLE_TIMEOUT`] backstop fired without it. Which end it was is
-    /// the whole diagnosis of a fall-through report, so it goes through the `sett` trace either way.
+    /// End the settle hold, called by the terrain streamer: `resident` is false when
+    /// [`SETTLE_TIMEOUT`] fired first, which the `sett` trace records.
     pub(crate) fn end_settle(&mut self, resident: bool, now: f32) {
         self.settling = false;
         let waited = now - self.settle_since;
         super::move_trace::settle(resident, waited, self.pos);
     }
 
-    /// 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; the CWater0Ripple driver `0x5fa760`).
+    /// The movement flags as last streamed; the water foam tests `& 0xf` (translating) and `& 0x30`
+    /// (turning) on them, as the reference's ripple driver `0x5fa760` does.
     pub(crate) fn move_flags(&self) -> u32 {
         self.move_flags
     }
 
-    /// **What is holding this body still** — every state on the resource that kills WASD, named,
-    /// or `"none"`. An *instrument*, not a gate (decision 1542): the controller keeps its own
-    /// tests, because each of these suppresses a different amount (`control_lost`/`server_riding`
-    /// take the whole controller at [`super::control`]'s early-out; `rooted` zeroes the direction
-    /// vector and the swim amounts but deliberately leaves turning live). What this exists for is
-    /// the question a *log line* has to answer after a session boundary — "can the character that
-    /// just entered the world be driven?" — which B306 proved nothing was asking: `scripts/smoke.sh`
-    /// has crossed `/logout` → re-enter on every run since 2277 while counting UI rebuilds, errors
-    /// and shutdown writes, none of which a frozen character disturbs.
-    ///
-    /// It does **not** make the smoke a B306 regression: that run logs in as a GM probe, so vmangos
-    /// takes the instant-logout branch and never roots us at all (`smoke.sh` reports that gap on
-    /// every run rather than banking a vacuous pass). What this covers live is the rest of the
-    /// family — a possession or a lost session that leaves the reins where they were.
-    ///
-    /// It reads only this resource. A stun (`UNIT_FIELD_FLAGS`, [`crate::player::UNIT_FLAG_STUNNED`])
-    /// lives on the unit's descriptor block and is not visible from here.
+    /// The states on this resource that stop WASD, comma-joined, or `"none"`: an instrument for the
+    /// log after a session boundary, not a gate. A stun lives on the descriptor and does not show.
     pub(crate) fn movement_suppressors(&self) -> String {
         let named = [
             (!self.active, "inactive"),
@@ -1280,22 +560,9 @@ impl Player {
         }
     }
 
-    /// The **commanded planar speed** in yd/s — the reference's `[[player+0x118]+0x84]`, the
-    /// CMovement speed scalar its producer `0x7c4c90` returns:
-    ///
-    /// ```text
-    /// mov  edx,[ecx+0x40]        ; movement flags
-    /// test dl,0xf                ; the four DIRECTION bits
-    /// jne  …                     ; moving → the speed
-    /// fld  dword ptr [0x7ffd74]  ; = 0.0
-    /// ```
-    ///
-    /// 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` (`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.
+    /// The commanded planar speed (yd/s), the reference's `[[player+0x118]+0x84]` from `0x7c4c90`:
+    /// exactly 0 with no direction bit set, and live, not averaged like the weather wind's
+    /// (`0x67c150`). The precipitation slab's tilt reads it (`0x67bf8b`).
     pub(crate) fn planar_speed(&self) -> f32 {
         if self.move_flags & 0xf == 0 {
             return 0.0;
@@ -1303,34 +570,26 @@ impl Player {
         self.horiz_vel.with_y(0.0).length()
     }
 
-    /// The transport we're standing on (its guid), if any — the platform-frame attachment
-    /// (decision 0438 phase 2). For instruments (the crossing probe watches the ride survive
-    /// the map seam).
+    /// The guid of the transport we stand on, for instruments.
     pub(crate) fn riding(&self) -> Option<u64> {
         self.ride.as_ref().map(|r| r.guid)
     }
 
-    /// The transport we're standing on, as its ECS entity — what the **ride frame** is read from
-    /// (`benilla_world::ride_frame`, decision 1591): a rider's world-space effects are stored in
-    /// the deck's frame, and the deck's live pose is the transport entity's transform.
+    /// The transport we stand on as its entity, whose transform is the deck frame a rider's effects
+    /// are stored in (`benilla_world::ride_frame`).
     pub(crate) fn ride_entity(&self) -> Option<Entity> {
         self.ride.as_ref().map(|r| r.entity)
     }
 
-    /// 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).
-    /// **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`).
+    /// Whether a server spline drives the avatar ([`super::server_ride`]), for instruments. Not
+    /// `UnitOnTaxi`, which reads [`crate::player::UNIT_FLAG_TAXI_FLIGHT`] (`0x517a86`).
     pub(crate) fn server_riding(&self) -> bool {
         self.server_riding
     }
 }
 
-/// 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
-/// streamed flags, so all four can never disagree (decision 0056).
+/// The forward/back axis, summed as the reference's emitter `0x514da0` sums it: autorun, forward
+/// and both-button run +1 each, backward −1; its sign picks the START, and zero is a STOP.
 pub(super) fn forward_axis(
     forward: bool,
     backward: bool,
@@ -1340,17 +599,11 @@ 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 (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 `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.
+/// Whether this frame's input clears autorun: the four of the reference's six writers of `0x1000`
+/// with an analog here. `fwd_down` and `back_down` are key-down edges (`0x514a5a`; a release
+/// restores nothing), `both_engaged` the edge into both-button run (`0x514a73`), and `lost_mover` a
+/// level, the translate gate down (`0x514748`). A jump, a chat box taking focus and a zone change
+/// leave autorun on; mounting's effect in the reference is untraced, and here it leaves it on.
 pub(super) fn autorun_cancelled(
     fwd_down: bool,
     back_down: bool,
@@ -1360,73 +613,23 @@ pub(super) fn autorun_cancelled(
     fwd_down || back_down || both_engaged || lost_mover
 }
 
-/// Does the reference **refuse** this stand-state change? The sit-down gate inside the client's one
-/// `SetStandState` (`0x5ed430`) — bug B155, *"you can sit fully underwater"*.
-///
-/// The client will not seat a body the movement layer is already driving. Sitting down reads the
-/// live `CMovement` flags word `[[this+0x118]+0x40]` — the same word we stream and the cast gates
-/// read (decision 1056) — against a per-target-state mask, and **returns before the packet is
-/// built** when any masked bit is set: no `CMSG_STANDSTATECHANGE`, no local apply, no message.
-/// 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`; decisions 1581/1582):
-///
-/// ```c
-/// if (newState != 0) {
-///     if (newState == 3 && (mov->flags & 0x30))  return;   // 0x5ed4e6, `test byte [ecx+0x40],0x30`
-///     if (mov->flags & 0x20000f)                 return;   // 0x5ed4f8, `test dword [edx+0x40],0x20000f`
-/// }
-/// ```
-///
-/// **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. 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 |
-/// |---|---|---|
-/// | 0 STAND | — (word never read) | never |
-/// | 1 SIT · 2 SIT_CHAIR · 8 KNEEL · … | `0x20000f` | translating **or swimming** |
-/// | 3 SLEEP | `0x20003f` | that, **plus** turning |
-///
-/// Neither mask is invented here; both are byte-verified twice over, at unrelated sites, as this
-/// client's own movement tests — `0x20000f` is the stationary-cast pin's `[9e8] & 0x20000f` at
-/// `0x5fde80` ([`crate::creature_anim::move_flags::CAST_PIN_MOVE`]) and `0x20003f` is the one-shot
-/// route's `[9e8] & 0x20003f` at `0x5fe6dc` ([`ROUTE_COMMITTED_MOVE`](crate::creature_anim::move_flags::ROUTE_COMMITTED_MOVE)).
-/// The swim bit in them is the whole of B155: a swimmer is *always* carrying it, so the press is
-/// refused for as long as they are in the water, whether or not they are stroking. Note what is
-/// **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. 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`.
-///
-/// The emote layer does **not** double up on the water half: the shipped `Emotes.dbc` gives
-/// STATE_SIT (13), STATE_SLEEP (12), STATE_KNEEL (68) and STATE_STAND (26) flags `0x6202`, with the
-/// swim-suppress bit `0x0080` clear — read off the 5875 data by
-/// `ui_chat::tests::the_posture_emotes_carry_no_swim_suppression_flag`. (It has a *separate*,
-/// louder gate that fires on movement rather than water — `0x4000` → `ERR_NOEMOTEWHILERUNNING` —
-/// which benilla does not model; see [`crate::ui_chat::input::emote_send_eligible`].)
+/// Whether the reference's `SetStandState` (`0x5ed430`) refuses this change, returning before the
+/// packet is built. A body that reads dead is refused either way; otherwise standing up never is,
+/// and any other state is refused while translating or swimming (`0x20000f`, `0x5ed4f8`), SLEEP
+/// also while turning (`0x5ed4e6`, which falls through into that test). FALLING is in neither
+/// mask. It is the one setter, so the X key, the posture emotes and the AFK sit all go through it.
 pub(super) fn stand_state_refused(reads_dead: bool, move_flags: u32, new_state: u8) -> bool {
     use crate::creature_anim::move_flags as f;
-    // **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
-    // (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.
+    // Health <= 0 (`0x5ed4ac`) or `UNIT_DYNAMIC_FLAGS & 0x20`, a feigner (`0x5ed4b2`), refuses in
+    // both directions, so it comes before the stand-up exit.
     if reads_dead {
         return true;
     }
-    // The stand-up asymmetry: never gated (`0x5ed4f0 je 0x5ed501`).
+    // Standing up skips the movement word (`0x5ed4f0`).
     if new_state == 0 {
         return false;
     }
-    // SLEEP's extra test, which falls THROUGH into the shared one below rather than replacing it.
+    // SLEEP's turn test falls through into the shared one (`0x5ed4ec`).
     if new_state == 3 && move_flags & (f::TURN_LEFT | f::TURN_RIGHT) != 0 {
         return true;
     }
@@ -1438,10 +641,6 @@ mod stand_state_tests {
     use super::stand_state_refused;
     use crate::creature_anim::move_flags as f;
 
-    /// **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).
     #[test]
     fn a_body_that_reads_dead_can_neither_sit_nor_stand() {
         for state in [0u8, 1, 2, 3, 8] {
@@ -1458,11 +657,9 @@ mod stand_state_tests {
         );
     }
 
-    /// B155's exact press: swimming, X pressed, the client refuses — and the same swimmer standing
-    /// up is not refused, which is the asymmetry that makes the water escapable.
     #[test]
     fn a_swimmer_cannot_sit_but_can_always_stand() {
-        // Floating still, no stroke: SWIMMING alone is enough.
+        // Floating still: SWIMMING alone refuses.
         assert!(
             stand_state_refused(false, f::SWIMMING, 1),
             "sit refused mid-swim"
@@ -1471,21 +668,19 @@ mod stand_state_tests {
             stand_state_refused(false, f::SWIMMING | f::FORWARD, 1),
             "swimming forward too"
         );
-        // …and every seat shape the posture emotes can ask for.
+        // SIT, SIT_CHAIR and KNEEL.
         for state in [1u8, 2, 8] {
             assert!(
                 stand_state_refused(false, f::SWIMMING, state),
                 "state {state} refused mid-swim"
             );
         }
-        // Standing up is never gated — `newState == 0` skips the word entirely.
+        // Standing up (0) skips the word.
         assert!(!stand_state_refused(false, f::SWIMMING | f::FORWARD, 0));
         assert!(!stand_state_refused(false, f::ANY_MOVE | f::SWIMMING, 0));
     }
 
-    /// On dry land the gate is the *translation* test, not a blanket "any flag": sitting while
-    /// walking is refused, sitting while turning in place is not — the turn bits are outside
-    /// `0x20000f`. (The control that says this is a real mask rather than a swim special-case.)
+    /// The turn bits are outside `0x20000f`.
     #[test]
     fn sitting_is_refused_while_translating_and_allowed_while_merely_turning() {
         assert!(
@@ -1504,7 +699,7 @@ mod stand_state_tests {
                 "turning in place: sit granted"
             );
         }
-        // Mode bits are not movement: a rooted or water-walking body may still sit.
+        // Mode bits are not movement.
         for bit in [f::ROOT, f::WATER_WALKING, f::FALLING, f::WALK_MODE] {
             assert!(
                 !stand_state_refused(false, bit, 1),
@@ -1513,13 +708,10 @@ mod stand_state_tests {
         }
     }
 
-    /// SLEEP (3) takes the shared mask **and one more test**, not a different one — the `0x30` turn
-    /// pair falls THROUGH into `0x20000f` (`0x5ed4ec eb 04`, a jmp *into* the second test). 1581
-    /// shipped it as an alternative and this is the assertion that pins the correction: a swimmer
-    /// cannot `/sleep` any more than they can `/sit`, and turning blocks only the sleep.
+    /// SLEEP (3) adds the `0x30` turn test and falls through into `0x20000f` (`0x5ed4ec`).
     #[test]
     fn sleep_takes_both_tests_so_it_is_the_strictest_posture() {
-        // The extra test, SLEEP's alone.
+        // The turn test is SLEEP's alone.
         assert!(
             stand_state_refused(false, f::TURN_LEFT, 3),
             "turning: /sleep refused"
@@ -1529,7 +721,7 @@ mod stand_state_tests {
             !stand_state_refused(false, f::TURN_LEFT, 1),
             "turning blocks ONLY the sleep — a sit is granted"
         );
-        // …and the shared one it falls into, which 1581's either/or wrongly skipped.
+        // The shared test it falls into.
         assert!(
             stand_state_refused(false, f::SWIMMING, 3),
             "swimming: /sleep refused"
@@ -1538,15 +730,15 @@ mod stand_state_tests {
             stand_state_refused(false, f::FORWARD, 3),
             "walking: /sleep refused"
         );
-        // So SLEEP's effective mask is exactly `0x20003f` — the one-shot route's own constant.
+        // SLEEP's effective mask is the one-shot route's `0x20003f`.
         assert_eq!(
             f::TURN_LEFT | f::TURN_RIGHT | f::ANY_MOVE | f::SWIMMING,
             f::ROUTE_COMMITTED_MOVE,
             "`0x20003f`, byte-verified at 0x5fe6dc as well as 0x5ed4e6+0x5ed4f8"
         );
-        // Standing up is still ungated from SLEEP, which is what makes it escapable.
+        // Standing up from SLEEP is still ungated.
         assert!(!stand_state_refused(false, f::ROUTE_COMMITTED_MOVE, 0));
-        // FALLING is in neither mask: a standing jump does not block a posture.
+        // FALLING is in neither mask.
         assert!(
             !stand_state_refused(false, f::FALLING, 3),
             "falling: /sleep granted"
@@ -1558,32 +750,24 @@ mod stand_state_tests {
 mod autorun_tests {
     use super::{autorun_cancelled, forward_axis};
 
-    /// The four states of the reference's axis table (`0x514da0`), in its own terms.
+    /// The reference's axis table (`0x514da0`).
     #[test]
     fn the_axis_reproduces_the_verified_state_table() {
-        // autorun, nothing held → +1, runs forward.
+        // Autorun alone: +1.
         assert_eq!(forward_axis(false, false, false, true), 1);
-        // "autorun + forward held" is the state AFTER W's key-down destroyed the bit, which is why
-        // the table reads +1 and why pressing W is wire-silent: the axis sees forward alone, the
-        // value it already had. The axis never sees the raw combination in this order.
+        // Autorun, then W: the key-down cleared the bit, so the axis sees W alone; nothing is sent.
         assert_eq!(forward_axis(true, false, false, false), 1);
-        // Reaching it the other way (hold W, then toggle) DOES sum to 2 — `0x514da5`'s `mov ebx,1`
-        // for autorun then `inc ebx` for forward. Only the sign is ever consumed, so it behaves
-        // identically; asserted so the byte-shape is recorded rather than accidentally "fixed".
+        // W, then autorun: 2 (`0x514da5`); only the sign is consumed.
         assert_eq!(forward_axis(true, false, false, true), 2);
-        // autorun ON, then S pressed → the key-down destroyed the bit first, so the axis sees
-        // backward alone: −1, a clean reversal.
+        // Autorun, then S: the key-down cleared the bit, so -1.
         assert_eq!(forward_axis(false, true, false, false), -1);
-        // S held, THEN autorun toggled on → the toggle misses the clear helper, both live: 0.
-        // The state no "autorun = held forward" reading can produce.
+        // S, then autorun: the toggle skips the clear and both stay live, so 0.
         assert_eq!(forward_axis(false, true, false, true), 0);
     }
 
-    /// The order-dependence is the whole shape of the feature: the same two inputs, applied in the
-    /// two orders, end in different places — and only one of them can resume.
     #[test]
     fn the_two_orders_differ_and_only_one_resumes() {
-        // Order A — autorun first, then press S.
+        // Autorun, then S.
         let mut autorun = true;
         if autorun_cancelled(false, true, false, false) {
             autorun = false;
@@ -1593,15 +777,14 @@ mod autorun_tests {
             -1,
             "walks backward"
         );
-        // Releasing S leaves nothing behind: the release restores no bit.
+        // Releasing S restores no bit.
         assert_eq!(
             forward_axis(false, false, false, autorun),
             0,
             "stops, does not resume"
         );
 
-        // Order B — S held first, then toggle autorun on. The toggle is not a directional SET, so
-        // the cancel set never fires.
+        // S held, then autorun: the toggle is not a directional set, so nothing clears it.
         let autorun = true;
         assert!(!autorun_cancelled(false, false, false, false));
         assert_eq!(
@@ -1609,7 +792,7 @@ mod autorun_tests {
             0,
             "STOP with S still held"
         );
-        // Releasing S now DOES resume — the bit survived.
+        // Releasing S resumes: the bit survived.
         assert_eq!(
             forward_axis(false, false, false, autorun),
             1,
@@ -1617,7 +800,6 @@ mod autorun_tests {
         );
     }
 
-    /// Both-button run and autorun stack on the same axis, and a held S nets either to a standstill.
     #[test]
     fn both_button_run_shares_the_axis() {
         assert_eq!(forward_axis(false, false, true, false), 1);
@@ -1626,15 +808,14 @@ mod autorun_tests {
             0,
             "S nets the both-button run to a stop"
         );
-        // Engaging the both-button run destroys autorun rather than stacking with it.
+        // Engaging both-button run clears autorun.
         assert!(autorun_cancelled(false, false, true, false));
     }
 
-    /// The verified survivors: only the four listed inputs clear the bit.
     #[test]
     fn a_jump_or_a_chat_line_is_not_in_the_cancel_set() {
         assert!(!autorun_cancelled(false, false, false, false));
-        // Losing the mover (death / root / taxi) is, and it is a level rather than an edge.
+        // Losing the mover clears it, as a level.
         assert!(autorun_cancelled(false, false, false, true));
     }
 }
@@ -1648,9 +829,6 @@ mod move_mode_tests {
     use crate::creature_anim::move_flags as f;
     use benilla_protocol::MoveMode;
 
-    /// Every ack'd mode round-trips: granted through [`MoveModes::set`], out as its own
-    /// `MOVEMENTFLAGS` bit, and revoked again. The bit values are the ones vmangos reads back out of
-    /// our acks, so a mismatch is silent on our side and wrong on the server's.
     #[test]
     fn each_granted_mode_rides_the_wire_word_as_its_own_bit() {
         for (mode, bit) in [
@@ -1677,9 +855,7 @@ mod move_mode_tests {
         }
     }
 
-    /// **Levitate grants three modes at once** (spell 1706 = feather fall + hover + water walk), so
-    /// the word has to carry all three together — the case that proves this is one system and not
-    /// four independent booleans.
+    /// Levitate (spell 1706) grants feather fall, hover and water walk at once.
     #[test]
     fn levitate_carries_its_three_modes_at_once() {
         let mut modes = MoveModes::default();
@@ -1690,15 +866,10 @@ mod move_mode_tests {
             modes.wire_flags(),
             f::SAFE_FALL | f::HOVER | f::WATER_WALKING
         );
-        // …and dropping one leaves the other two standing.
         modes.set(MoveMode::Hover, false);
         assert_eq!(modes.wire_flags(), f::SAFE_FALL | f::WATER_WALKING);
     }
 
-    /// The server-authored merge owns the four unhandshaked bits and **must not touch root**. Root
-    /// is inside the reference's `0x75a0_7dff` mask, so this is our deliberate divergence, not the
-    /// mask's doing — and the failure it prevents is concrete: a bare pose clearing root locally
-    /// while the server still holds us rooted streams moving bits into `CHEAT_TYPE_ROOT_MOVE`.
     #[test]
     fn the_wire_merge_never_unroots_us() {
         let mut modes = MoveModes {
@@ -1709,29 +880,24 @@ mod move_mode_tests {
         assert!(modes.rooted, "only the ack'd opcode may unroot");
         assert!(!modes.hover && !modes.feather_fall && !modes.water_walking && !modes.levitating);
 
-        // The other four do follow the wire, in both directions — this is how `.cheat fly` arrives.
+        // The other four follow the wire both ways, which is how `.cheat fly` arrives.
         modes.merge_from_wire(f::SAFE_FALL | f::HOVER | f::WATER_WALKING | f::LEVITATING);
         assert!(modes.hover && modes.feather_fall && modes.water_walking && modes.levitating);
         assert!(modes.rooted, "still ours alone");
     }
 
-    /// **Feather fall is a terminal-velocity substitution and nothing more** (`0x7c5d20`): gravity
-    /// is untouched, so the drop *accelerates normally* and only then rides the lower cap. Pinning
-    /// the shape, not just the constant — an implementation that scaled gravity instead would give
-    /// a fall that starts wrong, and would pass a constants-only test.
+    /// Feather fall swaps the terminal velocity and leaves gravity alone (`0x7c5d20`).
     #[test]
     fn feather_fall_caps_the_descent_without_softening_gravity() {
         let dt = 1.0 / 60.0;
         let step = |v: f32, terminal: f32| (v - GRAVITY * dt).max(-terminal);
 
-        // One frame from rest is identical with and without the aura — gravity is the same.
         assert_eq!(
             step(0.0, FEATHER_TERMINAL_VELOCITY),
             step(0.0, TERMINAL_VELOCITY),
             "the first frame of a slow fall is an ordinary fall"
         );
 
-        // Held long enough, the two settle at their own caps.
         let settle = |terminal: f32| {
             let mut v = 0.0;
             for _ in 0..600 {
@@ -1745,8 +911,7 @@ mod move_mode_tests {
         );
         assert_eq!(settle(TERMINAL_VELOCITY), -TERMINAL_VELOCITY);
 
-        // And the cap is reached in well under half a second, which is why Slow Fall reads as a
-        // drift rather than a fall: v = g·t ⇒ t = 7.0/19.291105 ≈ 0.363 s.
+        // The cap is reached at t = 7.0 / 19.291105 ≈ 0.363 s.
         let mut v = 0.0f32;
         let mut frames = 0;
         while v > -FEATHER_TERMINAL_VELOCITY {
@@ -1760,8 +925,6 @@ mod move_mode_tests {
         );
     }
 
-    /// The two mover constants are the reference's, not round numbers we liked. A drift here is
-    /// invisible in play and wrong everywhere.
     #[test]
     fn the_mode_constants_are_the_verified_ones() {
         assert_eq!(FEATHER_TERMINAL_VELOCITY, 7.0); // [0x87d898]
@@ -1769,27 +932,15 @@ mod move_mode_tests {
         assert_eq!(TERMINAL_VELOCITY, 60.148_003); // [0x87d894]
     }
 
-    /// Feather fall must be the SLOWER cap — the whole point of the aura. A *compile-time* assert,
-    /// because both sides are constants: swapped, they would otherwise only show up in play.
+    /// Feather fall is the slower cap.
     const _: () = assert!(FEATHER_TERMINAL_VELOCITY < TERMINAL_VELOCITY);
 
-    /// **A root and a stun are different states, and the difference is the pivot** (decision 0872).
-    /// This is the distinction the first pass got wrong — B179 was filed under the movement-mode
-    /// family, and it is not a member of it: root is a `MOVEMENTFLAGS` bit that leaves turning live
-    /// by the input tick's *authored* allow-list, while the freeze is `UNIT_FIELD_FLAGS` bit
-    /// `0x40000` gating the turn emitter. vmangos's `HandleModStun` grants both at once, which is
-    /// the only reason they look like one thing.
-    ///
-    /// The bit values are what the gate reads, so a transcription slip here silently un-freezes
-    /// every stun; `UNIT_FLAG_STUNNED` is checked against vmangos `UnitDefines.h` and against the
-    /// reference's own `shr eax, 0x12` (bit 18 → `1 << 18` = `0x40000`).
+    /// The stun is `UNIT_FIELD_FLAGS` bit 18 (vmangos `UnitDefines.h:563`, the reference's
+    /// `shr eax, 0x12`), not a movement flag.
     #[test]
     fn a_stun_is_not_a_root() {
         assert_eq!(crate::player::UNIT_FLAG_STUNNED, 1 << 18);
         assert_eq!(crate::player::UNIT_FLAG_STUNNED, 0x0004_0000);
-        // It is a UNIT_FIELD_FLAGS bit, not a MOVEMENTFLAGS one — they are different words, and the
-        // whole confusion was reading the freeze as a movement flag. Nothing in the mode family may
-        // collide with it.
         for mode in [
             MoveMode::Root,
             MoveMode::WaterWalk,
@@ -1802,15 +953,12 @@ mod move_mode_tests {
                 "{mode:?} is a MOVEMENTFLAGS bit; the stun gate is a descriptor bit"
             );
         }
-        // …and a root, alone, is not a stun: granting it touches no unit flag at all.
+        // A root alone is only the movement bit.
         let mut modes = MoveModes::default();
         modes.set(MoveMode::Root, true);
         assert_eq!(modes.wire_flags(), crate::creature_anim::move_flags::ROOT);
     }
 
-    /// The hover clearance is reached by a **rate-limited climb**, not a snap — the reference's
-    /// second writer. Pins the rate and, more importantly, that the rise takes real time: a body a
-    /// full yard low needs ~0.143 s, which is the difference between a float and a pop.
     #[test]
     fn hover_climbs_to_its_clearance_rather_than_popping() {
         assert_eq!(HOVER_CLIMB_RATE, 7.0); // [0x87d898], via 0x7c61b0
@@ -1831,10 +979,8 @@ mod move_mode_tests {
         );
     }
 
-    /// **A hover grant owes exactly one jump, and two states eat it** (decision 1620, B322) — the
-    /// `Jump(force = 0)` at `0x61a630`, refused by `0x7c625c test ah, 0x30` for ROOT and FALLING and
-    /// by nothing else. In particular NOT by hover itself: `0x7c6236`'s `force == 0` skip is the
-    /// whole point of the leg, and the body being launched is hovering by construction.
+    /// `Jump(0)` at `0x61a630` is refused by ROOT and FALLING (`0x7c625c`), never by hover
+    /// (`0x7c6236`).
     #[test]
     fn a_hover_grant_owes_one_jump_and_only_root_or_falling_eats_it() {
         let granted = || Player {
@@ -1872,18 +1018,7 @@ mod move_mode_tests {
         assert!(!ungranted.take_wire_jump(), "no opcode, no jump");
     }
 
-    /// **Death is both a root and a stun, and it is the only state that is both** (decision 1753)
-    /// — the truth table of the reference's two movement-input predicates, whose shared
-    /// precondition `0x5144e0` is what makes a corpse unturnable.
-    ///
-    /// The last two assertions are the bug this test exists for: benilla only ever modelled the
-    /// server's root on death, and a pure root leaves the pivot live *on purpose*, so a dead body
-    /// could be spun with the turn keys or a right-drag. The predicate that stops it must not need
-    /// the root, the stun, or the server's cooperation.
-    /// **A seated body is not re-faced by the mouse** (decision 2025): `0x5145e0`'s last conjunct
-    /// is `GetStandState() == 0`, so sitting, a chair (client 2 and the server's 4/5/6) and sleep
-    /// all refuse the camera→body hand-off — while the keyboard turn (`may_turn`) is untouched,
-    /// because that path stands you up instead of being refused.
+    /// Stand states 1-6: sitting, the chairs (the client's 2, the server's 4, 5 and 6) and sleep.
     #[test]
     fn a_seated_body_refuses_the_mouse_turn_and_keeps_the_keyboard_one() {
         let m = MoverInput {
@@ -1959,8 +1094,7 @@ mod move_mode_tests {
         );
     }
 
-    /// **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.
+    /// The teardown leg (`0x5146d6`).
     #[test]
     fn only_both_predicates_down_tears_the_follow_down() {
         assert!(
@@ -1985,16 +1119,7 @@ mod move_mode_tests {
         );
     }
 
-    /// **Far sight freezes your own body — and never a possessed one** (conjunct 5 of
-    /// `0x5144e0`). While your view is out on a far-sight object you may neither walk nor turn:
-    /// the term sits in the *shared* precondition, so it takes both predicates exactly the way
-    /// death does.
-    ///
-    /// The second half is the one worth a test of its own. Mind Control rides the same
-    /// `PLAYER_FARSIGHT` field the camera does, so during a possession the latch is engaged — and
-    /// the reference reads it only after `0x514537`'s active-player test on the **mover** has
-    /// already passed. Model the latch without that test and the victim freezes solid, which is the
-    /// one body the whole spell exists to walk around.
+    /// `0x5144e0`'s far-sight term, read only when the mover is the active player (`0x514537`).
     #[test]
     fn far_sight_freezes_your_own_body_but_never_a_possessed_one() {
         let driving = |driving_own_body, far_sight_engaged| {
@@ -2035,12 +1160,8 @@ mod move_mode_tests {
         );
     }
 
-    /// **The two incapacitate suppressions take exactly their own bits** (decision 0880) — the
-    /// difference between a pure root and a stun, which is the whole distinction B179 was drawing,
-    /// expressed on the one word that drives both the animation and the wire.
     #[test]
     fn the_incapacitate_suppressions_take_exactly_their_own_bits() {
-        // Every reported motion a body can hold at once, plus every mode a grant can have riding.
         let keys = f::FORWARD | f::STRAFE_LEFT | f::TURN_LEFT;
         let modes = f::ROOT | f::SWIMMING | f::SAFE_FALL | f::HOVER | f::WATER_WALKING;
 
@@ -2060,15 +1181,14 @@ mod move_mode_tests {
             f::FORWARD | f::STRAFE_LEFT,
             "the two are keyed on different state: the stun bit alone takes only the pivot"
         );
-        // A stun is both at once (vmangos `HandleModStun` = SetFlag(STUNNED) + SetRooted(true)).
+        // A stun is both: vmangos's `HandleAuraModStun` sets `UNIT_FLAG_STUNNED` and roots
+        // (`SpellAuras.cpp:3523`, `:3542`).
         let blocked = incapacitated_flags(keys | modes, true, true);
         assert_eq!(
             blocked, modes,
             "Ice Block leaves NO reported motion — which is what starves the anim resolver"
         );
-        // …and the modes must survive it, or the next server-authored echo clears them under us
-        // (decision 0726's failure mode). ROOT above all: dropping it unroots us locally against a
-        // server that still has us rooted.
+        // The modes ride on, or the server's next echo clears them.
         assert_eq!(blocked & f::ROOT, f::ROOT, "the root bit itself rides on");
         assert_eq!(
             blocked & f::SWIMMING,
diff --git a/crates/benilla-app/src/player/step_probe.rs b/crates/benilla-app/src/player/step_probe.rs
index 37998d1c..2bcadd6c 100644
--- a/crates/benilla-app/src/player/step_probe.rs
+++ b/crates/benilla-app/src/player/step_probe.rs
@@ -1,33 +1,10 @@
-//! **The step-up probe** — the instrument that answers "why won't it climb *this* kerb?".
-//!
-//! The symptom is always the same from outside the window: you walk into something small, the
-//! avatar keeps running on the spot, and nothing in the ordinary trace says why — the atomic
-//! step-up ([`super::mover::step_up`]) declined, and one of six different reasons is the truth.
-//! Reasoning cannot pick between them (0209's whole history is sessions that tried), and neither
-//! can a screenshot, so this measures instead:
-//!
-//! 1. **The blocked frame is detected, not hunted.** A grounded walk frame whose achieved
-//!    horizontal displacement is a fraction of what the input asked for *is* the report. No
-//!    keybind to remember, no guessing which of the director's frames were the bad ones.
-//! 2. **The surface profile ahead is measured** with one-sided down rays at a ladder of forward
-//!    offsets: how tall the thing actually is, whether it has a walkable top at all, and — the
-//!    reason the rays are one-sided like the mover's own probes — whether that top is even
-//!    *visible* to a downward sweep under the 0970 facing law.
-//! 3. **The maneuver is re-run at a ladder of advances.** The live step-up advances by this
-//!    frame's own travel (0209), which is 12 cm at 60 fps and 3 cm at 240 — while the capsule
-//!    radius is [`super::CAPSULE_RADIUS`]. If a rung further out commits where the live one did
-//!    not, the advance is the defect; if *every* rung says `NO-FLOOR`, the geometry is; if every
-//!    rung says `STEEP-FLOOR`, the walkable gate is. One line, one verdict.
-//! 4. **The candidate faces are dumped** ([`benilla_world::collision::WorldCollision::faces_near_body`]), with the
-//!    facing gate's own answer per face, when the trace asks for them.
-//!
-//! Output goes two places: the `stup` tag of `WOW_MOVE_TRACE` (the record we read afterwards) and
-//! [`latest`], a small ring the debug panel renders live — so the director can *see* the probe
-//! fire at the spot they meant, which is what makes a capture worth reading (method §6).
-//!
-//! Cost: nothing at all on a frame that moves. On a blocked one it is rate-limited to
-//! [`REPORT_HZ`] reports a second, each a handful of shape casts and rays — so leaning on a wall
-//! forever cannot turn into a frame-rate story of its own.
+//! The step-up probe: when [`super::mover::step_up`] declines and a grounded walk frame achieves a
+//! fraction of the asked distance, it reports the wall ahead, the surface profile from one-sided
+//! down rays, the maneuver re-run at a ladder of advances and, traced, the candidate faces. A rung
+//! committing beyond the live one blames the advance; `NO-FLOOR` on every rung, the geometry;
+//! `STEEP` on every rung, the walkable gate. Output goes to the `stup` trace tag and to
+//! [`latest`], which the debug panel shows live, so a run shows the probe fired at the intended
+//! spot (`docs/METHOD.md`, loop step 5).
 
 use avian3d::prelude::*;
 use bevy::prelude::*;
@@ -36,34 +13,28 @@ use std::sync::Mutex;
 use super::mover::{step_up, StepVerdict};
 use super::{CAPSULE_HEIGHT, CAPSULE_RADIUS, SKIN_WIDTH, STEP_UP_HEIGHT};
 
-/// A walk frame counts as blocked when it achieved less than this share of the horizontal distance
-/// the input asked for. A square push into a wall achieves ~0; a legitimate slide along one at 45°
-/// still achieves ~70%, and a walkable-slope ride achieves 100% by construction (decision 0220) —
-/// so the band below this is "went nowhere", not "was deflected".
+/// A walk frame is blocked below this share of the asked horizontal distance: a push into a wall
+/// achieves about 0, a 45° slide along one about 70%.
 const BLOCKED_SHARE: f32 = 0.35;
 
-/// Reports per second while blocked. Enough to catch a bump-and-retry, cheap enough to lean on.
+/// Reports per second while blocked.
 const REPORT_HZ: f32 = 5.0;
 
-/// Forward offsets the surface profile is sampled at (yd). The last two are past anything the
-/// maneuver could reach — they say what the geometry *is*, which is how a "there is no top surface
-/// here" reads differently from "the top is 0.9 yd away".
+/// Forward offsets of the surface profile in yd; the last two lie past the maneuver's reach.
 const PROFILE: [f32; 8] = [0.0, 0.1, 0.2, 0.35, 0.5, 0.7, 1.0, 1.4];
 
-/// Advances the maneuver is re-run at (yd). The live rung — this frame's own travel — is prepended
-/// at report time, so the table always opens with what actually happened.
+/// Advances the maneuver is re-run at in yd, after the live rung (this frame's own travel).
 const LADDER: [f32; 6] = [0.1, 0.2, CAPSULE_RADIUS, 0.5, 0.8, 1.2];
 
 /// How many candidate faces the geometry dump prints, nearest first.
 const FACE_DUMP: usize = 24;
 
-/// The probe's own state: the rate limiter, and the last report for the panel to render.
+/// The rate limiter and the last report, for the panel.
 struct Probe {
     /// App-elapsed seconds of the last report; `f32::MIN` before the first.
     last: f32,
-    /// The most recent report, one string per line — what [`latest`] hands the debug panel.
     report: Vec<String>,
-    /// App-elapsed seconds the report was taken, so the panel can grey out a stale one.
+    /// App-elapsed seconds the report was taken; the panel greys out a stale one.
     at: f32,
 }
 
@@ -73,7 +44,7 @@ static PROBE: Mutex<Probe> = Mutex::new(Probe {
     at: f32::MIN,
 });
 
-/// The last blocked report (lines) and the app-elapsed time it was taken — the debug panel's read.
+/// The last blocked report's lines and the app-elapsed time it was taken, for the debug panel.
 pub(crate) fn latest() -> (Vec<String>, f32) {
     PROBE
         .lock()
@@ -81,11 +52,8 @@ pub(crate) fn latest() -> (Vec<String>, f32) {
         .unwrap_or_default()
 }
 
-/// Watch one **local** grounded walk frame, and report it if the body went nowhere.
-///
-/// `from`/`to` are the capsule centre either side of [`super::mover::grounded_step`] — the walk
-/// resolve alone, before the hover climb and the water-walk clamp, both of which move the body for
-/// reasons that have nothing to do with a kerb.
+/// Reports one local grounded walk frame if the body went nowhere. `from`/`to` are the capsule
+/// centre around [`super::mover::grounded_step`] alone, before the hover and water-walk moves.
 pub(super) fn watch(
     world: &benilla_world::collision::WorldCollision<'_, '_>,
     capsule: &Collider,
@@ -95,21 +63,13 @@ pub(super) fn watch(
     dt: f32,
     now: f32,
 ) {
-    // **Nobody is reading this in a player build** (decision 1179). Unlike its neighbour
-    // `move_trace`, which gates on `trace::enabled()` in its first line, this ran unconditionally:
-    // every blocked walk frame — routine play, walking into a wall — paid a body shape-cast, eight
-    // down-rays and seven full re-runs of `step_up`, up to 5×/s, to fill a `static` whose only
-    // reader is the debug panel. 1174 filed this file as residue, "weight, not behaviour"; that was
-    // wrong, and this is the correction. (Narrowing it further in a DEV build — to "the panel is
-    // open or the trace is on" — is a live question the panel's readout has an opinion about, and
-    // is deliberately not done here.)
+    // Dev builds only: the debug panel is the result's reader.
     if !crate::run_mode::dev_affordances() {
         return;
     }
     let speed = horiz_vel.length();
     let wanted = speed * dt;
-    // Below a millimetre of intent there is no "blocked" to speak of — standing still, or a frame
-    // so short that every ratio is noise.
+    // Under a millimetre of intent every ratio is noise.
     if wanted < 1.0e-3 {
         return;
     }
@@ -130,10 +90,7 @@ pub(super) fn watch(
     let feet_y = from.y - CAPSULE_HEIGHT * 0.5;
     let cast = |c: Vec3, disp: Vec3| world.cast_body(capsule, c, disp, SKIN_WIDTH);
 
-    // The spot is stamped in **WoW** coordinates as well as Bevy's: every other probe, every `.go
-    // xyz`, and the director's own `/gps` speak that frame, so a blocked report is walkable-back-to
-    // without anyone converting by hand. (Bevy's are what the rest of this report's geometry is in,
-    // so both are on the line.)
+    // WoW coordinates, as `.go xyz` takes them, and Bevy's, as the rest of the report uses.
     let feet_wow = benilla_assets::coords::bevy_to_wow(Vec3::new(from.x, feet_y, from.z));
     let mut lines = Vec::with_capacity(5);
     lines.push(format!(
@@ -151,8 +108,7 @@ pub(super) fn watch(
         d.y,
     ));
 
-    // What we are pressed against — a look-ahead a full radius deep, so the face is found even
-    // when this frame's own travel is a centimetre and the live maneuver never saw it.
+    // A full radius ahead, so the face is found even when this frame's travel is tiny.
     let wall = cast(from, dir_h * CAPSULE_RADIUS);
     lines.push(match &wall {
         None => format!("  wall  none within {CAPSULE_RADIUS:.2} yd ahead"),
@@ -170,10 +126,8 @@ pub(super) fn watch(
         ),
     });
 
-    // The surface profile ahead: one-sided down rays from above the capsule, reported as height
-    // above the feet. `miss` on a rung with solid geometry under it is the facing law rejecting a
-    // top face — the reading no shape cast can give, because a sweep that finds nothing and a
-    // sweep that finds a backface are the same `None`.
+    // One-sided down rays, as height above the feet: `miss` over solid geometry is the facing law
+    // rejecting a top face, which a shape cast cannot tell from empty space.
     let eye = from + Vec3::Y * STEP_UP_HEIGHT;
     let ray_len = STEP_UP_HEIGHT + CAPSULE_HEIGHT * 0.5 + 1.0;
     let profile: Vec<String> = PROFILE
@@ -191,14 +145,12 @@ pub(super) fn watch(
         .collect();
     lines.push(format!("  ahead {}", profile.join(" ")));
 
-    // The ladder: the same maneuver, at advances the live one never tries. The live rung first.
+    // The same maneuver at advances the live one never tries, the live rung first.
     let rungs: Vec<String> = std::iter::once(wanted)
         .chain(LADDER)
         .map(|adv| {
             let v = step_up(&cast, from, dir_h, adv.max(wanted), adv, STEP_UP_HEIGHT).verdict;
-            // `fwd` — how far the elevated sweep ACTUALLY got — is on every rung, because without
-            // it a failing far rung is two different stories: "we advanced that far and the floor
-            // there is steep" and "something at head height stopped us short of it".
+            // `fwd`, the raised sweep's reach, tells a steep floor from a stop at head height.
             let tag = match v {
                 StepVerdict::NoFace => "no-face".to_string(),
                 StepVerdict::NoHeadroom => "NO-HEADROOM".to_string(),
@@ -212,8 +164,7 @@ pub(super) fn watch(
         .collect();
     lines.push(format!("  ladder {}", rungs.join(" | ")));
 
-    // The faces themselves, when the trace asks. Kept off the panel and off an untraced run: it is
-    // two dozen lines, and it is the answer only when the three readings above disagree.
+    // The faces, traced runs only: two dozen lines, needed when the readings above disagree.
     let mut faces = Vec::new();
     if benilla_assets::trace::enabled_for("stup") {
         let at = from + dir_h * CAPSULE_RADIUS;
diff --git a/crates/benilla-app/src/player/swim.rs b/crates/benilla-app/src/player/swim.rs
index 1b77fa6a..195a0234 100644
--- a/crates/benilla-app/src/player/swim.rs
+++ b/crates/benilla-app/src/player/swim.rs
@@ -1,48 +1,14 @@
-//! Player **swim mode** — the water-movement regime the ground mover ([`super::mover`]) can't express:
-//! when the water gets deep enough the avatar leaves the floor, floats, and swims in 3D along its
-//! pitched facing, instead of walking the lakebed. Setting [`Player::swimming`] here is what lights
-//! 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).
+//! Swim mode: deep enough, the avatar leaves the floor and swims in 3D along its pitched facing.
+//! The reference's decision `0x6030c0` latches `MOVEFLAG_SWIMMING` (`0x00200000`) on the depth
+//! over the feet against 0.75 × the unit's collision height, with a 1/36-yd hysteresis; there is
+//! no wade flag (`0x40000000` is HOVER).
 //!
-//! 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** (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** — 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 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`],
-//! `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
-//! value, discarding the residual (see [`update_swimming`]).
-//!
-//! **Space maps to the ref's Jump routing, at any depth, one hop per PRESS** (decisions
-//! 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
-//! 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).
+//! The floating resolver bypasses gravity: an idle swimmer's depth is frozen, the vertical comes
+//! only from the pitched stroke, and the one constraint is a top cap with the feet at
+//! `surface - 0.75·h` (`0x632ba0`), satisfied again when the surface falls ([`settle_to_rest`]) and
+//! never pulling a deeper swimmer up. A rise into the cap turns level at full speed
+//! ([`cap_redirect`]). The way out through the top is the swim jump ([`breach_step`], `0x7c6230`);
+//! the way to rise is aiming up and swimming forward (`0x7c6f70`).
 
 use avian3d::prelude::*;
 use bevy::prelude::*;
@@ -53,123 +19,59 @@ use super::mover::Outcome;
 use super::{Player, CAPSULE_HEIGHT, GRAVITY, GROUND_COS, GROUND_PROBE, SKIN_WIDTH};
 use benilla_assets::coords::bevy_to_wow;
 
-/// Swim travel speed (yd/s) — vanilla's default `MOVE_SWIM` (0.66× run). A real server-seeded speed
-/// (the 4th `SpeedInfo` field, already parsed for remote swimmers in [`benilla_protocol`]); the local
-/// avatar has no per-unit speed plumbing yet, so this stands in as the vanilla default. Independent of
-/// `$WOW_MOVE_SPEED` (that overrides run), so overriding run leaves swim at its own rate.
+/// Swim speed (yd/s), the stock `MOVE_SWIM` (vmangos `Unit.cpp:71`): the fallback until the
+/// server's speeds stream in, and under the `$WOW_MOVE_SPEED` run override.
 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)` (`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`].
+/// Backward swim speed (yd/s), the stock `MOVE_SWIM_BACK` (vmangos `Unit.cpp:72`), with the same
+/// fallback role as [`SWIM_SPEED`].
 pub(super) const SWIM_BACK_SPEED: f32 = 2.5;
 
-/// Swim-jump take-off speed (yd/s) — **VERIFIED** `0x7c6230`'s swim seed `0xc1118c48 = −9.096748`
-/// (the client stores fall velocity down-positive; up for us), vs the land jump's 7.955547 — a
-/// swim jump launches ~14% harder, enough to breach and hop onto a low bank.
+/// Swim-jump take-off speed (yd/s): `0x7c6230`'s swim seed `0xc1118c48` (-9.096748, down-positive),
+/// about 14% over the land jump's 7.955547.
 const SWIM_JUMP_SPEED: f32 = 9.096_748;
 
-/// The fraction of the unit's collision height the water must cover to start swimming — **VERIFIED**
-/// `0.75` (`0x8012cc`, the compare at `0x6030c0`). Applied to the feet-referenced depth.
+/// The share of the unit's collision height the water must cover to swim (`0x8012cc`, compared
+/// at `0x6030c0`).
 const SWIM_DEPTH_FRAC: f32 = 0.75;
-/// The enter/leave hysteresis band (yd) — **VERIFIED** `1/36` (`0x7ff9d0`): enter compares depth against
-/// `0.75·h`, leave against `0.75·h − 1/36`, so between them the swim state holds (`0x603100`/`0x6031c0`).
+/// The enter/leave band (yd, `0x7ff9d0`): enter above `0.75·h`, leave below `0.75·h - 1/36`,
+/// hold between (`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**.
-/// `0x6030c0` tests them on **both** legs of its decision, with **opposite sense**:
-///
-/// ```text
-/// ENTER (after depth > 0.75·R):
-/// 60310b mov ecx,[esi+0x110]   ; the unit descriptor block base — writer 0x5fad25
-/// 603111 mov eax,[ecx+0xa0]    ;   `add ebx,0x18` ⇒ &values[OBJECT_END=6], so +0xa0 = index 46
-/// 603117 test ah,ah   ; js  60312c    ; bit 15 SET → permit entry
-/// 60311b shr ecx,3    ; test cl,1 ; jne 60312c   ; bit  3 SET → permit
-/// 603125 shr eax,0xb  ; test al,1 ; je  60314a   ; ALL clear → skip TryStartSwim
-///
-/// EXIT (0x6031b4, after !inLiquid and depth < 0.75·R − 1/36 have both passed):
-/// 6031d6 test ah,ah   ; js  6031fa    ; bit 15 SET → RETURN, stay swimming
-/// 6031df test cl,1    ; jne 6031fa    ; bit  3 SET → stay
-/// 6031e9 test al,1    ; jne 6031fa    ; bit 11 SET → stay
-/// 6031eb ... call 0x60dff0            ; ALL clear → StopSwim ANYWAY, at any depth
-/// ```
-///
-/// 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; corrected in 1572.)
-///
-/// What each bit is:
-///
-/// - `0x8` **PLAYER_CONTROLLED** (bit 3) — every body a player can steer: players (set at creation,
-///   vmangos `Player.cpp:462`), pets, totems, guardians, companions, charms. Named by the *client*,
-///   not just the server: the `UnitPlayerControlled` binding pair.
-/// - `0x800` **PET_IN_COMBAT** (bit 11) — likewise client-named, by the `PET_ATTACK_START/STOP`
-///   event firing.
-/// - `0x8000` **USE_SWIM_ANIMATION** (bit 15) — applied on spawn from
-///   `creature_template.static_flags1 & CREATURE_STATIC_FLAG_CAN_SWIM`. **956 of 10912** rows carry
-///   it. The client gives this bit no other meaning whatever: a whole-image census finds exactly
-///   three readers (`0x5fb922`, `0x603111`, `0x6031d0`), all of them this predicate — so vmangos's
-///   name for it (*"Without it units walk on the sea floor instead of swimming"*, and at its
-///   pathing site *"Giant type creatures walk underwater"*) describes the server's intent, and the
-///   client's three reads are the whole of its effect.
-///
-/// **The local avatar does not consult this**, and that is a verified no-op rather than an
-/// omission: bit 3 is set on every body a player can be [`crate::net::Embodied`] in — its own
-/// character, a charmed creature, a possessed one. It bites on the creature marker
-/// (`crate::net::motion::spline::mark_swimming_creatures`), which is where benilla derives the swim
-/// state the wire never carries for a creature.
+/// The `UNIT_FIELD_FLAGS` bits that let a unit swim: `PLAYER_CONTROLLED` (0x8, set on every
+/// player, vmangos `Player.cpp:462`), `PET_IN_COMBAT` (0x800) and `USE_SWIM_ANIMATION` (0x8000,
+/// from the creature's `CAN_SWIM`). `0x6030c0` tests them on both legs: with none set a unit
+/// cannot enter and is stopped at any depth (`0x6031b4`, then `0x60dff0`). The client's only reads
+/// of 0x8000 are this predicate (`0x5fb922`, `0x603111`, `0x6031d0`). Every body a player can be
+/// [`crate::net::Embodied`] in has 0x8, so only the creature marker
+/// (`crate::net::motion::spline::mark_swimming_creatures`) needs this.
 const SWIM_UNIT_FLAGS: u32 = 0x8 | 0x800 | 0x8000;
 
-/// May this unit be locally SWIMMING at all? — [`SWIM_UNIT_FLAGS`]'s one spelling. False blocks
-/// entry **and** forces an exit at any depth; see the constant for the two byte sites.
+/// Whether a unit may swim at all ([`SWIM_UNIT_FLAGS`]): false blocks entry and forces an exit.
 pub(crate) fn may_swim(unit_flags: u32) -> bool {
     unit_flags & SWIM_UNIT_FLAGS != 0
 }
 
-/// Submersion depth (yd, water surface above the feet) to **start** swimming — VERIFIED `0.75·h`
-/// from the feet, where `h` is **the unit's own collision height**
-/// ([`crate::entities::CollisionHeight`]): water covering ~three-quarters of its collision box,
-/// chest/neck deep. ≈1.52 yd for a human male, ≈0.86 for a gnome female, ≈1.83 for a night elf male.
-///
-/// It was `0.75 × CAPSULE_HEIGHT` — one constant for every race — until decision 0645. The
-/// *fraction* was right all along; the height it multiplied was a human's, so a gnome's rest line
-/// sat below her own head and she could never surface (B76).
-///
-/// This is also the **wade ceiling**: wading is the implicit in-liquid-but-not-swimming state
-/// (there is no wade movement flag — `0x40000000` is HOVER), so "deepest water you can still wade"
-/// and "shallowest water you swim in" are one number. The consumers with no `Player` of their own —
-/// the creature swim marker and the footstep splash slot — call it through `crate::player`, rather
-/// than keeping the second spelling `liquid::WADE_MAX` was.
+/// The depth over the feet (yd) past which a unit swims: 0.75 × its own collision height
+/// ([`crate::entities::CollisionHeight`]), about 1.52 yd for a human male and 0.86 for a gnome
+/// female. Also the wade ceiling: wading is being in liquid without swimming.
 pub(crate) fn swim_enter_depth(h: f32) -> f32 {
     SWIM_DEPTH_FRAC * h
 }
-/// 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` (`0x6030f2` subtracts `[0x7ff9d0]` from `0.75·h`) —
-/// so it is subtracted, never scaled.
+/// The depth (yd) below which swimming stops, `0.75·h - 1/36`: the band is absolute, never scaled
+/// by `h` (`0x6030f2` subtracts `[0x7ff9d0]`).
 pub(super) fn swim_exit_depth(h: f32) -> f32 {
     swim_enter_depth(h) - SWIM_HYSTERESIS
 }
 
-/// The hard **top-cap line** (yd below the surface) a rising swimmer stops at — feet at
-/// `surface − 0.75·h`, i.e. ~three-quarters submerged, head out. VERIFIED: the floating resolver's
-/// collision top-cap plane at `surface − 0.75·collisionHeight` (`0x632ba0` ×0.75, the open-bottom
-/// k-DOP's one top plane). The same `0.75·h` as the enter threshold, so a capped swimmer sits above
-/// the leave threshold and can't flicker out of the mode.
+/// The depth (yd) of the top cap a rising swimmer's feet stop at, the floating resolver's top
+/// plane (`0x632ba0`). It equals the enter depth, so a capped swimmer never drops out of the latch.
 fn rest_cap(h: f32) -> f32 {
     swim_enter_depth(h)
 }
 
-/// The **Bevy-Y liquid surface** at the avatar's feet, if any liquid covers that XY — the shared
-/// swim/buoyancy query. The world answers in WoW Z; WoW Z maps straight to Bevy Y, so the
-/// surface height above the feet is the same delta in either space and we lift the feet's Bevy Y by it.
-///
-/// Asks for **any** liquid, not the water-only wrapper: **you swim in lava and slime too** —
-/// Blackrock's magma and Undercity's sludge are surfaces you enter, not ones you fall through
-/// (decision 0634). The subject is the player, so which ROOM's liquid answers is its own live
-/// interior claim (decision 0696).
+/// The Bevy-Y surface of any liquid over the feet: magma and slime are swum in like water. The
+/// subject is the player, so its own interior claim picks which room's liquid answers.
 pub(super) fn surface_over_feet(world: &WorldPoint, feet: Vec3) -> Option<f32> {
     let wow = bevy_to_wow(feet);
     world
@@ -177,31 +79,14 @@ pub(super) fn surface_over_feet(world: &WorldPoint, feet: Vec3) -> Option<f32> {
         .map(|hit| feet.y + (hit.surface_z - wow[2]))
 }
 
-/// Update [`Player::swimming`] from the water surface over the feet, with the verified enter/leave
-/// hysteresis (`0x6030c0`) — returns the new state. `None` surface = not in liquid = not swimming (the
-/// 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** — `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
-/// floating resolver freezes the depth — the residual velocity is discarded (`0x7c6e50`→`0x7c6290`
-/// clears FALLING, `+0xa0` left dormant), which our swim arm mirrors (`swim_step` zeroes `vel_y`,
-/// the controller clears the arc). `now` is `Time::elapsed_secs`, for the airborne clock.
-///
-/// The latch deliberately does NOT touch [`Player::settling`]: the settle release is the terrain
-/// streamer's, keyed on the destination's residency in every mover mode alike (decision 0737 —
-/// this latch used to release it as a special case, because the old release was a ground probe
-/// only the walk mover ran).
+/// Latches [`Player::swimming`] as `0x6030c0` does and returns it: enter on a strict
+/// `depth > 0.75·h`, leave on `depth < 0.75·h - 1/36` or no liquid at all. Entry also waits out a
+/// rising launch until its upward speed halves (`0x7c5de0`, about 0.236 s for a swim jump), so the
+/// hop re-latches still rising and its residual velocity is dropped (`0x7c6e50` → `0x7c6290`).
+/// `now` is `Time::elapsed_secs`. Never touches [`Player::settling`], the terrain streamer's.
 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`): 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
-    // very next frame.
+    // LEVITATING skips the whole decision (`0x6030d2` test ah,4, to `0x6031fa`): it is GM flight,
+    // whose SWIMMING the dry ground would otherwise clear the next frame.
     if player.modes.levitating {
         return player.swimming;
     }
@@ -226,38 +111,19 @@ pub(super) fn update_swimming(player: &mut Player, surface_y: Option<f32>, now:
     player.swimming
 }
 
-/// **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`]: 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
-/// out of a river nose-down, and without this the aim you left the water with would still be
-/// pointing past −37° when your feet found the surface, and the water would not hold you.
-///
-/// **The breach jump deliberately does not come here.** `CMovement::Jump 0x7c6230` clears SWIMMING
-/// through `0x7c61f0` (`and eax,0xfbdfffff` — `0x200000` and `0x4000000` together, plus `0x2000`
-/// FALLING), which never touches `+0x20`; only the depth path routes through `0x7c6e80`. So a
-/// dolphin-hop keeps its aim and a swim-out levels — and that difference is in the bytes, not a
-/// convenience.
+/// A depth-driven stop zeroes the mover pitch, which water walking reads on land: StopSwim
+/// `0x7c6e80` (via `0x6031eb` → `0x60dff0` → `0x61a070`) is the pitch's only zeroing writer. A
+/// breach keeps its aim, as `CMovement::Jump` (`0x7c6230`) clears SWIMMING through `0x7c61f0`.
 fn stop_pitch(player: &mut Player, was: bool) {
     if was && !player.swimming {
         player.mover_pitch = 0.0;
     }
 }
 
-/// 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
-/// depth-gated interlude). Horizontal
-/// momentum freezes at takeoff like every jump (`0x7c61f0` never rewrites it): the last swim
-/// frame's travel carries the leap. Like the land jump's takeoff frame there is no gravity tick
-/// here — the walk mover integrates gravity from the next frame — so the arc snapshot (and the
-/// wire jump tail) carries the exact seed. The caller has already cleared [`Player::swimming`];
-/// the walk/fall machinery owns the arc from here.
+/// The take-off frame of a jump while swimming (`0x7c6230`), at any depth: [`SWIM_JUMP_SPEED`],
+/// then FALLING. The last swim frame's travel carries the leap, frozen as in every jump
+/// (`0x7c61f0` never rewrites it), and there is no gravity tick this frame, so the jump tail
+/// carries the exact seed. The caller has already cleared [`Player::swimming`].
 pub(super) fn breach_step(
     player: &mut Player,
     time: &Time,
@@ -265,12 +131,9 @@ pub(super) fn breach_step(
     capsule: &Collider,
 ) -> Outcome {
     player.vel_y = SWIM_JUMP_SPEED;
-    // The breach is a take-off like any other, so it records its launch speed for the arc
-    // bookkeeping to snapshot (decision 1740). Without this the jump tail would send `zspeed = 0`
-    // for every water exit and observers would replay the breach as a step-off rather than a hop.
+    // For the arc bookkeeping, or the jump tail sends `zspeed = 0` and observers see a step-off.
     player.launch_vz = SWIM_JUMP_SPEED;
-    // Leaving the water starts a fresh arc, and it starts it with the swim keys still down — the
-    // nibble seeds from them exactly as a ledge step-off does.
+    // The fresh arc's direction nibble seeds from the swim keys, as a ledge step-off's does.
     player.arc_dirs_set = player.horiz_vel.length_squared() > 0.0;
     player.knock_arc = false;
     let half_h = Vec3::Y * (CAPSULE_HEIGHT * 0.5);
@@ -293,29 +156,20 @@ pub(super) fn breach_step(
     }
 }
 
-/// The outcome of one swim step — read by the controller for the wire/animation flags.
+/// One swim step's result, for the controller's flags and animation.
 pub(super) struct SwimOutcome {
-    /// Solid walkable floor is right under the feet (a shallow bottom). With the exit hysteresis this
-    /// is how a swim into the shallows resolves back onto the ground.
+    /// Walkable floor right under the feet: a shallow bottom.
     pub grounded: bool,
-    /// `Some` when the rest-line cap redirected the stroke (the surface-swim regime): the
-    /// *effective* travel pitch after the redirect — what the body pose and the wire pitch tail
-    /// present this frame (→0 pinned at the line). `None` when the cap didn't bite (free swim,
-    /// idle, descending). The raw camera aim stays in [`Player::mover_pitch`] untouched.
+    /// The travel pitch after a surface redirect, for the pose and the wire; `None` when the cap
+    /// did not bite. The raw aim stays in [`Player::mover_pitch`].
     pub surface_pitch: Option<f32>,
 }
 
-/// Cap a rising stroke at the rest line — and REDIRECT the capped speed level rather than bleed
-/// 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 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
-/// reaches the rest line this frame) and the remainder rotates into the level travel
-/// direction. Returns the velocity and, when the cap bit, the effective travel pitch
-/// (`atan2(up, level)`).
+/// Clamps a rising stroke's upward speed to `cap`, the rise that reaches the rest line this
+/// frame, and turns the rest level at the same speed; returns the velocity and, when the cap bit,
+/// the travel pitch. The 1.12 client is seen swimming level at full speed along the surface; its
+/// own-input resolver (`0x634640`) as read slides a steep aim along the cap at `cos(pitch)·speed`,
+/// near zero, so the mechanism behind the seen behaviour is untraced.
 fn cap_redirect(input_vel: Vec3, cap: f32) -> (Vec3, Option<f32>) {
     if input_vel.y <= 0.0 || input_vel.y <= cap {
         return (input_vel, None);
@@ -329,48 +183,25 @@ fn cap_redirect(input_vel: Vec3, cap: f32) -> (Vec3, Option<f32>) {
     )
 }
 
-/// How far the feet must sink to satisfy the rest-line constraint — the excess above
-/// `surface − 0.75·h`, or zero when already at or under it. Pure so the law is pinned without a
-/// physics world; the *sweep* that carries it out is [`swim_step`]'s, which is what leaves a rising
-/// lakebed free to hold the feet higher.
+/// How far the feet sit above the rest line: the sink that satisfies it, which [`swim_step`]
+/// sweeps so a lakebed can still hold the feet higher.
 fn settle_to_rest(feet_y: f32, surface_y: f32, h: f32) -> f32 {
     (feet_y - (surface_y - rest_cap(h))).max(0.0)
 }
 
-/// **Does the water own this mover's vertical this frame?** — the rest line [`swim_step`] enforces,
-/// or `None` for none at all.
-///
-/// `None` means exactly one thing: **GM flight** (decision 0726). `LEVITATING` is the reference's
-/// suppression of the water's authority over the mover (`0x6030d2`, the same bail
-/// [`update_swimming`] takes), and the swim regime with no liquid that owns it has nothing to
-/// constrain against — an ascent must be free, or you could dive but never climb.
-///
-/// A *momentary* sample miss in real water is deliberately **not** that case: it maps to
-/// `Some(own feet Y)`, a rest line at our own depth, so the avatar simply holds for the frame.
-/// Collapsing the two would make a chunk-seam glitch and GM flight indistinguishable.
-///
-/// This exists as one named function because the constraint has **two arms** — refuse the rise,
-/// satisfy the drop — and B128 was what happened when they read different sources: 0644 added the
-/// second arm after 0726 wrote the first, so flight was exempt from the cap and not from the settle
-/// (decision 0882).
+/// The surface [`swim_step`] caps the swimmer under, or `None` in GM flight: `LEVITATING` lifts
+/// the water's authority (`0x6030d2`, as in [`update_swimming`]), so an ascent is free. A
+/// momentary sample miss in real water is `Some(own feet Y)`, a hold for the frame. Both arms of
+/// the constraint, the rise cap and the settle, must read this one source.
 pub(super) fn rest_line(player: &Player, surface_y: Option<f32>) -> Option<f32> {
     (!player.modes.levitating).then(|| surface_y.unwrap_or(player.pos.y))
 }
 
-/// Advance the avatar one swim frame: the pitched travel velocity through the client's *floating*
-/// 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*
-/// the line settles back onto it ([`settle_to_rest`], decision 0644).
-///
-/// `input_vel` is the desired 3D velocity from the swim controls (the pitched travel basis +
-/// ascent); `surface_y` is the Bevy-Y waterline over the feet at the START of the frame (the rise
-/// cap is a limit on *this* frame's climb, so it belongs to the position we climb from), and
-/// `surface_at` resamples it at wherever the stroke actually lands (the settle has to satisfy the
-/// constraint where the swimmer ends up — on a river reading the entry waterline instead lags by a
-/// frame's descent, which on a steep enough surface is the whole hysteresis band). Writes
-/// `player.pos`/`vel_y`/`horiz_vel`.
+/// One swim frame through the floating resolver (`0x634640`): no gravity, the vertical only from
+/// `input_vel`, a slide against the lakebed and banks, the rise capped at the rest line
+/// ([`cap_redirect`]) and a stroke left above it settled back ([`settle_to_rest`]). `surface_y`
+/// is the waterline where the frame starts, which caps its climb; `surface_at` resamples it where
+/// the stroke lands, since on a steep river a frame's descent can be the whole hysteresis band.
 pub(super) fn swim_step(
     player: &mut Player,
     time: &Time,
@@ -384,21 +215,9 @@ pub(super) fn swim_step(
     let half_h = Vec3::Y * (CAPSULE_HEIGHT * 0.5);
     let center = player.pos + half_h;
 
-    // The one vertical constraint: never rise ABOVE the resting waterline — cap the *upward velocity*
-    // so the feet reach at most the rest line this frame, NOT the position after the slide. That
-    // distinction is load-bearing: a position clamp (the earlier bug) overrode terrain collision,
-    // shoving the feet down onto the rest line even where a shallow bottom held them higher — which
-    // clipped us into the floor AND pinned `depth` at ≥ rest, so `update_swimming` never saw water
-    // shallow enough to leave (you couldn't get out onto land, and Space-ascend fought a wall). A
-    // velocity cap leaves the bottom to collision: in the shallows the feet rest on the floor and
-    // `depth` drops below the leave threshold, so we walk out. dt-based so it can't overshoot the
-    // rest line and dip back under the exit depth (a flicker). No other vertical force exists here —
-    // no gravity, no surface-seek (the verified floating resolver).
-    // **No waterline, no rest line.** `None` is GM flight (decision 0726): the swim regime with no
-    // liquid under it at all, where the one vertical constraint below has nothing to constrain
-    // against and an ascent must be free. It is deliberately NOT the same as a *momentary* sample
-    // miss in real water — the caller keeps that case as `Some(own feet Y)`, which caps the rise at
-    // zero and holds for the frame.
+    // Cap the upward velocity, not the position after the slide: a position clamp overrides the
+    // lakebed's collision, so in the shallows the depth never drops below the leave threshold and
+    // the swimmer cannot walk out. `None` is GM flight, uncapped.
     let cap = match surface_y {
         Some(surface) if dt > 0.0 => {
             let rest_feet_y = surface - rest_cap(player.collision_height.0);
@@ -417,39 +236,12 @@ pub(super) fn swim_step(
         |_hit| MoveAndSlideHitResponse::Accept,
     );
     let mut c = out.position;
-    // **Satisfy the rest line, don't merely guard it.** The cap above only ever refuses to *rise*
-    // through the waterline; that is enough on a lake and wrong on everything else, because the
-    // common way a swimmer ends up above the line is the line coming down to meet them. With the
-    // vertical frozen (no gravity here — verified) a stroke down a river surface that falls ~10%
-    // (measured: Felwood's Felfire Hill channel drops 5.94 yd across 60) loses 0.47 yd/s of depth,
-    // and the whole enter/leave hysteresis band is 1/36 yd — so the latch left swim every ~0.05 s,
-    // the walk mover took over and fell a few centimetres, swim re-latched, forever: the avatar
-    // spent 47% of a downhill swim inside the FALL mover, flipping mode ~10×/s and alternating
-    // SWIMMING/FALLING on the wire (director-reported as bouncing off the surface; live-probe
-    // measured, decision 0644).
-    //
-    // The correction is a **swept** drop, not a position clamp: an earlier attempt clamped
-    // `pos.y` after the slide, which overrode terrain collision, shoved the feet onto the rest
-    // line even where a shallow bottom held them higher, and pinned `depth` at ≥ rest so the
-    // shore exit could never fire. Sweeping it leaves the bottom in charge — wading out of a
-    // lake, the bank holds the feet up, the depth falls under the leave threshold, and we walk
-    // out exactly as before — and unlike folding the sink into `input_vel` it cannot eat the
-    // horizontal stroke that climbs the bank in the first place.
-    //
-    // 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.
-    //
-    // …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
-    // the drop — and they must share one gate, because `None` here means exactly one thing: GM
-    // flight, the swim regime with no liquid that owns it (0726; a momentary sample miss is
-    // `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 the symptom
-    // exactly: from any height, and only when moving from land to water, the `input_vel != ZERO`
-    // gate right here.
+    // Satisfy the rest line, not only guard it: a swimmer mostly ends up above it by the surface
+    // falling to meet them, and a river falling a tenth of a yard per yard sheds the 1/36-yd band
+    // within a few frames, flapping the latch between swim and fall. The drop is swept, so a bank
+    // still holds the feet up. Only under a stroke, as the resolver's outer gate skips an idle
+    // mover (`0x634100` test [esi+0x40],0x200f), and only under the rest line the cap reads, or GM
+    // flight over a lake would drop onto the waterline.
     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);
@@ -462,8 +254,7 @@ pub(super) fn swim_step(
         }
     }
     player.pos = c - half_h;
-    // Swim owns its vertical directly; leave a clean zero so exiting into a fall starts from rest and
-    // horiz_vel drives the swim gait's playback rate like every other locomotion clip.
+    // Swim owns its vertical: a clean zero, so a fall out of the water starts from rest.
     player.vel_y = 0.0;
     player.horiz_vel = Vec3::new(vel.x, 0.0, vel.z);
 
@@ -475,21 +266,17 @@ pub(super) fn swim_step(
     }
 }
 
-/// What one swim frame produced: the mover outcome the controller's other arms also return, and
-/// the **presented** pitch — the raw aim, except leveled by the 0499 surface redirect when the
-/// rest-line cap bit (the body swims flat along the surface, not pitched against it; the wire tail
-/// streams the same value).
+/// One swim frame's mover outcome and its presented pitch, for the pose and the wire: the raw aim,
+/// or the level travel pitch after a surface redirect.
 pub(super) struct SwimFrame {
     pub outcome: Outcome,
     pub pitch: f32,
 }
 
-/// Drive one swimming frame: the drunk porpoise, the pitched travel basis, the directional speed
-/// select, the stroke rate, and [`swim_step`] itself.
-///
-/// `basis` is the **level** facing pair `(forward, right)`; `amounts` the netted `(fwd, side)`
-/// swim translation ([`translate_amounts`]); `wobble` this frame's drunk angle, already zeroed by
-/// the caller when it must not apply (sober, stunned, or not translating).
+/// One swimming frame: the drunk pitch wobble, the pitched travel basis, the directional speed,
+/// the stroke rate and [`swim_step`]. `basis` is the level `(forward, right)` pair, `amounts` the
+/// netted `(fwd, side)` translation ([`translate_amounts`]), and `wobble` the drunk angle, zero
+/// when it must not apply.
 pub(super) fn drive_step(
     player: &mut Player,
     time: &Time,
@@ -504,34 +291,23 @@ pub(super) fn drive_step(
     wobble: f32,
 ) -> SwimFrame {
     let (swim_fwd, swim_side) = amounts;
-    // The drunk porpoise (B210): while swimming and moving, the pitch increments by the
-    // wobble ×4.0 every frame (`0x60aabc–0x60ab0a`: flag `0x200000` → `pitch +
-    // wobble·[0x80306c]`, clamped, committed via the pitch pipeline `0x60de70`). Same
-    // wobble as the facing veer above, so the nose and the heading meander together.
-    // The clamp is the callee `0x60aba0`'s FIXED ±π/2 bounds (`0x808acc`/`0x80c5e4`),
-    // NOT the mouselook set's ±89° — the reference carries both (decision 1009 §C4).
+    // Drunk and swimming, the pitch wobbles too, by the facing veer's angle × 4.0 each frame
+    // (`0x60aabc`-`0x60ab0a`, `[0x80306c]`, committed through `0x60de70`), clamped to ±π/2
+    // (`0x60aba0`, `0x808acc`/`0x80c5e4`), not the mouselook's ±89°.
     if wobble != 0.0 {
         player.mover_pitch = (player.mover_pitch + wobble * super::drunk::SWIM_PITCH_WOBBLE_SCALE)
             .clamp(-std::f32::consts::FRAC_PI_2, std::f32::consts::FRAC_PI_2);
     }
     let mut pitch = player.mover_pitch;
-    // The travel basis (`0x7c5880`, the client's swim velocity direction): the FORWARD axis
-    // is the facing pitched by the swim pitch — `(cosP·horiz-fwd + sinP·up)` — so holding W
-    // with the nose down dives (and aimed up, climbs — the smooth ascend, like the
-    // ref's PitchUp+Forward); the STRAFE axis stays level. There is no vertical
-    // thruster and Space adds nothing here (the verified basis has no separate vertical
-    // input; Space's whole swim role is the jump-exit above).
+    // The travel basis (`0x7c5880`): forward is the facing pitched by the swim pitch, strafe stays
+    // level, and there is no vertical input; Space's one swim role is the jump.
     let (sp, cp) = player.mover_pitch.sin_cos();
     let fwd_axis = basis.0 * cp + Vec3::Y * sp;
     let v = fwd_axis * swim_fwd + basis.1 * swim_side;
     let dir3 = v.normalize_or_zero();
-    // 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 (`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`).
+    // The directional speed (`0x7c4c90`'s swim arm): backward takes `min(swimBack, swim)`,
+    // forward and strafe the swim speed.
     let (swim_speed, swim_back_speed) = match speeds {
         Some(s) if !move_speed.env_override => (s.swim, s.swim_back),
         _ => (SWIM_SPEED, SWIM_BACK_SPEED),
@@ -541,11 +317,8 @@ pub(super) fn drive_step(
     } else {
         swim_speed
     };
-    // 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.
-    // `0x5fe2f0` divides GetCurrentSpeed (flags + static speed
-    // fields only) by the clip's moveSpeed, the same path for local and observed units.
+    // The stroke rate's numerator is the flag speed whatever the pitch: `0x5fe2f0` divides
+    // `GetCurrentSpeed` by the clip's speed, for local and observed units alike.
     player.swim_stroke_speed = if dir3 == Vec3::ZERO { 0.0 } else { dir_speed };
     let out = swim_step(
         player,
@@ -556,11 +329,8 @@ pub(super) fn drive_step(
         rest_line,
         |feet| surface_over_feet(world, feet),
     );
-    // The surface redirect (decisions 0499+0505 — a NAMED DIVERGENCE, see
-    // [`cap_redirect`]): when the rise capped at the rest line, the stroke went
-    // level at full speed — present the *effective* pitch (body pose + wire tail
-    // follow the motion, →0 pinned at the line), while the raw aim stays in
-    // `player.mover_pitch` so a later nose-down dives instantly.
+    // After a surface redirect the pose and the wire show the travel pitch, while the raw aim
+    // stays in `mover_pitch` so a nose-down dives at once.
     if let Some(p) = out.surface_pitch {
         pitch = p;
     }
@@ -568,9 +338,8 @@ pub(super) fn drive_step(
         held: false,
         grounded: out.grounded,
         jumped: false,
-        // A knockback never resolves here: it clears SWIMMING at the take-off site above
-        // (the reference's `StartFalling 0x7c61f0` clears the bit outright rather than
-        // testing it), so a knocked swimmer is flown by the land mover.
+        // A knockback clears SWIMMING at take-off (`StartFalling`, `0x7c61f0`), so the land
+        // mover flies it.
         knocked: false,
         air_nudged: false,
         ground: None, // swimming detaches from any platform frame below
@@ -578,16 +347,14 @@ pub(super) fn drive_step(
     SwimFrame { outcome, pitch }
 }
 
-/// The swim translation amounts — read by [`drive_step`] AND the flag build, so the two can never
-/// disagree (decision 0056: the flags mirror the avatar's motion). W/S, strafe Q/E (+ mouselook
-/// A/D), and a root cuts both.
+/// The swim translation `(fwd, side)`, read by [`drive_step`] and the flag build alike so the two
+/// agree; under mouselook A/D strafe.
 pub(super) fn translate_amounts(
     axes: &super::input::MoveAxes,
     translate_gated: bool,
 ) -> (f32, f32) {
-    // The translate predicate being down (`0x514560`: a root, or **death** through the precondition
-    // it shares with the turn gate — decision 1753) kills swim translation like the walk `dir` does
-    // (decision 0308's regime — the water arm reads its own axes, so it needs its own cut).
+    // The translate predicate `0x514560` (a root, or death) cuts swim translation as it cuts the
+    // walk; the water reads its own axes, so it needs its own cut.
     if translate_gated {
         return (0.0, 0.0);
     }
@@ -614,10 +381,8 @@ pub(super) fn translate_amounts(
 mod tests {
     use super::*;
 
-    /// The shipped `CreatureModelData.collisionHeight × displayScale` for three real bodies —
-    /// the numbers `benilla_formats`' `collision_height_is_the_m2_collision_box` pins against the
-    /// client, restated here so these pure tests need no DBCs. Human male is the one the old
-    /// constant happened to match (2.031 vs 2.0278 — 2 mm apart, which is why B76 hid for so long).
+    /// `CreatureModelData.collisionHeight × displayScale` for three shipped bodies, as
+    /// `benilla_formats`' `collision_height_is_the_m2_collision_box` pins them.
     const HUMAN_MALE: f32 = 2.031;
     const GNOME_FEMALE: f32 = 1.150; // 1.000 column × 1.15 display scale
     const NIGHT_ELF_MALE: f32 = 2.438;
@@ -634,11 +399,6 @@ mod tests {
         }
     }
 
-    /// **StopSwim levels the mover pitch, the breach jump does not** — `0x7c6e80`'s zeroing of
-    /// `+0x20`, which only the depth-driven stop routes through (decision 1616, B322). It matters
-    /// because the pitch is land-live and water walking reads it: leave a river nose-down without
-    /// this and the aim you were swimming with is still past −37° when your feet reach the surface,
-    /// so the water refuses to hold you.
     #[test]
     fn leaving_the_water_by_depth_levels_the_pitch_and_a_breach_does_not() {
         let deep = swim_enter_depth(HUMAN_MALE) + 1.0;
@@ -646,41 +406,36 @@ mod tests {
         player.mover_pitch = -0.9;
         assert!(update_swimming(&mut player, Some(deep), 0.0), "must swim");
         assert_eq!(player.mover_pitch, -0.9, "swimming holds the aim");
-        // Still swimming inside the hysteresis band: nothing levels.
         let band = swim_exit_depth(HUMAN_MALE) + 0.001;
         assert!(update_swimming(&mut player, Some(band), 0.1));
         assert_eq!(player.mover_pitch, -0.9);
-        // Out through the bottom of the band — StopSwim, and the pitch goes with it.
+        // Out through the bottom of the band.
         assert!(!update_swimming(&mut player, Some(0.5), 0.2));
         assert_eq!(
             player.mover_pitch, 0.0,
             "`0x7c6e80` zeroes +0x20 on StopSwim"
         );
-        // Leaving the liquid entirely is the same stop (`inLiquid == 0`).
+        // No liquid at all is the same stop.
         player.mover_pitch = -0.9;
         assert!(update_swimming(&mut player, Some(deep), 1.0));
         assert!(!update_swimming(&mut player, None, 1.1));
         assert_eq!(player.mover_pitch, 0.0);
-        // The breach jump clears SWIMMING through `0x7c61f0`, which never touches `+0x20`: the
-        // caller drops the latch itself, so the next tick sees no transition and the aim survives.
+        // A breach clears the latch itself (`0x7c61f0`), so the next tick sees no stop.
         player.mover_pitch = -0.9;
         assert!(update_swimming(&mut player, Some(deep), 2.0));
-        player.swimming = false; // what the breach arm in `player::control` does
+        player.swimming = false; // as the controller's breach arm does
         breach_pitch_survives(&mut player, deep);
         assert_eq!(player.mover_pitch, -0.9, "a dolphin-hop keeps its aim");
     }
 
-    /// One tick of the latch after a breach has already cleared it — factored out only so the
-    /// assertion above reads as one line.
+    /// One latch tick after a breach has cleared it.
     fn breach_pitch_survives(player: &mut Player, depth: f32) {
         player.vel_y = 0.0;
         update_swimming(player, Some(depth), 2.1);
     }
 
-    /// The gate's three bits, named — `0x6030c0`'s `js` / `shr 3` / `shr 0xb` tests, which appear
-    /// **twice**: once permitting entry (`0x60310b`) and once preventing the stop (`0x6031ca`).
-    /// PET_IN_COMBAT is the one that reads like a typo and is not: the reference really does let a
-    /// pet's combat bit keep it swimming, and it is bit 11 of `UNIT_FIELD_FLAGS` in 1.12.1.
+    /// `PET_IN_COMBAT` is no typo: `0x6030c0` tests bit 11 on entry (`0x60310b`) and on the stop
+    /// (`0x6031ca`).
     #[test]
     fn the_swim_gate_is_those_three_unit_flags_and_no_others() {
         const PLAYER_CONTROLLED: u32 = 0x8;
@@ -694,25 +449,18 @@ mod tests {
             assert!(may_swim(bit), "any ONE of the three admits ({bit:#x})");
         }
         assert!(!may_swim(0), "no flags at all → walks the lakebed");
-        // Not vacuous: a unit carrying every OTHER unit flag still cannot enter. IN_COMBAT,
-        // SKINNABLE, PVP, NOT_SELECTABLE — none of them is a swim permit.
         assert!(!may_swim(!SWIM_UNIT_FLAGS));
     }
 
-    /// 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 (`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.
         for h in [HUMAN_MALE, GNOME_FEMALE, NIGHT_ELF_MALE] {
             assert!((swim_enter_depth(h) - swim_exit_depth(h) - 1.0 / 36.0).abs() < 1e-6);
-            // Enter is 0.75·collisionHeight from the feet.
             assert!((swim_enter_depth(h) - 0.75 * h).abs() < 1e-6);
         }
 
         let (enter, exit) = (swim_enter_depth(HUMAN_MALE), swim_exit_depth(HUMAN_MALE));
-        let mut p = player_at(0.0); // feet at y=0, so the surface height *is* the submersion depth
+        let mut p = player_at(0.0); // feet at 0, so the surface height is the depth
         let mid_band = (enter + exit) * 0.5;
         assert!(
             !update_swimming(&mut p, Some(enter), 0.0),
@@ -734,7 +482,6 @@ mod tests {
             !update_swimming(&mut p, Some(exit - 0.01), 0.0),
             "dropping below the leave threshold returns to walking"
         );
-        // Re-enter, then prove no-liquid stops it regardless of depth.
         assert!(update_swimming(&mut p, Some(enter + 0.5), 0.0));
         assert!(
             !update_swimming(&mut p, None, 0.0),
@@ -742,13 +489,9 @@ mod tests {
         );
     }
 
-    /// **GM flight is the suppression, not a lift** (decision 0726). `LEVITATING` bails the whole
-    /// water decision (`0x6030d2 test ah,4`), so the two things that would otherwise happen the very
-    /// next frame both stop happening: dry land cannot clear a server-granted swim (which is what
-    /// keeps you airborne), and deep water cannot grant one (the same bail, the other arm).
     #[test]
     fn levitating_bails_the_water_decision_in_both_directions() {
-        // The server just sent `.cheat fly on`: SWIMMING + LEVITATING, standing on dry ground.
+        // `.cheat fly on` sets SWIMMING and LEVITATING (`Player.cpp:4595`); on dry ground.
         let mut flying = player_at(0.0);
         flying.swimming = true;
         flying.modes.levitating = true;
@@ -761,7 +504,6 @@ mod tests {
             "nor may a surface far below the feet, which is what flying over a lake looks like"
         );
 
-        // The other arm, and it is the same instruction: water cannot latch swim while levitating.
         let mut dry = player_at(0.0);
         dry.modes.levitating = true;
         assert!(
@@ -769,7 +511,7 @@ mod tests {
             "the ENTER arm is skipped too — the bail is before the branch, not inside it"
         );
 
-        // And clearing the mode (`.cheat fly off` sends flags 0) hands the water its job back.
+        // `.cheat fly off` sends flags 0.
         flying.modes.levitating = false;
         assert!(
             !update_swimming(&mut flying, None, 0.0),
@@ -777,11 +519,6 @@ mod tests {
         );
     }
 
-    /// The latch never touches the settle hold (decision 0737): the release is the terrain
-    /// streamer's, keyed on residency in every mover mode alike. This pins the *absence* of the
-    /// old special case — a swim latch that cleared `settling` here would race the streamer's
-    /// judgement (the pre-0737 rule existed only because the old release was a walk-mover ground
-    /// probe a swimmer never reached; the Booty Bay underwater-login hang, 2026-07-18).
     #[test]
     fn the_latch_leaves_the_settle_hold_alone() {
         for (surface, name) in [
@@ -796,12 +533,6 @@ mod tests {
         }
     }
 
-    /// The verified fall re-entry gate (`0x7c5de0`): a fresh swim jump is not re-latched into swim
-    /// until its upward velocity has decayed to HALF the launch value (`t ≥ v₀/(2g)` ≈ 0.236 s) —
-    /// and the release happens *while still rising*, which is what tops the dolphin-hop at
-    /// ≈1.6 yd rather than the full ballistic apex. The leave arm is untouched: a swimmer's
-    /// vertical is owned by `swim_step` (which zeroes `vel_y`), so the gate can never hold
-    /// someone *in* the water.
     #[test]
     fn the_hop_relatches_at_half_launch_velocity() {
         let half_decay = SWIM_JUMP_SPEED / (2.0 * GRAVITY);
@@ -819,7 +550,6 @@ mod tests {
             update_swimming(&mut p, deep, half_decay + 1e-3),
             "velocity decayed to half — swim re-latches while STILL rising (the ~1.6 yd hop top)"
         );
-        // A plain fall into water (no upward velocity) enters regardless of the clock.
         let mut q = player_at(0.0);
         q.airborne_since = Some(0.0);
         q.jump_zspeed = SWIM_JUMP_SPEED;
@@ -830,39 +560,24 @@ mod tests {
         );
     }
 
-    /// The rest line is a **constraint**, not a one-way cap (decision 0644): a stroking swimmer
-    /// left above it settles back onto it, while one below it is never pulled up — the verified
-    /// floating resolver has no upward force but your own stroke, and no downward one at all.
     #[test]
     fn the_rest_line_is_satisfied_from_above_and_never_pulls_up() {
-        // The law is the same shape at every body height; run it at all three.
         for h in [HUMAN_MALE, GNOME_FEMALE, NIGHT_ELF_MALE] {
             let cap = rest_cap(h);
-            // Exactly on the line: nothing to do.
             assert_eq!(settle_to_rest(10.0 - cap, 10.0, h), 0.0);
-            // Below it — a dive, or a river swum upstream: no pull up at any depth.
             assert_eq!(settle_to_rest(10.0 - cap - 0.01, 10.0, h), 0.0);
             assert_eq!(settle_to_rest(10.0 - cap - 30.0, 10.0, h), 0.0);
-            // Above it, which on a river is the surface having come down to meet the feet: the
-            // sink is exactly the excess, so one satisfied frame lands on the line, not past it.
+            // Above it, as when a river's surface comes down to the feet: sink exactly the excess.
             let excess = 0.25;
             assert!((settle_to_rest(10.0 - cap + excess, 10.0, h) - excess).abs() < 1e-6);
         }
     }
 
-    /// **B128, pinned.** `.gm fly` over water yanked the avatar down onto the waterline instantly,
-    /// from any height (two reporters). Cause: the rest line's two arms read different sources —
-    /// [`rest_line`] exempted flight from the *cap*, while the *settle* re-read the liquid itself.
-    /// This pins the exemption at its single source, in both directions, so the two can't diverge
-    /// again: while levitating there is no line at all, and the moment the mode clears the water
-    /// has its authority back.
     #[test]
     fn gm_flight_hands_the_water_no_authority_over_the_vertical() {
         let lake_surface = 40.0;
 
-        // 300 yd above a lake, `.gm fly` on. This is the exact geometry of B128: liquid is over our
-        // XY (the query answers `Some`), and the drop the settle would compute is the whole
-        // altitude — through open air, so nothing stops the cast and one frame lands us in the lake.
+        // 300 yd above a lake in GM flight: the liquid query still answers `Some` under us.
         let mut flying = player_at(lake_surface + 300.0);
         flying.swimming = true;
         flying.modes.levitating = true;
@@ -871,19 +586,14 @@ mod tests {
             None,
             "no rest line while levitating — this is the gate BOTH arms take, not just the cap"
         );
-        // What the settle would have done had it reached its arithmetic: teleport us 300 yd down.
-        // Asserted so the fix is measured against the defect rather than merely asserted away.
         assert!(
             settle_to_rest(flying.pos.y, lake_surface, flying.collision_height.0) > 299.0,
             "the ungated settle's drop is the whole altitude — that was the yank"
         );
 
-        // Clear the mode (`.gm fly off` sends flags 0) and the water is back in charge immediately.
         flying.modes.levitating = false;
         assert_eq!(rest_line(&flying, Some(lake_surface)), Some(lake_surface));
 
-        // And the case flight must not be confused with: a *momentary* surface-query miss in real
-        // water is a rest line at our own feet — the avatar holds for the frame, it does not fly.
         let swimmer = player_at(lake_surface - 2.0);
         assert_eq!(
             rest_line(&swimmer, None),
@@ -892,15 +602,6 @@ mod tests {
         );
     }
 
-    /// **B76, pinned.** The bug the director reported: a gnome could not swim up to the surface,
-    /// her head stayed well under. The rest line is `0.75·h` below the waterline, so the head
-    /// clears it iff `0.75·h < h` — trivially true *for the unit's own h*, and false the moment
-    /// one body's h is used for another's. With the old constant a gnome female (1.15 yd tall)
-    /// was held 1.52 yd down: 0.37 yd of water **above her head**, no stroke able to reach it,
-    /// because the cap is a hard collision plane and the resolver has no upward force but the cap.
-    ///
-    /// Asserted as "every race floats with its head out", which is the property that actually
-    /// matters and which no single constant can satisfy for all of them.
     #[test]
     fn every_race_floats_with_its_head_out_of_the_water() {
         for (label, h) in [
@@ -913,13 +614,10 @@ mod tests {
                 submerged < h,
                 "{label}: rest line {submerged} is at or below the top of a {h}-yd body"
             );
-            // A quarter of the body clears the water — the verified 1−0.75.
             assert!(((h - submerged) / h - 0.25).abs() < 1e-6, "{label}");
         }
 
-        // And the shape of the defect itself, as the loop above would have run it pre-0645: the
-        // one constant applied to a gnome puts the rest line ABOVE her head, so `submerged < h`
-        // fails and she is held under with water to spare. This is what the fix removes.
+        // One shared height would put a gnome's rest line above her head.
         let pre_0645 = rest_cap(crate::player::DEFAULT_COLLISION_HEIGHT);
         assert!(
             pre_0645 > GNOME_FEMALE,
@@ -932,15 +630,8 @@ mod tests {
         );
     }
 
-    /// **The director's downhill-river jitter** (decision 0644), as the frame loop that produces
-    /// it. `SLOPE` is Felwood's Felfire Hill channel, measured off the shipped ADT and pinned by
-    /// `liquid::real_data::the_felfire_channel_falls_about_a_tenth_of_a_yard_per_yard`.
-    ///
-    /// The two halves are the two vertical laws over the same river. Frozen feet cannot hold the
-    /// latch for a tenth of a second — the surface descends through the whole 1/36-yd hysteresis
-    /// band almost at once, and every crossing hands the avatar to the fall mover and back
-    /// (live-probe measured at ~10 mode flips/s, 47% of the swim spent falling). Satisfying the
-    /// constraint instead pins the depth on the rest line for a run longer than any river.
+    /// `SLOPE` is Felwood's Felfire Hill channel, as benilla-world's
+    /// `liquid::real_data::the_felfire_channel_falls_about_a_tenth_of_a_yard_per_yard` measures it.
     #[test]
     fn a_descending_surface_does_not_flap_the_swim_latch() {
         const SLOPE: f32 = 0.099;
@@ -949,7 +640,7 @@ mod tests {
         let cap = rest_cap(H);
         let surface_after = |secs: f32| 100.0 - SLOPE * SWIM_SPEED * secs;
 
-        // (a) The pre-0644 law — the feet keep their Y while the water leaves them behind.
+        // Frozen feet: the water leaves them behind.
         let mut frozen = player_of_height(surface_after(0.0) - cap, H);
         frozen.swimming = true;
         let mut left_at = None;
@@ -966,8 +657,7 @@ mod tests {
             "the whole 1/36-yd band is spent in {left_at:.3}s of downhill swimming"
         );
 
-        // (b) The shipped law. The settle runs where `swim_step` runs it — after the stroke, on
-        // the surface at the position the stroke reached.
+        // Settled after each stroke, on the surface where the stroke landed, as `swim_step` does.
         let mut held = player_of_height(surface_after(0.0) - cap, H);
         held.swimming = true;
         for i in 0..600 {
@@ -986,21 +676,14 @@ mod tests {
         }
     }
 
-    /// The surface redirect (decision 0499): a pitched-up stroke reaching the rest line keeps its
-    /// SPEED and turns level — the ref's full-speed surface swimming — instead of sliding against
-    /// the cap at `cos(pitch)·speed ≈ 0` (the director's "invisible wall"). The presented pitch
-    /// levels with it; free/descending strokes pass through untouched.
     #[test]
     fn the_rest_line_redirects_the_stroke_level_at_full_speed() {
-        // Cap far away (deep): untouched, no presented-pitch override.
         let free = Vec3::new(0.1, 3.0, 0.2);
         assert_eq!(cap_redirect(free, 100.0), (free, None));
         assert_eq!(cap_redirect(free, f32::INFINITY), (free, None));
-        // Descending: the cap never touches a dive.
         let dive = Vec3::new(1.0, -2.0, 0.0);
         assert_eq!(cap_redirect(dive, 0.0), (dive, None));
 
-        // Pinned at the line (cap 0): a near-vertical stroke becomes a FULL-speed level stroke.
         let steep = Vec3::new(0.08, 4.72, 0.0); // ~89° aim, forward at swim speed
         let (vel, pitch) = cap_redirect(steep, 0.0);
         assert!((vel.length() - steep.length()).abs() < 1e-4, "speed kept");
@@ -1008,7 +691,7 @@ mod tests {
         assert!(vel.x > 4.7, "the whole speed went forward");
         assert_eq!(pitch, Some(0.0), "the presented pitch levels out");
 
-        // Approaching the line (partial cap): speed still preserved, pitch eases toward level.
+        // A partial cap, approaching the line.
         let (vel2, pitch2) = cap_redirect(steep, 2.0);
         assert!((vel2.length() - steep.length()).abs() < 1e-4);
         assert_eq!(vel2.y, 2.0);
diff --git a/crates/benilla-app/src/player/view_subject.rs b/crates/benilla-app/src/player/view_subject.rs
index 3aeae245..9a652c62 100644
--- a/crates/benilla-app/src/player/view_subject.rs
+++ b/crates/benilla-app/src/player/view_subject.rs
@@ -1,45 +1,20 @@
-//! **What the camera orbits** — the body, or a far-sight object standing somewhere else entirely.
+//! What the camera orbits: our body, or a far-sight subject elsewhere. Far sight moves only the
+//! eye, so the subject is published for the camera, not made a control branch like free-fly.
 //!
-//! Decision 0092 settled that this client has two answers to "where am I?": the **camera eye**
-//! (what it draws, culls and clicks) and the **active-player character** (what it is in and hears).
-//! Far sight adds no third answer — it moves the *eye*, and leaves the character exactly where it
-//! was. That is the whole of the feature, and it is why this is a published fact rather than a
-//! branch in the controller: Mind Vision must keep your body walking, your zone text, your
-//! minimap, your ambience and your movement stream all yours, while the picture comes from
-//! somewhere else. Free-fly ([`Player::detached`]) looks superficially similar and is the opposite
-//! shape — it swaps the *whole* control branch and parks the mover — so far sight must never be
-//! built as its peer.
-//!
-//! **The server names the object and nothing else announces it** (VERIFIED vmangos): the only
-//! signal is `PLAYER_FARSIGHT` (player field 712, a guid pair) arriving in a values block for our
-//! own object. Non-zero means look through it, zero means come home. Three details of how it
-//! arrives are load-bearing here:
-//!
-//! - **The set runs ~400 ms late** (`Player::ScheduleCameraUpdate` defers it by `BATCHING_INTERVAL`)
-//!   while the clear is immediate. So the object is always created, and its surroundings always
-//!   streamed, well before we are told to look through it — we never have to wait for the subject.
-//! - **The clear is broadcast to every client in range**, not just ours: it goes out through
-//!   `DirectSendPublicValueUpdate`, which bypasses the field's PRIVATE flag entirely. Reading only
-//!   our own [`SelfPlayer`] store is what keeps a neighbour cancelling Mind Vision from moving our
-//!   camera.
-//! - **`SMSG_CLEAR_FAR_SIGHT_IMMEDIATE` never arrives.** vmangos has zero send sites for it, so
-//!   there is nothing to handle and nothing to wait for; every teardown is the field going to zero.
-//!
-//! Mind Control rides the same field (the server sets it to the victim alongside the control
-//! handoff), so possession's camera half falls out of this for free and needs no arm of its own.
+//! The server's only signal is `PLAYER_FARSIGHT` (player field 712) on our own object: non-zero
+//! looks through that guid, zero comes home. vmangos defers the set by 400 ms
+//! (`Player::ScheduleCameraUpdate`, `Player.cpp:19136`), so the subject has streamed first, and
+//! sends the clear at once to every client in range (`DirectSendPublicValueUpdate`), so only our
+//! [`SelfPlayer`] store is read; it never sends `SMSG_CLEAR_FAR_SIGHT_IMMEDIATE`. Mind Control
+//! sets the same field (`SpellAuras.cpp:2975`).
 
 use bevy::prelude::*;
 
 use super::{head_height, CameraPivot};
 use crate::net::{ClientCommand, GuidIndex, NetCommands, ObjectStore, SelfPlayer};
 
-/// Where the camera should sit its rig this frame, when that is *not* our own body.
-///
-/// `None` — the overwhelmingly common case — means "the body", and the controller takes its
-/// normal path. This deliberately carries a resolved **pose** rather than an `Entity`: the
-/// controller cannot query an arbitrary unit's `Transform` (it already holds the self entity's
-/// mutably, and the two queries would conflict), and resolving here also lets one place answer
-/// "far sight is set but the object is not streamed" without the camera ever seeing a half-state.
+/// Where the camera rig sits this frame when it is not our body; `None` is the body. It carries a
+/// resolved pose because the controller, holding our own `Transform`, cannot query another's.
 #[derive(Resource, Default)]
 pub(crate) struct ViewSubject {
     pub(crate) remote: Option<RemoteView>,
@@ -48,48 +23,30 @@ pub(crate) struct ViewSubject {
 /// A far-sight subject's pose, in the two forms the camera rig asks for.
 #[derive(Clone, Copy)]
 pub(crate) struct RemoteView {
-    /// The subject itself. The rig never needs it — it has the resolved pose — but the systems
-    /// that read the **followed unit's own state** do: the reference's camera driver takes the
-    /// shake's body frame and both of its suspend gates off `[cam+0x88/0x8c]`, the followed unit,
-    /// never off `0x468550` (the active player). Under Mind Vision those are different objects.
-    /// Carrying the entity does not reopen the query conflict this resolver exists to avoid —
-    /// that constraint is the *controller's*, and the controller reads the pose.
+    /// For readers of the followed unit's state: the reference's camera shake reads the followed
+    /// unit (`[cam+0x88]`/`[cam+0x8c]`), never the active player (`0x468550`).
     pub(crate) entity: Entity,
-    /// The subject's feet, world space — what the rig orbits.
+    /// The subject's feet in world space, which the rig orbits.
     pub(crate) feet: Vec3,
-    /// Its framing pivot height above those feet (attachment-17 derived, scaled), the same
-    /// quantity [`head_height`] answers for our own avatar.
+    /// Its framing pivot height above the feet, as [`head_height`] gives it.
     pub(crate) pivot_height: f32,
 }
 
 impl RemoteView {
-    /// The origin the camera-collision boom sweeps *from*.
-    ///
-    /// For our own body the controller roots this at the capsule's top hemisphere centre, which it
-    /// can do because it owns the avatar's capsule constants. A far-sight subject has no capsule of
-    /// ours to read, so the framing pivot stands in — it is head-height by construction, which is
-    /// what the sweep wants.
-    ///
-    /// **Rooting the sweep at the subject rather than at our body is not a detail.** The boom is
-    /// cast from this point out to the seat; left at our own head it would be cast across the whole
-    /// world to a subject that may be hundreds of yards away, and jam against the first wall in
-    /// between — parking the camera at our feet with the view pointing at nothing.
+    /// The camera-collision boom's origin: the subject's framing pivot, standing in for the capsule
+    /// top our own body uses. Rooted at our body, the boom would sweep across the world to it.
     pub(crate) fn sweep_origin(&self) -> Vec3 {
         self.feet + Vec3::Y * self.pivot_height
     }
 }
 
-/// Resolve `PLAYER_FARSIGHT` on our own descriptor into a pose the rig can use.
-///
-/// Runs before the controller so the substitution is a plain read there. Deliberately silent about
-/// a far sight whose object we have not streamed: the camera stays on the body, which is the right
-/// picture while we wait, and the server's ordering makes the gap vanishingly rare.
+/// Resolves our `PLAYER_FARSIGHT` into a pose, before the controller runs; a subject not yet
+/// streamed leaves the camera on the body.
 pub(super) fn publish_view_subject(
     mut subject: ResMut<ViewSubject>,
     self_store: Query<&ObjectStore, With<SelfPlayer>>,
     index: Res<GuidIndex>,
-    // The subject's pose, its model-derived pivot, and its **raw** scale — the pivot height takes
-    // the raw `OBJECT_FIELD_SCALE_X`, not the eased render scale ([`head_height`]).
+    // The pivot height takes the raw `OBJECT_FIELD_SCALE_X`, not the eased render scale.
     poses: Query<(
         &Transform,
         Option<&CameraPivot>,
@@ -111,11 +68,9 @@ pub(super) fn publish_view_subject(
             pivot_height: head_height(pivot, net.map_or(1.0, |n| n.scale)),
         });
 
-    // The toggle vote, on the edge — the reference sends it from exactly two sites, `1` as the view
-    // attaches and `0` as it releases (`0x5ee290`). Keyed off the FIELD, not off whether we managed
-    // to resolve the object: the server is asking about the view it already chose, and answering
-    // "released" merely because the subject has not streamed yet would tear down its object stream
-    // around the very object we are waiting for.
+    // `CMSG_FAR_SIGHT` on the field's edge: 1 as the view attaches and 0 as it releases, the
+    // reference's two sites (`0x5ee290`). It follows the field, not the resolve: a release sent
+    // while the subject streams in would tear down the server's stream around it.
     if *engaged != anchor {
         if anchor.is_some() {
             let _ = net.0.send(ClientCommand::FarSight { engage: true });
@@ -130,11 +85,6 @@ pub(super) fn publish_view_subject(
 mod tests {
     use super::*;
 
-    /// The three states the resolver has to tell apart, and the two that must both read "body".
-    ///
-    /// The middle one is the case the ordering makes rare but not impossible — the field names an
-    /// object we have not streamed. Answering `None` there is what keeps the camera on the body
-    /// instead of at the world origin, which is what a naive `unwrap_or_default` would give.
     #[test]
     fn an_unset_or_unstreamed_far_sight_both_resolve_to_the_body() {
         let (tx, rx) = crossbeam_channel::unbounded();
@@ -143,7 +93,7 @@ mod tests {
             .init_resource::<GuidIndex>()
             .insert_resource(NetCommands(tx))
             .add_systems(Update, publish_view_subject);
-        // The toggle vote, drained as engage/release booleans.
+        // The `CMSG_FAR_SIGHT` votes, as engage booleans.
         let votes = |rx: &crossbeam_channel::Receiver<ClientCommand>| -> Vec<bool> {
             rx.try_iter()
                 .filter_map(|c| match c {
@@ -181,7 +131,7 @@ mod tests {
         );
         assert!(votes(&rx).is_empty(), "no field, no vote");
 
-        // Far sight set, but the object never streamed — still the body, not the origin.
+        // Far sight set, the object not streamed: still the body, not the origin.
         const FARSIGHT: u16 = 712;
         let set = |app: &mut App, lo: u32| {
             *app.world_mut().get_mut::<ObjectStore>(me).unwrap() =
@@ -227,7 +177,7 @@ mod tests {
              world and stops at the first wall in between"
         );
 
-        // Cleared back to zero: home, by the same path a real teardown takes.
+        // Cleared to zero: home.
         set(&mut app, 0);
         app.update();
         assert!(
diff --git a/crates/benilla-app/src/player/walk.rs b/crates/benilla-app/src/player/walk.rs
index fe2a6e58..4d9e1d6d 100644
--- a/crates/benilla-app/src/player/walk.rs
+++ b/crates/benilla-app/src/player/walk.rs
@@ -1,60 +1,31 @@
-//! **The walk/run gait toggle** — the `TOGGLERUN` keybind, the reference's `ToggleRun 0x513d50`.
+//! The walk/run toggle: the `TOGGLERUN` binding, the reference's `ToggleRun` `0x513d50`, latching
+//! [`Player::walking`]. The flag word carries it as `MOVEFLAG_WALK_MODE` `0x100`, the speed cascade
+//! ([`crate::net::current_speed`]) makes it `min(MOVE_WALK, MOVE_RUN)`, and the animation picks
+//! Walk(4) over Run(5) on speed alone, `speed > 2 × walkSpeed` (`0x5fd224`).
 //!
-//! One latched bit ([`Player::walking`]) and one refusal chain, kept here beside its concern like
-//! [`super::posture`] and [`super::gait`]. Everything downstream is already built and reads the
-//! bit through the ordinary paths: the flag word ([`super::flags`]) carries `MOVEFLAG_WALK_MODE`
-//! `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 (`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
-//! locomotion nibble (`0x61a99d test al,0xf`), so a toggle pressed while standing still would
-//! never reach the server through it — which is exactly why `ToggleRun` enqueues its own move
-//! event (`0x513dd2 call 0x60e080` → `0x60e060` → `0x617de0` → `0x617570`, kind `0xf` when the
-//! walk bit is currently clear and `0xe` when it is set). Ours goes out of the flag differ in
-//! [`super::movement_net`], which is likewise not nibble-gated.
+//! The reference's move-state broadcaster sends only with a locomotion bit set (`0x61a99d test
+//! al,0xf`), so `ToggleRun` enqueues its own move event (`0x513dd2 call 0x60e080` → `0x60e060` →
+//! `0x617de0` → `0x617570`), kind `0xf` when the walk bit is clear and `0xe` when set. Ours goes
+//! out of the flag differ in [`super::movement_net`], which does not wait on locomotion either.
 
 use super::{BodyQuery, Player};
 
-/// Does the reference **refuse** this `ToggleRun` press? The handler's own guard chain, in its byte
-/// order (`0x513d50`–`0x513dcf`; every gate falls to the same silent `0x513dd7` — no packet, no
-/// local flip, no message, exactly like the sheath and stand-state chains):
+/// Whether the reference refuses this `ToggleRun` press. Its guard chain (`0x513d50`–`0x513dcf`)
+/// falls silently to `0x513dd7`, with no packet, flip or message, on:
 ///
-/// ```text
-/// 513d8e  mov esi,[descr+0x40] ; test esi,esi ; jle    →  health <= 0
-/// 513d95  mov ecx,[unit+0x118] ; mov ecx,[ecx+0xa4]    →  the active spline object, if any
-/// 513da5  test byte [ecx+0x18],0x4 ; je                →  …its FINALIZE latch must be SET
-/// 513dab  (health, re-read and re-tested)
-/// 513dbe  mov ebx,[cmov+0x40] ; test bh,0x12 ; jne     →  MOVEMENTFLAGS & 0x1200
-/// 513dc6  cmp byte [descr+0x210],0x7 ; je              →  UNIT_FIELD_BYTES_1.standState == DEAD
-/// ```
-///
-/// `descr+0x40` is `UNIT_FIELD_HEALTH`, not a guess: benilla already byte-pinned it at the
-/// reference's own death predicate `0x605f90` ("really dead — `[descr+0x40] <= 0`", see
-/// `ObjectFields::unit_reads_dead`), and `descr+0x210` is `UNIT_FIELD_BYTES_1` (field index
-/// `0x84`), whose byte 0 is the stand state. So the death leg is health-or-standstate — and
-/// notably **not** the feign-death dynflag that `unit_reads_dead` also carries, which is why this
-/// takes the narrower [`ObjectFields::unit_is_dead`]. A **ghost** is health 1 and stand state 0,
-/// 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** (`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`
-/// (`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.
+/// - health ≤ 0 (`[descr+0x40]`, as the death predicate `0x605f90` reads it), with no feign-death
+///   flag, hence `ObjectFields::unit_is_dead`; a ghost (health 1) may toggle;
+/// - a live spline, its flags' bit `0x4` clear (set by `0x619de0`, inferred to mark the spline
+///   done); ours is [`Player::server_riding`] (taxi, charge, knockback);
+/// - `MOVEMENTFLAGS & 0x1200`: `0x1000` is `MOVEFLAG_ROOT` (`SetRoot` `0x7c7340`), and no 1.12
+///   code sets `0x200` (every wire route masks it out), so root is the whole test;
+/// - stand state 7 (`UNIT_FIELD_BYTES_1` byte 0, `[descr+0x210]`), not tested here.
 pub(super) fn toggle_refused(dead: bool, rooted: bool, on_spline: bool) -> bool {
     dead || rooted || on_spline
 }
 
-/// Run this frame's `TOGGLERUN` press. Nothing else in the client writes [`Player::walking`]
-/// except the server-authored merge in [`super::wire_in`].
+/// Runs this frame's `TOGGLERUN` press; the only other writer of [`Player::walking`] is the
+/// server-authored merge in [`super::wire_in`].
 pub(super) fn update(
     player: &mut Player,
     body: &BodyQuery,
@@ -69,14 +40,11 @@ pub(super) fn update(
         .and_then(|(.., store, _, _, _, _, _)| store.map(|s| s.0.unit_is_dead()))
         .unwrap_or(false);
     let (rooted, on_spline) = (player.modes.rooted, player.server_riding);
-    // A read-and-invert of the *current* bit, which is the reference's shape exactly: `0x60e080`
-    // fetches `[unit+0x9e8] & 0x100` and `0x617de0` picks the event kind off it (`neg`/`sbb`/
-    // `add 0xf` → `0xe` when set, `0xf` when clear). There is no "walk on"/"walk off" command in
-    // 1.12 — one binding, one flip.
+    // A flip of the current bit, as `0x60e080` reads `[unit+0x9e8] & 0x100` for `0x617de0`'s
+    // event kind; 1.12 has no walk-on or walk-off command.
     let want = !player.walking;
     if toggle_refused(dead, rooted, on_spline) {
-        // Silent, like the reference — no packet, no flip, no message. The trace tag is the only
-        // way a refusal is readable from a live run ([`super::move_trace::gait`]).
+        // Silent, as in the reference; the trace tag ([`super::move_trace::gait`]) records it.
         super::move_trace::gait("REFUSED", want, dead, rooted, on_spline);
         return;
     }
@@ -88,8 +56,6 @@ pub(super) fn update(
 mod tests {
     use super::toggle_refused;
 
-    /// The three refusals we can actually state, and the control that says the predicate is a
-    /// refusal chain rather than a blanket "not while anything is unusual".
     #[test]
     fn the_guard_chain_refuses_exactly_the_three_states_it_names() {
         assert!(!toggle_refused(false, false, false), "standing: granted");
diff --git a/crates/benilla-app/src/player/wire_in.rs b/crates/benilla-app/src/player/wire_in.rs
index 8d4c7678..548d148e 100644
--- a/crates/benilla-app/src/player/wire_in.rs
+++ b/crates/benilla-app/src/player/wire_in.rs
@@ -1,18 +1,9 @@
-//! Server-authored movement edges applied to our mover — the inbound mirror of
-//! [`super::movement_net`] (which streams our own movement out). One entry point,
-//! [`apply_server_moves`], called by [`super::control`] before input integrates: cross-map
-//! worldports (incl. the riding-through-the-seam branch, decision 0455), same-map teleports, the
-//! **granted movement-mode family** (root, water-walk, feather-fall, hover — decisions 0308/0866,
-//! applied to [`super::state::MoveModes`] and acked here), the one-shot take-control edge, the
-//! pre-control forced-speed acks (the controlled branch answers those through the movement
-//! stream's own per-frame payload instead — the returned list), and the **bare self-addressed
-//! move** ([`apply_self_move`], decision 0725).
-//!
-//! All but the last carry a **mandatory ack**, which is what made the last one easy to miss: a
-//! `MSG_MOVE_*` the server addresses to our own guid arrives with no handshake and owes no answer,
-//! and this client used to discard it. The real client applies it — its inbound move path has no
-//! mover-guid gate at all — and sends nothing back; the next ordinary heartbeat carries the
-//! server's own pose home, which is what makes `.go forward` stick.
+//! Server-authored movement edges applied to our mover, the inbound mirror of
+//! [`super::movement_net`]. [`apply_server_moves`], called by [`super::control`] before input,
+//! takes control changes, worldports, near teleports, the granted modes (root, water walk, feather
+//! fall, hover, into [`super::state::MoveModes`]), knockbacks, the take-control edge, pre-control
+//! speed acks and the bare self-addressed move ([`apply_self_move`]): a `MSG_MOVE_*` naming our
+//! own guid, which owes no ack and which the reference applies.
 
 use benilla_protocol::MoveMode;
 use bevy::prelude::*;
@@ -30,51 +21,33 @@ use benilla_world::world_map::CurrentMap;
 use super::camera::FlyCam;
 use super::{movement_net, Player, SETTLE_TIMEOUT};
 
-/// What one `SMSG_CLIENT_CONTROL_UPDATE` means for us — the four cases its two fields make, named.
-///
-/// Worth a type because the packet is genuinely ambiguous read casually: it is a statement *about a
-/// unit*, not an assignment, and the naive reading ("the mover is now `mover`") silently inverts
-/// the mind-controlled victim — the case where the server names **us** to say we may no longer
-/// move. That victim is half of B211, so the inversion would have shipped as the bug it was meant
-/// to fix.
+/// What one `SMSG_CLIENT_CONTROL_UPDATE` means for us. It says whether a unit may move, not who the
+/// mover is: the server revokes a mind-controlled victim's control by naming the victim.
 #[derive(Debug, PartialEq, Eq)]
 enum ControlVerdict {
-    /// Somebody is driving our body. We stop moving it — nothing else will stop us.
+    /// Somebody else drives our body; we stop moving it.
     Revoked,
     /// Our own body is ours again.
     Restored,
     /// We were handed the reins of another unit, and owe it a mover claim.
     Granted(u64),
-    /// A unit we were driving was taken back, and owes a parting pose.
+    /// Another unit may not move: the one we drive (kept, frozen) or one already given back.
     Released(u64),
 }
 
-/// Give our own body back to the server on a **hand-over**: the stop, then the parting pose.
-///
-/// `CMSG_MOVE_NOT_ACTIVE_MOVER` (`0x2D1`) is **only ever about our own character**. The reference
-/// sends it from `SetActiveMover 0x6006e0` for the outgoing mover *when that mover was the local
-/// player* (`0x5fa6d0`), and vmangos agrees from the other side: `HandleMoveNotActiveMover` rejects
-/// any guid that is not the session's currently-confirmed mover, and rejects again if the guid names
-/// something other than the player while the player's mover still is it. There is no such packet for
-/// a creature we are handing back.
-///
-/// **And none for a body merely frozen, either** (decision 1281). Being feared, confused or
-/// mind-controlled is not a mover change: our own body is still the mover, and the server still
-/// expects us to answer for it. What this packet does server-side is clear `m_clientMoverGuid`, and
-/// that single field is the key to two doors — `HandleMoveSplineDone` refuses any acknowledgement
-/// whose unit is not the confirmed mover, while `MoveSplineInit::Launch` arms
-/// `HasPendingSplineDone` on every spline it starts for a player, and `HandleMovementOpcodes` drops
-/// **every** movement packet until that acknowledgement arrives. Sending it on a fear therefore
-/// locks the client out of its own body for good: the flee splines can no longer be acked, so the
-/// server keeps our position and orientation frozen at the moment of the fear long after it lifts,
-/// and every spell we cast answers "you are facing the wrong way" (director, 2026-08-13). Only a
-/// map change clears it (`Map::AddPlayerToMap`), which is why relogging appeared to fix it.
-///
-/// 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;
 
+/// Give our own body back on a hand-over: the stop, then `CMSG_MOVE_NOT_ACTIVE_MOVER` (`0x2D1`).
+/// That packet is only ever about our own character: the reference sends it from `SetActiveMover`
+/// (`0x6006e0`) for the local player only (`0x5fa6d0`), and vmangos rejects a guid that is not its
+/// confirmed mover, or another unit still being moved (`MovementHandler.cpp:891-908`).
+///
+/// Never on a fear, confuse or mind control, where our body stays the mover: the packet clears
+/// `m_clientMoverGuid` (`MovementHandler.cpp:913`), so vmangos refuses the ack each later spline
+/// arms (`MoveSplineInit.cpp:131-132`, `MovementHandler.cpp:804`) and drops our movement until a
+/// map change (`MovementHandler.cpp:295-296`, `Map.cpp:448`). Skipped while a server spline owns
+/// the body, as in the reference (`0x619d50`).
 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 };
@@ -91,8 +64,7 @@ fn yield_own_body(net_cmds: &NetCommands, player: &mut Player, self_guid: Option
     });
 }
 
-/// Classify a control update. `self_guid` is `None` only before login has named us, where nothing
-/// can be "about me" yet.
+/// `self_guid` is `None` before login names us, when no update can be about our body.
 fn control_verdict(mover: u64, allow_move: bool, self_guid: Option<u64>) -> ControlVerdict {
     match (self_guid == Some(mover), allow_move) {
         (true, false) => ControlVerdict::Revoked,
@@ -102,13 +74,10 @@ fn control_verdict(mover: u64, allow_move: bool, self_guid: Option<u64>) -> Cont
     }
 }
 
-/// Drain this frame's server-authored movement messages, apply them to the mover, and send each
-/// ack. Returns the frame's forced-speed changes: pre-control/detached they were acked here with
-/// the parked pose; controlled, the caller's movement stream acks them with its live payload.
-/// `self_pose` is the streamed self entity's current translation + facing yaw (the take-control
-/// snap target).
-// One system phase's full input set (the spawner precedent); the transports query type is
-// `control`'s own param shape passed through.
+/// Apply this frame's server-authored movement and send each ack. Returns the forced-speed changes
+/// for the movement stream to ack, except pre-control or detached, where they are acked here.
+/// `self_pose` is the streamed self entity's translation and yaw, the take-control target.
+// `control`'s own transports query, passed through.
 #[allow(clippy::type_complexity)]
 pub(super) fn apply_server_moves(
     time: &Time,
@@ -130,22 +99,12 @@ pub(super) fn apply_server_moves(
     >,
     self_pose: Option<(Vec3, f32)>,
 ) -> Vec<SpeedChangeMessage> {
-    // The control handoff (B211). Two questions, and they are NOT the same one: "is this about my
-    // own body?" and "may that unit move?". The server revokes by naming *us* with allowMove=0 —
-    // which is what a mind-controlled player receives about themselves — and grants by naming
-    // somebody else, so a single "the mover is now `mover`" reading gets the victim backwards.
-    //
-    // The claim reply is not optional. vmangos discards every `MSG_MOVE_*` for a mover it has not
-    // confirmed (`Player::GetConfirmedMover`), so a grant we never answer leaves the possessed unit
-    // frozen server-side while our client cheerfully walks it around locally.
+    // A grant must be claimed: vmangos drops every `MSG_MOVE_*` for an unconfirmed mover
+    // (`MovementHandler.cpp:291-293`, `Player.cpp:20257-20272`).
     for c in control_msgs.read() {
         match control_verdict(c.mover, c.allow_move, self_guid) {
-            // Somebody is driving our body. We stop driving it and say **nothing** — the mover has
-            // not changed hands, only the permission to move it, and the one packet that looks
-            // right here (`CMSG_MOVE_NOT_ACTIVE_MOVER`) is the one that strands us: see
-            // [`yield_own_body`]. The flush below is the whole of our answer, and it matters — we
-            // may have been mid-run when the fear landed, and the server would otherwise keep
-            // extrapolating that run for every observer.
+            // Park, which stops the server extrapolating a run, and say nothing else: the mover has
+            // not changed hands, and `CMSG_MOVE_NOT_ACTIVE_MOVER` would strand us.
             ControlVerdict::Revoked => {
                 player.control_lost = true;
                 movement_net::park_mover(&net_cmds.0, player);
@@ -154,39 +113,21 @@ pub(super) fn apply_server_moves(
                 player.control_lost = false;
                 player.foreign_mover = None;
                 player.reseat = true;
-                // Re-claim ourselves as the mover — the same claim login makes. After a possession
-                // it is mandatory: the server's `m_clientMoverGuid` still names the creature we
-                // were driving. After a plain fear it is a no-op re-assert, because nothing ever
-                // took our own claim away (see [`yield_own_body`]).
-                //
-                // And send **nothing else**. A parting stop for the creature we were driving looks
-                // right and is a teleport: by the time this packet is written the server has
-                // already pointed `m_mover` back at us while `m_clientMoverGuid` still names the
-                // creature, so `GetConfirmedMover` falls through its mismatch branch to *us* — and
-                // a stop carrying the creature's pose would relocate our own character to wherever
-                // the creature was standing. The creature's own stop is the server's to send; it
-                // owns that unit again.
+                // Re-claim ourselves, as login does (after a possession `m_clientMoverGuid` still
+                // names the creature), and send nothing else: `GetConfirmedMover` resolves the
+                // mismatch to us (`Player.cpp:20267-20269`), so a parting stop for the creature
+                // would move our own character to it.
                 super::move_trace::mover_claim("SET_ACTIVE_MOVER", c.mover);
                 let _ = net_cmds
                     .0
                     .send(ClientCommand::SetActiveMover { guid: c.mover });
             }
-            // Claim them, or the server drops everything we send for that unit. Recording the
-            // claim is what stops the controller streaming OUR body's pose under their guid —
-            // outbound moves carry none of their own, so that would teleport them onto us.
+            // Claim it; recording the claim stops our body's pose streaming under its guid.
             ControlVerdict::Granted(guid) => {
-                // Hand our own body over FIRST, while it is still the mover the server attributes
-                // to. One command channel, so this is genuinely ordered ahead of the claim — and
-                // it has to be, in both directions: vmangos rejects a
-                // `CMSG_MOVE_NOT_ACTIVE_MOVER` whose guid is not the mover it currently has
-                // confirmed, and a `MSG_MOVE_STOP` sent after the claim would carry our pose under
-                // the creature's guid.
-                // …but only if it still IS the mover the server attributes to us. A grant is not
-                // always a first grant: vmangos re-sends one every time a possessed creature stops
-                // fleeing (`Unit::UpdateControl` off the fear generator's `Finalize`), and by then
-                // our own body was handed over long ago. Yielding it twice sends a
-                // `CMSG_MOVE_NOT_ACTIVE_MOVER` naming a unit that is not the confirmed mover, which
-                // vmangos rejects with an error log every time the creature is feared.
+                // Yield our own body first, on the same channel, while it is still the confirmed
+                // mover, and only once: vmangos re-sends a grant each time a possessed creature
+                // stops fleeing (`FearMovementGenerator.cpp:155`, `Unit.cpp:11157`) and rejects a
+                // second yield (`MovementHandler.cpp:891-897`).
                 if player.foreign_mover.is_none() {
                     yield_own_body(net_cmds, player, self_guid);
                 }
@@ -196,19 +137,10 @@ pub(super) fn apply_server_moves(
                 super::move_trace::mover_claim("SET_ACTIVE_MOVER", guid);
                 let _ = net_cmds.0.send(ClientCommand::SetActiveMover { guid });
             }
-            // "That unit may not move" — about a unit that is not us. Genuinely ambiguous on the
-            // wire, because vmangos sends it from two places: the unpossess path (right after the
-            // `Restored` that already took us home) and, while a possession is still very much in
-            // force, whenever the possessed unit becomes feared or confused.
-            //
-            // The reference resolves both with one rule, and so do we: *is this the unit I am
-            // driving?* If it is, we are still holding it and merely forbidden to move it — the
-            // mover global goes to nobody, exactly as `0x5fa600` zeroes it when the named unit is
-            // the current one. If it is not, `Restored` already ran and there is nothing to do.
-            //
-            // Clearing `foreign_mover` here — the obvious reading — would send us back to driving
-            // our own body while the server still has `m_mover` pointed at the creature, so every
-            // step we took would be applied to the creature instead.
+            // vmangos sends this on unpossess, after `Restored`, and when the possessed unit is
+            // feared or confused (`Unit.cpp:11157`). As in the reference (`0x5fa600`), only the
+            // unit we drive matters: we keep it but may not move it. Clearing `foreign_mover`
+            // would walk our own body while the server applies our steps to the creature.
             ControlVerdict::Released(guid) => {
                 if player.foreign_mover == Some(guid) {
                     player.control_lost = true;
@@ -216,76 +148,55 @@ pub(super) fn apply_server_moves(
             }
         }
     }
-    // Cross-map worldport (`.tele Orgrimmar`, initial-login map, a boat crossing the sea): the net
-    // bridge surfaced it as a message earlier this frame (WorldStage::Net). Snap the avatar, bump
-    // `CurrentMap` so the terrain streamer swaps ADTs on the next frame, and ack if required (the
-    // ack unblocks the new map stream).
+    // Cross-map worldport: snap, bump `CurrentMap` for the terrain streamer, ack if required.
     for w in worldports.read() {
         let riding = w.transport_entry.is_some() && player.ride.is_some();
         if riding {
-            // Riding through the transfer (decision 0455): the pose is BOAT-LOCAL (vmangos
-            // `SendNewWorld` sends the rider's `GetTransportPos()`), and the boat entity was
-            // spared through the worldport purge — recompose the world pose through its live
-            // transform. NO settle hold: the deck is the support and its collider never
-            // unloaded — and settling ("held") would drop MOVEFLAG_ONTRANSPORT from the first
-            // post-crossing move packet (the 0447 flag law is `ride && !held`), which the
-            // server reads as a deboard mid-ocean.
+            // Riding through: the pose is deck-local (`Player.cpp:2114`) and the boat survived the
+            // purge. No settle hold: it would drop `MOVEFLAG_ONTRANSPORT` from the next move
+            // packet, which the server reads as a deboard mid-ocean.
             let ride = player.ride.as_mut().expect("riding checked above");
             ride.local_pos = wow_to_bevy(w.position);
             if let Ok((boat, _, _)) = transports.get(ride.entity) {
                 let boat_yaw = boat.rotation.to_euler(EulerRot::YXZ).0;
                 ride.boat_yaw = boat_yaw;
                 player.pos = boat.translation + boat.rotation * ride.local_pos;
-                // Local wire orientation + boat yaw = world facing (the GetAbsoluteFacing law);
-                // carry the body and camera to match, as the deck turn does (rigid for the
-                // whole rider — a lone aim carry leaves the body-chase to sweep + shuffle).
                 let dyaw = wrap_pi(w.orientation + boat_yaw - player.face_yaw);
                 player.face_yaw += dyaw;
                 player.model_yaw = wrap_pi(player.model_yaw + dyaw);
                 cam.yaw += dyaw;
             } else {
-                // The spared boat is gone (shouldn't happen — the spare predicate keys on the
-                // ride's own path). Land at the local pose read as world: wrong but bounded;
-                // the server's post-ack stream corrects us.
                 warn!("worldport: riding but the boat entity is missing — using raw pose");
                 player.pos = wow_to_bevy(w.position);
                 player.ride = None;
             }
         } else {
-            // A transfer the server did NOT carry a transport through (GM `.tele`, dungeon
-            // port): world pose — and any ride is stale, the server detached us (without this
-            // the next frame's carry would yank the avatar back onto the boat).
+            // No transport carried through: a world pose, and any ride is stale.
             player.ride = None;
             player.pos = wow_to_bevy(w.position);
             player.face_yaw = w.orientation;
-            player.model_yaw = w.orientation; // a teleport snaps the body — no chase across a loading screen
+            player.model_yaw = w.orientation; // the body snaps too, no chase
             cam.yaw = w.orientation;
             player.settling = true; // hold (gravity off) until the new map's ground streams in
             player.settle_since = time.elapsed_secs();
             player.settle_deadline = time.elapsed_secs() + SETTLE_TIMEOUT;
-            // …and the physics world under the new position is still the OLD map's until the
-            // streamer swaps it, one stage from now. See [`Player::world_stale`].
+            // The physics world is still the old map's until the streamer swaps it.
             player.world_stale = true;
         }
         player.move_flags = 0;
-        player.airborne_since = None; // a snap ends any in-progress jump arc (no phantom FALL_LAND)
-                                      // `insert_resource` replaces if it exists; terrain_stream watches it for diff vs the
-                                      // loaded map. If terrain setup never ran (no `./WoW/`), inserting is harmless.
+        player.airborne_since = None; // a snap ends any jump arc (no phantom FALL_LAND)
         commands.insert_resource(CurrentMap(w.map_id));
         if w.needs_ack {
             if riding {
-                // A riding crossing never settles (the deck is the support, 0455) — ack now,
-                // exactly as before 1340.
+                // A riding crossing never settles, so it acks now.
                 let _ = net_cmds.0.send(ClientCommand::WorldportAck);
                 info!(
                     "worldport: mapId {} @ {:?} (riding, boat-local pose, acked)",
                     w.map_id, w.position
                 );
             } else {
-                // The ack rides the settle release (decision 1340): the real client sends
-                // MSG_MOVE_WORLDPORT_ACK only after its blocking destination load completes, and
-                // vmangos keeps us out-of-world — dropping everything we'd send — until the ack
-                // lands, with no load timeout. See [`Player::owes_worldport_ack`].
+                // The ack waits for the settle release: the reference acks after its blocking
+                // load, and vmangos keeps us out of world until the ack, with no timeout.
                 player.owes_worldport_ack = true;
                 info!(
                     "worldport: mapId {} @ {:?} (world pose, ack deferred to release)",
@@ -299,47 +210,32 @@ 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.
+    // Same-map teleport: snap and echo the ack, without which the server freezes our movement.
     for t in teleports.read() {
         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 (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
-        // (`ExecuteTeleportNear` → `TeleportPositionRelocation`), and the destination's units
-        // stream within ~1 s of this send — measured with the `pop` pulse, four legs, no
-        // stall. The invented echo-time Stop this arm used to send served nothing; if a
-        // silent-player pop-in ever resurfaces, `WOW_MOVE_TRACE_TAGS=pop` decides in one run.
+        // The echo is the whole handshake: the reference echoes on its next movement tick
+        // (`0x60e0a0`) and sends nothing else, and vmangos relocates us only when it lands
+        // (`ExecuteTeleportNear`, `MovementHandler.cpp:237`).
         let _ = net_cmds.0.send(ClientCommand::TeleportAck {
             guid: t.guid,
             counter: t.counter,
         });
         info!("teleport: snapped to {:?}, acked", t.position);
     }
-    // A bare server-authored move for our own mover (decision 0725) — no handshake, no ack. Drained
-    // after the teleport arms deliberately: a teleport in the same frame is the larger edge (it
-    // swaps maps, holds the settle and owes an ack), so it wins the pose.
+    // Bare self-addressed moves, after the teleports so a same-frame teleport wins the pose.
     for m in self_moves.read() {
         if player.active {
             apply_self_move(m, player, cam, time, transports);
         }
     }
 
-    // **The ack'd movement-mode family** (decisions 0308, 0866) — root, water-walk, feather-fall,
-    // hover. Apply the mode to our typed state FIRST, then ack with the flag word that state
-    // rebuilds to: that ordering is the real client's, and it is also the server's law — an
-    // apply-ack whose `MovementInfo` lacks the mode bit un-grants the very mode it is accepting,
-    // and for root it is an outright KICK (vmangos `HandleMoveRootAck:715-723`, live-verified
-    // against the deploy's `Movement.log`).
+    // The acked modes: apply to our state first, then ack with the flags it rebuilds to, as the
+    // reference does. vmangos kicks a root apply-ack without `MOVEFLAG_ROOT`, or defers the root to
+    // landing when the ack carries `JUMPING` or `FALLINGFAR` (`MovementHandler.cpp:715-729`).
     //
-    // Root additionally **parks the walk stream and ends the arc**: moving bits must never
-    // accompany `MOVEFLAG_ROOT` (they freeze the real client, and vmangos raises
-    // `CHEAT_TYPE_ROOT_MOVE`), and the reference's own `SetRoot 0x7c7340` clears the direction bits
-    // and calls stop-fall `0x7c6290` at apply. Turn bits are *not* moving bits —
-    // `MOVEFLAG_MASK_MOVING` excludes them — the same asymmetry that keeps turning live while
-    // rooted.
+    // Root also parks the walk stream and ends the arc, as the reference's `SetRoot` (`0x7c7340`)
+    // clears the direction bits and stops the fall (`0x7c6290`); moving bits beside ROOT freeze
+    // the reference and raise vmangos's `CHEAT_TYPE_ROOT_MOVE`. Turn bits are not moving bits.
     for m in mode_msgs.read() {
         player.modes.set(m.mode, m.apply);
         if m.mode == MoveMode::Root && m.apply {
@@ -348,18 +244,10 @@ pub(super) fn apply_server_moves(
             player.vel_y = 0.0;
             player.fall_far = false;
         }
-        // **A hover grant jumps you** ([`Player::hover_launch`], decision 1620). The reference's
-        // handler for this very opcode is `0x61a620`, and setting the flag is its *last* act:
-        // `61a62c je` splits enable from disable, enable runs `CMovement::Jump(force = 0)`
-        // (`61a62e push 0; 61a630 call 0x7c6230`) and disable runs `StartFalling` (`61a637 call
-        // 0x7c61c0`), and only then does `61a646 call 0x7c7310` write `0x40000000`. Casting
-        // Levitate while swimming therefore launches the body clear of the water — the director's
-        // report against the reference client, which 1616 had recorded as faithfully inert
-        // because its census looked inside the resolver and the lift is a layer above it.
-        //
-        // The revoke arm needs nothing of ours: `StartFalling` sets FALLING with velocity 0, and
-        // dropping `hover_offset` to zero already leaves the body a yard over its floor with the
-        // ground probe out of reach, so the next step falls from rest by itself.
+        // A hover grant jumps you (`Player::hover_launch`): the reference's handler (`0x61a620`)
+        // runs `CMovement::Jump` (`0x7c6230`) on enable and `StartFalling` (`0x7c61c0`) on disable
+        // before it sets the flag (`0x7c7310`), so Levitate cast while swimming leaves the water.
+        // Disable needs nothing: with `hover_offset` at zero the body falls from rest by itself.
         else if m.mode == MoveMode::Hover && m.apply {
             player.hover_launch = true;
         }
@@ -380,23 +268,12 @@ pub(super) fn apply_server_moves(
         );
     }
 
-    // **The knockback** (decision 1702) — the one server-authored movement edge here that is neither
-    // a snap nor a granted mode: a ballistic launch we fly ourselves, with the ack owed only if we
-    // actually fly it. Nothing is applied here and nothing is acked here, and both halves are the
-    // reference's own shape: `0x617a30` merely **enqueues** the knockback as a due-timed record, and
-    // the frame update `0x616620` drains it apply-then-send inside one call
-    // (`0x61624d call 0x6179c0` → `0x616261 push 0xf0`), so the `MovementInfo` that goes on the wire
-    // is always the post-launch one. Arming a latch the take-off site consumes is that ordering,
-    // written the way our mover works — and it is the same latch shape the hover launch uses, for
-    // the same reason (decision 1620): our mover re-derives ground contact from probes every frame
-    // and would zero a velocity written from out here on its very next step.
+    // A knockback is only latched here; the mover launches it and acks. The reference enqueues it
+    // (`0x617a30`), and its frame update (`0x616620`) applies it (`0x6179c0`, called at `0x61624d`)
+    // and then acks (`0x616261`), so the wire carries the post-launch `MovementInfo`.
     //
-    // **Two in one frame collapse to the last, and that is ours, not the reference's.** Its queue
-    // holds both, sorted by due time, and drains them in order; our latch holds one. The *motion* is
-    // the same either way — `0x6179c0` replaces the velocity outright, so flying both in sequence
-    // inside one frame ends exactly where flying only the second does — but the first one's ack is
-    // lost, which the server counts as `OnFailedToAckChange`. It takes two knockbacks inside 17 ms
-    // to reach, and sub-frame launch timing is already the open item in 1702.
+    // Two in one frame collapse to the last, where the reference queues both: the motion is the
+    // same, as `0x6179c0` replaces the velocity, but the first ack is lost (`OnFailedToAckChange`).
     for k in knock_msgs.read() {
         player.knockback = Some(super::state::PendingKnockback {
             guid: k.guid,
@@ -405,32 +282,16 @@ pub(super) fn apply_server_moves(
         });
     }
 
-    // Take control once the server first reports our position (the streamed mover entity, whose
-    // transform is already in Bevy space). From here the controller drives that entity directly;
-    // the entity renderer attaches its body model (0041) the same way it does for any other player.
-    //
-    // The same edge serves a *mover change* — a possessed creature arriving in our hands, or our
-    // own body coming back (decision 1277). It is one path deliberately: seizing a body means the
-    // same thing either way, and the resource's pose describes whatever we were driving a moment
-    // ago. What differs is only the login-once half below (`first`), which owns the settle, the
-    // stale-world flag and the initial camera seat.
+    // Take control when the server first reports our position, and again on a mover change; only
+    // the login (`first`) settles, flags a stale world and seats the camera.
     let seizing = !player.active || player.reseat;
     if seizing {
         if let Some((pos, yaw)) = self_pose {
             let first = !player.active;
             player.reseat = false;
-            // Momentum, movement bits and the platform under our feet all belonged to the body we
-            // just let go of. The reference's `SetActiveMover 0x6006e0` tears exactly this down on
-            // the outgoing mover — resetting movement flags and cancelling click-to-move — and
-            // carrying any of it across would have the new body sprinting, falling or standing on a
-            // boat it is nowhere near.
-            //
-            // `first` scopes this to a mover change **inside one session**, and that gate is
-            // right: on a login there is no outgoing mover here to tear down, because the session
-            // that owned it ended at `release_on_session_end`, which since decision 1542 takes the
-            // whole resource. Until it did, the two lists were the same law kept in two places and
-            // this one was the longer — the reason B306's root outlived a `/logout` was that the
-            // only teardown naming `modes` was the one a login skips.
+            // A mover change tears down the outgoing mover's state, as the reference's
+            // `SetActiveMover` (`0x6006e0`) resets its flags and click-to-move. A login needs none:
+            // `release_on_session_end` already reset the whole resource.
             if !first {
                 player.vel_y = 0.0;
                 player.horiz_vel = Vec3::ZERO;
@@ -440,37 +301,28 @@ pub(super) fn apply_server_moves(
                 player.fall_far = false;
                 player.fall_start_y = pos.y;
                 player.ride = None;
-                // The granted modes (root, water-walk, feather-fall, hover) were granted to the
-                // *previous* mover; the new one's arrive on its own `SMSG_FORCE_*`/mode packets.
+                // The new mover's modes arrive in their own packets.
                 player.modes = Default::default();
             }
             player.pos = pos;
             player.active = true;
             if first {
-                player.settling = true; // settle onto the initial ground once it loads (don't fall through)
+                player.settling = true; // settle once the initial ground loads
                 player.settle_since = time.elapsed_secs();
                 player.settle_deadline = time.elapsed_secs() + SETTLE_TIMEOUT;
-                player.world_stale = true; // nothing is streamed yet — see [`Player::world_stale`]
-                                           // The streamed spawn pose carries the server's facing (the character's logout
-                                           // orientation on a fresh login) — adopt it whole, camera seated behind, like
-                                           // the reference. Zeroing here made every login face due north regardless.
+                player.world_stale = true;
+                // The spawn pose carries the server's facing (the logout orientation): adopt it,
+                // camera behind, as the reference does.
                 cam.yaw = yaw;
                 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
-            // far sight moved it there before the reins arrived), and snapping its yaw would spin
-            // the view for a change the player made happen on purpose.
+            // No camera re-seat on a mover change: Mind Control's far sight already moved it.
             player.face_yaw = yaw;
             player.model_yaw = yaw;
-            // Seed the facing-change detector with the adopted facing — the server gave it to us,
-            // so the first controlled frame owes no `SET_FACING` (the real client sends nothing at
-            // login until the mouse actually turns).
+            // The first frame owes no `SET_FACING`: the reference sends none until a turn.
             player.last_facing = yaw.rem_euclid(std::f32::consts::TAU);
-            // The avatar's `MovementState` (the animation selector's motion source) is NOT inserted
-            // here: it rides the `SelfPlayer` tag (`net::apply::tag_self_player`), because a
-            // cross-map worldport despawns and re-streams this entity while `player.active` stays
-            // true — per-entity state attached only on this one-shot edge would be lost on transfer.
+            // `MovementState` comes with the `SelfPlayer` tag, not here: a worldport re-streams
+            // the entity while `player.active` stays true.
             info!(
                 "took control of {} @ {:?} facing {:.3}{}",
                 match player.foreign_mover {
@@ -484,11 +336,9 @@ pub(super) fn apply_server_moves(
         }
     }
 
-    // Forced speed changes (aura/mount/GM `.modify speed`): the net bridge already applied the new
-    // value to our `UnitSpeeds`; the mandatory ack is ours to send, carrying our live wire state
-    // (the server relocates us to it — the TeleportMessage pattern). In the controlled branch the
-    // ack rides the movement stream's exact per-frame payload (`stream_self_movement`); detached or
-    // pre-control, our honest wire state IS the parked pose (flags 0), so answer here directly.
+    // Forced speed changes: the bridge applied the speed; the ack carries our wire state, which the
+    // server relocates us to. Controlled, the movement stream acks; otherwise our state is the
+    // parked pose, so ack here.
     let speed_acks: Vec<SpeedChangeMessage> = speed_msgs.read().copied().collect();
     if !player.active || player.detached {
         for ack in &speed_acks {
@@ -510,70 +360,43 @@ 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.
+/// Apply one same-map teleport's snap (`MSG_MOVE_TELEPORT_ACK` inbound); the caller echoes it.
 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.
+    // A near teleport arrives detached: vmangos takes this path only off a transport
+    // (`Player.cpp:1866-1893`), and the reference's apply (`0x6186b0`) re-parents to the packet's
+    // transport guid, zero here. A kept ride would carry us back onto 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.airborne_since = None; // a snap ends any jump arc (no phantom FALL_LAND)
+    player.settling = true; // hold (gravity off) until the destination loads
     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`].
+    // The destination's ground may not have streamed yet.
     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).
+    // Voids any self ride: `drive_self_ride` drops it rather than mirror the stale pose over this.
     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
-/// a server-authored pose can relocate a rider but never board or deboard them. See
-/// [`move_flags::SERVER_AUTHORED`].
+/// The reference's masked merge of a server-authored `MOVEMENTFLAGS` (`0x618c30` at `0x618deb`:
+/// `old ^ ((old ^ wire) & 0x75a07dff)`). `ON_TRANSPORT` is outside the mask, so a server pose never
+/// boards or deboards us.
 pub(super) fn merge_server_flags(local: u32, wire: u32) -> u32 {
     move_flags::merge_server_authored(local, wire)
 }
 
-/// Apply one bare self-addressed `MSG_MOVE_*` — a pose the *server* wrote for our own mover, with
-/// no handshake (decision 0725). `.go forward`/`up`/`relative`,
-/// `.cheat fly`/`fixedz` and the movement anticheat's snap-back all land here.
+/// Apply one bare self-addressed `MSG_MOVE_*`, a pose the server wrote for our mover (`.go`,
+/// `.cheat fly`, an anticheat snap-back): a hard snap with no ack. The reference writes the pose
+/// into its live cell and its integrator base (`0x7c6420`), one cell for us ([`Player::pos`]), and
+/// our next heartbeat carries it home.
 ///
-/// **A hard snap, and nothing goes back.** The reference writes the wire pose into both its live
-/// position cell and its integrator *base* (`0x7c6420`), which is what makes the snap persist —
-/// the next frame integrates forward from the server's point instead of rubber-banding off it. For
-/// us those are one cell ([`Player::pos`]), so the snap is the whole of it. It sends no ack and
-/// opens no suppression window: our ordinary heartbeat then carries the server's own pose home,
-/// which is precisely why `.go forward` sticks.
-///
-/// **Applied inline, not scheduled** — the one place this departs from the reference's shape, and
-/// it is a deliberate divergence rather than a shortcut. The reference has a single move machine
-/// and routes a self-addressed packet through the same replay chain as a remote's (decisions
-/// 0601/0615). Measured against that chain (`net::motion::tests`'
-/// `the_chain_paces_a_server_authored_self_move_and_would_hold_an_early_one`) it does **not** always
-/// come back due: the first one fires at arrival, but once the chain has stamps to pace against, a
-/// packet arriving ahead of the sender's cadence is deliberately *held* — bounded at +1000 ms.
-///
-/// That holding is the chain's whole purpose and it is right for a remote: replaying a mover on the
-/// sender's own spacing is what stops a watched player stuttering between packets. It buys nothing
-/// here. Our avatar is not something we extrapolate between packets — there is no motion to
-/// de-jitter — so preserving the "cadence" between one GM command and the next would only delay a
-/// correction to our own pose behind a queue the controller would have to yield to. We take the
-/// snap at arrival. The trigger to revisit is a self-addressed *stream*: `Anticheat.Enable = 1`,
-/// whose snap-backs can burst, is the one sender that would produce one.
-// The transports query type is `control`'s own param shape passed through, like the caller's.
+/// Deviation: applied at arrival, because our own avatar has no motion to de-jitter; the reference
+/// routes it through the replay chain remotes use, which paces to the sender's cadence and can hold
+/// an early packet (up to 1000 ms in `net::motion`). A self-addressed stream, such as bursting
+/// anticheat snap-backs, would need that pacing.
+// `control`'s own transports query, passed through.
 #[allow(clippy::type_complexity)]
 fn apply_self_move(
     m: &SelfMoveMessage,
@@ -589,60 +412,34 @@ fn apply_self_move(
     player.move_flags = merge_server_flags(player.move_flags, m.flags);
     let now_falling = player.move_flags & move_flags::FALLING != 0;
 
-    // **Lift the granted mover MODES out of the merged word into typed state** (decision 0726).
-    // `move_flags` is our last-streamed wire bookkeeping and is rebuilt from state every frame, so a
-    // 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`, the local unit's server echo included. This pair is
-    // GM flight: `.cheat fly` sends SWIMMING + LEVITATING together.
+    // Lift the merged modes into typed state, as `move_flags` is rebuilt every frame; the
+    // reference's merge applies swimming too (`0x61a1af` → `0x61a230`). `.cheat fly` sends
+    // SWIMMING with LEVITATING.
     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
-    // carries whatever walk bit *it* last saw — normally our own, echoed back from the
-    // `m_movementInfo` our last packet refreshed, which makes this idempotent. Dropping the lift
-    // instead would let one server-authored move silently clear the bit out of the word while the
-    // latch stayed set, and the next frame would rebuild the word and re-announce it: a
-    // SET_RUN_MODE / SET_WALK_MODE pair per teleport.
+    // The walk bit is lifted too, normally our own echoed back; else a server move would clear it
+    // under a set latch, and the next frame would re-announce the gait.
     player.walking = player.move_flags & move_flags::WALK_MODE != 0;
     player.modes.merge_from_wire(player.move_flags);
-    // Neither mode touches `settling`: the settle release is the terrain streamer's, keyed on the
-    // destination's residency in every mover mode alike (decision 0737). The pre-0737 special case
-    // here (swim clears the hold) existed only because the old release was a walk-mover ground
-    // probe a swimmer/flyer never reached.
+    // Neither mode touches `settling`: the terrain streamer releases it in every mode alike.
 
     player.pos = wow_to_bevy(m.position);
-    // Facing turns **rigidly** — aim, rendered body and camera all take the same delta (the
-    // transport carry's idiom). The reference writes only the mover's own facing cells; hard-setting
-    // the camera the way the teleport arm does would yank the view on every `.cheat fly` toggle,
-    // whose heartbeat carries nothing but the server's slightly-stale copy of our own orientation.
+    // Aim, body and camera turn by the same delta; the reference writes only the mover's facing,
+    // and a hard camera set would yank the view on every `.cheat fly` toggle.
     let dyaw = wrap_pi(m.orientation - player.face_yaw);
     player.face_yaw = wrap_pi(player.face_yaw + dyaw);
     player.model_yaw = wrap_pi(player.model_yaw + dyaw);
     cam.yaw += dyaw;
     player.mover_pitch = m.pitch;
 
-    // Riding a deck: `ON_TRANSPORT` is outside the merge mask, so this packet did not deboard us —
-    // it moved us **within** the platform frame. Re-anchor the local pose, then let the carry
-    // recompose from it; without the re-anchor the next frame's carry reinstates the stale one and
-    // undoes the snap.
-    //
-    // **Take the wire's own deck-local pose when the packet carried one** (decision 2026). The
-    // subtraction below is only the server's answer while client and server agree about where the
-    // boat is, and at a cross-map seam they provably do not: our path clock has not crossed yet, so
-    // [`crate::transport::tick_transports`] is holding the boat's transform frozen at the *source*
-    // continent's pose while this packet's `position` is a world position on the *destination*. The
-    // difference is then not a deck offset but the distance between two continents — stable while
-    // the boat stays frozen (the carry just reproduces the server's own position, so nothing looks
-    // wrong), and a ~13 000 yd fling off the deck the instant the boat writes an honest pose again.
-    // The server sent us the right number in the same packet; use it.
+    // On a deck the packet moved us within the platform frame (`ON_TRANSPORT` is outside the mask):
+    // re-anchor the local pose, or the next carry undoes the snap. Prefer the wire's deck-local
+    // pose: at a cross-map seam our boat is still frozen on the source continent while `position`
+    // is on the destination, so the subtraction would fling us thousands of yards.
     if let Some(ride) = player.ride.as_mut() {
         if let Ok((boat, _, _)) = transports.get(ride.entity) {
             match m.transport.filter(|t| t.guid == ride.guid) {
                 Some(t) => {
                     ride.local_pos = wow_to_bevy([t.pos.x, t.pos.y, t.pos.z]);
-                    // World facing = local + boat yaw (the GetAbsoluteFacing law), so the carried
-                    // aim stays right even when the boat's own heading is the frozen one.
                     ride.boat_yaw = boat.rotation.to_euler(EulerRot::YXZ).0;
                     player.pos = boat.translation + boat.rotation * ride.local_pos;
                 }
@@ -654,9 +451,8 @@ fn apply_self_move(
         }
     }
 
-    // The airborne arc. The reference gates the fall tail on the *merged* `FALLING` bit — a data
-    // gate, not an identity one — seeding the arc from the wire when it is set (`0x7c6490`) and
-    // running the landing reaction when it just cleared.
+    // The arc follows the merged `FALLING` bit: seeded from the wire when set (`0x7c6490`), ended
+    // when it just cleared.
     match (was_falling, now_falling) {
         (_, true) => {
             let (vel_y, xy) = crate::net::jump_seed(m.jump, m.fall_time, player.modes.feather_fall);
@@ -672,9 +468,8 @@ fn apply_self_move(
             player.airborne_dirs = player.move_flags & move_flags::ANY_MOVE;
         }
         (true, false) => {
-            // The arc is over by server decree (`NearLandTo` strips `JUMPING|FALLINGFAR` before it
-            // sends). Ended **silently**: our landing report is a fall *height*, and the same packet
-            // just moved the body an arbitrary distance, so there is no descent left to measure.
+            // Ended by the server (`Unit.cpp:10073` strips `JUMPING|FALLINGFAR`), silently: the
+            // packet moved us, so there is no fall height to report.
             player.airborne_since = None;
             player.fall_far = false;
             player.vel_y = 0.0;
@@ -685,49 +480,18 @@ fn apply_self_move(
     player.wedge_still = 0;
 }
 
-/// **The avatar went away with the session** — the whole resource goes back to the state the
-/// process booted in (`player::setup` inserts `Player::default()`), so the next login re-takes
-/// control from its own streamed `SelfPlayer` (possibly a different character on a different map
-/// — the boot path) owing nothing to the session that ended. The entity itself is despawned by the
-/// net drain the same frame these messages are written.
-///
-/// Two edges, one answer (decision 1262): a confirmed `/logout` (decision 0193), and a **lost**
-/// session, which since 1262 takes the avatar too — there is no reconnect left for it to be the
-/// puppet of. Missing the second edge would leave `Player.active` true over a despawned entity: a
-/// 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). 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
-/// to revoke. `modes.rooted` therefore survived into the new world and killed WASD for the rest of
-/// the run. The list was the bug, not the missing line: the take-control edge above keeps its own
-/// list for the same law (a mover *change* tears the old mover down — `SetActiveMover 0x6006e0`),
-/// the two drifted apart, and only one of them ran here. So this end takes the resource whole —
-/// 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` (`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.
+/// On a `/logout` or a lost session, reset the whole resource to its boot state, so the next login
+/// owes nothing to the ended one. Whole, not by field: `/logout` roots us for the countdown
+/// (`MiscHandler.cpp:329`) and the next session never unroots, so any kept mover state persists.
+/// The reference also keeps no mover state, shutting the game down on logout (`0x491180`).
 pub(super) fn release_on_session_end(
     mut logouts: MessageReader<crate::net::LoggedOutMessage>,
     mut lost: MessageReader<crate::net::DisconnectedMessage>,
     mut player: ResMut<Player>,
 ) {
-    // Both readers drain unconditionally — `|`, not `||`: a short-circuit would leave the other
-    // message unread, and its cursor would carry it into the next frame.
+    // `|`, not `||`: both readers must drain, or the unread one carries into the next frame.
     if logouts.read().next().is_some() | lost.read().any(|m| m.session_over) {
-        // Nothing is carried across. Among what this clears that a named list kept missing: the
-        // granted modes (B306's root, and water-walk/feather-fall/hover with it — vmangos re-sends
-        // every one the new session really holds, `Player::SendInitialPacketsAfterAddToMap`
-        // re-applies the aura family), the reins (`control_lost`, `foreign_mover`) which would
-        // otherwise leave the next login driving a guid that no longer exists, the autorun latch,
-        // and — as before — `active`, the movement flags, the fall/wedge state and the worldport
-        // ack debt (decision 1340: an ack from the old transfer is rejected by a player who is
-        // already in world, and the server force-acked it at logout anyway).
+        // vmangos re-sends the modes the new session holds (`Player.cpp:19297-19311`).
         *player = Player::default();
     }
 }
@@ -748,9 +512,7 @@ mod session_end_tests {
         app
     }
 
-    /// A session that actually ran: in world, moving, with every mode the server can grant on our
-    /// mover — and the reins in somebody else's hands. Every one of these was granted TO THE MOVER
-    /// this session owned, which is the whole of why none of it may outlive it.
+    /// A session that ran: in world, moving, every mode granted, the reins in other hands.
     fn a_session_that_ran(app: &mut App) {
         let mut p = app.world_mut().resource_mut::<Player>();
         p.active = true;
@@ -773,17 +535,9 @@ mod session_end_tests {
         p.wedged = true;
     }
 
-    /// **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
-    /// the water-walk/feather-fall/hover aura family and roots only for a stun aura). So anything
-    /// the ended session left on this resource is permanent, and `modes.rooted` is WASD.
-    ///
-    /// The assertion is deliberately against `Player::default()` whole rather than a list of
-    /// fields: a list is what failed — this reset named six fields, the take-control edge's own
-    /// teardown named nine, and only the second list named `modes`. A field added to `Player`
-    /// tomorrow is covered by this test on the day it is added.
+    /// `/logout` roots us (`MiscHandler.cpp:329`) and the next login is never unrooted:
+    /// `SendInitialPacketsAfterAddToMap` re-roots only for a stun (`Player.cpp:19297-19311`).
+    /// Checked against `Player::default()` whole, so a new field is covered.
     #[test]
     fn a_logout_takes_every_grant_the_ended_session_made() {
         let mut app = harness();
@@ -804,9 +558,7 @@ mod session_end_tests {
         );
     }
 
-    /// The second edge (decision 1262) is the same answer: a lost session takes the avatar too, so
-    /// it takes everything granted to it. Not a variant of the above — it is a different message
-    /// on a different reader, and the `|` that drains both is load-bearing.
+    /// A lost session is a different message on a different reader; the `|` draining both matters.
     #[test]
     fn a_lost_session_takes_them_too() {
         let mut app = harness();
@@ -821,11 +573,7 @@ mod session_end_tests {
         assert!(*app.world().resource::<Player>() == Player::default());
     }
 
-    /// **A teardown that is not the end must not wipe a live avatar.** Both cases that reach this
-    /// system with `session_over: false` are ones where the body stays ours: the `/logout`'s own
-    /// teardown disconnect (the roster relist *inside* one session — its `LoggedOutMessage` is the
-    /// edge, above) and an unattended run's seamless reconnect (0065). Resetting on the mere
-    /// arrival of a `DisconnectedMessage` would drop control from under a probe mid-run.
+    /// `session_over: false` (the logout's own teardown, a seamless reconnect) keeps the body ours.
     #[test]
     fn a_teardown_that_is_not_the_end_keeps_the_avatar() {
         let mut app = harness();
@@ -851,10 +599,8 @@ mod self_move_tests {
     use super::merge_server_flags;
     use crate::creature_anim::move_flags as f;
 
-    /// The merge is not an assignment, and the bit that proves it is `ON_TRANSPORT`: it sits
-    /// outside the reference's `0x75a07dff` mask, so a server-authored pose relocates a rider on
-    /// the deck without ever boarding or deboarding them. Everything else we model is inside, and
-    /// the wire owns it — including `FALLING`, whose clearing is how `.go forward` ends an arc.
+    /// `ON_TRANSPORT` is outside the reference's `0x75a07dff` mask; `FALLING` is inside, which is
+    /// how `.go forward` ends an arc.
     #[test]
     fn a_server_move_owns_the_wire_bits_and_leaves_the_transport_bit_alone() {
         // Riding a boat, running forward. The server says: standing still, falling, not on a boat.
@@ -869,30 +615,23 @@ mod self_move_tests {
         assert_eq!(merged & f::FALLING, f::FALLING, "the wire owns FALLING");
         assert_eq!(merged & f::FORWARD, 0, "and it owns the direction bits too");
 
-        // The other direction: the wire claiming ON_TRANSPORT cannot board us either.
         assert_eq!(merge_server_flags(0, f::ON_TRANSPORT), 0);
     }
 
-    /// **`.cheat fly` survives the merge intact** (decision 0726). vmangos's `Player::SetFly` sends
-    /// `LEVITATING | SWIMMING | MOVED | FLYING`; the two we model must both be inside the mask, or
-    /// GM flight arrives half-applied — SWIMMING without LEVITATING is a swimmer on dry land that
-    /// the water decision clears on the next frame, and LEVITATING without SWIMMING is a walker
-    /// whose swim latch has simply been frozen.
+    /// `Player::SetFly` sends `LEVITATING | SWIMMING | MOVED | FLYING` (`Player.cpp:4595`).
     #[test]
     fn the_fly_toggle_arrives_whole() {
         const SET_FLY: u32 = f::LEVITATING | f::SWIMMING | 0x0080_0000 | 0x0100_0000;
         let merged = merge_server_flags(f::FORWARD, SET_FLY);
         assert_eq!(merged & f::LEVITATING, f::LEVITATING);
         assert_eq!(merged & f::SWIMMING, f::SWIMMING);
-        // …and `.cheat fly off` (flags 0) takes both away again, which is what lands us.
+        // `.cheat fly off` sends flags 0.
         assert_eq!(
             merge_server_flags(merged, 0) & (f::LEVITATING | f::SWIMMING),
             0
         );
     }
 
-    /// Every flag benilla models except `ON_TRANSPORT` is inside the mask — a guard against the
-    /// mask and our constants drifting apart as new bits get modelled.
     #[test]
     fn every_modelled_flag_but_the_transport_bit_is_server_authored() {
         for (name, bit) in [
@@ -928,10 +667,6 @@ mod control_tests {
     const VICTIM: u64 = 0x0000_0000_0000_0099;
     const CREATURE: u64 = 0xF130_000C_1A00_A2B4;
 
-    /// The victim's inversion trap, stated as a test: the packet that revokes control names **us**,
-    /// so "the mover is now `mover`" would read it as *gaining* control of ourselves at the exact
-    /// moment we lost it — and a mind-controlled player would keep walking, which is the reported
-    /// bug (B211's second half).
     #[test]
     fn naming_us_is_never_a_grant_and_naming_another_is_never_about_our_body() {
         assert_eq!(
@@ -953,17 +688,15 @@ mod control_tests {
         );
     }
 
-    /// vmangos's real Mind Control sequences, in order, from both sides of the spell. The caster's
-    /// *end* sequence is the one worth pinning: it restores us BEFORE releasing the victim, so a
-    /// handler that keyed off "the last packet wins" would leave the caster unable to move.
+    /// vmangos's Mind Control sequences; the caster's end restores before it releases.
     #[test]
     fn the_mind_control_sequences_classify_in_order() {
-        // Caster, possession start: one grant naming the victim. (`Unit::UpdateControl`.)
+        // Caster, possession start: one grant naming the victim.
         assert_eq!(
             control_verdict(VICTIM, true, Some(ME)),
             ControlVerdict::Granted(VICTIM)
         );
-        // Caster, possession end: `(self, 1)` then `(victim, 0)` — restore first, release second.
+        // Caster, possession end: `(self, 1)` then `(victim, 0)` (`SpellAuras.cpp:3023-3024`).
         let caster_end = [
             control_verdict(ME, true, Some(ME)),
             control_verdict(VICTIM, false, Some(ME)),
@@ -974,8 +707,7 @@ mod control_tests {
             "restore lands BEFORE the release; last-packet-wins would strand the caster"
         );
 
-        // Victim's own client, from ITS point of view (self_guid == VICTIM): revoked at the start,
-        // restored at the end. Both name the victim; only the byte differs.
+        // The victim's own client: revoked at the start, restored at the end.
         assert_eq!(
             control_verdict(VICTIM, false, Some(VICTIM)),
             ControlVerdict::Revoked
@@ -986,8 +718,6 @@ mod control_tests {
         );
     }
 
-    /// Before login names us, nothing can be about our body — and in particular a packet must not
-    /// classify as `Revoked` and silently freeze the character the moment control starts.
     #[test]
     fn an_unknown_self_guid_never_revokes_our_own_body() {
         assert_eq!(
@@ -1003,10 +733,7 @@ mod control_tests {
 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.
+    /// Hearthing off a zeppelin or a lift is a same-map teleport.
     #[test]
     fn a_near_teleport_leaves_the_transport() {
         let mut player = Player {
diff --git a/crates/benilla-app/src/player/world_focus.rs b/crates/benilla-app/src/player/world_focus.rs
index 72a3cce0..c96fd620 100644
--- a/crates/benilla-app/src/player/world_focus.rs
+++ b/crates/benilla-app/src/player/world_focus.rs
@@ -1,21 +1,7 @@
-//! **The game's half of 1160's wire (a) and the settle release** — what the world is told, and
-//! what the game does with what the world publishes back.
-//!
-//! The terrain streamer used to read `player::Player` directly (where the avatar is, whether it is
-//! settled) and write it back (lifting the post-snap hold when the destination's colliders
-//! arrived). Both directions are the engine reaching across the line: a world renderer cannot
-//! depend on a game's avatar type, and `benilla-worldview` proved the point by having to stub one.
-//!
-//! Inverted, it is two systems and no shared type:
-//!
-//! - [`publish_view_focus`] answers the world's one question — *where should I stream from* —
-//!   ahead of the stream stage. The viewer with no avatar (a capture run, the world viewer)
-//!   answers `ViewFocus::camera()` and needs nothing else.
-//! - [`release_post_snap_hold`] reads the residency the world publishes and decides when the
-//!   mover's hold ends. The *decision* is the game's; the *fact* is the world's. That split is why
-//!   decision 0737's law survives the move intact — the hold still ends on residency and never on
-//!   ground contact, and every mover mode still releases the same way, because there is still
-//!   exactly one place that does it.
+//! What the game tells the world, and what it does with what the world publishes back:
+//! [`publish_view_focus`] says where to stream from, ahead of the stream stage, and
+//! [`release_post_snap_hold`] ends the mover's settle hold on the residency the world publishes.
+//! The hold ends on residency, never on ground contact, the same way for every mover mode.
 
 use bevy::prelude::*;
 
@@ -23,8 +9,7 @@ use super::{Player, SETTLE_TIMEOUT};
 use benilla_world::terrain_stream::{ViewFocus, WorldLoadProgress};
 use benilla_world::view::Viewer;
 
-/// Tell the world where the avatar's body is, in the one shape the three lanes that ask actually
-/// want (see [`Viewer`]). Same frame position and same gate as the focus below.
+/// Tells the world where the avatar's body is ([`Viewer`]), with the focus's position and gate.
 pub(super) fn publish_viewer(
     mut viewer: ResMut<Viewer>,
     player: Option<Res<Player>>,
@@ -32,10 +17,8 @@ pub(super) fn publish_viewer(
     screen: Option<Res<crate::loading_screen::LoadingScreen>>,
     store: Query<&crate::net::ObjectStore, With<crate::net::SelfPlayer>>,
 ) {
-    // The viewer's *condition*, off **our own character's** descriptor block: both are whole-screen
-    // effects, which is why they ride here rather than on any body in the scene — and why they read
-    // `SelfPlayer` rather than the body we drive. Being drunk is a fact about you; possessing a boar
-    // does not sober you up, and a boar has no drunk byte to read (decision 1277).
+    // Drunk and ghost are whole-screen effects of our own character, so they read `SelfPlayer`,
+    // not the body we drive: possessing a boar does not sober you up.
     let (drunk, ghost) = match store.single() {
         Ok(s) => (
             s.0.player_drunk_byte()
@@ -44,9 +27,7 @@ pub(super) fn publish_viewer(
         ),
         Err(_) => (0.0, false),
     };
-    // The ghost A/B override (`WOW_GHOST_PROBE`) lands here rather than beside the screen pass it
-    // used to pin alone: this flag is what the death light and the DeathClouds sky both read, so
-    // overriding it is what makes the probe mean "the ghost world" rather than "the ghost filter".
+    // `WOW_GHOST_PROBE` overrides the flag the death light and the DeathClouds sky both read.
     let ghost = crate::death::ghost_probe().unwrap_or(ghost);
     let body = match player.as_deref() {
         Some(p) if p.active && !p.detached => Viewer {
@@ -61,16 +42,15 @@ pub(super) fn publish_viewer(
     *viewer = Viewer {
         drunk,
         ghost,
-        // The bare zoom feather. The mesh-side writer folds the aura factor separately, so this
-        // must stay the zoom alone or the self body double-applies it.
+        // The zoom feather alone: the mesh side folds in the aura factor, so it must not be here.
         self_fade: rig.as_deref().map_or(1.0, super::CameraControl::self_fade),
         world_covered: screen.as_deref().is_some_and(|s| s.covering()),
         ..body
     };
 }
 
-/// Tell the world where to stream from, once per frame, before the stream stage reads it — and,
-/// when that answer is not the body, put the body on the settle hold for as long as it is not.
+/// Tells the world where to stream from each frame, before the stream stage; a cinematic, which
+/// streams from the camera, also puts the body on the settle hold.
 pub(super) fn publish_view_focus(
     mut focus: ResMut<ViewFocus>,
     mut player: Option<ResMut<Player>>,
@@ -81,36 +61,13 @@ pub(super) fn publish_view_focus(
     let entry = roster
         .as_deref()
         .and_then(crate::char_select::Roster::pending_entry);
-    // A cinematic flies the eye away from the body — a Tauren's intro opens 1741 yards out — so
-    // the stream has to follow the *camera* for its duration or the shot crosses unstreamed
-    // terrain. That is what `detached` already means here (the eye is off the body; the zone
-    // authority stays on it), so a fly-by borrows free-fly's answer rather than inventing a third
-    // mode. The server does the mirror-image thing on its side: while a cinematic runs it
-    // re-anchors object visibility to its own copy of the flying camera (decision 0196).
+    // A cinematic flies the eye away from the body (a Tauren intro opens 1741 yd out), so the
+    // stream follows the camera, as in free-fly.
     let flying = cinematic.as_deref().is_some_and(|c| c.is_playing());
-    // **A detached focus stops keeping the body's own ground resident — so the body goes on the
-    // hold for as long as that lasts.** Free-fly never had to answer for this: `control` skips the
-    // whole controlled branch while `detached`, so nothing simulates the body there. A cinematic
-    // does, and the body stands with gravity on while the tiles under it unload. Measured on the
-    // probe: `.debug play cinematic 41` over a settled body at z=59.4 dropped it to z=-62 within
-    // four seconds, the server yanking it back, and it never sent a movement packet again.
-    //
-    // This is not a new fact — it is the settle hold's own ("the ground under this body is not
-    // there"), reached from the other side: after a teleport the body's world has not arrived
-    // *yet*, and here it is *leaving*. So it takes the same hold, and the release stays exactly
-    // where decision 0737 put it — [`release_post_snap_hold`], on residency about the body's own
-    // tile, which cannot become true again until the shot ends and the focus comes home. Nothing
-    // here ever clears the hold: starting one is the game's business, ending one is the world's.
-    //
-    // `world_stale` rides with it because it is equally true — the resident world is the flying
-    // camera's, not this body's — and because it is what keeps the stall backstop off. Without it
-    // a camera that settles mid-shot goes quiet, the 6 s no-progress budget expires, and gravity
-    // comes back on partway through a 102-second intro: the exact fall this prevents, delayed.
-    // Armed on the RISING EDGE, never re-asserted per frame — the sentence above is a rule, not a
-    // flourish. A shot whose camera happens to stay on the body's own tile makes that tile resident
-    // and the release ends the hold at once, correctly; re-arming every frame would fight it and
-    // leave `settling` oscillating under the loading screen's clear-gate and the zone-channel walk,
-    // both of which read it.
+    // Unlike free-fly, where `control` skips the body, a cinematic simulates it while its tiles
+    // unload, so it takes the settle hold, which only residency of its own tile ends. `world_stale`
+    // keeps the stall backstop from turning gravity back on mid-shot. Armed on the rising edge
+    // only, so a shot that stays on the body's tile lets the release end the hold.
     if flying && !*was_flying {
         if let Some(p) = player.as_deref_mut().filter(|p| p.active) {
             p.settling = true;
@@ -119,9 +76,8 @@ pub(super) fn publish_view_focus(
         }
     }
     *was_flying = flying;
-    // The pacing bit: spawn caps apply only to a live avatar standing in a settled world. Through
-    // entry, a teleport and a world swap the loading cover is absorbing the burst, and a cap there
-    // would only lengthen the reveal.
+    // Spawn caps pace only a live avatar in a settled world; under the loading cover (entry, a
+    // teleport, a world swap) a cap would only lengthen the reveal.
     *focus = match player.as_deref() {
         Some(p) if p.active => {
             let wow = benilla_assets::coords::bevy_to_wow(p.pos);
@@ -132,7 +88,7 @@ pub(super) fn publish_view_focus(
                 ViewFocus::body(wow, paced)
             }
         }
-        // No avatar: the picked character's row for the entry window (decision 0777), else
+        // No avatar: the picked character's row for the entry window, else
         // whatever the camera can see.
         _ => match entry {
             Some((map, pos)) => ViewFocus::entry(map, pos),
@@ -141,11 +97,8 @@ pub(super) fn publish_view_focus(
     };
 }
 
-/// End the post-snap hold when the destination's world has arrived — decision 0737, reading the
-/// streamer's published residency instead of being written by it.
-///
-/// Runs after the stream stage so `colliders_pending` is this frame's count, which is the same
-/// freshness `finish_colliders` heading the streaming chain was always there to give it.
+/// Ends the post-snap hold when the destination's world has arrived. Runs after the stream stage,
+/// so `colliders_pending` is this frame's count.
 pub(super) fn release_post_snap_hold(
     mut player: ResMut<Player>,
     progress: Option<Res<WorldLoadProgress>>,
@@ -154,27 +107,20 @@ pub(super) fn release_post_snap_hold(
     net_cmds: Option<Res<crate::net::NetCommands>>,
 ) {
     let Some(p) = progress else { return };
-    // **The facts must be about the ground under our own feet** (decision 1336, B263 round 3).
-    // `WorldLoadProgress` names the tile it describes; a mismatch means the streamer's focus and
-    // the avatar diverged — the stale-focus snap frame this guard exists for, or a detached
-    // free-fly eye — and residency published for another tile must never unfreeze this body. On a
-    // mismatch the resident release and the stale-clear below are both refused; the stall backstop
-    // still runs, so a genuinely wedged mismatch costs a logged 6 s timeout, never a silent fall.
+    // Residency counts only for the tile under the body. On a mismatch (the teleport's snap frame,
+    // a free-fly eye) the release and the stale-clear are refused and only the backstop runs.
     let focus_matches = p.focus_tile.is_some_and(|t| {
         let wow = benilla_assets::coords::bevy_to_wow(player.pos);
         let (tx, ty) = benilla_formats::world_to_tile(wow[0], wow[1]);
         t == (tx as i32, ty as i32)
     });
-    // The streamer is the only authority on *which map* the colliders under the avatar belong to.
-    // Residency here means this map's own tile (or, on a WMO-only map, its one building) is
-    // spawned — reachable only after a swap has drained every tile of the map we left.
+    // Residency means this map's own tile (a WMO-only map's one building) is spawned, which a
+    // swap reaches only after draining every tile of the map we left.
     if p.focus_resident && p.total > 0 && focus_matches {
         player.world_stale = false;
     }
-    // Did the stream move since last frame? Any counter changing — a tile spawned, a placement
-    // up, a collider queued or attached, a retained region baked — is the destination still
-    // arriving. Tracked every frame
-    // (not just while settling) so the first settling frame compares against a real baseline.
+    // Any counter moving is the destination still arriving; tracked every frame, so the first
+    // settling frame has a baseline.
     let counters = [
         p.ready,
         p.total,
@@ -187,16 +133,9 @@ pub(super) fn release_post_snap_hold(
     if !player.settling {
         return;
     }
-    // The release ends on scene AND colliders, never on ground contact — feet-on-ground dragged
-    // the whole mover-mode matrix into a loading decision, and a flyer or swimmer never touched
-    // it. The timeout is a STALL budget, twice over (0710's fail-closed law, extended by B263 /
-    // decision 1303): the deadline is pushed while the resident colliders still belong to the map
-    // we just left, AND while the destination's own stream is visibly advancing. As a fixed load
-    // budget it was 0.01 s from firing on a fast machine (a Stormwind arrival used 5.99 s of the
-    // 6.00), and on a slower one it fired mid-stream — gravity on, the city's collider still in
-    // the build queue, and the body fell to the canyon under the Valley of Heroes with the cover
-    // still up. Only a stream that has made NO progress for the whole budget — missing data, dead
-    // IO — can time out now, which is the case the backstop was always for.
+    // The release needs scene and colliders, never ground contact. The timeout is a stall budget:
+    // the deadline is pushed while the resident world is still the map we left and while the
+    // stream advances, so only a stream with no progress for the whole budget times out.
     let now = time.elapsed_secs();
     if p.presentable() && !player.world_stale && focus_matches {
         player.end_settle(true, now);
@@ -205,10 +144,8 @@ pub(super) fn release_post_snap_hold(
     } else if now >= player.settle_deadline {
         player.end_settle(false, now);
     }
-    // **Pay the worldport ack the moment the hold ends** (decision 1340) — on either end, the
-    // resident release or the stall timeout (a dead stream must still complete the transfer, or
-    // the server holds us out-of-world until logout). This is the real client's post-load `0xDC`,
-    // re-expressed: its blocking load's "done" is our release.
+    // The worldport ack, the reference's post-load `0xDC`, goes at either end of the hold: the
+    // server keeps an unacked transfer out of world until logout.
     if !player.settling && player.owes_worldport_ack {
         if let Some(net) = net_cmds.as_deref() {
             player.owes_worldport_ack = false;
@@ -224,18 +161,15 @@ mod tests {
 
     use super::*;
 
-    /// The tile under `Player::default()`'s position — what the streamer would publish as
-    /// `focus_tile` when its focus and the avatar agree (the ordinary, correctly-ordered frame).
+    /// The tile under `Player::default()`: the `focus_tile` when focus and avatar agree.
     fn own_tile() -> (i32, i32) {
         let wow = benilla_assets::coords::bevy_to_wow(Player::default().pos);
         let (tx, ty) = benilla_formats::world_to_tile(wow[0], wow[1]);
         (tx as i32, ty as i32)
     }
 
-    /// A test app with the release system registered (a registered system keeps its `Local`
-    /// baseline across frames, which `run_system_once` would reset) and a hand-driven clock.
-    /// The published progress names the avatar's own tile — each test then describes residency
-    /// facts that are at least *about* the right place (the mismatch test overrides it).
+    /// The release system registered, so its `Local` baseline survives frames (`run_system_once`
+    /// would reset it), a hand-driven clock, and progress about the avatar's own tile.
     fn app() -> App {
         let mut app = App::new();
         app.insert_resource(Time::<()>::default())
@@ -265,13 +199,6 @@ mod tests {
         app.world().resource::<Player>().settling
     }
 
-    /// **A cinematic puts the body on the settle hold, once.** The live defect this pins: with the
-    /// stream following the flying camera, the tiles under a standing body unload and it falls
-    /// through the world — measured on the probe at `.debug play cinematic 41`, z=59.4 to z=-62 in
-    /// four seconds, with the server yanking it back and no movement packet sent again.
-    ///
-    /// `world_stale` rides along because without it the stall backstop expires the moment the
-    /// camera stops streaming new ground, and gravity comes back partway through the shot.
     #[test]
     fn a_flying_cinematic_holds_the_body_and_marks_its_world_stale() {
         let mut app = App::new();
@@ -297,11 +224,8 @@ mod tests {
         );
     }
 
-    /// The other half of the same rule: **nothing here ever ends a hold**, and nothing re-arms one.
-    /// The release is the world's (decision 0737), and a shot whose camera stays on the body's own
-    /// tile makes that tile resident — so the release ends the hold correctly, and a per-frame
-    /// re-arm would fight it and leave `settling` flickering under the two systems that read it
-    /// (the loading screen's clear gate and the zone-channel walk).
+    /// A re-arm would flicker `settling` under the loading screen's clear gate and the zone-channel
+    /// walk, which both read it.
     #[test]
     fn the_hold_is_armed_on_the_edge_and_never_re_armed() {
         let mut app = App::new();
@@ -315,7 +239,7 @@ mod tests {
         app.update();
         assert!(app.world().resource::<Player>().settling);
 
-        // The world releases the hold (the camera's tile IS this body's), still mid-cinematic.
+        // The world ends the hold mid-cinematic, the camera's tile being the body's.
         app.world_mut().resource_mut::<Player>().settling = false;
         app.world_mut().resource_mut::<Player>().world_stale = false;
         app.update();
@@ -330,7 +254,6 @@ mod tests {
         );
     }
 
-    /// No cinematic, no hold — the ordinary frame is untouched.
     #[test]
     fn an_ordinary_frame_arms_nothing() {
         let mut app = App::new();
@@ -347,16 +270,11 @@ mod tests {
         assert!(!p.world_stale);
     }
 
-    /// B263 (decision 1303): a stream that keeps arriving keeps the hold, however long it takes.
-    /// The old fixed load budget released gravity at 6 s into a live Stormwind arrival — measured
-    /// 0.01 s from firing even on a fast machine — and the body fell through the not-yet-collided
-    /// city to the canyon under the Valley of Heroes, impact heard under the loading screen.
     #[test]
     fn a_slow_but_advancing_stream_never_times_out() {
         let mut app = app();
         app.world_mut().resource_mut::<Player>().world_stale = false;
-        // 5× the budget of wall-clock, with some counter moving every frame — a slow machine
-        // streaming a big city, five times slower than the budget ever allowed for.
+        // Five budgets of wall clock, with a counter moving every frame.
         for i in 0..(5.0 * SETTLE_TIMEOUT) as usize {
             step(&mut app, 1.0, |p| {
                 p.total = 2000;
@@ -371,14 +289,11 @@ mod tests {
         }
     }
 
-    /// The backstop's one remaining target: a stream that makes NO progress for the whole budget
-    /// (missing data, dead IO) still releases, so a broken world can never hold the screen forever.
     #[test]
     fn a_genuinely_stalled_stream_still_times_out() {
         let mut app = app();
         app.world_mut().resource_mut::<Player>().world_stale = false;
-        // Frozen counters, scene never presentable. First frame baselines the Local (counts as
-        // change), then the budget runs undisturbed.
+        // Frozen counters: the first frame baselines the `Local` (a change), then the budget runs.
         for _ in 0..=(SETTLE_TIMEOUT + 2.0) as usize {
             step(&mut app, 1.0, |p| {
                 p.total = 2000;
@@ -393,14 +308,11 @@ mod tests {
         );
     }
 
-    /// 0710's fail-closed law is untouched: while the resident world is still the departed map's,
-    /// frozen counters push the deadline rather than spending it.
     #[test]
     fn a_stale_world_pushes_the_deadline_before_the_stall_budget_starts() {
         let mut app = app();
         app.world_mut().resource_mut::<Player>().world_stale = true;
-        // Twice the budget of stale, frozen frames: no release (focus_resident stays false so
-        // nothing clears the stale flag).
+        // Two budgets of stale, frozen frames; `focus_resident` stays false, so stale stays set.
         for _ in 0..(2.0 * SETTLE_TIMEOUT) as usize {
             step(&mut app, 1.0, |p| {
                 p.total = 0;
@@ -409,7 +321,7 @@ mod tests {
             });
             assert!(settling(&mut app), "released over the departed map's floor");
         }
-        // The destination becomes resident and the stream then stalls: the budget starts HERE.
+        // The destination becomes resident, then stalls: the budget starts here.
         app.world_mut().resource_mut::<Player>().world_stale = false;
         for _ in 0..=(SETTLE_TIMEOUT + 2.0) as usize {
             step(&mut app, 1.0, |p| {
@@ -426,8 +338,6 @@ mod tests {
         );
     }
 
-    /// The ordinary end: scene presentable and colliders quiet releases at once — even on the very
-    /// frame the last counter moved, so residency is never delayed by its own arrival.
     #[test]
     fn residency_releases_on_the_frame_it_lands() {
         let mut app = app();
@@ -447,11 +357,7 @@ mod tests {
         assert!(!settling(&mut app), "presentable world, hold still on");
     }
 
-    /// Decision 1498: geometry that has SPAWNED but not yet baked is a hole in the world exactly
-    /// like an unattached collider, so it holds the post-snap freeze too. The retained pass took
-    /// the static world off the entity path (1429), and from then on "the placement spawned" and
-    /// "the building is on screen" stopped being the same fact — the hold, like the reveal, keys
-    /// on the second.
+    /// Spawned but unbaked geometry is a hole like an unattached collider, so it holds the settle.
     #[test]
     fn an_unbaked_region_holds_the_settle() {
         let mut app = app();
@@ -468,17 +374,12 @@ mod tests {
         assert!(!settling(&mut app), "baked — the world is really there");
     }
 
-    /// B263 round 3 (decision 1336): residency published for ANOTHER tile never releases the hold
-    /// and never clears the stale flag — the live defect was the focus publish racing the teleport
-    /// snap, so on the snap frame the streamer described the DEPARTURE city as fully resident and
-    /// the hold released into free fall at the destination. The facts now name their tile; facts
-    /// about somewhere else are not facts about the ground under this body.
+    /// On a teleport's snap frame the focus can still describe the departure tile as resident.
     #[test]
     fn residency_about_another_tile_neither_releases_nor_clears_stale() {
         let mut app = app();
         app.world_mut().resource_mut::<Player>().world_stale = true;
-        // A fully-resident, quiet world — but described for a tile the avatar is not standing on
-        // (the departure side of a same-map teleport, one frame stale).
+        // A resident, quiet world described for a tile the avatar is not on.
         let elsewhere = {
             let (tx, ty) = own_tile();
             Some((tx + 8, ty))
@@ -503,10 +404,7 @@ mod tests {
         assert!(!settling(&mut app), "matching residency must still release");
     }
 
-    /// Decision 1340: the arrival debts — the deferred worldport ack and the near-teleport
-    /// position report — are paid on the frame the hold ends, and exactly once. The ack is the
-    /// real client's post-load `0xDC`, so it must ride the release, never the snap — and go
-    /// out exactly once.
+    /// The ack is the reference's post-load `0xDC`, so it rides the release, never the snap.
     #[test]
     fn the_resident_release_pays_the_worldport_ack_once() {
         let mut app = app();
@@ -546,9 +444,7 @@ mod tests {
         assert!(rx.try_recv().is_err(), "the ack was paid twice");
     }
 
-    /// The stall timeout pays the ack too: a dead stream must still complete the transfer —
-    /// vmangos keeps an unacked far teleport out-of-world (dropping every packet) until logout,
-    /// so a release with no ack would strand the session, silently.
+    /// vmangos keeps an unacked far teleport out of world, dropping every packet, until logout.
     #[test]
     fn a_timeout_release_still_pays_the_ack() {
         let mut app = app();
diff --git a/crates/benilla-app/src/quest_markers/mod.rs b/crates/benilla-app/src/quest_markers/mod.rs
index 6f73ac9b..3623e672 100644
--- a/crates/benilla-app/src/quest_markers/mod.rs
+++ b/crates/benilla-app/src/quest_markers/mod.rs
@@ -1,86 +1,25 @@
-//! Overhead questgiver markers — the client's own `Interface\Buttons\TalkToMe*` M2s floating
-//! above NPC heads: gold `!` (quest available), gold `?` (turn-in ready), grey `!`/`?` and the
-//! light-blue `?` per the status map.
+//! Overhead questgiver markers: the reference's `Interface\Buttons\TalkToMe*` M2s over NPC heads,
+//! gold `!` for a quest available, gold `?` for a turn-in, grey `!` and `?`, and the light-blue
+//! `?`. This module renders them; [`query`] decides when to ask, and the answers land in
+//! [`QuestGiver`].
 //!
-//! The data plane is the era wire: every visible creature flagged `UNIT_NPC_FLAG_QUESTGIVER`
-//! gets one `CMSG_QUESTGIVER_STATUS_QUERY` — the server only ever *answers* queries (vmangos
-//! `QuestHandler.cpp:36-77`), never pushes, so every refresh point is the client's own to trigger,
-//! and a status that is never re-asked for is a marker frozen at first sight. The re-ask law —
-//! the reference's self-player descriptor **field watch**, and which of it we implement — is its
-//! 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.
+//! - Attach (`0x6074c0`): a child of the unit's body M2 at attachment 18, or 29
+//!   (`PlayerNameMounted`) when a mount model exists and the body authors it ([`overhead_slot`]).
+//!   With neither, the marker is never parented and so invisible. The reference re-runs the attach
+//!   from the `UNIT_FIELD_MOUNTDISPLAYID` watch (`0x5ffa50`), so a mount moves the slot.
+//! - Scale (`0x607570`): `1/L`, `L = ‖row0‖` of the attach point's world matrix, computed once at
+//!   attach into the marker's base matrix (`marker+0xbc`); not distance-based, no clamp. The
+//!   compose is `marker+0xfc = marker+0xbc × parentAttachMatrix` (`0x71439b`), so `1/L` cancels the
+//!   whole attach basis, model scale included. [`bake_seat_scale`] has the reference's race.
+//! - Animation (`0x6076c0`): the marker's own looping bob, anim 0 at the attach point (WoW z 0 to
+//!   −0.089), anim 190 raised (+0.517 to +0.427) while the unit has a live overhead name
+//!   (`unit+0xc7c`, via `0x6c7950`), clear of the text.
 //!
-//! 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
-//!   slot ⇒ the marker is created but never parented — invisible; we render nothing.
-//!
-//!   **That pick is LIVE.** `0x6074c0` is a call site of `0x5ffa50`, the
-//!   `UNIT_FIELD_MOUNTDISPLAYID` field-watch handler, so the reference re-runs the whole attach —
-//!   slot included — every time a unit mounts or dismounts. Our seat is *parented* rather than
-//!   read per frame, so re-picking means rebuilding the instance: [`sync_markers`] compares the
-//!   slot the seat was built at against the live pick on every pass (decision 1871).
-//! - **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** (`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
-//!   ogre get the same-sized `!`" — was unconditional and **is not**. `0x607570` reads the parent's
-//!   `model+0xbc` **as it stands at attach**, and the reference has legs where it has not been
-//!   stamped yet, each leaving the ctor identity ⇒ **no counter-scale at all**:
-//!
-//!   | ordering at attach | `L` | `marker+0xbc` | final world scale at `s = 3` |
-//!   |---|---|---|---|
-//!   | parent already placed (**case B**) | `3.0` | `diag(1/3)` | **1.0 — constant** |
-//!   | parent still ctor identity (**case A**) | `≈1.0` | identity (skip) | **3.0 — proportional** |
-//!
-//!   Case A fires when `SMSG_QUESTGIVER_STATUS` lands while the body model is still streaming (the
-//!   query goes out at object-create, in the same breath as the load starts, so it is a race), and
-//!   *structurally* for a mounted questgiver whose mount M2 is still resident-pending (`0x6075ac`
-//!   tests the MOUNT model too, which `0x6074c0` does not). Nothing re-runs the bake afterwards, so
-//!   case A is permanent for that unit. Both are invisible at `s = 1`, which is why this went
-//!   unnoticed — it is visible only on a scaled creature, which is exactly where B301 came from.
-//!
-//!   **benilla is case B by construction**: [`bake_seat_scale`] deliberately waits for propagation
-//!   to produce a settled joint matrix. **That is the right leg, and it is settled by observation,
-//!   not by argument** — the director ran the A/B against the reference and 1.12's `?` looks the
-//!   same as ours (decision 1548, closing 1541's open question). B301 is `not-a-bug`: a
-//!   gnome-sized `?` over a building-sized NPC is what the real client shows too.
-//!
-//!   So do **not** "fix" this by dropping the counter-scale. The report is real, the case-A leg is
-//!   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`). 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**
-//!   normally, anim **190** while the unit has a live overhead-name object (`unit+0xc7c` via
-//!   `0x6c7950`). The two bands hold the same 3-key bob SHAPE at different heights: anim 0 at the
-//!   attach point (WoW z 0 → −0.089), anim 190 raised (+0.517 → +0.427) — the authored push-up
-//!   that lifts the marker clear of the name text (m2bones key-value probe, all five models; an
-//!   earlier count-only probe recorded them as "the same bob" — falsified by the director's
-//!   reference eye, decision record with this change).
-//!
-//! benilla's translation (m2bones-probed: every marker M2 is ONE bone with a 3-key translation
-//! bob): a **seat** entity parented under the unit's overhead joint (18 or 29 — the held-items
-//! rail) carries the one-time `1/L` counter-scale; the `!` models (plain bone) animate through
-//! the doodad rail
-//! ([`benilla_world::doodad_anim::spawn_anim_host`] — skinned twin + the one-time sequence-0 arm); the `?`
-//! models (cylindrical-billboard bone) render as [`BillboardCard`]s under the identity root —
-//! cards write ABSOLUTE world transforms, so they can't sit under the moving seat; instead
-//! [`re_seat_cards`] re-seats them from the seat's world placement each frame (PostUpdate, the
-//! same-frame propagated pose), and the card's own
-//! armed [`seq_translation`](BillboardCard::with_seq_translation) loop plays the bob. Markers are
-//! few and player-adjacent, so the anim host runs ungated (no draw-gate `DoodadAnimHost`).
-//! [`pose_markers`] swaps every marker between the low and raised bob as the unit's overhead
-//! elements toggle (the floating name [`Nameplates::shows`] OR a live V-plate — our `unit+0xc7c`;
-//! the plate leg is a director-pinned deviation, rationale on [`pose_markers`], 2274/2275):
-//! cards re-arm the matching loop, hosts switch the playing clip.
+//! Every marker M2 is one bone with a three-key translation bob. A seat entity under the unit's
+//! overhead joint carries the `1/L`. The `!` models (a plain bone) animate through the doodad rail
+//! ([`benilla_world::doodad_anim::spawn_anim_host`]), ungated, since markers are few. The `?`
+//! models (a cylindrical billboard bone) are [`BillboardCard`]s under the identity root, which
+//! [`re_seat_cards`] re-seats from the seat each frame, their bob played by the card's own loop.
 
 mod query;
 
@@ -105,13 +44,11 @@ use bevy::mesh::MeshTag;
 
 use crate::entities::overhead_slot;
 
-/// The marker anim ids the client arms (`0x6076c0`): the low bob, and the raised bob played while
-/// the unit shows an overhead name (`unit+0xc7c` live — [`Nameplates::shows`] here).
+/// The bobs `0x6076c0` arms: low, and raised while the unit shows a name ([`Nameplates::shows`]).
 const ANIM_MARKER_LOW: u16 = 0;
 const ANIM_MARKER_RAISED: u16 = 190;
 
-/// The billboard bone's translation loop for `anim_id`, if authored. The marker models are
-/// single-bone, so every card of one marker shares the bone's loop.
+/// The billboard bone's translation loop for `anim_id`; the one bone's loop serves every card.
 fn seq_loop(info: &BillboardInfo, anim_id: u16) -> Option<BoneScaleAnim> {
     info.seq_translations
         .iter()
@@ -119,14 +56,11 @@ 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 (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
-/// packet — the flight-master green (`TalkToMeGreen`, table index 4) now feeds [`sync_markers`]
-/// from [`crate::ui_taxi::FlightMasterStatus`]; the rest stay out of scope, same as the client.)
+/// The marker M2 per dialog status: the reference's file table `0xc4d9d8` through the status map
+/// `0x80c454` = `{0,3,0,2,7,1,6,6}`, its `.mdx` names loaded as `.m2`. The statuses are
+/// UNAVAILABLE 1, INCOMPLETE 3, REWARD_REP 4, AVAILABLE 5, REWARD_OLD 6 and REWARD2 7; NONE 0 and
+/// CHAT 2 draw nothing. File index 4, the green `!`, comes from the flight-master status instead,
+/// and index 5, the blue `!`, is unreachable in 1.12.1.
 fn marker_model(status: u32) -> Option<&'static str> {
     match status {
         1 => Some("Interface\\Buttons\\TalkToMeGrey.m2"),
@@ -138,52 +72,42 @@ fn marker_model(status: u32) -> Option<&'static str> {
     }
 }
 
-/// One live marker: the root entity (billboard-card children live here) and which model it shows —
-/// a status change swaps the whole thing (the client's model-swap `0x607480`).
+/// One live marker's root and model; a status change swaps the whole instance (`0x607480`).
 struct MarkerInst {
     root: Entity,
     path: &'static str,
 }
 
-/// The marker root: the lifecycle handle. Stays at the WORLD origin (identity) — billboard cards
-/// under it write absolute world transforms. The attach seat (under the UNIT's joint) is tracked
-/// here so a swap/prune can despawn it too.
+/// The marker root, at the world origin because its billboard cards write absolute transforms.
 #[derive(Component)]
 struct QuestMarkerRoot {
     npc: u64,
     handle: Handle<M2Model>,
-    /// The seat under the unit's overhead joint, once built. Lives OUTSIDE this root's hierarchy —
-    /// [`sync_markers`] despawns it explicitly (guarded: a despawned unit already cascaded it).
+    /// The seat under the unit's overhead joint, once built; outside this root's hierarchy.
     seat: Option<Entity>,
-    /// The overhead slot ([`overhead_slot`]) the live [`Self::seat`] was parented at — `None`
-    /// until it is built. A parent link bakes the slot in, so this is what [`sync_markers`]
-    /// watches against the live pick to catch a mount or dismount moving it (decision 1871).
+    /// The overhead slot [`Self::seat`] was parented at, which [`sync_markers`] compares against
+    /// the live pick to catch a mount or dismount.
     slot: Option<u16>,
-    /// The unit's body model resolved but authors NEITHER overhead attachment: the client's
-    /// marker is created but never parented — invisible. Latched so we stop retrying.
+    /// The body model authors neither overhead attachment: never parented, invisible. Latched.
     no_anchor: bool,
-    /// The armed pose: `Some(true)` = the raised (anim 190) bob, `Some(false)` = the low (anim 0)
-    /// bob, `None` = not yet posed (fresh build) — [`pose_markers`] arms on the first pass and
-    /// re-arms on every name-visibility flip.
+    /// The armed bob: raised (anim 190), low (anim 0), or `None`, not yet posed.
     raised: Option<bool>,
 }
 
-/// The attach seat: a child of the unit's overhead joint (18/29) at the attachment offset.
-/// Carries the marker joints + plain submeshes as children; [`bake_seat_scale`] bakes the `1/L`
-/// counter-scale into its local transform (the client's `0x607570` base matrix).
+/// The attach seat under the unit's overhead joint, at the attachment offset. It carries the
+/// marker's joints and plain meshes, and [`bake_seat_scale`] bakes the `1/L` into its transform.
 #[derive(Component)]
 struct MarkerSeat {
-    /// The one-time scale latch (the client computes it once at attach, not per frame).
+    /// Latched once baked: the reference computes the scale once, at attach.
     scaled: bool,
 }
 
-/// A marker billboard card's model-local pivot — [`BillboardCard::re_place`]'s second argument
-/// each frame.
+/// A billboard card's model-local pivot, [`BillboardCard::re_place`]'s second argument.
 #[derive(Component)]
 struct MarkerCardPivot(Vec3);
 
-/// Despawn one marker instance: the root (cards cascade) and its seat — which lives under the
-/// UNIT's joint, so it needs the explicit, guarded kill (a despawned unit already cascaded it).
+/// Despawns the root (its cards cascade) and the seat, which lives under the unit's joint; a
+/// despawned unit has already taken the seat with it.
 fn despawn_marker(commands: &mut Commands, roots: &Query<&QuestMarkerRoot>, root: Entity) {
     if let Some(seat) = roots.get(root).ok().and_then(|m| m.seat) {
         if let Ok(mut e) = commands.get_entity(seat) {
@@ -193,13 +117,13 @@ fn despawn_marker(commands: &mut Commands, roots: &Query<&QuestMarkerRoot>, root
     commands.entity(root).despawn();
 }
 
-/// 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`], 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
-/// (a named deviation, invisible in practice: a flight master carrying an active quest marker).
+/// Spawns, swaps and despawns marker roots to match two sources for the one overhead slot: the
+/// questgiver status, and the flight master's green `!` while its node is unknown
+/// ([`crate::ui_taxi::FlightMasterStatus`], `0x607480` with file index 4).
+///
+/// Deviation: a quest marker outranks the green, where the reference's two handlers race
+/// last-write-wins on the slot, because a fixed order is deterministic; the two meet only on a
+/// flight master with a live quest marker, invisible in practice.
 fn sync_markers(
     mut commands: Commands,
     quest: Res<QuestGiver>,
@@ -209,28 +133,16 @@ fn sync_markers(
     assets: Option<Res<WorldAssets>>,
     roots: Query<&QuestMarkerRoot>,
     seats: Query<(), With<MarkerSeat>>,
-    // The live overhead-slot pick's two inputs, read per pass off the unit (a handful of markers
-    // exist at once, so this is a few map lookups a frame).
     anchors: Query<&BoneAttach>,
     mounts: Query<(), With<crate::entities::mount::MountChild>>,
     mut live: Local<HashMap<u64, MarkerInst>>,
 ) {
     if assets.is_none() {
-        return; // no client data — nothing could build anyway
+        return; // no client data: nothing could build
     }
-    // Rebuild the whole instance whenever the built seat has stopped describing the unit — all
-    // or nothing, because a partial rebuild would duplicate the root's billboard cards. The next
-    // pass then re-attaches under the joints and the slot that are true now. Two triggers:
-    //
-    // - **the seat entity is gone** — the unit's visual was rebuilt out from under it, taking the
-    //   joint tree the seat lived under with it (a redress, a display change);
-    // - **the overhead slot has moved** (18 ↔ 29) — the unit mounted or dismounted since the
-    //   build. Nothing else would notice, and this is the trigger benilla was missing (1871): a
-    //   mount transition deliberately leaves the rider's visual intact — `reseat_mounts`
-    //   RE-PARENTS the rig's joint anchors onto the seat frame instead of despawning them — so
-    //   the marker's seat survives the transition, riding the right bone at the WRONG slot,
-    //   permanently. The reference re-runs the whole attach here: `0x6074c0` is a call site of
-    //   `0x5ffa50`, the `UNIT_FIELD_MOUNTDISPLAYID` watch handler.
+    // Rebuild the whole instance, never part of it (that duplicates the root's cards), when the
+    // seat is gone with a rebuilt visual or the slot moved on a mount or dismount, which keeps the
+    // seat. The reference re-runs the attach from the mount watch (`0x5ffa50` calls `0x6074c0`).
     let rebuild: Vec<u64> =
         live.iter()
             .filter(|(&npc, inst)| {
@@ -250,7 +162,6 @@ fn sync_markers(
             despawn_marker(&mut commands, &roots, old.root);
         }
     }
-    // The desired marker per guid, composed from both sources (still-streamed units only).
     let mut desired_by_npc: HashMap<u64, &'static str> = HashMap::new();
     for (&npc, &status) in quest.statuses() {
         if index.0.contains_key(&npc) {
@@ -305,27 +216,18 @@ fn sync_markers(
     }
 }
 
-/// [`sync_markers`]' rebuild test for one live instance, split out because each of its three legs
-/// has a trap in it:
-///
-/// - **not built yet** (`seat: None`) is never stale — [`build_markers`] owns that instance, and
-///   calling it stale would despawn a root that is still waiting on its M2.
-/// - **`seat_alive == false`** is stale: the unit's visual was rebuilt out from under the seat,
-///   taking the joint tree it lived under with it.
-/// - **`want` differs from the slot the seat was built at** is stale: the unit mounted or
-///   dismounted. `want` is [`overhead_slot`]'s live pick, and `None` means *unreadable this pass*
-///   (the unit is still streaming, or gone) — which must NOT count as a move, or a marker would
-///   rebuild its whole instance every frame its unit's attachment table is out of reach. A unit
-///   that really is gone is pruned below on its own terms.
+/// [`sync_markers`]' rebuild test for one instance. Unbuilt (`seat: None`) is never stale:
+/// [`build_markers`] owns it, and a rebuild would despawn a root still waiting on its M2. A dead
+/// seat is stale, and so is a `want` that differs from the built slot; but a `None` want is
+/// unreadable this pass (the unit streaming or gone), not a move, or the instance would rebuild
+/// every frame its unit's attachment table is out of reach.
 fn seat_is_stale(marker: &QuestMarkerRoot, seat_alive: bool, want: Option<u16>) -> bool {
     marker.seat.is_some() && (!seat_alive || (want.is_some() && want != marker.slot))
 }
 
-/// Build a marker once its M2 AND its unit's joint set ([`BoneAttach`]) have both landed: the seat
-/// under the slot-18 joint, the anim host + skinned plain submeshes on it (the `!` bob), and the
-/// billboard cards under the identity root with their bob loop armed (the `?`). Retries silently
-/// while either half still loads; latches [`QuestMarkerRoot::no_anchor`] when the body model has
-/// no overhead point (the client's marker never parents — invisible).
+/// Builds a marker once its M2 and its unit's [`BoneAttach`] have both loaded: the seat under the
+/// overhead joint with the `!` models' plain meshes, and the `?` models' cards under the root.
+/// Latches [`QuestMarkerRoot::no_anchor`] when the body has no overhead point.
 fn build_markers(
     mut commands: Commands,
     mut roots: Query<(Entity, &mut QuestMarkerRoot)>,
@@ -336,8 +238,7 @@ fn build_markers(
     mut palettes: ResMut<benilla_world::rig_palette::RigPalettes>,
     index: Res<GuidIndex>,
     anchors: Query<&BoneAttach>,
-    // The unit's pose buffer: the overhead joint the marker parents under spawns on first
-    // demand (`RigPose::anchor_for`, decision 1355).
+    // The overhead joint spawns on first demand (`RigPose::anchor_for`).
     mut poses: Query<&mut benilla_world::rig_anim::RigPose>,
     mounts: Query<(), With<crate::entities::mount::MountChild>>,
     time: Res<Time>,
@@ -349,12 +250,10 @@ fn build_markers(
         let Some(model) = m2s.get(&marker.handle) else {
             continue; // marker M2 still loading
         };
-        // The marker's render forms, built NOW (decision 0834): two tiny models per map, on the
-        // booth-lane exception — a marker popping a frame late over a questgiver would be a
-        // regression nothing here needs.
+        // Render forms built now, uncapped, like the booths': two tiny models, and a marker a
+        // frame late over its questgiver would be seen.
         forms.ensure_now_rigged(&marker.handle, &model.submeshes, &mut mesh_assets);
-        // The unit's joint set + attachment table — absent while its own model still loads (or
-        // forever on a boneless/model-less unit, which then simply never shows a marker).
+        // Absent while the unit's model loads, and for good on a unit without one.
         let Some((unit, anchor)) = index
             .0
             .get(&marker.npc)
@@ -362,10 +261,8 @@ fn build_markers(
         else {
             continue;
         };
-        // The overhead slot as it stands THIS pass — 29 while a mount model is attached and the
-        // body authors it, else 18 (`0x6074c0`'s own pick). It is recorded on the root below so
-        // `sync_markers` can rebuild the instance when a mount or dismount moves it. Neither slot
-        // ⇒ never parented ⇒ invisible, like the client.
+        // This pass's slot, `0x6074c0`'s pick: 29 while mounted if the body authors it, else 18.
+        // Neither: never parented, so invisible, as in the reference.
         let Some((slot, joint, offset)) =
             overhead_slot(anchor, mounts.contains(unit)).and_then(|slot| {
                 let &(bone, offset) = anchor.points.get(&slot)?;
@@ -382,10 +279,8 @@ fn build_markers(
             continue;
         };
 
-        // The seat: a child of the attach joint, so the marker rides the live bone with zero lag
-        // (the held-items rail). The `!` models' plain geometry animates through the doodad rail —
-        // the client's one-time load arm IS sequence 0 here (anim id 0, m2bones-verified, the same
-        // file-order-first clip). The all-billboard `?` models skip the host (nothing to skin).
+        // The seat rides the attach joint's live bone. The `!` models animate through the doodad
+        // rail (sequence 0, anim 0); the all-billboard `?` models have nothing to skin.
         let seat_tf = Transform::from_translation(offset);
         let host = model
             .submeshes
@@ -393,12 +288,8 @@ fn build_markers(
             .any(|s| s.billboard.is_none())
             .then(|| benilla_world::doodad_anim::spawn_anim_host(&mut commands, model, seat_tf))
             .flatten();
-        // EAGER slot allocation — this lane has no draw gate to promote lazily (decision 0863
-        // made laziness the terrain-stream caller's policy, not the host's). A handful of
-        // markers exist at once, so eager is the right spend; slot 0 (table full, warned)
-        // falls back to the static mesh below exactly as before. `allocate_bones` — the
-        // collapsed shape (decision 1365): the world pass writes the rows off the host's
-        // `RigPose`, no joint list exists.
+        // Allocated eagerly: this lane has no draw gate to promote lazily. Slot 0 (table full)
+        // falls back to the static mesh below.
         let marker_slot = host.as_ref().map_or(0, |h| {
             benilla_world::rig_palette::RigSkin::allocate_bones(
                 &mut palettes,
@@ -423,22 +314,19 @@ fn build_markers(
             host.is_some()
         );
 
-        // The client arms the marker's animation at status receive — the cards' bob loop starts
-        // its cursor here (the same clock `face_billboards` samples).
+        // The reference arms the animation at status receive; the cards' loop starts here, on
+        // the clock `face_billboards` samples.
         let arm_ms = time.elapsed().as_millis() as u32;
         let built = forms.slices(&marker.handle);
         let (stat_forms, skin_forms) = (built.stat, built.skin.unwrap_or(&[]));
         for (pi, sub) in model.submeshes.iter().enumerate() {
-            // A floating marker is an ordinary world-lit batch: one steady material, batch
-            // order 0 (a `?` is a single 353-vert mesh, not a coplanar stack).
+            // An ordinary world-lit batch: one steady material, batch order 0 (a `?` is one
+            // 353-vertex mesh, not a coplanar stack).
             let Some(material) = mats.steady(sub, sub.texture.clone(), 0) else {
                 continue; // no shared light buffer yet
             };
             match &sub.billboard {
                 Some(info) => {
-                    // Cards write ABSOLUTE world transforms (`face_billboards`), so they live
-                    // under the identity root and `re_seat_cards` re-seats them from the seat's
-                    // world placement each frame; the armed loop plays the bob at the pivot.
                     let child = commands
                         .spawn((
                             Mesh3d(
@@ -458,10 +346,8 @@ fn build_markers(
                     commands.entity(root).add_child(child);
                 }
                 None => {
-                    // Plain geometry under the seat: the skinned twin bound to the host's palette
-                    // rig when the model animates (the `!` bob — decision 0720); the static mesh
-                    // otherwise (capture mode keeps every marker static, like the doodad rail),
-                    // including the palette-full fallback (slot 0).
+                    // Plain geometry under the seat: the skinned twin on the host's palette rig
+                    // when the model animates, else the static mesh (capture mode, a full palette).
                     let use_rig = marker_slot != 0;
                     let mesh = if use_rig {
                         skin_forms.get(pi).cloned().unwrap_or_default()
@@ -490,10 +376,8 @@ fn build_markers(
                 }
             }
         }
-        // Attach the pose buffer, plus the seat-frame cascade marker (decision 1365): the
-        // marker host root is a rig's `joints_root` living inside the UNIT's anchor subtree, so
-        // a patch walk that re-seats the overhead anchor must re-finalize the marker rig the
-        // same frame (`RigFrame` — the mount seat's law, `finalize_rig_worlds`).
+        // `RigFrame`: the host root is a rig inside the unit's anchor subtree, so re-seating the
+        // overhead anchor must re-finalize the marker rig the same frame (`finalize_rig_worlds`).
         if let Some(h) = host {
             commands
                 .entity(h.root)
@@ -505,17 +389,14 @@ fn build_markers(
     }
 }
 
-/// Swap each built marker between its LOW (anim 0) and RAISED (anim 190) bob as the unit's
-/// overhead elements toggle — the client's `0x6076c0` selector: anim 190 while the unit's name
-/// object (`unit+0xc7c`) is live, anim 0 otherwise. The 190 band is the authored raised loop
-/// (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 (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.
+/// Swaps each built marker between the low (anim 0) and raised (anim 190) bob, `0x6076c0`'s
+/// selector: raised while the unit's name object (`unit+0xc7c`) is live. The reference arms at
+/// attach and re-arms on the frame the name's shown state flips (an edge in `0x6c6e90`), never
+/// per frame.
+///
+/// Deviation: a live V-plate ([`VPlates`](crate::vplates::VPlates)) raises the marker too,
+/// because the reference's marker sits low behind the plate: it arms anim 0 under a plate, whose
+/// name suppression nulls the `desc+0x8` handle `0x6c7950` tests.
 #[allow(clippy::type_complexity)] // a Bevy system: each param is one resource, the app's convention
 fn pose_markers(
     plates: Res<Nameplates>,
@@ -523,16 +404,14 @@ fn pose_markers(
     index: Res<GuidIndex>,
     m2s: Res<Assets<M2Model>>,
     time: Res<Time>,
-    // `Children` is OPTIONAL: a `!` marker's plain meshes live under the SEAT, so its root has no
-    // children at all — a `&Children` query silently skipped every `!` marker (caught by the live
-    // run: two Northshire TalkToMe markers, zero pose lines).
+    // Optional: a `!` marker's meshes live under the seat, so its root may have no children.
     mut roots: Query<(&mut QuestMarkerRoot, Option<&Children>)>,
     mut cards: Query<&mut BillboardCard, With<MarkerCardPivot>>,
     mut players: Query<&mut AnimationPlayer>,
 ) {
     for (mut marker, children) in &mut roots {
         let Some(seat) = marker.seat else {
-            continue; // not built yet — first pose lands right after the build, same frame
+            continue; // not built yet; posed the frame it builds
         };
         let raised = index
             .0
@@ -542,7 +421,7 @@ fn pose_markers(
             continue;
         }
         let Some(model) = m2s.get(&marker.handle) else {
-            continue; // a swap mid-load — retry next frame
+            continue; // a swap mid-load: retry next frame
         };
         marker.raised = Some(raised);
         let anim_id = if raised {
@@ -556,8 +435,8 @@ fn pose_markers(
             if raised { "raised" } else { "low" }
         );
         let arm_ms = time.elapsed().as_millis() as u32;
-        // The `?` path: re-arm each card's loop with a fresh cursor (the client's arm law). A
-        // model without the raised band keeps its low bob rather than going static.
+        // `?`: re-arm each card's loop from a fresh cursor; a model without the raised band keeps
+        // its low bob rather than going still.
         let bob = model
             .submeshes
             .iter()
@@ -568,10 +447,8 @@ fn pose_markers(
                 card.arm_seq_translation(bob.clone(), arm_ms);
             }
         }
-        // The `!` path: switch the anim host's playing clip (the host, when one exists, IS the
-        // seat entity). `stop_all` first — bevy's `play` only ADDS to the active set, and two
-        // live clips BLEND (the director caught the `!` floating at half raise: anim 0 + 190
-        // averaged). No 190 clip ⇒ re-arm what's there.
+        // `!`: switch the clip on the anim host, which is the seat entity. `stop_all` first:
+        // `play` adds to the active set, and two live clips blend to a half raise.
         if let Ok(mut player) = players.get_mut(seat) {
             if let Some(clip) = model.animations.as_ref().and_then(|a| a.find(anim_id)) {
                 player.stop_all();
@@ -581,19 +458,14 @@ fn pose_markers(
     }
 }
 
-/// Bake each new seat's one-time counter-scale — the client's `0x607570` computes
-/// `L = |attach-bone basis|` once at attach and writes `diag(1/L)` into the marker's base matrix
-/// (the exact-`1.0` skip is the client's own identity guard). One-time per seat (latched).
+/// Bakes each new seat's `1/L` once, as `0x607570` does at attach, skipped at exactly 1.0 (the
+/// reference's identity guard).
 ///
-/// **This is the module doc's "case B" leg, and choosing it is a decision, not a transcription.**
-/// We retry until propagation yields a real joint matrix, so our `L` is always the *settled* world
-/// basis and the marker is always constant-size. The reference reads whatever `model+0xbc` happens
-/// to hold at attach, and on a still-streaming parent that is the ctor identity — no counter-scale,
-/// a marker proportional to the NPC, permanently. So the old note here ("the joint global being a
-/// frame old is immaterial — bone basis length doesn't animate") was true about the *bone* and
-/// wrong about the *risk*: what varies between the two legs is not the bone, it is whether the
-/// parent's world matrix exists yet. We keep the settled read — it is the reference's intent, the
-/// only leg that is deterministic, and (decision 1548) the leg the reference was observed on.
+/// Deviation: we wait for propagation to settle the joint matrix, so the marker is always constant
+/// size. The reference reads the parent's `model+0xbc` as it stands at attach, and a parent still
+/// at its constructor identity (a body still streaming, or a mount model pending, `0x6075ac`)
+/// leaves the marker unscaled and proportional to the NPC for good. We keep the settled read
+/// because it is deterministic and is what the reference shows over a placed NPC.
 fn bake_seat_scale(
     mut seats: Query<(&mut MarkerSeat, &ChildOf, &mut Transform)>,
     joints: Query<&GlobalTransform, Without<MarkerSeat>>,
@@ -607,9 +479,9 @@ fn bake_seat_scale(
         };
         let l = joint.affine().matrix3.x_axis.length();
         if l <= 0.0 {
-            continue; // propagation hasn't produced a real matrix yet — retry next frame
+            continue; // not propagated yet: retry next frame
         }
-        #[allow(clippy::float_cmp)] // the client's own exact-identity guard (fcomp 1.0)
+        #[allow(clippy::float_cmp)] // the reference's exact identity guard (fcomp 1.0)
         if l != 1.0 {
             tf.scale = Vec3::splat(1.0 / l);
         }
@@ -617,11 +489,8 @@ fn bake_seat_scale(
     }
 }
 
-/// Re-seat every billboard card from its seat's world placement (cards write absolute world
-/// transforms, so they can't be parented under the moving seat). Runs in PostUpdate after
-/// transform propagation and before [`benilla_world::billboard::BillboardPlace`] writes the card
-/// transforms — the card
-/// rides the SAME-frame posed seat, no trailing frame.
+/// Re-seats every card from its seat's world placement. Runs in PostUpdate after propagation and
+/// before [`benilla_world::billboard::BillboardPlace`], so a card rides the same frame's seat.
 fn re_seat_cards(
     seats: Query<&GlobalTransform, With<MarkerSeat>>,
     roots: Query<(&QuestMarkerRoot, &Children)>,
@@ -680,9 +549,8 @@ mod tests {
         }
     }
 
-    /// The rebuild test the mounted marker turns on (1871). A seat bakes its slot into a parent
-    /// link, and a mount transition leaves the rider's visual — and therefore the seat — intact,
-    /// so this comparison is the ONLY thing that can notice 18 ↔ 29 moving.
+    /// A mount keeps the rider's visual and so the seat, so only this comparison sees the slot
+    /// move between 18 and 29.
     #[test]
     fn a_seat_goes_stale_when_its_slot_moves_but_never_on_a_reading_it_could_not_take() {
         let built_at_18 = root(
@@ -704,16 +572,13 @@ mod tests {
             "the seat entity is gone — the visual was rebuilt out from under it"
         );
 
-        // Not built yet: `build_markers` owns the instance, and a rebuild would despawn a root
-        // still waiting on its M2. True even when the seat is reported dead — it has none.
+        // Unbuilt is never stale, even with the seat reported dead: it has none.
         let unbuilt = root(None, None);
         assert!(!seat_is_stale(&unbuilt, false, Some(29)));
         assert!(!seat_is_stale(&unbuilt, true, Some(29)));
     }
 
-    /// The seat's counter-scale is the client's `0x607570`: `1/L` from the attach joint's world
-    /// basis, baked ONCE at attach — a later joint rescale does not re-bake (the one-time latch),
-    /// and an exactly-1.0 basis skips the write (the client's own identity guard).
+    /// `0x607570`: `1/L` baked once, never re-baked on a later rescale, and skipped at 1.0.
     #[test]
     fn seat_counter_scale_bakes_once_from_the_attach_basis() {
         let mut app = App::new();
@@ -738,7 +603,7 @@ mod tests {
         let scale = |app: &App, e: Entity| app.world().entity(e).get::<Transform>().unwrap().scale;
         assert_eq!(scale(&app, seat), Vec3::splat(0.5), "1/L off the basis");
 
-        // Rescale the joint afterwards: the latch holds (the client computes once at attach).
+        // A later joint rescale: the latch holds.
         *app.world_mut()
             .entity_mut(joint)
             .get_mut::<GlobalTransform>()
@@ -746,7 +611,7 @@ mod tests {
         app.update();
         assert_eq!(scale(&app, seat), Vec3::splat(0.5), "one-time latch");
 
-        // An identity basis skips the write entirely (`fcomp 1.0`'s no-op leg) but still latches.
+        // An identity basis skips the write (`fcomp 1.0`) but still latches.
         let plain_joint = app
             .world_mut()
             .spawn((Transform::default(), GlobalTransform::IDENTITY))
diff --git a/crates/benilla-app/src/quest_markers/query.rs b/crates/benilla-app/src/quest_markers/query.rs
index 23e53bf8..8f9e7220 100644
--- a/crates/benilla-app/src/quest_markers/query.rs
+++ b/crates/benilla-app/src/quest_markers/query.rs
@@ -1,27 +1,14 @@
-//! The **query** half of the overhead markers: when to ask the server what an NPC's `!`/`?` should
-//! be — and, for a GameObject, when to ask a question whose answer is thrown away. The rendering
-//! half is [`super`].
+//! When to ask the server for a questgiver's `!` or `?`; [`super`] renders them. The server never
+//! pushes a status, it only answers the query (vmangos `QuestHandler.cpp:36-77`), so every refresh
+//! is the client's to trigger ([`query_statuses`]).
 //!
-//! **Both markers, not just the questgiver one** (decision 1918). The gold `!` and the flight
-//! master's green `!` are the same `unit+0xb2c`: `0x607480` installs whichever arrives into that
-//! one slot, `0x6073f0` zeroes it (along with `+0xcb8`), and `0x607380` — the per-unit path — tears
-//! it down once and then re-issues *both* queries, `0x182` on `UNIT_NPC_FLAGS` bit 1 and `0x1aa` on
-//! 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.
+//! The gold `!` and the flight master's green `!` share one slot, `unit+0xb2c`: `0x607480`
+//! installs whichever arrives, `0x6073f0` zeroes it with the status at `+0xcb8`, and the per-unit
+//! path `0x607380` tears it down, then re-issues `0x182` on `UNIT_NPC_FLAGS` bit 1 and `0x1aa` on
+//! bit 3. So one system owns both asks, and `ui_taxi` keeps only the answer.
 //!
-//! **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
-//! re-asked for is a marker frozen at whatever it was when we first saw the NPC. That made this a
-//! surprisingly deep fidelity question; the answer is decisions 0650 (the reference's trigger set,
-//! byte-enumerated) and 0654 (what benilla implements of it), and it lives on [`query_statuses`].
+//! A quest-flagged GameObject is asked about and never rendered: the answer handler `0x5dc9f0`
+//! resolves the guid with typemask 8 (`0x468460`), so its answer dies at `0x5dca2f`.
 
 use std::collections::HashMap;
 
@@ -34,104 +21,39 @@ use crate::target::cursor_mode::go_reaction;
 use crate::target::ring::Factions;
 use crate::ui_quest::QuestGiver;
 
-/// `UNIT_NPC_FLAGS` questgiver service bit (vanilla; `update_object.rs`'s accessor doc).
+/// `UNIT_NPC_FLAGS` questgiver service bit.
 const NPC_FLAG_QUESTGIVER: u32 = 0x2;
-/// `UNIT_NPC_FLAGS` flightmaster service bit — the other half of `0x607380`'s re-gate
-/// (`0x6073de shr eax,3; test al,1`), and the gate on the only live `0x1aa` sender there is.
+/// `UNIT_NPC_FLAGS` flightmaster service bit, the other half of `0x607380`'s re-gate (`0x6073de`)
+/// and the gate on the only `0x1aa` sender.
 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: `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
-/// shipped content as well as from the branch: across the genuine 2005-06 sniff corpus, all 122
-/// GameObjects the real client sent a status query for carry it, and none without it does, against
-/// a 79.2 % base rate.
+/// `GAMEOBJECT_FLAGS` bit 2, the sweep's whole GameObject gate (`0x5eb0ef`..`0x5eb0f5`: shift 2,
+/// so mask `0x4`, not the unit leg's `0x2`). The name is vmangos's (`GameObjectDefines.h:76`).
 const GO_FLAG_INTERACT_COND: u32 = 0x4;
 
-/// Ask the dialog status of every questgiver-flagged creature, and re-ask when the answer could
-/// have changed. The server only ever *answers* queries (vmangos `QuestHandler.cpp`), so every
-/// refresh point is the client's own to trigger — a status never re-asked for is a marker frozen
-/// at whatever it was when we first saw the NPC.
+/// Asks the dialog status of every questgiver-flagged creature, and re-asks when the answer could
+/// have changed. The reference sweeps every visible object (`0x5eb070 → 0x468380`) from its
+/// self-player field watches (`0x468070`) and four packet handlers.
 ///
-/// 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). 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).
+/// - Sweep: [`self_generation`] (the field watches) XOR [`QuestGiver::reask_epoch`] (the packet
+///   handlers); a changed generation is a sweep.
+/// - Per unit: asked from the create path and when its service bits (`0x60b490`, `0x60b4c5`) or
+///   reaction inputs (`0x606f0a`) move, our [`unit_ask_key`]. The entry goes when the guid leaves
+///   [`GuidIndex`], as the reference's cache at `unit+0xcb8` dies with the object.
+/// - GameObject: asked only on a sweep (`0x5eb159`, `0x5eb456`), gated on
+///   [`GO_FLAG_INTERACT_COND`] and a reaction toward us above 1 ([`go_reaction`], `0x5f7fd0`). Its
+///   constructor calls no sender, so there is no query at first sight, and with no status slot it
+///   is never torn down.
 ///
-/// **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;
-/// ours is [`self_generation`] (the descriptor half, recomputed only when our store actually
-/// changes) XOR [`QuestGiver::reask_epoch`] (the packet half, bumped from `net/apply`). A changed
-/// generation clears the whole asked set, which is the sweep.
+/// The light sweep's callback `0x5eb0a0` sends `0x182` for a questgiver and tears down
+/// (`0x5eb143`) any Hated or Hostile creature, questgiver or not, never on the flag alone. A flag
+/// change reaches `0x607380` through the `UNIT_NPC_FLAGS` watch (`0x60b420`), which tears down
+/// first (`0x607384`), then re-gates on reaction. The full sweep `0x5eb3c0` (your revive, your own
+/// reaction inputs) runs `0x607380` on every creature (`0x5eb3f0`): `full` below.
 ///
-/// **Per unit** — the reference queries one unit from its create/init path (`0x607380`) and when
-/// its own fields move: the questgiver bit (`0x60b490`), the flightmaster bit (`0x60b4c5`), and
-/// anything that could change its *reaction* to us (`0x606f0a`). Ours keys the asked set on
-/// [`unit_ask_key`], so any of those re-asks that one NPC; and the entry is dropped when the guid
-/// leaves [`GuidIndex`], which is the create-path query (the reference caches the answer *on* the
-/// unit at `unit+0xcb8`, so its cache dies with the object — ours is a map and needs the prune).
-///
-/// **Per GameObject — on a sweep, and ONLY on a sweep.** A quest-giving GameObject (a wanted
-/// poster, a suspicious barrel) is a questgiver on the wire exactly as a creature is: the same
-/// sweep callback tests typemask bit 5 and sends the same opcode for it (`0x5eb0a0` @ `0x5eb159`,
-/// and its sibling `0x5eb3f0` @ `0x5eb456`), gated on [`GO_FLAG_INTERACT_COND`] and on the
-/// GameObject's own reaction toward us being **> 1** ([`go_reaction`], the reference's `0x5f7fd0`).
-/// 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 (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
-/// all. That is a real, slightly surprising reference behaviour, and **a per-guid asked-set that
-/// queries on first sight is a deviation, not a fix** — hence the `swept` gate below rather than
-/// an [`unit_ask_key`] analogue. Nothing visible turns on any of this: the answer is dropped
-/// ([`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). `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:
-///
-/// | `UNIT_NPC_FLAGS & 0x2` | reaction **> 1** | reaction **≤ 1** |
-/// |---|---|---|
-/// | **set** | sends `0x182` (`0x5eb159`) | **tears down** (`0x5eb143`) |
-/// | **clear** | **nothing** (`0x5eb15e`) | **tears down** (`0x5eb143`) |
-///
-/// So the sweep tears down **iff the reaction is Hated/Hostile**, whether or not the unit is a
-/// questgiver — and it *never* tears down on the flag alone, which is what decision 0647 recorded
-/// and what this file did until now. A flag that goes off is torn down by the **`UNIT_NPC_FLAGS`
-/// field watch** instead (`0x6043c5` registers `0x604a20` → `0x60b420`, which XORs old against new
-/// and calls `0x607380` on *any* change to bit `0x2`) — and `0x607380`'s **first instruction after
-/// its prologue** is `0x607384 call 0x6073f0`, an unconditional teardown no branch can skip, with
-/// the reaction gate (`0x6073b2`) sitting *after* it and guarding only the re-issued queries. Ours
-/// is [`unit_ask_key`] moving, which is the same event observed from outside.
-///
-/// **The two sweeps therefore disagree, deliberately.** The light sweep (`0x5eb070`, 11 callers)
-/// runs the table above. The full re-query sweep (`0x5eb3c0`, 2 callers — **your revive**, and a
-/// change to your own record's reaction inputs) runs `0x5eb3f0`, whose creature arm is an
-/// unconditional `0x607380`: every creature's marker is torn down and then re-asked for. `full`
-/// below is that distinction.
-///
-/// There is no GameObject counterpart to any of it: a GameObject has no status to invalidate
-/// (`+0xcb8` is `0x9a8` bytes past the end of a `0x310`-byte `CGGameObject_C`), and all 8 of
-/// `0x6073f0`'s call sites are unit-side.
-///
-/// **Still not covered**, and why: the reference also sweeps when an *item* moves between
-/// containers (an `ITEM` typeid watch, `0x5d9375` — quest availability can depend on carried
-/// items). benilla does not stream item objects (`EntityKind` has no `Item`), so there is nothing
-/// to watch; the equipment and equipped-bag guids in our own descriptor *are* folded, which covers
-/// equipping, unequipping and swapping a bag but not moving a stack inside one. Per unit, the
-/// reference's reaction refresh also keys on charm/persuade/duel-team/`PLAYER_BYTES_3`; we key on
-/// the faction template, and catch a standing change through the reputation sweep instead.
+/// Not covered: the reference's `ITEM` watch (`0x5d9375`) also sweeps when an item moves between
+/// containers; with no item objects, only our equipment and bag guids are folded. Per unit, its
+/// reaction refresh also keys on charm, persuade, duel team and `PLAYER_BYTES_3`; ours on the
+/// faction template, a standing change coming through the reputation sweep.
 #[allow(clippy::type_complexity)] // a Bevy system: one param per resource
 pub(super) fn query_statuses(
     self_q: Query<Ref<ObjectStore>, With<SelfPlayer>>,
@@ -156,24 +78,16 @@ pub(super) fn query_statuses(
     let Some(store) = self_q.iter().next() else {
         return;
     };
-    // The descriptor half is only recomputed when our own store actually changed — it walks 20
-    // quest-log slots, 128 skill slots and 23 inventory slots, which has no business running every
-    // frame. The packet half (the epoch) is a plain counter, so it is always cheap to fold.
+    // The descriptor walk runs only when our store changed; the epoch is a plain counter.
     if store.is_changed() {
         state.fields = self_generation(&store.0);
     }
     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 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
-    // revive edge is a full one, and the folded alive/dead bit cannot tell them apart.
+    // The full sweep's triggers (`0x5eb3c0`): your revive, the `≤0 → >0` crossing (`0x6046f0`),
+    // and your own reaction inputs moving (`0x606e20`). Edges, since death is a light sweep.
     let alive = store.0.unit_health().unwrap_or(1) != 0;
-    // Compared only between two frames that both *saw* the field: our template arrives with the
-    // create block, and treating "absent → present" as a change would fire one spurious full sweep
-    // at every login.
+    // Compared only between frames that both saw the field, or the template's arrival at login
+    // would fire a full sweep.
     let my_faction = store.0.unit_faction_template();
     let full = (alive && state.was_dead)
         || (my_faction.is_some() && state.my_faction.is_some() && state.my_faction != my_faction);
@@ -181,40 +95,26 @@ pub(super) fn query_statuses(
     if my_faction.is_some() {
         state.my_faction = my_faction;
     }
-    // **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 (`0x5eb159`, `0x5eb456`) — and a full sweep is a sweep too, even
-    // when it arrives through an edge the generation does not carry.
+    // A sweep frame, the only time a GameObject is asked about.
     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
-    // its "already asked" mark and its cached status, so re-entering view re-asks from scratch.
-    // The map is NOT cleared by a sweep — it holds each unit's last ask key, and a sweep re-asking
-    // everyone must stay distinguishable from that unit's own key actually moving, because only
-    // the second is a `0x607380` and only a `0x607380` tears the marker down.
-    // …and it can only shrink on a frame the object index moved (a guid left the world): the
-    // two retains used to walk both maps every frame, the second through `ResMut` — which
-    // marked `QuestGiver` changed on every frame whether or not a status left.
+    // A guid that left the world drops its ask key and cached status. A sweep never clears the
+    // map: only a unit's own key moving is a `0x607380`. Pruned only when the index moved, as the
+    // `ResMut` retain marks `QuestGiver` changed.
     if index.is_changed() {
         state.asked.retain(|guid, _| index.0.contains_key(guid));
         quest.retain_statuses(|npc| index.0.contains_key(&npc));
     }
-    // On a frame that is not a sweep, a unit's verdict below is a function of its own
-    // descriptor and of the two reaction catalogs, and nothing else: with all three still, the
-    // arm is a no-op (same reaction → same teardown already done, same key → no `0x607380`), so
-    // the unit is not visited. A city's whole idle population used to take the reaction
-    // resolve and the ask-key insert every frame for it.
+    // Off a sweep, a unit's verdict depends only on its descriptor and the two reaction
+    // catalogs; with all three still it is a no-op, so the unit is skipped.
     let catalogs_moved =
         reputations.is_changed() || factions.as_ref().is_some_and(|f| f.is_changed());
     for (entity, guid, net, obj, fm) in &objects {
         if !swept && !full && !catalogs_moved && !obj.is_changed() {
             continue;
         }
-        // `0x6073f0` zeroes `+0xb2c` (the marker instance) and `+0xcb8` (the questgiver status)
-        // **together**, and the flight master's green `!` lives in that same `+0xb2c` — so every
-        // teardown below takes both. Only removed when there is something to remove: a `Commands`
-        // write per unit per frame would be a queue of no-ops.
+        // `0x6073f0` zeroes the marker (`+0xb2c`, the green `!` too) and the status (`+0xcb8`)
+        // together, so every teardown takes both.
         let tear_down = |quest: &mut QuestGiver, ecs: &mut Commands| {
             quest.clear_status(guid.0);
             if fm.is_some() {
@@ -223,15 +123,11 @@ pub(super) fn query_statuses(
             }
         };
         match net.kind {
-            // `0x5eb0a0` @ `0x5eb0d3`: `cmp eax,9; je` — typemask EXACTLY `OBJECT|UNIT`, a plain
-            // creature. A player is `0x19` and falls out of the sweep here, before any flag test.
+            // Typemask exactly `OBJECT|UNIT` (`0x5eb0d3`): a player, `0x19`, leaves the sweep here.
             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`) 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.
+                // The unit's reaction toward us (`0x6061e0`, this = the unit, at `0x5eb12a`), the
+                // direction `ring_reaction` resolves: `<= 1` is Hated or Hostile, and a missing
+                // input reads Neutral, so a cold catalog never blanks a marker.
                 let reaction = crate::target::ring_reaction(
                     factions.as_deref(),
                     &reputations,
@@ -239,40 +135,24 @@ pub(super) fn query_statuses(
                     Some(&store),
                 );
                 if reaction <= 1 {
-                    // The sweep's ONE teardown (`0x5eb143`), and it is convergent: it fires for a
-                    // hostile creature whether or not it is a questgiver. Dropping the ask key too
-                    // means the marker comes back through a `0x607380` when the reaction recovers.
+                    // The sweep's one teardown (`0x5eb143`), questgiver or not. Dropping the ask
+                    // key brings the marker back through a `0x607380` when the reaction recovers.
                     state.asked.remove(&guid.0);
                     tear_down(&mut quest, &mut ecs);
                     continue;
                 }
                 let key = unit_ask_key(&obj.0);
                 let key_moved = state.asked.insert(guid.0, key) != Some(key);
-                // **`0x607380` — teardown first, unconditionally, then re-gate.** Reached from this
-                // unit's own field watches (`UNIT_NPC_FLAGS` via `0x60b420`'s XOR, so *either*
-                // direction; the flightmaster bit; its reaction inputs), from its create/init
-                // hooks, and from the full sweep's callback. `0x607384 call 0x6073f0` is the first
-                // instruction after the prologue and no branch can skip it.
-                //
-                // This is where **B257** actually lives, and it used to hang off the wrong
-                // mechanism: an escort's giver drops `UNIT_NPC_FLAGS` in the same server tick as
-                // the quest-log write (vmangos `FollowerAI::StartFollow`, `ScriptedEscortAI`'s
-                // "disable npcflags"), and its cached AVAILABLE status — with its `!` — stayed
-                // frozen over the NPC for the whole escort. The flag is half of [`unit_ask_key`],
-                // so the drop moves the key, and the key moving is a `0x607380`.
+                // `0x607380`, from the unit's field watches, its create path and the full sweep:
+                // tear down first (`0x607384`), then re-gate. An escort giver's flag drop, with
+                // the quest-log write, moves the ask key and lands here.
                 let per_unit = key_moved || full;
                 if per_unit {
                     tear_down(&mut quest, &mut ecs);
                 }
-                // …and re-gate. Reaction is already `> 1` — the arm above returned otherwise —
-                // so what is left is the two service bits, and **they are not symmetric**:
-                //
-                // - `0x182` (questgiver) is issued by `0x607380` @`0x6073cd` on bit `0x2` **and**
-                //   inline by the light sweep's own callback (`0x5eb159`), so every sweep re-asks;
-                // - `0x1aa` (taxi node status) has exactly ONE live sender site image-wide —
-                //   `0x607380` @`0x6073e8` — so it is re-asked on this unit's own key moving and
-                //   on a full sweep, and **never** on a light one. `0x5eb0a0` does not test bit
-                //   `0x8` at all.
+                // The re-gate, the reaction being above 1. `0x182` goes out from `0x607380`
+                // (`0x6073cd`) and from the light sweep (`0x5eb159`), so every sweep re-asks;
+                // `0x1aa` has one sender, `0x607380` (`0x6073e8`), so never on a light sweep.
                 let flags = obj.0.unit_npc_flags();
                 if (per_unit || swept) && flags & NPC_FLAG_QUESTGIVER != 0 {
                     let _ = commands
@@ -285,16 +165,14 @@ pub(super) fn query_statuses(
                         .send(ClientCommand::TaxiNodeStatusQuery { guid: guid.0 });
                 }
             }
-            // `0x5eb0da shr ecx,5; test cl,1` — typemask bit 5, `TYPEMASK_GAMEOBJECT`. Sweep-only,
-            // no asked-set, no teardown: see this function's doc.
+            // `TYPEMASK_GAMEOBJECT` (`0x5eb0da`): sweep only, no ask key, no teardown.
             EntityKind::GameObject if swept => {
                 if obj.0.gameobject_flags() & GO_FLAG_INTERACT_COND == 0 {
                     continue;
                 }
-                // `0x5eb101 cmp eax,1; jle` — the GameObject's reaction toward us must be at least
-                // **2**. Not a friendliness test: Unfriendly(2) and Neutral(3) both pass, and a
-                // faction-less GameObject resolves Neutral. `None` = unresolvable (no catalog yet)
-                // and passes, the same "no opinion" rule the cursor's own gate uses.
+                // A reaction toward us above 1 (`0x5eb101`): Unfriendly and Neutral pass, a
+                // faction-less object reads Neutral, and `None` (no catalog yet) passes, as in the
+                // cursor's gate.
                 let reaction = go_reaction(
                     factions.as_deref(),
                     obj.0.gameobject_faction(),
@@ -312,23 +190,16 @@ pub(super) fn query_statuses(
     }
 }
 
-/// The per-unit ask key: re-ask that NPC whenever this moves. `UNIT_NPC_FLAGS` carries both service
-/// bits the reference watches — questgiver `0x2` (`0x60b490`) and flightmaster `0x8` (`0x60b4c5`) —
-/// and `UNIT_FIELD_FACTIONTEMPLATE` is the reaction input we can see (`0x606f0a`); a charm or a
-/// faction swap changes what the server will answer for a hostile giver.
+/// The per-unit ask key: `UNIT_NPC_FLAGS`, which carries both watched service bits, and the
+/// faction template, the reaction input we can see.
 fn unit_ask_key(fields: &benilla_protocol::ObjectFields) -> u64 {
     u64::from(fields.unit_npc_flags())
         | (u64::from(fields.unit_faction_template().unwrap_or(0)) << 32)
 }
 
-/// Fold every *self* descriptor field the reference watches into one value — a change to any of
-/// them sweeps every visible questgiver, because each is an input the server's `GetDialogStatus`
-/// reads. The reference registers one handler per field (`0x468070`); we hash the lot, which is
-/// the same thing observed from the outside. Recomputed only when our own store changes.
-///
-/// Level (`SatisfyQuestLevel`, the grey `!`), the quest log, money, every skill
-/// (`SatisfyQuestSkill`), `PLAYER_FLAGS`, health, and our equipment/bag guids — the last standing
-/// in for the reference's `ITEM` watch, as far as our object model can see it.
+/// Folds the self descriptor fields the reference watches, one handler each (`0x468070`), into one
+/// value: level, the quest log, money, every skill, `PLAYER_FLAGS`, alive or dead, and the
+/// equipment and bag guids in place of the reference's `ITEM` watch.
 fn self_generation(fields: &benilla_protocol::ObjectFields) -> u64 {
     const FNV_PRIME: u64 = 0x0000_0100_0000_01B3;
     let mut h = 0xcbf2_9ce4_8422_2325u64; // FNV offset
@@ -337,25 +208,9 @@ fn self_generation(fields: &benilla_protocol::ObjectFields) -> u64 {
         h = h.wrapping_mul(FNV_PRIME);
     };
     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. 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
-    // branch. Ordinary damage, heal and regen ticks fall through both and reach nothing — which is
-    // why the captures show no query bursts tracking combat (one carries 28 consecutive non-lethal
-    // packets, 70 → 2 HP, with zero bursts; the single packet crossing to 0 has the only burst in
-    // the stretch).
-    //
-    // 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. `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
-    // `0x1aa`), the GameObject arm the lighter. So the death edge sweeps (`0x5eb070`) and the
-    // **revive** edge sweeps too (`0x5eb3c0`), and one sweep per crossing is the reference's own
-    // behaviour rather than a deviation we were paying for. 0654, 1872.
+    // Health enters as the alive bit: the `UNIT_FIELD_HEALTH` watch (`0x6046f0`) sweeps only on a
+    // zero crossing, death to the light sweep (`0x604774`) and revive to the full one
+    // (`0x6047f0`); damage and regen ticks reach neither.
     fold(u64::from(fields.unit_health().unwrap_or(1) == 0));
     fold(u64::from(fields.player_flags()));
     fold(u64::from(fields.player_money().unwrap_or(0)));
@@ -366,8 +221,7 @@ fn self_generation(fields: &benilla_protocol::ObjectFields) -> u64 {
             }
         }
     }
-    // The reference watches the skill *value* half specifically (`edx=0x84c`), so the id + current
-    // value are what matter — a rank-up is the event, not a temporary bonus ticking.
+    // The reference watches the skill value word (`edx=0x84c`): a rank-up, not a bonus ticking.
     for slot in 0..benilla_protocol::messages::PLAYER_SKILL_SLOTS {
         if let Some(s) = fields.player_skill(slot) {
             if s.skill_id != 0 {
@@ -386,16 +240,14 @@ fn self_generation(fields: &benilla_protocol::ObjectFields) -> u64 {
 /// [`query_statuses`]'s memory across frames.
 #[derive(Default)]
 pub(super) struct QueryState {
-    /// The last folded [`self_generation`] — kept separately from `generation` so the expensive
-    /// descriptor walk can be skipped on frames where our own store didn't change.
+    /// The last [`self_generation`], kept so the walk runs only when our store changes.
     fields: u64,
     /// `fields` combined with the packet epoch; a change here is the sweep.
     generation: u64,
-    /// Which guids we've asked about, and the [`unit_ask_key`] we asked at. Pruned by object
-    /// lifetime only — never by a sweep, so "this unit's own key moved" stays a distinct event.
+    /// Each asked guid's [`unit_ask_key`]; pruned by object lifetime only, never by a sweep.
     asked: HashMap<u64, u64>,
-    /// Our own alive/dead and faction-template from last frame — the two edges that make a sweep a
-    /// **full** one. `None`/`false` initially, so the first frame in a world is never a full sweep.
+    /// Last frame's alive state and faction template, the two full-sweep edges; the first frame in
+    /// a world is never a full sweep.
     was_dead: bool,
     my_faction: Option<u32>,
 }
@@ -404,12 +256,6 @@ pub(super) struct QueryState {
 mod tests {
     use super::*;
 
-    /// The re-ask law (decision 0654). The server only *answers* queries, so a status we never
-    /// re-ask for is a marker frozen at whatever it was when the NPC came into view. Three
-    /// invalidations, all exercised here and all faithful: our own level (the ding that turns a
-    /// grey `!` gold — the reference's `UNIT_FIELD_LEVEL` field watch), the object leaving and
-    /// re-entering the world (its per-object query at create), and the questgiver bit going off
-    /// (its teardown branch).
     #[test]
     fn the_status_is_re_asked_on_a_ding_on_re_entry_and_dropped_with_the_flag() {
         use crate::net::{Guid, NetEntity};
@@ -466,8 +312,7 @@ mod tests {
         assert_eq!(asked(&mut app), 1, "asked once when it comes into view");
         assert_eq!(asked(&mut app), 0, "not again while nothing has changed");
 
-        // The ding: `SatisfyQuestLevel` is what made the answer UNAVAILABLE, so the whole set is
-        // re-asked — the marker can't learn it went gold any other way.
+        // The ding: `SatisfyQuestLevel` made the answer UNAVAILABLE, so the whole set is re-asked.
         *app.world_mut()
             .entity_mut(me)
             .get_mut::<ObjectStore>()
@@ -475,8 +320,7 @@ mod tests {
         assert_eq!(asked(&mut app), 1, "our level changed — re-ask everyone");
         assert_eq!(asked(&mut app), 0, "…once");
 
-        // Out of view: the cached status dies with the object (the reference caches it *on* the
-        // unit), so the marker can't flash stale on the way back in.
+        // Out of view: the cached status dies with the object, as the reference's does.
         app.world_mut()
             .resource_mut::<QuestGiver>()
             .set_status(NPC, 5);
@@ -510,18 +354,10 @@ mod tests {
         );
     }
 
-    /// **B257 — an escort giver's `!` outlived the accept.** The teardown branch used to be gated on
-    /// the guid still being in `asked` ("did we ever query it?"), which is a memo about *questions*
-    /// standing in for a fact about *answers* — and the sweep clears that memo. On accepting an
-    /// escort both halves land in the same update: vmangos writes the quest-log slot and, from the
-    /// script hook in the same handler, zeroes `UNIT_NPC_FLAGS`
-    /// (`FollowerAI::StartFollow` / `ScriptedEscortAI`'s "disable npcflags"). So the quest-log write
-    /// bumps the generation, `asked.clear()` runs first, `remove` finds nothing, and the cached
-    /// AVAILABLE status stays — forever, because the flag stays off and this arm never queries.
-    /// The reference tears down on the flag test alone (`0x5eb0a0`, decision 0647).
-    ///
-    /// The control below is the half that must NOT change: an ordinary giver, whose flag stays on,
-    /// is re-asked by the same sweep rather than torn down.
+    /// Accepting an escort, vmangos writes the quest-log slot and zeroes the giver's
+    /// `UNIT_NPC_FLAGS` in the same update (`ScriptedEscortAI.cpp:470`,
+    /// `ScriptedFollowerAI.cpp:328`): the frame is a sweep, and the flag drop must still tear the
+    /// marker down, while a giver whose flag stays on keeps its answer.
     #[test]
     fn an_escort_giver_loses_its_marker_when_the_flag_drops_with_the_quest_log_write() {
         use crate::net::{Guid, NetEntity};
@@ -575,8 +411,7 @@ mod tests {
                 .set_status(npc, 5);
         }
 
-        // The accept, as one update: the quest-log slot appears in OUR store (the sweep) and the
-        // escort's questgiver bit goes off (the teardown) — in the same drained batch.
+        // The accept as one update: our quest-log slot (a sweep) and the escort's flag drop.
         *app.world_mut()
             .entity_mut(me)
             .get_mut::<ObjectStore>()
@@ -617,16 +452,8 @@ mod tests {
         );
     }
 
-    /// **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
-    /// through `0x607380`, whose first post-prologue instruction is an unconditional teardown.
-    ///
-    /// The death and revive edges are the sharp end: they are the same folded alive/dead bit, one
-    /// each way, and they land on *different sweeps*. A model that cannot tell them apart either
-    /// blinks every marker on a damage-to-zero or fails to blink them on the way back.
+    /// The light sweep (`0x5eb0a0`, death among its triggers) sends without tearing down; the full
+    /// sweep (`0x5eb3f0`: your revive, your own reaction inputs) tears down first, in `0x607380`.
     #[test]
     fn a_light_sweep_re_asks_but_only_a_revive_tears_the_marker_down_first() {
         use crate::net::{Guid, NetEntity};
@@ -698,13 +525,12 @@ mod tests {
         assert_eq!(asked(&mut app), 1, "the create-path query");
         restore(&mut app);
 
-        // The packet half of the LIGHT sweep — a quest turn-in, a reputation change, a roster
-        // change. Re-asks; the `!` stays up until the fresh answer lands.
+        // A packet's light sweep (a turn-in, a reputation or roster change): the `!` stays up.
         app.world_mut().resource_mut::<QuestGiver>().bump_reask();
         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 `0x6046f0` routes to the light sweep. Same rule.
+        // Death, the `>0 → ≤0` edge, is a light sweep (`0x6046f0`).
         set_self(
             &mut app,
             &[(FIELD_LEVEL, 5), (FIELD_HEALTH, 0), (FIELD_FACTION, 1)],
@@ -712,7 +538,7 @@ mod tests {
         assert_eq!(asked(&mut app), 1, "death re-asks");
         assert_eq!(held(&app), Some(5), "…and is still a light sweep");
 
-        // Your REVIVE — the `≤0 → >0` edge, the sibling branch, and the FULL sweep.
+        // Revive, the `≤0 → >0` edge, is the full sweep.
         set_self(
             &mut app,
             &[(FIELD_LEVEL, 5), (FIELD_HEALTH, 100), (FIELD_FACTION, 1)],
@@ -724,8 +550,8 @@ mod tests {
             "…and tears every creature's marker down first (0x5eb3f0 -> 0x607380)"
         );
 
-        // Your own record's reaction inputs moving — the full sweep's other caller. It is NOT in
-        // the folded generation at all, so this also pins that `full` can raise a sweep by itself.
+        // Our own faction moving, the full sweep's other trigger, is outside the generation, so
+        // `full` alone raises the sweep.
         restore(&mut app);
         set_self(
             &mut app,
@@ -735,11 +561,8 @@ mod tests {
         assert_eq!(held(&app), None, "…fully");
     }
 
-    /// **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.
+    /// The sweep tears down on hostility (`0x5eb143`), the flag deciding only the send; on the real
+    /// `FactionTemplate.dbc`.
     #[test]
     fn a_hostile_questgiver_is_torn_down_and_never_asked_about() {
         use crate::net::{Guid, NetEntity};
@@ -750,8 +573,7 @@ mod tests {
         const FIELD_LEVEL: u16 = 34;
         const FIELD_FACTION: u16 = 35;
         const FIELD_NPC_FLAGS: u16 = 147;
-        /// `FactionTemplate.dbc` 35 = "friendly to players", 14 = the monster template that is
-        /// hostile to everything — the pair the ring's own tests use.
+        /// `FactionTemplate.dbc` 35 is friendly to players, 14 the monster template hostile to all.
         const TPL_FRIENDLY: u32 = 35;
         const TPL_MONSTER: u32 = 14;
 
@@ -807,10 +629,7 @@ mod tests {
                 .collect()
         };
 
-        // Bring both into view first. That frame is a `0x607380` for each of them (the create/init
-        // hook: an unconditional teardown, then the re-gate), so a status seeded *before* it would
-        // be torn down for a reason that has nothing to do with hostility — and it is not a state a
-        // client can be in anyway, since a status cannot exist for a unit never seen.
+        // First sight is a `0x607380` teardown for each, so statuses are seeded after it.
         app.update();
         assert_eq!(
             drain(&rx),
@@ -845,18 +664,9 @@ mod tests {
         );
     }
 
-    /// **The flight master's green `!` shares one slot with the gold one, so it shares its
-    /// 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`
-    ///   @`0x6073e8` — so it goes out on this unit's own key moving and on a full sweep, and
-    ///   **never** on a light one. There is no mouseover trigger; the function that claim rested on
-    ///   (`0x5eb220`) is the callback of a seeder nothing calls.
-    /// - the questgiver query is the opposite: the light sweep's callback sends it inline
-    ///   (`0x5eb159`), so every sweep re-asks.
-    /// - and `0x6073f0` zeroes `+0xb2c` and `+0xcb8` together, so whatever tears one marker down
-    ///   takes the other with it.
+    /// `CMSG_TAXINODE_STATUS_QUERY`'s one sender is `0x607380` (`0x6073e8`): on sight, on the
+    /// unit's own key moving and on a full sweep, never a light one and never on mouseover
+    /// (`0x5eb220` is the callback of a seeder nothing calls). `0x6073f0` clears both markers.
     #[test]
     fn a_flight_master_is_asked_by_the_per_unit_path_only_and_loses_its_green_with_the_gold() {
         use crate::net::{Guid, NetEntity};
@@ -864,8 +674,8 @@ mod tests {
         use benilla_protocol::{EntityKind, ObjectFields};
 
         const FM: u64 = 0x9001; // flightmaster only
-        const GIVER: u64 = 0x9002; // questgiver only — the asymmetry's control
-        const VENDOR: u64 = 0x9003; // neither — never asked at all
+        const GIVER: u64 = 0x9002; // questgiver only, the control
+        const VENDOR: u64 = 0x9003; // neither: never asked
         const FIELD_LEVEL: u16 = 34;
         const FIELD_HEALTH: u16 = 22;
         const FIELD_NPC_FLAGS: u16 = 147;
@@ -924,7 +734,7 @@ mod tests {
             (taxi, giver)
         };
 
-        // On sight: the create/init hook IS a `0x607380`, so both services are asked, once each.
+        // On sight: the create path is a `0x607380`, so each service is asked once.
         app.update();
         let (taxi, giver) = drain(&rx);
         assert_eq!(taxi, vec![FM], "the flight master is asked on sight");
@@ -937,8 +747,7 @@ mod tests {
         app.update();
         assert_eq!(drain(&rx), (vec![], vec![]), "then quiet");
 
-        // A LIGHT sweep: the questgiver is re-asked inline by the callback; the flight master is
-        // not, because `0x5eb0a0` does not test bit 0x8 at all.
+        // A light sweep re-asks the questgiver; `0x5eb0a0` never tests bit `0x8`.
         app.world_mut().resource_mut::<QuestGiver>().bump_reask();
         app.update();
         let (taxi, giver) = drain(&rx);
@@ -949,7 +758,7 @@ mod tests {
             "…and never the flight master: 0x1aa has one sender site and it is not in the sweep"
         );
 
-        // The green marker is up, and a FULL sweep (a revive) takes it down and re-asks.
+        // With the green marker up, a full sweep (a revive) takes it down and re-asks.
         app.world_mut()
             .entity_mut(fm)
             .insert(FlightMasterStatus { known: false });
@@ -962,7 +771,7 @@ mod tests {
                 (FIELD_HEALTH, hp),
             ]));
         };
-        set_self(&mut app, 0); // death — a LIGHT sweep
+        set_self(&mut app, 0); // death: a light sweep
         app.update();
         assert_eq!(
             drain(&rx).0,
@@ -974,7 +783,7 @@ mod tests {
             "…and a light sweep leaves the green marker up"
         );
 
-        set_self(&mut app, 100); // revive — a FULL sweep
+        set_self(&mut app, 100); // revive: a full sweep
         app.update();
         assert_eq!(drain(&rx).0, vec![FM], "a revive re-asks the flight master");
         assert!(
@@ -1003,30 +812,21 @@ mod tests {
         );
     }
 
-    /// **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;
-    /// - a sweep asks exactly once, and the frames between sweeps are silent;
-    /// - **there is no bring-up query.** A GameObject entering view asks nothing; it waits for the
-    ///   next sweep. The unit control in the same world does the opposite on the same frame, which
-    ///   is what makes this a contrast and not an accident of ordering.
+    /// A GameObject's only send sites sit in sweep callbacks: no query at first sight, where the
+    /// unit control asks, and one per sweep.
     #[test]
     fn a_gameobject_is_asked_on_a_sweep_and_never_at_first_sight() {
         use crate::net::{Guid, NetEntity};
         use benilla_protocol::ObjectFields;
 
-        /// The Goldshire `Wanted Poster`'s real guid (`HIGHGUID_GAMEOBJECT`, template 68, spawn
-        /// 26843) and its real `GAMEOBJECT_FLAGS` — INTERACT_COND | NODESPAWN, read off the live
-        /// wire by `WOW_PROBE_GOQUEST`.
+        /// The Goldshire Wanted Poster (template 68, spawn 26843) as the server sends it, flags
+        /// `INTERACT_COND | NODESPAWN`, read off the wire by `WOW_PROBE_GOQUEST`.
         const POSTER: u64 = 0xf110_0000_0044_68db;
         const POSTER_FLAGS: u32 = 0x24;
         /// A GameObject next to it with no quest condition: a plain door, `NODESPAWN` only.
         const DOOR: u64 = 0xf110_0000_0045_0001;
         const DOOR_FLAGS: u32 = 0x20;
-        /// The control: an ordinary creature questgiver, which the same sweep treats differently.
+        /// The control: a creature questgiver.
         const NPC: u64 = 0x2222;
         const FIELD_LEVEL: u16 = 34;
         const FIELD_NPC_FLAGS: u16 = 147;
@@ -1063,7 +863,6 @@ mod tests {
             Guid(1),
             ObjectStore(ObjectFields::from_pairs(&[(FIELD_LEVEL, 5)])),
         ));
-        // Drain per update, then count per guid — several objects are in flight at once here.
         let asked = |app: &mut App| -> Vec<u64> {
             app.update();
             rx.try_iter()
@@ -1074,8 +873,7 @@ mod tests {
                 .collect()
         };
 
-        // Settle the generation first: the very first frame in a fresh world IS a sweep (nothing
-        // has been folded yet), so "first sight" can only be asked of a later frame.
+        // The first frame in a fresh world is a sweep, so first sight comes a frame later.
         assert!(asked(&mut app).is_empty(), "nothing in view yet");
 
         spawn(
@@ -1108,8 +906,7 @@ mod tests {
             "and the frames after it stay silent"
         );
 
-        // A sweep: any of the reference's 13 local-player triggers. The packet epoch stands in for
-        // its four packet handlers.
+        // A sweep, through the packet epoch.
         app.world_mut().resource_mut::<QuestGiver>().bump_reask();
         let swept = asked(&mut app);
         assert!(
@@ -1135,8 +932,7 @@ mod tests {
             "between sweeps, nothing — a GameObject has no per-object key to re-ask on"
         );
 
-        // ...and it is not one-shot: the next sweep asks again, because the reference keeps no
-        // per-GameObject memo of having asked (there is nowhere on a CGGameObject_C to keep one).
+        // Not one-shot: the reference keeps no per-GameObject memo of having asked.
         app.world_mut().resource_mut::<QuestGiver>().bump_reask();
         assert!(
             asked(&mut app).contains(&POSTER),
@@ -1144,9 +940,6 @@ mod tests {
         );
     }
 
-    /// The rest of the reference's trigger set (0654): the remaining self-descriptor watches, the
-    /// packet epoch that stands in for its four packet handlers, and the per-unit key that catches
-    /// a unit's own service bits or faction moving. Each leg must re-ask exactly once.
     #[test]
     fn every_recorded_trigger_re_asks_exactly_once() {
         use crate::net::{Guid, NetEntity};
@@ -1174,8 +967,7 @@ mod tests {
             .init_resource::<crate::net::Reputations>()
             .add_systems(Update, query_statuses);
 
-        // Our own store starts with every watched field present, so each leg below is a CHANGE to
-        // one field rather than a field appearing for the first time.
+        // Every watched field starts present, so each leg below is a change, not an arrival.
         let base_self = vec![
             (34u16, 5u32),
             (FIELD_HEALTH, 100),
@@ -1219,8 +1011,7 @@ mod tests {
                 )
                 .count()
         };
-        // Replace one field of our own descriptor, keeping the rest — the shape a values-update
-        // delta actually has.
+        // One field replaced, the rest kept: a values-update delta's shape.
         let set_self = |app: &mut App, field: u16, value: u32| {
             let mut pairs = base_self.clone();
             match pairs.iter_mut().find(|(f, _)| *f == field) {
@@ -1237,7 +1028,7 @@ mod tests {
         assert_eq!(asked(&mut app), 0, "then quiet");
 
         for (label, field, value) in [
-            ("death", FIELD_HEALTH, 0u32), // the alive/dead bit, not the raw value — see 0654
+            ("death", FIELD_HEALTH, 0u32), // the alive bit, not the raw value
             ("PLAYER_FLAGS", FIELD_PLAYER_FLAGS, 0x10),
             ("money", FIELD_COINAGE, 900),
             ("a skill rank", FIELD_SKILL_1_1 + 1, 80 | (300 << 16)),
diff --git a/crates/benilla-app/src/target/by_name.rs b/crates/benilla-app/src/target/by_name.rs
index c5e7da08..476b1c76 100644
--- a/crates/benilla-app/src/target/by_name.rs
+++ b/crates/benilla-app/src/target/by_name.rs
@@ -1,66 +1,22 @@
-//! 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:
+//! Selection by name: the reference's one resolver (`0x493aa0`) behind `/target`, `/assist` and
+//! `/follow`, parameterised per binding.
 //!
 //! | binding | typemask | filter mode | exact-only |
 //! |---|---|---|---|
-//! | `TargetByName 0x489d60` | 8 = UNIT (creatures **and** players) | 0 | Lua arg #2, never supplied |
-//! | `AssistByName 0x489c40` | 0x10 = **PLAYER only** | 0 | hardcoded 0 |
-//! | `FollowByName 0x489ec0` | 0x10 = PLAYER only | 2 (`CanAssist` + alive) | Lua arg #2 |
+//! | `TargetByName 0x489d60` | 8, creatures and players | 0 | Lua arg 2 |
+//! | `AssistByName 0x489c40` | 0x10, players only | 0 | 0 |
+//! | `FollowByName 0x489ec0` | 0x10, players only | 2, `CanAssist` and alive | Lua arg 2 |
 //!
-//! **Filter mode 0 is the whole point of the shape**: it underflows `0x493e40`'s jump table
-//! (`dec eax; cmp eax,3; ja`) into the default arm `mov eax,1; ret 4` — *accept unconditionally*. So
-//! by-name selection has **no** range limit, **no** facing cone, **no** dead/reaction/attackability
-//! test, **no** scene-attach visibility gate, and **no** self-exclusion. It is a far wider net than
-//! TAB ([`super::scan`]), which shares none of those defaults. `/target <your own name>` self-targets
-//! in the real client, and so does it here.
+//! Filter mode 0 underflows `0x493e40`'s jump table into accept-all: no range, facing, reaction,
+//! liveness, visibility or self test. A name matches whole-string first (`0x64a4c0` → CRT
+//! `0x414310`), else by the longest common prefix (`0x493cb6`-`0x493cf6`), both case-insensitive.
 //!
-//! ## The comparison — two tiers, both case-insensitive
+//! Deviation: the reference ends the walk at the first whole-string hit (`0x493ca2`), so its pick
+//! follows the object list's order (a tail append, `0x4646c3`-`0x4646d4`); we rank exact, then
+//! longer prefix, then nearest ([`Rank::beats`]), because the nearest namesake is the better pick.
 //!
-//! 1. **Whole-string** (`0x64a4c0` → CRT `0x414310`, which folds both operands in its own bytes).
-//! 2. **Longest common PREFIX** (`0x493cb6`-`0x493cf6`), anchored at index 0 — a prefix, never a
-//!    substring. Live whenever the second Lua argument is absent, which is every shipped call site,
-//!    so `/target Rag` really does select "Ragnaros". The running best length starts at **1**, so one
-//!    folded character of overlap is enough to enter the ranking — and a query sharing no first
-//!    letter with anything matches nothing.
-//!
-//! Within one prefix-length class the tie-break is the **strictly nearest** 3D centre-to-centre
-//! dist² (the reference's `fcomp`/`jp` edge is a strict `<`, so ties keep the incumbent).
-//!
-//! ## The one deliberate deviation — and why
-//!
-//! In the reference a tier-1 whole-string hit **returns 0 from the walk callback, terminating the
-//! enumeration** (`0x493ca2`, stopped at `0x4683b7`). Two consequences fall out, both
-//! enumeration-order dependent: among several identically-named creatures the client takes
-//! *whichever the ClntObjMgr table walk reaches first* — never the nearest — and a near "Bobby"
-//! recorded before a far "Bob" beats it outright for the query `Bob`.
-//!
-//! **We do not reproduce the early-out**, and since 0886 was written the order it depends on has
-//! been derived, so the choice is now made against a known reference rather than an unknown one.
-//! Table #1 is an intrusive doubly-linked list (link field at `obj+0x38`, written by the ctor at
-//! `0x4650c2`) whose insert is a **tail append** (`0x4646c3`-`0x4646d4`), so the walk runs
-//! **oldest-linked first** — and "linked", not "spawned": a unit that streams out and back in is
-//! re-appended to the tail. The reference's tier-1 pick is therefore *the same-named candidate that
-//! has been continuously known longest*, which no client-side heuristic reproduces without modelling
-//! the list itself.
-//!
-//! [`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.
-//! 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.
-//!
-//! ## Not carried
-//!
-//! The reference pre-scans the **party** (`0x493b20`) and **raid** (`0x493b9d`) rosters before the
-//! object walk, matching group members against the guid-keyed name cache at a sentinel distance of
-//! 2.5e9 — so a groupmate with no streamed object is still selectable. benilla cannot hold a
-//! guid-only selection at all yet ([`Selection::target`] is an `Entity`; the same gap already
-//! no-ops `TargetUnit("partyN")` on an out-of-range member, see [`super::click`]), so the pre-scans
-//! wait on that slice rather than being half-built here.
+//! Not built: the reference's party (`0x493b20`) and raid (`0x493b9d`) pre-scans, which select an
+//! unstreamed groupmate; [`Selection::target`] is an `Entity`.
 
 use std::cmp::Ordering;
 
@@ -74,13 +30,12 @@ use crate::net::{Guid, GuidIndex, ObjectStore, SelfPlayer};
 
 use super::{scan, Selection};
 
-/// Which guid families a search accepts — the reference's `edx` typemask argument.
+/// Which guid families a search accepts, the reference's typemask argument.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum NameSearch {
-    /// Typemask 8: creatures **and** players (a player object carries the UNIT bit). `/target`.
+    /// Typemask 8, creatures and players (a player carries the UNIT bit): `/target`.
     AnyUnit,
-    /// Typemask 0x10: players only. `/assist` — so `/assist <creature name>` cannot resolve, while
-    /// assisting a *targeted* creature can (the no-argument form never goes through the resolver).
+    /// Typemask 0x10, players only: `/assist <name>` and `/follow <name>`.
     PlayerOnly,
 }
 
@@ -93,35 +48,33 @@ impl NameSearch {
     }
 }
 
-/// `/target <name>` — resolve and select (`TargetByName`).
+/// `/target <name>`: resolve and select (`TargetByName`).
 #[derive(bevy::ecs::message::Message, Clone, Debug)]
 pub(crate) struct TargetByNameRequest {
     pub(crate) name: String,
 }
 
-/// `/assist [name]` — select the basis unit's own target (`AssistByName` / `AssistUnit("target")`).
-/// `None` is the bare form, whose basis is the current selection.
+/// `/assist [name]`: select the basis unit's target (`AssistByName`, or bare
+/// `AssistUnit("target")`, whose basis is the current selection).
 #[derive(bevy::ecs::message::Message, Clone, Debug)]
 pub(crate) struct AssistRequest {
     pub(crate) name: Option<String>,
 }
 
-/// How well one candidate answered the query. Ordered by [`Rank::beats`].
+/// How well one candidate answered the query, ordered by [`Rank::beats`].
 #[derive(Clone, Copy, Debug, PartialEq)]
 struct Rank {
-    /// A tier-1 whole-string (case-insensitive) match.
+    /// A whole-string, case-insensitive match.
     exact: bool,
-    /// Folded common-prefix length, capped by both strings — the reference's
-    /// `matchLen = searchCursor - ctx.name`.
+    /// The folded common-prefix length.
     prefix: usize,
     /// 3D centre-to-centre squared distance from the active player.
     dist2: f32,
 }
 
 impl Rank {
-    /// Strictly better than the incumbent? Exact beats any prefix; then the longer prefix; then the
-    /// strictly nearer. Ties keep the incumbent, and a NaN distance never displaces — both edges the
-    /// reference's `fcomp` + `test ah,5` + `jp` reject makes.
+    /// Strictly better than the incumbent: exact, then the longer prefix, then the strictly nearer.
+    /// A tie or a NaN distance keeps the incumbent, as the reference's `fcomp`/`jp` compare does.
     fn beats(self, other: Rank) -> bool {
         match (self.exact, other.exact) {
             (true, false) => true,
@@ -135,9 +88,8 @@ impl Rank {
     }
 }
 
-/// The folded common-prefix length of `query` and `name` — the reference's lockstep walk
-/// (`0x493cc0`-`0x493cee`) through the ASCII case fold `0x41089b`, stopping at whichever string ends
-/// first or at the first folded mismatch.
+/// The case-folded common-prefix length, the reference's lockstep walk (`0x493cc0`-`0x493cee`)
+/// through the ASCII fold `0x41089b`.
 fn common_prefix_len(query: &str, name: &str) -> usize {
     query
         .bytes()
@@ -146,26 +98,19 @@ fn common_prefix_len(query: &str, name: &str) -> usize {
         .count()
 }
 
-/// The follow start gate's decision, as a pure function of the five things it reads — so the
-/// **order** of the chain (which refusal you see when two apply at once) is pinned by test rather
-/// than by whichever `if` happens to come first after an edit.
-///
-/// `0x60fed0`'s mode-3 chain, in its own order, with the message ids it pushes:
+/// The follow start gate (`0x60fed0`'s mode-3 chain) as a pure function, its order pinned by test:
 ///
 /// | check | site | failure |
 /// |---|---|---|
-/// | followee typemask `0x10` (PLAYER) | `0x60ff5f` | `0x128` `ERR_INVALID_FOLLOW_TARGET` |
-/// | `CanAssist` the followee (`0x606ba0`) | `0x60ff6a` | `0x128`, the same line |
+/// | followee is a player (typemask `0x10`) | `0x60ff5f` | `0x128` `ERR_INVALID_FOLLOW_TARGET` |
+/// | `CanCooperate` with the followee (`0x606ba0`) | `0x60ff6a` | `0x128`, the same line |
 /// | we are alive | `0x60ff7c` | `0x7e` `ERR_PLAYER_DEAD` |
 /// | we are not stunned (`UNIT_FIELD_FLAGS & 0x40000`) | `0x60ff95` | `0x191` `ERR_GENERIC_STUNNED` |
-/// | we are not casting (`[[mover+0x110]+0x228] == 0`) | `0x60ffb9` | `0x134` `ERR_TOOBUSYTOFOLLOW` |
+/// | we are not casting | `0x60ffb9` | `0x134` `ERR_TOOBUSYTOFOLLOW` |
 ///
-/// There is deliberately **no followee-alive check** and **no distance check**. A corpse can be
-/// followed (it is the per-tick death test that ends the follow, not the gate), and the
-/// max-distance machinery — `0x6110a0`, which raises `ERR_AUTOFOLLOW_TOO_FAR` at the binary's only
-/// `0x126` call site — is **disabled by data**: follow's row in the per-mode table `0x860a58` has a
-/// `0.0f` threshold, which `0x6110c8` short-circuits on. So the error string ships, the code ships,
-/// and no distance is ever enforced at either end. One `.rdata` float from being a real limit.
+/// There is no followee-alive check (the per-tick death test ends a follow) and no distance check:
+/// follow's row in `0x860a58` has a `0.0` threshold, so `ERR_AUTOFOLLOW_TOO_FAR` (`0x6110a0`)
+/// never fires (`0x6110c8`).
 fn follow_refusal_key(
     followee_is_player: bool,
     can_assist_followee: bool,
@@ -188,23 +133,19 @@ fn follow_refusal_key(
     None
 }
 
-/// Whether the resolver's **second tier** is live — the shared resolver's exact-only parameter,
-/// which every caller in the table above sources from the second Lua argument.
-///
-/// It is not decoration: `UnitPopup.lua`'s Follow row passes `FollowByName(name, 1)`, and a menu
-/// that already names its unit exactly must not prefix-match its way onto a bystander who happens
-/// to share a first letter. `/follow rag` still may, because the slash command passes nothing.
+/// Whether the prefix tier is live, the resolver's exact-only argument. The unit popup's Target and
+/// Follow pass 1 (`UnitPopup.lua:557`, `UnitPopup.lua:623`), so a menu naming its unit never lands
+/// on a bystander sharing a first letter; the slash commands pass nothing.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum Match {
-    /// Tier 1 then tier 2 — a whole-string hit, else the longest common prefix.
+    /// A whole-string hit, else the longest common prefix.
     PrefixOk,
-    /// Tier 1 only. Tier 2 is skipped entirely, so a query that is not the whole name matches
-    /// nothing at all.
+    /// Whole-string only.
     ExactOnly,
 }
 
-/// Score one candidate against the query, or `None` when it does not match at all. The reference's
-/// running best length seeds at **1**, so a zero-length overlap is not a match.
+/// Score one candidate against the query. The reference's best length seeds at 1, so a zero-length
+/// overlap is no match.
 fn rank(query: &str, name: &str, dist2: f32, mode: Match) -> Option<Rank> {
     if query.eq_ignore_ascii_case(name) {
         return Some(Rank {
@@ -224,11 +165,11 @@ fn rank(query: &str, name: &str, dist2: f32, mode: Match) -> Option<Rank> {
     })
 }
 
-/// Everything a by-name search reads. Shared by the `/target` and `/assist` drains.
+/// Everything a by-name search reads.
 #[derive(SystemParam)]
-#[allow(clippy::type_complexity)] // one bundled system param — the app's convention for big query sets
+#[allow(clippy::type_complexity)] // one bundled param, the app's convention for big query sets
 pub(crate) struct ByNameScan<'w, 's> {
-    /// Every known unit INCLUDING our own avatar — the reference has no self-exclusion on this path.
+    /// Every known unit, our own avatar included: the reference has no self-exclusion here.
     units: Query<
         'w,
         's,
@@ -250,30 +191,26 @@ pub(crate) struct ByNameScan<'w, 's> {
         ),
         With<SelfPlayer>,
     >,
-    /// Read-only: a by-name sweep must never fire a name query per candidate. A unit whose name has
-    /// not been cached yet is simply not matchable — the same limit the reference has, whose own
-    /// name getter reads an already-resolved string.
+    /// Read-only: a sweep fires no name query, so an uncached name does not match, as in the
+    /// reference.
     names: Res<'w, NameCache>,
-    /// Only [`Filter::AssistableAlive`] reads these — the reaction ladder behind `CanAssist`.
+    /// The reaction inputs behind `CanAssist`, for [`Filter::AssistableAlive`] and the follow gate.
     factions: Option<Res<'w, super::Factions>>,
     reputations: Res<'w, crate::net::Reputations>,
 }
 
-/// The per-candidate filter the reference hands `0x493e40` as its mode argument.
+/// The per-candidate filter, the mode argument the reference hands `0x493e40`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum Filter {
-    /// **Mode 0** — and the shape is the point: `0-1` underflows the `cmp eax,3; ja` bound, so the
-    /// jump table is skipped entirely for `mov eax,1; ret 4`. Accept unconditionally. `/target`,
-    /// `/assist`.
+    /// Mode 0, which underflows the jump table's bound into accept-all: `/target`, `/assist`.
     AcceptAll,
-    /// **Mode 2** (`0x493eca`) — `CanAssist 0x6066f0` **and** `UNIT_FIELD_HEALTH > 0`. `/follow`
-    /// resolves only to living, assistable candidates, so `/follow <an enemy player>` finds nothing.
+    /// Mode 2, `CanAssist` and `UNIT_FIELD_HEALTH > 0`: `/follow`.
     AssistableAlive,
 }
 
 impl ByNameScan<'_, '_> {
-    /// The active player's position — the distance origin (the reference returns `(0,0)` outright
-    /// when the active player object does not resolve, `0x493ae0`).
+    /// The distance origin, the active player's position; without one the reference resolves
+    /// nothing (`0x493ae0`).
     fn origin(&self) -> Option<Vec3> {
         self.self_q
             .single()
@@ -281,9 +218,7 @@ impl ByNameScan<'_, '_> {
             .map(|(_, _, tf, _)| tf.translation)
     }
 
-    /// The reference's mode-2 arm (`0x493eca`): `CanAssist` — the reaction ladder at **≥ 4**
-    /// (friendly; `CanAssist_Unit 0x6066f0`), the mirror of [`scan::can_attack`]'s
-    /// `≤ 3` — **and** alive.
+    /// The mode-2 arm (`0x493eca`): alive, and `CanAssist 0x6066f0` as a friendly reaction (4+).
     fn assistable_alive(&self, store: Option<&ObjectStore>) -> bool {
         if store.is_some_and(|s| s.0.unit_is_dead()) {
             return false;
@@ -297,20 +232,8 @@ impl ByNameScan<'_, '_> {
         ) >= 4
     }
 
-    /// The **follow start gate** — `0x60fed0`'s mode-3 chain (reached via the remap
-    /// `0x610094[3] = 1` → `0x610084[1]` = `0x60ff59`), in the reference's own order. Returns the
-    /// GlobalStrings key of the *first* refusal, or `None` to let the follow begin.
-    ///
-    /// This gate is why 0890's "the bare form follows whatever you have selected, creature or
-    /// player, with no such filter" was **true and yet wrong about the behaviour**. That sentence
-    /// was about the by-name *resolver's* filter, and it is correct: `FollowUnit` never goes
-    /// through `0x493aa0`. But the gate below sits downstream of both bindings, so a creature is
-    /// refused all the same — with "You can't follow that unit.", which is exactly what the real
-    /// client says. Being right about *a* mechanism is not being right about *the* cause.
-    ///
-    /// Each refusal is a real error line through the one `CGGameUI::DisplayError` route
-    /// ([`crate::ui_action::UiErrorKeys`]) rather than silence, because that is what the reference
-    /// does — these five have message ids, and three of the four strings exist for no other caller.
+    /// The follow start gate ([`follow_refusal_key`], entered at `0x60ff59`): the key of the first
+    /// refusal, for `CGGameUI::DisplayError`. `FollowUnit` skips the resolver but not this gate.
     fn follow_refusal(
         &self,
         followee: u64,
@@ -332,12 +255,8 @@ impl ByNameScan<'_, '_> {
         )
     }
 
-    /// Resolve a name to a unit, or `None`. See the module header for the full law.
-    ///
-    /// Every call logs its verdict under the `by-name:` prefix — one line per typed command, so a
-    /// "`/target` won't take that mob" report is diagnosable from the log rather than re-guessed
-    /// (the `WOW_TAB_TRACE` instrument's shape, ungated because the cost is per-command, not
-    /// per-frame). The line names how many candidates were eligible, which won, and on what.
+    /// Resolve a name to a unit, logging one `by-name:` line per call, ungated since it runs per
+    /// command: the candidates counted, the winner and on what.
     fn resolve(
         &self,
         query: &str,
@@ -393,14 +312,10 @@ impl ByNameScan<'_, '_> {
     }
 }
 
-/// Drain `/target <name>`: resolve, then commit through the shared SetSelection path so a by-name
-/// switch obeys the same stop → select → re-swing law a click does ([`scan::commit`]).
-///
-/// 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 its text is not statically recoverable, so we say nothing rather
-/// than invent a line. That silence is the known deviation on this path.
+/// Drain `/target <name>` through [`scan::commit`], the stop, select, re-swing path a click takes.
+/// A miss leaves the target alone, as neither failure edge in `0x489db4` calls `SetSelection`, and
+/// prints nothing; the reference prints message `0x127` `ERR_UNIT_NOT_FOUND` there, or `0xb8`
+/// `ERR_GENERIC_NO_TARGET` for an empty name.
 pub(super) fn target_by_name_requests(
     mut requests: MessageReader<TargetByNameRequest>,
     scan_params: ByNameScan,
@@ -419,23 +334,9 @@ pub(super) fn target_by_name_requests(
     }
 }
 
-/// Drain the **Lua** `TargetByName(name, exactMatch)` asks — the binding half of the same
-/// resolver [`target_by_name_requests`] runs for `/target`.
-///
-/// A separate system rather than a second writer of [`TargetByNameRequest`] because the binding
-/// carries a second argument the slash command has no way to supply: `0x489d8e` fetches Lua arg #2
-/// with default 0 and hands it to `0x493aa0` as the **exact-only** flag (`ctx+0x0c`, consumed at
-/// `0x493cab`). Shipped FrameXML never passes it — its own usage string documents one argument —
-/// so a stock `/target` and a stock addon call both run with prefix matching live; an addon that
-/// already knows the exact name can turn tier 2 off, exactly as `UnitPopup.lua` does for
-/// `FollowByName(name, 1)`.
-///
-/// Everything else is identical to the slash path, deliberately: typemask 8 (creatures *and*
-/// players), filter mode 0 (accept unconditionally — no range, cone, dead, reaction or
-/// self-exclusion test), commit through [`SelectCommit`], and a miss that leaves the current
-/// target untouched and says nothing (the reference's two game-message ids are `0x127`/`0xb8`,
-/// whose strings are runtime-populated BSS and are not statically recoverable — the known
-/// deviation this path already carries).
+/// Drain the Lua `TargetByName(name, exactMatch)` asks, the `/target` path plus the second
+/// argument, which `0x489d8e` reads with default 0 as the resolver's exact-only flag (consumed at
+/// `0x493cab`).
 pub(super) fn script_target_by_name_requests(
     script: Option<NonSendMut<benilla_ui::script::UiScript>>,
     scan_params: ByNameScan,
@@ -461,27 +362,15 @@ 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, 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
-/// completely silent no-op (verified: the shared tail bails before any send).
-///
-/// **The `assistAttack` leg is correctly absent.** With that CVar (`0xb4d8f8`) non-zero the
-/// reference's tail also opens the swing on the newly-selected target (`0x5ecb70` →
-/// `CMSG_ATTACKSWING`) — but its **registered default is `"0"`** (VERIFIED at the registration
-/// bytes: `0x48fc50`, default-value slot `[ebp+0xc]` = `0x82e570` = `"0"`, int-parsed into
-/// `[cvar+0x28]` by `0x63e127`). So stock `/assist` selects and does **not** swing, which is exactly
-/// what this does. The leg becomes reachable only if benilla ever grows the CVar itself.
+/// Drain `/assist [name]`: the basis is a named player, or bare the current selection
+/// (`AssistUnit("target")`, `ChatFrame.lua:744`), and [`SelectCommit::assist`] selects its target.
 pub(super) fn assist_requests(
     mut requests: MessageReader<AssistRequest>,
     scan_params: ByNameScan,
     mut commit: SelectCommit,
 ) {
     for request in requests.read() {
-        // The basis: a named PLAYER, or — bare — whatever is currently selected.
+        // The basis: a named player, or bare, whatever is selected.
         let basis = match &request.name {
             Some(name) => scan_params
                 .resolve(
@@ -497,22 +386,13 @@ pub(super) fn assist_requests(
             info!("assist (/assist): no basis unit; nothing to assist");
             continue;
         };
-        // Everything from here is `AssistUnit`'s tail too — one function, as in the reference.
+        // From here on this is `AssistUnit`'s tail too, one function as in the reference.
         commit.assist(basis, "/assist");
     }
 }
 
-/// Drain `/follow [name]`: resolve the subject and hand it to [`crate::player`], which owns the
-/// motion (decision 0890). Nothing goes on the wire — follow is client-side movement only.
-///
-/// The two forms differ in how the subject is **found** — a name goes through the resolver with
-/// the reference's filter mode 2 (players only, alive and assistable), a token takes whatever it
-/// points at — but **not** in what is allowed. [`ByNameScan::follow_refusal`] sits downstream of
-/// both, so `/follow` on a creature refuses either way, with the reference's own error line.
-///
-/// The followee's **name** is latched here rather than re-read later: it is what
-/// `AUTOFOLLOW_BEGIN` carries into the status text ([`crate::ui_follow`]), and the resolver has
-/// already produced it for the by-name half.
+/// Drain `/follow [name]` into [`crate::player`]; follow sends nothing on the wire. The followee's
+/// name is latched here for `AUTOFOLLOW_BEGIN` ([`crate::ui_follow`]).
 pub(super) fn follow_requests(
     mut requests: MessageReader<crate::player::FollowRequest>,
     scan_params: ByNameScan,
@@ -538,11 +418,8 @@ pub(super) fn follow_requests(
                     },
                 )
                 .map(|(_, guid, name)| (guid, name)),
-            // `"target"` is deliberately NOT routed through `player_token_guid`: that helper
-            // applies the inspect/popup family's players-only typemask *at the token*, whereas
-            // follow's typemask is the start gate's, one layer down, and must produce the gate's
-            // error line rather than a silent nothing. The party tokens do go through it — they
-            // can only ever name a player anyway, and it knows the roster order.
+            // `"target"` skips `player_token_guid`, whose players-only filter would make a
+            // creature a silent miss: the start gate must refuse it with its error line.
             crate::player::FollowRequest::Unit(token) => match token.as_str() {
                 "target" => selection.guid,
                 tok => crate::ui_unit::player_token_guid(tok, &selection, &group),
@@ -552,7 +429,7 @@ pub(super) fn follow_requests(
                 (guid, name)
             }),
         };
-        // The start gate, applied to whichever way the subject was found.
+        // The start gate, whichever way the subject was found.
         if let Some((guid, _)) = &resolved {
             let followee = index.0.get(guid).and_then(|e| stores.get(*e).ok());
             if let Some(key) = scan_params.follow_refusal(
@@ -571,24 +448,20 @@ pub(super) fn follow_requests(
                 follow.start(guid, name);
             }
             None => {
-                // The reference's `if GetSlashCmdTarget(msg)` guard and the resolver's own miss both
-                // land here: nothing to follow, and whatever we were following is left alone.
+                // No subject by name or token: a follow in progress is left alone.
                 info!("follow: nothing to follow");
             }
         }
     }
 }
 
-/// The shared commit tail — everything [`scan::commit`] needs, bundled, so both drains route a
-/// resolved unit through the one SetSelection path (dedup + the stop → select → re-swing law).
+/// Everything [`scan::commit`], the one `SetSelection` path, needs.
 #[derive(SystemParam)]
-#[allow(clippy::type_complexity)] // one bundled system param — the app's convention for big query sets
+#[allow(clippy::type_complexity)] // one bundled param, the app's convention for big query sets
 pub(crate) struct SelectCommit<'w, 's> {
     pub(super) selection: ResMut<'w, Selection>,
     seam: crate::creature_anim::AttackSeam<'w, 's>,
-    // Our own body, read only for what the classification needs: the guid to compare against, the
-    // store `can_attack` reads, and whether we are mid-swing. It used to carry the `Entity` too,
-    // for `TargetUnit("player")`; that resolves through `crate::ui_unit::UnitTokens` now.
+    // Our own body: the guid, the store `can_attack` reads, and whether we are mid-swing.
     me: Query<
         'w,
         's,
@@ -600,29 +473,20 @@ pub(crate) struct SelectCommit<'w, 's> {
         With<SelfPlayer>,
     >,
     pub(super) stores: Query<'w, 's, &'static ObjectStore>,
-    /// The guid → entity map — `0x489a40`'s own `0x468460` lookup, which every one of this tail's
-    /// callers needs and none of them should re-derive.
+    /// The guid to entity map, `0x489a40`'s `0x468460` lookup.
     index: Res<'w, GuidIndex>,
     factions: Option<Res<'w, super::Factions>>,
     reputations: Res<'w, crate::net::Reputations>,
-    /// `assistAttack` — the assist tail's second leg (see [`Self::assist`]).
+    /// `assistAttack`, the assist tail's second leg.
     assist_attack: Res<'w, super::AssistAttack>,
 }
 
 impl SelectCommit<'_, '_> {
-    /// **The shared assist tail** (`0x489bb2`–`0x489c07`, byte-identical to `AssistByName`'s
-    /// `0x489cae`–`0x489d07`): read the basis unit's `UNIT_FIELD_TARGET` (`[[obj+0x110]+0x28]`),
-    /// bail **silently** on zero, then select it if it resolves.
-    ///
-    /// One function because the reference has one — the two Assist bindings differ only in how the
-    /// *basis* is found (a name through the resolver, a unit token through `0x515940`, or the
-    /// current selection for the bare form), never in what happens after. Three ways to no-op, all
-    /// of them silent and none of them a deselect: no basis, a basis targeting nothing, and a
-    /// target guid that is not streamed (`0x489a40`'s arm 3 is a bare `ret`).
-    ///
-    /// **The `assistAttack` swing leg** (`0x489c02`/`0x489d02 call 0x5ecb70`) runs after the
-    /// selection when that CVar is non-zero — its registered default is `"0"`, so stock assist
-    /// selects and does not swing.
+    /// The shared assist tail (`0x489bb2`-`0x489c07`, byte-identical in `AssistByName` at
+    /// `0x489cae`-`0x489d07`): select the basis unit's `UNIT_FIELD_TARGET` if it is streamed.
+    /// Every miss is silent and deselects nothing: no basis, a basis targeting nothing, or an
+    /// unstreamed guid (`0x489a40`'s arm 3 is a bare `ret`). With `assistAttack` set, the tail then
+    /// opens the swing (`0x489c02`/`0x489d02` call `0x5ecb70`).
     pub(super) fn assist(&mut self, basis: Entity, how: &str) {
         let Some(guid) = self
             .stores
@@ -634,20 +498,16 @@ impl SelectCommit<'_, '_> {
             info!("assist ({how}): the basis unit is targeting nothing; silent no-op");
             return;
         };
-        // "Select if it resolves" (`0x489a40`): only a streamed unit can be selected — the
-        // reference's group-roster fallback for an unstreamed guid needs the guid-only selection
-        // benilla does not have yet (see the module header).
+        // Only a streamed unit can be selected; the reference's roster fallback for an unstreamed
+        // guid is not built (see the module doc).
         let Some(entity) = self.index.0.get(&guid).copied() else {
             info!("assist ({how}): the basis is targeting guid {guid:#x}, which is not streamed");
             return;
         };
         info!("assist ({how}) -> the basis unit's target, guid {guid:#x}");
-        // `engaged` and the attackability walk are read BEFORE the selection, and that ordering is
-        // the reference's own seen from outside: `SetSelection` may itself have re-pointed a swing
-        // we already had (`0x4938c8`), and `0x5ecb70`'s already-attacking test then skips the
-        // *send* while still running the tail — the skip's `jmp` lands inside it. So the second leg
-        // is a no-op send plus a real sheath snap when we were already fighting, and a fresh swing
-        // when we were not.
+        // `engaged` and attackability are read before the selection: `SetSelection` may re-point
+        // a swing we already had (`0x4938c8`), and `0x5ecb70` then skips the send but still runs
+        // its tail, a sheath snap; not yet fighting, the second leg opens a fresh swing.
         let me = self.me.single().ok();
         let engaged = me.is_some_and(|(_, _, engaged)| engaged);
         let attackable = super::relations::can_attack(
@@ -657,20 +517,19 @@ impl SelectCommit<'_, '_> {
             me.and_then(|(_, store, _)| store),
         );
         self.commit(entity, guid);
-        // The second leg. `0x5ecb70`'s own attackability walk is the caller's here, as it is at
-        // every other benilla call site (`start_attack_local`'s header): a friendly assist target
-        // is selected and not swung at.
+        // The second leg. `0x5ecb70`'s attackability test is the caller's here, so a friendly
+        // target is selected, not swung at.
         if self.assist_attack.0 && attackable {
             info!("assist ({how}): assistAttack is on -> opening the swing");
             self.seam.start(guid, engaged, false);
         }
     }
 
-    /// Select a guid that is already resolved — `0x489a40`'s arm 1, plus [`scan::commit`]'s law.
+    /// Select a resolved guid, `0x489a40`'s arm 1, through [`scan::commit`].
     pub(super) fn commit(&mut self, entity: Entity, guid: u64) {
         let me = self.me.single().ok();
-        // The new-target classification `scan::commit` expects from its callers (it does not
-        // re-derive one) — the same `can_attack` the cursor and the TAB scan pass.
+        // `scan::commit` takes the new target's attackability from its caller: the same
+        // `can_attack` the cursor and TAB pass.
         let attackable = super::relations::can_attack(
             self.stores.get(entity).ok(),
             self.factions.as_deref(),
@@ -727,7 +586,7 @@ mod tests {
 
     #[test]
     fn a_match_needs_one_folded_character() {
-        // The reference seeds its best length at 1, so zero overlap is not a match at all.
+        // The reference seeds its best length at 1: zero overlap is no match.
         assert!(rank("zzz", "Ragnaros", 1.0, Match::PrefixOk).is_none());
         assert_eq!(
             rank("rag", "Ragnaros", 1.0, Match::PrefixOk).map(|r| r.prefix),
@@ -739,21 +598,15 @@ mod tests {
     fn whole_string_match_is_case_insensitive_and_ranks_exact() {
         let r = rank("kobold vermin", "Kobold Vermin", 9.0, Match::PrefixOk).expect("matches");
         assert!(r.exact, "tier 1 is case-insensitive whole-string");
-        // A multi-word creature name is the case that made the whole-argument trim load-bearing.
     }
 
-    /// The exact-only flag is the unit popup's Follow row (`FollowByName(name, 1)`): tier 2 is
-    /// skipped outright, so the prefix that `/follow rag` rides cannot fire. Tier 1 is unaffected
-    /// and stays case-insensitive — "exact" is about the whole string, never about case.
-    /// The follow start gate's chain, in the reference's order. The order is the point: a dead
-    /// player who targets a creature sees "You can't follow that unit.", not "You are dead" — the
-    /// followee checks come first, and both of them raise the SAME message id (0x128).
+    /// A dead player following a creature sees `ERR_INVALID_FOLLOW_TARGET`, not `ERR_PLAYER_DEAD`:
+    /// the two followee checks come first and share message `0x128`.
     #[test]
     fn the_follow_gate_refuses_in_the_references_own_order() {
         // The clean case.
         assert_eq!(follow_refusal_key(true, true, false, false, false), None);
-        // A creature — the correction that matters most, and the reason `/follow` on a mob refuses
-        // however you got there (0890 read the by-name filter and missed this gate below it).
+        // A creature refuses, however it was found.
         assert_eq!(
             follow_refusal_key(false, true, false, false, false),
             Some("ERR_INVALID_FOLLOW_TARGET")
@@ -776,12 +629,12 @@ mod tests {
             follow_refusal_key(true, true, false, false, true),
             Some("ERR_TOOBUSYTOFOLLOW")
         );
-        // Everything wrong at once: the followee's line wins outright.
+        // Everything wrong at once: the followee's line wins.
         assert_eq!(
             follow_refusal_key(false, false, true, true, true),
             Some("ERR_INVALID_FOLLOW_TARGET")
         );
-        // Dead AND stunned: dead wins, because it is checked first.
+        // Dead and stunned: dead is checked first.
         assert_eq!(
             follow_refusal_key(true, true, true, true, true),
             Some("ERR_PLAYER_DEAD")
@@ -800,18 +653,17 @@ mod tests {
 
     #[test]
     fn exact_beats_any_prefix_and_nearest_breaks_the_tie() {
-        // Our deliberate deviation: the reference's enumeration-order early-out would let a nearer
-        // "Bobby" beat a farther "Bob"; we rank exact first, unconditionally.
+        // The deviation: exact ranks first, whatever the reference's walk order.
         assert!(exact(100.0).beats(prefix(3, 1.0)));
         assert!(!prefix(3, 1.0).beats(exact(100.0)));
-        // Among exact matches — several identically-named kobolds — the nearest wins.
+        // Among same-named exact matches, the nearest wins.
         assert!(exact(4.0).beats(exact(9.0)));
         assert!(!exact(9.0).beats(exact(4.0)));
     }
 
     #[test]
     fn longer_prefix_beats_nearer_shorter_one() {
-        // The reference's `jg -> accept` edge: a longer prefix wins outright, distance irrelevant.
+        // The reference's `jg` accept: a longer prefix wins at any distance.
         assert!(prefix(5, 900.0).beats(prefix(3, 1.0)));
         assert!(!prefix(3, 1.0).beats(prefix(5, 900.0)));
         // Equal prefix length falls through to strictly-nearest.
diff --git a/crates/benilla-app/src/target/click.rs b/crates/benilla-app/src/target/click.rs
index 8c784f85..c637f7fc 100644
--- a/crates/benilla-app/src/target/click.rs
+++ b/crates/benilla-app/src/target/click.rs
@@ -1,37 +1,18 @@
-//! The click/USE router — the input half of targeting: a clean left-click selects the
-//! [`super::Hovered`] unit, a clean right-click dispatches the context action (attack, NPC
-//! interact, GameObject USE with the lock/refusal ladder), and the UI's selection asks
-//! (`TargetUnit` / `AssistUnit` / `TargetLastEnemy`) + Esc drain into the same
-//! [`super::Selection`]. Split from `mod.rs` (which keeps the state resources and the plugin)
-//! along the state-vs-input seam; the systems here are registered by [`super::TargetPlugin`] in
-//! the target chain after the hover picks and the cursor classifier.
+//! The click router: a clean left-click selects, a clean right-click takes the context action,
+//! and the UI's selection asks and Esc commit into the same [`super::Selection`].
 
 use benilla_ui::script::SelectionRequest;
 
 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 /
-/// 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
-///   the "right-click dismisses the held item/spell" behavior.
-/// - released over a **world object**: no payload change at all — `0x492ce0` clears only the
-///   displayId-PREVIEW gate (`[0xb4b41c]`, an arm benilla doesn't carry) and INTERACT proceeds
-///   normally in the systems that follow, item or spell still on the cursor.
-///
-/// The left-click legs live in the UI engine's world drop ([`benilla_ui::script`]'s
-/// `world_drop_click`, routed by the app-fed pick — decisions 0218/0571/0574); that press is
-/// consumed when it would drop, so no `WorldClick` fires for them. The put-down sound rides the
-/// app's cursor-transition watcher (`crate::sound`), matching the ref's `ClearCursor` play.
+/// The right-click payload leg of the reference's click router (`0x481f60`, clean clicks only,
+/// `0x514ae0`): over terrain (`0x492c90`) or nothing (`0x492d30`) any payload clears, silently.
+/// Over a world object this keeps every payload; the reference's object leg `0x492ce0` there
+/// clears one that sets `[0xb4b41c]` (mode 5 vendor row, mode 7 bar item, mode 9 ammo).
 pub(super) fn world_right_click_payload(
     mut right_clicks: MessageReader<WorldRightClick>,
-    // The **press** pick, not the live hover (decision 2230) — this leg and [`act_on_right_click`]
-    // are two halves of one click's routing, so they must classify the same pick or a right-click
-    // can dismiss the cursor payload *and* interact with the thing it was held over.
+    // The press pick: this leg and [`act_on_right_click`] must classify the same pick.
     press: Res<PressPick>,
     script: Option<NonSendMut<UiScript>>,
 ) {
@@ -47,28 +28,10 @@ pub(super) fn world_right_click_payload(
     script.clear_cursor_payload();
 }
 
-/// **A plate click is a click on its unit** — the plate's own click slot (`0x7cb910`) ends in the
-/// same `SetSelection` a click on the body does (decision 2148).
-///
-/// It **carries its own unit** rather than reading the press pick, and that is the whole design:
-/// pfUI's click-through calls `plate:Click("LeftButton")` with the cursor wherever the player left
-/// it (`nameplates.lua:1274`), so a plate click that depended on the hover would work under the
-/// mouse and silently do nothing for the addon it exists to serve. The first cut of this system
-/// replayed a [`WorldClick`] and was guarded on the press pick naming the same unit; the live probe
-/// caught it — the scripted click selected nothing.
-///
-/// The RIGHT button is the other way round, deliberately. [`act_on_right_click`] acts on the
-/// frame's [`PressPick`] across many legs (interact, attack, loot, GameObject), so feeding it a
-/// unit that pick does not name could attack the wrong thing; it is replayed only when the press
-/// pick already names the plate's unit. A scripted right-click on a plate does nothing yet, which
-/// is a stated gap rather than a guess about which leg it should take.
-///
-/// Since 2233 the **physical** right-click on a plate comes through here, and this is the only path
-/// it has: the press is the plate's (the camera no longer looks through one), so no look session
-/// starts and the camera arbiter emits no [`WorldRightClick`] of its own. The plate's click slot
-/// fires on the up edge and the replay below turns it into the interact leg — which is the
-/// reference's own shape, `0x7cb910` → `0x4949f0(mask 4)` → `0x492820`, the same terminal the world
-/// right-click's object leg `0x492ce0` reaches.
+/// A plate click is a click on its unit (the click slot `0x7cb910`). The left button carries the
+/// plate's unit, as a scripted `plate:Click()` (pfUI, `nameplates.lua:1228`) has no cursor; the
+/// right replays [`WorldRightClick`] only when the press pick names it, so a scripted one does
+/// nothing yet. A physical right-click arrives only here: `0x7cb910` → `0x4949f0` → `0x492820`.
 pub(super) fn select_on_plate_click(
     mut plate: ResMut<crate::vplates::PlateClicks>,
     press: Res<PressPick>,
@@ -84,7 +47,6 @@ pub(super) fn select_on_plate_click(
         std::mem::take(&mut plate.left),
         std::mem::take(&mut plate.right),
     );
-    // The ground-targeting cursor owns the click, exactly as it does for a world one (0792).
     if ground.active() {
         return;
     }
@@ -96,11 +58,9 @@ pub(super) fn select_on_plate_click(
         let Ok((guid, store)) = units.get(entity) else {
             continue; // the unit left between the click and this frame
         };
-        // The NPC greets us on the SELECT gesture, plate or body — the byte-verified trigger fires
-        // before SetTarget either way (`0x60c270`).
+        // The greeting fires on the select, plate or body, before SetTarget (`0x60c270`).
         greeting.write(crate::sound::NpcGreetingRequest { npc: entity });
-        // The attack classification is the press pick's, and only when the press was actually on
-        // this unit: a scripted click has no cursor behind it, so it is not an attack-cursor click.
+        // Attack-classified only when the press was on this unit: a scripted click has no cursor.
         let attack = press.attack() && press.hovered.target == Some(entity);
         scan::commit(
             &mut selection,
@@ -118,18 +78,9 @@ pub(super) fn select_on_plate_click(
     }
 }
 
-/// On a [`WorldClick`], select the unit the **press** was over ([`PressPick`]) and inform the
-/// server; a click on empty ground / a non-unit clears the target — except a click on NOTHING (sky
-/// — no occlusion-ray hit) while a payload is held: the reference's nothing-leg deselect is
-/// no-payload-gated (`0x492d30`'s local flag test), while the terrain leg deselects regardless of a
-/// surviving spell/action payload (`0x5e03bb` — decisions 0571 + 0574). Skipped while the inspector
-/// is armed (left-click is its copy affordance).
-///
-/// **The press pick, not the live hover** (decision 1122). A click may now arrive at the end of a
-/// gesture that orbited the camera, and the live hover is empty by then — `update_hover` clears it
-/// for the whole look session, as the reference suppresses its own hover during freelook. Reading
-/// the live hover here would take the `_ =>` arm below and *clear* the player's target on every
-/// drag. The reference picks once, on the down edge, and this consumes that same latch.
+/// On a [`WorldClick`], select the press pick's unit or deselect on empty world, except on nothing
+/// (the sky) with a payload held (`0x492d30`); the terrain leg deselects regardless (`0x5e03bb`).
+/// The press pick, since the hover is empty through a camera drag, as in the reference's freelook.
 pub(super) fn select_on_click(
     mut clicks: MessageReader<WorldClick>,
     inspect: Res<InspectMode>,
@@ -141,21 +92,15 @@ pub(super) fn select_on_click(
     mut greeting: MessageWriter<crate::sound::NpcGreetingRequest>,
     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
-    // the object at the *commit*, not at the down edge.
+    // Read at the commit, where the reference resolves it for `0x493540`'s `IsSelectable` gate.
     stores: Query<&ObjectStore>,
 ) {
     let (hovered, occlusion) = (press.hovered, press.occlusion);
-    // Drain the frame's clicks; act only if there was one and the inspector isn't holding left-click.
     let clicked = clicks.read().last().is_some();
     if !clicked || inspect.enabled {
         return;
     }
-    // The ground-targeting cursor owns the click (decision 0792): the ref's terrain leg tries
-    // the ground commit BEFORE its select/deselect half and skips it when the commit fires
-    // (`0x492580`'s "otherwise"). The commit system runs after this one in the chain, so the
-    // mode is still readable here — selection changes not at all, in range or out.
+    // The ground cursor owns the click (`0x492580`); its commit system runs after this one.
     if ground.active() {
         return;
     }
@@ -165,17 +110,10 @@ 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 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
-            // same NPC steps the variation sequence; the sound crate holds the per-unit latch (a
-            // re-click while the line still sounds is silent) and resolves non-NPCs to nothing.
+            // The greeter `0x60c270` runs before SetTarget, so on the left-click select only; every
+            // click fires it, so a re-click steps the variation.
             greeting.write(crate::sound::NpcGreetingRequest { npc: entity });
-            // The one SetSelection law ([`scan::commit`]): dedup + selection + the engaged-switch
-            // stop→select→re-swing. The cursor's Attack classification (alive + reaction ≤
-            // neutral, hover-refreshed every frame) IS Attack `0x5ecb70`'s new-target validation.
+            // The cursor's Attack classification is `0x5ecb70`'s new-target validation.
             scan::commit(
                 &mut selection,
                 &mut seam,
@@ -187,27 +125,11 @@ pub(super) fn select_on_click(
                 press.attack(),
             );
         }
-        // Clicked nothing targetable → deselect (only sends the clear if we actually had a
-        // target). The one exception is a payload held over NOTHING (sky): the ref's
-        // nothing-leg deselect is no-payload-gated. Since 0843 ANY payload's empty-world left
-        // press is consumed for the drop/dismiss (input.rs's `would_drop`), so a payload
-        // normally never reaches this arm at all — the gate still holds the nothing-leg law
-        // for the residual GameObject-hover case (`Object` pick, unit arm empty).
-        // `deselectOnClick` (0961) gates the whole arm: "Sticky Targeting" checked = the CVar
-        // at 0 = an empty-world click keeps the target (1.12's own inverted checkbox).
+        // Deselect, except on the sky with a payload held (reachable only over a GameObject, as a
+        // payload's empty-world press is the drop's); `deselectOnClick` 0 keeps the target.
         _ => {
-            // A **corpse** is an object hit, not empty world (decision 1723): the reference's
-            // deselect lives in the terrain and nothing legs, and an object leg clears no
-            // selection — so a left-click on a body must leave the target exactly where it was.
-            // Without this the corpse would arrive here (its guid is in the other slot) and read
-            // as "clicked nothing", dropping the player's target every time they clicked a body.
-            //
-            // **A REFUSED pick is the same kind of object hit** (decision 2060). The hover grader
-            // `0x4828d0` takes the mouseover away from a `NOT_SELECTABLE` unit, but the *click*
-            // never went through it: the down-edge pick `0x481f00` still found the object, so the
-            // release takes the object leg `0x4925d0`, whose tail `0x49280c call 0x493540` hits
-            // `SetSelection`'s own `IsSelectable` early-out and returns having changed nothing.
-            // Selecting is refused; deselecting was never on the table.
+            // A corpse or a refused unit is an object hit, which never deselects: the down-edge
+            // pick `0x481f00` still finds a `NOT_SELECTABLE` unit, and `0x493540` refuses it.
             if hovered.corpse.is_some() || hovered.refused {
                 return;
             }
@@ -218,133 +140,62 @@ pub(super) fn select_on_click(
     }
 }
 
-/// The service arms that are **not** a bare packet, as one [`SystemParam`] (the 16-param ceiling).
-///
-/// 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 (`0x5f0130`'s ladder).
+/// The service arms that are not a bare packet, bundled for the 16-param ceiling.
 #[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
-    /// predicate `0x5df490` reads off the TARGET.
+    /// The last `SMSG_QUESTGIVER_STATUS` per guid (`[unit+0xcb8]`), read by bit 1's `0x5df490`.
     pub(crate) quest: Res<'w, crate::ui_quest::QuestGiver>,
-    /// The innkeeper's bind question (bit 7): `0x5dfdc0` caches the guid and fires `CONFIRM_BINDER`
-    /// — `CMSG_BINDER_ACTIVATE` belongs to the dialog's Accept, not to the click.
+    /// Bit 7: `0x5dfdc0` fires `CONFIRM_BINDER`; `CMSG_BINDER_ACTIVATE` is the dialog's Accept.
     pub(crate) binder: ResMut<'w, crate::ui_binder::BinderState>,
-    /// The spirit healer's XP-loss question (bit 5): `0x5df730` does the same, firing
-    /// `CONFIRM_XP_LOSS`.
     pub(crate) death: ResMut<'w, crate::death::DeathNet>,
-    /// The spirit GUIDE's arm (bit 6) — the battleground graveyard's resurrect wave. Unlike its
-    /// two no-packet neighbours this one does send, and it sends through the cache the per-frame
-    /// proximity poll also writes, so the click and the poll cannot disagree about which healer
-    /// is current.
+    /// Bit 6 sends through the cache the proximity poll writes, so the two agree on the healer.
     pub(crate) spirit: ResMut<'w, crate::ui_dialog_verbs::AreaSpiritHealer>,
-    /// `[0xb4e2d0]/[0xb4e2d4]`'s mirror — the NPC whose window is open, which the dispatcher
-    /// compares the clicked guid against *before* the ladder ([`interaction_already_open_on`]).
+    /// The NPC whose window is open (`[0xb4e2d0]`), checked before the ladder.
     pub(crate) interact: Res<'w, crate::ui_session::InteractNpc>,
-    /// The cursor, for the vendor arm's fork (`0x5df5d7`) — peeked to choose the arm's leg, then
-    /// taken through the **sell** clear once the sale actually goes out. `Option` because a
-    /// headless net-only build mounts no VM.
+    /// The cursor, for the vendor arm's sell fork (`0x5df5d7`); `None` when no VM is mounted.
     pub(crate) script: Option<NonSendMut<'w, benilla_ui::script::UiScript>>,
 }
 
-/// **The re-click gate** — `0x5f0130`'s own, at `0x5f0251`/`0x5f025c`, sitting between the range
-/// test and the ladder:
-///
-/// ```text
-/// 5f024c  8b 46 08            mov edx,[esi+8] → [eax]   ; the CLICKED unit's guid
-/// 5f0251  3b 15 d0 e2 b4 00   cmp edx,[0xb4e2d0]        ; the interaction NPC, low
-/// 5f0257  75 0f               jne 0x5f0268              ; different → on to the ladder
-/// 5f025c  3b 05 d4 e2 b4 00   cmp eax,[0xb4e2d4]        ; high
-/// 5f0262  0f 84 62 03 00 00   je  0x5f05ca              ; SAME → the silent return
-/// ```
-///
-/// 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, 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
-/// resource rather than growing a second latch — the mailbox and the item-text reader are the two
-/// arming sites it leaves out, and neither is a unit a right-click can land on.
+/// The re-click gate (`0x5f0251`), before the ladder: a right-click on the NPC whose window is
+/// open (`[0xb4e2d0]`) does nothing, no packet, no error, no gesture. The reference arms that NPC
+/// only from window openers (`0x4930d0`, cleared at `0x493310`), never on the click, the set
+/// [`crate::ui_session::feed_interact_npc`] collapses (less the mailbox and text reader).
 fn interaction_already_open_on(target: u64, interact: &crate::ui_session::InteractNpc) -> bool {
     interact.1 == Some(target)
 }
 
-/// 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 (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
-///   live vendor shares): open the corpse's loot (`CMSG_LOOT`), decision 0084.
-/// - **Interact** on an in-range friendly service NPC: the reference's own first-match-wins ladder
-///   over `UNIT_NPC_FLAGS` ([`service_arm`] → [`service_action`], decision 1861) — bit 0 GOSSIP
-///   first, so a trainer or questgiver that also carries the bit still opens a menu and only a
-///   flagless one opens its own window (1865). A click that lands on the NPC whose window is
-///   already open is eaten before any of it ([`interaction_already_open_on`], 1905). On a taken
-///   arm our avatar plays EmoteTalk (id 60), which stows the weapon via the anim→sheath reconcile.
-///
-/// The cursor's own gate grays a service beyond `SERVICE_RANGE` (`unable`); we don't send then (no
-/// auto-approach yet) — the selection still lands. Attack, by contrast, is never range-gated
-/// (`unable` only grays): the server holds the swing until we're in reach, as the real client does.
-/// A right-click on empty ground was just a turn — it never deselects.
-// The `ui_feedback` tuple is the 16-SystemParam ceiling's overflow bundle, commented at its site.
+/// On a clean right-click, select the press pick's unit and act by the cursor's classification
+/// (the INTERACT leg `0x492820`): a GameObject, a corpse, an attack, loot, skin, or the
+/// `UNIT_NPC_FLAGS` ladder ([`service_arm`]). The range gray (`unable`) suppresses every send but
+/// attack, which the server holds until in reach; there is no auto-approach yet.
+// `ui_feedback` is the overflow bundle past the 16-SystemParam ceiling.
 #[allow(clippy::type_complexity)]
 pub(super) fn act_on_right_click(
     mut clicks: MessageReader<WorldRightClick>,
-    // **The press pick, not the live hover** (decision 2230) — the same latch the left button has
-    // read since 1122, and for the same reason: the reference picks exactly once, on the down edge
-    // (`0x481f00`, one caller image-wide), into the WorldFrame's own slots, and nothing re-picks on
-    // move or on release. Reading the live hover here only looked right because the release frame
-    // re-picks at the restored cursor and, for a body click that moved nothing, lands back on the
-    // same unit. A V-plate has no body under the cursor to land back on: the plate published the
-    // mouseover at the press (`0x7cb850` → `0x492890`), freelook then took the plates' mouse away
-    // (`0x60f830`), and the live hover at the release was empty — so a right-click on a plate
-    // reached every branch below with nothing hovered and did nothing at all.
+    // The press pick: the reference picks once, on the down edge (`0x481f00`).
     press: Res<PressPick>,
     mut selection: ResMut<Selection>,
     mut seam: crate::creature_anim::AttackSeam,
     self_player: Query<(Entity, &Guid, Has<Engaged>), With<SelfPlayer>>,
-    // The interact talk gesture. The reference's NPC-interact dispatcher calls the SAME gesture
-    // entry point the chat display path does, always with code 0 — so this goes through
-    // `creature_anim::gesture` rather than writing a raw AnimID, and inherits its gate chain
-    // (decision 1469; before that it played unconditionally, even asleep or mid-combat).
+    // Through `creature_anim::gesture`, the chat path's entry, as the reference's dispatcher does.
     mut gestures: ResMut<crate::creature_anim::GestureQueue>,
-    // The GameObject lock-routing inputs (decisions 0239 / 0545 / 0752) as one [`GoLockInputs`]
-    // (the 16-SystemParam ceiling).
     mut go_inputs: GoLockInputs,
     player_actions: Res<crate::ui_action::PlayerActions>,
-    // `[0xb700e4]`'s mirror — the skin leg's spell, already gated by the classifier (0752).
+    // The skin leg's spell (`[0xb700e4]`), already gated by the classifier.
     learned: Res<crate::ui_action::LearnedAbilities>,
-    // The GO leg needs the object's stored state too (the Action gate, decision 0752); the unit
-    // legs ignore the second member.
+    // The GameObject leg also reads the object's anim state (the Action gate).
     stores: Query<(&ObjectStore, Option<&crate::go_anim::GoAnim>)>,
-    // One tuple param (the 16-SystemParam ceiling): the red-error keys + the reason-coded cast
-    // line (the opener cast's local totem refusal, decision 0552) + the loot-target latch
-    // the loot branch arms (decision 0515), and the mailbox session the mailbox branch opens
-    // (decision 0544).
-    // The three non-packet service arms (decision 1861), bundled — see [`ServiceArms`].
     mut service: ServiceArms,
     ui_feedback: (
         ResMut<crate::ui_action::UiErrorKeys>,
         ResMut<crate::ui_action::CastErrors>,
         ResMut<crate::ui_loot::LootLatch>,
         ResMut<crate::ui_mail::MailOpen>,
-        // The reader session the TEXT branch opens (decision 1105) — like the mailbox, a
-        // client-side window with no packet behind it.
         ResMut<crate::ui_item_text::ItemTextOpen>,
-        // The GameObject opener's one-frame queue (decision 2199): this system cannot hold
-        // `CastLadder` (it would reach `Items`/`CastErrors` twice), so the lock chain's verdict
-        // travels to `ui_action::drain::drain_go_openers` instead of becoming a packet here.
+        // The opener queue: this system cannot also hold `CastLadder` (a second `Items` and
+        // `CastErrors` borrow), so the lock verdict goes to `ui_action::drain::drain_go_openers`.
         ResMut<crate::ui_action::GoOpenerCasts>,
-        // The meeting stone's use slot (decision 2283), here for the same reason: its four
-        // refusals read the roster and the template cache, so the click hands the object to
-        // `ui_dialog_verbs::drain_meeting_stone_joins` rather than validating and sending here.
+        // The stone's refusals need the roster, so they run in `drain_meeting_stone_joins`.
         MessageWriter<crate::ui_dialog_verbs::MeetingStoneUse>,
     ),
 ) {
@@ -360,42 +211,20 @@ pub(super) fn act_on_right_click(
     if clicks.read().last().is_none() {
         return;
     }
-    // The whole ladder below reads ONE pick — the gesture's own, frozen at the press.
     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": 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
-    // scope. This is that third family (decision 1851): the right-click interact dispatchers read
-    // the very same field, in their own ladders, and until now we read it in none of them.
+    // The reference's one mounted predicate, the player's `UNIT_FIELD_MOUNTDISPLAYID`.
     let self_store = self_player
         .single()
         .ok()
         .and_then(|(e, _, _)| stores.get(e).ok())
         .map(|(s, _)| s);
     let self_mounted = self_store.is_some_and(|s| s.0.unit_mount_display_id() != 0);
-    // 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: **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 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.
+    // A GameObject is used, never falling through to units: `OnUse 0x5f8660` gates on
+    // highlightable (our `Point` cursor, silent), then usable (`0x5f3130`), whose lock arm toasts
+    // first, even out of range. Out of range (`unable`) this shows nothing; the reference shows
+    // `ERR_USE_TOO_FAR` (`0x5f874b`) unless its auto-walk `0x610300` starts (`AutoInteract` on).
     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`
-        // the server answers with — and until this line existed only the *taken* branches said
-        // anything, at `debug!`, which the hardcoded log filter keeps off. Both silent refusals are
-        // traced here: a `Point` cursor (the reference's highlightable no-op) and `unable` (the
-        // range gray, which suppresses the send with no toast). Pairs with the `fx` kit lines, so
-        // ONE run says which link is dead instead of one round-trip per link.
+        // Traced (tag `use`): a `Point` cursor and the range gray both refuse silently here.
         if benilla_assets::trace::enabled_for("use") {
             let ty = hovered_object
                 .target
@@ -417,40 +246,11 @@ pub(super) fn act_on_right_click(
                     .target
                     .and_then(|e| stores.get(e).ok())
                     .map(|(s, anim)| (s, crate::go_anim::go_state(anim, s)));
-                // ── The GameObject leg's OWN mounted gate — not the cast validator's ────────
-                // The strategy's usable predicate `0x5f3130` carries a mounted arm of its own at
-                // `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.
-                //
-                // **It applies only to LOCK-LESS objects.** The gate sits behind
-                // `0x5f3195 call 0x5f8180` / `0x5f319c jne 0x5f3231`, which resolves the object's
-                // **Lock.dbc row** and skips the whole thing when one exists. So a mining node, a
-                // 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 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 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`
-                // equality, no table, no range). TEXT is NOT exempt — the reference refuses a sign
-                // from horseback even though its opener is every bit as client-side as the
-                // mailbox's, which is why this sits ABOVE both local-open branches below.
-                //
-                // Silent by Blizzard's omission, not our choice: `ERR_NOT_WHILE_MOUNTED` is one of
-                // 1.12.1's orphan keys with no GlobalStrings value, and both of `DisplayError`'s
-                // 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
-                // binary could not settle — it wants one mounted click on a sign.
+                // The GameObject's own mounted gate (`0x5f31a8`) returns before the opener: no
+                // packet, no cast. It applies only without a Lock.dbc row (`0x5f8180`, a pointer
+                // test, so an all-empty row counts, unlike `LockCatalog::is_locked`); a locked
+                // object is refused by its opener cast. Only MAILBOX is exempt (`0x5f31bb`).
+                // Silent: the key has no text or sound, and `0x4945b0` drops the empty string.
                 let lock_id = go_inputs.templates.get(guid).map_or(0, |t| t.lock_id);
                 let has_lock_row = lock_id != 0
                     && go_inputs
@@ -464,11 +264,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 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).
+                // MAILBOX (type 19) opens locally: its use handler `0x5f6820` sends no
+                // `CMSG_GAMEOBJ_USE`, and `MAIL_SHOW` → `CheckInbox` asks for the list.
                 if go.is_some_and(|(s, _)| s.0.gameobject_type_id() == cursor_mode::GO_TYPE_MAILBOX)
                 {
                     if !cursor.unable {
@@ -477,18 +274,8 @@ pub(super) fn act_on_right_click(
                     }
                     return;
                 }
-                // TEXT (GO type 9): a book, plaque or sign — READ it, client-side, before the lock
-                // 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). 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.
-                //
-                // `arg2 == 0` here means the reference's **toggle**: right-clicking the book whose
-                // reader is already open closes it. The page id + material are NOT resolved here —
-                // the reader asks the object's template for them as it paints, like the reference's
-                // `vtbl+0x74` getter, so a click that beats the ask-once template query still opens.
+                // TEXT (type 9) opens locally (`0x5f58c0` → `0x4e32e0(goGuid, 0)`; vmangos' `Use`
+                // has no type-9 case); a re-click closes it, and the page is read at paint time.
                 if go.is_some_and(|(s, _)| s.0.gameobject_type_id() == cursor_mode::GO_TYPE_TEXT) {
                     if !cursor.unable {
                         if item_text.toggle_closed(guid) {
@@ -500,26 +287,10 @@ pub(super) fn act_on_right_click(
                     }
                     return;
                 }
-                // 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). 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
-                // every meeting stone dead here: vmangos' `GameObject::Use` has an explicit
-                // 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; 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
-                // exempted there) and behind the same `unable` range suppression every sending
-                // arm takes. The refusals themselves need the roster, the ask-once template and
-                // the wire, which this system cannot also hold, so the verdict travels as a
-                // message to `ui_dialog_verbs::drain_meeting_stone_joins` — the 2199 shape.
+                // MEETINGSTONE (type 23) has its own use slot `0x5f69d0`: four client-side
+                // refusals, then `CMSG 0x292 {u64 goGuid}` (`0x4c9ff0`), never `CMSG_GAMEOBJ_USE`,
+                // whose type-23 arm in vmangos does nothing (`GameObject.cpp:1836`). Types 9, 19,
+                // 23 and 28 override the shared sender `0x5f33e0`.
                 if go.is_some_and(|(s, _)| {
                     s.0.gameobject_type_id() == cursor_mode::GO_TYPE_MEETINGSTONE
                 }) {
@@ -529,12 +300,7 @@ pub(super) fn act_on_right_click(
                     }
                     return;
                 }
-                // Branch on the lock (decisions 0239 / 0545 / 0752): a lockless GameObject is USEd;
-                // a lockable one casts the opener (a known OPEN_LOCK spell, or a carried key's own
-                // 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).
+                // By lock: used, opened by its opener cast, or refused locally (`0x5f3427..`).
                 match resolve_go_action(
                     guid,
                     &mut go_inputs,
@@ -555,15 +321,8 @@ pub(super) fn act_on_right_click(
                         }
                         let _ = seam.net.0.send(ClientCommand::GameObjUse { guid });
                     }
-                    // **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`) 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
-                    // the bar of the cast that is still running. The local reagent/totem and
-                    // mounted checks that used to stand here are ladder rungs; they ran here only
-                    // because this arm could not reach the ladder at all.
+                    // Both opener arms queue for the one cast path, as the reference reaches
+                    // `TryCast 0x6e4b60` from the use sender (`0x5f35c0`) like a button press.
                     GoAction::OpenLock(spell_id) => {
                         debug!("right-click gameobject open-lock: cast {spell_id} at {guid:#x}");
                         openers.0.push(crate::ui_action::GoOpener::Spell {
@@ -579,8 +338,6 @@ pub(super) fn act_on_right_click(
                         openers.0.push(crate::ui_action::GoOpener::Key(it));
                     }
                     GoAction::Refuse(err) => {
-                        // `None` is a case the ref is silent on too (a key-item record miss —
-                        // its ask-once query is away — or the deferred key-in-hand open).
                         debug!("right-click gameobject {guid:#x}: locked, refused ({err:?})");
                         if let Some(err) = err {
                             ui_error_keys.0.push(err);
@@ -591,29 +348,14 @@ pub(super) fn act_on_right_click(
         }
         return;
     }
-    // ── The corpse leg: `CGCorpse_C`'s own interact slot, `0x5d6bf0` (vtable `+0x60`) ───────────
-    // A corpse is not a unit and never routes through the unit block below — the reference gives
-    // its class a *different* function in the same slot the unit class fills with `0x60bea0`.
-    // Transcribed from the disassembly at `0x5d6bf0..0x5d6cdd`, which has exactly two legs:
-    //
-    //   1. `[player descriptor + UNIT_FIELD_MOUNTDISPLAYID] <= 0` (**not mounted**, `0x5d6c2a jg`)
-    //      AND `0x5d6e20(corpse)` (**lootable** — `CORPSE_FIELD_DYNAMIC_FLAGS` bit 0) → a player-
-    //      state check on the vtable `+0xa4` slot, which on failure raises message `0x85` and
-    //      sends nothing; else `SetAutoLoot` (`0x5df460`) and then `0x5df130` — **`CMSG_LOOT`**.
-    //   2. else `CORPSE_FIELD_FLAGS` bit 5 (the PvP insignia) AND the `[0xb700e8]`
-    //      SKIN_PLAYER_CORPSE learn latch AND `!0x6067d0(player, corpse)` → the skin cast
-    //      (`0x5f05e0`). Unreachable without that latch, and nothing in 1.12.1 sets it.
-    //
-    // **Neither leg touches your own body**, which carries neither flag — the function runs and
-    // does nothing at all. Recovering your corpse is a separate route (decision 0308's
-    // `RECOVER_CORPSE` → `CMSG_RECLAIM_CORPSE`) whose click path is out for RE and is NOT
-    // guessed at here; the director reports a right-click on their own body raising the resurrect
-    // prompt, so a route exists and this function is not it.
+    // ── The corpse leg, `CGCorpse_C`'s interact slot `0x5d6bf0` ──
+    // Leg 1: not mounted and lootable (`CORPSE_FIELD_DYNAMIC_FLAGS` bit 0) → a stand-state check,
+    // `SetAutoLoot` (`0x5df460`) and `CMSG_LOOT` (`0x5df130`). Leg 2: `CORPSE_FIELD_FLAGS` bit 5,
+    // the `[0xb700e8]` latch (never set in 1.12.1) and an unfriendly corpse (`!0x6067d0`) → the
+    // skin cast (`0x5f05e0`). Your own corpse takes neither: the resurrect prompt comes from the
+    // 40 yd `CORPSE_IN_RANGE` poll (`0x492130`), never a click.
     if let (Some(entity), Some(guid)) = (hovered.corpse, hovered.corpse_guid) {
         let store = stores.get(entity).ok().map(|(s, _)| s);
-        // The same one-line answer the GameObject leg gives (tag `use`): a corpse's click is three
-        // silent refusals deep — no flag, the range gray, the missing latch — and every one of them
-        // otherwise looks identical from the outside. One run says which.
         if benilla_assets::trace::enabled_for("use") {
             benilla_assets::trace::line(
                 "use",
@@ -627,21 +369,10 @@ pub(super) fn act_on_right_click(
                 ),
             );
         }
-        // **Leg 1's first conjunct is `!mounted`** (`0x5d6c2a jg`, the player's MOUNTDISPLAYID read
-        // one test before the lootable one). The block comment above has named this conjunct since
-        // the leg was transcribed and the code never carried it — a rider could loot bones from the
-        // saddle. A mounted click is **not** an error here: it falls through to leg 2 exactly as the
-        // unit dispatcher falls through to skin, and since no 1.12.1 player has the insignia latch,
-        // what the rider actually gets is silence.
+        // A rider fails leg 1 (`0x5d6c2a jg`) with no error and falls to leg 2, silently.
         if !self_mounted && store.is_some_and(|s| s.0.corpse_lootable()) {
-            // **`GetStandState() != 0` refuses before the send** (`0x5d6c3b call [playerVtbl+0xa4]`
-            // = `0x5ed570`, non-zero → `0x496720(0x85)`): sitting, kneeling or asleep, the click
-            // raises the client-local red **`ERR_LOOT_NOTSTANDING`** as a `UI_ERROR_MESSAGE` and
-            // sends nothing. Client-local, so the line shows even where the server would also have
-            // refused — and unlike the range gray it is loud, because the player can fix it.
-            // No longer scoped to the corpse leg: 1851 read the unit dispatcher's own copy
-            // (`0x60bfb7` → `0x60c007 push 0x85`) off the same fork and built it too, so the
-            // "unverified here" caveat this comment carried since 1729 is retired.
+            // Not standing: the client-local red `ERR_LOOT_NOTSTANDING`, no packet (`0x5d6c3b` →
+            // `GetStandState 0x5ed570`, non-zero → `0x496720(0x85)`).
             let standing = self_store.is_none_or(|s| s.0.unit_stand_state() == 0);
             if !standing {
                 debug!("right-click corpse loot: refused, not standing ({guid:#x})");
@@ -650,28 +381,20 @@ pub(super) fn act_on_right_click(
                     .push(crate::ui_action::UiError::key("ERR_LOOT_NOTSTANDING"));
                 return;
             }
-            // Range rides the cursor's own gray, exactly as the unit loot branch does —
-            // the classifier and the click ask literally the same question, so the pouch can never
-            // be lit on something a click refuses.
+            // Range rides the cursor's gray, so the pouch is never lit where the click refuses.
             if !cursor.unable {
                 debug!("right-click corpse loot: {guid:#x}");
                 let _ = seam.net.0.send(ClientCommand::Loot { guid });
-                // Same client-side prediction as the unit corpse (decision 0515): the reference's
-                // `CMSG_LOOT` sender arms `[player+0x1d28]` and kneels before any reply.
+                // Predicted, as for a unit corpse (`[player+0x1d28]` armed at the send).
                 loot_latch.0 = Some(guid);
             }
         } else if store.is_some_and(|s| s.0.corpse_pvp_insignia()) {
-            // Leg 2, with its real precondition. `skin_player_corpse` is the mirror of `[0xb700e8]`
-            // and is `None` for every 1.12.1 player, so this is inert for the reference's own
-            // reason rather than by omission.
+            // Leg 2. `skin_player_corpse` mirrors `[0xb700e8]`, `None` for every 1.12.1 player,
+            // so this is inert as in the reference; the unfriendly test is not built.
             if let Some(spell_id) = learned.skin_player_corpse {
                 if !cursor.unable {
-                    // Same TryCast funnel as the unit skin leg, so the same mounted block — and
-                    // this is the leg a mounted bones-click FALLS INTO, which makes the gate here
-                    // the difference between "nothing happens" and a rider yanking insignias.
-                    // The record comes off [`GoLockInputs`]'s catalog because that bundle is this
-                    // system's only handle on `Spells` and the param list is at the 16 ceiling —
-                    // the bundle is named for its first tenant, not scoped to it.
+                    // The cast's mounted check, where a mounted click lands; the record comes off
+                    // [`GoLockInputs`]' catalog, this system's only `Spells` handle.
                     let def = go_inputs
                         .spells
                         .as_ref()
@@ -696,21 +419,10 @@ pub(super) fn act_on_right_click(
     };
     let attack = cursor.kind == cursor_mode::CursorKind::Attack;
     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 (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`
-    // reads `[ecx+0x1fc]` off the *player's* descriptor block — the one still in `ecx` from
-    // `0x60bee5` — and `jg 0x60c01f` skips the whole loot leg for a mounted player, landing on the
-    // skin leg. That is a **fall-through, not a refusal**: no packet, no red line, no "You are
-    // mounted". The cast and attack families of this same gate (0481) each announce themselves;
-    // this one is silent, which is exactly why it could sit here unbuilt without ever looking
-    // broken from the inside.
-    // Step 0 of the fork, hoisted because the trace prints it too: a corpse the dispatcher will
-    // actually treat as one.
+    // ── The dead-target fork of the unit dispatcher `0x60bea0` ──
+    // Loot routes by classification (dead and `UNIT_DYNFLAG_LOOTABLE`), not the cursor kind, whose
+    // Pickup(8) a live vendor shares. A rider skips the loot leg for the skin leg (`0x60bf98`),
+    // silently. Step 0 of [`DeadUnitLeg`] is hoisted for the trace.
     let dead_fork = target.is_some_and(|s| s.0.unit_is_dead() && !s.0.unit_dynflag_dead());
     let leg = dead_unit_leg(
         self_mounted,
@@ -719,9 +431,6 @@ pub(super) fn act_on_right_click(
         target.is_some_and(|s| s.0.unit_flags() & cursor_mode::UNIT_FLAG_SKINNABLE != 0),
         learned.skinning.is_some(),
     );
-    // The unit twin of the GO/corpse legs' one-line answer (tag `use`). Every refusal on this
-    // ladder is silent from the outside — the range gray, the mounted fall-through, a corpse
-    // somebody else owns — and they are indistinguishable on screen. One run says which.
     if benilla_assets::trace::enabled_for("use") {
         benilla_assets::trace::line(
             "use",
@@ -735,8 +444,8 @@ pub(super) fn act_on_right_click(
                 } else if dead_fork {
                     leg.tag()
                 } else {
-                    // The alive branch (`0x60c162`): `CanInteract` → the service send. Not this
-                    // fork's to name, and NOT mounted-gated — a rider talks to a flight master.
+                    // The alive branch (`0x60c162`), not mounted-gated: a rider talks to a
+                    // flight master.
                     "service"
                 },
                 cursor.kind,
@@ -745,10 +454,7 @@ pub(super) fn act_on_right_click(
         );
     }
     let me = self_player.single().ok();
-    // The one SetSelection law ([`scan::commit`]): dedup + selection + the engaged-switch
-    // stop→select→re-swing. The Attack cursor kind is Attack `0x5ecb70`'s new-target validation
-    // (alive + reaction ≤ neutral) — a mid-combat click on a vendor/corpse switches and stops,
-    // it never swings at them.
+    // A mid-combat click on a vendor or corpse switches and stops, never swings (`0x5ecb70`).
     let outcome = scan::commit(
         &mut selection,
         &mut seam,
@@ -761,50 +467,23 @@ pub(super) fn act_on_right_click(
     );
     match unit_branch(attack, dead_fork, leg) {
         UnitBranch::Attack => {
-            // The actor-eligibility block — **silent here**, and that is 1851 correcting 0481. The
-            // click still SELECTED (the commit above already ran, the ref's select-then-refuse order)
-            // 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. 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
-            // the click, and the fix is not to delete six of them but to move where they are asked
-            // for. [`attack_actor_blocked`] is the same ladder with the message removed; the bar keeps
-            // [`attack_actor_refusal`]. (The predicate is still `0x612df0`'s and not `0x5ecb70`'s own
-            // overlapping set — a separate slice — but the SILENCE is the verified law, and the swing
-            // is suppressed either way.)
+            // Silent after the select: the click's `0x60c247 call 0x5ecb70` has no `DisplayError`,
+            // and the red `ERR_ATTACK_*` lines are `0x612df0`'s (the Attack action, pet attack,
+            // TryCast). The predicate is `0x612df0`'s; `0x5ecb70`'s own set is not transcribed.
             if crate::ui_action::attack_actor_blocked(self_store, me.map(|(_, g, _)| g.0)).is_some()
             {
-                // refused — selection stands, no swing, and nothing is said
+                // refused: the selection stands, no swing, nothing said
             } else {
                 debug!("right-click attack: {guid:#x}");
-                // The right-click's own StartAttack, through the one seam (auto-draw + the swing +
-                // the auto-repeat cancel — `0x5ecb70`'s whole body). The commit above may already
-                // have re-pointed the swing at this guid, in which case the ref's `0x5eccda` is the
-                // thing that suppresses a second send, so pass it the real lock state and let the
-                // seam decide: `swung` means the re-swing already went out and the lock is ours, so
-                // no stop is in flight any more.
+                // `0x5ecb70`'s body through the seam; `swung` means the commit's re-swing already
+                // went out, which `0x5eccda` keeps from sending twice.
                 let engaged = me.is_some_and(|(_, _, e)| e);
                 seam.start(guid, engaged || outcome.swung, false);
             }
         }
         UnitBranch::Dead(DeadUnitLeg::Loot) => {
-            // A dead unit carrying UNIT_DYNFLAG_LOOTABLE (the Pickup loot cursor, decision 0084): open
-            // its loot (`CMSG_LOOT`). Range-gated like the interact branch — the cursor grays a corpse
-            // beyond the melee interact reach (`unable`), and we don't send then (no auto-approach yet).
-            // No EmoteTalk: looting is not an NPC interaction, the corpse plays no talk.
-            //
-            // **The unit leg's own stand-state gate** (`0x60bfb7 call [playerVtbl+0xa4]`, non-zero →
-            // `0x60c007 push 0x85; call DisplayError 0x496720`) — the exact instruction pair the corpse
-            // leg carries at `0x5d6c3b`/`0x496720(0x85)`, in the same fork, one test after the lootable
-            // one. The corpse leg's comment has said since 1729 that "the unit loot branch's own copy of
-            // it is unverified here"; it is the same `push 0x85` and the same virtual, read off the same
-            // dispatcher this session's `0x60bf98` mounted gate came out of. So the caveat retires and
-            // the two legs say the same thing: sitting, kneeling or asleep, the click raises the
-            // client-local red `ERR_LOOT_NOTSTANDING` and sends nothing.
+            // `CMSG_LOOT`, no talk gesture; the stand-state check (`0x60bfb7` → `0x60c007 push
+            // 0x85`) matches the corpse leg's.
             if self_store.is_some_and(|s| s.0.unit_stand_state() != 0) {
                 debug!("right-click loot: refused, not standing ({guid:#x})");
                 ui_error_keys
@@ -813,23 +492,15 @@ pub(super) fn act_on_right_click(
             } else if !cursor.unable {
                 debug!("right-click loot: {guid:#x}");
                 let _ = seam.net.0.send(ClientCommand::Loot { guid });
-                // The kneel is client-predicted AT THE SEND: the real client's `CMSG_LOOT` sender
-                // (`0x5df253`) sets the loot-target latch `[player+0x1d28]` and plays Loot 50 before
-                // any server response (decision 0515). Arm the latch the anim driver's loot leg
-                // reads for the self unit; the release/refusal drops it.
+                // Predicted at the send, as the reference's sender (`0x5df253`) arms
+                // `[player+0x1d28]` and kneels before any reply; the anim driver reads the latch.
                 loot_latch.0 = Some(guid);
             }
         }
         UnitBranch::Dead(DeadUnitLeg::Skin) => {
-            // A dead SKINNABLE corpse the loot leg declined (`0x60c01f`): cast our known Skinning spell
-            // at it — the unit-side mirror of the GO lock split (0239; decision 0437's gathering
-            // finish). The spell comes from the reference's own learn-time latch
-            // ([`crate::ui_action::LearnedAbilities`] = `[0xb700e4]`, decision 0752), which is the same
-            // thing the classifier gated the Skin cursor on. Ordinarily that means an unlootable
-            // corpse; **while mounted it also means a still-lootable one**, and the cast then meets the
-            // cast family's own mounted gate (`0x6094f0`'s reason `0x39`) and says "You are mounted" —
-            // the one leg of this dispatcher where the rider is told anything at all.
-            // Range rides the cursor's melee-reach gray, like loot.
+            // The skin leg (`0x60c01f`): the known Skinning spell (`[0xb700e4]`) at a corpse the
+            // loot leg declined, lootable ones included while mounted. Its cast mounted check
+            // (`0x6094f0`, reason `0x39`) is the one place a rider is told anything.
             if !cursor.unable {
                 if let Some(spell_id) = learned.skinning {
                     let def = go_inputs
@@ -849,35 +520,14 @@ pub(super) fn act_on_right_click(
                 }
             }
         }
-        // **The silent leg — and it is TERMINAL.** That is the whole of decision 1858. A dead
-        // unit whose fork declined both legs (a rider over a lootable corpse; a corpse someone
-        // else killed; a skinnable one without the skill) is DONE: the reference reaches its
-        // NPC-service dispatch only down the ALIVE branch (`0x60c162`), never off the back of
-        // this fork.
-        //
-        // benilla wrote the fork as an `if/else if` chain whose LAST arm was the service send, so
-        // "the dead fork chose nothing" fell through into "this is a live service NPC" — and that
-        // arm dispatches on the CURSOR kind, which over a lootable corpse is `Pickup`, the mode
-        // the vendor pouch also uses ([`interact_command`]). The click therefore sent
-        // `CMSG_LIST_INVENTORY` at a dead wolf, and vmangos answers a non-vendor with
-        // `SELL_ERR_CANT_FIND_VENDOR` (`ItemHandler.cpp:701-710` → `GetNPCIfCanInteractWith` →
-        // `CanInteractWithNPC`'s npc-flag and `IsAlive` tests), which this client renders as the
-        // red **"That merchant doesn't like you."** on an animal corpse.
+        // Terminal: a dead unit that took no leg does nothing; only the alive branch (`0x60c162`)
+        // reaches the service dispatch.
         UnitBranch::Dead(DeadUnitLeg::Nothing) => {
             debug!("right-click unit {guid:#x}: dead fork took no leg — nothing sent");
         }
         UnitBranch::Service if !cursor.unable => {
-            // An in-range friendly service NPC (the cursor already gated friendly + service +
-            // range): run **the reference's own ladder over `UNIT_NPC_FLAGS`** ([`service_arm`]).
-            //
-            // Not the cursor's kind, which is what this dispatched on until decision 1861. The
-            // reference runs two structurally identical ladders — one for the cursor
-            // (`0x482336`), one for the send (`0x5f0289`) — and the cursor MODE is a lossy
-            // projection of the winning bit: eight arms collapse to Speak(6) and two to Buy(3),
-            // so a kind-keyed dispatch cannot tell a banker from an auctioneer, nor a trainer
-            // from an innkeeper from a spirit healer. It sent `CMSG_GOSSIP_HELLO` for all eight.
-            // `0x5f0251` — the click that lands on the NPC we are already talking to is eaten
-            // whole, before the ladder and before the gesture (decision 1905).
+            // The reference's own `UNIT_NPC_FLAGS` ladder (`0x5f0289`), not the cursor kind, which
+            // its cursor ladder (`0x482336`) projects lossily; the re-click gate comes first.
             if interaction_already_open_on(guid, &service.interact) {
                 debug!(
                     "right-click interact: {guid:#x} — its window is already open, nothing sent"
@@ -888,16 +538,9 @@ pub(super) fn act_on_right_click(
                 .get(entity)
                 .map(|(s, _)| s.0.unit_npc_flags())
                 .unwrap_or(0);
-            // The vendor fork's input, resolved before the arm is known because it is cheap and
-            // because `service_action` must stay pure. **Peeked, not taken**: the cursor is only
-            // cleared once the sale is actually chosen, so a click on a trainer while holding an
-            // item leaves the item where it is.
-            //
-            // The reference addresses the packet with the cursor's own stored guid; we carry
-            // `(bag, slot)` and resolve it, exactly as the merchant window's sell route does. A
-            // pickup LOCKS the source slot rather than emptying it, so the guid is there in every
-            // ordinary case; if it ever is not, the fork simply does not arm and the click opens
-            // the list instead — the benign side of a divergence we cannot avoid.
+            // Peeked, not taken: the cursor clears only once a sale goes out. The reference sends
+            // the cursor's stored guid; we resolve the held `(bag, slot)`, which a pickup locks,
+            // and a slot with no guid opens the list instead.
             let cursor_sale = service
                 .script
                 .as_deref()
@@ -909,9 +552,7 @@ pub(super) fn act_on_right_click(
                     })
                 });
             let Some(arm) = service_arm(npc_flags, service.quest.status(guid)) else {
-                // `0x5f05ca` — a unit that reaches the ladder and matches no consulted bit
-                // (repair-only, or a questgiver with nothing on offer) does nothing at all, and
-                // takes no gesture with it.
+                // `0x5f05ca`: no consulted bit does nothing, gesture included.
                 debug!("right-click interact: {guid:#x} matches no service bit — nothing sent");
                 return;
             };
@@ -928,8 +569,7 @@ pub(super) fn act_on_right_click(
                 ServiceAction::SellFromCursor(cmd) => {
                     debug!("right-click interact: {guid:#x} (vendor — selling the held item)");
                     let _ = seam.net.0.send(cmd);
-                    // Now the cursor goes, through the SELL clear: `CURSOR_UPDATE` fires and the
-                    // source slot stays greyed until the server's inventory update takes it away.
+                    // The sell clear: the slot stays greyed until the server's update.
                     if let Some(script) = service.script.as_deref_mut() {
                         script.take_cursor_item_for_sale();
                     }
@@ -966,77 +606,42 @@ pub(super) fn act_on_right_click(
                     debug!("right-click interact: {guid:#x} ({arm:?}) — silent: {why}");
                 }
             }
-            // Talk at the NPC — on **every taken arm**, including the ones that send nothing:
-            // the reference calls the gesture after the arm's handler RETURNS, not after a send
-            // (each arm of `0x5f0130` ends `call 0x60bb30(0)` then `ret 8`). The gesture's own
-            // anim carries WeaponFlags `0x10`, so the per-animation sheath reconcile stows a drawn
-            // weapon — a committed change that persists after the talk (decisions 0080/0081).
+            // Talk on every taken arm, silent ones too (each arm of `0x5f0130` ends `call
+            // 0x60bb30(0)`); the anim's WeaponFlags `0x10` stows a drawn weapon for good.
             if let Some((_, my_guid, _)) = me {
                 gestures.push(my_guid.0, crate::creature_anim::Gesture::Talk);
             }
         }
-        // The classifier's own range gray on a LIVE service NPC — outside the 5.5556 yd service
-        // reach the click sends nothing (there is no auto-approach yet), exactly as the loot and
-        // skin legs ride the same `unable`.
+        // Beyond the 5.5556 yd service range nothing is sent (no auto-approach yet).
         UnitBranch::Service => {}
     }
 }
 
-/// The right-click action a hovered GameObject resolves to (decisions 0239 / 0545 / 0752) — chosen
-/// by its lock, through the shared chain in [`super::lock`].
+/// The right-click action for a hovered GameObject, chosen by its lock ([`super::lock`]).
 pub(crate) enum GoAction {
-    /// No lock (or no lock data): `CMSG_GAMEOBJ_USE` — door / lever / quest object / mailbox /
-    /// unlocked chest.
+    /// No lock, or no lock data: `CMSG_GAMEOBJ_USE`.
     Use,
-    /// A lock we can open with a **known skill spell**: cast it at the object — a known
-    /// `OPEN_LOCK` (chest / vein / herb / a picked lock). `CMSG_CAST_SPELL`.
+    /// A lock a known skill spell opens (`OPEN_LOCK`): cast it at the object.
     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; 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.
+    /// A satisfied key slot: use the key at the object, `CMSG_USE_ITEM` targeting it (the cast
+    /// sender `0x6e54f0` takes its item arm), since the server honours a key slot only with
+    /// `m_CastItem` set (`Spell.cpp:7892`). `on_object` is the lock's guid.
     OpenByKey(crate::ui_items::ItemUse),
-    /// 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.
+    /// An unopenable lock: the client-local refusal, `None` where the reference is silent too.
     Refuse(Option<crate::ui_action::UiError>),
 }
 
-/// What we know about a key-item lock slot's key when routing a refusal ([`route_lock_refusal`]).
+/// A key-item slot's key, when routing a refusal ([`route_lock_refusal`]).
 enum KeyFact {
-    /// Not held; the item template names it ("Requires Shadowforge Key").
+    /// Not held, and the template names it ("Requires Shadowforge Key").
     Named(String),
-    /// 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.
+    /// Not held and uncached: silent, like the reference's record miss (`0x5f3562`).
     Unknown,
 }
 
-/// Resolve a hovered GameObject's right-click action from its lock — the reference's USE sender
-/// `0x5f33e0` over the shared resolver (decisions 0239 / 0545 / **0752**).
-///
-/// Not-yet-queried or no `Lock.dbc` → treat as lockless (`Use`): the stream-in query makes "not
-/// cached" a rare race, and `Use` is both the correct lockless action and a harmless no-op on a
-/// 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 (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
-/// 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: the client never sends a bare CMSG_CAST_SPELL for a key lock (the cast sender
-/// `0x6e54f0` takes its item arm).
+/// A hovered GameObject's action from its lock, the reference's use sender `0x5f33e0` over the
+/// resolver [`super::lock::resolve_lock`] (`0x5f83d0`) the cursor's `usable` also asks. An uncached
+/// template or no `Lock.dbc` counts as lockless.
 pub(crate) fn resolve_go_action(
     guid: u64,
     inputs: &mut GoLockInputs,
@@ -1051,8 +656,7 @@ pub(crate) fn resolve_go_action(
     let Some(locks) = inputs.locks.as_deref() else {
         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`.
+    // A lockId with no row is no lock (`0x5f8180` returns null).
     let Some(slots) = locks.0.slots(tmpl.lock_id).filter(|_| tmpl.lock_id != 0) else {
         return GoAction::Use;
     };
@@ -1071,17 +675,12 @@ pub(crate) fn resolve_go_action(
     let key_entry = match outcome {
         super::lock::LockOutcome::Unlocked => return GoAction::Use,
         super::lock::LockOutcome::OpenBySpell(spell_id) => {
-            // The retest instrument for B247 (decision 1312): which of the player's openers this
-            // lock resolved to, by id. The spell's Spell.dbc name is what the cast bar prints, so
-            // reading the id off a probe run is how "the bar says Opening - No Text" becomes a
-            // machine-checkable fact instead of a screenshot.
             debug!("target: lock {} → open by spell {spell_id}", tmpl.lock_id);
             return GoAction::OpenLock(spell_id);
         }
         super::lock::LockOutcome::OpenByKey(entry) => entry,
         super::lock::LockOutcome::Unmet => {
-            // Unopenable — the toast routing of `0x5f3427..`, which keys off Lock.dbc **slot 0**
-            // regardless of which slot the resolver walked.
+            // The toast routing keys off Lock.dbc slot 0, whichever 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) {
@@ -1103,13 +702,9 @@ pub(crate) fn resolve_go_action(
             ));
         }
     };
-    // A key we carry: **use it at the object**. The resolver `0x5f85aa` only hands the caller the
-    // key's ON_USE spell id AND the item object itself; it is the sender `0x6e54f0` that then
-    // discriminates on cast-item-vs-caster and takes the item arm — `0x6e57d8 push 0xab`,
-    // CMSG_USE_ITEM carrying `u8 bag · u8 slot · u8 spellSlot · SpellCastTargets(GO)`, with no raw
-    // spell id at all (the server re-resolves the Item* from bag+slot). Decision 0769.
-    //
-    // So what the wire needs is the key's POSITION, which the same walker that found it gives us.
+    // A key we carry is used at the object: the sender `0x6e54f0` takes its item arm
+    // (`0x6e57d8 push 0xab`), `CMSG_USE_ITEM {u8 bag, u8 slot, u8 spellSlot, targets}` with no
+    // spell id, so the wire needs the key's position.
     let Some(store) = me_store else {
         return GoAction::Refuse(None);
     };
@@ -1119,11 +714,11 @@ pub(crate) fn resolve_go_action(
         key_entry,
         crate::ui_items::ItemSearch::default(),
     ) else {
-        // Held a moment ago (the resolver said so) and gone now — nothing to send.
+        // Held when the resolver ran, gone now: nothing to send.
         return GoAction::Refuse(None);
     };
-    // The template is ask-once — a miss queries and does nothing this click, exactly like the
-    // toast's own name miss. `use_spell_index` is the BLOCK ordinal, the packet's third byte.
+    // An uncached template queries and does nothing this click. `use_spell_index` is the spell
+    // block ordinal, the packet's third byte.
     let Some(tmpl) = inputs.items.template(key_entry, 0, net) else {
         return GoAction::Refuse(None);
     };
@@ -1138,26 +733,16 @@ pub(crate) fn resolve_go_action(
         entry: key_entry,
         spell_index,
         use_spell: tmpl.use_spell.as_ref().map(|u| u.spell_id),
-        // The bound lock — `CGItem::Use`'s own target argument (decision 0769).
         on_object: Some(guid),
         is_charter: tmpl.flags & benilla_protocol::messages::ITEM_FLAG_CHARTER != 0,
     })
 }
 
-/// 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 —
-///    DOOR "The door is locked." / BUTTON "That has already been used." / else "Item is locked."
-/// 2. Flag clear: route by **Lock.dbc slot 0** — key item missing → "Requires <item>" (`0xde`),
-///    skill spell unknown → "Requires <LockType.Name>" (`0xdf`, the "Requires Herbalism" case),
-///    known but under-rank → "Requires <name> <rank>" (`0xe0`, rank = `Skill[0]`, else
-///    GO-level×5), slot-0 type neither → "You can't open that." (`0xda`).
-///
-/// The `"UNKNOWN"` literal is the ref's own missing-LockType-row fallback (`0x838044`). The
-/// `0xd9` chest-in-use pre-check (`0x5f81d0`) is unmodeled — its state is generally unreachable
-/// through our highlightable gate (`GO_FLAG_IN_USE` already excludes the busy chest).
+/// The client-local toast for an unopenable lock (`0x5f3427..`): `GO_FLAG_LOCKED` takes the
+/// strategy default first; otherwise Lock.dbc slot 0 picks `0xde` (key item), `0xdf` (skill
+/// unknown), `0xe0` (under rank: `Skill[0]`, else GO level × 5) or `0xda`. `"UNKNOWN"` is the
+/// reference's missing-LockType fallback (`0x838044`). The chest-in-use check (`0xd9`,
+/// `0x5f81d0`) is not built; `GO_FLAG_IN_USE` already fails the highlightable gate.
 fn route_lock_refusal(
     slot0: &benilla_formats::LockSlot,
     opener_known: bool,
@@ -1197,40 +782,22 @@ fn route_lock_refusal(
     }
 }
 
-/// Which leg the reference's unit interact dispatcher `0x60bea0` takes on a **dead** target — its
-/// `0x60bf75` fork, transcribed. Pure, because every conjunct in it is a fact about two units'
-/// wire state and nothing else, and because the conjunct this project was missing is invisible
-/// from the outside (see [`DeadUnitLeg::Nothing`]).
+/// The dead-target fork (`0x60bf75`) of the unit dispatcher `0x60bea0`, in the reference's order:
 ///
-/// The reference's order, and ours:
+/// 0. a corpse: `HEALTH <= 0` and the feign-death bit `UNIT_DYNFLAG_DEAD` clear, else alive;
+/// 1. the player mounted (`0x60bf98`): straight to the skin leg, silently;
+/// 2. lootable (`0x6003a0`): [`DeadUnitLeg::Loot`];
+/// 3. skinnable (`UNIT_FIELD_FLAGS` bit 26) with Skinning known (`[0xb700e4]`): the skin leg;
+/// 4. otherwise nothing (`0x60c25f`).
 ///
-/// 0. **`0x60bf75`/`0x60bf86` — is it a corpse at all?** `HEALTH <= 0` **and** the target's
-///    `UNIT_DYNFLAG_DEAD` (`[+0x224]` bit 5, the feign-death bit — decision 1022) **clear**; either
-///    failing routes to the alive branch `0x60c162` instead. The caller passes this as `dead`.
-/// 1. **`0x60bf98` — am I mounted?** `mov eax,[ecx+0x1fc]` on the *player's* descriptor block
-///    (`UNIT_FIELD_MOUNTDISPLAYID`, the one mounted signal — decision 0481), `jg 0x60c01f`. A
-///    rider does not loot. It is a jump into the skin leg, not a refusal: nothing is sent and
-///    nothing is said.
-/// 2. **`0x6003a0` — is it lootable?** (`UNIT_DYNFLAG_LOOTABLE`, plus the decay deadline the server
-///    owns.) Yes ⇒ [`DeadUnitLeg::Loot`] and `CMSG_LOOT`.
-/// 3. **`0x60c01f` — is it skinnable?** `UNIT_FIELD_FLAGS` bit 26, on the TARGET, plus the
-///    learn-time latch `[0xb700e4]` that says we know a Skinning spell (decision 0752). Yes ⇒
-///    [`DeadUnitLeg::Skin`] and the skin cast — which, being a cast, meets the mounted gate's cast
-///    face (`0x6094f0`, reason `0x39`) and is where a rider finally gets told something.
-/// 4. Otherwise nothing at all (`0x60c25f`, the bare epilogue).
-///
-/// Note what step 1 does **not** do: it does not consult the target. A lootable-*and*-skinnable
-/// corpse — an already-looted one, which is the common case for a skinner — routes to Skin while
-/// mounted and to Loot on foot, off the same two units.
+/// Step 1 never reads the target: a lootable and skinnable corpse skins mounted, loots on foot.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(super) enum DeadUnitLeg {
     /// `CMSG_LOOT` (`0x60bff7` → `0x5df2a0`).
     Loot,
     /// The skin cast (`0x60c082` → `0x5f05e0`).
     Skin,
-    /// **The silent leg.** No packet, no message, no state write — the dispatcher just returns.
-    /// A mounted click on an ordinary lootable corpse lands here, and that silence is why the
-    /// missing gate looked like working code: the loot window simply opened, as it would on foot.
+    /// The dispatcher returns: no packet, no message, no state write.
     Nothing,
 }
 
@@ -1263,30 +830,19 @@ fn dead_unit_leg(
     }
     DeadUnitLeg::Nothing
 }
-/// **Which branch of `0x60bea0` a right-click on a unit takes** — the dispatcher's own top-level
-/// fork, named so it cannot be fallen out of.
-///
-/// The reference splits on the target's death *first* and never rejoins: the dead side runs
-/// [`dead_unit_leg`]'s three-way ladder and returns, and the NPC-service dispatch hangs off the
-/// ALIVE side alone (`0x60c162`'s `CanInteract` → the service send). An `if/else if` chain that
-/// ends in the service arm gets that wrong in one specific, invisible way — a dead target whose
-/// ladder chose [`DeadUnitLeg::Nothing`] slides into the service arm — which is exactly the bug
-/// decision 1858 was written for. This enum exists so the compiler, not a comment, is what keeps
-/// the two sides apart: the call site matches it exhaustively, so a new [`DeadUnitLeg`] variant
-/// cannot silently acquire a service send.
+/// The branch of `0x60bea0` a unit right-click takes: the reference splits on death first and
+/// never rejoins, so only the alive side (`0x60c162`) reaches the service send.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 enum UnitBranch {
-    /// The Attack cursor's own leg — `0x60c247 call 0x5ecb70` (select, then swing).
+    /// The Attack cursor's leg, `0x60c247 call 0x5ecb70`: select, then swing.
     Attack,
-    /// The dead fork (`0x60bf75`), and its chosen leg. **Terminal in every variant.**
+    /// The dead fork (`0x60bf75`) and its chosen leg; terminal in every variant.
     Dead(DeadUnitLeg),
     /// The alive branch (`0x60c162`): `CanInteract`, then the NPC-service packet.
     Service,
 }
 
-/// [`UnitBranch`], from the two facts that pick it. `attack` first, matching the chain the
-/// dispatcher's callers see: the Attack cursor kind is only ever classified for a LIVE hostile,
-/// so the order is a formality on real data and a defined answer on impossible data.
+/// [`UnitBranch`] from its two facts; `attack` first, which only a live hostile classifies.
 fn unit_branch(attack: bool, dead_fork: bool, leg: DeadUnitLeg) -> UnitBranch {
     if attack {
         UnitBranch::Attack
@@ -1297,65 +853,50 @@ 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. 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
-/// so long. It is not: the projection is lossy. Speak(6) is bits 0, 1, 5, 6, 9, 10, 11 and 13 —
-/// eight arms, two of which send nothing — and Buy(3) is bits 8 and 12. A kind-keyed dispatch
-/// cannot express this ladder, and benilla's sent `CMSG_GOSSIP_HELLO` for all eight Speak arms
-/// (decision 1861).
-///
-/// **First-match-wins is load-bearing**: a GOSSIP+VENDOR NPC sends `CMSG_GOSSIP_HELLO` only, and
-/// a stable master with a menu keeps the menu — which is where 1677's hand-written
-/// `STABLEMASTER && !GOSSIP` conjunct came from. The bit order gives it for free.
+/// The reference's NPC-service ladder, `0x5f0130`'s first-match-wins walk over `UNIT_NPC_FLAGS`,
+/// low bit to high. The cursor classifier `0x482200` walks the same bits but projects them lossily
+/// (Speak is bits 0, 1, 5, 6, 9, 10, 11 and 13; Buy is 8 and 12), so the send keys on the bit.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum ServiceArm {
-    /// bit 0 — `0x5f02a4` → `0x5df4d0`.
+    /// Bit 0: `0x5f02a4` → `0x5df4d0`.
     Gossip,
-    /// bit 1, **and** the target's cached questgiver status ∉ {0, 1} (`0x5f02c0` → `0x5df490`).
+    /// Bit 1, and the target's cached questgiver status ∉ {0, 1} (`0x5f02c0` → `0x5df490`).
     Questgiver,
-    /// bit 2 — `0x5f0317` → `0x5df5d0`.
+    /// Bit 2: `0x5f0317` → `0x5df5d0`.
     Vendor,
-    /// bit 3 — `0x5f034e` → `0x5ed020`.
+    /// Bit 3: `0x5f034e` → `0x5ed020`.
     FlightMaster,
-    /// bit 4 — `0x5f0385` → `0x5df680`.
+    /// Bit 4: `0x5f0385` → `0x5df680`.
     Trainer,
-    /// bit 5 — `0x5f03bc` → `0x5df730`. **Ghost-gated, and sends nothing.**
+    /// Bit 5: `0x5f03bc` → `0x5df730`. Ghost-gated, and sends nothing.
     SpiritHealer,
-    /// bit 6 — `0x5f03f3` → `0x5df950`. **Ghost-gated.**
+    /// Bit 6: `0x5f03f3` → `0x5df950`. Ghost-gated.
     SpiritGuide,
-    /// bit 7 — `0x5f042a` → `0x5dfdc0`. **Sends nothing.**
+    /// Bit 7: `0x5f042a` → `0x5dfdc0`. Sends nothing.
     Innkeeper,
-    /// bit 8 — `0x5f0461` → `0x5dffe0`.
+    /// Bit 8: `0x5f0461` → `0x5dffe0`.
     Banker,
-    /// bit 9 — `0x5f04e3` → `0x5e0060`.
+    /// Bit 9: `0x5f04e3` → `0x5e0060`.
     Petitioner,
-    /// bit 10 — `0x5f051a` → `0x5e00e0`.
+    /// Bit 10: `0x5f051a` → `0x5e00e0`.
     TabardDesigner,
-    /// bit 11 — `0x5f0551` → `0x5e01a0`.
+    /// Bit 11: `0x5f0551` → `0x5e01a0`.
     Battlemaster,
-    /// bit 12 — `0x5f0588` → `0x5e0220`.
+    /// Bit 12: `0x5f0588` → `0x5e0220`.
     Auctioneer,
-    /// bit 13 — `0x5f05bc` → `0x5e02a0`.
+    /// Bit 13: `0x5f05bc` → `0x5e02a0`.
     StableMaster,
 }
 
-/// The ladder itself. `None` = no consulted bit set (`0x5f05ca`) — the click does nothing, and
-/// takes no talk gesture with it. Bit 14 (REPAIR) has no arm in the binary and none here.
-///
-/// The reference re-reads the flags field for a redundant `bits 9 AND 10` block before the plain
-/// bit-9 test; it routes to the same handler bit 9 alone reaches, so it is dead in effect and is
-/// not transcribed (recording it would be a distinction with no outcome).
+/// The ladder; `None` when no consulted bit is set (`0x5f05ca`). REPAIR (bit 14) has no arm, and
+/// the reference's redundant `bits 9 AND 10` test reaches bit 9's handler, so it is omitted.
 pub(crate) fn service_arm(npc_flags: u32, quest_status: Option<u32>) -> Option<ServiceArm> {
     use cursor_mode::npc_flags as f;
     let bit = |m: u32| npc_flags & m != 0;
     Some(if bit(f::GOSSIP) {
         ServiceArm::Gossip
     } else if bit(f::QUESTGIVER) && cursor_mode::questgiver_has_quest(quest_status) {
-        // The SAME predicate the cursor ladder uses at `0x482362`, shared rather than copied so
-        // the two can never disagree about which questgiver is worth talking to.
+        // The cursor ladder's own predicate (`0x482362`), shared so the two cannot disagree.
         ServiceArm::Questgiver
     } else if bit(f::VENDOR) {
         ServiceArm::Vendor
@@ -1386,42 +927,26 @@ pub(crate) fn service_arm(npc_flags: u32, quest_status: Option<u32>) -> Option<S
     })
 }
 
-/// What a taken [`ServiceArm`] does. Three arms are not a packet at all.
+/// What a taken [`ServiceArm`] does.
 pub(crate) enum ServiceAction {
     /// The arm's own opcode.
     Send(ClientCommand),
-    /// The vendor arm's **cursor fork** (`0x5df5d7`): an item is on the cursor, so this click
-    /// sells it rather than opening the list — send, then take the cursor through the sell clear
-    /// ([`benilla_ui::script::UiScript::take_cursor_item_for_sale`]).
+    /// The vendor arm's cursor fork (`0x5df5d7`): sell the held item, then clear the cursor.
     SellFromCursor(ClientCommand),
     /// Raise `CONFIRM_BINDER` locally and send nothing (`0x5dfdc0`).
     AskBinder,
     /// Raise `CONFIRM_XP_LOSS` locally and send nothing (`0x5df730`).
     AskSpiritHealer,
-    /// Adopt this spirit guide as the current-area spirit healer (`0x5df950` → two calls into
-    /// `0x4921c0`, the second of which always transmits) — `CMSG_AREA_SPIRIT_HEALER_QUERY`.
+    /// Adopt this guide as the area's spirit healer; `0x5df950` → `0x4921c0` sends the query.
     AcquireSpiritGuide,
-    /// Nothing goes out. The payload is why, for the debug line.
+    /// Nothing goes out; the payload says why, for the debug line.
     Silent(&'static str),
 }
 
-/// One taken arm → what benilla does about it.
-///
-/// `cursor_sale` is the vendor fork's input: the guid of the **mode-1 item on the cursor**, or
-/// `None` for an empty cursor or any other payload — benilla's resolution of the reference's
-/// `GetCursorItem 0x494c60`, which returns `[0xb4e248]/[0xb4e24c]` only while `[0xb4d900] == 1`.
-///
-/// **The two "spirit" arms are ghost-gated at entry** (`0x5df74a` / `0x5df962`, the byte-identical
-/// `PLAYER_FLAGS` bit 4 test): a LIVING player who right-clicks a spirit healer or spirit guide
-/// carrying no gossip bit gets nothing at all — no packet, no event, no error. That is not an
-/// omission here, it is the reference's own answer.
-///
-/// The `TabardDesigner` and `Battlemaster` arms send their own opcodes (`0x5f051a`'s
-/// `MSG_TABARDVENDOR_ACTIVATE`, `0x5f0551`'s `CMSG_BATTLEMASTER_HELLO`) since decision 1977 —
-/// 1861 had them on the universal gossip greeting while neither window existed; the battleground
-/// list (1974) and the tabard designer (1977) answer the replies now. The tabard arm's one gate
-/// — the shapeshift refusal `ERR_EMBLEMERROR_NOTABARDGEOSET` when the player's displayed model is
-/// not the native one, and the same-vendor no-op — is named, not built (1977's record).
+/// A taken arm → what benilla does. `cursor_sale` is the guid of a mode-1 item on the cursor, as
+/// the reference's `GetCursorItem 0x494c60`. The spirit arms are ghost-gated (`0x5df74a`,
+/// `0x5df962`: `PLAYER_FLAGS` bit 4), silent for the living. The tabard arm's shapeshift refusal
+/// (`ERR_EMBLEMERROR_NOTABARDGEOSET`) and same-vendor no-op are not built.
 pub(crate) fn service_action(
     arm: ServiceArm,
     guid: u64,
@@ -1431,18 +956,14 @@ pub(crate) fn service_action(
     match arm {
         ServiceArm::Gossip => ServiceAction::Send(ClientCommand::GossipHello { guid }),
         ServiceArm::Questgiver => ServiceAction::Send(ClientCommand::QuestgiverHello { npc: guid }),
-        // **The vendor arm is a fork, not a send** (`0x5df5d0`). `0x5df5d7 call 0x494c60` is
-        // `GetCursorItem` — the cursor's own payload guid, answered for **mode 1 only** — and a
-        // non-zero answer takes the arm to `CMSG_SELL_ITEM 0x1a0` instead of the list. Nothing on
-        // either leg tests the merchant window, so this sells to a vendor whose window was never
-        // opened; the re-click gate above is what keeps it from firing when it IS open.
+        // A held item sells (`CMSG_SELL_ITEM 0x1a0`) instead of listing, with no merchant-window
+        // test; the re-click gate stops it while this vendor's window is open.
         ServiceArm::Vendor => match cursor_sale {
             Some(item_guid) => ServiceAction::SellFromCursor(ClientCommand::SellItem {
                 vendor: guid,
                 item_guid,
-                // `xor ecx,ecx` at `0x5df5ee` — the body's `u8 count`, and the client only ever
-                // writes the zero here. Whole stack (vmangos `HandleSellItemOpcode` corroborates
-                // the meaning; the byte is the fact).
+                // Always 0 (`xor ecx,ecx` at `0x5df5ee`): the whole stack
+                // (`ItemHandler.cpp:495`).
                 count: 0,
             }),
             None => ServiceAction::Send(ClientCommand::ListInventory { guid }),
@@ -1451,12 +972,8 @@ pub(crate) fn service_action(
         ServiceArm::Trainer => ServiceAction::Send(ClientCommand::TrainerList { trainer: guid }),
         ServiceArm::SpiritHealer if ghost => ServiceAction::AskSpiritHealer,
         ServiceArm::SpiritHealer => ServiceAction::Silent("spirit healer, and we are alive"),
-        // Ghost-gated like its neighbour. The arm sends `CMSG_AREA_SPIRIT_HEALER_QUERY 0x2E2`
-        // from one call deeper (`0x5df950` → `0x4921c0`), and it does it through the *same*
-        // "set current area spirit healer" routine the per-frame proximity poll uses — with a
-        // deliberate `(0,0)` cache-bust first, so a click on the guide you are already standing
-        // next to re-asks for the wave clock instead of being swallowed by the routine's
-        // unchanged-guid early return.
+        // The query goes through the proximity poll's routine after a `(0,0)` cache bust, so a
+        // click beside the current guide still re-asks for the wave.
         ServiceArm::SpiritGuide if ghost => ServiceAction::AcquireSpiritGuide,
         ServiceArm::SpiritGuide => ServiceAction::Silent("spirit guide, and we are alive"),
         ServiceArm::Innkeeper => ServiceAction::AskBinder,
@@ -1479,13 +996,8 @@ pub(crate) fn service_action(
     }
 }
 
-/// Drain the ESC chain's `ClearTarget()` (the ref's ESC ladder's last close/cancel leg (`ToggleGameMenu` — the ref's
-/// `ToggleGameMenu` order, `UIParent.lua:1492`) and commit the deselect. The target drops ONLY
-/// when nothing earlier in the chain ate the press: a mid-cast ESC cancels the cast instead, an
-/// open window closes instead — the two-press behavior the raw-key clear this replaces couldn't
-/// express (it ran beside the chain, so the first ESC both canceled the cast AND dropped the
-/// target — the director's 0449 report). EditBox precedence rides the chain too: a focused box
-/// consumes ESCAPE before `ToggleGameMenu` ever runs.
+/// Drain `ClearTarget()`, the last leg of the Esc chain (`UIParent.lua:1492`), so the target drops
+/// only when no cast, window or focused edit box took the press first.
 pub(super) fn clear_target_requests(
     script: Option<NonSendMut<benilla_ui::script::UiScript>>,
     mut selection: ResMut<Selection>,
@@ -1493,8 +1005,6 @@ pub(super) fn clear_target_requests(
     engaged: Query<(), (With<Engaged>, With<SelfPlayer>)>,
     mut guid_asks: MessageReader<DeselectGuid>,
 ) {
-    // The engine-side teardown ask (`0x493910(guid, 1)`): a no-op unless the selection IS that
-    // guid — the loot window's move-start close is its one producer today (decision 2097).
     let asked = guid_asks.read().any(|ask| selection.guid == Some(ask.0));
     let Some(mut script) = script else {
         if asked {
@@ -1502,58 +1012,32 @@ pub(super) fn clear_target_requests(
         }
         return;
     };
-    // Both drained every frame: a `||` that short-circuited on `asked` would leave the VM's
-    // ClearTarget flag armed for the next frame and clear whatever was targeted by then.
+    // Both drained every frame: a `||` short-circuiting on `asked` would leave the VM's
+    // ClearTarget flag armed and clear the next frame's target.
     let vm_clear = script.take_target_clear();
     if asked || vm_clear {
         clear(&mut selection, &mut seam, !engaged.is_empty());
     }
 }
 
-/// Ask for the selection teardown **if the selection is this guid** — the reference's
-/// `CGGameUI::SelectionTeardown 0x493910(guid, ecx=1)`, which no-ops unless a selection exists
-/// and equals the argument. The loot window's move-start close raises it for a dead corpse
-/// (`0x48f369`, decision 2097); drained by [`clear_target_requests`], so the attack-stop and the
-/// wire clear stay the teardown's.
+/// A deselect that applies only if the selection is this guid (`0x493910(guid, 1)`), raised by
+/// the loot window's move-start close (`0x48f369`) and drained by [`clear_target_requests`].
 #[derive(bevy::ecs::message::Message, Clone, Copy, Debug)]
 pub(crate) struct DeselectGuid(pub(crate) u64);
 
-/// Drain the UI's **selection asks** — `TargetUnit(token)`, `AssistUnit(token)` and
-/// `TargetLastEnemy()` — and commit each through the shared SetSelection path ([`scan::commit`]).
-///
-/// 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`, 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
-/// in one ordered queue also keeps their relative order, which a macro can observe.
-///
-/// `TargetUnit` callers: the player frame's left-click (`TargetUnit("player")`), the party frames'
-/// (`TargetUnit("partyN")`, decision 0434 phase 5), the TARGETSELF binding. Only tokens resolving
-/// to a STREAMED unit act: `"player"` → our avatar; `"target"` → the current selection (a dedup
-/// no-op); `"partyN"`/`"raidN"` → that roster slot when its entity is in range (an out-of-range
-/// member needs the guid-only selection the phase-4 out-of-range slice owns — until then the click
-/// no-ops, like the real client on a nonexistent unit); `"pet"` → the bar's cached pet guid
-/// (decision 0990, the pet frame's left click); `"targettarget"` → the selection's own
-/// `UNIT_FIELD_TARGET` (decision 1576, the ToT frame's). Everything else (mouseover/name) waits
-/// for its wire.
-///
-/// `AssistUnit` resolves the same token and then runs the shared assist tail
-/// ([`super::by_name::SelectCommit::assist`]) — the basis's own `UNIT_FIELD_TARGET`, which is the
-/// hop `"targettarget"` already makes for the ToT frame. `TargetLastEnemy` skips the token
-/// grammar entirely and reads [`scan::LastEnemy`].
+/// Drain the UI's selection asks in order through the shared SetSelection path. `TargetUnit`
+/// (`0x4899d0`), `AssistUnit` (`0x489b80`) and `TargetLastEnemy` share the reference's helper
+/// `0x489a40`: a resolved unit or a roster member is committed, anything else is a no-op, never a
+/// deselect. Here a token must name a streamed unit, so an out-of-range roster member is a no-op
+/// (the guid-only selection is not built).
 pub(super) fn selection_requests(
     script: Option<NonSendMut<UiScript>>,
-    // The one unit-token resolver (`crate::ui_unit::UnitTokens`) — the arms this drain used to
-    // spell out inline. It is shared with the reach feed precisely so `TargetUnit("target")` and
-    // `CheckInteractDistance("target", …)` can never mean two different units (B304).
+    // The one unit-token resolver, shared with the reach feed so `TargetUnit("target")` and
+    // `CheckInteractDistance("target", …)` name the same unit.
     tokens: crate::ui_unit::UnitTokens,
-    // `TargetLastEnemy`'s memory — `[0xb4e2e8]/[0xb4e2ec]`, stamped by `scan::remember_last_enemy`.
+    // `TargetLastEnemy`'s memory (`[0xb4e2e8]`), stamped by `scan::remember_last_enemy`.
     last_enemy: Res<scan::LastEnemy>,
-    // The one SetSelection tail, shared with `/target` and `/assist` (decision 1583). It carries
-    // the classification too, which is why this drain no longer states one: hand-stating it here
-    // is exactly how a `false` that the binary refutes got written down.
+    // The SetSelection tail shared with `/target` and `/assist`, classification included.
     mut commit: super::by_name::SelectCommit,
     mut assist_by_name: MessageWriter<super::by_name::AssistRequest>,
 ) {
@@ -1566,30 +1050,23 @@ pub(super) fn selection_requests(
     }
     for request in requests {
         match request {
-            // Resolved before the commit borrows the selection mutably. An unstreamed unit — an
-            // out-of-range party member, a despawned pet — resolves to nothing and no-ops.
             SelectionRequest::Unit(token) => {
                 if let Some((entity, guid)) = tokens.resolve(&token, &commit.selection) {
                     commit.commit(entity, guid);
                 }
             }
-            // `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 with no statically recoverable text — the
-            // known deviation `TargetByName` already carries on this path.
+            // `0x489ba9 call 0x515940(token)`, then the shared tail. An unresolvable token is
+            // silent here; the reference shows message `0xb8` `ERR_GENERIC_NO_TARGET` (`0x489c0e`).
             SelectionRequest::Assist(token) => match tokens.resolve(&token, &commit.selection) {
                 Some((basis, _)) => commit.assist(basis, "AssistUnit"),
                 None => info!("assist (AssistUnit): \"{token}\" names nothing; silent no-op"),
             },
-            // `0x489c40` — the `/assist Bob` handler's verb: a player NAME, resolved by the
-            // app's name scan (prefix-ok, players only) the way the slash line always was.
+            // `0x489c40`, `/assist <name>`: a player name, prefix-matched by the app's name scan.
             SelectionRequest::AssistByName(name) => {
                 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**: 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.
+            // `0x489b45` → `0x489a40`. Empty memory is a no-op (the shim `0x489b40` tests nothing),
+            // unlike `TargetLastTarget 0x489b00`, which reaches `0x493540(0,0)` and deselects.
             SelectionRequest::LastEnemy => {
                 let Some(guid) = last_enemy.0 else {
                     info!("TargetLastEnemy: nothing hostile has been targeted yet; no-op");
@@ -1597,9 +1074,7 @@ pub(super) fn selection_requests(
                 };
                 match tokens.held(guid) {
                     Some((entity, guid)) => commit.commit(entity, guid),
-                    // The stale-guid arm: the remembered unit has streamed out or despawned. The
-                    // memory is deliberately kept (the reference never clears its globals either)
-                    // and this is a bare no-op, never a deselect.
+                    // Stale: a no-op, and the memory stays, as the reference never clears it.
                     None => info!(
                         "TargetLastEnemy: {guid:#x} is no longer streamed; target left untouched"
                     ),
@@ -1609,11 +1084,8 @@ pub(super) fn selection_requests(
     }
 }
 
-/// Drop the current target and tell the server (`CMSG_SET_SELECTION` guid 0). A no-op when nothing is
-/// selected, so it never sends a redundant clear. Losing the target also ends melee auto-attack when
-/// one is running (`engaged`, our server-echoed [`Engaged`]): `CMSG_ATTACKSTOP` — the ref stops
-/// swinging and drops the attack stance on Esc/click-off/target-death alike (the stance itself falls
-/// when the `SMSG_ATTACKSTOP` echo removes [`Engaged`]). Weapons *stay drawn* — combat never stows.
+/// Drop the target and send `CMSG_SET_SELECTION` 0 (a no-op with none); when `engaged`, melee
+/// stops too, as on the reference's Esc, click-off or target death. Weapons stay drawn.
 pub(super) fn clear(
     selection: &mut Selection,
     seam: &mut crate::creature_anim::AttackSeam,
@@ -1622,9 +1094,8 @@ pub(super) fn clear(
     if selection.target.take().is_some() {
         selection.guid = None;
         let _ = seam.net.0.send(ClientCommand::SetSelection { guid: 0 });
-        // `SetSelection 0x493540`'s own `0x493a08 call 0x5ecac0` — the real StopAttack, so
-        // losing the target also un-queues a pending on-next-swing strike. It was a bare
-        // `CMSG_ATTACKSTOP` before the seam existed.
+        // `SetSelection 0x493540`'s own `0x493a08 call 0x5ecac0`, the real StopAttack, which
+        // also un-queues a pending on-next-swing strike.
         seam.stop(engaged);
     }
 }
@@ -1633,9 +1104,8 @@ pub(super) fn clear(
 mod tests {
     use super::*;
 
-    /// 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.
+    /// The `0x5f3427..` toast routing on real data: Peacebloom (lock 29: skill slot, LockType 2,
+    /// Skill 0), a rank-155 vein (lock 42: LockType 3), a keyed door, a padlocked chest.
     #[test]
     fn lock_refusals_route_like_the_reference() {
         use benilla_formats::{LockSlot, LOCK_KEY_ITEM, LOCK_KEY_SKILL};
@@ -1691,7 +1161,7 @@ mod tests {
         )
         .unwrap();
         assert_eq!(e.arg_d(), Some(100));
-        // A missing LockType row fills the ref's literal fallback (`0x838044`).
+        // A missing LockType row fills the reference's literal fallback (`0x838044`).
         let e = route_lock_refusal(
             &skill_slot(9999, 0),
             false,
@@ -1703,9 +1173,7 @@ mod tests {
         )
         .unwrap();
         assert_eq!(e.arg_s(), Some("UNKNOWN"));
-        // Key lock, key absent + named → 0xde "Requires %s" with the item name; the template
-        // miss is silent, like the ref (a key we DO hold never reaches the toast at all — the
-        // resolver returns `OpenByKey` and the click casts it, decision 0752).
+        // Key lock, key absent: 0xde "Requires %s" when named, silent when uncached.
         let key_slot = LockSlot {
             key_type: LOCK_KEY_ITEM,
             index: 11000,
@@ -1729,8 +1197,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 (`usable`'s lock
-        // check, `0x5f32a6`): door 0xdc, button 0xdd, chest/else 0xdb — even on a skill lock.
+        // GO_FLAG_LOCKED: the strategy default (`0x5f32a6`), even on a skill lock: door 0xdc,
+        // button 0xdd, else 0xdb.
         for (go_type, key) in [
             (0, "ERR_DOOR_LOCKED"),
             (1, "ERR_BUTTON_LOCKED"),
@@ -1760,41 +1228,34 @@ mod tests {
         assert_eq!(e.key, "ERR_USE_CANT_OPEN");
     }
 
-    /// The dead-target fork of `0x60bea0`, and the conjunct that was missing: **the rider does not
-    /// loot** (`0x60bf98`). The director found it from the saddle, over a Young Wolf, with the loot
-    /// window open — the one shape of bug that never looks like one from inside the client.
+    /// The dead fork's rider test (`0x60bf98`): a mounted player never takes the loot leg.
     #[test]
     fn a_mounted_player_never_takes_the_loot_leg() {
-        // On foot, a lootable corpse loots. This is the control: the fix must not touch it.
+        // On foot, a lootable corpse loots.
         assert_eq!(
             dead_unit_leg(false, true, true, false, false),
             DeadUnitLeg::Loot
         );
-        // Mounted, the same corpse: the loot leg is skipped and, with nothing to skin, the
-        // dispatcher returns having done nothing. Silent — no packet and no red line.
+        // Mounted, the same corpse, nothing to skin: nothing at all.
         assert_eq!(
             dead_unit_leg(true, true, true, false, false),
             DeadUnitLeg::Nothing
         );
-        // Mounted over a corpse that is BOTH lootable and skinnable (an already-looted body a
-        // skinner rides up to): the fall-through reaches the skin leg, which `cursor.kind` alone
-        // could never have routed — the classifier names Skin only on an unlootable corpse.
+        // Mounted over a lootable and skinnable corpse, the fall-through skins.
         assert_eq!(
             dead_unit_leg(true, true, true, true, true),
             DeadUnitLeg::Skin
         );
-        // ...and on foot the very same body loots instead. Step 1 never consults the target.
+        // On foot the same body loots: step 1 never reads the target.
         assert_eq!(
             dead_unit_leg(false, true, true, true, true),
             DeadUnitLeg::Loot
         );
     }
 
-    /// The rest of the fork's ladder, so the mounted conjunct above cannot be "fixed" by
-    /// collapsing a leg it shares with the others.
     #[test]
     fn the_dead_fork_keeps_its_other_three_gates() {
-        // A live unit is not this fork's business at all (`0x60bf75 jg` → the alive branch).
+        // A live unit takes the alive branch (`0x60bf75 jg`).
         assert_eq!(
             dead_unit_leg(false, false, true, true, true),
             DeadUnitLeg::Nothing
@@ -1804,8 +1265,7 @@ mod tests {
             dead_unit_leg(false, true, false, true, true),
             DeadUnitLeg::Skin
         );
-        // The learn-time latch `[0xb700e4]` is the leg's second precondition (0752): a
-        // non-skinner gets nothing on the same corpse.
+        // Without the learn-time latch `[0xb700e4]` the same corpse gives nothing.
         assert_eq!(
             dead_unit_leg(false, true, false, true, false),
             DeadUnitLeg::Nothing
@@ -1818,19 +1278,7 @@ mod tests {
             );
         }
     }
-    /// **The dead fork is TERMINAL** — decision 1858, and the reason a mounted right-click on a
-    /// Young Wolf answered *"That merchant doesn't like you."*
-    ///
-    /// [`dead_unit_leg`] was right; where its `Nothing` WENT was not. The dispatcher's arms were
-    /// an `if/else if` chain ending in the NPC-service send, so a dead target that took no leg
-    /// slid into the arm that dispatches on the CURSOR kind — and a lootable corpse's cursor is
-    /// `Pickup`, the very mode a vendor shows. The click sent `CMSG_LIST_INVENTORY` at the
-    /// corpse, and vmangos answers a non-vendor with `SELL_ERR_CANT_FIND_VENDOR`, which is
-    /// `ERR_VENDOR_HATES_YOU`. Nothing about that was visible in [`dead_unit_leg`], which is why
-    /// 1851's two tests passed over it: they asserted the LEG, and the bug was in the ROUTING.
-    ///
-    /// So this asserts the property rather than the instance — over a dead target, no combination
-    /// of the fork's four inputs may produce [`UnitBranch::Service`].
+    /// No combination of the dead fork's four inputs reaches [`UnitBranch::Service`].
     #[test]
     fn the_dead_fork_never_reaches_the_service_dispatch() {
         for mounted in [false, true] {
@@ -1848,26 +1296,20 @@ mod tests {
                 }
             }
         }
-        // The exact shape the director hit: mounted, over a lootable corpse with no skinning.
+        // Mounted, over a lootable corpse, no skinning.
         let leg = dead_unit_leg(true, true, true, false, false);
         assert_eq!(
             unit_branch(false, true, leg),
             UnitBranch::Dead(DeadUnitLeg::Nothing)
         );
-        // (What that used to fall into: the pouch over a corpse and the pouch over a vendor are
-        // one cursor mode, so the old last arm read the corpse as a shop. The dispatch no longer
-        // consults a cursor kind at all — 1861 — but the fork's terminality is the guarantee that
-        // does not depend on that, so it is the one asserted here.)
-        // A LIVE unit still reaches the service dispatch — the fix must not shut the door on the
-        // branch that is supposed to send.
+        // A live unit still reaches the service dispatch.
         assert_eq!(
             unit_branch(false, false, DeadUnitLeg::Nothing),
             UnitBranch::Service
         );
     }
 
-    /// **The ladder, bit by bit** — decision 1861. Every arm of `0x5f0130`'s first-match-wins walk
-    /// over `UNIT_NPC_FLAGS`, in the order the binary tests them.
+    /// Every arm of `0x5f0130`'s walk over `UNIT_NPC_FLAGS`, in the reference's order.
     #[test]
     fn the_service_ladder_walks_the_reference_bit_order() {
         use cursor_mode::npc_flags as f;
@@ -1895,19 +1337,15 @@ mod tests {
             Some(ServiceArm::Questgiver)
         );
         assert_eq!(service_arm(f::QUESTGIVER, None), None);
-        // No consulted bit — REPAIR (bit 14) has no arm in the binary, so a repair-only NPC does
-        // nothing at all. Neither does an empty field.
+        // REPAIR (bit 14) has no arm, and an empty field matches nothing.
         assert_eq!(service_arm(0x4000, None), None);
         assert_eq!(service_arm(0, None), None);
     }
 
-    /// **First-match-wins, which is the half a kind-keyed dispatch could not express.** The two
-    /// collisions that made the old proxy wrong are the two this pins.
     #[test]
     fn the_service_ladder_is_first_match_wins() {
         use cursor_mode::npc_flags as f;
-        // A gossip-flagged anything keeps its menu — this is where 1677's hand-written
-        // `STABLEMASTER && !GOSSIP` conjunct came from, now free.
+        // Anything gossip-flagged keeps its menu.
         for other in [
             f::VENDOR,
             f::TRAINER,
@@ -1920,20 +1358,18 @@ mod tests {
                 Some(ServiceArm::Gossip)
             );
         }
-        // Banker (bit 8) before auctioneer (bit 12) — both were Buy(3) to the cursor.
+        // Banker (bit 8) before auctioneer (bit 12), both Buy(3) to the cursor.
         assert_eq!(
             service_arm(f::BANKER | f::AUCTIONEER, None),
             Some(ServiceArm::Banker)
         );
-        // Trainer (bit 4) before innkeeper (bit 7) — both were Speak/Interact to the cursor.
+        // Trainer (bit 4) before innkeeper (bit 7).
         assert_eq!(
             service_arm(f::TRAINER | f::INNKEEPER, None),
             Some(ServiceArm::Trainer)
         );
     }
 
-    /// **The three arms that are not a packet**, and the packets the other eleven actually send.
-    /// The eight arms that used to collapse into `CMSG_GOSSIP_HELLO` are the point of this test.
     #[test]
     fn the_service_arms_send_what_the_reference_sends() {
         let sent = |arm, ghost| match service_action(arm, 0x42, ghost, None) {
@@ -1976,14 +1412,12 @@ mod tests {
             service_action(ServiceArm::StableMaster, 0x42, false, None),
             ServiceAction::Send(ClientCommand::ListStabledPets { npc: 0x42 })
         ));
-        // The innkeeper asks, mounted or not, alive or not — and sends nothing.
+        // The innkeeper asks and sends nothing.
         assert_eq!(sent(ServiceArm::Innkeeper, false), "ask-binder");
-        // The two ghost-gated arms: nothing at all for a living player, which is the reference's
-        // own answer and not an omission.
+        // The two ghost-gated arms give a living player nothing, as in the reference.
         assert_eq!(sent(ServiceArm::SpiritHealer, false), "silent");
         assert_eq!(sent(ServiceArm::SpiritGuide, false), "silent");
         assert_eq!(sent(ServiceArm::SpiritHealer, true), "ask-spirit-healer");
-        // The two arms 1861 had on the greeting send their own opcodes since 1977.
         assert!(matches!(
             service_action(ServiceArm::TabardDesigner, 0x42, false, None),
             ServiceAction::Send(ClientCommand::TabardVendorActivate { npc: 0x42 })
@@ -1994,26 +1428,19 @@ mod tests {
         ));
     }
 
-    /// **The vendor arm is a fork, and only the vendor arm** — decision 1914.
-    ///
-    /// `0x5df5d0` asks `GetCursorItem 0x494c60` before anything else, and a mode-1 item on the
-    /// cursor sends `CMSG_SELL_ITEM` instead of `CMSG_LIST_INVENTORY`. What this pins is the
-    /// blast radius: the held item must change the **vendor** arm and **nothing else**, because
-    /// the fork lives inside that one handler and every other arm is reached without ever
-    /// consulting the cursor. A cursor read that leaked into the ladder would sell an item at a
-    /// trainer.
+    /// The sell fork lives in the vendor handler alone (`0x5df5d0`), so no other arm may change
+    /// with the cursor.
     #[test]
     fn only_the_vendor_arm_reads_the_cursor() {
         const VENDOR: u64 = 0xF130_0000_0000_0042;
         const ITEM: u64 = 0x4000_0000_0000_0099;
 
-        // Empty cursor: the plain list open, exactly as before.
+        // Empty cursor: the list opens.
         assert!(matches!(
             service_action(ServiceArm::Vendor, VENDOR, false, None),
             ServiceAction::Send(ClientCommand::ListInventory { guid: VENDOR })
         ));
-        // An item held: the sale, addressed to the CLICKED npc, count 0 = whole stack — and the
-        // variant that carries the cursor clear with it.
+        // An item held: the sale to the clicked NPC, count 0 (the whole stack).
         assert!(matches!(
             service_action(ServiceArm::Vendor, VENDOR, false, Some(ITEM)),
             ServiceAction::SellFromCursor(ClientCommand::SellItem {
@@ -2022,9 +1449,7 @@ mod tests {
                 count: 0,
             })
         ));
-        // Every other arm answers the same held or not. `SellFromCursor` may not appear anywhere
-        // but the vendor arm — that is the property, asserted over the whole enum rather than
-        // over the arms someone remembered to list.
+        // Every other arm answers the same, held or not.
         for arm in [
             ServiceArm::Gossip,
             ServiceArm::Questgiver,
@@ -2063,18 +1488,8 @@ mod tests {
         }
     }
 
-    /// **The re-click gate, and the wiring it rests on** — decision 1905.
-    ///
-    /// The comparison itself is one `==`; what could actually be wrong is the *latch*. The
-    /// reference arms `[0xb4e2d0]` from fourteen window openers and from nothing on the click
-    /// path, so the gate is only ever "a window is open on this NPC" — and benilla reads that
-    /// state off [`crate::ui_session::feed_interact_npc`]'s collapse rather than a latch of its
-    /// own. So this drives the real feed and asserts the property that makes the transcription
-    /// sound: **nothing arms it until a window opens, every NPC window arms it, and the arm names
-    /// the window's own NPC.**
-    ///
-    /// The first click must always get through — that is the half a wrong latch would break, and
-    /// it is asserted first.
+    /// The re-click gate through the real [`crate::ui_session::feed_interact_npc`]: nothing arms
+    /// it before a window opens, a window arms its own NPC, and a close disarms it.
     #[test]
     fn the_reclick_gate_fires_only_while_that_npc_s_window_is_open() {
         use crate::ui_session::{feed_interact_npc, InteractNpc};
@@ -2091,13 +1506,12 @@ mod tests {
             world.remove_resource::<InteractNpc>().unwrap()
         };
 
-        // Nothing open: the FIRST click on any NPC reaches the ladder.
+        // Nothing open: a first click on any NPC reaches the ladder.
         let idle = armed(&|_| {});
         assert!(!interaction_already_open_on(NPC, &idle));
         assert!(!interaction_already_open_on(OTHER, &idle));
 
-        // Each NPC window arms the token with its own NPC — one representative per opener family
-        // (a menu, a quest panel, a specialized window), which is the shape the gate depends on.
+        // One opener per family (a menu, a quest panel, a specialized window) arms its own NPC.
         let with_gossip = armed(&|w| {
             let mut g = crate::ui_gossip::GossipState::default();
             g.npc = Some(NPC);
@@ -2119,21 +1533,19 @@ mod tests {
             ("trainer", &with_trainer),
         ] {
             assert_eq!(armed.1, Some(NPC), "{what} did not arm the npc token");
-            // The re-click on THAT npc is eaten…
+            // A re-click on that NPC is eaten...
             assert!(
                 interaction_already_open_on(NPC, armed),
                 "{what}: the re-click was not suppressed"
             );
-            // …and a click on the NPC beside him is not. A gate that swallowed this would make
-            // every neighbouring vendor unclickable while a window stood.
+            // ...but a click on another NPC is not.
             assert!(
                 !interaction_already_open_on(OTHER, armed),
                 "{what}: the gate ate a click on a different NPC"
             );
         }
 
-        // Closing the window disarms it — the reference's `0x493310` zeroes the pair, and ours is
-        // a collapse, so a cleared session must read through as "clickable again".
+        // Closing the window disarms it, as the reference's `0x493310` zeroes the pair.
         let closed = armed(&|w| {
             let mut t = crate::ui_trainer::TrainerOpen::default();
             t.open(NPC, 0, Vec::new(), String::new());
@@ -2144,17 +1556,8 @@ mod tests {
         assert!(!interaction_already_open_on(NPC, &closed));
     }
 
-    /// **The nothing-leg deselect, and the two object hits that are not it** — `select_on_click`'s
-    /// `_` arm.
-    ///
-    /// The reference's deselect lives in the terrain and *nothing* legs of the world click; an
-    /// **object** leg clears no selection, whatever it then decides to do with the object. Two
-    /// picks reach this arm carrying no `target`: a **corpse** (its guid is in the other slot,
-    /// decision 1723) and a **refused** one (a `NOT_SELECTABLE` unit the hover grader threw away,
-    /// decision 2060 — the click's own down-edge pick `0x481f00` still found the object, so the
-    /// release takes the object leg `0x4925d0` and its tail `0x493540` merely refuses to select).
-    /// Reading either as "clicked the sky" would drop the player's target: click a body mid-fight,
-    /// or click the flagged boss you are standing next to, and your target evaporates.
+    /// A corpse and a refused `NOT_SELECTABLE` unit reach `select_on_click`'s `_` arm with no
+    /// `target`, but are object hits, and only the terrain and nothing legs deselect.
     #[test]
     fn an_object_hit_never_deselects_but_empty_world_does() {
         use crate::net::NetCommands;
@@ -2186,7 +1589,6 @@ mod tests {
                 ..PressPick::default()
             });
             world.spawn(SelfPlayer);
-            // The clean left-click the player controller emits.
             world
                 .resource_mut::<Messages<WorldClick>>()
                 .write(WorldClick);
@@ -2196,13 +1598,11 @@ mod tests {
             world.resource::<Selection>().guid
         };
 
-        // Empty world: the deselect arm, which is the behaviour the guards are carved out of.
         assert_eq!(
             click(Hovered::default()),
             None,
             "clicking the sky deselects"
         );
-        // A corpse.
         assert_eq!(
             click(Hovered {
                 corpse: Some(Entity::PLACEHOLDER),
@@ -2213,7 +1613,6 @@ mod tests {
             Some(HELD),
             "a body is an object hit — the target must survive it"
         );
-        // A refused unit.
         assert_eq!(
             click(Hovered {
                 refused: true,
@@ -2225,18 +1624,9 @@ mod tests {
         );
     }
 
-    /// **The selection queue, end to end** — Lua in, `Selection` out — over the four ways it is
-    /// reachable from a player macro. Every one of them is a shipped binding body: `AssistUnit`
-    /// is ASSISTTARGET's (default `F`), `TargetLastEnemy` is TARGETLASTHOSTILE's (default `G`).
-    ///
-    /// What it pins, claim by claim:
-    /// * `AssistUnit("target")` on a basis that has a target selects **that unit** — the shared
-    ///   assist tail's one hop off `UNIT_FIELD_TARGET`;
-    /// * a basis with **no** target is a silent no-op — the reference's tail bails before any send;
-    /// * a **garbage token** resolves to nothing and is a no-op, never a deselect (`0x489a40`'s
-    ///   arm 3 is a bare `ret`) — and, being reachable from any macro, must not panic;
-    /// * `TargetLastEnemy()` re-selects the remembered guid, and with a **stale** one — the unit
-    ///   despawned or streamed out — leaves the target exactly where it was.
+    /// The selection queue from Lua, through the binding bodies of ASSISTTARGET (`AssistUnit`) and
+    /// TARGETLASTHOSTILE (`TargetLastEnemy`): an empty basis, a garbage token and a stale memory
+    /// are each a no-op (`0x489a40`'s bare `ret`), never a deselect or a panic.
     #[test]
     fn the_selection_queue_runs_assist_and_last_enemy_without_ever_deselecting() {
         use crate::net::NetCommands;
@@ -2297,27 +1687,24 @@ mod tests {
             sel.guid = target.map(|(_, g)| g);
         };
 
-        // Assist the current target: one hop onto ITS target.
+        // Assist the current target: one hop onto its target.
         set(&mut world, Some((basis, BASIS)));
         assert_eq!(run(&mut world, r#"AssistUnit("target")"#), Some(VICTIM));
 
-        // The victim targets nobody — assisting it is a silent no-op, not a deselect.
+        // The victim targets nobody: assisting it is a no-op, not a deselect.
         assert_eq!(run(&mut world, r#"AssistUnit("target")"#), Some(VICTIM));
 
-        // A token that names nothing: a no-op, and above all not a panic.
         assert_eq!(run(&mut world, r#"AssistUnit("nosuchunit")"#), Some(VICTIM));
         assert_eq!(run(&mut world, r#"TargetUnit("nosuchunit")"#), Some(VICTIM));
 
         // TargetLastEnemy with nothing remembered: also a no-op.
         assert_eq!(run(&mut world, "TargetLastEnemy()"), Some(VICTIM));
 
-        // Remember the victim, drop the target, and press it: back onto the victim.
         world.resource_mut::<scan::LastEnemy>().0 = Some(VICTIM);
         set(&mut world, None);
         assert_eq!(run(&mut world, "TargetLastEnemy()"), Some(VICTIM));
 
-        // A STALE memory — the unit despawned, so the guid is in no index. The target stays put;
-        // the reference's helper returns without touching the selection.
+        // A stale memory (the unit despawned, so its guid is in no index) leaves the target alone.
         world.resource_mut::<scan::LastEnemy>().0 = Some(GONE);
         assert_eq!(run(&mut world, "TargetLastEnemy()"), Some(VICTIM));
         set(&mut world, None);
@@ -2328,7 +1715,7 @@ mod tests {
 
     const F_HEALTH: u16 = 22;
     const F_MAXHEALTH: u16 = 28;
-    /// `GAMEOBJECT_TYPE_ID`, absolute field 21 — the store the GO arms fork on.
+    /// `GAMEOBJECT_TYPE_ID`, absolute field 21, which the GameObject arms fork on.
     const GO_TYPE_FIELD: u16 = 21;
     const BOAR: u64 = 0xB0A2;
     const ME: u64 = 0x5E1F;
@@ -2337,7 +1724,7 @@ mod tests {
         ObjectStore(benilla_protocol::ObjectFields::from_pairs(pairs))
     }
 
-    /// Everything [`act_on_right_click`] and the commit under it reach for, and nothing else.
+    /// Everything [`act_on_right_click`] and the commit under it reach for.
     fn right_click_world() -> (World, Entity) {
         let (tx, _rx) = crossbeam_channel::unbounded::<ClientCommand>();
         let mut world = World::new();
@@ -2374,23 +1761,13 @@ mod tests {
         (world, boar)
     }
 
-    /// **A right-click that began on a V-plate acts on that plate's unit** — the bug the director
-    /// reported as "right click on nameplates no longer works", and the reason
-    /// [`act_on_right_click`] reads [`PressPick`] (decision 2230).
-    ///
-    /// The gesture it reconstructs is the whole of it: the plate published the mouseover at the
-    /// press, the press engaged freelook (the camera looks *through* a plate — 2159), freelook
-    /// handed the plates' mouse back (`0x60f830`) so the plate's own `OnClick` never fires and its
-    /// hover goes dark, and `update_hover` blanks the live [`Hovered`] for the whole session. What
-    /// survives all of that is the press latch — and a plate hover leaves **no body under the
-    /// cursor** for the release frame's re-pick to land back on, which is exactly why the live
-    /// hover carried the body case and dropped this one.
+    /// A right-click begun on a plate acts on the plate's unit: [`act_on_right_click`] reads the
+    /// [`PressPick`], and a plate leaves no body under the cursor for a live hover to find.
     #[test]
     fn a_right_click_begun_on_a_plate_acts_on_the_plates_unit() {
         let (mut world, boar) = right_click_world();
-        // The press: the plate's unit is the mouseover (distance 0.0 — topmost UI), classified
-        // Attack. Nothing here is live state; it is the latch, exactly as `latch_press_pick` wrote
-        // it one frame before the look session began.
+        // The press latch as `latch_press_pick` writes it: the plate's unit, distance 0.0
+        // (topmost UI), classified Attack.
         *world.resource_mut::<PressPick>() = PressPick {
             hovered: Hovered {
                 target: Some(boar),
@@ -2414,13 +1791,8 @@ mod tests {
             "the release must act on the unit whose plate the press was over"
         );
     }
-    /// **A meeting stone is JOINED, not USEd** (decision 2283). The GO type's own use slot
-    /// (`0x5f69d0`) replaces the shared `CMSG_GAMEOBJ_USE` sender, so the click must hand the
-    /// object to the join validator and put **no** `0xB1` on the wire — which is what left every
-    /// stone dead, since vmangos' `GameObject::Use` has an explicit do-nothing arm for type 23.
-    ///
-    /// The falsification is the assertion that matters: with the arm removed this test sees a
-    /// `GameObjUse` command and no `MeetingStoneUse` message.
+    /// A meeting stone's own use slot (`0x5f69d0`) replaces the shared sender: the click hands it
+    /// to the join validator and puts no `0xB1` on the wire, which vmangos' type-23 `Use` ignores.
     #[test]
     fn a_right_click_on_a_meeting_stone_joins_it_and_sends_no_gameobj_use() {
         const STONE: u64 = 0x5701;
@@ -2464,8 +1836,8 @@ mod tests {
         );
     }
 
-    /// Out of interact range the click is suppressed with no toast and no packet, exactly as the
-    /// shared arms are (the reference auto-walks instead; `0x610300`, no packet).
+    /// Out of interact range the click sends nothing, like the shared arms; the reference shows
+    /// `ERR_USE_TOO_FAR` unless its auto-walk (`0x610300`) starts.
     #[test]
     fn an_out_of_range_meeting_stone_click_sends_nothing() {
         const STONE: u64 = 0x5702;
diff --git a/crates/benilla-app/src/target/cursor_mode.rs b/crates/benilla-app/src/target/cursor_mode.rs
index 7b3b6dc4..819678a1 100644
--- a/crates/benilla-app/src/target/cursor_mode.rs
+++ b/crates/benilla-app/src/target/cursor_mode.rs
@@ -1,36 +1,7 @@
-//! 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`):
-//! - an **interactable NPC** (service flags, not hostile) → the `UNIT_NPC_FLAGS` service ladder
-//!   (`0x482336..0x4824e3`), lowest bit wins — the full statically-unrolled map is
-//!   [`service_cursor`]. Notably vendor → **Pickup** (the pouch), innkeeper → **Interact**,
-//!   banker/auctioneer → **Buy**; REPAIR (0x4000) is *never consulted* — a repair-only unit falls
-//!   through to the attack/clear leg (real repairers all carry VENDOR too).
-//! - otherwise **loot / skin / attack** keyed on state: dead + `UNIT_DYNFLAG_LOOTABLE` →
-//!   **Pickup or LootAll** — the loot leg's mode is `8 + (keyDown(0) ? 8 : 0)` (`0x48252c`):
-//!   the triple-pouch LootAll(16) while the auto-loot modifier is held, generalized since 0961's
-//!   auto-loot to the EFFECTIVE state (`autoLootDefault` XOR shift — [`loot_cursor`]); dead +
-//!   `UNIT_FLAG_SKINNABLE` → Skin; alive and attackable → Attack.
-//! - **`Unable*` (grayed) by a different gate per mode** (byte-verified): NPC services gray beyond
-//!   **5.5556 yd** (`0x482320`); attack beyond a fixed **10.45 yd** (`0x4826a7`); skin outside the
-//!   melee interact reach `max(reachA + reachB + 1.333, 5.0)` — the 5.0 is a **floor**, not a cap
-//!   (`0x6e3480` for skin; the same formula inline in `CanLootNow 0x5ec110` @ `0x5ec142..0x5ec1c8`
-//!   for loot, center-to-center, boundary-inclusive — director-measured ~5 yd, byte-confirmed).
-//!   Loot *rights* never gray — they gate whether the loot cursor shows at all; the mid-loot state
-//!   block and the open-loot-window able-override are not modeled.
-//!
-//! **Both branch predicates are the reference's own, not thresholds** (decision 1674): the
-//! service/loot split is `CanInteract 0x6067f0` (`0x482310`, via the `CanInteractNow 0x606880`
-//! wrapper) and the sword is `CanAttack 0x606980` (`0x48269a`) — [`super::can_interact`] /
-//! [`super::can_attack`], both byte-verified complete. That matters because each reads
-//! `UnitReaction` in the **player → unit** direction, which answers a reputation-slot faction with
-//! the **at-war bit** and never the standing. The reaction-rank approximation these legs used to
-//! carry read the *other* direction, and drew the sword over every not-at-war neutral faction —
-//! a Cenarion Circle druid, a Booty Bay goblin, an Argent Dawn quartermaster. (The questgiver
-//! bit's own quest-status gate, `0x5df490`, and the auto-loot Pickup/LootAll split, `0x41f8f0`,
-//! both used to be listed here as unmodelled; both are modelled now — [`questgiver_has_quest`],
-//! [`loot_cursor`].)
+//! The world cursor's classifier: the hovered unit, GameObject or corpse resolves to a
+//! [`CursorKind`] as the reference's `CGWorldFrame` classifier does (`0x4828d0`, unit branch
+//! `0x482200`): the NPC service ladder, else loot, skin or attack by state, each grayed by its own
+//! range gate. Loot rights never gray; they decide whether the loot cursor shows at all.
 
 use bevy::prelude::*;
 
@@ -39,58 +10,47 @@ use crate::net::{ObjectStore, Reputations, SelfPlayer};
 use super::ring::Factions;
 use super::{go_is_nearest, Hovered, HoveredObject};
 
-/// The blp-name set of world cursor modes benilla can currently trigger (named off the client's own
-/// mode table `0x853b8c` — the strings are the `Interface\Cursor\<Name>.blp` stems).
+/// The world cursor modes benilla shows, named by the reference's mode table (`0x853b8c`), whose
+/// strings are the `Interface\Cursor\<Name>.blp` stems.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum CursorKind {
     Point,
     Attack,
     Speak,
-    /// Pickup(8) — the vendor's pouch AND the loot leg's base mode.
+    /// Pickup(8): the vendor's pouch and the loot leg's base mode.
     Pickup,
-    /// LootAll(16) — the loot leg's triple pouch while the EFFECTIVE auto-loot is on
-    /// (`autoLootDefault` XOR the held shift, 0961's own rule — in 1.12 the held key alone was
-    /// the whole mechanism, `8 + (keyDown(0) ? 8 : 0)` @ `0x48252c`). Loot only: the vendor
+    /// LootAll(16): the loot leg's triple pouch while the effective auto-loot is on; the vendor
     /// pouch never triples.
     LootAll,
-    /// Interact(5) — the generic gear. A GameObject base type's cursor when it carries no
-    /// data-named cursor (a door, button, chest, keyed/keyless lock, fishing, …); also the
-    /// innkeeper service.
+    /// Interact(5): the gear, for a GameObject with no data-named cursor and for the innkeeper.
     Interact,
     Buy,
-    /// 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(7): the UI's Ctrl-hover cursor (`ShowInspectCursor 0x48ac60`) and the world cursor
+    /// over a readable TEXT(9) GameObject (`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 0x4fbcc0`'s locked mode), overlaid by
-    /// [`crate::cursor`].
+    /// Repair(17): never set by the world classifier; the UI's repair-mode base cursor
+    /// (`ShowRepairCursor 0x4fbcc0`).
     Repair,
-    /// Mail(15) — a MAILBOX(19) / RITUAL(18) / type-28 GameObject (the shared
-    /// `0x5f6840`/`0x5f6e30` behavior). The mailbox's own cursor, not the gear.
+    /// Mail(15): a MAILBOX(19) or type-28 GameObject (`0x5f6840`, `0x5f6e30`).
     Mail,
-    /// Mine(11) — a GameObject whose lock's first `LockType` is Mining (3). A LockType.dbc
-    /// data-named cursor (`0x5f3070`), resolved off the GO's lock, not a fixed type.
+    /// Mine(11): a GameObject whose lock's first `LockType` is Mining (3), named by LockType.dbc
+    /// (`0x5f3070`).
     Mine,
-    /// GatherHerbs(13) — a GameObject whose lock's first `LockType` is Herbalism (2). Also a
-    /// LockType.dbc data-named cursor.
+    /// GatherHerbs(13): the same, for Herbalism (2).
     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** (`0x5f3070`: `LockType.Id == 1` skips
-    /// the usable gate), since any rogue can attempt the lock.
+    /// PickLock(14): the same, for Pick Lock (1); never grayed, since `0x5f3070` skips the usable
+    /// gate for `LockType.Id == 1`.
     PickLock,
-    /// 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).
+    /// Cast(2): the spell-targeting cursor (`0x4820f0`), which pre-empts the whole object
+    /// classifier while a spell awaits a target; the classifier here never sets it.
     Cast,
 }
 
 impl CursorKind {
-    /// The cursor's BLP stem in `Interface\Cursor\` (the client's mode-name table strings).
+    /// The cursor's BLP stem in `Interface\Cursor\`.
     fn name(self) -> &'static str {
         match self {
             CursorKind::Point => "Point",
@@ -114,9 +74,8 @@ impl CursorKind {
     }
 }
 
-/// The resolved world cursor for this frame — what the OS cursor should show. Written by
-/// [`classify_cursor`] (after hover), read by [`crate::cursor`]'s platform drivers. `unable`
-/// selects the grayed `Unable<Name>` twin (`mode + 20` in the client's enum — out of range).
+/// This frame's world cursor, written by [`classify_cursor`]; `unable` picks the grayed
+/// `Unable<Name>` twin (the reference's `mode + 20`).
 #[derive(Resource, Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) struct WorldCursor {
     pub(crate) kind: CursorKind,
@@ -133,7 +92,7 @@ impl Default for WorldCursor {
 }
 
 impl WorldCursor {
-    /// The BLP file stem (`Attack` / `UnableAttack` / …) — the key the platform cursor caches use.
+    /// The BLP stem (`Attack`, `UnableAttack`), the key the platform cursor caches use.
     pub(crate) fn stem(&self) -> String {
         if self.unable && self.kind != CursorKind::Point {
             format!("Unable{}", self.kind.name())
@@ -143,13 +102,8 @@ impl WorldCursor {
     }
 }
 
-/// Vanilla `UNIT_NPC_FLAGS` bits (vmangos `UnitDefines.h`, 1.12 values — later expansions differ).
-/// REPAIR (0x4000) exists but the classifier never consults it (falls `je 0x4826cb`).
-/// `pub(crate)` so the right-click dispatch ([`super::click`]) reuses BANKER to split the shared
-/// Buy cursor kind (banker vs auctioneer) without a duplicate table (decision 0604), and so a live
-/// probe scans for a service NPC by the same bits the cursor classifies with instead of keeping a
-/// private copy ([`crate::capture::ProbeCharterPlugin`] and PETITIONER) — a duplicated flag table
-/// is how B249's icon map went stale.
+/// `UNIT_NPC_FLAGS` bits, 1.12 values (vmangos `UnitDefines.h`); REPAIR (`0x4000`) is left out
+/// because the ladder never tests it.
 pub(crate) mod npc_flags {
     pub const GOSSIP: u32 = 0x1;
     pub const QUESTGIVER: u32 = 0x2;
@@ -167,156 +121,90 @@ pub(crate) mod npc_flags {
     pub const STABLEMASTER: u32 = 0x2000;
 }
 
-/// `UNIT_FLAG_SKINNABLE` in `UNIT_FIELD_FLAGS` (vanilla).
 pub(super) const UNIT_FLAG_SKINNABLE: u32 = 0x0400_0000;
 
-/// NPC-service range gate: gray beyond 5.5556 yd (squared 30.864 — the client's `0xb4b32c` cell,
-/// `[0x804328]²`; checked at `0x482320`, boundary-inclusive). Shared with the merchant window's
-/// out-of-range auto-close ([`crate::ui_merchant`]) so the window closes exactly where the cursor
-/// says the vendor is out of service.
+/// NPC-service range, squared: gray beyond 5.5556 yd (`0xb4b32c` = `[0x804328]²`, checked
+/// boundary-inclusive at `0x482320`). The NPC windows' walk-away close uses the same constant.
 pub(crate) const SERVICE_RANGE_SQ: f32 = 30.864;
-/// Attack's fixed range gate: gray beyond 10.45 yd (squared 109.2025, const `0x80447c`, checked at
-/// `0x4826a7` — *not* the melee reach; that gates skin/insignia only).
+/// Attack's range, squared: gray beyond a fixed 10.45 yd (`0x80447c`, checked at `0x4826a7`), not
+/// the melee reach.
 const ATTACK_RANGE_SQ: f32 = 109.2025;
-/// The melee interact reach offset + floor (`0x80b058` / `0x80a1e8`): reach = **max**(rA + rB +
-/// 1.333, 5.0) — the 5.0 is a floor (`fcomp`-then-keep-larger, `0x6e35bf` / `0x5ec1a4`), so small
-/// pairs always get 5 yd and large creatures reach *farther*. Gates skin (`0x6e3480`) and loot
-/// (inline in `CanLootNow 0x5ec110`); distance is center-to-center, boundary-inclusive.
+/// Melee interact reach `max(reachA + reachB + 1.333, 5.0)` (`0x80b058`, `0x80a1e8`): 5.0 is a
+/// floor, so large creatures reach farther. Gates skin (`0x6e3480`) and loot (`CanLootNow
+/// 0x5ec110`), center to center, boundary-inclusive.
 const MELEE_OFFSET: f32 = 1.333_33;
 const MELEE_FLOOR: f32 = 5.0;
 
-/// A **corpse object**'s interact reach, squared — `25.0`, i.e. a flat **5.0 yd**.
-///
-/// 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`, 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.
+/// A corpse's interact reach, squared: a flat 5 yd, since a corpse has no combat reach and the
+/// melee formula falls to its floor. `CanLootNow 0x5ec110` and the `CMSG_LOOT` sender `0x5df130`
+/// both compare against 25.0.
 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 (`0x5f47f0`).
+/// `GAMEOBJECT_TYPE_GENERIC`: decoration whose highlightable slot is constant false (`0x5f47f0`),
+/// so it never shows an interact cursor.
 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:
-/// `0x80ba58+0x14`→`0x5f5c70`, `0x80b710`/`0x80b798+0x14`→`0x5f48b0`), so a boat / zeppelin /
-/// elevator never shows a cursor, tooltip, or right-click USE.
+/// The transport family, TRANSPORT(11), MAP_OBJECT(14) and MO_TRANSPORT(15): both strategy slots
+/// are constant false (vtables `0x80ba58`, `0x80b710`, `0x80b798`; `+0x14` is `0x5f5c70` or
+/// `0x5f48b0`), so a boat or elevator never shows a cursor, a tooltip or a right-click use.
 const GO_TYPE_TRANSPORT: i32 = 11;
 const GO_TYPE_MAP_OBJECT: i32 = 14;
 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` (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
-/// school publish a mouseover (gold-name tooltip) and then show **cursor mode 0** — the plain
-/// pointer, not the Interact gear — take no `+64` brighten, and swallow the right-click
-/// (`OnUse 0x5f8660` gates on the same `+0x14`). Without this arm they fell through to
-/// [`highlightable_flags`], whose flag/faction terms a SPELL_FOCUS passes trivially (`flags 0x0`),
-/// and every anvil in the world wore the gear.
+/// The marker set, SPELL_FOCUS(8), DUEL_ARBITER(16), FISHINGHOLE(25) and AURA_GENERATOR(30):
+/// mouseover slot `+0xc` constant true, highlightable slot `+0x14` constant false (vtables
+/// `0x80b8a8`, `0x80bb68`, `0x80bbf8`, `0x80c2a0`). An anvil or a duel flag tooltips and brightens
+/// but shows the plain pointer and ignores the right-click (`OnUse 0x5f8660` asks `+0x14`).
 const GO_TYPE_SPELL_FOCUS: i32 = 8;
 const GO_TYPE_DUEL_ARBITER: i32 = 16;
 const GO_TYPE_FISHINGHOLE: i32 = 25;
 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.
+/// The highest type the type factory's jump table (`0x5f76cc`) covers; 21 GUARDPOST has no case
+/// and takes `default:` with every out-of-range type.
 const GO_TYPE_MAX: i32 = 30;
-/// `GAMEOBJECT_TYPE_GUARDPOST` (21) — see [`strategy_is_default`].
 const GO_TYPE_GUARDPOST: i32 = 21;
 
-/// Whether the type factory hands this type the **default** strategy — the shared static placeholder
-/// rather than a type of its own. Type 21 and every out-of-range id take the `default:` arm
-/// `0x5f76a0`, which allocates nothing: `mov dword ptr [esi+0x210], 0xc4d840` parks one static in
-/// `.bss` (given vtable `0x80b188` by the initializer `0x5f36e0`) and logs `"BADBASEGAMEOBJECT|%d"`.
-/// 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.
-///
-/// 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.
+/// Whether the type factory gives this type its `default:` strategy (`0x5f76a0`): a static
+/// placeholder (vtable `0x80b188`) whose `+0x14` (`0x5f36f0`) and `+0xc` both answer false, so the
+/// object shows nothing. No 1.12 data sends such a type; the flag predicate alone would pass it.
 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 (`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.
+/// `GAMEOBJECT_TYPE_TEXT` (9), a readable book or plaque: the Inspect magnifier (`0x5f5890`).
 pub(crate) const GO_TYPE_TEXT: i32 = 9;
-/// 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.
+/// MAILBOX(19) (`0x5f6840`) and type 28 (`0x5f6e30`) show Mail; no 1.12 data uses type 28.
+/// RITUAL(18) shows Mail here, where the reference gives it the base cursor: its own vtable
+/// `0x80bd10` keeps `0x5f3070`.
 const GO_TYPE_RITUAL: i32 = 18;
-/// `pub(super)` so the right-click dispatch ([`super::act_on_right_click`]) reuses the one type
-/// constant to route a mailbox to the client-side window open (decision 0544), not a duplicate.
 pub(super) const GO_TYPE_MAILBOX: i32 = 19;
 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.
+/// Every other type's interact range: the NPC-service reach, standing in for the reference's
+/// per-type strategy constant (`[strat+0xc]`, compared squared by `usable 0x5f3130`; base 5.0,
+/// overridden by several types), which is not transcribed.
 const GO_INTERACT_RANGE_SQ: f32 = SERVICE_RANGE_SQ;
-/// `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.
+/// `GAMEOBJECT_TYPE_FISHINGNODE` (17), the bobber: its strategy (vtable `0x80bc80`) overrides only
+/// the highlightable slot, and its interact range is 100 yd (`0x5f66b0`, `[0x80b0b0]`).
 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. 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
-/// than a transcribed server number (the B158 trap).
+/// `GAMEOBJECT_TYPE_CHAIR` (7): its own range predicate `0x5f5670` accepts within 3.0 yd
+/// (`[0xc4d808]`, written only by `0x5f98b0` as 3.0 squared).
 pub(crate) const GO_TYPE_CHAIR: i32 = 7;
 fn go_interact_range_sq(type_id: i32) -> f32 {
     match type_id {
         GO_TYPE_FISHINGNODE => 100.0 * 100.0,
-        // The chair is the one type whose reach is *shorter* than the 0236 interim, so it is the one
-        // where the interim was visibly wrong: from 3 to ~5.56 yd we showed a live interact cursor
-        // and sent a `CMSG_GAMEOBJ_USE` the server drops on the floor (its own chair arm refuses
-        // past 3.0 to the nearest seat), so the click did nothing and said nothing. Now the cursor
-        // greys where the reference greys it.
-        //
-        // **Measured to the GameObject, not to the seat.** The reference runs its compare per seat,
-        // over the 5 slots `0x5f5760` builds at template bind; vmangos likewise measures to
-        // `GetClosestChairSlotPosition`. Seats spread along `orientation + PI/2` at
-        // `size·i − size·(slots−1)/2`, so for a 1-slot chair — the common case, and the B79 chair —
-        // the seat *is* the object and the two agree exactly; a long bench differs by at most half
-        // its span. Closing that gap needs the seat table, which needs `data0`/`data1` off the GO
-        // template; it is a refinement of this number, not a correction to it.
+        // Measured to the object; the reference (seats from `0x5f5760`) and vmangos
+        // (`GameObject.cpp:2231-2236`) measure to the nearest seat, so only a multi-seat bench
+        // differs, by up to half its span.
         GO_TYPE_CHAIR => 9.0,
         _ => GO_INTERACT_RANGE_SQ,
     }
 }
-/// `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.
+/// `GameObjectFlags` IN_USE (`0x1`) and NO_INTERACT (`0x10`), which `0x5f2f80` rejects together.
 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
-/// is set. This is the quest gate: a quest chest/goober carries it, an ordinary door does not.
+/// `GO_FLAG_INTERACT_COND`: usable only while the per-player activate bit is set, the quest gate.
 const GO_FLAG_INTERACT_COND: u32 = 0x4;
-/// `GO_DYNFLAG_LO_ACTIVATE` (`0x1` in `GAMEOBJECT_DYN_FLAGS`) — the per-player "usable for me now" bit the
-/// server sets from `GameObject::ActivateToQuest` (sparkle). Consulted only under `INTERACT_COND`.
+/// `GO_DYNFLAG_LO_ACTIVATE` in `GAMEOBJECT_DYN_FLAGS`, set per player by the server
+/// (`GameObject::ActivateToQuest`); read only under `INTERACT_COND`.
 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: 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
-/// USE and its pick priority together, exactly as the binary does.
+/// The types whose highlightable slot `+0x14` is constant false, so `0x5f2f80` never runs.
 fn strategy_never_highlightable(type_id: i32) -> bool {
     strategy_is_default(type_id)
         || matches!(
@@ -334,69 +222,30 @@ fn strategy_never_highlightable(type_id: i32) -> bool {
         )
 }
 
-/// `GAMEOBJECT_TYPE_AUCTIONHOUSE` (20) — its `+0x14` is `0x5f68a0`, a bare `xor al,al; ret`, and its
-/// `+0xc` forwards straight into it. So an auction-house **GameObject** shows nothing at all: no
-/// cursor, no tooltip, no brighten, and `OnUse 0x5f8660` returns at `0x5f8673` without sending. (The
-/// auctioneer you actually click in 1.12 is a *unit* with the AUCTIONEER service bit — a different
-/// branch entirely — which is why this reads as a surprise and isn't one.)
+/// `GAMEOBJECT_TYPE_AUCTIONHOUSE` (20): both slots false (`0x5f68a0`), so it shows nothing and
+/// `OnUse` returns unsent (`0x5f8673`); the auctioneer players click is a unit.
 const GO_TYPE_AUCTIONHOUSE: i32 = 20;
-/// `GAMEOBJECT_TYPE_CAPTURE_POINT` (29) — `+0x14` = `0x5f6d40` const-false, so never a cursor; but
-/// its `+0xc` is `0x5f6d80` = `data[19] != 0`, byte-for-byte GENERIC's shape at a different slot.
-/// So it carries **GENERIC's exact law**: tooltip and brighten iff its highlight column is set,
-/// never an interact cursor. Ships in no 1.12 data.
+/// `GAMEOBJECT_TYPE_CAPTURE_POINT` (29): never a cursor (`0x5f6d40`), but a tooltip and brighten
+/// when its highlight column `data[19]` is set (`0x5f6d80`), GENERIC's rule. No 1.12 data uses it.
 const GO_TYPE_CAPTURE_POINT: i32 = 29;
-/// The inputs of the **own-predicate** `+0x14` slots — the two types (so far) whose highlightable
-/// slot is neither the shared `0x5f2f80` nor a constant, and so reads state the shared gate never
-/// touches. Resolved by the caller, like the reference resolves them from the active player and the
-/// UI globals; each field is inert for every type but its own.
-///
-/// A struct rather than a tail of bare booleans on purpose: the signature was growing one `bool` per
-/// override discovered (17 FISHINGNODE, then 23 MEETINGSTONE), and three adjacent same-typed
-/// arguments is a swap waiting to happen at a call site. [`Default`] is "no override applies", which
-/// is what every test and every non-override type wants.
+/// Inputs of the two types whose `+0x14` is a predicate of its own rather than `0x5f2f80` or a
+/// constant; the caller resolves them, and each is ignored for every other type.
 #[derive(Clone, Copy, Default)]
 pub(crate) struct GoOverrides {
-    /// FISHINGNODE(17): the local player is channeling at exactly this bobber
-    /// ([`fishing_channel_owned`]).
+    /// FISHINGNODE: the local player is channeling at this bobber.
     pub(crate) channel_owned: bool,
-    /// MEETINGSTONE(23): this stone's area IS the area we are queued at
-    /// ([`meeting_stone_queued`]).
+    /// MEETINGSTONE: this stone's area is the one we are queued at.
     pub(crate) meeting_stone_queued: bool,
 }
 
-/// `GAMEOBJECT_TYPE_MEETINGSTONE` (23) — the second type with its **own** `+0x14`
-/// (`0x5f6990`), alongside FISHINGNODE(17). It never calls `0x5f2f80`: no faction term, no
-/// `GAMEOBJECT_FLAGS`, no INTERACT_COND, no DYN_FLAGS. It is exactly
-/// `template.data[2] (areaID) != [0xb72038]` — see [`highlightable_flags`]'s `meeting_stone_queued`.
+/// `GAMEOBJECT_TYPE_MEETINGSTONE` (23): its `+0x14` (`0x5f6990`) is only
+/// `template.data[2] != [0xb72038]`, the queued area; it never calls `0x5f2f80`.
 pub(super) const GO_TYPE_MEETINGSTONE: i32 = 23;
 
-/// 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
-/// highlightable, and an **INTERACT_COND** object (the quest gate) is highlightable only when the
-/// server has set its per-player **activate** dyn-flag — so a quest chest sparkles and opens only once
-/// the quest is held, while an ordinary door (no INTERACT_COND) is always highlightable regardless of
-/// 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`): 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`): 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
-/// already queued at**, and nothing else about it matters. The caller resolves the equality (as it
-/// does `channel_owned`) against the live queue — [`crate::ui_dialog_verbs::MeetingStone::area`],
-/// benilla's `[0xb72038]` (decision 2283; it was a hardcoded `0` while no queue existed, which is
-/// the reference's own not-queued value and so was right for exactly as long as we never queued).
-/// Ignored for every other type.
+/// Whether a GameObject shows an interact cursor at all: `0x5f2f80` plus the per-type overrides.
+/// An INTERACT_COND object passes only while the server has set its per-player activate bit: the
+/// quest gate. The FISHINGNODE override (`0x5f6710`) compares our channel object, not
+/// `CREATED_BY`, then runs the shared gate.
 fn highlightable_flags(
     type_id: i32,
     flags: u32,
@@ -410,19 +259,15 @@ fn highlightable_flags(
     if type_id == GO_TYPE_FISHINGNODE && !overrides.channel_owned {
         return false;
     }
-    // MEETINGSTONE's slot REPLACES the shared gate rather than guarding it — so this returns
-    // outright and never falls through to the faction / flags / activate terms below.
+    // MEETINGSTONE's slot replaces the shared gate, so none of the terms below apply to it.
     if type_id == GO_TYPE_MEETINGSTONE {
         return !overrides.meeting_stone_queued;
     }
-    // The FACTION term (`0x5f2f80` @ `0x5f3026/29`, decision 0764). `reaction` is the GameObject's
-    // reaction **toward us** ([`go_reaction`]); the ordinary test is `> 1`, i.e. anything but
-    // hostile. `None` = unresolvable (no faction catalog / our store not streamed) and passes, so a
-    // data gap never blanks the world.
+    // The faction term (`0x5f3026`): the GameObject's reaction toward us must beat hostile. An
+    // unresolved reaction passes, so a data gap never blanks the world.
     let ordinary_faction_ok = |r: Option<u8>| r.is_none_or(|r| r > 1);
     if type_id == GO_TYPE_TRAP {
-        // TRAP alone INVERTS it (`0x5f2fc6/c9: cmp eax,1; jg` — reject when greater): a trap is
-        // highlightable only to whoever it is hostile to. Everything below still applies.
+        // TRAP inverts it (`0x5f2fc6`): highlightable only to whoever it is hostile to.
         if !reaction.is_none_or(|r| r == 1) {
             return false;
         }
@@ -438,22 +283,14 @@ fn highlightable_flags(
     true
 }
 
-/// `GAMEOBJECT_TYPE_TRAP` (6) — the one type whose faction term is inverted.
+/// `GAMEOBJECT_TYPE_TRAP` (6), the one type whose faction term is inverted.
 const GO_TYPE_TRAP: i32 = 6;
 
-/// A GameObject's reaction **toward us** — the reference's `0x5f7fd0` → `0x606530` → `0x606640`
-/// chain, whose direction is GO→player (`this` = the GO's own `FactionTemplate` row, the argument =
-/// the player; `0x606640` tests `self.enemyGroupMask & other.ourMask`). On the client's 1/3/4 scale.
-///
-/// `None` when it cannot be resolved (no catalog, our store not streamed, either template missing) —
-/// callers treat that as "no opinion" and pass. A GameObject with **no** faction resolves NEUTRAL(3),
-/// which is the binary's own default (`0x5f8025: mov eax,3`).
-///
-/// INTERIM, and narrower than the unit path on purpose: the reference's `0x606530` also has a
-/// player-controlled/reputation arm, but every GameObject faction that ships (114 monster, 35
-/// friendly-to-players, 14, 1375) resolves through the plain template comparator, so the
-/// reputation branch is not modelled here. `GAMEOBJECT_CREATED_BY` (a player-summoned object taking
-/// its creator's reaction) is likewise not modelled.
+/// A GameObject's reaction toward us on the 1/3/4 scale: the reference's `0x5f7fd0` → `0x606530` →
+/// `0x606640` chain, the GameObject's template toward the player's. No faction is neutral
+/// (`0x5f8025`); `None` when unresolvable, which callers pass. Only the template comparator runs:
+/// every shipped GameObject faction (114, 35, 14 and 1375) resolves through it, so the reference's
+/// reputation arm and a `GAMEOBJECT_CREATED_BY` creator's reaction are not applied.
 pub(crate) fn go_reaction(
     factions: Option<&Factions>,
     go_faction: u32,
@@ -468,41 +305,11 @@ pub(crate) fn go_reaction(
     Some(go_tpl.reaction_toward(self_tpl) as u8)
 }
 
-/// The **mouseover-eligibility** virtual `[obj->vtbl+0x54]` — the gate that decides whether a picked
-/// object becomes the mouseover **at all** (decision 0762).
-///
-/// 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
-/// `0x52aa20` and the +64 brighten `0x4945e0` are then never reached: **no tooltip, no highlight, no
-/// cursor — nothing.** That is the "some GameObjects show nothing at all on hover" report.
-///
-/// For a GameObject, slot `+0x54` is `0x5f8620`, which tail-calls the **per-GO-TYPE strategy slot
-/// `+0xc`** — and that slot is *not* uniform:
-///
-/// | `[strat_vtbl+0xc]` | types |
-/// |---|---|
-/// | `0x5f9db0` = `jmp [+0x14]` = **[`highlightable_flags`] itself** | 0 DOOR · 1 BUTTON · 2 QUESTGIVER · 3 CHEST · 4 BINDER · 6 TRAP · 7 CHAIR · 9 TEXT · 10 GOOBER · 12 AREADAMAGE · 13 CAMERA · 17 FISHINGNODE · 18 RITUAL · 19 MAILBOX · 20 AUCTIONHOUSE · 22 SPELLCASTER · 23 MEETINGSTONE · 24 FLAGSTAND · 26 FLAGDROP · 27 MINI_GAME · 28 LOTTERY_KIOSK · + the default |
-/// | the **highlight column** — `0x5f4830` = `data[1] != 0` / `0x5f6d80` = `data[19] != 0` | 5 GENERIC · 29 CAPTURE_POINT |
-/// | `mov al,1` — always | 8 SPELL_FOCUS · 16 DUEL_ARBITER · 25 FISHINGHOLE · 30 AURA_GENERATOR |
-/// | `xor al,al` — never | 11 TRANSPORT · 14 MAP_OBJECT · 15 MO_TRANSPORT |
-///
-/// **This slot is not the cursor's.** For the marker set the two slots point opposite ways — `+0xc`
-/// constant-TRUE, `+0x14` constant-FALSE ([`GO_TYPE_SPELL_FOCUS`]) — so an anvil is *fully* hovered
-/// (mouseover published, gold-name tooltip) and *not at all* interactable (plain pointer, no
-/// 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**, 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.
-///
-/// `highlight_column` is the template slot the two data-driven types read — GENERIC's `data[1]`,
-/// CAPTURE_POINT's `data[19]`. `None` = the ask-once template hasn't answered, which reads as
-/// eligible so a signpost isn't blank for the first frames of its query.
+/// Whether a picked object becomes the mouseover at all (`[vtbl+0x54]`): false publishes the null
+/// mouseover (`0x482985`), so no tooltip (`0x52aa20`), brighten (`0x4945e0`) or cursor. For a
+/// GameObject it is the type's slot `+0xc` (`0x5f8620`), not the cursor's slot. `highlight_column`
+/// is GENERIC's `data[1]` or CAPTURE_POINT's `data[19]` (`0x5f4830`, `0x5f6d80`); `None`, a
+/// template not yet answered, reads eligible.
 pub(crate) fn mouseover_eligible(
     type_id: i32,
     flags: u32,
@@ -518,24 +325,15 @@ pub(crate) fn mouseover_eligible(
         | GO_TYPE_FISHINGHOLE
         | GO_TYPE_AURA_GENERATOR => true,
         GO_TYPE_GENERIC | GO_TYPE_CAPTURE_POINT => highlight_column.unwrap_or(true),
-        // Everything else forwards `+0xc` into its own `+0x14` (`0x5f9db0`) — including
-        // AUCTIONHOUSE(20), whose `+0x14` is const-false, and MEETINGSTONE(23), whose is its own
-        // predicate. Both fall out of this one arm because the forward is literal.
+        // Every other type's `+0xc` forwards to its own `+0x14` (`0x5f9db0`).
         _ => highlightable_flags(type_id, flags, dyn_flags, reaction, overrides),
     }
 }
 
-/// [`highlightable_flags`] read off a hovered GameObject's descriptor store. An absent
-/// `GAMEOBJECT_TYPE_ID` is the wire default `0` = DOOR (vmangos omits the zero field), so a door
-/// resolves to a highlightable type rather than being wrongly rejected as "unknown".
-///
-/// Gates the **cursor**, the `+64` **brighten**, the right-click **USE** (`OnUse 0x5f8660` calls this
-/// same `+0x14` first) and the GO pick's **pass-2 priority** (decision 1071: classify `0x480c90`
-/// ranks a highlightable GameObject `1` via `0x5f8800`, else `0`) — the four consumers of one vtable
-/// slot. It is **not** the mouseover publish, which is the sibling slot `+0xc`
-/// ([`mouseover_eligible`]): the two agree for most types and deliberately disagree for GENERIC(5)
-/// (a signpost tooltips while showing no cursor — 0349's reference close-up) and for the marker set
-/// (an anvil tooltips while showing no cursor either).
+/// [`highlightable_flags`] off a GameObject's descriptor; an absent `GAMEOBJECT_TYPE_ID` is the
+/// wire default 0, DOOR. This slot gates the cursor, the right-click use (`OnUse 0x5f8660`) and
+/// the pick's pass-2 priority (`0x480c90` via `0x5f8800`); the tooltip and the brighten follow the
+/// mouseover slot, [`mouseover_eligible`].
 pub(crate) fn go_highlightable(
     store: &ObjectStore,
     reaction: Option<u8>,
@@ -550,25 +348,16 @@ pub(crate) fn go_highlightable(
     )
 }
 
-/// MEETINGSTONE(23)'s highlightable override, resolved for one GameObject: the reference's
-/// `template.data[2] != [0xb72038]`, expressed as its negation so the caller passes the same shape
-/// of boolean as [`fishing_channel_owned`].
-///
-/// `queued_area` is benilla's `[0xb72038]` — [`crate::ui_dialog_verbs::MeetingStone::area`], stored
-/// unconditionally by every `SMSG 0x295` and `0` when we are not queued (decision 2283).
-///
-/// A template that hasn't answered yet resolves `false` (⇒ highlightable), the same permissive
-/// default the highlight column takes — a stone isn't dead for the first frames of its query. Note a
-/// stone whose `data[2]` really is **0** is *not* highlightable when we are unqueued, which is the
-/// binary's own `0 != 0` and not an edge case worth smoothing away.
+/// MEETINGSTONE's override for one stone, `template.data[2] == [0xb72038]`. `queued_area` is the
+/// reference's global: 0 until the `SMSG_MEETINGSTONE_SETQUEUE` handler (`0x4ca230`) writes it
+/// (zeroed at `0x4c9eec`). An unanswered template reads not queued; a `data[2]` of 0 matches the
+/// unqueued 0, as in the reference.
 pub(crate) fn meeting_stone_queued(area: Option<u32>, queued_area: u32) -> bool {
     area.is_some_and(|a| a == queued_area)
 }
 
-/// The FISHINGNODE highlightable override's input (`0x5f6710`): is the local player currently
-/// channeling at exactly this GameObject — `self.UNIT_FIELD_CHANNEL_OBJECT == go_guid`. `false`
-/// when the self store hasn't streamed or the guid is unknown: an unverifiable bobber shows
-/// nothing, matching the reference's no-active-player early-false.
+/// The FISHINGNODE override's input (`0x5f6710`): our `UNIT_FIELD_CHANNEL_OBJECT` is this
+/// GameObject. False when either is unknown, as the reference answers false with no active player.
 pub(crate) fn fishing_channel_owned(
     self_store: Option<&ObjectStore>,
     go_guid: Option<u64>,
@@ -579,10 +368,8 @@ pub(crate) fn fishing_channel_owned(
     }
 }
 
-/// A `LockType.dbc` **CursorName** stem → the [`CursorKind`] it names — the client's
-/// `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."
+/// A `LockType.dbc` CursorName to its cursor, the reference's `CursorModeFromName` (`0x523d40`)
+/// over the three cursor-bearing lock types in 1.12.
 fn cursor_kind_from_lock_name(name: &str) -> Option<CursorKind> {
     match name {
         "PickLock" => Some(CursorKind::PickLock),
@@ -592,13 +379,8 @@ fn cursor_kind_from_lock_name(name: &str) -> Option<CursorKind> {
     }
 }
 
-/// 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
-/// falls back to the Interact gear. A [`CursorKind::PickLock`] result *is* the `LockType.Id == 1`
-/// signal the classifier keys on to skip the grayed twin ("Pick Lock" is the only name that maps
-/// there), so no separate flag is needed.
+/// The data-named cursor for a GameObject's lock (`0x5f3070`): the `Lock.dbc` row's first slot
+/// only (`[lockRow+0x24]`, no scan), then that `LockType.dbc` row's CursorName.
 fn go_lock_cursor(
     lock_id: u32,
     locks: Option<&crate::go_templates::Locks>,
@@ -608,15 +390,13 @@ fn go_lock_cursor(
         return None;
     }
     let slots = locks?.0.slots(lock_id)?;
-    let lock_type_id = slots[0].index; // Index[0] — the client's single, first-slot read.
+    let lock_type_id = slots[0].index;
     let name = lock_types?.0.cursor_name(lock_type_id)?;
     cursor_kind_from_lock_name(name)
 }
 
-/// 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.
+/// A highlightable GameObject's cursor (`GetCursorMode 0x5f8760`): TEXT and the Mail types by
+/// type, any other its lock's data-named cursor or the gear.
 fn go_cursor_kind(type_id: i32, lock_cursor: Option<CursorKind>) -> CursorKind {
     match type_id {
         GO_TYPE_TEXT => CursorKind::Inspect,
@@ -625,40 +405,20 @@ 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}` (`+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 —
-/// and it is load-bearing far beyond the cursor. Melika Isenstrider (vmangos entry 6778) is flagged
-/// QUESTGIVER, carries no other service bit, and has zero rows in `creature_questrelation`: without
-/// this gate she classifies Speak, we send `CMSG_GOSSIP_HELLO`, and vmangos answers the resulting
-/// `DEFAULT_GOSSIP_MESSAGE` text query with eight literal `"Greetings $N"` blocks
-/// (`QueryHandler.cpp:210-217`) — an empty gossip frame carrying a placeholder greeting, on an NPC
-/// the reference never opens anything for. That was the whole of the reported "the client invents
-/// 'Greetings NAME'" bug: the text was genuine, the *asking* was ours.
-///
-/// `None` (no status ever sent) reads as no quest: the server sends the status unprompted for every
-/// questgiver in range, so its absence means the unit isn't offering us one.
+/// The QUESTGIVER bit's own gate (`0x5df490`): the cached `SMSG_QUESTGIVER_STATUS`
+/// (`[unit+0xcb8]`) is neither NONE nor UNAVAILABLE, and a missing one reads as NONE since the
+/// server sends it unprompted. Without the gate a quest-less questgiver opens an empty gossip frame
+/// that vmangos fills with placeholder "Greetings $N" text (`QueryHandler.cpp:313-319`).
 pub(crate) fn questgiver_has_quest(quest_status: Option<u32>) -> bool {
     use benilla_protocol::messages::dialog_status::{NONE, UNAVAILABLE};
     !matches!(quest_status, None | Some(NONE) | Some(UNAVAILABLE))
 }
 
-/// 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).
-///
-/// `quest_status` is the unit's last `SMSG_QUESTGIVER_STATUS` (`None` = never sent), which gates the
-/// QUESTGIVER leg — see [`questgiver_has_quest`].
+/// The service ladder (`0x482336..0x4824e3`, unrolled): lowest set bit wins. `None` when no tested
+/// bit is set, repair-only units included: bit 14 is never tested.
 fn service_cursor(service: u32, quest_status: Option<u32>) -> Option<CursorKind> {
     use npc_flags::*;
-    // Bits 0 and 1 both land on Speak, and bit 0 is tested first, so the two rows fold into one
-    // condition without changing a single outcome — the same folding the SPIRITHEALER/SPIRITGUIDE
-    // and PETITIONER/TABARDDESIGNER/BATTLEMASTER rows already use. Only bit 1 carries a gate.
+    // Bits 0 and 1 both give Speak, so they fold into one test; only bit 1 is gated.
     if service & GOSSIP != 0 || (service & QUESTGIVER != 0 && questgiver_has_quest(quest_status)) {
         Some(CursorKind::Speak)
     } else if service & VENDOR != 0 {
@@ -684,10 +444,9 @@ fn service_cursor(service: u32, quest_status: Option<u32>) -> Option<CursorKind>
     }
 }
 
-/// The loot leg's mode split (`8 + (keyDown(0) ? 8 : 0)` @ `0x48252c`): the single pouch, or
-/// the triple LootAll while the EFFECTIVE auto-loot is on — the 0961 rule (`autoLootDefault`
-/// XOR the held modifier) so the cursor always announces what the click will actually do. In
-/// 1.12 the held key alone *was* the effective state (no CVar existed).
+/// The loot leg's mode, `8 + (keyDown(0) ? 8 : 0)` in the reference (`0x48252c`): LootAll while
+/// the effective auto-loot, `autoLootDefault` XOR shift, is on. `autoLootDefault` is not a 1.12
+/// CVar; with it off the held key alone decides, as in 1.12.
 fn loot_cursor(auto_loot: bool, shift_held: bool) -> CursorKind {
     if auto_loot != shift_held {
         CursorKind::LootAll
@@ -696,76 +455,49 @@ 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.
-///
-/// 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;
-/// the base occupant it falls through to is `0x469fd0`, a constant false, which is the same reason
-/// an item lying in the world is never moused over.
-///
-/// This is a *separate* gate from pick eligibility (`0x480816`) — a rejected corpse is still
-/// picked, it simply publishes no mouseover, so it gets no name plate and no brighten. Ours reads
-/// it the same way: the pick is unconditional, this decides what the hover *shows*.
+/// Whether a corpse becomes the mouseover (`[CGCorpse_C vtbl+0x54]` = `0x5d76d0`, asked at
+/// `0x482982`): a body always, your own included; a bone pile only while it has loot. A refused
+/// corpse is still picked (`0x480816`) but shows no name and no brighten.
 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`,
-/// 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
-/// neither flag, fails both tests, and falls out to the reference's "else clear": the plain
-/// pointer. (Recovering it is decision 0308's `RECOVER_CORPSE` route, not a world cursor.)
-/// What the corpse classifier reads — one struct rather than seven positional bools, so the call
-/// sites (and the test) name each byte fact instead of counting commas.
+/// What the corpse classifier `0x482740` reads. It has two legs and no own-corpse leg: your own
+/// body sets neither flag and reads Point.
 #[derive(Debug, Clone, Copy, Default)]
 struct CorpseFacts {
-    /// `0x5d6e20` — `CORPSE_FIELD_DYNAMIC_FLAGS` bit 0.
+    /// `CORPSE_FIELD_DYNAMIC_FLAGS` bit 0 (`0x5d6e20`).
     lootable: bool,
-    /// `CORPSE_FIELD_FLAGS` bit 5 — `CORPSE_FLAG_LOOTABLE`, the PvP insignia.
+    /// `CORPSE_FIELD_FLAGS` bit 5, `CORPSE_FLAG_LOOTABLE`: the PvP insignia.
     insignia: bool,
-    /// `[0xb700e8]` — the `SPELL_EFFECT_SKIN_PLAYER_CORPSE` learn-time latch.
+    /// `[0xb700e8]`, latched by learning a `SPELL_EFFECT_SKIN_PLAYER_CORPSE` spell.
     skin_latch: bool,
     /// `d2`, centre to centre.
     dist_sq: f32,
     /// The already-looting override: `[player+0x1d28/2c] == corpse GUID`.
     looting_this: bool,
-    /// The effective auto-loot's two terms (0961): the knob…
     auto_loot: bool,
-    /// …and the live key-0.
+    /// Key 0, shift.
     shift_held: bool,
 }
 
 fn corpse_cursor(f: CorpseFacts) -> Option<(CursorKind, bool)> {
-    // Leg 1 — lootable by me. Able-vs-Unable is `CanLootNow 0x5ec110(player, corpse)` — the same
-    // range+state gate as the unit loot leg — OR the already-looting override, which keeps the lit
-    // pouch on the object whose loot window is open even as you drift out of reach. The mode is
-    // Pickup(8)/LootAll(16) by the held key-0 (`0x41f8f0`, `0x4827f8`); both fail →
-    // UnablePickup(28)/UnableLootAll(36) at `0x482818`. Distance grays exactly as on units.
+    // Leg 1, lootable: able within `CanLootNow 0x5ec110`'s reach or while this corpse's loot
+    // window is open; Pickup or LootAll by key 0 (`0x41f8f0` at `0x4827f8`), grayed at `0x482818`.
     if f.lootable {
         let able = f.dist_sq <= CORPSE_INTERACT_RANGE_SQ || f.looting_this;
         return Some((loot_cursor(f.auto_loot, f.shift_held), !able));
     }
-    // Leg 2 — the PvP-insignia / skin-player-corpse leg (`0x482875..0x4828a2`): the flag **and**
-    // the learn latch **and** `!0x6067d0(player, corpse)`, then the reach gate picks
-    // SkinAlliance(20)/SkinHorde(19) or their Unable twins.
-    //
-    // Modelled with its real precondition rather than omitted, so it stays inert for the
-    // reference's own reason: `[0xb700e8]` is latched only by learning a spell whose `Effect[0]`
-    // is `SPELL_EFFECT_SKIN_PLAYER_CORPSE`, and no 1.12.1 player holds one. Benilla ships one Skin
-    // cursor rather than the faction pair (`[0x80439c + 4×0x5efe00(player)]`) — a distinction with
-    // no consequence while the leg is unreachable.
+    // Leg 2, the PvP insignia (`0x482875..0x4828a2`), inert in 1.12.1 as no player holds a
+    // latching spell. Not applied: its third term `!0x6067d0(player, corpse)`, and the faction's
+    // SkinAlliance(20) or SkinHorde(19) cursor (`0x80439c`), shown here as Skin.
     if f.insignia && f.skin_latch {
         return Some((CursorKind::Skin, f.dist_sq > CORPSE_INTERACT_RANGE_SQ));
     }
-    None // "Else clear" — a plain body under the cursor is Point.
+    None // the reference's "else clear": Point
 }
 
-/// Resolve this frame's [`WorldCursor`] from the hovered unit — the reference's classifier order:
-/// interactable-NPC service ladder, else loot/skin/attack by state, each grayed by its own range
-/// gate. No hover (or anything unresolvable) → Point.
+/// Resolve this frame's [`WorldCursor`]; no hover, or nothing resolvable, reads Point.
 #[allow(clippy::type_complexity)]
 pub(super) fn classify_cursor(
     hovered: Res<Hovered>,
@@ -779,38 +511,19 @@ 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, `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
-    // [`super::lock::GoLockInputs`], so the cursor and the click ask literally the same question.
     go_inputs: super::lock::GoLockInputs,
     player_actions: Res<crate::ui_action::PlayerActions>,
-    // `[0xb700e4]`/`[0xb700e8]` — the skin leg's learned-ability precondition (decision 0752).
+    // `[0xb700e4]` and `[0xb700e8]`, the skin legs' learned-spell latches.
     learned: Res<crate::ui_action::LearnedAbilities>,
-    // The QUESTGIVER leg's gate reads the per-guid `SMSG_QUESTGIVER_STATUS` store — see
-    // [`questgiver_has_quest`].
     quest: Res<crate::ui_quest::QuestGiver>,
-    // The loot leg's Pickup/LootAll split (0965): the auto-loot knob (0961) + the live shift.
     loot_cfg: Res<crate::ui_loot::LootConfig>,
     keys: Res<ButtonInput<KeyCode>>,
-    // `[player+0x1d28/2c]` — the open loot session's object. The corpse leg's already-looting
-    // override reads it (the reference keeps the lit pouch on the corpse you are looting even
-    // once you have drifted past the range gate).
+    // `[player+0x1d28/2c]`, the object whose loot window is open.
     loot_latch: Res<crate::ui_loot::LootLatch>,
-    // `[0xb72038]` — the meeting-stone queue, MEETINGSTONE(23)'s own highlightable term
-    // (decision 2283). `Option` because a headless build mounts no UI dialog verbs; absent reads
-    // as the reference's zero-initialized global, i.e. not queued.
+    // `[0xb72038]`, the queued area; absent in a headless build, which reads as not queued.
     stone: Option<Res<crate::ui_dialog_verbs::MeetingStone>>,
 ) {
-    // 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
-    // clear (decision 0243): a GENERIC decoration, a busy/NO_INTERACT object, or a quest object whose
-    // per-player activate bit the server hasn't set (INTERACT_COND without the quest). The usable-
-    // grayed twin is still the interim distance gate (decision 0243); the client's fuller `usable`
-    // (lock satisfaction, player-state) is later.
+    // A GameObject that is not highlightable clears the cursor, as the reference's handler does.
     let resolve_go = || {
         let (go_tf, store, anim) = units.get(hovered_object.target?).ok()?;
         let store = store?;
@@ -820,8 +533,7 @@ pub(super) fn classify_cursor(
             store.0.gameobject_faction(),
             Some(self_store),
         );
-        // The ask-once template is read BEFORE the gate now: MEETINGSTONE's override is a template
-        // slot, so the gate itself needs it (the lock cursor below still does too).
+        // Read before the gate: MEETINGSTONE's override is a template slot.
         let tmpl = hovered_object.guid.and_then(|g| go_inputs.templates.get(g));
         let overrides = GoOverrides {
             channel_owned: fishing_channel_owned(Some(self_store), hovered_object.guid),
@@ -833,8 +545,7 @@ pub(super) fn classify_cursor(
         if !go_highlightable(store, reaction, overrides) {
             return None;
         }
-        // The type's own cursor wins; a base type reads its lock's data-named cursor (needs the
-        // ask-once template — a not-yet-answered GO falls back to the gear until it arrives).
+        // Until its template answers, a locked GameObject reads the gear.
         let lock_id = tmpl.map_or(0, |t| t.lock_id);
         let lock_cursor = go_lock_cursor(
             lock_id,
@@ -843,12 +554,9 @@ pub(super) fn classify_cursor(
         );
         let kind = go_cursor_kind(store.0.gameobject_type_id(), lock_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**: 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 (`0x5f3070`: `LockType.Id == 1`
-        // skips the usable gate), so the rogue's affordance still reads as available.
+        // `usable 0x5f3130`'s lock arm (`0x5f32a6`) then range arm (`0x5f330c`); its player-state
+        // arm is not applied. The lock arm needs `GO_FLAG_LOCKED`, so an herb the player cannot
+        // gather stays lit and refuses on the click, while a padlocked door grays.
         let facts = super::lock::go_facts(Some((store, crate::go_anim::go_state(anim, store))));
         let lock_unmet = go_inputs
             .locks
@@ -871,15 +579,13 @@ pub(super) fn classify_cursor(
             && (lock_unmet || dist_sq > go_interact_range_sq(store.0.gameobject_type_id()));
         Some((kind, unable))
     };
-    // The reference makes one pick over all CGObjects and switches on type; benilla picks unit and
-    // GameObject separately, then classifies whichever is nearer under the cursor.
+    // The reference picks once over all objects; benilla picks units and GameObjects apart and
+    // classifies whichever is nearer under the cursor.
     let resolve_unit = || {
         let (unit_tf, store, _) = units.get(hovered.target?).ok()?;
         let store = store?;
         let (self_tf, self_store) = self_q.single().ok()?;
         let dist_sq = unit_tf.translation.distance_squared(self_tf.translation);
-        // Melee interact reach (loot + skin's gate): both units' combat reach + the offset,
-        // floored at 5 yd. Boundary-inclusive, center-to-center.
         let reach = (store.0.unit_combat_reach() + self_store.0.unit_combat_reach() + MELEE_OFFSET)
             .max(MELEE_FLOOR);
         let in_melee = dist_sq <= reach * reach;
@@ -887,28 +593,21 @@ pub(super) fn classify_cursor(
         let dead = store.0.unit_is_dead();
         if dead {
             if store.0.unit_lootable() {
-                // The loot mode split `8 + (keyDown(0) ? 8 : 0)` @ `0x48252c`, over 0961's
-                // effective auto-loot ([`loot_cursor`]). Gray by the byte-verified gate
-                // (inline in `CanLootNow 0x5ec110`): the same melee interact reach as skin —
-                // ~5 yd vs a normal mob (director-measured, confirmed).
+                // Grayed by `CanLootNow 0x5ec110`'s melee reach; the reference's mid-loot state
+                // block and open-loot-window override are not applied to units.
                 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: the flag alone is not enough —
-            // the reference also requires the learn-time latch `[0xb700e4 + 4×isPlayerTarget]` to
-            // 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).
+            // Skin also needs the learn latch `[0xb700e4 + 4×isPlayerTarget]` (`0x482589`): a
+            // player who has learned no Skinning spell sees Point.
             if store.0.unit_flags() & UNIT_FLAG_SKINNABLE != 0 && learned.skinning.is_some() {
                 return Some((CursorKind::Skin, !in_melee));
             }
             return None; // a plain corpse: Point
         }
 
-        // `CanInteract 0x6067f0` — the classifier's own gate (`0x482310`, through the
-        // `CanInteractNow 0x606880` wrapper), and it is not a reaction threshold: service bits
-        // plus BOTH reaction directions >= neutral, the player->unit one answered by the AT-WAR
-        // bit. TRUE goes to the ladder, FALSE to the loot/skin/attack block.
+        // `CanInteract 0x6067f0`, asked at `0x482310` through `CanInteractNow 0x606880`, picks
+        // the ladder; it is not a reaction threshold.
         if super::can_interact(
             Some(store),
             factions.as_deref(),
@@ -916,15 +615,13 @@ pub(super) fn classify_cursor(
             Some(self_store),
         ) {
             let status = hovered.guid.and_then(|g| quest.status(g));
-            // A unit that reaches the ladder and matches no consulted bit — repair-only, or a
-            // QUESTGIVER with nothing on offer — falls `je 0x4826cb` straight to the cursor
-            // CLEAR. It never reaches the attack leg, so it reads Point, not the sword.
+            // No matching bit clears the cursor (`je 0x4826cb`) without reaching the attack leg:
+            // Point, never the sword.
             return service_cursor(store.0.unit_npc_flags(), status)
                 .map(|kind| (kind, dist_sq > SERVICE_RANGE_SQ));
         }
-        // `CanAttack 0x606980` (`0x48269a`) + the fixed 10.45 yd gray. The predicate is shared
-        // with TAB, the combat flash and `UnitCanAttack`, so the sword can never disagree with
-        // what a click or a spell will actually be allowed to do.
+        // `CanAttack 0x606980` (`0x48269a`), the predicate TAB, the combat flash and
+        // `UnitCanAttack` share.
         if super::can_attack(
             Some(store),
             factions.as_deref(),
@@ -933,10 +630,9 @@ pub(super) fn classify_cursor(
         ) {
             return Some((CursorKind::Attack, dist_sq > ATTACK_RANGE_SQ));
         }
-        None // nothing matched → the reference's `0x4826cb` cursor-clear: Point
+        None // the reference's cursor clear (`0x4826cb`): Point
     };
-    // The **corpse classifier** `0x482740`, whose whole decision is [`corpse_cursor`] — the store
-    // reads and the distance are all that happens here.
+    // The corpse classifier `0x482740`.
     let resolve_corpse = || {
         let (corpse_tf, store, _) = units.get(hovered.corpse?).ok()?;
         let store = store?;
@@ -971,19 +667,15 @@ mod tests {
     use super::*;
     use benilla_protocol::messages::dialog_status;
 
-    /// The corpse classifier `0x482740` has two legs and no more — and neither of them is your
-    /// own body, which is what makes a corpse read as the plain pointer until something *else*
-    /// offers to recover it.
     #[test]
     fn the_corpse_classifier_has_two_legs_and_no_own_corpse_leg() {
-        let near = 25.0; // exactly the gate — boundary-inclusive, like every reach in this file
+        let near = 25.0; // exactly the gate, which is inclusive
         let far = 25.01;
         let bones = |dist_sq| CorpseFacts {
             lootable: true,
             dist_sq,
             ..CorpseFacts::default()
         };
-        // Leg 1: lootable bones. Pickup vs LootAll by the effective auto-loot, grayed by range.
         assert_eq!(
             corpse_cursor(bones(near)),
             Some((CursorKind::Pickup, false))
@@ -996,7 +688,6 @@ mod tests {
             Some((CursorKind::LootAll, false))
         );
         assert_eq!(corpse_cursor(bones(far)), Some((CursorKind::Pickup, true)));
-        // …and the already-looting override keeps it lit past the gate.
         assert_eq!(
             corpse_cursor(CorpseFacts {
                 looting_this: true,
@@ -1004,9 +695,6 @@ mod tests {
             }),
             Some((CursorKind::Pickup, false))
         );
-        // Leg 2 needs BOTH the insignia flag and the learn-time latch. The flag alone is nothing —
-        // which is why a battleground body shows no knife to a player who cannot skin one, and why
-        // this leg is inert in 1.12.1: nothing latches `[0xb700e8]`.
         let insignia = |skin_latch, dist_sq| CorpseFacts {
             insignia: true,
             skin_latch,
@@ -1022,7 +710,7 @@ mod tests {
             corpse_cursor(insignia(true, far)),
             Some((CursorKind::Skin, true))
         );
-        // Leg 1 wins outright when both flags are up — the binary tests lootable FIRST and returns.
+        // The reference tests lootable first.
         assert_eq!(
             corpse_cursor(CorpseFacts {
                 insignia: true,
@@ -1031,8 +719,7 @@ mod tests {
             }),
             Some((CursorKind::Pickup, false))
         );
-        // **Your own corpse**: neither bit is set. Both legs miss, the classifier clears, and the
-        // cursor is the plain pointer at any range and with anything held.
+        // Your own corpse sets neither flag.
         let mine = |dist_sq| CorpseFacts {
             skin_latch: true,
             dist_sq,
@@ -1049,16 +736,13 @@ mod tests {
         );
     }
 
-    /// The loot pouch follows the EFFECTIVE auto-loot (0961: setting XOR shift) — the cursor
-    /// and the click can never disagree about what a pick will do.
     #[test]
     fn the_loot_pouch_triples_with_the_effective_auto_loot() {
         assert_eq!(loot_cursor(false, false), CursorKind::Pickup);
         assert_eq!(loot_cursor(true, false), CursorKind::LootAll);
-        // Shift inverts BOTH ways (era's AUTOLOOTTOGGLE; vanilla's whole mechanism).
+        // Shift inverts both ways; with the setting off it is 1.12's whole mechanism.
         assert_eq!(loot_cursor(false, true), CursorKind::LootAll);
         assert_eq!(loot_cursor(true, true), CursorKind::Pickup);
-        // The grayed twin rides the same stem.
         let far = WorldCursor {
             kind: CursorKind::LootAll,
             unable: true,
@@ -1078,7 +762,6 @@ mod tests {
             unable: true,
         };
         assert_eq!(far.stem(), "UnableAttack");
-        // Point has no grayed twin — unable never redirects it.
         let point = WorldCursor {
             kind: CursorKind::Point,
             unable: true,
@@ -1086,11 +769,8 @@ mod tests {
         assert_eq!(point.stem(), "Point");
     }
 
-    /// The mouseover-eligibility table (decision 0762) — the gate that decides whether an object
-    /// becomes the mouseover at all, so a false here is "no tooltip, no brighten, no cursor".
     #[test]
     fn mouseover_eligibility_matches_the_per_type_slot_table() {
-        // The constant-TRUE slots (`mov al,1`) ignore their flags entirely.
         for t in [
             GO_TYPE_SPELL_FOCUS,
             GO_TYPE_DUEL_ARBITER,
@@ -1114,7 +794,6 @@ mod tests {
                 GoOverrides::default()
             ));
         }
-        // The three constant-FALSE slots (`xor al,al`) — the transport family is never a mouseover.
         for t in [GO_TYPE_TRANSPORT, GO_TYPE_MAP_OBJECT, GO_TYPE_MO_TRANSPORT] {
             assert!(!mouseover_eligible(
                 t,
@@ -1125,8 +804,6 @@ mod tests {
                 GoOverrides::default()
             ));
         }
-        // GENERIC answers from its template's `data[1]` alone — the signpost that hovers vs the
-        // scenery beside it that does not. Not from `highlightable_flags`, which rejects GENERIC.
         assert!(mouseover_eligible(
             GO_TYPE_GENERIC,
             0,
@@ -1147,9 +824,6 @@ mod tests {
             mouseover_eligible(GO_TYPE_GENERIC, 0, 0, None, None, GoOverrides::default()),
             "template not answered yet reads eligible, so a signpost isn't blank while it queries"
         );
-        // Everything else IS highlightable — which is the whole correction. A pre-quest
-        // INTERACT_COND object (the Stone of Binding, a Stratholme portcullis at flags 0x24) and an
-        // IN_USE / NO_INTERACT object show NOTHING, where we used to tooltip them.
         assert!(!mouseover_eligible(
             0,
             GO_FLAG_INTERACT_COND,
@@ -1182,9 +856,7 @@ mod tests {
             None,
             GoOverrides::default()
         )); // IN_USE chest
-            // The FACTION term (decision 0764): a door whose template is hostile to us is not
-            // eligible — no cursor, no tooltip, no brighten. This is Deadmines' Factory Door
-            // (faction 114, flags 0x20), which the director could still hover and open.
+            // A door hostile to us, like the Deadmines Factory Door (faction 114, flags 0x20).
         assert!(!mouseover_eligible(
             0,
             0x20,
@@ -1209,7 +881,6 @@ mod tests {
             Some(4),
             GoOverrides::default()
         ));
-        // TRAP inverts it: hostile-to-us is exactly the case a trap DOES highlight for.
         assert!(mouseover_eligible(
             GO_TYPE_TRAP,
             0,
@@ -1226,7 +897,6 @@ mod tests {
             Some(3),
             GoOverrides::default()
         ));
-        // An unresolvable reaction never blanks the world.
         assert!(mouseover_eligible(
             0,
             0x20,
@@ -1235,7 +905,6 @@ mod tests {
             None,
             GoOverrides::default()
         ));
-        // A plain door is still eligible — the everyday case must not regress.
         assert!(mouseover_eligible(
             0,
             0,
@@ -1256,10 +925,7 @@ mod tests {
 
     #[test]
     fn highlightable_gates_the_quest_object_but_not_the_plain_door() {
-        // An ordinary unlocked door (no INTERACT_COND) is highlightable regardless of its zero activate
-        // bit — plain doors must never gray out.
         assert!(highlightable_flags(0, 0, 0, None, GoOverrides::default())); // DOOR, no flags
-                                                                             // A GENERIC decoration is never highlightable.
         assert!(!highlightable_flags(
             GO_TYPE_GENERIC,
             0,
@@ -1267,8 +933,6 @@ mod tests {
             None,
             GoOverrides::default()
         ));
-        // Neither is the transport family (the byte-dumped constant-false +0x14 slots): no gear,
-        // no tooltip, no USE on a boat / elevator / map object — flags can't make them so.
         for t in [GO_TYPE_TRANSPORT, GO_TYPE_MAP_OBJECT, GO_TYPE_MO_TRANSPORT] {
             assert!(!highlightable_flags(
                 t,
@@ -1278,9 +942,6 @@ mod tests {
                 GoOverrides::default()
             ));
         }
-        // Nor the marker set, whose `+0x14` is the same byte-dumped `xor al,al` — an anvil / forge /
-        // brazier (SPELL_FOCUS, flags 0x0, faction 0 ⇒ NEUTRAL, every flag term passing) is exactly
-        // the case that used to reach the predicate and come back true, wearing the Interact gear.
         for t in [
             GO_TYPE_SPELL_FOCUS,
             GO_TYPE_DUEL_ARBITER,
@@ -1296,8 +957,7 @@ mod tests {
                 GoOverrides::default()
             ));
         }
-        // And the two slots point OPPOSITE ways for the marker set: hovered (tooltip) but never
-        // interactable (no cursor, no brighten, no USE). The reported anvil, both halves at once.
+        // The marker set's two slots disagree: a tooltip, but no interact cursor.
         assert!(mouseover_eligible(
             GO_TYPE_SPELL_FOCUS,
             0,
@@ -1313,9 +973,6 @@ mod tests {
             Some(3),
             GoOverrides::default()
         ));
-        // The DEFAULT strategy — type 21, and everything outside the factory's 0..=30 jump table.
-        // It shows NOTHING (both slots false), where the flag predicate would have answered `true`
-        // for exactly the all-zero descriptor an unknown type arrives with.
         for t in [GO_TYPE_GUARDPOST, GO_TYPE_MAX + 1, 99, -1] {
             assert!(strategy_is_default(t), "type {t} takes the default arm");
             assert!(!highlightable_flags(t, 0, 0, None, GoOverrides::default()));
@@ -1328,13 +985,9 @@ mod tests {
                 GoOverrides::default()
             ));
         }
-        // …and each of the 30 real cases has its own strategy — 21 is the table's only hole.
         for t in (0..=GO_TYPE_MAX).filter(|t| *t != GO_TYPE_GUARDPOST) {
             assert!(!strategy_is_default(t), "type {t} has its own strategy");
         }
-        // AUCTIONHOUSE(20) — `+0x14` = `0x5f68a0`, a bare `xor al,al`, and `+0xc` forwards INTO it,
-        // so the auction-house GameObject shows nothing at all. (The auctioneer you click is a
-        // unit; this type is not that.) Flags can't make it so.
         assert!(!highlightable_flags(
             GO_TYPE_AUCTIONHOUSE,
             0,
@@ -1350,9 +1003,6 @@ mod tests {
             Some(3),
             GoOverrides::default()
         ));
-        // CAPTURE_POINT(29) carries GENERIC's law at a different slot: never a cursor, but a
-        // tooltip iff its highlight column (`data[19]`) is set. The two slots disagree by design,
-        // exactly as they do for type 5 — so assert BOTH, or the pairing is untested.
         assert!(!highlightable_flags(
             GO_TYPE_CAPTURE_POINT,
             0,
@@ -1376,7 +1026,6 @@ mod tests {
             Some(3),
             GoOverrides::default()
         ));
-        // A busy (IN_USE) or NO_INTERACT object is not highlightable.
         assert!(!highlightable_flags(
             3,
             0x1,
@@ -1391,8 +1040,6 @@ mod tests {
             None,
             GoOverrides::default()
         )); // CHEST, NO_INTERACT
-            // The quest gate: an INTERACT_COND object is highlightable only with the activate bit set — the
-            // exact bug, a quest chest without the quest.
         assert!(!highlightable_flags(
             3,
             GO_FLAG_INTERACT_COND,
@@ -1409,15 +1056,12 @@ mod tests {
         )); // quest chest, quest held → usable
     }
 
-    /// MEETINGSTONE(23)'s own `+0x14` (`0x5f6990`): `template.data[2] (areaID) != [0xb72038]`, and
-    /// **nothing else** — it never calls `0x5f2f80`, so none of the shared gate's terms apply.
     #[test]
     fn the_meeting_stone_answers_only_the_queued_area() {
         let queued = GoOverrides {
             meeting_stone_queued: true,
             ..Default::default()
         };
-        // Unqueued (the only state benilla can be in today) → highlightable.
         assert!(highlightable_flags(
             GO_TYPE_MEETINGSTONE,
             0,
@@ -1425,8 +1069,6 @@ mod tests {
             None,
             GoOverrides::default()
         ));
-        // Queued at THIS stone → not highlightable: no cursor, and (via the `+0xc` forward) no
-        // tooltip or brighten either.
         assert!(!highlightable_flags(
             GO_TYPE_MEETINGSTONE,
             0,
@@ -1442,9 +1084,6 @@ mod tests {
             None,
             queued
         ));
-        // The slot REPLACES the shared gate — it does not ride on top of it. Every term that would
-        // reject any other type is inert here: hostile faction, NO_INTERACT, IN_USE, and an
-        // INTERACT_COND with no activate bit all still leave an unqueued stone highlightable.
         for (flags, dyn_flags, reaction) in [
             (0x10, 0, Some(1)),
             (0x1, 0, Some(1)),
@@ -1461,25 +1100,17 @@ mod tests {
                 "flags {flags:#x} must not reach a meeting stone — its slot never calls 0x5f2f80"
             );
         }
-        // The caller's half: the resolved boolean is `data[2] == the queued area`, with an
-        // unanswered template reading as not-queued so a stone isn't dead while it queries. The
-        // right-hand side is the LIVE queue since 2283 — unqueued (`0`) leaves every stone
-        // highlightable, and queueing at one area silences exactly that area's stones.
         assert!(!meeting_stone_queued(None, 0));
         assert!(!meeting_stone_queued(Some(1519), 0));
         assert!(meeting_stone_queued(Some(1519), 1519));
         assert!(!meeting_stone_queued(Some(1519), 1517));
         assert!(!meeting_stone_queued(None, 1519));
-        // The binary's own `0 != 0`: a `data[2] == 0` stone reads as the stone we are "queued at"
-        // while we are not queued at all.
+        // The reference's own `0 != 0`: a stone whose `data[2]` is 0 matches while unqueued.
         assert!(meeting_stone_queued(Some(0), 0));
     }
 
     #[test]
     fn the_bobber_is_channel_gated_and_reaches_a_hundred_yards() {
-        // 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(
             GO_TYPE_FISHINGNODE,
             0,
@@ -1497,7 +1128,7 @@ mod tests {
             None,
             GoOverrides::default()
         ));
-        // The pass tail-jumps the SHARED gate, so the flags still apply on top.
+        // NO_INTERACT still applies after the channel check.
         assert!(!highlightable_flags(
             GO_TYPE_FISHINGNODE,
             0x10,
@@ -1508,7 +1139,6 @@ mod tests {
                 ..Default::default()
             }
         ));
-        // The mouseover thunk (`+0xc` → `+0x14`) rides the same predicate: no tooltip either.
         assert!(!mouseover_eligible(
             GO_TYPE_FISHINGNODE,
             0,
@@ -1528,40 +1158,30 @@ mod tests {
                 ..Default::default()
             }
         ));
-        // Every other type ignores the channel input entirely.
         assert!(highlightable_flags(0, 0, 0, None, GoOverrides::default()));
-        // The per-type range: the bobber's ctor constant is 100.0 yd (squared at the compare) —
-        // effectively un-range-gated — while everything else stays on the interim reach.
         assert_eq!(go_interact_range_sq(GO_TYPE_FISHINGNODE), 100.0 * 100.0);
         assert_eq!(go_interact_range_sq(0), GO_INTERACT_RANGE_SQ);
-        // The chair's own 3.0 yd (1464) — the one type that reaches *less* far than the interim, so
-        // the interim was the visible bug: a live cursor and a dropped packet from 3 to 5.56 yd.
         assert_eq!(go_interact_range_sq(GO_TYPE_CHAIR), 9.0);
         assert!(
             go_interact_range_sq(GO_TYPE_CHAIR) < GO_INTERACT_RANGE_SQ,
             "the chair reaches SHORTER than the interim — a longer one would restore the bug"
         );
-        // The channel compare itself: owned iff self's channel object is exactly this guid.
         assert!(!fishing_channel_owned(None, Some(7)));
         assert!(!fishing_channel_owned(None, None));
     }
 
     #[test]
     fn melee_reach_floors_at_five() {
-        // The byte-verified floor (`0x80a1e8` is a max, not a min): a typical player-vs-mob pair
-        // (1.5 + 1.5 + 1.333 = 4.333) is lifted to 5 yd — the threshold the director measured.
+        // A typical pair, 1.5 + 1.5 + 1.333, is lifted to the 5 yd floor.
         assert_eq!((1.5_f32 + 1.5 + MELEE_OFFSET).max(MELEE_FLOOR), 5.0);
-        // Large creatures reach *farther* than 5 — the floor never cuts a big sum down.
         assert!(((3.0_f32 + 3.0 + MELEE_OFFSET).max(MELEE_FLOOR) - 7.333_33).abs() < 1e-4);
     }
 
     #[test]
     fn service_ladder_matches_the_unrolled_binary() {
         use npc_flags::*;
-        // 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`.
+        // A quest on offer, so the QUESTGIVER row passes its gate.
         let has = Some(dialog_status::AVAILABLE);
-        // 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));
@@ -1573,7 +1193,6 @@ mod tests {
         assert_eq!(service_cursor(BATTLEMASTER, None), Some(CursorKind::Speak));
         assert_eq!(service_cursor(AUCTIONEER, None), Some(CursorKind::Buy));
         assert_eq!(service_cursor(STABLEMASTER, None), Some(CursorKind::Speak));
-        // Lowest bit wins: a gossiping vendor speaks; an innkeeper-banker interacts.
         assert_eq!(
             service_cursor(GOSSIP | VENDOR, None),
             Some(CursorKind::Speak)
@@ -1582,26 +1201,17 @@ mod tests {
             service_cursor(INNKEEPER | BANKER, None),
             Some(CursorKind::Interact)
         );
-        // REPAIR (0x4000) is never consulted — repair-only falls to the attack/clear leg.
+        // REPAIR (`0x4000`) is never tested.
         assert_eq!(service_cursor(0x4000, None), None);
         assert_eq!(service_cursor(0, None), None);
     }
 
-    /// **A unit that reaches the ladder and matches nothing falls to the cursor CLEAR, never to
-    /// the sword** (`je 0x4826cb`, past the attack leg's `0x48269a`). This is the second half of
-    /// 1674: the ladder's fall-out used to drop into benilla's attack leg, so a repair-only NPC —
-    /// or a QUESTGIVER with nothing on offer — read as attackable purely because its reaction was
-    /// neutral. `service_cursor` returning `None` inside the interactable branch must mean Point.
     #[test]
     fn the_ladder_falls_out_to_point_not_to_the_sword() {
         use npc_flags::*;
-        // Both shapes that reach the ladder and match no consulted bit.
         assert_eq!(service_cursor(REPAIR_ONLY, None), None);
         assert_eq!(service_cursor(QUESTGIVER, Some(dialog_status::NONE)), None);
-        // The classifier's own expression for that branch: `Option::map` over the ladder, so a
-        // `None` returns `None` from `resolve_unit` and the caller's `unwrap_or` lands on Point.
-        // (Written as the identity it is, so a future edit that adds an `else` fall-through to the
-        // attack leg has to delete this test to compile a different shape.)
+        // `resolve_unit`'s own expression for the branch: a `None` stays `None`, which reads Point.
         let unable = 20.0 > SERVICE_RANGE_SQ;
         assert_eq!(
             service_cursor(REPAIR_ONLY, None).map(|kind| (kind, unable)),
@@ -1615,17 +1225,12 @@ mod tests {
         );
     }
 
-    /// `UNIT_NPC_FLAGS` REPAIR — the one service bit the ladder never tests.
+    /// `UNIT_NPC_FLAGS` REPAIR, the service bit the ladder never tests.
     const REPAIR_ONLY: u32 = 0x4000;
 
-    /// The QUESTGIVER leg's `0x5df490` gate: the bit alone never makes a unit talkable. This is the
-    /// "client invents 'Greetings NAME'" bug at its root — a questgiver-flagged NPC with nothing to
-    /// offer must fall out of the ladder entirely, so we never send `CMSG_GOSSIP_HELLO` and never
-    /// open the empty gossip frame the server would answer with a placeholder greeting.
     #[test]
     fn questgiver_flag_alone_is_not_talkable() {
         use npc_flags::*;
-        // Melika Isenstrider's exact shape: QUESTGIVER, no other service bit, nothing on offer.
         for status in [
             None,
             Some(dialog_status::NONE),
@@ -1637,7 +1242,6 @@ mod tests {
                 "status {status:?} must not classify Speak"
             );
         }
-        // Every other status is a quest worth talking about — `[unit+0xcb8] ∉ {0, 1}`.
         for status in [
             dialog_status::CHAT,
             dialog_status::INCOMPLETE,
@@ -1652,9 +1256,6 @@ mod tests {
                 "status {status} must classify Speak"
             );
         }
-        // The gate is the QUESTGIVER leg's alone: a quest-less unit that also gossips still speaks
-        // (bit 0 is tested first and carries no gate), and a quest-less vendor still shows Pickup
-        // rather than falling out of the ladder.
         assert_eq!(
             service_cursor(GOSSIP | QUESTGIVER, None),
             Some(CursorKind::Speak)
@@ -1667,8 +1268,6 @@ mod tests {
 
     #[test]
     fn lock_names_resolve_to_the_three_data_cursors() {
-        // The only cursor-bearing LockType CursorNames in 5875 (byte-confirmed in the LockType
-        // catalog test) — the client's `CursorModeFromName` over them.
         assert_eq!(
             cursor_kind_from_lock_name("PickLock"),
             Some(CursorKind::PickLock)
@@ -1678,24 +1277,20 @@ mod tests {
             Some(CursorKind::GatherHerbs)
         );
         assert_eq!(cursor_kind_from_lock_name("Mine"), Some(CursorKind::Mine));
-        // Anything else (an empty CursorName, or an unmodeled name) → no data cursor → Interact.
         assert_eq!(cursor_kind_from_lock_name(""), None);
         assert_eq!(cursor_kind_from_lock_name("Fishing"), None);
     }
 
     #[test]
     fn go_cursor_kind_maps_type_then_lock() {
-        // MAILBOX(19), RITUAL(18) and type 28 all show Mail — regardless of any (irrelevant) lock.
+        // MAILBOX(19), RITUAL(18) and type 28 take Mail whatever their lock.
         assert_eq!(go_cursor_kind(19, None), CursorKind::Mail);
         assert_eq!(go_cursor_kind(18, None), CursorKind::Mail);
         assert_eq!(go_cursor_kind(28, Some(CursorKind::Mine)), CursorKind::Mail);
-        // TEXT(9) plaque → the Inspect magnifier.
-        assert_eq!(go_cursor_kind(9, None), CursorKind::Inspect);
-        // Base types: a door(0)/button(1)/chest(3)/goober(10) with no data cursor → the Interact gear.
+        assert_eq!(go_cursor_kind(9, None), CursorKind::Inspect); // TEXT
         for t in [0, 1, 3, 10, 6, 24] {
             assert_eq!(go_cursor_kind(t, None), CursorKind::Interact);
         }
-        // A base type carrying a data-named lock cursor shows it (a chest over a vein/herb/picked lock).
         assert_eq!(go_cursor_kind(3, Some(CursorKind::Mine)), CursorKind::Mine);
         assert_eq!(
             go_cursor_kind(3, Some(CursorKind::GatherHerbs)),
@@ -1709,8 +1304,6 @@ mod tests {
 
     #[test]
     fn go_cursor_stems_name_the_shipped_blps() {
-        // The new GO cursor kinds resolve to real `Interface\Cursor\<stem>.blp` stems (all present
-        // in 5875, confirmed by extraction); their grayed twins prepend Unable, except Point.
         for (kind, stem) in [
             (CursorKind::Mail, "Mail"),
             (CursorKind::Mine, "Mine"),
diff --git a/crates/benilla-app/src/target/flash.rs b/crates/benilla-app/src/target/flash.rs
index 75a99f86..6687a994 100644
--- a/crates/benilla-app/src/target/flash.rs
+++ b/crates/benilla-app/src/target/flash.rs
@@ -1,23 +1,12 @@
-//! 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.
+//! The melee combat flash: the target's selection ring and overhead name pulse red to orange while
+//! the local player auto-attacks 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
-//! unit is the local player's current **TARGET**, the local player is **actively auto-attacking**
-//! (`[player+0xc48]` — the swing-target GUID the `Attack()` handler stores; benilla's
-//! server-echoed [`Engaged`] bracket is the same predicate), and the unit is **legally
-//! attackable** (`0x606980`: UNIT_FIELD_FLAGS disqualifier bits clear + reaction ≤ neutral —
-//! the recorded "hostile ≤ 1" gloss was director-falsified, see `scan::can_attack` / 0170;
-//! the duel/PVP leg is deferred with duels). So the flash means *"I am in melee with my target"*
-//! — not "this unit attacks me" (the hypothesis the bytes refined).
-//!
-//! The pulse (`0x607f67`–`0x607fd0`): a continuous linear **triangle** wave on the **G byte
-//! only** — half-period 500 ms (1 Hz full period), `G = trunc(128·frac)`, red `0xFFFF0000`
-//! (G=0) ↔ orange `0xFFFF8000` (G=128); A/R/B fixed. The clock cells (`[0xc4daa0]/[0xc4daa4]`)
-//! are **global** — one shared phase — and advance only while a unit qualifies. Consumers: the
-//! **selection ring** and the **overhead name**, through the SAME `GetSelectionCircleColor
-//! 0x605960` first-priority branch (colour global `0xc4d8c8`) — and nothing else (the V-key
-//! nameplate never flashes; verified exhaustive).
+//! The reference recomputes the flag, `[unit+0xc58]` bit `0x10`, every frame in CGUnit's OnUpdate
+//! (`0x607f60` set, `0x607fe2` clear), and no packet touches it: set iff the unit is the current
+//! target, the local player is auto-attacking (`[player+0xc48]`, here the server-echoed
+//! [`Engaged`]) and `CanAttack 0x606980` passes. The pulse is one global phase that advances only
+//! while a unit qualifies. Only the ring and the overhead name read it, through
+//! `GetSelectionCircleColor 0x605960` (colour global `0xc4d8c8`); the V-key nameplate never does.
 
 use bevy::prelude::*;
 
@@ -27,17 +16,15 @@ use crate::net::{ObjectStore, Reputations, SelfPlayer};
 use super::relations::can_attack;
 use super::{Factions, Selection};
 
-/// This frame's flash verdict + the global pulse clock. Recomputed every frame by
-/// [`drive_flash`]; read by the ring's material pick and the nameplate colour gate.
+/// This frame's flash verdict and the global pulse clock, read by the ring and the nameplate.
 #[derive(Resource)]
 pub(crate) struct CombatFlash {
-    /// The unit whose ring + overhead name pulse this frame — the current target, or nobody.
+    /// The unit that pulses this frame: the current target, or none.
     pub(crate) unit: Option<Entity>,
-    /// This frame's wave colour (the G-byte triangle over red↔orange).
     pub(crate) color: Color,
-    /// `[0xc4daa0]` — the last half-cycle reset time (ms).
+    /// `[0xc4daa0]`: the last half-cycle flip, in ms.
     last_reset_ms: u32,
-    /// `[0xc4daa4]` — the wave direction bit.
+    /// `[0xc4daa4]`: the wave direction.
     rising: bool,
 }
 
@@ -45,8 +32,8 @@ impl Default for CombatFlash {
     fn default() -> Self {
         Self {
             unit: None,
-            // The default writer `0x5fa3f0`: 0xFFFF0000. GAMMA LANE (0161): authored bytes go
-            // raw into the gamma framebuffer — `linear_rgb`, like the ring/name palettes.
+            // `0x5fa3f0`'s default, `0xFFFF0000`. Authored bytes go raw into the gamma
+            // framebuffer, hence `linear_rgb`.
             color: Color::linear_rgb(1.0, 0.0, 0.0),
             last_reset_ms: 0,
             rising: false,
@@ -54,11 +41,9 @@ impl Default for CombatFlash {
     }
 }
 
-/// One G-byte triangle sample at `now`, advancing the global clock cells — the exact `0x607f67`
-/// recurrence: `t = (500 − (now − lastReset))/500 ∈ (0,1]`, `frac = rising ? 1−t : t`,
-/// `G = trunc(128·frac)`; a half-cycle elapse flips the direction and resets the cell to `now`
-/// (the client's own sparse-frame drift). The join is continuous — G hits 0/128 exactly at each
-/// flip.
+/// One sample of the `0x607f67` triangle on the G byte alone, advancing the clock: red
+/// `0xFFFF0000` (G 0) to orange `0xFFFF8000` (G 128) over 500 ms, `G = trunc(128·frac)`. A flip
+/// resets the cell to `now`, not to the half-period, so sparse frames drift as in the reference.
 fn wave_g(now: u32, last_reset: &mut u32, rising: &mut bool) -> u8 {
     if now.wrapping_sub(*last_reset) >= 500 {
         *rising = !*rising;
@@ -66,12 +51,11 @@ fn wave_g(now: u32, last_reset: &mut u32, rising: &mut bool) -> u8 {
     }
     let t = (500 - now.wrapping_sub(*last_reset)) as f32 / 500.0;
     let frac = if *rising { 1.0 - t } else { t };
-    (128.0 * frac) as u8 // truncation toward zero — the client's __ftol
+    (128.0 * frac) as u8 // truncation toward zero, the client's __ftol
 }
 
-/// Recompute the flash verdict — the client's per-frame OnUpdate gate, evaluated over the one
-/// unit that can qualify (your current target). Runs before the ring update and the nameplate
-/// drive so both consume this frame's verdict.
+/// The per-frame OnUpdate gate, over the one unit that can qualify, the current target. Runs
+/// before the ring update and the nameplate drive, which read this frame's verdict.
 #[allow(clippy::type_complexity)] // one Bevy system's full input set
 pub(super) fn drive_flash(
     mut flash: ResMut<CombatFlash>,
@@ -84,17 +68,14 @@ pub(super) fn drive_flash(
     units: Query<Option<&ObjectStore>, Without<SelfPlayer>>,
 ) {
     let was = flash.unit;
-    // The per-frame gate — `None` means no flash this frame.
     flash.unit = (|| {
-        // Gate 1 — the unit is the current target (`[0xb4e2d8]`).
+        // The current target (`[0xb4e2d8]`).
         let target = selection.target?;
-        // Gate 3 — the local player is actively auto-attacking (`[player+0xc48]` ≠ 0).
+        // Auto-attacking: `[player+0xc48]` is nonzero.
         if engaged.is_empty() {
             return None;
         }
-        // Gate 4 — legally attackable: the shared `CanAttack 0x606980` predicate (flag
-        // disqualifiers + reaction ≤ neutral — see `scan::can_attack`; the director's reference
-        // A/B pinned that neutral targets flash too).
+        // `CanAttack 0x606980`: a neutral target flashes too.
         let store = units.get(target).ok()?;
         can_attack(
             store,
@@ -105,7 +86,7 @@ pub(super) fn drive_flash(
         .then_some(target)
     })();
     if flash.unit.is_some() {
-        // Qualified — advance the global wave and stamp this frame's colour.
+        // Only a qualifying frame advances the global wave.
         let now = time.elapsed().as_millis() as u32;
         let CombatFlash {
             last_reset_ms,
@@ -113,12 +94,10 @@ pub(super) fn drive_flash(
             ..
         } = &mut *flash;
         let g = wave_g(now, last_reset_ms, rising);
-        // The wave byte, raw into the gamma lane (0161): G=128 lands exactly on the authored
-        // orange 0xFF8000 = linear_rgb(1.0, 0.502, 0.0).
+        // Raw into the gamma lane: G 128 is the authored orange `0xFF8000`.
         flash.color = Color::linear_rgb(1.0, g as f32 / 255.0, 0.0);
     }
-    // The arm/disarm EDGE (never per-frame) — so "it never flashes" in the field is diagnosable
-    // from the log.
+    // Logged on the arm and disarm edge only.
     if was != flash.unit {
         debug!("combat flash: {was:?} → {:?}", flash.unit);
     }
@@ -128,16 +107,14 @@ pub(super) fn drive_flash(
 mod tests {
     use super::*;
 
-    /// The wave's pinned points: falling from 128 hits 0 at the half-period, the flip is
-    /// continuous (0 at the joint), the rising half climbs back to 128 — 1 Hz round trip, and
-    /// truncation (not rounding) on the G byte.
+    /// 128 down to 0 over 500 ms and back, continuous at the flip, truncated rather than rounded.
     #[test]
     fn triangle_wave_matches_the_byte_recurrence() {
         let (mut reset, mut rising) = (0u32, false);
         assert_eq!(wave_g(0, &mut reset, &mut rising), 128, "falling start");
         assert_eq!(wave_g(250, &mut reset, &mut rising), 64, "midpoint");
         assert_eq!(wave_g(499, &mut reset, &mut rising), 0, "trunc(128·1/500)");
-        // The flip: elapsed ≥ 500 resets the cell and reverses — continuous at 0.
+        // Elapsed ≥ 500 resets the cell and reverses.
         assert_eq!(wave_g(500, &mut reset, &mut rising), 0, "joint");
         assert!(rising && reset == 500);
         assert_eq!(wave_g(750, &mut reset, &mut rising), 64, "rising midpoint");
diff --git a/crates/benilla-app/src/target/highlight.rs b/crates/benilla-app/src/target/highlight.rs
index f7e8e83b..7c784f45 100644
--- a/crates/benilla-app/src/target/highlight.rs
+++ b/crates/benilla-app/src/target/highlight.rs
@@ -1,21 +1,14 @@
-//! The mouseover / target **model brighten** — the real client's per-model highlight emissive.
+//! The mouseover and target model brighten, the reference'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` 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.
+//! The reference sets it on a change, not per frame: `SetHighlight 0x614550` and `ClearHighlight
+//! 0x6144f0` keep a per-object reason mask (bit 0 target, bit 1 mouseover), and the glow drops when
+//! the last reason clears. `SetHighlight` samples the scene's committed ambient (`[0xce9cd8]`,
+//! `0x614576`..`0x6145bd`) into the model, and every batch adds it before the final clamp (`c29`),
+//! lit or unlit, 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 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
-//! to set membership: an entity is lit while it is hovered *or* targeted — same stacking result.
-//! Scope tracks whatever hover/selection can resolve (the reference brightens any hoverable object
-//! with a model — units today; GameObjects when they become hoverable).
+//! benilla carries the flag in bit 31 of the per-instance `MeshTag` (`benilla_world::mesh_tag`),
+//! and `wow_model.wgsl` adds the scene ambient when it is set.
 
 use bevy::mesh::MeshTag;
 use bevy::prelude::*;
@@ -24,34 +17,27 @@ use benilla_world::mesh_tag::HIGHLIGHT_BIT;
 
 use super::{go_is_nearest, Hovered, HoveredObject, Selection};
 
-/// OR/clear [`HIGHLIGHT_BIT`] on the hovered + targeted roots' part tags. `was_lit` is last frame's
-/// root set, so a root that loses both reasons gets its bit cleared exactly once. A hovered
-/// GameObject brightens exactly like a unit (the reference's reason bit 1 = mouseover covers any
-/// hoverable CGObject — the signpost glow, director-matched 2026-07-13), gated by the same
-/// nearer-pick the click router uses so only the object a click would act on lights.
+/// The bit's only writer: ORs [`HIGHLIGHT_BIT`] onto every part of the hovered and targeted roots
+/// and clears it on roots that left the set, the reason mask collapsed to set membership. Runs in
+/// PostUpdate, after the Update writers that overwrite the whole tag. The mouseover reason covers
+/// any hoverable object, so a GameObject lights like a unit, through the click's nearer-pick.
 pub(super) fn apply_highlight(
     hovered: Res<Hovered>,
     hovered_go: Res<HoveredObject>,
     selection: Res<Selection>,
-    // The hovered corpse's descriptor — the mouseover-eligibility gate below is a field read.
     stores: Query<&crate::net::ObjectStore>,
     children: Query<&Children>,
     mut tags: Query<&mut MeshTag>,
     mut was_lit: Local<Vec<Entity>>,
 ) {
-    // [`Hovered::any`], not `target`: a hovered **corpse** is a pick too (decision 1723), so it
-    // holds the brighten off a farther GameObject exactly as a unit does.
+    // `any`, not `target`: a hovered corpse also holds the brighten off a farther GameObject.
     let go = hovered_go
         .target
         .filter(|_| hovered.any().is_none() || go_is_nearest(&hovered, &hovered_go));
     let unit_hover = hovered.target.filter(|_| go.is_none());
-    // **And the corpse body brightens too** (1729, byte-verified): the mouseover brighten
-    // `0x49295e → 0x4945e0` runs *before* the publisher's type switch and tests nothing but
-    // "has a model, has an object" — reason bit 1 is mouseover, and it applies to a corpse
-    // exactly as to a unit or a signpost. (Bit 0 is the target brighten, which a corpse can
-    // never take: `SetSelection` refuses it.) Gated by the same mouseover eligibility that
-    // decides whether it gets a name plate — a bone pile with nothing to take publishes no
-    // mouseover, so it neither lights nor labels.
+    // A hovered corpse brightens too: the mouseover brighten (`0x49295e → 0x4945e0`) runs before
+    // the publisher's type switch. Gated like its name plate: a bone pile with nothing to take
+    // publishes no mouseover.
     let corpse_hover = hovered
         .corpse
         .filter(|_| go.is_none())
@@ -70,17 +56,14 @@ pub(super) fn apply_highlight(
             set_bit(root, false, &children, &mut tags);
         }
     }
-    // Re-asserted every frame, not only on change: the Update payload writers (fade/interior/…)
-    // overwrite the whole tag without the bit whenever they run.
+    // Every frame, not on change: the Update writers overwrite the whole tag without the bit.
     for &root in &want {
         set_bit(root, true, &children, &mut tags);
     }
     *was_lit = want;
 }
 
-/// Set/clear the highlight bit on `root` and every descendant carrying a `MeshTag` (the model's
-/// parts — and its attachments, which the reference brightens with the body). A despawned root
-/// simply yields no descendants.
+/// Sets or clears the bit on `root` and every descendant `MeshTag`, attachments included.
 fn set_bit(root: Entity, on: bool, children: &Query<&Children>, tags: &mut Query<&mut MeshTag>) {
     for e in std::iter::once(root).chain(children.iter_descendants(root)) {
         if let Ok(mut tag) = tags.get_mut(e) {
diff --git a/crates/benilla-app/src/target/hover.rs b/crates/benilla-app/src/target/hover.rs
index 3bd27050..508adba0 100644
--- a/crates/benilla-app/src/target/hover.rs
+++ b/crates/benilla-app/src/target/hover.rs
@@ -1,9 +1,6 @@
-//! The mouseover pick — which unit is under the cursor, recomputed each frame into
-//! [`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.
+//! The mouseover picks, each frame: the unit under the cursor into [`super::Hovered`] and the
+//! GameObject into [`super::HoveredObject`], as the reference's pick (`0x481190` → `0x7089c0`)
+//! finds them.
 
 use std::collections::HashSet;
 
@@ -27,15 +24,10 @@ 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`): 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
-/// hit is *strictly* nearer (`0x480eb4`: tie keeps the object). No cursor / mouselook →
-/// `INFINITY` (the picks bail on their own guards). The occluder set deliberately excludes net
-/// entities (units, GameObject hulls, transports) — they are the *object* trace; a chest must not
-/// occlude itself.
+/// Trace this frame's world hit, the reference's `CWorld::Intersect` leg of the scene trace
+/// (`0x480df0`), through the [`PickOccluder`] set: terrain, the WMO walk-bake faces (about the
+/// `0x84` reject mask) and static doodad hulls. Net entities are the object trace, not occluders,
+/// so a chest never occludes itself. The picks run unbounded and compare against it after.
 pub(super) fn update_pick_occlusion(
     camera: Query<(&Camera, &GlobalTransform), With<WorldCamera>>,
     window: Query<&Window, With<PrimaryWindow>>,
@@ -59,8 +51,7 @@ pub(super) fn update_pick_occlusion(
         ray.direction,
         f32::MAX,
         true,
-        // Default (terrain/doodads) + the WMO *walk* bake — the mask that reaches every
-        // `PickOccluder`-marked collider; the marker picks the exact occluder set within it.
+        // The mask that reaches every `PickOccluder` collider; the marker picks the set within it.
         &benilla_world::collision::WorldCollision::body_filter(),
         &|e| occluders.contains(e),
     ) {
@@ -69,19 +60,10 @@ pub(super) fn update_pick_occlusion(
     }
 }
 
-/// Every model instance whose parts are `unit`'s pick geometry: **the body, everything it wears,
-/// and its mount** (decision 1658; the mount leg is 0441's).
-///
-/// This is the reference's chained-model set. `0x480d90` registers a pick candidate by walking the
-/// 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.
-///
-/// 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**
-/// ([`crate::capture::probes`]'s `pick=` column), which must count what the picker will actually
-/// test and not a second opinion about it.
+/// The model instances whose parts are `unit`'s pick geometry: the body, everything it wears, and
+/// its mount. The reference's `0x480d90` walks the CM2 attachment tree (`[model+0x1dc]` head,
+/// `[+0x1e4]` sibling) and registers each model (`0x713cb0`) under one candidate, so a hit on a
+/// held axe is a hit on its wielder. `pub(crate)` for the capture census, which counts the same.
 pub(crate) fn pick_model_roots(
     unit: Entity,
     worn: &[Option<Entity>],
@@ -92,65 +74,40 @@ pub(crate) fn pick_model_roots(
         .chain(mount)
 }
 
-/// **Where every model's skeleton is right now** — the owned palette rows and the per-part link
-/// that indexes them, as one [`SystemParam`].
-///
-/// They are two halves of one lookup ([`update_hover`]'s `palette_of` reads both, in that order,
-/// and neither has ever been wanted alone) and they are bundled because the picker sits exactly on
-/// Bevy's 16-param function-system ceiling — the seat this freed went to the `IsSelectable` grader
-/// (decision 2060), which has to run *inside* the pick rather than after it so [`Hovered`] is never
-/// published in its ungraded state.
+/// Every model's current skeleton pose, as one [`SystemParam`] (the picker is at Bevy's 16-param
+/// limit): the palette rows and the per-part rig link that indexes them.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(super) struct PickPose<'w, 's> {
-    /// The owned palette table (decision 0720): the picker reads the same world-space matrices the
-    /// vertex stage skins with, straight from the CPU rows.
+    /// The world-space matrices the vertex stage skins with, read from the CPU rows.
     palettes: Res<'w, benilla_world::rig_palette::RigPalettes>,
     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 (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
-/// generous retry — never LoS/spell traces): the same posed mesh with every vertex displaced
-/// **+1 model-unit along its skinned normal** (a ~1-yd halo, fattest where the body is widest),
-/// resolved by the reference's priority ladder — last frame's pick sticks (anti-flicker), else an
-/// alive unit beats a dead one even when farther, ties by distance. A unit with no skinned parts
-/// (cube fallback) keeps the interim render-mesh AABB test, competing at pass-1 level. Inert while
-/// mouse-looking (cursor hidden) or over the dev UI.
-///
-/// **A unit's pick geometry includes what it wears** (decision 1658): every model chained to the
-/// body — held weapons, the helm, the shoulders, a mount — is its own pass-1/pass-2 candidate
-/// resolving to the same unit, because the reference registers the whole CM2 attachment tree into
-/// the pick scene under one candidate node (`0x480d90` walking `[model+0x1dc]`/`[+0x1e4]`).
+/// The unit under the cursor, as the reference's pick (`0x7089c0`) finds it. Broad phase: the ray
+/// against the playing sequence's bounds sphere. Pass 1: the ray against the posed render mesh,
+/// nearest wins. Pass 2, the mouse pick's retry when pass 1 hit nothing anywhere: every vertex
+/// pushed 1 model unit along its skinned normal, a halo of about a yard, won by last frame's pick,
+/// else the higher priority (alive 3, dead 2), else the nearer. Every model chained to a unit is
+/// its geometry ([`pick_model_roots`]); a unit with no skinned parts takes a box test at pass-1
+/// level. Inert while mouse-looking or over the UI.
 #[allow(clippy::type_complexity)]
 pub(super) fn update_hover(
     camera: Query<(&Camera, &GlobalTransform), With<WorldCamera>>,
     window: Query<&Window, With<PrimaryWindow>>,
     rig: Res<CameraControl>,
     pointer_over_ui: Res<PointerOverUi>,
-    // The frame's world-occlusion distance: the final pick is discarded iff the world hit is
-    // strictly nearer (behind terrain/WMO/doodad geometry — the post-hoc compare below).
     occlusion: Res<PickOcclusion>,
-    // The unit whose plate the pointer is inside (last frame's layout — the plate drive runs
-    // after this chain), published by the plate widgets themselves.
+    // The unit whose plate holds the pointer, as of last frame's plate layout.
     plate_hover: Res<crate::vplates::PlateHover>,
     mut hovered: ResMut<Hovered>,
     mesh_assets: Res<Assets<Mesh>>,
     pose: PickPose,
-    // `IsSelectable`'s second clause reads the active player's guid — see the grader at the publish.
+    // For `IsSelectable`'s `UNIT_FIELD_CREATEDBY` clause.
     self_guid: Res<crate::net::SelfGuid>,
-    // Last frame's pick, for pass 2's sticky-hover (the reference's anti-flicker cache: the previous
-    // pick outranks everything in the halo retry, so the hover doesn't strobe between two units).
+    // Last frame's pick, which outranks everything in pass 2 (the reference's anti-flicker cache).
     mut last_pick: Local<Option<Entity>>,
-    // Unit roots: pose + scale, the playing animation (for its bounds sphere), the descriptor store
-    // (alive-vs-dead sets the pass-2 priority), the part children — and whether the body is drawn
-    // at all. **You cannot click what is not in the scene** (decision 1277): a body the
-    // exterior-scene election sent to pass 2 never reaches the reference's draw list, so it takes
-    // no mouseover, no sword cursor and no click. This lane used to ray-test every unit root with a
-    // `Guid` and never ask, which is how the director could still target Tanaris mobs through a
-    // sealed cavern ceiling after their models had correctly stopped drawing.
+    // Unit roots. An undrawn body is not in the reference's draw list, so it takes no mouseover,
+    // cursor or click.
     roots: Query<
         (
             Entity,
@@ -162,22 +119,14 @@ pub(super) fn update_hover(
             Option<&Children>,
             Option<&crate::entities::mount::MountChild>,
             Option<&InheritedVisibility>,
-            // What this unit WEARS — the spawned root per attach slot. Each is a chained model
-            // and therefore pick geometry of its wearer (see the system doc); read here rather
-            // than by a query of its own because this system sits at Bevy's 16-param ceiling.
             Option<&HeldAttached>,
         ),
         (With<Guid>, Without<SelfPlayer>),
     >,
-    // A mounted unit's mount-child part children (decision 0441): the mount's geometry joins the
-    // unit's pick set — the reference draws mount + rider as one clickable unit.
+    // The part children of every pick model root: body, worn items and mount.
     child_sets: Query<&Children>,
-    // A part child's mesh + its palette-rig link (the rig its vertices pose through).
     parts: Query<(&Mesh3d, &benilla_world::rig_palette::RigPart)>,
-    // Fallback path: a unit's pickable mesh children, by [`CreaturePickPart`] (stamped beside the
-    // part's `WorldObject` at the attach sites, fallback cube included — the archetype filter that
-    // replaced a per-frame kind-compare over every streamed row) — model-local `Aabb`, world
-    // transform, and the link to the streamed parent (whose `Guid` we resolve the hit to).
+    // The box fallback: every `CreaturePickPart`, the fallback cube included.
     meshes: Query<
         (
             &ChildOf,
@@ -187,10 +136,7 @@ pub(super) fn update_hover(
         ),
         With<CreaturePickPart>,
     >,
-    // The pick's guid resolution — **and its kind**, which the skinless fallback below needs to
-    // apply the same eligibility rule the faithful path states inline (decision 1706: a corpse
-    // renders, and renders as a character body with pickable parts, but it is not a unit and a
-    // click must never send `CMSG_SET_SELECTION` for it).
+    // The pick's guid and kind; the kind decides which slot of `Hovered` a hit lands in.
     units: Query<(&Guid, &NetEntity), Without<SelfPlayer>>,
 ) {
     hovered.target = None;
@@ -199,19 +145,14 @@ pub(super) fn update_hover(
     hovered.corpse_guid = None;
     hovered.distance = f32::MAX;
     hovered.refused = false;
-    // **The plate publishes the mouseover, and it does so THROUGH the UI gate below, not around
-    // it.** A plate is mouse-enabled UI (2148): with the pointer inside one, the UI pointer pass
-    // owns the cursor, `PointerOverUi` is true, and the world pick correctly stands down — so this
-    // has to be read before that early return or hovering a plate would clear the mouseover it is
-    // supposed to set. That is the reference's own arrangement: the plate's OnEnter (`0x7cb850`)
-    // publishes `[0xb4e2c8]` directly, with none of the world hover's grading, and the frame walk
-    // stops there — no world pick behind it. Freelook still wins, because there the plates have
-    // handed the mouse back (`0x60f830`).
+    // A plate under the pointer is the mouseover, read before the UI gate below, which the plate
+    // itself trips: the reference's plate OnEnter (`0x7cb850`) publishes `[0xb4e2c8]` ungraded,
+    // with no world pick behind it. Freelook wins, as the plates hand the mouse back (`0x60f830`).
     if !rig.is_looking() {
         if let Some(entity) = plate_hover.0 {
             hovered.target = Some(entity);
             hovered.guid = units.get(entity).ok().map(|(g, _)| g.0);
-            hovered.distance = 0.0; // topmost UI — it beats any world GameObject at a tie
+            hovered.distance = 0.0; // topmost UI: it beats any world GameObject at a tie
             *last_pick = Some(entity);
             return;
         }
@@ -232,57 +173,36 @@ pub(super) fn update_hover(
     let (origin, dir) = (ray.origin, *ray.direction);
     let limit = occlusion.distance;
 
-    // ── The faithful path: collect broad-sphere-passing candidates, then pass 1 / pass 2 ────────
-    // A pass-2-eligible candidate: the unit, its pass-2 priority (alive 3 / dead 2 — the lootable
-    // refinement awaits loot state), its parts' mesh ids, and its posed joint palette.
+    // ── Broad phase, then pass 1 and pass 2 ──
+    // A candidate: the unit, its pass-2 priority, its parts' mesh ids and its posed joint palette.
     let mut candidates: Vec<(Entity, u8, Vec<AssetId<Mesh>>, Vec<Mat4>)> = Vec::new();
-    // Units the faithful path *owns* (they have skinned parts): excluded from the AABB fallback
-    // even when the broad phase rejects them — the reference wouldn't click them there either.
+    // Units with skinned parts: out of the box fallback even when the broad phase rejects them.
     let mut faithful: HashSet<Entity> = HashSet::new();
     for (entity, gt, net, anims, drv, store, children, mount_child, drawn, held) in &roots {
-        // Units, players — and **corpses** (decision 1723). A corpse is a skinned character body
-        // like any other, so it belongs in this pass, not in a fourth picker duplicating it; the
-        // reference picks every CGObject in one trace and switches on type at the end. Which slot
-        // of [`Hovered`] the winner lands in is decided at the publish below, by kind.
+        // Units, players and corpses: the reference picks every CGObject in one trace and
+        // switches on type at the end, below.
         if !matches!(
             net.kind,
             EntityKind::Unit | EntityKind::Player | EntityKind::Corpse
         ) {
             continue;
         }
-        // Not drawn ⇒ not clickable (see the query's note). Deliberately BEFORE `faithful.insert`
-        // below, so an undrawn unit is not claimed by the faithful path either — otherwise it
-        // would merely be excluded from the AABB fallback and stay unpickable by accident rather
-        // than by rule.
+        // Not drawn, not clickable. Checked before `faithful.insert`, so an undrawn unit is out by
+        // this rule, not by its exclusion from the box fallback.
         if !drawn.is_none_or(|v| v.get()) {
             continue;
         }
         let Some(children) = children else { continue };
-        // The models this unit WEARS, each its own pick candidate below. The reference registers
-        // every model **chained** to the object, not just its body: `0x480d90` walks the CM2
-        // 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 (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.
         let worn = held.map_or(&[][..], |h| h.spawned_slots().as_slice());
-        // Ownership probe only — no collect yet. The `skinned` Vec used to be built HERE, for
-        // every drawn unit in the scene, ahead of the few-FLOP broad phase that rejects nearly
-        // all of them (1473 §3's hover row); the survivors alone pay it now, below. Membership
-        // in `faithful` must still be decided pre-reject — a broad-phase-rejected skinned unit
-        // stays excluded from the AABB fallback by RULE, not by accident.
+        // Membership in `faithful` is decided before the broad phase rejects; the parts are
+        // collected below, for the survivors only.
         if !children.iter().any(|c| parts.contains(c)) && worn.iter().all(Option::is_none) {
             continue; // static/cube unit → the AABB fallback below
         }
         faithful.insert(entity);
-        // Broad phase: the playing sequence's bounds sphere, world-placed + world-scaled (uniform
-        // scale — the root bakes `OBJECT_FIELD_SCALE_X`). An unknown clip / unauthored radius passes
-        // through (the reference falls back to the header sphere; permissive is the safe direction).
-        // A MOUNTED unit passes through too: the rider's Mount-pose sphere doesn't cover the
-        // mount's body (the reference recomputes the pick radius from the mount's box — a P2
-        // refinement, decision 0441).
+        // Broad phase: the playing sequence's bounds sphere, scaled by `OBJECT_FIELD_SCALE_X`. An
+        // unauthored radius passes (the reference uses the header sphere), as does a mounted unit
+        // (the reference sizes it from the mount's box).
         let clip = match (anims, drv) {
             (Some(a), Some(d)) => d.active_anim().and_then(|id| a.find(id)),
             _ => None,
@@ -290,18 +210,14 @@ pub(super) fn update_hover(
         if let Some(c) = clip.filter(|c| c.bounds_radius > 0.0 && mount_child.is_none()) {
             let centre = gt.transform_point(c.bounds_center);
             let radius = c.bounds_radius * gt.scale().max_element();
-            // Ray-sphere: reject when the ray's closest approach to the centre exceeds the radius
-            // (dir is normalized; a centre behind the origin projects to t=0, keeping units we
-            // stand inside clickable).
+            // Reject when the ray's closest approach exceeds the radius; a centre behind the
+            // origin clamps to t = 0, so a unit we stand inside stays clickable.
             let along = (centre - origin).dot(dir).max(0.0);
             if (centre - origin - dir * along).length_squared() > radius * radius {
                 continue;
             }
         }
-        // The posed joint palette (parts of one skeleton share the rig): the same
-        // world-from-bind-pose matrices GPU skinning applies, read from the owned palette rows
-        // (decision 0720 — last frame's propagated pose, exactly what the previous
-        // joint-GlobalTransform read gave).
+        // The skinning matrices of one skeleton's parts, as of last frame's propagated pose.
         let palette_of =
             |sk: &[(&Mesh3d, &benilla_world::rig_palette::RigPart)]| -> Option<Vec<Mat4>> {
                 sk.first().and_then(|(_, part)| {
@@ -309,16 +225,9 @@ 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 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.
-        //
-        // The rung matters less than it looks: **pass 1 sorts on distance alone**, so a corpse
-        // can neither steal a click from a unit standing in front of it nor lose one it is in
-        // front of. Priority decides only the inflated pass-2 retry. Still not read off
-        // `unit_is_dead()` — a corpse descriptor has no UNIT block, so that accessor answers
-        // "alive" for one.
+        // The pass-2 ladder (`0x480c90`): alive 3, dead 2, a corpse 2 when
+        // `CORPSE_DYNFLAG_LOOTABLE`, else 0 (`0x480cec`). A corpse has no UNIT block, so
+        // `unit_is_dead()` would answer alive for it.
         let priority = if net.kind == EntityKind::Corpse {
             u8::from(store.is_some_and(|s| s.0.corpse_lootable())) * 2
         } else if store.is_some_and(|s| s.0.unit_is_dead()) {
@@ -326,12 +235,8 @@ pub(super) fn update_hover(
         } else {
             3
         };
-        // **One candidate per model instance, every one of them resolving to this unit** — the
-        // reference's own shape (one candidate node; every chained model registered under it).
-        // The body contributes nothing when it has no parts, which is not a reason to stop: a
-        // trigger creature's whole visible self is what it wears. An attached item rides a rigid
-        // one-frame palette of its own (`RigRider`, 1609), so it reads here exactly like a body —
-        // its parts, its rig, its pose — and so does a mount child (decision 0441).
+        // One candidate per model instance, all resolving to this unit. A partless body is no
+        // reason to stop: a trigger creature's whole visible self can be what it wears.
         for root in pick_model_roots(entity, worn, mount_child.map(|mc| mc.0)) {
             let Ok(kids) = child_sets.get(root) else {
                 continue;
@@ -349,9 +254,8 @@ pub(super) fn update_hover(
         }
     }
 
-    // Pass 1 — the exact posed render mesh, pure nearest-wins (the reference's first pass).
-    // UNBOUNDED, like the reference: the object trace never carries the world distance; occlusion
-    // is one strict compare on the final result (below).
+    // Pass 1: the exact posed mesh, nearest wins, unbounded as in the reference; occlusion is one
+    // compare on the result, below.
     let mut best: Option<(f32, Entity)> = None;
     for (entity, _, mesh_ids, palette) in &candidates {
         for id in mesh_ids {
@@ -364,11 +268,11 @@ pub(super) fn update_hover(
         }
     }
 
-    // ── Fallback for skinless units only: the model-bounds box test (pre-RE interim) ────────────
-    // A unit's parts are separate meshes; testing each and keeping the closest parent is equivalent
-    // to testing the union. `dir` is normalized, so `t` is a world distance like the hits above.
+    // ── The box fallback, for skinless units only ──
+    // The nearest part per parent is the union's hit; `dir` is normalized, so `t` is a world
+    // distance like the hits above.
     for (child_of, aabb, gt, drawn) in &meshes {
-        // …and the same rule on the skinless fallback: a part inherits its root's pass-2 verdict.
+        // Not drawn, not clickable: a part inherits its root's visibility.
         if !drawn.is_none_or(|v| v.get()) {
             continue;
         }
@@ -376,12 +280,8 @@ pub(super) fn update_hover(
         if faithful.contains(&parent) {
             continue; // posed-mesh-tested above
         }
-        // The same eligibility the faithful path states at its head — and **a bone pile lives
-        // here** (decision 1723): the skeletal corpse model ships without a skeleton, so it never
-        // reaches the posed-mesh pass and this box test is the only thing that can ever pick it.
-        // The self player is still excluded (its query filter), and so is everything that is not a
-        // body: a hit resolves to a `Guid` the click will act on, and the kind decides which slot
-        // of [`Hovered`] receives it.
+        // The same kinds as the posed pick. A bone pile lands here: its corpse model has no
+        // skeleton, so only this box test can pick it.
         let Ok((_, parent_net)) = units.get(parent) else {
             continue;
         };
@@ -398,10 +298,7 @@ pub(super) fn update_hover(
         }
     }
 
-    // Pass 2 — nothing exactly hit: the reference's generous retry (mouse-pick only). Same
-    // candidates, every vertex displaced +1 model-unit along its skinned normal — a ~1-yd halo
-    // around the drawn body. Accept by the priority ladder, not pure distance: last frame's pick
-    // sticks (anti-flicker), else higher priority wins even when farther, ties by distance.
+    // Pass 2, when nothing hit exactly: the halo, won by the priority ladder, not distance.
     if best.is_none() {
         let mut best2: Option<(f32, u32, Entity)> = None;
         for (entity, priority, mesh_ids, palette) in &candidates {
@@ -423,14 +320,12 @@ pub(super) fn update_hover(
         best = best2.map(|(t, _, e)| (t, e));
     }
 
-    // The occlusion verdict — the reference's single strict compare (`0x480df0` @ `0x480eb4`):
-    // the object hit is discarded iff the world hit is STRICTLY nearer (a tie keeps the object).
+    // Occlusion (`0x480eb4`): a strictly nearer world hit drops the pick, a tie keeps it.
     if best.is_some_and(|(t, _)| limit < t) {
         best = None;
     }
-    // **Switch on type at the end**, the reference's own shape: the one pick lands in the unit slot
-    // or the corpse slot, never both. Everything downstream that means "unit" reads `target` and so
-    // stays right by construction; the corpse legs read `corpse`.
+    // Switch on type at the end, as the reference does: the one pick lands in the unit slot or the
+    // corpse slot, and a unit the `IsSelectable` grader refuses in neither.
     if let Some((t, entity)) = best {
         if let Ok((guid, net)) = units.get(entity) {
             if net.kind == EntityKind::Corpse {
@@ -447,53 +342,22 @@ pub(super) fn update_hover(
         } else {
             hovered.refused = true;
         }
-        // Set on EVERY arm, the refusal included — see [`Hovered::refused`].
+        // Set on every arm, the refusal included (`Hovered::refused`).
         hovered.distance = t;
     }
     *last_pick = best.map(|(_, e)| e);
 }
 
-/// **The hover grader's `IsSelectable` verdict** — `0x4828d0`, the step between the pick and the
-/// mouseover publish:
+/// The hover grader's `IsSelectable` test: `0x4828d0` calls vtable slot 21 at `0x482982`
+/// (`0x60be60`, the predicate `SetSelection` runs), and a refusal jumps to `0x482090(0,0)` and
+/// `ResetCursor 0x523d30`, past the publisher `0x492890`: no tooltip, cursor, brighten or click.
 ///
-/// ```text
-/// 48297d  mov  eax,[esi]              ; the picked object's vtable
-/// 482982  call [eax+0x54]             ; slot 21 = 0x60be60 IsSelectable — the SAME predicate
-/// 482985  test eax,eax                ;   SetSelection runs, reached there via the +0x58 thunk
-/// 482987  je   0x4829ed               ; FALSE -> 0x482090(0,0) + ResetCursor 0x523d30
-/// ```
-///
-/// So the refusal is **total, and it is one rule**: the mouseover globals `[0xb4e2c8]/[0xb4e2cc]`
-/// are cleared (their only two writers image-wide live in the publisher `0x492890`, which that jump
-/// skips), the cursor is reset, and the type dispatch that would have chosen an Interact/Attack
-/// cursor never runs. No tooltip, no cursor, no brighten and no click, out of one predicate rather
-/// than four.
-///
-/// **It is a grader, not a filter, and the difference is observable.** A census over the pick itself
-/// (`0x480a50`, `0x480d90`, `0x713cb0`, `0x481190`, `0x480df0`) finds **zero** reads of
-/// `[obj+0x110]`/`[+0xa0]` — positive control: four such reads inside `CanAttack` — so the flagged
-/// unit is registered as a candidate and *wins* the trace before anything looks at it. That is why
-/// the caller records [`Hovered::refused`] and keeps the pick's distance instead of skipping the
-/// candidate: a trigger stalker in front of a chest takes the pick, and the chest behind it must not
-/// inherit the mouseover.
-///
-/// Applied to the **unit** arms only. A corpse reaches `0x482982` too, but slot 21 there is
-/// `CGCorpse_C`'s, not `CGUnit_C`'s — the `xor eax,eax` base stub sits at slot **22** (`+0x58`),
-/// which is what makes a non-unit unselectable for `SetSelection`, and is not what this call goes
-/// through.
-///
-/// A **plate** hover is a deliberate non-case: the reference publishes it straight from
-/// `0x7cb869 call 0x492890` with no grader at all, so a plate on a flagged unit *would* tooltip —
-/// but the per-tick plate gate `0x60f600` refuses the same units one step earlier
-/// (`0x60f622`/`0x60f628`, unconditional, re-run every OnUpdate), which `crate::vplates` already
-/// models. There is no reachable state where the two disagree.
-///
-/// Run at the publish rather than as a system of its own, deliberately. The reference really does
-/// pick and *then* grade, but a second Bevy system means [`Hovered`] is briefly readable in its
-/// 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.
-///
-/// Decision 2060.
+/// It grades the winner and filters no candidate: the pick (`0x480a50`, `0x480d90`, `0x713cb0`,
+/// `0x481190`, `0x480df0`) reads no unit field, so a refused unit in front of a chest still takes
+/// the pick ([`Hovered::refused`]). A corpse's slot 21 is `CGCorpse_C`'s, so only the unit arms
+/// run this. A plate hover skips the grader (`0x7cb869`), but the plate gate `0x60f600` already
+/// refuses the same units (`0x60f622`/`0x60f628`). Graded at the publish, so [`Hovered`] is never
+/// readable ungraded.
 #[allow(clippy::type_complexity)] // the picker's own root query, borrowed as-is
 fn selectable_pick(
     entity: Entity,
@@ -518,78 +382,33 @@ fn selectable_pick(
     super::relations::is_selectable(store, self_guid)
 }
 
-/// Recompute the **GameObject** under the cursor each frame into [`HoveredObject`] (decision 0236):
-/// a mesh-accurate ray pick against GameObject parts *only*, reusing the inspector's picker
-/// (the resident-geometry caster of decision 0857, which hits the colliderless props a physics ray
-/// misses and the `RENDER_WORLD`-only static forms Bevy's `MeshRayCast` lost at 0834). Kept
-/// separate from [`update_hover`]'s unit pick because a GameObject is usable-but-not-*selected*:
-/// this drives the Interact cursor and the right-click USE, never selection. Inert while
-/// mouse-looking (cursor hidden) or over the dev UI, exactly like the unit pick. Cheap — only the
-/// 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`): **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*
-/// its leaves instead of only pixel-on-texture. "Nothing anywhere" spans the unit pick too (one
-/// resolve in the reference): a frame where [`Hovered`] holds any unit — exact hit or its own
-/// halo — never opens the GO halo, because the pass-2 accept ladder ranks every unit (alive 3 /
-/// dead 2) above every GameObject (highlightable 1 / else 0). Within the GO halo the same ladder
-/// applies: last frame's pick sticks (anti-flicker), else higher priority wins even when farther,
-/// ties by distance. Both passes stay world-occlusion-clamped. (Residual, same slice as the
-/// eligibility note below: the reference's sticky slot is cross-type, so a stuck GO pick can
-/// outrank a unit's halo there; our split picks give the unit that frame instead.)
-/// The GO picker's own state, bundled — the pick-set cache with the stream edges that rebuild
-/// it, plus the sticky-hover memory — one [`SystemParam`] because [`update_hovered_object`]
-/// sits at Bevy's 16-param function-system ceiling. See the maintenance comment at the top of
-/// that system for the cache contract.
+/// The GameObject picker's state as one [`SystemParam`] (the picker is at Bevy's 16-param limit):
+/// the pick-set cache and the stream edges that rebuild it, the sticky pick and the probe's locals.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(super) struct GoPickSet<'w, 's> {
     added: Query<'w, 's, (), Added<GoPickPart>>,
     removed: RemovedComponents<'w, 's, GoPickPart>,
     cache: Local<'s, bevy::platform::collections::HashSet<Entity>>,
-    /// Last frame's GO pick, for pass 2's sticky-hover (the reference's anti-flicker cache, by
-    /// net entity — the same rung the unit picker keeps).
+    /// Last frame's pick by net entity, which outranks everything in pass 2.
     last_pick: Local<'s, Option<Entity>>,
-    /// Every pickable billboard card, for [`net_entity_of`]'s first hop. Bundled here rather than
-    /// taken as its own `SystemParam` because [`update_hovered_object`] is at Bevy's 16-param
-    /// function-system ceiling.
+    /// Every billboard card, for [`net_entity_of`]'s first hop.
     cards: Query<'w, 's, &'static BillboardCard>,
-    /// The headless probe's frame counter and its say-once report ([`super::hover_probe`], 2250).
-    /// `Local`s: in a player run the probe is unarmed, so these are one `u64` and one `None` that
-    /// nothing ever reads.
+    /// The headless probe's frame counter and say-once report ([`super::hover_probe`]), idle in
+    /// a player run.
     frame: Local<'s, u64>,
     report: Local<'s, super::hover_probe::ProbeReport>,
-    /// `WOW_HOVER_PROBE=lock`'s held target (2255) — the object the probe rests its aim on for the
-    /// remainder of the run.
+    /// `WOW_HOVER_PROBE=lock`'s held target, where the probe rests its aim for the rest of the run.
     lock: Local<'s, super::hover_probe::LockedAim>,
 }
 
-/// The number of `ChildOf` hops [`net_entity_of`] will climb before giving up — a malformed-data
-/// guard, not a real depth. The deepest real chain is a card on a nested joint (bone hierarchies
-/// in the shipped corpus are single digits deep), so this is orders of margin.
+/// The most `ChildOf` hops [`net_entity_of`] climbs: a malformed-data guard, as real joint chains
+/// are single digits deep.
 const NET_WALK_HOPS: usize = 64;
 
-/// A picked GameObject part → the **net entity** that carries its `Guid` (the object the mouseover
-/// publishes, the cursor classifies and the right-click USEs).
-///
-/// Two shapes reach here and they attach differently. An ordinary mesh part is a direct child of
-/// the net entity — one `ChildOf` hop. A **billboard card is a world ROOT** (decision 0153: a card
-/// writes an absolute world transform and lives at the root/identity), so it has no `ChildOf` edge
-/// at all: its link to the model is [`BillboardCard::follows`] — the joint it rides on a rigged
-/// host, the mirror anchor under the net entity otherwise — and the climb continues from there.
-///
-/// Before the card hop existed a card hit resolved to the **card**, which carries no `Guid`, so
-/// [`update_hovered_object`] bailed and published the **null** mouseover: no cursor, no tooltip and
-/// a dead right-click over exactly the screen area the card covers. The Lightwell found it (B169's
-/// second half) — its light shaft is a lock-Z card standing 4.5 yd out of a 1.09 yd bowl, so the
-/// 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 — so
-/// a hit on the shaft **is** a hit on the GameObject, which is what this restores.
+/// A picked GameObject part's net entity, the one carrying its `Guid`. A mesh part is its child; a
+/// billboard card is a world root linked by [`BillboardCard::follows`] (a joint on a rigged host,
+/// else the mirror anchor), and the climb goes on from there. The reference's narrow phase walks
+/// the one model's batches, billboards included (`0x7089c0`), so a card hit is a GameObject hit.
 fn net_entity_of(
     e: Entity,
     cards: &Query<&BillboardCard>,
@@ -611,22 +430,19 @@ fn net_entity_of(
     cur
 }
 
-/// The state the GameObject gates read beside the object's own store, bundled because this system
-/// sits at Bevy's 16-`SystemParam` ceiling: the ask-once template cache (GENERIC's eligibility is
-/// its `data[1]`, decision 0762; MEETINGSTONE's is its `data[2]`), the faction catalog behind the
-/// eligibility faction term (decision 0764), and the live meeting-stone queue — benilla's
-/// `[0xb72038]`, the other half of MEETINGSTONE(23)'s own highlightable predicate (decision 2283).
+/// What the GameObject gates read beside the object's store: the template cache (GENERIC's
+/// eligibility is its `data[1]`, MEETINGSTONE's its `data[2]`), the faction catalog, and the
+/// meeting-stone queue, the reference's `[0xb72038]`.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct GoGateInputs<'w> {
     pub(crate) templates: Res<'w, crate::go_templates::GameObjectTemplates>,
     pub(crate) factions: Option<Res<'w, super::ring::Factions>>,
-    /// `Option` because a headless/net-less build mounts no UI dialog verbs; absent reads as the
-    /// reference's zero-initialized `[0xb72038]`, i.e. not queued.
+    /// Absent in a net-less build, read as the reference's zeroed `[0xb72038]`: not queued.
     pub(crate) stone: Option<Res<'w, crate::ui_dialog_verbs::MeetingStone>>,
 }
 
 impl GoGateInputs<'_> {
-    /// `[0xb72038]` — the area we are queued at, `0` when we are not (or when there is no VM).
+    /// `[0xb72038]`, the area we are queued at, or 0.
     pub(crate) fn queued_area(&self) -> u32 {
         self.stone.as_deref().map_or(0, |s| s.area)
     }
@@ -638,24 +454,16 @@ pub(super) fn update_hovered_object(
     rig: Res<CameraControl>,
     pointer_over_ui: Res<PointerOverUi>,
     occlusion: Res<PickOcclusion>,
-    // The unit pick's verdict — [`update_hover`] runs earlier in the target chain. Any unit hover
-    // means pass 1 + the unit halo already own the mouseover, so the GO pass 2 stays shut.
+    // The unit pick, earlier in the chain: a unit hover keeps the GameObject halo shut.
     unit_hovered: Res<Hovered>,
     mut hovered: ResMut<HoveredObject>,
-    // Every pickable GameObject part carries [`GoPickPart`] (stamped beside its
-    // `WorldObject { kind: GameObject }` at the attach sites; units/doodads/WMOs never enter this
-    // query — units have their own posed-mesh pick).
     go_parts: Query<Entity, With<GoPickPart>>,
     child_of: Query<&ChildOf>,
     guids: Query<&Guid>,
     stores: Query<&ObjectStore>,
-    // The three state reads the GameObject gates need beside the object's own store, as one
-    // param (the 16-`SystemParam` ceiling) — see [`GoGateInputs`].
     go_gate: GoGateInputs,
     self_q: Query<&ObjectStore, With<crate::net::SelfPlayer>>,
     parts: PickParts,
-    // The picker's own state, one bundled param ([`GoPickSet`] — the fn sits at Bevy's
-    // 16-param ceiling): the pick-set cache, its stream edges, and the sticky-hover memory.
     mut cache: GoPickSet,
 ) {
     *cache.frame = cache.frame.wrapping_add(1);
@@ -664,30 +472,19 @@ pub(super) fn update_hovered_object(
     let pickable = &mut *cache.cache;
     let last_pick = &mut *cache.last_pick;
     let cards = &cache.cards;
-    // The hit part → its guid-bearing net entity ([`net_entity_of`]: the card hop, then the climb).
     let resolve_net = |e: Entity| net_entity_of(e, cards, &guids, &child_of);
-    // The pick set (bevy's `HashSet` — the caster's type, not the `std` one this module uses
-    // elsewhere), rebuilt on GO-part stream edges ONLY — the `WaterIndex` shape. It used to be
-    // collected from every streamed GO part on every cursor frame (ChildOf hop + store probe +
-    // hash insert each); membership only actually changes when GO models spawn or despawn, and
-    // a GO's type id never changes after create. Maintained FIRST, ahead of every early return:
-    // an `Added` edge is only visible on the frame it happens (the run advances this system's
-    // change tick even through a `return`), so a rebuild parked behind the cursor gates would
-    // silently drop parts streamed in while the pointer sat on UI. A despawned entry between
-    // edges self-filters at the caster (`parts.get` on a dead entity misses).
+    // The pick set, rebuilt only on GameObject-part stream edges (a type id never changes after
+    // create). Maintained before any early return: an `Added` edge shows only on its own frame, so
+    // a rebuild behind the cursor gates would drop parts streamed in while the pointer sat on UI.
+    // A part despawned between edges misses at the caster.
     //
-    // A transport-family GO (TRANSPORT 11 / MAP_OBJECT 14 / MO_TRANSPORT 15) never joins the
-    // set: in the reference it has no pick geometry at all — the GO model resolver `0x5f80e0`
-    // returns 0 for these three types (they render via the WMO/spline path, not an M2) and their
-    // strategy's interaction predicates are constant-false (w2c1 + go-render-gate + the +0x14
-    // vtable dump). Concretely: a ship's hull must not swallow the pick — an NPC on deck stays
-    // hoverable through the railing, and the hull shows no gear or tooltip.
+    // Transports (TRANSPORT 11, MAP_OBJECT 14, MO_TRANSPORT 15) never join: the reference's model
+    // resolver `0x5f80e0` gives them no pick geometry and their interaction predicates are
+    // constant false, so a ship's hull never swallows the pick of an NPC on deck.
     if removed_parts.read().next().is_some() || !added_parts.is_empty() {
         pickable.clear();
         pickable.extend(go_parts.iter().filter(|&e| {
-            // Through the same resolver the hit uses, so a card and its mesh siblings can never
-            // disagree about which GameObject they belong to (a transport's card would otherwise
-            // stay in the set while its meshes were filtered out).
+            // Through the hit's own resolver, so a card and its mesh siblings agree.
             !stores
                 .get(resolve_net(e))
                 .is_ok_and(|s| matches!(s.0.gameobject_type_id(), 11 | 14 | 15))
@@ -696,8 +493,7 @@ pub(super) fn update_hovered_object(
     hovered.target = None;
     hovered.guid = None;
     hovered.distance = f32::MAX;
-    // The sticky-hover cache drops the moment the pointer is not ours, exactly as before — the
-    // probe's aim below must not change *when* that happens.
+    // The sticky pick drops the moment the pointer is not ours.
     let yielded = rig.is_looking() || pointer_over_ui.0;
     if yielded {
         *last_pick = None;
@@ -705,13 +501,9 @@ pub(super) fn update_hovered_object(
     let (Ok((camera, cam_tf)), Ok(window)) = (camera.single(), window.single()) else {
         return;
     };
-    // The aim. A person's pointer always wins; the probe (2250) answers only for a window that has
-    // no cursor at all, which is every automated run — see [`super::hover_probe`].
-    //
-    // **Resolved and PUBLISHED ahead of the yield below** (2255), because the UI mouse feed reads
-    // the published aim as its pointer: a frame that returned early without publishing would take
-    // the pointer off the UI, drop `PointerOverUi`, and unlatch the very gate that skipped the
-    // pick — the probe would flicker the interface on and off instead of resting on it.
+    // The aim: the OS pointer, else the probe's for a cursorless window. Published before the
+    // yield, as the UI mouse feed reads it as its pointer: skipping it would drop `PointerOverUi`
+    // and flicker the UI the probe rests on.
     let probing = super::hover_probe::armed();
     let probe_aim = cache
         .lock
@@ -733,10 +525,8 @@ pub(super) fn update_hovered_object(
     };
     let self_store = self_q.single().ok();
 
-    // The probe's census (2250): once a second, where the pickable GameObjects actually ARE on
-    // screen. Without it a headless "no hit" is unreadable — it cannot tell a pick fault from a
-    // camera that is simply not looking at the thing, which is the single question a person with a
-    // mouse never has to ask.
+    // The probe's census, once a second: where the pickable GameObjects are on screen, so a
+    // headless miss tells a pick fault from a camera looking elsewhere.
     if probing && (*cache.frame).is_multiple_of(60) {
         let rows: Vec<String> = pickable
             .iter()
@@ -765,15 +555,18 @@ pub(super) fn update_hovered_object(
         );
     }
 
-    // Pass 1 — the exact resident geometry, pure nearest-wins (priority-independent).
+    // Pass 1: the exact resident geometry, nearest wins.
     let mut best: Option<(f32, Entity)> =
         benilla_world::interact::cast_pick_ray(ray, pickable, &parts, false)
             .into_iter()
             .next()
             .map(|(e, h)| (h.distance, e));
 
-    // Pass 2 — nothing exactly hit anywhere (no GO, and no unit either — the doc above): the
-    // generous retry over the normal-inflated geometry, accepted by the priority ladder.
+    // Pass 2, only when nothing hit anywhere, units included (one resolve in the reference): the
+    // geometry pushed 1 model unit along its normals, a halo of about a yard that makes a wispy
+    // herb clickable around its leaves. Every unit outranks every GameObject on that ladder, so a
+    // unit hover keeps it shut. The reference's sticky pick is cross-type and can hold a
+    // GameObject over a unit's halo; here the unit wins that frame.
     if best.is_none() {
         if unit_hovered.target.is_some() {
             *last_pick = None;
@@ -785,9 +578,8 @@ pub(super) fn update_hovered_object(
             let prio = if *last_pick == Some(net) {
                 u32::MAX // the sticky-hover cache outranks everything
             } else {
-                // The classify priority (`0x480c90`): highlightable GameObject 1, else 0. A store
-                // that hasn't streamed reads highlightable — the eligibility gate's own
-                // permissive default, so a fresh spawn isn't a dead zone for its first frames.
+                // `0x480c90`: highlightable 1, else 0. A store not yet streamed reads
+                // highlightable, the eligibility gate's own default.
                 stores.get(net).map_or(1, |s| {
                     let reaction = crate::target::cursor_mode::go_reaction(
                         go_gate.factions.as_deref(),
@@ -820,8 +612,7 @@ pub(super) fn update_hovered_object(
         best = best2.map(|(t, _, e)| (t, e));
     }
 
-    // The occlusion verdict (`0x480df0` @ `0x480eb4`): discard the GO hit iff the world hit is
-    // STRICTLY nearer — a tie keeps the object.
+    // Occlusion (`0x480eb4`): a strictly nearer world hit drops the pick, a tie keeps it.
     if best.is_some_and(|(t, _)| occlusion.distance < t) {
         best = None;
     }
@@ -839,17 +630,10 @@ pub(super) fn update_hovered_object(
     let Ok(guid) = guids.get(net_entity) else {
         return;
     };
-    // **The mouseover-eligibility gate** (`[obj->vtbl+0x54]` at `0x482982`, decision 0762): an
-    // ineligible object publishes the NULL mouseover, so it gets no tooltip, no +64 brighten and no
-    // cursor — nothing. Applied here, at the one place the GO mouseover is published, so all three
-    // consumers fall out together exactly as they do in the reference (which reaches `0x492890`,
-    // `0x52aa20` and `0x4945e0` only past this gate).
-    //
-    // KNOWN RESIDUAL: the reference nulls the **whole** mouseover, so a unit standing behind an
-    // ineligible portcullis is not hoverable through it either. benilla picks unit and GameObject
-    // separately and arbitrates by distance, so here the unit behind it stays hoverable. Narrower
-    // than the old behaviour (which tooltipped the portcullis itself) and documented rather than
-    // silently accepted; closing it wants the single-pick arbitration, which is its own slice.
+    // The mouseover-eligibility gate (vtable `+0x54` at `0x482982`): an ineligible object
+    // publishes the null mouseover, so no tooltip, brighten or cursor; the reference reaches
+    // `0x492890`, `0x52aa20` and `0x4945e0` only past it. Its null mouseover also hides a unit
+    // behind the object, which our split picks leave hoverable.
     if let Ok(store) = stores.get(net_entity) {
         let tmpl = go_gate.templates.get(guid.0);
         let reaction = crate::target::cursor_mode::go_reaction(
@@ -896,10 +680,8 @@ pub(super) fn update_hovered_object(
                 tmpl.map(|t| t.highlight_column),
                 occlusion.distance,
             ));
-            // `lock` takes its target here and nowhere else: past the eligibility gate, so the
-            // probe holds something that actually publishes a mouseover rather than the first
-            // lamp-post the grid grazed. The hit point is re-expressed in the PART's frame so the
-            // aim survives the camera settling and the object moving (see [`LockedAim`]).
+            // `lock` holds only an object past the eligibility gate, the hit kept in the part's
+            // frame so the aim survives the camera and the object moving.
             if super::hover_probe::locks() {
                 if let Some((t, part)) = best {
                     if let Ok((_, gt, ..)) = parts.get(part) {
@@ -930,24 +712,13 @@ mod tests {
         BillboardCard::following(&info, owner)
     }
 
-    /// **A billboard card's hit belongs to its GameObject** — bug B169's second half, the Lightwell
-    /// you could see but not click (2026-08-25).
-    ///
-    /// A card is a world ROOT, so the old one-`ChildOf`-hop resolve answered with the card itself;
-    /// the card carries no `Guid`, so `update_hovered_object` bailed and published the null
-    /// mouseover — no cursor, no tooltip, a dead right-click — over the whole screen area the card
-    /// covers. On `G_HolyLightWell.m2` that is a 4.5 yd shaft standing out of a 1.09 yd bowl, so
-    /// nearly every ray landed on the dead card and only the ring of bowl around it answered:
-    /// *"very hard to find the right position, and even when I see the cog nothing happens"*.
-    ///
-    /// Both card shapes are covered, because `spawn_billboard_part` picks between them on whether
-    /// the host is rigged: following the **mirror anchor** (a direct child of the net entity) and
-    /// following a **joint** (nested under the model root, so the climb is more than one hop).
+    /// Both card shapes `spawn_billboard_part` makes: following the mirror anchor (a rigless host)
+    /// and following a nested joint (a rigged one).
     #[test]
     fn a_billboard_cards_hit_resolves_to_its_gameobject() {
         let mut world = World::new();
         let net = world.spawn(Guid(0xdead_beef)).id();
-        // An ordinary mesh part: the direct child the old one-hop resolve was written for.
+        // An ordinary mesh part, a direct child.
         let mesh_part = world.spawn(ChildOf(net)).id();
         // The rigless shape: the card follows the mirror anchor under the net entity.
         let anchor = world.spawn(ChildOf(net)).id();
@@ -995,14 +766,8 @@ mod tests {
         assert_eq!(resolved[4], net, "the net entity resolves to itself");
     }
 
-    /// **A unit's pick geometry is every model chained to it** — decision 1658, the Naxxramas
-    /// weapon mobs (`.go xyz 2729.28 -3159.80 267.54 533`).
-    ///
-    /// "Unholy Axe" is an `InvisibleStalker` body — 80 bones, 135 animations, zero vertices —
-    /// holding a real axe on its right-hand attachment. Enumerating only the body left the unit
-    /// with no pick candidate at all, so the model could not be hovered or clicked and the name
-    /// plate was the only way to select it. The reference registers each chained model under the
-    /// same candidate node, which is what makes the axe itself the clickable surface.
+    /// Naxxramas's "Unholy Axe" is an `InvisibleStalker` body with no vertices holding a real axe,
+    /// which is its whole pick surface.
     #[test]
     fn a_units_pick_geometry_is_every_model_chained_to_it() {
         let unit = Entity::from_raw_u32(1).unwrap();
@@ -1013,8 +778,8 @@ mod tests {
         let bare: Vec<_> = pick_model_roots(unit, &[], None).collect();
         assert_eq!(bare, vec![unit], "a unit wearing nothing is just its body");
 
-        // The empty slots between the filled ones are the real `HeldAttached` shape (main/off/
-        // ranged/helm/shL/shR/ammo/quiver), and must not become candidates.
+        // Empty slots, as in the real `HeldAttached` (main, off, ranged, helm, both shoulders,
+        // ammo, quiver), are not candidates.
         let worn = [
             Some(main_hand),
             None,
@@ -1032,7 +797,7 @@ mod tests {
             "body, then every worn model, then the mount — all one unit's geometry"
         );
 
-        // The case that was broken: the body draws nothing, so the axe is the whole hit surface.
+        // A body that draws nothing: the axe is the whole hit surface.
         let trigger: Vec<_> = pick_model_roots(unit, &worn[..1], None).collect();
         assert!(
             trigger.contains(&main_hand),
diff --git a/crates/benilla-app/src/target/hover_probe.rs b/crates/benilla-app/src/target/hover_probe.rs
index 6aeeb51b..415cd783 100644
--- a/crates/benilla-app/src/target/hover_probe.rs
+++ b/crates/benilla-app/src/target/hover_probe.rs
@@ -1,44 +1,22 @@
-//! **The headless hover probe** (decision 2250) — aim the mouseover pick from a screen point when
-//! the window has no OS cursor of its own, and say what the pick found.
+//! The headless hover probe: aims the mouseover pick from a screen point when the window has no OS
+//! cursor, and reports what the pick found. An unattended run's window never receives the OS
+//! cursor, so without it [`super::hover::update_hovered_object`] never reaches the pick.
 //!
-//! ## Why this exists
-//!
-//! An automated run **cannot hover anything**. The rig's probe window (640×360, corner-parked,
-//! always-on-top) never receives the OS cursor: `Window::cursor_position()` stays `None` through a
-//! `CGWarpMouseCursorPosition` *and* through HID-level `mouseMoved` events posted into its content
-//! rect, so [`super::hover::update_hovered_object`] returns before the pick on every frame. The
-//! consequence is not subtle — every report of the shape *"this object shows no tooltip"* has had to
-//! be settled by the director hovering it and reading the card back to us, because the pick was
-//! reachable only by a person with a mouse (2248 recorded that gap; this closes it).
-//!
-//! ## What it does
-//!
-//! `WOW_HOVER_PROBE` names where to aim, in the window's own cursor space (logical px, y-down):
+//! `WOW_HOVER_PROBE` names the aim, in the window's cursor space (logical px, y-down):
 //!
 //! | value | aim |
 //! |---|---|
 //! | `centre` / `center` | the window's middle |
 //! | `<x>,<y>` | that point |
-//! | `sweep` | a 7×5 grid across the middle half of the window, one point per frame, cycling |
-//! | `lock` | sweep until something is picked, then HOLD that object for the rest of the run |
+//! | `sweep` | a fixed 7×5 grid over the middle half of the window, one point per frame, cycling |
+//! | `lock` | sweep until something is picked, then hold that object for the rest of the run |
 //!
-//! `sweep` is the one that makes a rig run useful without a camera: standing a body in front of a
-//! known object and asking *"what is anywhere near the middle of the screen"* answers the question
-//! a fixed point can only answer if the aim was already right. It is a probe, not a camera search —
-//! the grid is fixed, bounded and the same every run.
+//! `lock` stands for a resting pointer: it holds the hit point in the object's own frame and
+//! re-projects it every frame, so it follows camera drift and the object's motion, and it never
+//! releases. A sweep re-enters its object every cycle, and a re-enter rebuilds the mouseover plate,
+//! so only `lock` can show a defect in a plate that is already up.
 //!
-//! **`lock` is what a resting pointer looks like, and `sweep` cannot stand in for it** (2255). A
-//! sweep re-enters the object every cycle, and a *re-enter* is precisely what rebuilds the
-//! mouseover plate — so a whole class of defect, the one where a plate that is already up never
-//! comes back after something else takes the tooltip, is invisible to a sweep by construction. It
-//! is also what a fixed `x,y` cannot do: the camera settles over the first seconds of a rig run and
-//! the object slides across the screen, so a hand-aimed point that hit at 30 s misses at 60 s.
-//! `lock` holds the hit POINT IN THE OBJECT'S OWN FRAME and re-projects it every frame, so the aim
-//! follows the object through camera drift and through the object's own motion. It never releases:
-//! that is the point — it stands for a pointer a person put down and left there.
-//!
-//! **Armed only when the window reports no cursor**, so an attended run is never overridden: a
-//! person's pointer always wins, and leaving the variable set costs a player nothing.
+//! Armed only while the window reports no cursor, so a person's pointer always wins.
 
 use bevy::prelude::*;
 use bevy::window::Window;
@@ -84,22 +62,19 @@ fn aim() -> Option<Aim> {
     })
 }
 
-/// Is the probe armed at all? (Cheap enough to ask per frame — one `OnceLock` read.)
+/// Whether the probe is armed: one `OnceLock` read, cheap per frame.
 pub(super) fn armed() -> bool {
     aim().is_some()
 }
 
-/// The point to pick from, given the window and a frame counter — `None` when the probe is not
-/// armed. The caller uses it **only** where the real cursor is absent.
+/// The point to pick from this frame; the caller uses it only where the real cursor is absent.
 pub(super) fn point(window: &Window, frame: u64) -> Option<Vec2> {
     let (w, h) = (window.width(), window.height());
     match aim()? {
         Aim::Centre => Some(Vec2::new(w / 2.0, h / 2.0)),
         Aim::At(x, y) => Some(Vec2::new(x as f32, y as f32)),
-        // The grid: 7 columns × 5 rows over the middle half, so the edges of the frame (chrome,
-        // sky, the player's own back) are never the answer. One cell per frame, cycling — at frame
-        // rate the whole grid is covered ~2× a second. `lock` searches with the same grid; once it
-        // holds an object [`LockedAim::point`] answers ahead of this and the grid stops mattering.
+        // 7 × 5 cells over the middle half, off the frame's edges (chrome, sky, the player's own
+        // back), one per frame. Once `lock` holds an object, `LockedAim::point` answers first.
         Aim::Sweep | Aim::Lock => {
             const COLS: u64 = 7;
             const ROWS: u64 = 5;
@@ -112,49 +87,36 @@ pub(super) fn point(window: &Window, frame: u64) -> Option<Vec2> {
     }
 }
 
-/// Does the aim HOLD its first pick? (`WOW_HOVER_PROBE=lock`.)
+/// Whether the aim holds its first pick (`lock`).
 pub(super) fn locks() -> bool {
     matches!(aim(), Some(Aim::Lock))
 }
 
-/// **This frame's aim**, published by the pick and read by everything else that needs to know
-/// where the probe is pointing: the UI mouse feed (so `PointerOverUi` rises and falls over a panel
-/// exactly as it does for a person) and the tooltip's cursor-seated arm.
-///
-/// It is a process-global rather than a resource for two reasons. The probe already is one — the
-/// env var behind [`aim`] — and its three readers sit in three different systems that are each at
-/// or near Bevy's parameter ceiling, so a resource would cost a bundle refactor apiece for a debug
-/// instrument with exactly one writer.
-///
-/// **One aim, published once per frame, is the correctness claim and not a convenience.** Before
-/// 2255 each reader called [`point`] again for itself, and the tooltip's call passed frame `0` —
-/// so on a `sweep` the plate was seated at grid cell 0 while the pick was aiming at cell N, and the
-/// two disagreed about where the pointer was on 34 frames out of every 35.
+/// This frame's aim, published once by the pick so the UI mouse feed and the tooltip's
+/// cursor-seated arm agree with it about where the pointer is. A process global, like the env var
+/// behind it: its readers are systems already at Bevy's parameter ceiling.
 static AIM_NOW: std::sync::Mutex<Option<Vec2>> = std::sync::Mutex::new(None);
 
-/// Publish this frame's aim. Called by the pick BEFORE its own gates: a frame that skipped the
-/// pick must still report a pointer, or the UI feed would take the pointer off the UI and unlatch
-/// the very gate that skipped it.
+/// Called by the pick before its own gates: a frame that skipped the pick still reports a pointer,
+/// or the UI feed would drop it and unlatch the gate that skipped it.
 pub(super) fn publish(point: Option<Vec2>) {
     *AIM_NOW.lock().unwrap_or_else(|e| e.into_inner()) = point;
 }
 
-/// This frame's aim, as published. `None` when the probe is not armed.
+/// This frame's published aim.
 pub(super) fn now() -> Option<Vec2> {
     *AIM_NOW.lock().unwrap_or_else(|e| e.into_inner())
 }
 
-/// `lock` mode's held target: the part the probe first picked, and the point it hit **in that
-/// part's own frame**. Re-projected every frame, so the aim follows the object rather than going
-/// stale the moment the camera settles or the object moves.
+/// `lock`'s held target: the part first picked, and the hit point in that part's own frame.
 #[derive(Default)]
 pub(super) struct LockedAim {
     held: Option<(Entity, Vec3)>,
 }
 
 impl LockedAim {
-    /// Where the held point is on screen now, or `None` while nothing is held (the grid still
-    /// searches) or while it has gone off-camera (the grid searches again).
+    /// The held point on screen now; `None` while nothing is held or it is off-camera, and the grid
+    /// searches.
     pub(super) fn point(
         &self,
         camera: &Camera,
@@ -168,13 +130,8 @@ impl LockedAim {
             .ok()
     }
 
-    /// Hold this hit — **once**. A lock that never releases is the whole point; re-locking onto
-    /// whatever happened to be picked later would make the aim wander exactly like the sweep it
-    /// exists to replace.
-    ///
-    /// Deliberately does **not** ask [`locks`] itself: the caller gates on the mode (a `sweep` that
-    /// held its first hit would stop sweeping), and keeping this half pure is what lets a test
-    /// drive it without an env var behind a `OnceLock`.
+    /// Holds the first hit and never another. The caller gates on the mode, which keeps this
+    /// testable without the env var.
     pub(super) fn hold(&mut self, part: Entity, gt: &GlobalTransform, hit_world: Vec3) {
         if self.held.is_some() {
             return;
@@ -185,9 +142,8 @@ impl LockedAim {
     }
 }
 
-/// One line per *change*, so a stationary probe does not flood the log: what the pick found at the
-/// aim point, and every term of the GameObject tooltip ladder the card shows a person (2248) —
-/// eligibility, the published mouseover, and the ask-once template the plate needs.
+/// One log line per change: what the pick found, and the GameObject tooltip ladder's terms
+/// (eligibility, the published mouseover, the ask-once template).
 #[derive(Default)]
 pub(super) struct ProbeReport {
     last: Option<String>,
@@ -207,8 +163,6 @@ impl ProbeReport {
 mod tests {
     use super::*;
 
-    /// The grid stays inside the middle half on both axes — the property that keeps a sweep off the
-    /// frame's edges, where the answer is always sky or the player's own back.
     #[test]
     fn the_sweep_grid_stays_in_the_middle_half() {
         let w = 800.0_f32;
@@ -223,9 +177,6 @@ mod tests {
         }
     }
 
-    /// **The lock holds its FIRST target and keeps it**, and holds it in the object's own frame —
-    /// the two properties that make a locked aim stand for a resting pointer rather than a slowly
-    /// wandering one.
     #[test]
     fn the_lock_holds_its_first_target_in_the_objects_own_frame() {
         let mut l = LockedAim::default();
@@ -247,7 +198,6 @@ mod tests {
         );
     }
 
-    /// Nothing held is nothing aimed — the search half keeps running until the first hit.
     #[test]
     fn an_unheld_lock_aims_at_nothing() {
         let l = LockedAim::default();
@@ -257,7 +207,6 @@ mod tests {
             .is_none());
     }
 
-    /// The published aim round-trips, and clearing it is how a frame says "no pointer here".
     #[test]
     fn the_published_aim_round_trips() {
         publish(Some(Vec2::new(3.0, 4.0)));
@@ -266,8 +215,6 @@ mod tests {
         assert_eq!(now(), None);
     }
 
-    /// A repeated line is said once — the property that makes the probe readable in a log rather
-    /// than 60 identical lines a second.
     #[test]
     fn the_report_only_speaks_on_change() {
         let mut r = ProbeReport::default();
diff --git a/crates/benilla-app/src/target/lock.rs b/crates/benilla-app/src/target/lock.rs
index b9322c50..70586e7c 100644
--- a/crates/benilla-app/src/target/lock.rs
+++ b/crates/benilla-app/src/target/lock.rs
@@ -1,35 +1,19 @@
-//! The GameObject **lock chain** — the client's resolver `0x5f83d0`, its per-slot **Action** gate
-//! (`0x5f81d0`), and the refusal-toast routing (`0x5f3427..`; decisions 0239 / 0545 / **0752**).
+//! The GameObject lock chain: the reference's resolver `0x5f83d0`, its per-slot Action gate
+//! (`0x5f81d0`) and the refusal-toast routing (`0x5f3427`). The reference asks the one resolver
+//! from `usable 0x5f3130` (the cursor's grey twin, and whether a right-click sends) and from the
+//! USE sender `0x5f33e0` (`CMSG_GAMEOBJ_USE`, an `OPEN_LOCK` cast or a toast), so the icon and the
+//! click agree by construction.
 //!
-//! **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), and from the **USE sender
-//! `0x5f33e0`** (which picks between `CMSG_GAMEOBJ_USE`, an `OPEN_LOCK` cast, and a client-local
-//! 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 judges each `Lock.dbc` slot on the object's state and its `GO_FLAG_LOCKED` bit
+//! ([`benilla_formats::LockSlot::available`]). It alone keeps a keyed door such as Scholomance's
+//! shut: its spare Quick Open slot (Action 0), which 6247 "Opening" satisfies for every character,
+//! applies only while the door is not flagged locked.
 //!
-//! ## The Action gate — the piece that was missing (0752)
-//!
-//! Before the resolver will *consider* a `Lock.dbc` slot it asks `0x5f81d0(GO, Action[i])`, which
-//! answers from the GameObject's own **state** and its `GO_FLAG_LOCKED` wire bit — see
-//! [`benilla_formats::LockSlot::available`]. Without it, the ladder is over-permissive in a way
-//! that looks arbitrary from the chair: nearly every keyed door in 5875 carries a spare
-//! `Quick Open` slot (`LockType 10`, `Skill 0`, **`Action 0`**), *every* character knows spell 6247
-//! "Opening", and Action 0 means "only when the object is NOT flagged locked" — so skipping the
-//! gate hands every padlocked door in the game to every player. The Searing Gorge gate (lock 84)
-//! was the one that refused because it is the one that carries no `Action 0` slot.
-//!
-//! ## Satisfaction is the SPELL's value — and the value's level term IS the player's skill
-//!
-//! `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" — 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
-//! satisfied a 300-skill vein (decision 1320 named the bug; this module now carries the fix).
+//! A slot is satisfied when the matched spell's `OPEN_LOCK` value
+//! ([`benilla_formats::SpellDisplay::open_lock_skill`]) reaches the requirement (`0x5f850f`),
+//! `Skill[i]` or `GAMEOBJECT_LEVEL × 5` when that is zero (`0x5f84be`). The value's level term is
+//! the player's skill in the spell's own line (`0x6e384d → 0x6e3130 → [vtbl+0xa8] = 0x5ea690`,
+//! [`spell_skill_value`]), not the character level.
 
 use std::collections::BTreeSet;
 
@@ -38,69 +22,60 @@ use bevy::prelude::*;
 
 use crate::net::ObjectStore;
 
-/// The lock chain's full data set as ONE [`SystemParam`] (decisions 0239 / 0545 / 0752): the
-/// ask-once GO-template cache, `Lock.dbc` + `LockType.dbc`, the spell catalog, and the ask-once
-/// 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.
+/// The lock chain's data as one [`SystemParam`]: the ask-once GameObject and item template caches
+/// (the item's for a key's name and ON_USE spell), `Lock.dbc`, `LockType.dbc` and the spell
+/// catalog. The `Option` members are absent without client data.
 #[derive(bevy::ecs::system::SystemParam)]
 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.
+    // `Res`: a miss's ask-once template request marks itself through `&self`.
     pub(crate) templates: Res<'w, crate::go_templates::GameObjectTemplates>,
     pub(crate) locks: Option<Res<'w, crate::go_templates::Locks>>,
     pub(crate) lock_types: Option<Res<'w, crate::go_templates::LockTypes>>,
     pub(crate) spells: Option<Res<'w, crate::ui_action::Spells>>,
-    /// The skill-line catalog — the opener-value level term's spell→line hop
-    /// ([`spell_skill_value`]). Absent without client data, which reads as skill 0 (fail-closed).
+    /// The spell to skill-line hop of [`spell_skill_value`]; absent, the skill reads 0.
     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.
+    /// The object index the key-item scan walks the bags through.
     pub(crate) objects: crate::net::Objects<'w, 's>,
 }
 
-/// The GameObject facts the Action gate and the requirement fallback read off the wire — gathered
-/// once by the caller so the resolver stays pure.
+/// The wire facts the Action gate and the requirement fallback read, gathered by the caller.
 #[derive(Clone, Copy, Debug)]
 pub(crate) struct GoFacts {
-    /// The client's stored `GAMEOBJECT_STATE` (`go+0x27c`) — [`crate::go_anim::go_state`].
+    /// The stored `GAMEOBJECT_STATE` (`go+0x27c`), from [`crate::go_anim::go_state`].
     pub(crate) state: u32,
     /// `GAMEOBJECT_FLAGS & GO_FLAG_LOCKED (0x2)`.
     pub(crate) flag_locked: bool,
-    /// `GAMEOBJECT_LEVEL` — the `Skill[i] == 0` requirement fallback's `× 5` base. vmangos leaves
-    /// it 0 on everything but transports, so on this server the fallback resolves to "no
-    /// requirement" and the server does the real gating; the client law is modelled regardless.
+    /// `GAMEOBJECT_LEVEL`, the zero-`Skill` fallback's base. vmangos sets it only on transports
+    /// (`GameObject.cpp:247`), so there the fallback asks nothing and the server gates.
     pub(crate) level: u32,
 }
 
-/// What the resolver says about a GameObject's lock — the reference's return plus its spell-id
-/// out-param, made explicit.
+/// The resolver's verdict: the reference's return and its spell-id out-param in one.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum LockOutcome {
-    /// No `Lock.dbc` row, or every slot empty — `0x5f8180` null / `[ebp-1]` never set. The object
-    /// opens by `CMSG_GAMEOBJ_USE`.
+    /// No `Lock.dbc` row (`0x5f8180` null) or every slot empty: opens by `CMSG_GAMEOBJ_USE`.
     Unlocked,
-    /// A skill slot the player satisfies with a known `OPEN_LOCK` spell — cast it at the GO.
+    /// A skill slot satisfied by this known `OPEN_LOCK` spell, cast at the object.
     OpenBySpell(u32),
-    /// A key slot whose item the player carries; the value is the **key's entry**. The reference
-    /// resolves the item's ON_USE spell here (`0x5d8c80`) and casts that.
+    /// A key slot whose item we carry, by the key's entry; the reference casts the item's ON_USE
+    /// spell (`0x5d8c80`).
     OpenByKey(u32),
-    /// A lock is present and no slot is satisfied — the client-local refusal, **no packet**.
+    /// A lock no slot satisfies: the client-local refusal, no packet.
     Unmet,
 }
 
 impl LockOutcome {
-    /// The `usable` half: `0x5f3130`'s lock arm returns *not usable* only for [`Self::Unmet`], and
-    /// **only when `GO_FLAG_LOCKED` is set** (`0x5f32a6`: `shr 1; test al,1; je`). With the flag
-    /// clear the arm is skipped entirely — which is exactly why a herb node you cannot gather still
-    /// shows the lit `GatherHerbs` cursor and only toasts on the click.
+    /// `usable 0x5f3130`'s lock arm: not usable only for [`Self::Unmet`] with `GO_FLAG_LOCKED` set
+    /// (`0x5f32a6`). With the flag clear the arm is skipped, so a herb node you cannot gather keeps
+    /// the lit `GatherHerbs` cursor and toasts on the click.
     pub(super) fn blocks_usable(self, flag_locked: bool) -> bool {
         flag_locked && self == LockOutcome::Unmet
     }
 }
 
-/// Read the Action gate's inputs off a hovered GameObject — its store plus the stored state the
-/// caller already resolved ([`crate::go_anim::go_state`]). `None` (nothing hovered / no store yet)
-/// answers with the wire defaults, which make every gated slot inapplicable rather than free.
+/// The Action gate's inputs off a hovered GameObject's store and its resolved state. `None` gives
+/// the wire defaults, under which every gated slot is inapplicable rather than free.
 pub(crate) fn go_facts(go: Option<(&ObjectStore, u32)>) -> GoFacts {
     match go {
         Some((store, state)) => GoFacts {
@@ -116,39 +91,27 @@ 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 (`0x5f32a6`).
+/// `GO_FLAG_LOCKED` (vmangos `GameObjectDefines.h:75`): selects the Action 1 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).
+/// The reference's lock resolver `0x5f83d0`. Walks the eight `Lock.dbc` slots in order:
+/// - SKILL (2): past the Action gate, scan the known spells for an `OPEN_LOCK` effect whose
+///   `EffectMiscValue` is the slot's `Index`; a match sets `matched_spell` before the value test
+///   (`0x5f84f8`), then its effect value is compared to the requirement (`0x5f850f`).
+/// - KEY (1): past the Action gate, look for the key item in our bags and keyring.
+/// - NONE (0): skipped.
 ///
-/// Walks the 8 `Lock.dbc` slots **in order**, dispatching each by `Type`:
-/// - **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 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.
+/// A SKILL or KEY slot makes the lock real even when the Action gate rejects it (`[ebp-1] = 1`
+/// before `0x5f81d0`), so a door whose only opener is gated out refuses instead of falling through
+/// to `CMSG_GAMEOBJ_USE`. Whether `matched_spell` is set routes the toast (`0xdf` or `0xe0`).
 ///
-/// Any SKILL/KEY slot marks the lock **real** even when its Action gate rejects it (the binary
-/// writes `[ebp-1] = 1` *before* calling `0x5f81d0`), so a door whose only opener is gated out
-/// refuses rather than falling through to `CMSG_GAMEOBJ_USE`.
-///
-/// `matched_spell` is the out-param the toast routing needs; it is written for a LockType match
-/// even when the value test then fails.
-///
-/// **The scan order is part of the answer, not an implementation detail** (decision 1312). The
-/// reference walks its known-spell **array** in index order and *returns on the first sufficient
-/// match*, so when two known spells both match the LockType and both clear the requirement, the
-/// order decides which one is cast — and that spell's name is what the cast bar reads. This was
-/// documented here for a long time as a harmless difference ("it only decides which spell lands in
-/// `matched_spell`, never the outcome"), which is false: every character knows both 6478 "Opening"
-/// and 22810 **"Opening - No Text"** — both `SPELL_EFFECT_OPEN_LOCK` on `LockType 13` (Open
-/// Kneeling), both trivially sufficient against the `Skill == 0` slots the ground containers carry
-/// — so iterating a `HashSet` put Blizzard's placeholder name on the cast bar at the hash's whim
-/// (B247). `known` is a [`BTreeSet`] for exactly that reason: ascending spell id is the reference
-/// array's own order after login, the server building `SMSG_INITIAL_SPELLS` out of a `std::map`.
+/// The first sufficient match is cast, so the scan order picks between two sufficient openers,
+/// such as 6478 "Opening" and 22810 "Opening - No Text" on LockType 13, which every character
+/// knows. `known` is a [`BTreeSet`], so ours scans in ascending spell id; the reference scans its
+/// opener list (`0xb700b0`) in the order `SMSG_INITIAL_SPELLS` listed them, later learns at the
+/// tail, and vmangos sends that packet in `std::unordered_map` order (`Player.cpp:3458`,
+/// `Player.h:113`).
 pub(crate) fn resolve_lock(
     slots: &[LockSlot],
     known: &BTreeSet<u32>,
@@ -175,8 +138,7 @@ pub(crate) fn resolve_lock(
                     if spell.open_lock_type() != Some(slot.index) {
                         continue;
                     }
-                    // `0x5f84f8` — the out-param is written on the LockType match, before the
-                    // value test.
+                    // `0x5f84f8`: set on the LockType match, before the value test.
                     matched_spell.get_or_insert(id);
                     let skill = spell_skill_value(me, skill_lines, id);
                     let provides = spell.open_lock_skill(skill).unwrap_or(0);
@@ -204,13 +166,9 @@ pub(crate) fn resolve_lock(
     }
 }
 
-/// 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
-/// SLA record, or a line the player does not carry all answer **0** — the opener then provides
-/// only its flat terms.
+/// The player's skill in `spell_id`'s own line, the opener value's level term: `0x5ea690` hops
+/// spell to SkillLineAbility line (`0x6de040`), then `0x5ea520` reads that line's
+/// `PLAYER_SKILL_INFO` slot. Every missing input reads 0, like the reference's null paths.
 fn spell_skill_value(
     me: Option<&ObjectStore>,
     skill_lines: Option<&benilla_formats::SkillLineCatalog>,
@@ -227,9 +185,8 @@ fn spell_skill_value(
     )
 }
 
-/// The `0x5ea520` sum on one line's slot: `value + temp_bonus + perm_bonus`, floored at 0 (the
-/// bonuses are signed — a curse can push the sum below the base). First matching slot wins;
-/// a line absent from the block reads 0.
+/// `0x5ea520`'s sum on the line's first slot: `value + temp_bonus + perm_bonus`
+/// (`0x5ea56d`..`0x5ea580`), floored at 0 since the bonuses are signed.
 fn line_skill_value(
     slots: impl Iterator<Item = benilla_protocol::messages::PlayerSkillSlot>,
     line: u32,
@@ -243,35 +200,14 @@ fn line_skill_value(
     0
 }
 
-/// **`0x5f8260`** — the *targeting cursor's* lock question, and this chain's **third** consumer
-/// (decision 0949). Reached from the object dispatcher `0x4828d0`'s targeting step
-/// (`0x482910 → 0x6e6460`, whose GameObject arm calls it at `6e670f` with the GO, the cast-item
-/// guid `0xceac48` and the pending spell id `[0xceac58]`).
+/// `0x5f8260`, the targeting cursor's question for the pending spell (`[0xceac58]`) over a
+/// GameObject, from the object dispatcher `0x4828d0` through `0x6e6460`. Unlike [`resolve_lock`]
+/// it matches the spell's own `OPEN_LOCK` effects against each slot's `Index` and compares no skill
+/// values, so the cursor lights on a chest the skill cannot open and the server refuses the click;
+/// no `Lock.dbc` row (`0x5f8180` null) is false, so the cursor greys over a mailbox.
 ///
-/// Where [`resolve_lock`] (`0x5f83d0`) asks *"can I open this with anything I have?"*, this asks
-/// the narrower *"does **this pending spell** open **this lock**?"*. Three differences, all in the
-/// bytes:
-///
-/// - It walks the **spell's** three effect slots, not the player's known spells — `5f82c0`'s outer
-///   loop over `SpellRec+0xf4/f8/fc` with `cmp …, 0x21` (`SPELL_EFFECT_OPEN_LOCK`), matching
-///   `EffectMiscValue[k]` (`[ebx+0xb4]`) against the slot's `Index[i]`.
-/// - **It never compares skill values.** `0x5f83d0`'s satisfaction test (`0x5f850f`,
-///   [`required_skill`]) has no counterpart here. A matched `LockType` that passes the Action gate
-///   is the whole predicate — so the cursor lights on a chest your skill cannot yet open, the
-///   click sends, and the *server* refuses. That is the same "no gate on the object leg" 0939
-///   found at `BindTarget`, and it is why this is not simply [`resolve_lock`] reused.
-/// - A GameObject with **no `Lock.dbc` row is `false`**, not "open" (`0x5f8180` null → `5f8273`
-///   returns 0) — the opposite of [`resolve_lock`]'s lockless arm, and correct: you cannot Pick
-///   Lock a mailbox, and the cursor greys over one.
-///
-/// The Action gate ([`LockSlot::available`]) is shared with both siblings — same `0x5f81d0`, so
-/// the cursor, the tooltip and the click cannot disagree about whether a slot applies.
-///
-/// **Not transcribed:** the `SPELL_EFFECT_OPEN_LOCK_ITEM` (59) arm at `5f831c`, which matches the
-/// **cast item's** entry against a `LOCK_KEY_ITEM` slot (`5f8360`: `Type[i] == 1`, `5f836c`: the
-/// item's entry `== Index[i]`, then the same gate). It needs a per-effect id the catalog does not
-/// carry yet, and it only fires for a key's own ON_USE spell armed at a GameObject — a seam 0939
-/// built but no 5875 key is known to use. Named residual, decision 0949.
+/// Not built: the `SPELL_EFFECT_OPEN_LOCK_ITEM` (59) arm, which matches the cast item's entry
+/// against a KEY slot; the catalog lacks its per-effect id.
 pub(crate) fn spell_opens_lock(
     slots: &[LockSlot],
     spell: &benilla_formats::SpellDisplay,
@@ -287,10 +223,8 @@ pub(crate) fn spell_opens_lock(
     })
 }
 
-/// The slot's required skill: `Skill[i]`, or **`GAMEOBJECT_LEVEL × 5`** when it is zero
-/// (`0x5f84be..0x5f84ca` — the resolver; `0x5f3490..0x5f349f` recomputes the same value for the
-/// `0xe0` toast's `%d`). A zero `Skill` is *not* "no requirement": every gathering node in the game
-/// stores 0 there and leans on the object's level.
+/// The slot's requirement: `Skill[i]`, or `GAMEOBJECT_LEVEL × 5` when that is zero
+/// (`0x5f84be`..`0x5f84ca`; `0x5f3490`..`0x5f349f` recomputes it for the `0xe0` toast's `%d`).
 pub(crate) fn required_skill(slot: &LockSlot, go_level: u32) -> i32 {
     if slot.skill != 0 {
         slot.skill as i32
@@ -299,12 +233,8 @@ pub(crate) fn required_skill(slot: &LockSlot, go_level: u32) -> i32 {
     }
 }
 
-/// Whether we carry item `entry` — the key-slot scan's inventory walk. This IS the reference's own
-/// walker (`0x622270` → `0x622420`, mode 0 ⇒ `0x47` = equipment | bags | backpack | keyring), which
-/// benilla already transcribes once as [`crate::ui_items::find_item`]; it used to be a second,
-/// hand-rolled walk here that missed the equipment slots and read 32 keyring slots where the wire
-/// has 16. One walker, one answer — and the caller needs the POSITION it returns anyway, to address
-/// `CMSG_USE_ITEM` (decision 0769).
+/// Whether we carry item `entry`, by the reference's own walker, [`crate::ui_items::find_item`]
+/// (`0x622270 → 0x622420`, mode 0: equipment, bags, backpack and keyring).
 fn holds_item(
     store: &benilla_protocol::messages::ObjectFields,
     objects: &crate::net::Objects,
@@ -333,13 +263,11 @@ mod tests {
         }
     }
 
-    /// **`0x5f8260` is not `0x5f83d0`** (decision 0949). The cursor's question differs from the
-    /// right-click resolver's in three ways that all show on screen, and getting any of them
-    /// wrong greys the wrong chest.
+    /// `0x5f8260` against `0x5f83d0`: the cursor's question differs from the resolver's.
     #[test]
     fn the_cursor_lock_predicate_ignores_skill_and_refuses_the_lockless() {
         use benilla_formats::SpellDisplay;
-        // Pick Lock: LockType 1 (Lockpicking), providing 300 at level 60.
+        // Pick Lock: LockType 1, Lockpicking.
         let pick_lock = SpellDisplay {
             open_lock: Some(benilla_formats::OpenLock {
                 effect: 0,
@@ -360,20 +288,18 @@ mod tests {
             "the right LockType through an applicable slot lights the cursor"
         );
 
-        // **The skill value is never read** — `0x5f850f` has no counterpart in `0x5f8260`. A slot
-        // demanding far more than Pick Lock provides STILL lights: the click sends and the server
-        // refuses. This is the single biggest difference from `resolve_lock`.
+        // No skill compare: a slot far beyond Pick Lock still lights, and the server refuses.
         let brutal = [skill_slot(1, 9999, 1), LockSlot::default()];
         assert!(
             spell_opens_lock(&brutal, &pick_lock, unlocked),
             "0x5f8260 compares no skill values — an out-of-reach lock still lights"
         );
 
-        // Wrong LockType (3 = Mining) — a lockpick greys over an ore vein.
+        // Wrong LockType (3, Mining): a lockpick greys over an ore vein.
         let mining = [skill_slot(3, 0, 1), LockSlot::default()];
         assert!(!spell_opens_lock(&mining, &pick_lock, unlocked));
 
-        // The shared Action gate still applies: Action 0 means "only when NOT flagged locked".
+        // The shared Action gate: Action 0 applies only while not flagged locked.
         assert!(!spell_opens_lock(
             &[skill_slot(1, 0, 0)],
             &pick_lock,
@@ -388,8 +314,7 @@ mod tests {
             }
         ));
 
-        // **No lock row at all is FALSE, not "open"** (`0x5f8180` null → `5f8273`) — the exact
-        // opposite of `resolve_lock`'s lockless arm. You cannot Pick Lock a mailbox.
+        // No lock row is false, unlike `resolve_lock`: no Pick Lock on a mailbox.
         assert!(!spell_opens_lock(&[], &pick_lock, unlocked));
         assert!(!spell_opens_lock(
             &[LockSlot::default()],
@@ -404,7 +329,7 @@ mod tests {
             unlocked
         ));
 
-        // A KEY slot is not the SKILL arm's business (the effect-59 arm is a named residual).
+        // A KEY slot belongs to the unbuilt effect-59 arm.
         let key = [LockSlot {
             key_type: LOCK_KEY_ITEM,
             index: 1,
@@ -414,20 +339,16 @@ mod tests {
         assert!(!spell_opens_lock(&key, &pick_lock, unlocked));
     }
 
-    /// The requirement fallback (`0x5f84be`): a zero `Skill[i]` means GO-level × 5, not "free".
     #[test]
     fn zero_skill_falls_back_to_go_level_times_five() {
         assert_eq!(required_skill(&skill_slot(3, 0, 0), 0), 0);
         assert_eq!(required_skill(&skill_slot(3, 0, 0), 20), 100);
-        // A nonzero Skill wins outright — the level is never consulted.
+        // A nonzero Skill wins; the level is not read.
         assert_eq!(required_skill(&skill_slot(1, 280, 1), 60), 280);
     }
 
-    /// **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)
-    /// and the bonus halves of the `0x5ea520` sum.
+    /// A level-60 with 1 Mining is refused a 250-skill vein; missing data reads skill 0, and the
+    /// `0x5ea520` sum counts both bonus halves.
     #[test]
     fn the_lock_value_tracks_the_players_skill_not_their_level() {
         use benilla_formats::{OpenLock, SkillLineCatalog, SpellCatalog, SpellDisplay};
@@ -451,8 +372,6 @@ mod tests {
         // Spell → line: Mining is SkillLine 186.
         let lines = SkillLineCatalog::from_spell_lines([(2575, 186)]);
         let known = BTreeSet::from([2575]);
-        // 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).
@@ -463,8 +382,8 @@ mod tests {
             flag_locked: false,
             level: 0,
         };
-        // A level-60 store (UNIT_FIELD_LEVEL = 34) whose skill block holds Mining at `value`,
-        // with the bonus dwords in the third word ([`PlayerSkillSlot`]'s verified packing).
+        // A level-60 store (`UNIT_FIELD_LEVEL` 34) with Mining at `value` and the bonuses in the
+        // third word, as `PlayerSkillSlot` packs them.
         let store_with_mining = |value: u32, bonus_word: u32| {
             ObjectStore(ObjectFields::from_pairs(&[
                 (34, 60),
@@ -486,7 +405,7 @@ mod tests {
             )
         };
 
-        // 300 Mining opens; 1 Mining — the level-60 the old reading waved through — is refused.
+        // 300 Mining opens; 1 Mining is refused.
         let skilled = store_with_mining(300, 0);
         assert_eq!(
             resolve(Some(&skilled), Some(&lines)),
@@ -503,23 +422,18 @@ mod tests {
             LockOutcome::OpenBySpell(2575)
         );
 
-        // Fail-closed legs: no skill-line catalog, or no store, reads skill 0 — refused, never
-        // a fall-back to the character level.
+        // No skill-line catalog, or no store, reads skill 0: refused.
         assert_eq!(resolve(Some(&skilled), None), LockOutcome::Unmet);
         assert_eq!(resolve(None, Some(&lines)), LockOutcome::Unmet);
     }
 
-    /// A door whose only opener is gated out by its Action must refuse, **not** fall through to
-    /// `CMSG_GAMEOBJ_USE`: the binary marks the lock real (`[ebp-1] = 1`) *before* asking
-    /// `0x5f81d0`. This is the difference between "locked door refuses" and "locked door opens".
+    /// The lock is marked real (`[ebp-1] = 1`) before `0x5f81d0` is asked.
     #[test]
     fn a_gated_out_slot_still_makes_the_lock_real() {
         let slots = [
-            skill_slot(10, 0, 0), // Quick Open — Action 0, gated out on a flagged-locked door
+            skill_slot(10, 0, 0), // Quick Open: Action 0, gated out on a flagged-locked door
             LockSlot::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;
@@ -542,24 +456,19 @@ mod tests {
             out.blocks_usable(true),
             "a flagged-locked unmet lock grays the cursor"
         );
-        // …and with the flag clear the SAME lock is not a `usable` blocker (the arm is skipped) —
-        // the herb-node case: lit cursor, toast on click.
+        // With the flag clear it blocks nothing: lit cursor, toast on click.
         assert!(!out.blocks_usable(false));
     }
 
-    /// The reported bug, end to end, on the **real** shipped `Lock.dbc` / `Spell.dbc` values
-    /// (decision 0752). `benilla-formats`' own `real_lock_catalog_reads_the_action_column` and
-    /// `real_spell_catalog_computes_the_lock_skill_an_opener_provides` pin these numbers against
-    /// the files, so this stays a pure unit test while still describing real data.
-    ///
-    /// Before the Action gate, every one of these doors opened for every character: "Opening"
-    /// (6247) satisfied their spare `Quick Open` slot with a flat 100 ≥ 0.
+    /// Shipped `Lock.dbc` and `Spell.dbc` values, which `benilla-formats`'
+    /// `real_lock_catalog_reads_the_action_column` and
+    /// `real_spell_catalog_computes_the_lock_skill_an_opener_provides` pin against the files.
     #[test]
     fn a_keyed_door_refuses_the_universally_known_opening_spell() {
         use benilla_formats::{OpenLock, SpellCatalog, SpellDisplay};
 
-        // Scholomance Door, lockId 1159 — key 13704 / Pick Lock 280 / Quick Open / Quick Close /
-        // Blasting 300; the template ships GO_FLAG_LOCKED.
+        // Scholomance Door, lock 1159: key 13704, Pick Lock 280, Quick Open, Quick Close, Blasting
+        // 300; the template ships `GO_FLAG_LOCKED`.
         let mut scholomance = [LockSlot::default(); 8];
         scholomance[0] = LockSlot {
             key_type: LOCK_KEY_ITEM,
@@ -572,8 +481,8 @@ mod tests {
         scholomance[3] = skill_slot(11, 0, 2);
         scholomance[4] = skill_slot(16, 300, 1);
 
-        // Two openers with their real value inputs: the "Opening" every character is created
-        // with, and Pick Lock (whose value tracks 5×level).
+        // Two openers with their real value inputs: 6247 "Opening", which every character is
+        // created with, and Pick Lock, whose value tracks the Lockpicking skill.
         let opening = SpellDisplay {
             open_lock: Some(OpenLock {
                 lock_type: 10,
@@ -600,8 +509,6 @@ mod tests {
             ),
             ..crate::ui_action::Spells::empty_for_tests()
         };
-        // 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 {
@@ -610,7 +517,7 @@ mod tests {
             level: 0,
         };
 
-        // A character who knows only "Opening" — i.e. everybody — is refused.
+        // A character who knows only "Opening" is refused.
         let mut matched = None;
         assert_eq!(
             resolve_lock(
@@ -630,8 +537,8 @@ mod tests {
             "a gated-out slot never even reaches the known-spell scan"
         );
 
-        // Clear the flag and the SAME door opens to the SAME spell — proof that the gate is what
-        // refuses, not the value test. (No shipped door does this; it isolates the mechanism.)
+        // With the flag clear the same door opens to the same spell: the gate refuses, not the
+        // value test.
         assert_eq!(
             resolve_lock(
                 &scholomance,
@@ -649,11 +556,8 @@ mod tests {
             LockOutcome::OpenBySpell(6247),
         );
 
-        // 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 (`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.)
+        // The flag selects Pick Lock's Action 1 slot, but with no store the skill reads 0, its
+        // flat 5 < 280 refuses, and the out-param is still written (`0x5f84f8`).
         let mut matched = None;
         assert_eq!(
             resolve_lock(
@@ -674,8 +578,7 @@ mod tests {
             "a LockType match writes the out-param before the value test"
         );
 
-        // The Searing Gorge gate (lockId 84) — the reporter's counter-example. No Action-0 slot at
-        // all, which is why it refused even before the gate existed; it must still refuse.
+        // The Searing Gorge gate, lock 84, has no Action 0 slot.
         let mut searing_gorge = [LockSlot::default(); 8];
         searing_gorge[0] = LockSlot {
             key_type: LOCK_KEY_ITEM,
@@ -698,8 +601,8 @@ mod tests {
             LockOutcome::Unmet,
         );
 
-        // And the gate must not touch what already worked: a Copper Vein (lockId 38 — one Mining
-        // slot, Skill 0, Action 0) on an unflagged, READY object still opens for a miner.
+        // A Copper Vein, lock 38 (one Mining slot, Skill 0, Action 0), unflagged and READY, opens
+        // for a miner.
         let mining = SpellDisplay {
             open_lock: Some(OpenLock {
                 lock_type: 3,
@@ -735,17 +638,10 @@ mod tests {
         );
     }
 
-    /// **B247** (decision 1312): two known openers on one LockType, both sufficient — the LOWEST
-    /// spell id wins, deterministically, because that is the reference array's order and the scan
-    /// returns on its first sufficient match.
-    ///
-    /// The real values: lock 43 (Hyacinth Mushroom and every other ground container) carries one
-    /// SKILL slot, `LockType 13` "Open Kneeling", `Skill 0`, `Action 0`. Three shipped spells carry
-    /// `SPELL_EFFECT_OPEN_LOCK` on type 13 — 6478 "Opening", 17667 "Light On Fire", and 22810
-    /// **"Opening - No Text"** — and `playercreateinfo_spell` grants 6478 *and* 22810 to every
-    /// race/class. Whichever this scan returns is the spell the click casts, so its Spell.dbc name
-    /// is what the cast bar prints: with a `HashSet` here the bar read Blizzard's placeholder about
-    /// half the time.
+    /// Two sufficient openers on one LockType: the lower spell id wins, `known` being ordered.
+    /// Lock 43 (a Hyacinth Mushroom's) has one SKILL slot, LockType 13 "Open Kneeling", Skill 0,
+    /// Action 0, and `playercreateinfo_spell` grants both 6478 "Opening" and 22810 "Opening - No
+    /// Text" to every race and class.
     #[test]
     fn two_sufficient_openers_pick_the_lower_spell_id() {
         use benilla_formats::{OpenLock, SpellCatalog, SpellDisplay};
@@ -753,9 +649,8 @@ mod tests {
         let mut mushroom = [LockSlot::default(); 8];
         mushroom[0] = skill_slot(13, 0, 0);
 
-        // Both "Opening" spells: OPEN_LOCK on type 13, flat value 100 (base 99 + dice 1), which
-        // clears the slot's `Skill 0`. Identical in every input the resolver reads — the pick is
-        // decided by visit order and nothing else, which is the whole point.
+        // Both "Opening" spells: OPEN_LOCK on type 13, flat value 100 (base 99 + dice 1), identical
+        // in every input the resolver reads, so only the visit order decides.
         let kneeling_opener = || SpellDisplay {
             open_lock: Some(OpenLock {
                 lock_type: 13,
@@ -773,8 +668,6 @@ mod tests {
             ),
             ..crate::ui_action::Spells::empty_for_tests()
         };
-        // 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 {
@@ -800,7 +693,7 @@ mod tests {
         );
         assert_eq!(matched, Some(6478), "the toast's out-param agrees");
 
-        // Insertion order cannot change it — the set is ordered, so the scan is too.
+        // Insertion order cannot change it: the set is ordered.
         let mut matched = None;
         assert_eq!(
             resolve_lock(
@@ -817,12 +710,9 @@ mod tests {
         );
     }
 
-    /// An all-empty row is not a lock at all — `CMSG_GAMEOBJ_USE`.
     #[test]
     fn an_empty_row_is_unlocked() {
         let slots = [LockSlot::default(); 8];
-        // 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;
diff --git a/crates/benilla-app/src/target/mod.rs b/crates/benilla-app/src/target/mod.rs
index bd8e6bcb..778b9097 100644
--- a/crates/benilla-app/src/target/mod.rs
+++ b/crates/benilla-app/src/target/mod.rs
@@ -1,49 +1,7 @@
-//! Targeting — click a unit to select it, and mark it with a ground selection ring.
-//!
-//! The first real player-facing consumer of the [`benilla_world::interact`] picking foundation (whose header
-//! long anticipated "mouseover-targeting"). This module owns the *selection state and input*; the
-//! ring itself — the projected decal, its colour selector, and the reaction decode — lives in
-//! [`ring`]. The pieces here:
-//! - **Selection state** ([`Selection`]) — the entity + guid of our current target, tracked *locally*
-//!   and set the instant we click (the faithful client behaviour: the ring appears immediately, no
-//!   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 (`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 =
-//!   the visible creature's silhouette at its pose. (The M2 bounding-triangle block is *not* the
-//!   unit pick volume — that's the static-doodad path; an earlier gloss saying otherwise was
-//!   refuted by asset data.) Hull-less/model-less units (cube fallbacks) keep the old render-mesh
-//!   AABB test. Stored in [`Hovered`] — the state a mouseover highlight will read.
-//! - **Click to select** ([`select_on_click`]) — a [`WorldClick`] (the clean left-click the player
-//!   controller emits; a left *drag* orbits the camera instead) selects whatever is [`Hovered`].
-//!   Clicking empty ground / a non-unit, or pressing **Esc**, clears the target; the target's death
-//!   clears it too (in [`ring::update_ring`], where death is already read).
-//!
-//! **A unit the classifier refuses is not the mouseover at all** ([`hover::refuse_unselectable`]).
-//! `IsSelectable` (`UNIT_FIELD_FLAGS` bit 25 clear, or `UNIT_FIELD_CREATEDBY` == us) is tested by
-//! the hover grader `0x4828d0` at `0x482982`, and a false answer jumps straight to
-//! `0x482090(0,0)` + `ResetCursor 0x523d30` — the mouseover globals are cleared and the type
-//! 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 (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**
-//! (`crate::vplates`, drawn later off [`Hovered`] + [`Selection`]). The plate rect is itself part
-//! of the pick: hovering a plate makes its unit the mouseover *before* any world ray-test
-//! ([`hover::update_hover`] reads `crate::vplates::PlateHover` first — the plate is real
-//! mouse-enabled UI since 2148/2159, so it takes the pointer and publishes the unit itself, the
-//! reference's own OnEnter arrangement), so plates brighten the model and take clicks like the
-//! body does ([`click::select_on_plate_click`]).
-//! The real pick's **world-occlusion clamp** is modelled ([`PickOcclusion`]): the reference's scene
-//! trace runs `CWorld::Intersect` first and the object pick only wins nearer than the world hit —
-//! a unit or GameObject behind a wall is not hoverable. Not yet modelled: the header-sphere
-//! fallback for a sequence with unauthored bounds (we pass the broad phase through instead —
-//! strictly more permissive, never less).
+//! Targeting: the selection, the mouseover pick, click-to-select and the ground selection ring
+//! ([`ring`]). The pick is the reference's (`0x481190` → `0x7089c0`, [`hover::update_hover`]): a
+//! nameplate under the pointer first, then the posed-mesh pick, clamped by the world trace; a click
+//! acts on what the press was over ([`PressPick`]).
 
 use bevy::prelude::*;
 
@@ -57,54 +15,33 @@ use benilla_world::interact::{WorldClick, WorldRightClick};
 use benilla_world::schedule::WorldStage;
 
 mod by_name;
-// `pub(crate)` for the chest live probe alone (decision 1471): it resolves a GameObject's
-// right-click action through the very same [`click::resolve_go_action`] the mouse does, rather
-// than re-deciding lockless-vs-opener itself — an instrument that guesses the packet is testing
-// its own guess (`probe_book`'s pattern: drive the click's own route, never a parallel one).
+// `pub(crate)` for the chest live probe, which drives the mouse's own `click::resolve_go_action`.
 pub(crate) mod click;
-// `pub(crate)` for the hover inspector's interact-gate line (`interact/inspect.rs`): the overlay
-// states the very predicate the cursor runs ([`cursor_mode::go_highlightable`]) rather than a
-// re-derivation of it, so the readout can never drift from the behaviour it is reporting on.
+// `pub(crate)` for the hover inspector, which runs the cursor's `cursor_mode::go_highlightable`.
 pub(crate) mod cursor_mode;
 mod flash;
 mod highlight;
 pub(crate) mod hover;
-/// The headless hover probe (2250) — see its header.
 mod hover_probe;
 
-/// The probe's aim for a window with no OS cursor — for the tooltip's cursor-seated arm and the
-/// UI mouse feed (2250; 2255 made it THIS frame's aim as the pick published it, rather than a
-/// second, independently recomputed one that disagreed with the pick on 34 sweep frames in 35).
+/// The hover probe's aim for a cursorless window, as this frame's pick published it.
 pub(crate) fn hover_probe_point() -> Option<bevy::math::Vec2> {
     hover_probe::now()
 }
 
-/// Is the headless hover probe armed? (Gates its own log lines outside this module.)
+/// Whether the headless hover probe is armed.
 pub(crate) fn hover_probe_armed() -> bool {
     hover_probe::armed()
 }
 pub(crate) mod lock;
 mod relations;
 mod reticle;
-// `pub(crate)` for the same reason as `cursor_mode`: the faction catalog is one of
-// [`cursor_mode::go_highlightable`]'s three inputs, so the inspector needs it to run the real gate.
+// `pub(crate)` for the hover inspector too: its faction catalog feeds `go_highlightable`.
 pub(crate) mod ring;
 mod scan;
 
-/// The standing pair — `Faction.dbc` and our own reputation table — as ONE [`SystemParam`].
-///
-/// Every consumer of either takes both: [`ring_reaction`], [`can_attack`], [`can_assist`],
-/// [`can_interact`] and `ui_unit::faction_group` are all `(factions, reputations)` functions, and
-/// no system has ever wanted one without the other. Bundling them says that, and buys back a slot
-/// against Bevy's 16-param tuple limit — which `ui_tooltip`'s hover system hit the moment it
-/// legitimately needed one more resource.
-///
-/// `factions` is `Option` for the reason its flat form always was: it belongs to the asset layer,
-/// and a UI-only harness runs with no client data rather than panicking on system validation.
-///
-/// `ui_unit::feed_units` is the other system that takes the pair (22 call sites). It has not
-/// adopted this yet — its own crowding was solved by [`crate::ui_unit::UnitStores`] — and it
-/// should, next time that file is opened for anything.
+/// `Faction.dbc` and our reputation table as one [`SystemParam`], since every reaction function
+/// takes both; `factions` is `Option` so a UI-only harness runs without client data.
 #[derive(bevy::ecs::system::SystemParam)]
 pub(crate) struct ReactionInputs<'w> {
     pub(crate) factions: Option<Res<'w, Factions>>,
@@ -114,114 +51,75 @@ pub(crate) struct ReactionInputs<'w> {
 pub(crate) use cursor_mode::{
     corpse_mouseover_eligible, CursorKind, WorldCursor, GO_TYPE_GENERIC, SERVICE_RANGE_SQ,
 };
-/// `GO_FLAG_LOCKED` — the wire bit the lock chain and the GO tooltip's "Locked" line both read.
+/// `GO_FLAG_LOCKED`, the bit the lock chain and the GameObject tooltip's "Locked" line read.
 pub(crate) use lock::GO_FLAG_LOCKED;
-// This frame's combat-flash verdict — read by the ring's material pick (in `ring`) and by the
-// nameplate colour gate (`crate::nameplates`), the flash's only two consumers (byte-verified).
+// This frame's combat-flash verdict, for the ring's material and the nameplate colour gate.
 pub(crate) use flash::CombatFlash;
-// The action layer's "attack pressed with no target" request — the nearest-enemy auto-acquire
-// (`scan`) answers it with the same core TAB uses. `attack_order_target` + `TargetScan` are that
-// same core called *synchronously*, by the pet bar's ATTACK arm: the pet's order has to leave in
-// the frame it was pressed carrying the acquired guid, so it cannot go round through a request.
+// The attack-with-no-target request, and the same nearest-enemy core called synchronously for the
+// pet bar's Attack, whose order must leave in the frame it was pressed.
 pub(crate) use relations::{can_assist, can_attack, can_interact};
 pub(crate) use scan::{attack_order_target, AttackNearestRequest, TargetScan};
-// The chat layer's by-name selection asks (`/target`, `/assist` — decision 0886), answered by the
-// shared resolver the reference parameterises per caller.
+// The chat layer's by-name asks (`/target`, `/assist`).
 pub(crate) use by_name::{AssistRequest, TargetByNameRequest};
-// The byte-verified reaction decode + its faction catalog, reused by the unit-frame feed to tint the
-// target's name plate (`TargetFrame_CheckFaction`) the same way the selection ring colours itself.
-// `duel_rung` is the diagnostic face of the same walk, for `/reaction` (decision 0637).
+// The reaction decode and its faction catalog, which also tint the target frame
+// (`TargetFrame_CheckFaction`); `duel_rung` is the same walk, for `/reaction`.
 pub(crate) use ring::{duel_rung, ring_reaction, ring_variant, Factions, RingVariant};
 
 pub(crate) use click::DeselectGuid;
 
-/// Our current target: the selected entity and its server guid, or `None`. Set the instant we click a
-/// unit (client-authoritative for the ring — the real client doesn't wait for the server), cleared on
-/// deselect or when the target streams out. The guid is what we send in `CMSG_SET_SELECTION` and, later,
-/// what unit frames / other-unit rings key off.
+/// Our target, set the instant we click, as the 1.12 client does without waiting for the server,
+/// and cleared on deselect or when it streams out. `CMSG_SET_SELECTION` carries the guid, which the
+/// server records in our `UNIT_FIELD_TARGET`.
 #[derive(Resource, Default)]
 pub(crate) struct Selection {
     pub(crate) target: Option<Entity>,
     pub(crate) guid: Option<u64>,
 }
 
-/// The **character-model pick** this frame — the one ray pass over every skinned body in the scene,
-/// published by kind. Recomputed every frame by [`hover::update_hover`] (plate rects first, then the
-/// posed-mesh pick).
-///
-/// **Two slots, and at most one of them is ever set**, because there is one pick: [`Self::target`]
-/// when the winner is a unit or another player, [`Self::corpse`] when it is a corpse object. That
-/// split is the reference's own shape — it makes a single pick over all CGObjects and switches on
-/// **type** at the end (`0x480df0` → `0x7089c0`), and `CGCorpse_C` is a type that pick can land on
-/// while being neither selectable nor a GameObject. Keeping the corpse out of `target` is what
-/// keeps every existing consumer — selection, the plates, the unit tooltip, the mouseover
-/// highlight, the `mouseover` unit token — correct without knowing corpses exist: a corpse is not
-/// a unit and must never answer as one.
+/// This frame's character-model pick, by [`hover::update_hover`]. At most one slot is set: the
+/// reference makes one pick over all CGObjects and switches on type at the end (`0x480df0` →
+/// `0x7089c0`), and a corpse (`CGCorpse_C`) is not a unit, so it never answers as `target`.
 #[derive(Resource, Default, Clone, Copy)]
 pub(crate) struct Hovered {
-    /// The hovered **unit or player** — the selectable one. `None` when the pick found a corpse,
-    /// or nothing.
+    /// The hovered unit or player, the selectable slot.
     pub(crate) target: Option<Entity>,
     pub(crate) guid: Option<u64>,
-    /// World-space ray distance to the picked mesh (a plate-rect hover is `0.0` — UI wins any tie).
-    /// Meaningless when neither slot is set. Covers **whichever** slot won, so the cursor/interact
-    /// arbiter picks the nearer of the character pick vs. a hovered GameObject ([`go_is_nearest`]),
-    /// the reference's single nearest-CGObject pick.
+    /// Ray distance to the pick, refused or not; a plate hover is `0.0`, so UI wins any tie.
     pub(crate) distance: f32,
-    /// The hovered **corpse object** (decision 1723) — a streamed body with a guid and a character
-    /// model that is nonetheless not a unit: the reference's `CGCorpse_C` fills the interact slot
-    /// `+0x60` with its own `0x5d6bf0`, never `SetTarget`. Read by the cursor classifier's corpse
-    /// leg and the right-click corpse route; deliberately invisible to everything that means
-    /// "unit".
+    /// The hovered corpse: the reference's `CGCorpse_C` fills the interact slot `+0x60`
+    /// (`0x5d6bf0`), never `SetTarget`.
     pub(crate) corpse: Option<Entity>,
-    /// The hovered corpse's guid — `CMSG_LOOT` / `CMSG_RECLAIM_CORPSE` carry it.
+    /// The hovered corpse's guid, which `CMSG_LOOT` and `CMSG_RECLAIM_CORPSE` carry.
     pub(crate) corpse_guid: Option<u64>,
-    /// **The pick won, and the grader threw it away** — [`hover::selectable_pick`], the
-    /// `IsSelectable` refusal at `0x482982`–`0x482987`. Both entity slots are empty, but
-    /// [`Self::distance`] still holds where the ray hit, because in the reference there is ONE
-    /// pick over all CGObjects: a non-selectable unit standing in front of a chest **wins** that
-    /// pick and is then discarded, so the chest behind it does not inherit the mouseover.
-    ///
-    /// Two readers, and no others: [`go_is_nearest`], and [`click::select_on_click`]'s
-    /// nothing-leg guard — a refused pick is an **object** hit, and the reference's object leg
-    /// clears no selection. Everything else sees an empty hover, which is the point.
+    /// The `IsSelectable` grader refused the winning pick (`0x482982`): both slots are empty but
+    /// [`Self::distance`] holds the hit, so a chest behind the unit does not inherit the mouseover.
+    /// To [`click::select_on_click`] it is an object hit, which clears no selection.
     pub(crate) refused: bool,
 }
 
 impl Hovered {
-    /// The picked entity whichever slot holds it — the "did the ray hit a character model at all?"
-    /// question the GameObject arbiter asks.
+    /// The picked entity, whichever slot holds it.
     pub(crate) fn any(&self) -> Option<Entity> {
         self.target.or(self.corpse)
     }
 }
 
-/// The **GameObject** under the cursor this frame — the interaction arc's separate hover authority
-/// (decision 0236), kept out of the byte-verified unit [`Hovered`] path because a GameObject is
-/// *usable but never selected*. Filled by [`hover::update_hovered_object`] (a GO-only mesh-ray pick);
-/// read by the cursor classifier (the Interact gear) and the right-click USE action. Both compose it
-/// with the unit hover by [`go_is_nearest`] — a GO acts only when it is the nearer object.
+/// The GameObject under the cursor this frame, by [`hover::update_hovered_object`]: usable, never
+/// selected. It acts only when nearer than the character pick ([`go_is_nearest`]).
 #[derive(Resource, Default, Clone, Copy)]
 pub(crate) struct HoveredObject {
     pub(crate) target: Option<Entity>,
     pub(crate) guid: Option<u64>,
-    /// World-space ray distance to the GO mesh, compared against [`Hovered::distance`].
+    /// World-space ray distance, compared against [`Hovered::distance`].
     pub(crate) distance: f32,
 }
 
-/// 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`) 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.
+/// This frame's world hit along the cursor ray, by [`hover::update_pick_occlusion`]: a unit or
+/// GameObject behind a wall is not hoverable (`0x480df0`).
 #[derive(Resource, Clone, Copy)]
 pub(crate) struct PickOcclusion {
     pub(crate) distance: f32,
-    /// The hit itself — the world-space point `distance` names along the cursor ray, or `None`
-    /// with no hit (sky, mouselook, no cursor). The ground-targeting machine's hover/commit point
-    /// (decision 0792): the same world trace the reference's targeting position rides.
+    /// The world hit point, which the ground-targeting cursor rides, as in the reference.
     pub(crate) point: Option<Vec3>,
 }
 
@@ -234,61 +132,30 @@ 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, 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:
-/// the mouse may travel anywhere in between, and the latched pick is untouched.
-///
-/// benilla had no latch — every click consumer read the *live* hover, which
-/// [`hover::update_hover`] clears outright the moment a look session engages. So the release found
-/// an empty hover and [`click::select_on_click`] fell into its deselect arm: a drag didn't merely
-/// fail to select, it would have **cleared** the target (decision 1122, ledger B226).
-///
-/// Note this is a *different* thing from the hover highlight, which the reference **does** suppress
-/// during freelook (`0x483e80` sets the WorldFrame cursor-suppress bit `[wf+0x38c]&2`, tested by the
-/// hover classifier `0x4828d0`). Tooltip, brighten and cursor go quiet while you orbit; the pending
-/// click's subject does not. Conflating those two was the root cause.
-///
-/// Written by [`latch_press_pick`] at the head of the target chain, which runs **before**
-/// [`hover::update_hover`] can clear anything, so the values it copies are the pick as of the press.
-///
-/// **Both buttons read it** (decision 2230). 1122 built this for the left button and left
-/// [`click::act_on_right_click`] on the live hover, where it appeared to work only because the
-/// release frame re-picks at the restored cursor and — for a body click that moved nothing —
-/// lands back on the same unit. It is not the same pick: the plate case has no body under the
-/// cursor to re-find, so a right-click on a V-plate acted on nothing at all.
+/// The pick latched on the button's down edge, which a world click of either button acts on: the
+/// reference picks once per press (`0x481f00`) into the WorldFrame (state `+0x350`, guid `+0x358`,
+/// point `+0x360`, distance `+0x36c`), so a drag can orbit the camera and still select. The hover
+/// is another matter: the reference blanks it during freelook (`0x483e80` sets `[wf+0x38c]&2`).
 #[derive(Resource, Default, Clone, Copy)]
 pub(crate) struct PressPick {
     pub(crate) hovered: Hovered,
     pub(crate) object: HoveredObject,
     pub(crate) occlusion: PickOcclusion,
-    /// The **context cursor as of the press** — the classification the whole right-click ladder
-    /// forks on (Attack/Speak/Loot/the GameObject arms) plus its `unable` range gray, and the
-    /// reference's new-target validation (`0x5ecb70`) likewise reads the pick the gesture started
-    /// on, not a live one. Latched whole rather than as the single Attack bit it used to be,
-    /// because every one of those forks is the same frozen pick's answer.
+    /// The context cursor as of the press, which the right-click ladder forks on; the reference's
+    /// new-target validation (`0x5ecb70`) also reads the press's pick, not a live one.
     pub(crate) cursor: cursor_mode::WorldCursor,
 }
 
 impl PressPick {
-    /// Was the press an **Attack**-cursor press? `0x5ecb70`'s new-target validation.
+    /// Whether the press was an Attack-cursor press, for `0x5ecb70`'s new-target validation.
     pub(crate) fn attack(&self) -> bool {
         self.cursor.kind == cursor_mode::CursorKind::Attack
     }
 }
 
-/// Latch the frame's pick as a press begins — the [`PressPick`] writer.
-///
-/// Ordered at the **head** of the target chain, ahead of every pick refresh, for a reason that is
-/// easy to lose: `player::control` (input) has already run this frame, so on the press frame the
-/// look session is *already* engaged and [`hover::update_hover`] — two systems below — is about to
-/// clear the hover. The values still standing here are last frame's, computed at the same cursor
-/// position the press landed on, because the cursor cannot have moved between the two. That is the
-/// press-time pick, and it is the last moment it exists.
+/// Latch the frame's pick as a press begins. It must run at the head of the target chain: input has
+/// already engaged the look session on the press frame, and [`hover::update_hover`] is about to
+/// clear the hover, so what stands here is last frame's pick at the same cursor, the press's.
 pub(crate) fn latch_press_pick(
     buttons: Res<ButtonInput<MouseButton>>,
     hovered: Res<Hovered>,
@@ -297,10 +164,8 @@ pub(crate) fn latch_press_pick(
     cursor: Res<cursor_mode::WorldCursor>,
     mut press: ResMut<PressPick>,
 ) {
-    // Either primary button's down edge arms a pick, exactly as the reference's `0x514810` does for
-    // clickMode 1 (CameraOrSelectOrMove) and 2 (TurnOrAction). A chord — the second button of a
-    // both-button run — must NOT re-latch: `0x51481a` refuses to arm while another primary is held,
-    // and the arbiter cancels the pending click outright anyway.
+    // Either button's down edge arms a pick (`0x514810`, clickModes 1 and 2); a chord does not
+    // re-latch, as `0x51481a` refuses to arm while the other button is held.
     let left = buttons.just_pressed(MouseButton::Left) && !buttons.pressed(MouseButton::Right);
     let right = buttons.just_pressed(MouseButton::Right) && !buttons.pressed(MouseButton::Left);
     if !(left || right) {
@@ -314,20 +179,10 @@ pub(crate) fn latch_press_pick(
     };
 }
 
-/// Which of the two hovered CGObjects — the character-model [`Hovered`] or the [`HoveredObject`] —
-/// is the nearer thing under the cursor, and so the one a click acts on. The reference makes one
-/// pick over all CGObjects and switches on type; benilla runs the character and GameObject picks
-/// separately, then chooses the nearer here. A GameObject wins only when it is strictly closer
-/// than the character pick (so a mailbox in front of a distant NPC takes the click; an NPC in
-/// front of a chest keeps it).
-///
-/// **Either slot of [`Hovered`] counts** ([`Hovered::any`]): a hovered *corpse* holds the ground
-/// against a farther GameObject exactly as a unit does. Reading only `target` here — as this did
-/// before corpses could be picked — would have handed the click, the cursor, the tooltip and the
-/// highlight to any GameObject on screen the instant the ray landed on a body instead of a unit.
+/// Whether the hovered GameObject, not the character pick, is what a click acts on. The reference
+/// makes one pick over all CGObjects; benilla makes two and keeps the GameObject only when strictly
+/// nearer. A corpse or a refused pick holds the ground as a unit does.
 pub(crate) fn go_is_nearest(character: &Hovered, go: &HoveredObject) -> bool {
-    // A **refused** character pick still occupies the pick (see [`Hovered::refused`]): it wins on
-    // distance exactly as a kept one would, and then nothing is hovered at all.
     match (character.any().is_some() || character.refused, go.target) {
         (true, Some(_)) => go.distance < character.distance,
         (false, Some(_)) => true,
@@ -335,28 +190,20 @@ 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` (`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.
+/// A unit's model-local ring radius, `sqrt(0.5 · sqrt(dx² + dy²))` over the Stand sequence box's
+/// horizontal extents (`0x608e00`/`0x60aee0`); the ring scales it by `OBJECT_FIELD_SCALE_X`.
+/// Stamped at attach; a model-less unit has none and takes the ring's fallback radius.
 #[derive(Component, Clone, Copy)]
 pub(crate) struct SelectionRadius(pub(crate) f32);
 
-/// The Update set the whole targeting chain runs in. Consumers of the frame's verdicts —
-/// [`Selection`], [`Hovered`], [`CombatFlash`] (the nameplate driver) — order after it; without
-/// the constraint their order against the chain is ambiguous and they can read last frame's
-/// verdict (one-frame flicker on select/flash edges).
+/// The set the targeting chain runs in: readers of [`Selection`], [`Hovered`] or [`CombatFlash`]
+/// order after it, or they can read last frame's verdict.
 #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
 pub(crate) struct TargetUpdate;
 
-/// The click-behavior player knob (decision 0961): `deselectOnClick` is 1.12's own CVar behind
-/// the "Sticky Targeting" Interface Options checkbox (inverted there AND in era — checked means
-/// the CVar at 0). Default true = the reference default: an empty-world click clears the
-/// target, which is exactly the behavior [`click::select_on_click`] shipped with (0571/0574's
-/// terrain/nothing legs); the knob only makes its gate player-settable through the CVar store
-/// (0954).
+/// `deselectOnClick`, 1.12's CVar behind the "Sticky Targeting" checkbox, which shows it inverted
+/// (`UIOptionsFrame.lua:250`). On by default, as in the reference: an empty-world click clears the
+/// target.
 #[derive(Resource)]
 pub(crate) struct ClickConfig {
     pub(crate) deselect_on_click: bool,
@@ -370,25 +217,13 @@ impl Default for ClickConfig {
     }
 }
 
-/// **`assistAttack`** — the second, opt-in leg of `/assist` (1.12's *Assist Attack* checkbox).
-///
-/// `/assist` always does leg 1: read the basis unit's `UNIT_FIELD_TARGET` and select it
-/// (`CMSG_SET_SELECTION`). With this CVar non-zero the reference's shared tail runs a **second**
-/// leg — `0x489c02`/`0x489d02 call 0x5ecb70` `StartAttack(&guid)` — which stands you and sends
-/// `CMSG_ATTACKSWING`. So `/assist` stops meaning "select what my friend is fighting" and starts
-/// meaning "select it and open the swing".
-///
-/// Its record `[0xb4d8f8]` has exactly **three references image-wide**: the registration store and
-/// 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** (`0x48fc50`).
-/// Reading `"3"` for it is the `mov ds:` adjacency trap: that is the *next* registration's
-/// default (`minimapZoom`).
+/// `assistAttack`, 1.12's "Attack on assist" option (`[0xb4d8f8]`, registered at `0x48fc50` with
+/// default "0"). When set, `/assist`'s shared tail also calls `StartAttack 0x5ecb70` on the new
+/// target (`0x489c02`, `0x489d02`), which stands you and sends `CMSG_ATTACKSWING`.
 #[derive(Resource, Default)]
 pub(crate) struct AssistAttack(pub(crate) bool);
 
-/// The targeting rows' change callback (decision 2303): two flags.
+/// The targeting rows' change callback: two flags.
 pub(crate) fn on_cvar(
     ev: On<crate::cvars::CvarChanged>,
     mut click: ResMut<ClickConfig>,
@@ -430,95 +265,71 @@ impl Plugin for TargetPlugin {
                     (ring::load_factions, scan::load_creature_types).after(AssetSet::Open),
                 ),
             )
-            // All after input (so this frame's `WorldClick` from `player::control` is available), in
-            // order: refresh the hovered unit, resolve its context cursor, route the right-click
-            // cursor-payload leg (decisions 0571 + 0574), let a click select it, handle Esc,
-            // drain the UI's `TargetUnit` requests (the PlayerFrame self-target), then the
-            // selection writers that don't come from the mouse (the auto-acquires + TAB), then
-            // the flash verdict and the ring off the frame's final selection.
+            // After input, so this frame's `WorldClick` is here, in order: the picks, the cursor,
+            // the clicks, the non-mouse selection writers, then the flash and the ring off the
+            // frame's final selection. Nested tuples keep the chain within Bevy's 20-tuple limit.
             .add_systems(
                 Update,
                 (
-                    // Grouped as one element (the outer chain is at Bevy's 20-tuple limit), and
-                    // ordered: the latch FIRST, ahead of every pick refresh, to freeze what the
-                    // press was over while it still exists (decision 1122 — see [`latch_press_pick`]).
+                    // The latch first, before any pick refresh clears what the press was over.
                     (latch_press_pick, hover::update_pick_occlusion).chain(),
                     hover::update_hover,
                     hover::update_hovered_object,
                     cursor_mode::classify_cursor,
-                    // 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.
+                    // The right-press cancel (the reference's OnMouseDown hook) before the cursor
+                    // drive, so the press frame already reads the mode cleared.
                     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.
+                    // Overwrites the classifier's verdict while the targeting cursor is up, as the
+                    // reference's dispatcher runs this branch before the object classifier.
                     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).
+                    // Reads that verdict: `WorldCursor.unable` is the frame's range state, as the
+                    // reference's one `CheckGroundPointInRange` caller feeds both.
                     reticle::update_reticle,
                     click::world_right_click_payload,
-                    // A plate click replayed as the click it is (2148), then the select that
-                    // reads it. One element, chained: the outer chain is at Bevy's 20-tuple limit.
+                    // A plate click replayed as a click, then the select that reads it.
                     (click::select_on_plate_click, click::select_on_click).chain(),
-                    // AFTER the gated select (which holds while the mode is active): the commit
-                    // may clear the mode, and the selection gate must have read it first. The two
-                    // 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.
+                    // After the gated select, which must read the targeting mode before a commit
+                    // clears it. The pending spell feeds only one of the two legs, so their mutual
+                    // order is free.
                     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
-                    // Bevy's 20-tuple limit): the selection asks' commit (`TargetUnit`,
-                    // `AssistUnit`, `TargetLastEnemy` — one queue, one drain, as the reference has
-                    // one `0x489a40`), and `DropItemOnUnit`'s pet-leg feed (decision 1055).
-                    // Independent of each other — one writes `Selection`, the other sends a cast —
-                    // so they need no order.
+                    // The unit-token asks (`TargetUnit`, `AssistUnit`, `TargetLastEnemy`: one
+                    // drain, as the reference has one `0x489a40`) and `DropItemOnUnit`'s pet leg,
+                    // independent of each other.
                     (
                         click::selection_requests,
                         crate::ui_action::drop_item::drop_item_on_unit,
                     ),
-                    // The chat layer's by-name asks (decision 0886), beside the UI's token asks:
-                    // both are non-mouse selection writers committing through `scan::commit`.
-                    // The chat layer's by-name asks, grouped as one chained element (the outer
-                    // chain is at Bevy's 20-tuple limit): `/target` and `/assist` commit through
-                    // `scan::commit` like every other non-mouse selection writer, and `/follow`
-                    // resolves its subject for `crate::player` to move (decision 0890) without
-                    // touching `Selection` at all.
+                    // The by-name asks: `/target`, the Lua `TargetByName` and `/assist` commit
+                    // through `scan::commit`; `/follow` hands its subject to `crate::player`.
                     (
                         by_name::target_by_name_requests,
-                        // The Lua binding's own by-name asks (11 corpus addons call
-                        // `TargetByName`), beside the chat layer's — same resolver, same commit,
-                        // one extra argument the slash command cannot supply.
                         by_name::script_target_by_name_requests,
                         by_name::assist_requests,
                         by_name::follow_requests,
                     )
                         .chain(),
                     scan::auto_acquire_attacker,
-                    // The two sides of the one cycler (`0x493f60`, mode 1 / mode 2), grouped as
-                    // one element (the outer chain is at Bevy's 20-tuple limit) and chained
-                    // because they share `TabHistory`, whose side switch clears it.
+                    // The one cycler's two sides (`0x493f60`, modes 1 and 2), chained: they share
+                    // `TabHistory`, which a side switch clears.
                     (scan::tab_target, scan::target_nearest_friend_requests).chain(),
                     scan::acquire_and_attack,
                     flash::drive_flash,
-                    // `TargetLastEnemy`'s stamp, then the ring. The order is load-bearing: the
-                    // ring's death-clear drops the selection, and a hostile that dies while
-                    // selected must still be remembered (the reference's shim has no liveness
-                    // gate — re-targeting the corpse is faithful).
+                    // The last-enemy stamp before the ring's death-clear, so a hostile that dies
+                    // selected is still remembered (the reference's `TargetLastEnemy` has no
+                    // liveness gate).
                     (scan::remember_last_enemy, ring::update_ring).chain(),
                 )
                     .chain()
                     .in_set(TargetUpdate)
                     .after(WorldStage::Input),
             )
-            // The model brighten writes MeshTag bit 31 — PostUpdate, after every Update payload
-            // writer (fade/interior/…), so their whole-tag overwrites can't strand the bit.
+            // PostUpdate: the brighten sets MeshTag bit 31 after every Update writer that
+            // overwrites the whole tag.
             .add_systems(PostUpdate, highlight::apply_highlight)
-            // The ring's stream push: after the frame's stream clear (the projection cache was
-            // rebuilt by `update_ring` in Update; this is a tinted copy).
+            // The ring's stream push, after the frame's stream clear.
             .add_systems(
                 PostUpdate,
                 (ring::push_ring, reticle::push_reticle)
@@ -537,7 +348,7 @@ mod tests {
             distance: d,
             ..Hovered::default()
         };
-        // The same hover, landed on a CORPSE instead of a unit — the other slot of the one pick.
+        // The same hover landed on a corpse, the other slot of the one pick.
         let corpse = |t: bool, d: f32| Hovered {
             corpse: t.then_some(Entity::PLACEHOLDER),
             distance: d,
@@ -548,29 +359,21 @@ mod tests {
             guid: None,
             distance: d,
         };
-        // No GameObject hovered → the unit path always keeps the click.
+        // No GameObject hovered: the unit path keeps the click.
         assert!(!go_is_nearest(&hov(true, 5.0), &obj(false, 0.0)));
         assert!(!go_is_nearest(&hov(false, 0.0), &obj(false, 0.0)));
-        // A GameObject with no competing unit → it takes the click.
+        // A GameObject with no competing unit takes the click.
         assert!(go_is_nearest(&hov(false, 0.0), &obj(true, 42.0)));
-        // Both hovered → only a *strictly nearer* GameObject wins (a mailbox in front of a distant
-        // NPC); a farther or tied GameObject yields to the unit (a plate hover sits at distance 0.0).
+        // Both hovered: only a strictly nearer GameObject wins; a tie goes to the unit.
         assert!(go_is_nearest(&hov(true, 10.0), &obj(true, 4.0)));
         assert!(!go_is_nearest(&hov(true, 4.0), &obj(true, 10.0)));
         assert!(!go_is_nearest(&hov(true, 5.0), &obj(true, 5.0)));
-        // A hovered CORPSE competes on exactly the same terms as a unit (decision 1723): it is the
-        // other slot of the same pick, so it keeps the click from a farther or tied GameObject and
-        // yields only to a strictly nearer one.
+        // A corpse competes on the same terms as a unit.
         assert!(!go_is_nearest(&corpse(true, 5.0), &obj(false, 0.0)));
         assert!(!go_is_nearest(&corpse(true, 4.0), &obj(true, 10.0)));
         assert!(!go_is_nearest(&corpse(true, 5.0), &obj(true, 5.0)));
         assert!(go_is_nearest(&corpse(true, 10.0), &obj(true, 4.0)));
-        // A **refused** pick — a `NOT_SELECTABLE` unit the hover grader threw away
-        // (`hover::selectable_pick`; the predicate's own arms are pinned in
-        // `scan::tests::not_selectable_refuses_the_commit_and_keeps_the_old_target`) — holds the
-        // ground on distance exactly as a kept one does, and then nothing is hovered at all: the
-        // reference makes ONE pick over all CGObjects, so the flagged unit *wins* it and is
-        // discarded, and the chest standing behind it never inherits the mouseover.
+        // So does a pick the `IsSelectable` grader refused, and then nothing is hovered at all.
         let refused = |d: f32| Hovered {
             refused: true,
             distance: d,
@@ -581,13 +384,8 @@ mod tests {
         assert!(go_is_nearest(&refused(10.0), &obj(true, 4.0)));
     }
 
-    /// The latch survives the hover being cleared — which is the whole reason it exists.
-    ///
-    /// A drag engages the look session, and `hover::update_hover` then blanks [`Hovered`] for its
-    /// whole duration (as the reference suppresses its own hover during freelook). Before decision
-    /// 1122 every click consumer read that live hover, so a click ending a drag saw *nothing*
-    /// hovered and [`click::select_on_click`] took its deselect arm: the gesture would have cleared
-    /// the player's target rather than selecting. The press latch is what a click reads instead.
+    /// A drag blanks the live hover for its whole length, and a click at its end must still act on
+    /// what the press was over.
     #[test]
     fn the_press_latch_outlives_the_hover_a_drag_clears() {
         let mut world = World::new();
@@ -604,7 +402,7 @@ mod tests {
         world.resource_mut::<Hovered>().guid = Some(BOAR);
         world.resource_mut::<cursor_mode::WorldCursor>().kind = cursor_mode::CursorKind::Attack;
 
-        // Press left. The latch takes the pick.
+        // Press left: the latch takes the pick.
         world
             .resource_mut::<ButtonInput<MouseButton>>()
             .press(MouseButton::Left);
@@ -612,8 +410,7 @@ mod tests {
         assert_eq!(world.resource::<PressPick>().hovered.guid, Some(BOAR));
         assert!(world.resource::<PressPick>().attack(), "Attack rode along");
 
-        // The drag begins: the look session blanks the live hover, every frame, for as long as it
-        // lasts. The latch must not follow it down.
+        // The drag begins: the look session blanks the live hover.
         *world.resource_mut::<Hovered>() = Hovered::default();
         world.resource_mut::<ButtonInput<MouseButton>>().clear();
         world.run_system(id).unwrap();
@@ -624,10 +421,8 @@ mod tests {
         );
     }
 
-    /// A chord — the second primary joining a held one — must not re-latch. The reference refuses
-    /// to arm or pick while another primary is down (`0x51481a`), and kills the pending click
-    /// outright (`0x514ac1`), so neither release of a both-button run can select. Re-latching here
-    /// would hand a spurious pick to a gesture that is only ever a camera turn.
+    /// The reference refuses to arm while another button is down (`0x51481a`) and kills the
+    /// pending click (`0x514ac1`), so neither release of a both-button run selects.
     #[test]
     fn a_chord_does_not_relatch_the_pick() {
         let mut world = World::new();
diff --git a/crates/benilla-app/src/target/relations.rs b/crates/benilla-app/src/target/relations.rs
index 7757e1e3..ab47a8d5 100644
--- a/crates/benilla-app/src/target/relations.rs
+++ b/crates/benilla-app/src/target/relations.rs
@@ -1,19 +1,13 @@
-//! **Who may I attack, who may I interact with, who may I help** — the three unit-relationship
-//! predicates the reference shares across systems, kept together because they are one concern and
-//! none belongs to the system that happens to call it first.
+//! The three unit-relationship predicates the reference shares across systems, may I attack,
+//! interact with or help this unit, as the store-only entry points every consumer calls:
 //!
-//! The first two are byte-verified **complete** functions and live next door in [`super::ring`],
-//! beside the two reaction directions they turn on — because *which direction* is the whole
-//! content of both (`0x6061e0(this = player)` answers a reputation-slot faction with the **at-war
-//! bit**; `0x6061e0(this = unit)` reads the standing, and the two routinely disagree). This file
-//! is the shared store-only entry point every consumer calls:
+//! - `CanAttack 0x606980` forwards to [`super::ring::can_attack_from_player`],
+//! - `CanInteract 0x6067f0` forwards to [`super::ring::can_interact_from_player`],
+//! - `CanAssist 0x6066f0` is derived here, on [`ring_reaction`].
 //!
-//! - `CanAttack 0x606980` → [`super::ring::can_attack_from_player`],
-//! - `CanInteract 0x6067f0` → [`super::ring::can_interact_from_player`],
-//! - `CanAssist 0x6066f0` → still the reaction-rank derivation below, on [`ring_reaction`].
-//!
-//! They lived in `scan.rs` while `can_attack` had exactly one caller; `can_assist` (the `UnitBuff`
-//! gate, decision 1035) made that a second concern in a file about TAB targeting.
+//! The first two live in [`super::ring`] beside the reaction directions they turn on:
+//! `0x6061e0(this = player)` answers a reputation faction with the at-war bit,
+//! `0x6061e0(this = unit)` with the standing, and the two often disagree.
 
 use benilla_protocol::messages::{ObjectType, OwnerFallback};
 
@@ -21,37 +15,21 @@ use crate::net::{ObjectStore, Reputations};
 
 use super::{ring_reaction, Factions};
 
-/// `OBJECT_FIELD_TYPE` bit 4 — the reference's own "is this a Player" test, read as
-/// `[obj->descriptorBlock[2] + 8] >> 4 & 1` (`0x606984` in `CanAttack`, `0x6067fc` in
-/// `CanInteract`). Taken off the object's own field rather than the spawning `NetEntity`, because
-/// that is the bit the binary reads and it cannot drift from the store the rest of the predicate
-/// walks.
+/// `OBJECT_FIELD_TYPE` bit 4, the reference's own player test (`0x606984` in `CanAttack`,
+/// `0x6067fc` in `CanInteract`), read off the store the rest of the predicate walks.
 ///
-/// **The one thing not verified against a live stream** is whether the server always puts field 2
-/// in the create block (vmangos sends every non-zero field, and a player's is `0x19`, so it should
-/// always be there — but that is a reading of the emulator, not an observation). The failure mode
-/// is bounded and inert: this feeds only `CanAttack`'s ghost leg, so a false negative on a real
-/// player skips a refusal that the both-player-controlled arm then makes anyway — a ghost carries
-/// no duel, PvP flag or FFA pair. `/reaction` prints this beside the `NetEntity` kind so the first
-/// hover over a player settles it by observation.
+/// Relies on the create block carrying field 2: vmangos sends every non-zero field, and a player's
+/// is `0x19`. A miss only skips `CanAttack`'s ghost refusal, which the both-player-controlled arm
+/// makes anyway; `/reaction` prints the field beside the `NetEntity` kind.
 fn is_player_object(store: Option<&ObjectStore>) -> bool {
     store.and_then(|s| s.0.object_type()) == Some(ObjectType::Player)
 }
 
-/// `CanAttack 0x606980` — the shared attackability predicate: the world cursor's sword leg
-/// (`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 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.
-///
-/// It used to be `flag disqualifiers && ring_reaction ≤ 3`, and **the threshold was reading the
-/// wrong reaction direction** — the very substitution decision 1530 named as the shipped defect
-/// and corrected for nameplates alone. `0x606980`'s mixed arm is `UnitReaction(**player** → target)
-/// < 4`, and that direction answers a reputation-slot faction with the **at-war bit**, never the
-/// standing. Keeping the standing here made every not-at-war neutral faction attackable: hovering
-/// a Cenarion Circle NPC drew the sword, TAB targeted it, and `UnitCanAttack` agreed (decision 1674).
+/// `CanAttack 0x606980`, the one attackability question of the world cursor's sword
+/// (`0x48269a`), the combat flash, the TAB scan's filter 3, `UnitCanAttack` and hostile spell
+/// targeting. Its mixed arm is `UnitReaction(player → target) < 4`, which answers a reputation
+/// faction with the at-war bit, never the standing, so a not-at-war neutral faction (Cenarion
+/// Circle) is not attackable.
 pub(crate) fn can_attack(
     store: Option<&ObjectStore>,
     factions: Option<&Factions>,
@@ -67,11 +45,9 @@ pub(crate) fn can_attack(
     )
 }
 
-/// `CanInteract 0x6067f0` — "may I take a service from this unit?", the gate the world-cursor
-/// classifier runs at `0x482310` (through the `CanInteractNow 0x606880` wrapper) to choose between
-/// the NPC service ladder and the loot/skin/attack block.
-///
-/// Forwards to [`super::ring::can_interact_from_player`], which is the complete `0x6067f0`.
+/// `CanInteract 0x6067f0`, may I take a service from this unit: the world-cursor classifier runs it
+/// at `0x482310` (through `CanInteractNow 0x606880`) to choose between the NPC service ladder and
+/// the loot, skin and attack block.
 pub(crate) fn can_interact(
     store: Option<&ObjectStore>,
     factions: Option<&Factions>,
@@ -81,42 +57,23 @@ pub(crate) fn can_interact(
     super::ring::can_interact_from_player(factions, reputations, store, self_store)
 }
 
-/// `UNIT_FLAG_NOT_SELECTABLE` (bit 25) — `CanAssist`'s own first disqualifier, and one of
-/// `CanAttack`'s five refusal bits (vmangos `UnitDefines.h`).
+/// `UNIT_FLAG_NOT_SELECTABLE`, bit 25 (vmangos `UnitDefines.h:570`): `CanAssist`'s first refusal
+/// and one of `CanAttack`'s.
 const UNIT_FLAG_NOT_SELECTABLE: u32 = 1 << 25;
 
-/// `IsSelectable` — CGUnit_C's **vtable slot 21** (`0x60be60`), the predicate every selection path
-/// reaches through the `+0x58` thunk `0x5f1ec0` (`mov eax,[ecx]; jmp [eax+0x54]`):
+/// `IsSelectable`, CGUnit_C's vtable slot 21 (`0x60be60`): `UNIT_FLAG_NOT_SELECTABLE` clear, or the
+/// unit's `UNIT_FIELD_CREATEDBY` is the active player, so your own flagged totems and traps stay
+/// selectable. Every vtable but CGUnit_C's and CGPlayer_C's has the `xor eax,eax` stub
+/// (`0x469fe0`) there, so a GameObject, item or corpse never becomes the selection.
 ///
-/// ```text
-/// 60be60  mov  eax,[ecx+0x110]        ; the descriptor block
-/// 60be6f  shr  ecx,0x19 / test cl,1   ; UNIT_FIELD_FLAGS bit 25 (0x02000000) — clear ⇒ return 1
-/// 60be82  cmp  [eax+0x20],…           ; else UNIT_FIELD_CREATEDBY == the active player's guid
-/// 60be94  mov  eax,1 / ret            ;      ⇒ return 1, otherwise 0
-/// ```
-///
-/// So: **`NOT_SELECTABLE` clear, OR the unit is something *I* created.** The `CREATEDBY` clause is
-/// the asymmetry worth carrying — your own flagged creations (your totems, your traps) stay
-/// selectable, somebody else's do not.
-///
-/// Slot `+0x58` is the base stub `0x469fe0` (`xor eax,eax`) in **every** vtable but CGUnit_C's
-/// (`0x80c4f8`) and CGPlayer_C's (`0x80af78`), so a GameObject, an item or a corpse answers
-/// **false** here — which is the reason a non-unit guid can never become the selection.
-///
-/// **`None` is the reference's skipped vcall, not a refusal.** `SetSelection` only makes the call
-/// on an object the manager actually resolved (`0x4935c6`/`0x4935c8` falls straight through to the
-/// commit when it does not), which is how an out-of-range party member — on the roster, no
-/// streamed object — stays selectable. A missing store here is that same state, so it passes; and
-/// a store whose `OBJECT_FIELD_TYPE` has not streamed is read the same permissive way rather than
-/// refusing a selection over an absent field.
-///
-/// `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`).
+/// `None` passes: `SetSelection 0x493540` makes the call (`0x4935ee`) only on an object the
+/// manager resolved (`0x4935c8`), which keeps an out-of-range party member selectable. A store
+/// whose `OBJECT_FIELD_TYPE` has not streamed passes the same way.
 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`)
+        return true; // no resolved object: the reference skips the call (`0x4935c8`)
     };
-    // The base stub: only a CGUnit_C / CGPlayer_C carries a real slot-21 override.
+    // Only CGUnit_C and CGPlayer_C override slot 21.
     if !matches!(
         store.0.object_type(),
         None | Some(ObjectType::Unit) | Some(ObjectType::Player)
@@ -127,28 +84,21 @@ pub(crate) fn is_selectable(store: Option<&ObjectStore>, self_guid: Option<u64>)
         || (self_guid.is_some() && store.0.unit_created_by() == self_guid)
 }
 
-/// `UNIT_FLAG_PVP` (bit 12) — what `IsPvP 0x605ff0` tests, after resolving the unit's owner
-/// (vmangos `UnitDefines.h:UNIT_FLAG_PVP = 0x1000`).
+/// `UNIT_FLAG_PVP`, bit 12 (vmangos `UnitDefines.h:557`), what `IsPvP 0x605ff0` tests on the
+/// unit's owner.
 const UNIT_FLAG_PVP: u32 = 0x1000;
-/// `UNIT_FLAG_PVP_ATTACKABLE` (bit 3) — behaviourally "player-controlled", the same bit
+/// `UNIT_FIELD_FLAGS` bit 3, player-controlled (vmangos `UnitDefines.h:548`), the bit
 /// [`ring_reaction`]'s duel leg selects on.
 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`]). Named by its own Lua registrar pair
-/// (`.data 0x8504c8 = {"UnitCanAssist", 0x516bb0}`), not by resemblance.
+/// `CanAssist 0x6066f0` (Lua `UnitCanAssist` `0x516bb0`, registered at `.data 0x8504c8`), the
+/// unit-level gate of `UnitBuff` ([`crate::ui_aura::buffs_visible_on`]): `UNIT_FLAG_NOT_SELECTABLE`
+/// clear, a reaction of at least 4, and for a unit that is not player-controlled, `IsPvP 0x605ff0`
+/// on its owner. The 4 is the internal scale [`ring_reaction`] returns (`UnitReaction 0x5167e0`
+/// adds 1 for Lua at `0x51683e`), so neutral fails.
 ///
-/// Three clauses: `UNIT_FLAG_NOT_SELECTABLE` clear, `UnitReaction ≥ 4`, and — for a unit that is
-/// **not** player-controlled — `IsPvP 0x605ff0` on the unit (owner-chased). The reaction bar is the
-/// **internal** scale, not the Lua one: `UnitReaction 0x5167e0` does `inc eax` at `0x51683e` before
-/// pushing, so Lua's FRIENDLY(5) is internal 4. [`ring_reaction`] already returns the raw internal
-/// rank, so the comparison is against 4 directly — **neutral fails**.
-///
-/// The player-controlled arm (`0x60673e`–`0x60679f`) keys on an `[obj+0xe68]` record whose fields
-/// 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.
+/// The player-controlled arm (`0x60673e`..`0x60679f`) reads an `[obj+0xe68]` record whose fields
+/// are unnamed and is not built: a player-controlled unit passes, which never hides a buff.
 pub(crate) fn can_assist(
     store: Option<&ObjectStore>,
     factions: Option<&Factions>,
@@ -167,11 +117,10 @@ pub(crate) fn can_assist(
         return false;
     }
     if flags & UNIT_FLAG_PLAYER_CONTROLLED != 0 {
-        // The un-derived arm — see the doc comment.
+        // The player-controlled arm, not built: passes.
         return true;
     }
-    // `IsPvP 0x605ff0`: the flag on the unit's OWNER when it has one (charmedBy, else createdBy —
-    // the `0x5ee5a0` fallback pair), otherwise on the unit itself.
+    // `IsPvP 0x605ff0`: the owner's flag (charmedBy, else createdBy, `0x5ee5a0`), else the unit's.
     let owned = store
         .0
         .unit_owner(OwnerFallback::CreatedBy)
diff --git a/crates/benilla-app/src/target/reticle.rs b/crates/benilla-app/src/target/reticle.rs
index e595c509..3c2e4cbd 100644
--- a/crates/benilla-app/src/target/reticle.rs
+++ b/crates/benilla-app/src/target/reticle.rs
@@ -1,35 +1,22 @@
-//! The **ground-targeting AoE reticle** — the terrain-projected decal a **location** cast's
-//! 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.
+//! The ground-targeting AoE reticle: the terrain-projected decal under a location cast's cursor.
+//! Only a targeting word passing `TargetingWantsLocation`'s `& 0x60` draws one; a bag click or a
+//! world GameObject click arms the same cursor and draws none.
 //!
-//! 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
-//! horizontal plane, **± 2.0 vertically** (`0x4837b0`); textures
-//! `Interface\SpellShadow\Spell-Shadow-Acceptable.blp` (in range) /
-//! `…-Unacceptable.blp` (out), vertex colour `0xffffffff` — the *texture* carries the
-//! green/red, not a tint. It projects through **the same ground-decal projector as the
-//! selection ring** (`0x6d7330 → 0x6d6fa0 → 0x6d7480` — [`benilla_world::decal`]), axis-aligned (no
-//! rotation term; the effect-0x51 placement rotate orients a GameObject *preview model*, a
-//! machine we don't carry — that family of spells is a named residual).
+//! The reference projects a decal for an area spell: the picked ground point ± r horizontally and
+//! ± 2.0 vertically (`0x4837b0`), axis-aligned, through the selection ring's ground-decal projector
+//! (`0x6d7330 → 0x6d6fa0 → 0x6d7480`, [`benilla_world::decal`]). The texture carries the colour,
+//! `Spell-Shadow-Acceptable.blp` in range and `Spell-Shadow-Unacceptable.blp` out of it, under a
+//! white vertex colour. The reference also rotates a GameObject preview model for an
+//! object-placement spell (effect `0x51`); that model is not built.
 //!
-//! **Radius**: `r = min(GetCurrentCastRadius, 20.0)` (`0x6e6350`, clamp `0x4820f0`):
-//! per-effect `radius + casterLevel × perLevel` over **EffectRadiusIndex[0] and [1] only**
-//! (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
-//! is not wired to them (the same residual as the range gate, 0792).
+//! The radius is `ground_cast_radius` (`GetCurrentCastRadius 0x6e6350`, clamped to 20.0 in
+//! `0x4820f0`), with no spell mod applied. Out of range forces it to 0.0, and 0.0 draws at the
+//! 1.3888889 default. With no world hit nothing is drawn: the
+//! reference resets its draw state every hover pass. Over a unit the decal lands on the ground
+//! behind it, since a dest-only word's pick skips the object trace (`0x480e7b`).
 //!
-//! **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 — its flags skip the object trace at `0x480e7b`).
-//!
-//! 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.
+//! The reference's second pass (`0x483727`) also projects onto liquid (flags `0x0f0000`); the
+//! decal surfaces have no liquid yet, so the reticle vanishes over water.
 
 use bevy::prelude::*;
 
@@ -41,22 +28,20 @@ use benilla_world::decal::{DecalFrame, WorldDecal};
 use benilla_world::particles::buffer::EffectVertex;
 use benilla_world::view::WorldCamera;
 
-/// The default footprint when the radius is 0 — out of range, or a rowless spell
-/// (`[0xb4b3b0] == 0.0 → 1.3888889`, the ref's literal).
+/// The footprint for a zero radius, out of range or rowless (the reference's literal for
+/// `[0xb4b3b0] == 0.0`).
 const RETICLE_DEFAULT_RADIUS: f32 = 1.388_889;
-/// The projection box's vertical slab: ± 2.0 around the picked point (`0x4837b0` — fixed, not
-/// radius-scaled like the ring's).
+/// The box's vertical half-height (`0x4837b0`), fixed, not radius-scaled like the ring's.
 const RETICLE_VERT: f32 = 2.0;
 
-/// The two state textures (the render-side residency gate withholds the draw until loaded).
+/// The two state textures; the draw waits until they are loaded.
 #[derive(Resource)]
 pub(super) struct ReticleAssets {
     acceptable: Handle<Image>,
     unacceptable: Handle<Image>,
 }
 
-/// The single reticle record — the ring's resource pattern (projection cached against a key,
-/// pushed onto the effect stream per frame).
+/// The reticle: its projection, cached against a key and pushed onto the effect stream each frame.
 #[derive(Resource, Default)]
 pub(super) struct ReticleState {
     verts: Vec<EffectVertex>,
@@ -65,7 +50,7 @@ pub(super) struct ReticleState {
     shown: bool,
 }
 
-/// The projection's rebuild inputs — a still cursor costs a compare.
+/// The projection's rebuild inputs: a still cursor costs one compare.
 #[derive(Default, PartialEq, Clone, Copy)]
 struct ReticleKey {
     center: Vec3,
@@ -83,21 +68,15 @@ pub(super) fn setup_reticle(mut commands: Commands, asset_server: Res<AssetServe
     commands.init_resource::<ReticleState>();
 }
 
-/// Place/size/state the reticle each frame while a **location** cast awaits its click. Runs
-/// after the targeting cursor drive in the target chain: `WorldCursor.unable` IS the frame's
-/// range verdict (the one `CheckGroundPointInRange` caller — the cursor and the decal state are
-/// the same read in the ref).
+/// Places, sizes and colours the reticle while a location cast awaits its click. Runs after the
+/// targeting cursor drive: `WorldCursor.unable` is the frame's range verdict, one read for the
+/// cursor and the decal, as in the reference.
 ///
-/// **Both of `0x4820f0`'s guards, in its order** (decision 0943): `4820f9 IsTargeting 0x6e48a0`
-/// **and** `482106 TargetingWantsLocation 0x6e6320` — either false and it returns having never
-/// touched the draw state, which the hover handler already reset to `3` = *do not draw*
-/// (`481840`, every pass). The *word's* mask decides, not the mere fact of targeting: a lock or
-/// an enchant word (`0x4000` / `0x0010`) fails `& 0x60`, so no decal is drawn for one. The
-/// reference does not even reach here for such a word — `0x481050`'s targeting arm builds the
-/// pick flags from the word alone, and one without `0x60` gets no bit `0x1`, so the pick reports
-/// state 2 (object → `0x4828d0`) or 0, never state 1. Our picks are not word-gated, so this
-/// consumer carries the guard; asking [`SpellTargeting::spell_for`] rather than `spell()` is what
-/// keeps the next seam from forgetting it.
+/// Both of `0x4820f0`'s guards, in order: `IsTargeting 0x6e48a0`, then `TargetingWantsLocation
+/// 0x6e6320`. Either false returns before the draw state, which the hover handler reset to 3, do
+/// not draw (`0x481840`), so a lock or enchant word (`0x4000`, `0x0010`) draws no decal. The
+/// reference's pick is word-gated (`0x481050`) and ours is not, so this consumer carries the guard,
+/// through [`SpellTargeting::spell_for`].
 pub(super) fn update_reticle(
     targeting: Res<SpellTargeting>,
     occlusion: Res<PickOcclusion>,
@@ -112,14 +91,12 @@ pub(super) fn update_reticle(
         targeting.spell_for(TargetingWants::Location),
         occlusion.point,
     ) else {
-        // Not targeting, targeting a word that wants no location, or the pick hit nothing (sky):
-        // nothing is drawn — the ref resets the draw state on every hover pass before the pick.
+        // Not targeting, a word that wants no location, or no world hit: nothing is drawn.
         state.shown = false;
         return;
     };
     let acceptable = !cursor.unable;
-    // Out of range forces radius 0.0 (the ref writes the global before the state fork), and a
-    // zero radius draws at the literal default.
+    // Out of range forces radius 0.0, which draws at the default.
     let radius = if acceptable {
         let level = self_store
             .single()
@@ -144,9 +121,8 @@ pub(super) fn update_reticle(
         state.verts.clear();
         state.key = key;
         state.acceptable = acceptable;
-        // Axis-aligned box (no rotation term), the fixed ±2.0 vertical slab, box → [0,1]² UVs
-        // (the ref's 0.5 UV bias is exactly this center mapping). Vertical fade mirrors the
-        // ring's treatment so a draped wall piece dims instead of smearing at full strength.
+        // Box to [0,1]² UVs, the reference's 0.5 UV bias. The vertical fade is the ring's, so a
+        // draped wall piece dims rather than smears.
         let frame = DecalFrame {
             center: point,
             sin: 0.0,
@@ -168,9 +144,8 @@ pub(super) fn update_reticle(
     state.shown = !state.verts.is_empty();
 }
 
-/// Push the shown reticle onto the effect stream — vertex colour white (the ref writes
-/// `0xffffffff`; the state picks the TEXTURE), standard alpha blend (the ref's GxRs blend-mode
-/// 2), fog off, at the ring's decal rung.
+/// Pushes the shown reticle onto the effect stream: vertex colour `0xffffffff`, alpha blend (the
+/// reference's blend mode 2), no fog.
 pub(super) fn push_reticle(
     assets: Option<Res<ReticleAssets>>,
     state: Option<Res<ReticleState>>,
@@ -192,10 +167,7 @@ pub(super) fn push_reticle(
     let mut batch = draw
         .batch(cam, texture)
         .anchored(state.key.center)
-        // Sort rung from the pre-water decal band — the reference draws this pass at `0x4836c5`
-        // with flags `0x200122`, before the water (B347); its liquid-receiver twin at `0x483727`
-        // is the half that draws after it, and has no counterpart here until liquid becomes a
-        // receiving surface. Raster margin from the family's shared coplanarity constant.
+        // The pre-water decal band, the reference's pass at `0x4836c5` (flags `0x200122`).
         .rung(
             benilla_world::sky_order::Rung::RETICLE,
             benilla_world::sky_order::Rung::DECAL_RASTER,
@@ -216,14 +188,8 @@ mod tests {
     use benilla_world::collision::GroundDecalSurface;
     use bevy::ecs::system::RunSystemOnce;
 
-    /// **`0x4820f0`'s second guard** (decision 0943). One armed cursor, three seams, one decal:
-    /// only a word that answers `TargetingWantsLocation`'s `& 0x60` may draw. Before this, the
-    /// reticle asked `IsTargeting` alone, so arming Pick Lock (`0x4000`), Opening (`0x4800`) or an
-    /// enchant (`0x0010`) dropped a green AoE circle on the ground under a cursor whose click is a
-    /// hover-pick — director-reported, and true of the item seam since 0928.
-    ///
-    /// The ground is a real trimesh so "nothing drawn" is a verdict and not an empty scene: the
-    /// same fixture with a DEST word must draw, or this test proves nothing.
+    /// `0x4820f0`'s second guard. The ground is a real trimesh, so a DEST word draws and "nothing
+    /// drawn" is a verdict, not an empty scene.
     #[test]
     fn only_a_location_word_draws_a_decal() {
         let drawn_for = |word: u16| {
@@ -238,8 +204,8 @@ mod tests {
             world
                 .resource_mut::<SpellTargeting>()
                 .enter(2120, CastCommit::Spell, word);
-            // A flat 100×100 yd ground quad at y = 0, world-space verts (the marked colliders'
-            // identity-pose contract) — inside the ±2.0 slab and wide enough for any radius.
+            // A flat 100×100 yd quad at y = 0 in world space (the marked colliders' identity-pose
+            // contract), inside the ±2.0 slab and wider than any radius.
             let q = 50.0;
             world.spawn((
                 GroundDecalSurface,
@@ -257,11 +223,11 @@ mod tests {
             world.resource::<ReticleState>().shown
         };
 
-        // Blizzard's bare DEST word — the seam the decal belongs to.
+        // Blizzard's bare DEST word.
         assert!(drawn_for(0x0040), "a DEST word draws its reticle");
         // SOURCE|DEST is still `& 0x60`.
         assert!(drawn_for(0x0060), "a SOURCE|DEST word draws its reticle");
-        // The three words the director saw a grenade circle under.
+        // Lock, Opening (lock and GameObject), item and GameObject words.
         for word in [0x4000, 0x4800, 0x0010, 0x0800] {
             assert!(
                 !drawn_for(word),
diff --git a/crates/benilla-app/src/target/ring.rs b/crates/benilla-app/src/target/ring.rs
index 875ac64d..2780d2a2 100644
--- a/crates/benilla-app/src/target/ring.rs
+++ b/crates/benilla-app/src/target/ring.rs
@@ -1,42 +1,8 @@
-//! The ground selection ring — a projected decal under the current target, reaction-coloured.
-//!
-//! **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
-//! the reference, and passes *under* props. (A Bevy `ForwardDecal` was rejected: it distorts at
-//! WoW's steep camera angle and its depth-prepass broke clutter. An earlier per-vertex height-probe
-//! grid was replaced by this — a height field can't represent ledge faces and spiked on them.)
-//!
-//! **Texture + blend**: the reference's own `UnitSelectTexture.blp`, additive, **not** pulsed (the
-//! reference's pulsing circle is a separate spell/AoE indicator). The baked alpha fade (bright arc,
-//! fading tail) is oriented **camera-relative** each frame ([`ring_fade_angle`]): the bright arc
-//! faces the viewer, the fade points away — the reference decal's behaviour (its projector
-//! transform is camera-fed).
-//!
-//! **Colour: the ring's own selector** (`CGUnit::GetSelectionCircleColor` `0x605960`, trace + byte
-//! verified — NOT the nameplate palette): players branch to pale blue / hostile red; NPCs to
-//! dead-gray or the reaction-rank palette (red / orange / yellow / green) — see
-//! [`RingMaterials::pick`]. The reaction rank resolves in the client's own order
-//! ([`ring_reaction`]): **reputation rank first** (a reputation faction's NPCs colour by our
-//! 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: 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 (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
-//! triangle pulse) — is live: [`super::CombatFlash`] carries the frame's verdict + colour and
-//! outranks every branch below (player/dead/reaction), the byte order. The player path's party
-//! legs are live (0434 phase 6 — pale blue / pale green off the roster). Deferred selector
-//! states: the full PvP attackability matrix (X/Y), forced reactions, contested-guard.
+//! The ground selection ring under the current target: the reference's `UnitSelectTexture.blp`
+//! projected onto the terrain and WMO faces in its box, never doodads or GameObjects (`0x6723b0`,
+//! flags `0x200122`), additive, steady and at full brightness from the instant of selection, its
+//! bright arc toward the camera. The vertical fade on wall and ledge pieces is matched to
+//! captures: the reference's edge-fade ramp (`0x6147f0`) is untraced.
 
 use benilla_formats::{load_faction_catalog, reputation_rank, FactionCatalog, Reaction};
 use benilla_protocol::EntityKind;
@@ -52,20 +18,17 @@ use super::{CombatFlash, Selection, SelectionRadius};
 use crate::creature_anim::Engaged;
 use benilla_world::view::WorldCamera;
 
-/// The single ring record (a resource since 0733 — the projection rides the effect stream; no
-/// entity, no mesh, no materials). `update_ring` rebuilds `verts` when the [`RingKey`] moves and
-/// re-resolves `color` every frame; `push_ring` copies the slice onto the stream tinted.
+/// The ring record: `verts` is rebuilt when the [`RingKey`] changes, `color` every frame.
 #[derive(Resource, Default)]
 pub(super) struct RingState {
     verts: Vec<EffectVertex>,
     key: RingKey,
-    /// This frame's resolved tint (the selector's dword — or the combat flash's wave sample).
+    /// This frame's tint: the selector's colour or the combat flash's.
     color: Color,
     shown: bool,
 }
 
-/// The projection's rebuild inputs — a still target under a still camera costs a compare
-/// (0733 §5, the ShadowKey treatment; the old path re-projected every shown frame).
+/// The projection's inputs; while they hold still, the cached projection is reused.
 #[derive(Default, PartialEq, Clone, Copy)]
 struct RingKey {
     feet: Vec3,
@@ -74,36 +37,21 @@ struct RingKey {
     surfaces: usize,
 }
 
-/// The ring texture (the render-side residency gate withholds the draw until it loads).
+/// The ring texture; the draw waits until it loads.
 #[derive(Resource)]
 pub(super) struct RingAssets {
     texture: Handle<Image>,
 }
 
-/// The reference's ground selection-circle texture (`Textures\UnitSelectTexture.blp`, loaded at
-/// `0x6146d0`) — a white ring, sampled top-down, tinted + additively blended below.
+/// The reference's selection-circle texture, loaded at `0x6146d0`: a white ring, tinted per vertex.
 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.
+/// Ring radius for a unit with no model: the reference's degenerate-box answer, 1.2 (`0x60aee0`).
 const RING_FALLBACK_RADIUS: f32 = benilla_formats::DEGENERATE_RING_FOOTPRINT;
-/// 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
-/// **`0xFF6060FF`** (96,96,255), not the nameplate's pure blue. NPC branch indexes the raw reaction
-/// rank: 0–1 red `0xFFFF0000`, **2 unfriendly orange `0xFFFF8000`**, 3 neutral yellow `0xFFFFFF00`,
-/// 4–7 friendly green `0xFF00FF00`; a **dead NPC** overrides to mid-gray `0xFF7F7F7F` (players skip
-/// the health check). Tints draw at full strength (an earlier ×0.5 theory was refuted by pixels).
-/// The selector's first-priority branch — the combat flash (`0xFFFF0000↔0xFFFF8000` pulse) — is
-/// live via [`super::CombatFlash`] and outranks all of these. The player path's `¬X∧¬Y` leg is
-/// live (0434 phase 6): PvP-flagged → green `0xFF00FF00` (party member → pale-green
-/// `0xFFAAFFAA`), unflagged → the soft blue (party member → pale-blue `0xFFAAAAFF`, the
-/// selector's 4-slot party-guid table `0xbc6f48` = our roster). Still deferred: the
-/// cross-faction attackability matrix X/Y (approximated as hostile-red on rank ≤ 1) and the
-/// CHARMEDBY/SUMMONEDBY owner resolve inside the PvP-flag read (we read the unit's own flag).
-// GAMMA LANE (0161): raw authored bytes into the gamma framebuffer (see nameplates.rs).
+/// The selector's own palette (`0x605960`), not the nameplate's, written as each decal vertex's
+/// diffuse: NPCs by reaction rank 0-1 red, 2 orange `0xFFFF8000`, 3 yellow, 4-7 green, dead gray
+/// `0xFF7F7F7F`; players soft blue `0xFF6060FF` or, PvP-flagged, green; party members (the table
+/// `0xbc6f48`) pale blue `0xFFAAAAFF` or pale green `0xFFAAFFAA`.
+// `linear_rgb` passes the authored bytes raw: the framebuffer is gamma-encoded.
 const RING_HOSTILE: Color = Color::linear_rgb(1.0, 0.0, 0.0);
 const RING_UNFRIENDLY: Color = Color::linear_rgb(1.0, 0.502, 0.0);
 const RING_NEUTRAL: Color = Color::linear_rgb(1.0, 1.0, 0.0);
@@ -113,36 +61,25 @@ const RING_DEAD: Color = Color::linear_rgb(0.498, 0.498, 0.498);
 const RING_PARTY: Color = Color::linear_rgb(0.667, 0.667, 1.0); // 0xFFAAAAFF
 const RING_PARTY_PVP: Color = Color::linear_rgb(0.667, 1.0, 0.667); // 0xFFAAFFAA
 
-/// The FactionTemplate.dbc catalog, for the ring's reaction colour. Absent if the DBC failed to load
-/// (the ring then stays the neutral fallback).
+/// The FactionTemplate.dbc catalog; absent if it failed to load, and the faction legs then read
+/// neutral.
 #[derive(Resource)]
 pub(crate) struct Factions(FactionCatalog);
 
 impl Factions {
-    /// The loaded catalog — for sibling faction consumers (the zone PvP state reads our own
-    /// template's group mask through it, decision 0287).
     pub(crate) fn catalog(&self) -> &FactionCatalog {
         &self.0
     }
 
-    /// Wrap a catalog — **tests only**. A sibling module exercising a reaction gate needs a real
-    /// `Factions` in its world, and the field stays private otherwise: in a running client the
-    /// resource is built exactly once, from the DBC, by the loader below.
+    /// Wrap a catalog, for tests; a running client builds the resource once, from the DBC.
     #[cfg(test)]
     pub(crate) fn from_catalog(catalog: FactionCatalog) -> Self {
         Self(catalog)
     }
 }
 
-/// The colour `GetSelectionCircleColor` resolves — the pure classification half of the
-/// selector, split out so the branch logic (players vs NPCs, the `¬X∧¬Y` party split) is
-/// unit-testable.
-///
-/// **This is the single source for BOTH surfaces the selector feeds** — the ground ring here and
-/// the overhead name (`nameplates.rs` fetches the same `vtable+0x2c`, decision 0156). It was a
-/// duplicated mirror until decision 0659: the ring gained the PvP/party legs with 0453 and the
-/// name's copy did not, so a flagged player drew a green ring under a blue name. One law, one
-/// function; the name maps this to its own material cache.
+/// The colour class `GetSelectionCircleColor` resolves, shared by the ground ring and the overhead
+/// name, which both read the selector (`vtable+0x2c`).
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub(crate) enum RingVariant {
     Hostile,
@@ -156,7 +93,6 @@ pub(crate) enum RingVariant {
 }
 
 impl RingVariant {
-    /// Every variant, for a consumer that pre-builds one material per colour.
     pub(crate) const ALL: [Self; 8] = [
         Self::Hostile,
         Self::Unfriendly,
@@ -168,7 +104,6 @@ impl RingVariant {
         Self::PartyPvp,
     ];
 
-    /// The selector's dword for this variant (see the palette constants above).
     pub(crate) fn color(self) -> Color {
         match self {
             Self::Hostile => RING_HOSTILE,
@@ -183,14 +118,11 @@ impl RingVariant {
     }
 }
 
-/// The ring's own colour selector (`0x605960`) on the raw reaction rank (`0..=7`): **players**
-/// branch first and never check health (a dead player doesn't gray) — hostile red on rank ≤ 1
-/// (the X/Y matrix approximation), else the `¬X∧¬Y` split: PvP-flagged → green / party
-/// pale-green, unflagged → soft blue / party pale-blue (the 4-slot party table `0xbc6f48`, our
-/// roster — self is never in it, and self reads blue/green exactly like the law's own-guid legs);
-/// **NPCs** — dead → gray, else the rank palette (0–1 red, 2 orange, 3 yellow, 4–7 green).
-///
-/// Shared with the overhead name (decision 0659) — see [`RingVariant`].
+/// The selector's branch (`0x605960`) on the raw reaction rank `0..=7`. A player never grays: rank
+/// 0-1 reads red, standing in for the reference's attackability matrix, else green when PvP-flagged
+/// and blue when not, paler for a party member; self is not in the party table. An NPC reads gray
+/// when dead, else the rank palette. The reference takes the player branch on `UNIT_FIELD_FLAGS`
+/// bit 3 (`0x605baa`), which a player's pet carries too; callers pass the object type.
 pub(crate) fn ring_variant(
     rank: u8,
     is_player: bool,
@@ -224,18 +156,14 @@ pub(crate) fn ring_variant(
     }
 }
 
-/// Load the ring texture and seed the ring record. (The old path built 9 tinted
-/// `StandardMaterial` clones and a mesh asset here; the tint is per-vertex colour at push time
-/// now — the reference writes the selector's dword as every decal vertex's diffuse, which is
-/// exactly what the stream does.)
+/// Load the ring texture and seed the ring record.
 pub(super) fn setup_ring(mut commands: Commands, asset_server: Res<AssetServer>) {
     let texture = asset_server.load::<Image>(RING_TEXTURE);
     commands.insert_resource(RingAssets { texture });
     commands.init_resource::<RingState>();
 }
 
-/// Startup (after the MPQ chain opens): load FactionTemplate.dbc for the reaction colour. On failure
-/// the resource is simply absent and the ring stays neutral yellow.
+/// Load FactionTemplate.dbc once the MPQ chain is open; on failure the resource stays absent.
 pub(super) fn load_factions(mut commands: Commands, world_assets: Option<Res<WorldAssets>>) {
     let Some(world_assets) = world_assets else {
         return;
@@ -250,15 +178,9 @@ pub(super) fn load_factions(mut commands: Commands, world_assets: Option<Res<Wor
     }
 }
 
-/// Position, size, colour + show the ring under the current target each frame; hide it when nothing is
-/// selected. Radius = the unit's model ring footprint ([`SelectionRadius`], the Stand-box
-/// `sqrt(0.5·sqrt(dx²+dy²))`, or 1.2 for a degenerate box) × its transform scale
-/// (`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 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.
+/// Place, size and colour the ring under the current target, or hide it: radius the model's ring
+/// footprint ([`SelectionRadius`]) times its scale, colour resolved every frame as faction can
+/// change live.
 #[allow(clippy::type_complexity)]
 pub(super) fn update_ring(
     mut selection: ResMut<Selection>,
@@ -268,31 +190,17 @@ pub(super) fn update_ring(
     mut state: ResMut<RingState>,
     camera: Query<&GlobalTransform, With<WorldCamera>>,
     decals: WorldDecal,
-    // The last camera-relative fade angle, kept across frames so a degenerate (straight-down) camera
-    // holds the previous orientation instead of snapping.
+    // Kept so a straight-down camera holds the last fade angle.
     mut fade_angle: Local<f32>,
-    // The last guid whose colour decision was logged (log once per target change, not per frame).
     mut logged_guid: Local<Option<u64>>,
-    // Last frame's (target guid, dead?) — the alive→dead edge on the *same* unit clears the
-    // selection. Tracked per frame keyed on the guid, never armed only at selection *change*: a
-    // `.respawn`ed creature reuses its spawn guid, so change-armed state goes stale and misses the
-    // second kill (the bug this replaces).
+    // Last frame's (guid, dead), tracked every frame: a respawned creature reuses its guid, so
+    // state armed only on a selection change would miss its second death.
     mut last_vitals: Local<Option<(u64, bool)>>,
     mut seam: crate::creature_anim::AttackSeam,
-    // Net entities are roots, so their `Transform` is already world-space + current this frame
-    // (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 (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.
+    // Net entities are roots, so `Transform` is this frame's world position. `.0` filters on
+    // `Guid`, which a torn-down unit sheds at the teardown while its model fades on. `.1` gives a
+    // mounted target the mount model's footprint at its rendered scale, as the reference's ring
+    // cache (`+0xcf0`) recomputes from the mount (`0x60ce70` → `0x60aee0`).
     targets: (
         Query<
             (
@@ -305,34 +213,24 @@ pub(super) fn update_ring(
             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).
+        // The party roster: the selector's party table `0xbc6f48`.
         Res<crate::ui_party::GroupState>,
     ),
     self_store: Query<&ObjectStore, With<SelfPlayer>>,
-    // Are *we* mid auto-attack (server-echoed [`Engaged`])? Both clear paths below end the swing
-    // then — the reference's death/teardown edges stop the attack along with the selection.
+    // Our auto-attack; both clear paths end it, as the reference's death and teardown edges do.
     engaged: Query<(), (With<Engaged>, With<SelfPlayer>)>,
 ) {
     let state = &mut *state;
     let hide = match selection.target {
         None => {
-            // No target: drop the per-target trackers, so re-selecting the *same* guid later is a
-            // fresh start (vitals re-read, colour decision re-logged).
             *last_vitals = None;
             *logged_guid = None;
             true
         }
         Some(target) => match targets.0.get(target) {
             Ok((unit, sel_radius, store, net, mount_child)) => {
-                // A real model uses its own footprint, whatever it measures; only a model-less unit
-                // falls back. **No floor** — the reference has none, and the one we used to keep
-                // (0.05) is what a zero-bounds model landed on: `ring_footprint` now carries the
-                // writer's own degenerate-box answer (1.2) instead of a 0 for the picker to clamp,
-                // so the Naxxramas weapon mobs ring at 1.2 × 2.25 ≈ 2.7 yd like the reference and
-                // not at a coin's width (decision 1658).
-                // Mounted, the footprint and the extra scale column come from the mount child
-                // (the `mount_parts` doc above); a still-loading mount rides the fallback the
-                // way any model-less unit does until its bounds land.
+                // The footprint has no floor, as in the reference: a zero-bounds model already
+                // measures the degenerate-box 1.2.
                 let (local, mount_scale) = match mount_child.and_then(|mc| targets.1.get(mc.0).ok())
                 {
                     Some((mnet, msel)) => (msel.map_or(RING_FALLBACK_RADIUS, |r| r.0), mnet.scale),
@@ -340,8 +238,6 @@ pub(super) fn update_ring(
                 };
                 let radius = local * (unit.scale.x * mount_scale).max(0.01);
                 *fade_angle = ring_fade_angle(&camera).unwrap_or(*fade_angle);
-                // The rebuild gate (0733 §5): a still target under a still camera keeps the
-                // cached projection — the old path re-projected every shown frame.
                 let key = RingKey {
                     feet: unit.translation,
                     radius,
@@ -364,24 +260,16 @@ pub(super) fn update_ring(
                     self_store.single().ok(),
                 );
                 let is_player = net.is_some_and(|n| n.kind == EntityKind::Player);
-                // The ¬X∧¬Y split's inputs: the unit's own PvP flag (UNIT_FIELD_FLAGS 0x1000;
-                // the charm-owner resolve is noted residue) + roster membership by guid.
+                // The unit's own PvP flag (`0x1000`); the reference reads its charmer's or
+                // summoner's when it has one.
                 let pvp = store.is_some_and(|s| s.0.unit_flags() & 0x1000 != 0);
                 let in_party = selection
                     .guid
                     .is_some_and(|g| targets.2.members.iter().any(|m| m.guid == g));
-                // Dead (health 0, absent-counts-as-zero — `unit_is_dead`) — re-read each frame, so
-                // the ring reacts the moment the kill's health delta merges into the store, and an
-                // 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: 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
-                // reference: deliberately selecting a corpse afterwards stays valid (gray ring).
-                // (The same edge also stops auto-attack and cancels a cast at the dying unit —
-                // faithful siblings for when combat/casting exist.)
+                // The alive-to-dead edge clears the target, as the reference's health handler does
+                // (`0x6046f0` fires `0x605860`, which sends `CMSG_SET_SELECTION 0`); a corpse
+                // selected afterwards stays selected, gray.
                 let died = is_dead
                     && selection
                         .guid
@@ -394,8 +282,6 @@ pub(super) fn update_ring(
                     state.verts.clear();
                     return;
                 }
-                // One line per target change — the whole colour decision, so a wrong ring colour in
-                // the field is diagnosable from the log instead of guessed at.
                 if selection.guid != *logged_guid {
                     *logged_guid = selection.guid;
                     info!(
@@ -410,25 +296,18 @@ pub(super) fn update_ring(
                         if is_dead { " [dead→gray]" } else { "" },
                     );
                 }
-                // The selector's first-priority branch (`0x605960`, byte order): the combat
-                // flash outranks player/dead/reaction. The tint is a per-vertex colour at push
-                // time now, so the flash's per-frame wave sample costs a resource write — the
-                // old path's one material mutation is gone.
+                // The combat flash, the selector's first branch (`0x605960`), outranks the rest.
                 state.color = if flash.unit == Some(target) {
                     flash.color
                 } else {
                     ring_variant(rank, is_player, is_dead, pvp, in_party).color()
                 };
-                // No receiving surface in the box (mid-air, unstreamed tile) → hide, the reference's
-                // own no-ground gate (`0x6d74b5`: the whole draw is skipped).
+                // No ground in the box hides the ring: the reference skips the draw (`0x6d74b5`).
                 !projected
             }
-            // 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).
+            // No longer an object: clear and tell the server, as the reference's deactivate does on
+            // both removal paths (`0x5fbb60` → `0x493910`). This also drops a selected corpse at
+            // respawn, which the server destroys before the fresh create.
             Err(_) => {
                 clear(&mut selection, &mut seam, !engaged.is_empty());
                 *last_vitals = None;
@@ -443,15 +322,10 @@ pub(super) fn update_ring(
     }
 }
 
-/// The ring fade's camera-relative angle θ: the texture's **faded side always points away from the
-/// camera** (the bright arc faces the viewer — the reference decal's behaviour, director-confirmed;
-/// its projector transform is camera-fed). The fade is baked into `UnitSelectTexture.blp`'s alpha
-/// (bright at v=1 → ring-local **+Z**, transparent at v=0 → **−Z**, measured off the shipped
-/// texture); [`project_ring`] rotates each vertex's UV by −θ, which is equivalent to yawing the
-/// texture square by θ so its −Z side lands on the camera's ground-projected forward
-/// (a yaw θ maps a local `atan2(z,x)` angle φ to `φ − θ`; local −Z sits at −π/2; so
-/// `θ = −π/2 − atan2(f.z, f.x)`). `None` looking straight down (degenerate forward) — the caller
-/// keeps the previous angle rather than snapping to an arbitrary one.
+/// The fade's camera-relative angle θ, turning the texture's faded side away from the camera as
+/// the reference's camera-fed projector does. The texture is bright toward ring-local +Z and clear
+/// toward −Z, and [`project_ring`] rotates the UVs by −θ, so `θ = −π/2 − atan2(f.z, f.x)` for the
+/// camera's ground-projected forward `f`. `None` looking straight down.
 fn ring_fade_angle(camera: &Query<&GlobalTransform, With<WorldCamera>>) -> Option<f32> {
     let cam = camera.single().ok()?;
     let f = cam.forward();
@@ -462,20 +336,10 @@ 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 (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 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
-/// (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.
+/// Project the ring through the reference's decal projector (`0x6d7330` → `0x6d6fa0` →
+/// `0x6d7480`): the box is the texture square, yawed by the fade angle, reaching two radii up and
+/// down (`0x608e00`). Vertex alpha is full within half a radius of the feet and falls to 0 at the
+/// box's top and bottom. False when nothing is gathered.
 fn project_ring(
     out: &mut Vec<EffectVertex>,
     decals: &WorldDecal<'_, '_>,
@@ -504,8 +368,7 @@ fn project_ring(
     )
 }
 
-/// Push the shown ring's cached projection onto the stream, tinted with this frame's resolved
-/// colour — one Add draw at the ring rung (the top decal, over the blob shadows), fog off.
+/// Draw the cached projection tinted, one additive draw on the ring rung above the blob shadows.
 pub(super) fn push_ring(
     assets: Option<Res<RingAssets>>,
     state: Option<Res<RingState>>,
@@ -531,45 +394,19 @@ pub(super) fn push_ring(
     batch.extend(state.verts.iter().map(|v| EffectVertex {
         pos: v.pos,
         uv: v.uv,
-        // The selector's dword as every vertex's diffuse — the reference's own wiring
-        // (`0x605960` → vertex colour, alpha = the vertical fade the projector baked).
+        // The selector's colour as each vertex's diffuse, as in the reference; alpha is the fade.
         color: [tint.red, tint.green, tint.blue, v.color[3]],
     }));
     batch.tris();
 }
 
-/// The target's reaction toward our player — the direction the reference colours by (its nameplate/ring
-/// resolver `0x7cbaa0` calls `unit->UnitReaction(activePlayer)`, byte-verified; the reverse would read
-/// every attackable-but-passive yellow beast as hostile red, since a *player* template is enemy-masked
-/// against the whole Monster group), resolved in the client's own order (`0x606530`):
-///
-/// **First reputation, then the comparator.** If the unit's faction *has a reputation slot*
-/// (`FactionHasReputation` `0x605fc0`), the reaction is **our reputation rank** with it
-/// (`0x4d63a0`): DBC race/class base + the `SMSG_INITIALIZE_FACTIONS` standing, ranked
-/// hated→exalted — *before* any template comparison, which is why every Stormwind NPC is green to a
-/// human (base 4000 = friendly) **even in GM mode** (director-verified on the reference: the GM
-/// faction template never gets consulted for reputation-faction NPCs). Only a reputation-less
-/// faction falls through to the faction-template comparator (byte-exact `0x606640`) over both
-/// units' `UNIT_FIELD_FACTIONTEMPLATE`.
-///
-/// **Before either of those, the duel leg** (decision 0633, byte-exact `UnitReaction 0x6061e0`).
-/// The real function runs a player-vs-player ladder *ahead of* the faction work, gated on
-/// `UNIT_FIELD_FLAGS` bit 3 (`0x8` `UNIT_FLAG_PVP_ATTACKABLE`, behaviourally "player-controlled")
-/// being set on **both** parties. Its first rung is the duel ([`duel_reaction`]): when both
-/// players carry a non-zero `PLAYER_DUEL_TEAM` **and** the same `PLAYER_DUEL_ARBITER`, the answer
-/// is `1` (hostile) for opposing teams and `4` (friendly) for the same team — `0x606296`'s
-/// `setne/dec/and 3/inc`, which maps *equal* → 4 and *unequal* → 1. That is the whole reason a
-/// duel opponent turns red, becomes attackable, and takes the combat flash without any of those
-/// systems knowing what a duel is. The ladder's later rungs — the party leg (`0x6062b0`) and the
-/// both-FFA leg (`0x60632c`) — are NOT implemented here: party colouring already runs through
-/// [`ring_variant`]'s own split, and FFA waits for PvP. Both are strictly *below* the duel rung,
-/// so their absence cannot change a duel's answer.
-///
-/// Deferred pieces of the real orchestration: contested-guard flag, forced reactions
-/// (`SMSG_SET_FORCED_REACTIONS`), and the summon +1 tail. Returns the **raw reaction rank**
-/// (`0..=7` — the scale the ring palette indexes: 0–1 red, 2 orange, 3 yellow, 4–7 green); the
-/// comparator's `{1, 3, 4}` sit on the same scale. **3 (neutral)** when anything is missing (no
-/// catalog, fields not yet streamed) — the reference resolver's own fall-through is the yellow branch.
+/// The target's reaction toward our player as a raw rank `0..=7`, the direction every NPC colour
+/// uses (`0x605960` and `0x7cbaa0` ask `UnitReaction 0x6061e0` with the unit as `this`). When
+/// both carry `UNIT_FIELD_FLAGS` bit 3, a duel (`0x606296`) or mutual FFA decides first. Then
+/// `0x606530`: a faction with a reputation slot (`0x605fc0`) answers with our reputation rank
+/// (`0x4d63a0`), even in GM mode; any other goes to the template comparator (`0x606640`). Neutral
+/// when anything is missing. Not applied: the party rung (`0x6062b0`), the contested guard,
+/// forced reactions and the summon tail.
 pub(crate) fn ring_reaction(
     factions: Option<&Factions>,
     reputations: &Reputations,
@@ -588,7 +425,7 @@ pub(crate) fn ring_reaction(
         let catalog = &factions?.0;
         let self_store = self_store?;
         let target_tpl = catalog.template(target_store?.0.unit_faction_template()?)?;
-        // 1. The reputation branch: rank with the unit's faction, when it has a reputation slot.
+        // A reputation faction: our rank with it.
         if let Some(info) = catalog.reputation_faction(target_tpl.faction) {
             let standing = reputations
                 .0
@@ -598,29 +435,22 @@ pub(crate) fn ring_reaction(
             let class = self_store.0.unit_class().unwrap_or(0);
             return Some(reputation_rank(info.base_for(race, class) + standing));
         }
-        // 2. The faction-template comparator ({1, 3, 4} on the rank scale).
+        // The template comparator: 1, 3 or 4 on the rank scale.
         let self_tpl = catalog.template(self_store.0.unit_faction_template()?)?;
         Some(target_tpl.reaction_toward(self_tpl) as u8)
     })();
     resolved.unwrap_or(Reaction::Neutral as u8)
 }
 
-/// `UNIT_FLAG_PVP_ATTACKABLE` — `UNIT_FIELD_FLAGS` bit 3. Behaviourally "player-controlled": the
-/// local player and other players carry it, wild creatures do not. `UnitReaction 0x606217`/
-/// `0x60622f` requires it on both parties before any player-vs-player rung runs, and `CanAttack
-/// 0x606a13` selects its three reaction legs on the same bit.
+/// `UNIT_FIELD_FLAGS` bit 3, player-controlled in behaviour: players and their pets carry it, wild
+/// creatures do not. `UnitReaction` needs it on both sides before any player-vs-player rung
+/// (`0x606217`, `0x60622f`), and `CanAttack` picks its reaction arm by it (`0x606a13`).
 const UNIT_FLAG_PVP_ATTACKABLE: u32 = 1 << 3;
 
-/// The duel rung of `UnitReaction` (`0x60626b`–`0x6062ad`, byte-exact). `Some(1)` when the two
-/// are duelling each other on **opposing** teams, `Some(4)` on the same team (the client's own
-/// arithmetic; only pets ever land there), `None` when no duel relates them — the caller then
-/// falls through to the faction work.
-///
-/// The gate is deliberately all three facts and not the arbiter alone: `PLAYER_DUEL_ARBITER` is
-/// set on both players the moment the challenge goes out, while `PLAYER_DUEL_TEAM` stays `0`
-/// until `Player::UpdateDuelFlag` fires at the end of the countdown. Testing only the arbiter
-/// would turn the opponent red during the popup and the 3-second count — before a blow may
-/// legally land.
+/// The duel rung of `UnitReaction` (`0x60626b`–`0x6062ad`): hostile (1) between opposing teams,
+/// friendly (4) on one team, `None` when no duel relates the two. It needs team and arbiter both:
+/// `PLAYER_DUEL_ARBITER` is set at the challenge, `PLAYER_DUEL_TEAM` only when the countdown ends
+/// (`Player::UpdateDuelFlag`), so the arbiter alone would turn the opponent red during the count.
 fn duel_reaction(
     target: &benilla_protocol::ObjectFields,
     own: &benilla_protocol::ObjectFields,
@@ -631,14 +461,9 @@ fn duel_reaction(
     }
 }
 
-/// The **both-FFA** rung of `UnitReaction` (`0x60632c`, the ladder 0633 §5 read in full; decision
-/// 0646 §5): two player-controlled units that are BOTH free-for-all flagged are hostile to each
-/// other, whatever their factions say. This is the only rung an ordinary PvP flag does *not* have
-/// — a same-faction player who flags for PvP stays friendly, which is why there is no `pvp` arm
-/// beside this one.
-///
-/// The flag is `PLAYER_FLAGS` bit 7 (`PLAYER_FLAGS_FFA_PVP`, vmangos `Player.h:322`), the same
-/// field and bit the unit snapshot feeds `UnitIsPVPFreeForAll` from.
+/// The both-FFA rung of `UnitReaction` (`0x60632c`): two player-controlled units both flagged
+/// free-for-all (`PLAYER_FLAGS` bit 7, vmangos `Player.h:322`) are hostile whatever their factions.
+/// A plain PvP flag has no such rung: a same-faction player flagged for PvP stays friendly.
 fn ffa_reaction(
     target: &benilla_protocol::ObjectFields,
     own: &benilla_protocol::ObjectFields,
@@ -652,49 +477,28 @@ fn ffa_reaction(
         && own.player_flags() & PLAYER_FLAGS_FFA_PVP != 0
 }
 
-/// `UNIT_FIELD_FLAGS` bits `CanAttack` (`0x606980`) tests on its TARGET, any one of which refuses
-/// 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`.
+/// Target `UNIT_FIELD_FLAGS` bits, any one of which makes `CanAttack` refuse
+/// (`0x6069b7`–`0x6069ff`); their vanilla names are unconfirmed, so none is used.
 const CANNOT_BE_ATTACKED: u32 = 0x2 | 0x80 | 0x1_0000 | 0x10_0000 | 0x200_0000;
-/// The two cross-flag immunity bits `CanAttack` reads on BOTH sides (`0x606a05`–`0x606a8a`): bit 8
-/// `0x100` and bit 9 `0x200`, each paired against the other unit's `PLAYER_CONTROLLED` bit 3.
+/// The cross-flag immunity bits `CanAttack` reads on both sides (`0x606a05`–`0x606a8a`), each
+/// against the other unit's bit 3.
 const IMMUNE_TO_PLAYER_CONTROLLED: u32 = 0x100;
 const IMMUNE_TO_UNCONTROLLED: u32 = 0x200;
-/// `UNIT_FIELD_FLAGS` bit 12 (`0x1000`) — the PvP-flag the both-players arm of `CanAttack` accepts
-/// on its target (`0x606b5c`).
+/// The PvP flag, which `CanAttack`'s player-vs-player arm accepts on its target (`0x606b5c`).
 const UNIT_FLAG_PVP: u32 = 0x1000;
 
-/// 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:
-///
-/// - **This direction** (`A` = the local player) always reaches leg 3 at `0x606372`, because
-///   `0x606170(localPlayer)` resolves to the player themselves. Leg 3 answers a rep-slot faction
-///   with the **AT-WAR BIT** — `at_war ? 1 : 4` — and never looks at the standing. Only a
-///   faction with no reputation slot falls through to the template comparator.
-/// - **[`ring_reaction`]'s direction** (`A` = the unit) never reaches leg 3, falls into `0x606530`,
-///   and *there* the standing is read. That is the correct input for the plate's bar COLOUR, the
-///   ring, and the overhead name.
-///
-/// So a not-at-war neutral-standing NPC — a Booty Bay goblin, an Argent Dawn quartermaster, a
-/// battleground emissary — is **friendly** to this function and **neutral** to the other one, and
-/// the client shows exactly that: a friendly-category plate with a yellow bar. Substituting the
-/// standing here is what put those 36 shipped faction templates in the enemy category (1530).
-///
-/// Deferred, and each one only ever makes a unit *more* friendly than we say: the forced-reaction
-/// table (`0x4d6490`, `SMSG_SET_FORCED_REACTIONS` — no wire support yet), the party rung of the
-/// player-vs-player block, and the charmed-player case that would stop leg 3 firing at all.
+/// The local player's reaction toward a unit, `0x6061e0` with the player as `this`. This direction
+/// reaches leg 3 (`0x606372`), which answers a reputation faction by the at-war bit alone, never
+/// the standing, so a not-at-war neutral NPC is friendly here and neutral to [`ring_reaction`]: a
+/// friendly-category plate with a yellow bar. Not applied, each only ever making a unit
+/// friendlier: forced reactions (`0x4d6490`), the party rung and the charmed-player case.
 pub(crate) fn reaction_from_player(
     factions: Option<&Factions>,
     reputations: &Reputations,
     target_store: Option<&ObjectStore>,
     self_store: Option<&ObjectStore>,
 ) -> u8 {
-    // The player-vs-player block (`0x606217`) sits ahead of all faction work in BOTH directions,
-    // and benilla implements the same two rungs of it here that [`ring_reaction`] does.
+    // The player-vs-player block (`0x606217`) runs first in both directions.
     if let (Some(target), Some(own)) = (target_store, self_store) {
         if let Some(rank) = duel_reaction(&target.0, &own.0) {
             return rank;
@@ -706,7 +510,7 @@ pub(crate) fn reaction_from_player(
     let resolved = (|| {
         let catalog = &factions?.0;
         let target_tpl = catalog.template(target_store?.0.unit_faction_template()?)?;
-        // Leg 3: a faction that owns a reputation slot is answered by the AT-WAR bit alone.
+        // Leg 3: a reputation faction answers by the at-war bit alone.
         if let Some(at_war) = at_war_with(catalog, reputations, target_tpl.faction) {
             return Some(if at_war {
                 Reaction::Hostile as u8
@@ -714,22 +518,16 @@ pub(crate) fn reaction_from_player(
                 Reaction::Friendly as u8
             });
         }
-        // Leg 4: no reputation slot → the template comparator, PLAYER → UNIT.
+        // Leg 4: the template comparator, player toward unit.
         let self_tpl = catalog.template(self_store?.0.unit_faction_template()?)?;
         Some(self_tpl.reaction_toward(target_tpl) as u8)
     })();
     resolved.unwrap_or(Reaction::Neutral as u8)
 }
 
-/// **Leg 3's whole content**: is the local player at war with the `Faction.dbc` id a unit's
-/// faction template names? `None` when that faction owns no reputation slot — the one case leg 3
-/// does not answer, and the reaction falls through to the template comparator.
-///
-/// `faction_flags::AT_WAR` is the same wire byte the reputation pane's war checkbox writes, which
-/// is what makes declaring war on Booty Bay turn its goblins' plates red, move them into the enemy
-/// category, and put the sword on the cursor — one bit, three consequences, as the reference has
-/// it. Shared with `/reaction`, which prints it: the bit is the cause of every "why is this
-/// friendly NPC attackable" question and it is visible nowhere else in the client.
+/// Leg 3: whether we are at war with the `Faction.dbc` faction a unit's template names; `None` when
+/// it has no reputation slot. The bit is the one the reputation pane's war checkbox writes, so
+/// declaring war moves the plate, the cursor and attackability at once. `/reaction` prints it.
 pub(crate) fn at_war_with(
     catalog: &benilla_formats::FactionCatalog,
     reputations: &Reputations,
@@ -744,35 +542,12 @@ pub(crate) fn at_war_with(
     )
 }
 
-/// `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`).
-///
-/// **This is the world cursor's service gate — not a reaction threshold** (`0x482310`, `test al,al;
-/// je 0x4824e6`): TRUE sends the hover into the `UNIT_NPC_FLAGS` service ladder, FALSE into the
-/// loot/skin/attack block. Three terms, in the binary's order:
-///
-/// 1. the unit's `UNIT_FIELD_FLAGS` **bit 25** clear (`0x606835 shr ecx,0x19`),
-/// 2. its `UNIT_NPC_FLAGS` **non-zero** (`0x60683d`) — a unit carrying no service bit at all is
-///    never interactable, whatever its reaction,
-/// 3. **both** reaction directions `>= 3` (neutral), and they are genuinely different functions:
-///    `0x606847 push esi; mov ecx,edi; call 0x6061e0` is [`ring_reaction`] (unit → player, the
-///    standing), `0x606854 push edi; mov ecx,esi; call 0x6061e0` is [`reaction_from_player`]
-///    (player → unit, the **at-war bit**). Each is `cmp eax,3; jl → 0`.
-///
-/// Term 3's second half is what makes declaring war on a faction drop its vendors out of the
-/// service ladder and into the sword — one bit, both consequences, exactly as it moves the plate
-/// category (1530).
-///
-/// **Deferred, and each can only ever make a unit *less* interactable than we say** — so none of
-/// them can manufacture a service cursor we would not already show: the `CanInteractNow 0x606880`
-/// wrapper's own gates (player `UNIT_FIELD_FLAGS` bit 20 clear @ `0x606893`, both sides'
-/// `UNIT_FIELD_CHARMEDBY` zero, player alive, the shapeshift-form clause `0x60e9f0` +
-/// `SpellShapeshiftForm` flag `0x8`, and the two unnamed unit predicates `0x613230` / `0x60ecd0`),
-/// and `0x6067f0`'s own ghost leg `0x605f70(unit)` — which term 2 already subsumes, since a ghost
-/// is a player and a player has no `UNIT_NPC_FLAGS`.
+/// `CanInteract` from the local player (`0x6067f0`), the world cursor's service gate at
+/// `0x482310`: bit 25 of `UNIT_FIELD_FLAGS` clear (`0x606835`), some `UNIT_NPC_FLAGS`
+/// (`0x60683d`), and both reactions at least neutral, [`ring_reaction`] (`0x606847`) and
+/// [`reaction_from_player`] (`0x606854`). Not applied, each only ever making a unit less
+/// interactable: the `CanInteractNow 0x606880` wrapper's gates (`0x606893`, charm, alive,
+/// shapeshift `0x60e9f0`, `0x613230`, `0x60ecd0`) and the ghost leg `0x605f70`.
 pub(crate) fn can_interact_from_player(
     factions: Option<&Factions>,
     reputations: &Reputations,
@@ -780,7 +555,7 @@ pub(crate) fn can_interact_from_player(
     self_store: Option<&ObjectStore>,
 ) -> bool {
     let Some(target) = target_store else {
-        return false; // fields not streamed yet — nothing to take a service from
+        return false; // fields not streamed yet
     };
     const UNIT_FLAG_NOT_SELECTABLE: u32 = 1 << 25;
     if target.0.unit_flags() & UNIT_FLAG_NOT_SELECTABLE != 0 || target.0.unit_npc_flags() == 0 {
@@ -791,14 +566,9 @@ 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`, 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: 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).
+/// `CanAttack` from the local player (`0x606980`), every leg in the reference's order; the V-plate
+/// category turns on it. Not a reaction threshold: an unflagged opposite-faction player on a PvE
+/// realm is hostile yet not attackable, a same-faction duel opponent friendly yet attackable.
 pub(crate) fn can_attack_from_player(
     factions: Option<&Factions>,
     reputations: &Reputations,
@@ -807,12 +577,11 @@ pub(crate) fn can_attack_from_player(
     target_is_player: bool,
 ) -> bool {
     let (Some(target), Some(own)) = (target_store, self_store) else {
-        return false; // fields not streamed yet — the reference's own null path refuses
+        return false; // fields not streamed yet; the reference's null path refuses too
     };
     let (tflags, oflags) = (target.0.unit_flags(), own.0.unit_flags());
-    // (a) The ghost gate (`0x606987`): a ghost PLAYER can only be attacked by an attacker holding a
-    // creature record whose type-flags carry `0x2` — which a player never does. So for the local
-    // player as attacker this leg is unconditional.
+    // (a) The ghost gate (`0x606987`): only a creature whose type flags carry `0x2` may attack a
+    // ghost player, so the local player never can.
     const PLAYER_FLAGS_GHOST: u32 = 0x10;
     if target_is_player && target.0.player_flags() & PLAYER_FLAGS_GHOST != 0 {
         return false;
@@ -821,8 +590,7 @@ pub(crate) fn can_attack_from_player(
     if tflags & CANNOT_BE_ATTACKED != 0 {
         return false;
     }
-    // (c) The four cross-flag immunity legs, each pairing one side's immunity bit against the
-    // other's `PLAYER_CONTROLLED`.
+    // (c) The four cross-flag immunity legs.
     let (t_controlled, o_controlled) = (
         tflags & UNIT_FLAG_PVP_ATTACKABLE != 0,
         oflags & UNIT_FLAG_PVP_ATTACKABLE != 0,
@@ -834,18 +602,17 @@ pub(crate) fn can_attack_from_player(
     {
         return false;
     }
-    // (d) The three terminal arms, selected by the two `PLAYER_CONTROLLED` bits.
+    // (d) The three terminal arms, selected by the two bit-3 flags.
     let toward_target = || reaction_from_player(factions, reputations, target_store, self_store);
     match (o_controlled, t_controlled) {
-        // Neither is player-controlled: hostile in EITHER direction is enough.
+        // Neither player-controlled: hostile in either direction suffices.
         (false, false) => {
             toward_target() <= Reaction::Hostile as u8
                 || ring_reaction(factions, reputations, target_store, self_store)
                     <= Reaction::Hostile as u8
         }
-        // Both are: the PvP arm. A friendly reaction refuses outright; past that an attack needs a
-        // live duel, the target's PvP flag, or mutual FFA. (The charm-owner resolve `0x606170` is
-        // an identity for both sides here — benilla has no charm.)
+        // Both: a friendly reaction refuses; else a live duel, the target's PvP flag or mutual
+        // FFA. The reference's charm-owner resolve (`0x606170`) is not applied.
         (true, true) => {
             if toward_target() >= Reaction::Friendly as u8 {
                 return false;
@@ -854,17 +621,13 @@ pub(crate) fn can_attack_from_player(
                 || tflags & UNIT_FLAG_PVP != 0
                 || ffa_reaction(&target.0, &own.0)
         }
-        // The mixed arm — the local player against any ordinary NPC, i.e. the case the plate gate
-        // takes for almost everything on screen: attackable iff worse than friendly.
+        // Mixed, the player against an ordinary NPC: attackable when worse than friendly.
         _ => toward_target() < Reaction::Friendly as u8,
     }
 }
 
-/// The one number `CanCooperate` turns on: a unit's `FactionTemplate` **faction-group mask**
-/// (`row + 0xc`) — 3 for every Alliance race row, 5 for every Horde one, and something else
-/// entirely for a row that is neither. Exposed for `/reaction`, which prints both sides of the
-/// comparison: when a player's plate lands in the wrong bucket this is nearly always the reason,
-/// and it is not visible anywhere else in the client.
+/// A unit's `FactionTemplate` faction-group mask (`row + 0xc`), the one number `CanCooperate`
+/// compares: 3 on every Alliance race row, 5 on every Horde one. `/reaction` prints it.
 pub(crate) fn faction_group_mask(
     factions: Option<&Factions>,
     store: Option<&ObjectStore>,
@@ -877,10 +640,8 @@ pub(crate) fn faction_group_mask(
     )
 }
 
-/// `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.
+/// `CanCooperate` from the local player (`0x606ba0`): equal faction-group masks, neither side
+/// charmed, and not the same unit; it reads no party or raid state.
 pub(crate) fn can_cooperate_with_player(
     factions: Option<&Factions>,
     target_store: Option<&ObjectStore>,
@@ -889,10 +650,7 @@ pub(crate) fn can_cooperate_with_player(
     let (Some(target), Some(own)) = (target_store, self_store) else {
         return false;
     };
-    // `606ba6 cmp B,A ; je -> 0` — the predicate's FIRST leg: a unit never cooperates with
-    // itself. The reference compares object pointers, so ours compares component identity. The
-    // plate gate can't reach it (its query is `Without<SelfPlayer>`), but the predicate is
-    // transcribed law and the leg was missing from it.
+    // The first leg: a unit never cooperates with itself (`0x606ba6` compares the objects).
     if std::ptr::eq(target, own) {
         return false;
     }
@@ -910,13 +668,9 @@ pub(crate) fn can_cooperate_with_player(
     resolved.unwrap_or(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 —
-/// > `CanAttack(localPlayer → subject)` is FALSE; and for a player subject, additionally
-/// > `CanCooperate(localPlayer → subject)` is TRUE.
+/// The V-plate category (`0x60f6b7`–`0x60f6f1`): `true` is the friendly bucket (Shift-V, bit
+/// `0x8`), `false` the enemy one (V, bit `0x1`). A unit is friendly when `CanAttack` refuses it,
+/// and a player only when `CanCooperate` also passes; no reaction rank takes part.
 pub(crate) fn plate_is_friendly(
     factions: Option<&Factions>,
     reputations: &Reputations,
@@ -938,22 +692,17 @@ pub(crate) fn plate_is_friendly(
     }
 }
 
-/// Why [`duel_reaction`]'s rung did or did not fire, with the values it judged on. This is the
-/// diagnostic face of the same walk — `/reaction` prints it, so a duel that fails to turn the
-/// opponent red names the gate that refused instead of silently reporting "neutral". Keeping one
-/// walk with a richer return (rather than a second copy in the probe) is what stops the
-/// instrument and the law from drifting apart.
+/// Why [`duel_reaction`]'s rung did or did not fire, with the values it judged; `/reaction` prints
+/// it from this same walk.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum DuelRung {
-    /// One or both sides lack `UNIT_FIELD_FLAGS` bit 3, so no player-vs-player rung runs at all.
+    /// A side lacks `UNIT_FIELD_FLAGS` bit 3, so no player-vs-player rung runs.
     NotPlayerControlled { own: bool, target: bool },
-    /// No duel under way yet: `PLAYER_DUEL_TEAM` is still `0` on one or both sides (it is set
-    /// only when `Player::UpdateDuelFlag` fires at the end of the countdown).
+    /// `PLAYER_DUEL_TEAM` is 0 on a side: no duel, or its countdown has not ended.
     NoTeam { own: u32, target: u32 },
-    /// Both carry a team, but they are not duelling **each other** — or the arbiter guid has not
-    /// streamed to us.
+    /// Both have a team but are not duelling each other, or the arbiter has not streamed.
     ArbiterMismatch { own: u64, target: u64 },
-    /// The rung fires: `1` (hostile) on opposing teams, `4` (friendly) on the same one.
+    /// The rung fires: 1 (hostile) on opposing teams, 4 (friendly) on one team.
     Engaged {
         rank: u8,
         own_team: u32,
@@ -961,7 +710,7 @@ pub(crate) enum DuelRung {
     },
 }
 
-/// The duel rung's walk, reporting the gate that decided (see [`DuelRung`]).
+/// The duel rung's walk, reporting the gate that decided.
 pub(crate) fn duel_rung(
     target: &benilla_protocol::ObjectFields,
     own: &benilla_protocol::ObjectFields,
@@ -1008,9 +757,6 @@ mod tests {
         ring_variant, Factions, RingVariant, UNIT_FLAG_PVP_ATTACKABLE,
     };
 
-    /// The selector's player path — the `¬X∧¬Y` split the party arc added (0434 phase 6). A
-    /// friendly player reads soft blue solo, pale blue in our party; PvP-flagged reads green
-    /// solo, pale green in party; hostile rank still wins for a player; a dead player never grays.
     #[test]
     fn player_ring_party_and_pvp_split() {
         let v = |pvp, in_party| ring_variant(5, true, false, pvp, in_party);
@@ -1030,17 +776,14 @@ mod tests {
             RingVariant::PartyPvp,
             "pvp party = pale green"
         );
-        // A hostile-rank player is red regardless of party/pvp (the X/Y approximation).
         assert_eq!(
             ring_variant(1, true, false, true, true),
             RingVariant::Hostile
         );
-        // Players skip the health check — a dead ally still reads its party colour, never gray.
+        // A dead player never grays.
         assert_eq!(ring_variant(5, true, true, false, true), RingVariant::Party);
     }
 
-    /// The NPC path is untouched by the party inputs: dead grays, else the reaction palette,
-    /// and pvp/in_party never apply to a non-player.
     #[test]
     fn npc_ring_ignores_party_inputs() {
         assert_eq!(ring_variant(0, false, true, true, true), RingVariant::Dead);
@@ -1058,15 +801,8 @@ mod tests {
         );
     }
 
-    /// **The plate category, end to end on the REAL build-5875 DBC — the two subjects the director
-    /// observed on the reference client** (1530), plus the leg that actually discriminates the
-    /// mechanism.
-    ///
-    /// This is the regression pin the old `rank >= 4` model could never have passed. It asserts the
-    /// *divergence itself*: the emissary's reaction rank stays 3 (neutral — which is right, and is
-    /// what paints its bar yellow) while its plate CATEGORY is friendly. A future refactor that
-    /// "simplifies" the category back into a rank threshold fails here, on real data, naming the
-    /// creature.
+    /// The emissary's rank stays neutral, which paints its bar yellow, while its plate category is
+    /// friendly: the two run the reaction in opposite directions.
     #[test]
     fn the_plate_category_reproduces_the_reference_on_the_real_dbc() {
         use crate::net::{ObjectStore, Reputations};
@@ -1077,12 +813,12 @@ mod tests {
         let factions = Factions(benilla_formats::load_faction_catalog(&mut chain).expect("dbc"));
         // Field indices: 35 = UNIT_FIELD_FACTIONTEMPLATE, 46 = UNIT_FIELD_FLAGS.
         let unit = |tpl: u32| ObjectStore(ObjectFields::from_pairs(&[(35, tpl)]));
-        // Us: faction template 1 (PLAYER, Human), carrying `PLAYER_CONTROLLED`.
+        // Us: a player-controlled Human, faction template 1.
         let me = ObjectStore(ObjectFields::from_pairs(&[
             (35, 1),
             (46, UNIT_FLAG_PVP_ATTACKABLE),
         ]));
-        let quiet = Reputations::default(); // nothing at war — the out-of-box state
+        let quiet = Reputations::default(); // nothing at war
         let category = |unit: &ObjectStore, reps: &Reputations| {
             plate_is_friendly(Some(&factions), reps, Some(unit), Some(&me), false)
         };
@@ -1090,16 +826,12 @@ mod tests {
             ring_reaction(Some(&factions), reps, Some(unit), Some(&me))
         };
 
-        // A Chicken (FT 31 → faction 28 "Prey", NO reputation slot) falls to the template
-        // comparator, which matches nothing → 3 → attackable → the ENEMY bucket, plain V. The
-        // director confirmed this on the reference: critters do plate, and nothing excludes them.
+        // A Chicken, template 31 with no reputation slot: neutral, attackable, the enemy bucket.
         let chicken = unit(31);
         assert!(!category(&chicken, &quiet), "a critter is enemy-category");
         assert_eq!(rank(&chicken, &quiet), 3, "and its bar is neutral yellow");
 
-        // A League of Arathor Emissary (FT 1577 → faction 509, reputation slot 53) is answered by
-        // the AT-WAR bit — not at war → 4 → not attackable → the FRIENDLY bucket, Shift-V only.
-        // The director confirmed exactly this on the reference.
+        // A League of Arathor Emissary, template 1577, reputation slot 53, not at war.
         let emissary = unit(1577);
         assert!(category(&emissary, &quiet), "friendly-category at neutral");
         assert_eq!(
@@ -1109,12 +841,9 @@ mod tests {
              directions, and this disagreement is the reference's own"
         );
 
-        // **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.
+        // Booty Bay, template 120: the comparator says 3, so only the at-war leg makes it friendly.
         let goblin = unit(120);
         assert!(category(&goblin, &quiet), "Booty Bay: friendly, not at war");
-        // …and declaring war flips it, which is the same bit the reputation pane's checkbox writes.
         let mut slots = vec![(0u8, 0i32); 64];
         slots[1] = (benilla_formats::faction_flags::AT_WAR, 0); // Booty Bay = slot 1
         let at_war = Reputations(slots);
@@ -1124,25 +853,13 @@ mod tests {
             "…and only that faction's own bit moves"
         );
 
-        // A Stormwind guard (FT 12 → faction 72, slot 19) is friendly by BOTH routes — the case
-        // that agreed all along, kept so the fix cannot be read as having moved it.
+        // A Stormwind guard, template 12, faction 72, slot 19: friendly by both routes.
         assert!(category(&unit(12), &quiet));
         assert_eq!(rank(&unit(12), &quiet), 4);
     }
 
-    /// **The reported bug, on the real build-5875 DBC, naming the faction** (1674): hovering a
-    /// **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 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.
-    ///
-    /// The pin asserts the divergence the threshold cannot express: **the rank stays 3 — the ring
-    /// and the bar are untouched — while both branch predicates say Point.** A "simplification"
-    /// back to a threshold has to break this, on real data, naming the creature.
+    /// Cenarion Circle, faction 609 with reputation slot 36: not at war, its NPCs are neither
+    /// attackable nor, without a service bit, interactable, while the rank stays neutral.
     #[test]
     fn a_not_at_war_cenarion_circle_npc_takes_no_cursor_at_neutral() {
         use crate::net::{ObjectStore, Reputations};
@@ -1159,7 +876,7 @@ mod tests {
             (35, 1), // Human
             (46, UNIT_FLAG_PVP_ATTACKABLE),
         ]));
-        let quiet = Reputations::default(); // nothing at war — the out-of-box state
+        let quiet = Reputations::default(); // nothing at war
         let mut slots = vec![(0u8, 0i32); 64];
         slots[36] = (benilla_formats::faction_flags::AT_WAR, 0); // Cenarion Circle = slot 36
         let at_war = Reputations(slots);
@@ -1171,9 +888,7 @@ mod tests {
             crate::target::ring::can_interact_from_player(Some(&factions), r, Some(u), Some(&me))
         };
 
-        // FactionTemplate 996 → faction 609 "Cenarion Circle" (also 635/994/1254/1608). The
-        // reported subject: no service bit at all, so the ladder was never in play — the unit fell
-        // straight to the attack leg.
+        // Template 996, faction 609, with no service bit.
         let silent = npc(996, 0);
         assert_eq!(
             ring_reaction(Some(&factions), &quiet, Some(&silent), Some(&me)),
@@ -1189,15 +904,12 @@ mod tests {
             "and with no service bit it is not interactable either → the cursor CLEARS to Point"
         );
 
-        // A Cenarion Circle NPC that DOES gossip keeps its speech bubble — the control that must
-        // not move, and the half of the report that was already right.
+        // One that gossips keeps its speech bubble.
         let gossip = npc(996, crate::target::cursor_mode::npc_flags::GOSSIP);
         assert!(interactable(&gossip, &quiet), "gossip NPC still talks");
         assert!(!attackable(&gossip, &quiet));
 
-        // Declaring war moves BOTH, off one bit: leg 3 answers hostile, so the gossiper drops out
-        // of the service ladder and the silent one takes the sword. This is the behaviour the
-        // director named as the discriminator — "even if you don't have the faction set to at war".
+        // At war: the gossiper leaves the ladder, the silent one takes the sword.
         assert!(
             attackable(&silent, &at_war),
             "at war → the sword is correct"
@@ -1207,17 +919,13 @@ mod tests {
             !interactable(&gossip, &at_war),
             "at war → no more gossip cursor; the reference leaves the ladder entirely"
         );
-        // …and only that faction's own slot moves.
         assert_eq!(
             ring_reaction(Some(&factions), &at_war, Some(&silent), Some(&me)),
             3,
             "the STANDING is still neutral — at-war does not touch the bar"
         );
 
-        // **The control that must not change**: an ordinary neutral creature whose faction owns no
-        // reputation slot (Chicken, FT 31 → faction 28 "Prey") is answered by the template
-        // comparator, reads neutral, and is still attackable. Neutral mobs keep the sword — the fix
-        // is about the at-war bit, not about neutrality.
+        // A Chicken, template 31 with no reputation slot, still takes the sword.
         let chicken = npc(31, 0);
         assert!(
             attackable(&chicken, &quiet),
@@ -1226,21 +934,9 @@ mod tests {
         assert!(!interactable(&chicken, &quiet));
     }
 
-    /// **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 (`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
-    /// row is `faction 31, group_mask 0`. Zero equals no player's mask, so a GM-mode character —
-    /// on either side of the pair — falls out of the friendly bucket and takes a plate under plain
-    /// V. Nothing else on screen moves, because `CanCooperate` is only ever consulted for a player
-    /// subject. That asymmetric signature is what a "players are plating and mobs look fine"
-    /// report means, and this test is where to read it. (`GM.LoginState = 2` keeps the mode across
-    /// logins, so it outlives the session that set it.)
+    /// A player is friendly only if `CanCooperate`, faction-group-mask equality (`0x606ba0`), also
+    /// passes. Template 35, which vmangos's `.gm on` sets (`Player.cpp:2661`), is faction 31 with
+    /// mask 0, so a GM-mode character leaves every player's friendly bucket while NPCs keep theirs.
     #[test]
     fn the_player_subject_category_on_the_real_dbc() {
         use crate::net::{ObjectStore, Reputations};
@@ -1250,7 +946,6 @@ mod tests {
         let mut chain = benilla_formats::open_chain(&data).expect("open chain");
         let factions = Factions(benilla_formats::load_faction_catalog(&mut chain).expect("dbc"));
         let reps = Reputations::default();
-        // Every player carries `PLAYER_CONTROLLED`; the plate gate passes `is_player = true`.
         let player = |tpl: u32| {
             ObjectStore(ObjectFields::from_pairs(&[
                 (35, tpl),
@@ -1261,27 +956,24 @@ mod tests {
             plate_is_friendly(Some(&factions), &reps, Some(subject), Some(me), true)
         };
 
-        // Us: a Human (FT 1, group_mask 3).
+        // Us: a Human, template 1, mask 3.
         let me = player(1);
-        // Same faction group — a Gnome is FT 115, a different row with the SAME mask. Friendly
-        // category: no plate under plain V, which is the shipped behaviour this pins.
+        // A Gnome, template 115: another row with the same mask.
         assert!(
             category(&player(115), &me),
             "an Alliance player is friendly"
         );
         assert!(category(&player(1), &me), "…same race, same answer");
-        // The other faction group (Orc FT 2, mask 5) is enemy-category — and that is FAITHFUL:
-        // the reference plates the opposing faction under plain V, flagged or not.
+        // An Orc, template 2, mask 5: the enemy bucket, flagged or not.
         assert!(!category(&player(2), &me), "a Horde player is enemy");
-        // A GM-mode player (FT 35, mask 0) matches NOBODY's mask — enemy category from a normal
-        // character, while `CanAttack` still refuses (the plate is drawn over someone unattackable).
+        // A GM-mode player, template 35, mask 0, matches no one: enemy, though not attackable.
         assert!(!category(&player(35), &me), "a GM-mode player is enemy");
         assert!(
             !can_attack_from_player(Some(&factions), &reps, Some(&player(35)), Some(&me), true),
             "…and not because we can attack them",
         );
 
-        // The mirror: a GM-mode OBSERVER loses the friendly bucket for every player at once…
+        // A GM-mode observer loses the friendly bucket for every player…
         let gm = player(35);
         for tpl in [1u32, 3, 4, 115, 2, 5, 6, 116] {
             assert!(
@@ -1289,9 +981,7 @@ mod tests {
                 "FT {tpl} is enemy-category to a GM-mode observer",
             );
         }
-        // …while nothing else on screen moves: `CanCooperate` is never consulted for an NPC, so a
-        // Stormwind guard stays friendly and a Monster-faction mob stays enemy. THAT asymmetry is
-        // the report's signature.
+        // …while NPCs keep theirs: `CanCooperate` is never asked for an NPC.
         let npc = |tpl: u32| ObjectStore(ObjectFields::from_pairs(&[(35, tpl)]));
         let npc_category = |subject: &ObjectStore, me: &ObjectStore| {
             plate_is_friendly(Some(&factions), &reps, Some(subject), Some(me), false)
@@ -1299,7 +989,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 (`606ba6`): nobody cooperates with themselves.
+        // Nobody cooperates with themselves (`0x606ba6`).
         assert!(!can_cooperate_with_player(
             Some(&factions),
             Some(&me),
@@ -1307,11 +997,7 @@ 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 (`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.
+    /// `CanAttack`'s flag refusals (`0x6069b7`–`0x6069ff`) beat a hostile reaction.
     #[test]
     fn an_unattackable_flag_beats_a_hostile_reaction() {
         use crate::net::{ObjectStore, Reputations};
@@ -1327,7 +1013,7 @@ mod tests {
         let reps = Reputations::default();
         let mob = |flags: u32| ObjectStore(ObjectFields::from_pairs(&[(35, 14), (46, flags)]));
 
-        // FT 14 "Monster" — hostile to the player by the mask comparison.
+        // Template 14, Monster: hostile by the comparator.
         assert_eq!(
             ring_reaction(Some(&factions), &reps, Some(&mob(0)), Some(&me)),
             1
@@ -1336,14 +1022,14 @@ mod tests {
             !plate_is_friendly(Some(&factions), &reps, Some(&mob(0)), Some(&me), false),
             "a plain hostile mob is enemy-category"
         );
-        // Each of the five refusal bits alone flips the category, hostile reaction and all.
+        // Each of these refusal bits alone flips the category.
         for bit in [0x2u32, 0x80, 0x1_0000, 0x10_0000] {
             assert!(
                 plate_is_friendly(Some(&factions), &reps, Some(&mob(bit)), Some(&me), false),
                 "flag {bit:#x} refuses the attack → friendly category"
             );
         }
-        // Bit 8 (0x100) refuses only because WE are player-controlled — the cross-flag leg.
+        // Bit 8 (`0x100`) refuses because we are player-controlled: the cross-flag leg.
         assert!(plate_is_friendly(
             Some(&factions),
             &reps,
@@ -1353,13 +1039,10 @@ mod tests {
         ));
     }
 
-    /// **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.
+    /// A torn-down object stops being an object at the teardown, not when its model has faded:
+    /// both of the reference's routes (`SMSG_DESTROY_OBJECT`, the out-of-range block) reach
+    /// `0x464920` → `0x5fbb60` → `0x493910`, which clears a matching selection and sends
+    /// `CMSG_SET_SELECTION 0` at once, while only the detached model fades on.
     mod teardown {
         use benilla_protocol::field::{
             FIELD_UNIT_FLAGS, FIELD_UNIT_HEALTH, FIELD_UNIT_LEVEL, FIELD_UNIT_MAXHEALTH,
@@ -1399,8 +1082,7 @@ mod tests {
             }
         }
 
-        /// The built client with our own avatar and one live mob in the index, the mob
-        /// selected, and the write channel captured.
+        /// The built client with our avatar and one selected live mob, 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();
@@ -1414,8 +1096,7 @@ mod tests {
                     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.
+                        // Player-controlled: a neutral mob is attackable with no faction catalog.
                         ObjectFields::from_pairs(&[
                             (FIELD_UNIT_HEALTH, 100),
                             (FIELD_UNIT_MAXHEALTH, 100),
@@ -1432,12 +1113,12 @@ mod tests {
                 target: Some(mob),
                 guid: Some(MOB),
             };
-            // The control: a live selected unit keeps its selection through a ring pass.
+            // Control: a live target 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.)
+            // The create's name query is on the channel too; only a selection send matters.
             assert!(
                 !rx.try_iter()
                     .any(|c| matches!(c, ClientCommand::SetSelection { .. })),
@@ -1450,7 +1131,6 @@ mod tests {
             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"
@@ -1483,8 +1163,7 @@ mod tests {
             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.
+        /// The nearest-enemy scan never picks a fading model.
         #[test]
         fn the_nearest_enemy_scan_never_picks_a_torn_down_object() {
             let (mut app, _mob, _rx) = client_with_selected_mob();
@@ -1511,9 +1190,8 @@ mod tests {
             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.
+        /// A respawn destroys and re-creates the guid in one tick: the create is a new object, and
+        /// the fading model does not answer 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();
diff --git a/crates/benilla-app/src/target/scan.rs b/crates/benilla-app/src/target/scan.rs
index f05bd579..559c6ff1 100644
--- a/crates/benilla-app/src/target/scan.rs
+++ b/crates/benilla-app/src/target/scan.rs
@@ -1,48 +1,14 @@
-//! TAB / nearest-enemy targeting + combat auto-target — the **Classic-priority selection**
-//! (decision 0567) over the 1.12 wire laws.
+//! TAB and nearest-unit targeting, and the attack auto-acquires.
 //!
-//! 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 — 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
-//! character axis), and its snapshot cycle walks into behind-you mobs. Blizzard hit the same
-//! wall and rewrote targeting for Legion 7.2 — the system Classic Era ships. We follow that
-//! design, pinned from the Classic binary's own cvar-description strings (statically recovered;
-//! the code section is packer-encrypted) and the 7.2 patch note:
+//! Deviation: TAB uses Classic Era's screen-space priority, not 1.12's ±30° facing cone and
+//! snapshot cursor (`0x493f60`), because the cone skips a close mob in front of the camera, which
+//! sits behind the character. On-screen candidates come first, the lowest score wins, and each
+//! press skips recently tabbed guids; a fighting-me bonus, not Classic's hard combat lock, ranks
+//! attackers first without pinning TAB to them.
 //!
-//! - **Screen-space tiering** — a candidate whose projected point lands inside the camera
-//!   frustum with each screen edge pulled in (`TargetPriorityFrustumPullIn{Sides,Top,Bot}`:
-//!   "Percentage towards center to pull in [edge] of the screen for in-view checks") is a
-//!   tier-1 ("100% correct") pick; off-screen candidates are reachable **only when no
-//!   on-screen candidate exists** (`TargetPriorityAllowAnyOnScreen` = 1 semantics).
-//! - **A weighted score, not a lexicographic sort** (`TargetPriorityValueBank`): screen
-//!   off-centerness + normalized distance − an "attacking me" bonus; lowest wins.
-//! - **A fighting-me score bonus, not Classic's hard combat lock**: units attacking me outrank
-//!   everything peaceful, but TAB can always walk off them onto a fresh target. Classic's
-//!   `TargetPriorityCombatLock` (pool restricted to in-combat units) was implemented and then
-//!   retired by the director's feel — decision 0568: with a single attacker it pinned TAB to
-//!   that mob with no way off.
-//! - **History cycling, no snapshot cursor** (`TargetPriorityHighlightHistoryMs` — "time target
-//!   history should be maintained for repeated activations"): every press re-scores the live
-//!   world and skips recently-tabbed guids; exhausting the pool clears the history (the wrap).
-//!   Shift-TAB steps back through the history. A clicked target joins the history when tabbed
-//!   away from (`TargetPriorityContinueFromManualTarget`'s observable).
-//!
-//! The **numbers** here (pull-in margins, weights, the history window) are tunable stand-ins —
-//! Blizzard's defaults live in the encrypted code section; each const names its cvar so a later
-//! pin (the director's in-game `GetCVarInfo` dump) slots straight in. Not modeled, disclosed:
-//! `TargetPriorityUpdateDelay` (a timer-refreshed list feeding the hold-to-highlight preview we
-//! don't have — per-press rebuild covers selection), `TargetPriorityAutoTargetIgnoreWindow`,
-//! `AllowAnyOnScreen=2` (out-of-range picks), PvP weighting, and the 7.2 note's
-//! character-OR-camera visibility union (we test the camera only).
-//!
-//! **What stays byte-law from 1.12** (wire/data semantics, unchanged): the validity filters
-//! (dead / [`can_attack`] `0x606980` / CreatureType flag-bit-0 critters), the [`commit`]
-//! stop→select→re-swing SetSelection law (`0x493540`), attack-with-no-target acquiring the best
-//! candidate and swinging (`0x612df0` @ `6130b5`), and the ATTACKERSTATEUPDATE auto-acquire
-//! (`6259c9`–`6259fe`). The 41-yd range keeps 1.12's `targetNearestDistance` default — Classic
-//! still ships that cvar ("limited to tab targeting range").
+//! Kept from 1.12: the validity filters (`0x493e40`, [`can_attack`] `0x606980`, critters), the
+//! [`commit`] through `SetSelection` (`0x493540`), the attack acquire (`0x612df0` at `0x6130b5`),
+//! the ATTACKERSTATEUPDATE acquire (`0x6259c9`–`0x6259fe`) and the 41 yd range.
 
 use benilla_formats::CreatureTypeFlags;
 use benilla_protocol::{guid, EntityKind};
@@ -59,76 +25,45 @@ use super::ring::reaction_from_player;
 use super::{Factions, Selection};
 
 // == The Classic-priority dials ==
-// Each names the Classic Era cvar it stands in for. The VALUES are tuned, not pinned — the
-// binary's defaults are packer-encrypted; when the director's in-game `GetCVarInfo` dump lands,
-// replace these with the real defaults and note it in the 0567 lineage.
+// Each names the Classic Era cvar it stands in for; the values are tuned.
 
-/// `targetNearestDistance` — the tab-targeting range (yd). 1.12's byte-verified default 41
-/// (`[0x804510]`); Classic still ships the cvar ("limited to tab targeting range").
+/// `targetNearestDistance`, the TAB range in yards: 1.12's default (`[0x804510]`).
 const TAB_RANGE: f32 = 41.0;
-/// `TargetPriorityFrustumPullInSides` — fraction of the viewport width pulled toward center
-/// from EACH side edge for the in-view check.
+/// `TargetPriorityFrustumPullInSides`: the viewport width fraction pulled in from each side.
 const FRUSTUM_PULL_SIDES: f32 = 0.10;
-/// `TargetPriorityFrustumPullInTop` — fraction of the viewport height pulled down from the top.
+/// `TargetPriorityFrustumPullInTop`: the viewport height fraction pulled down from the top.
 const FRUSTUM_PULL_TOP: f32 = 0.10;
-/// `TargetPriorityFrustumPullInBot` — fraction of the viewport height pulled up from the bottom.
+/// `TargetPriorityFrustumPullInBot`: the viewport height fraction pulled up from the bottom.
 const FRUSTUM_PULL_BOT: f32 = 0.10;
-/// `TargetPriorityHighlightHistoryMs` — how long a tabbed guid stays "recently visited" (the
-/// skip set for repeated presses).
+/// `TargetPriorityHighlightHistoryMs`: how long a tabbed guid is skipped by repeated presses.
 const HISTORY_SECS: f64 = 4.0;
-/// The score's screen term weight: per unit of normalized off-centerness (0 = screen center,
-/// 1 ≈ a viewport corner). One slot of the `TargetPriorityValueBank` stand-in.
+/// The weight per unit of off-centerness (0 at the centre, about 1 at a corner).
 const W_SCREEN: f32 = 1.0;
-/// The score's distance term weight: per unit of `dist / TAB_RANGE`.
+/// The weight per unit of `dist / TAB_RANGE`.
 const W_DIST: f32 = 1.0;
-/// The "attacking me" bonus (`TargetPriorityCombatLock`'s spirit as a score term — the hard
-/// lock itself is retired, decision 0568): a mob whose UNIT_FIELD_TARGET is me and whose
-/// in-combat flag is set outranks anything peaceful at any screen position (the bonus exceeds
-/// the terms' max sum), but never pins the cycle.
+/// Above the other terms' largest sum, so an attacker outranks anything peaceful.
 const COMBAT_WITH_ME_BONUS: f32 = 3.0;
 
-/// `WOW_TAB_TRACE=1` — the TAB-target field instrument: every press logs each known unit's
-/// verdict (the reject reason, or its distance / screen position / score), the sorted pool,
-/// the history, and the pick — so a "TAB won't take the mob next to me"
-/// report is diagnosable from the log instead of re-guessed. One `OnceLock` read per press when
-/// unset; the lines ride `info!` under the `tab-trace:` prefix.
+/// `WOW_TAB_TRACE=1`: log each press's verdicts, pool and pick under `tab-trace:`.
 fn tab_trace_on() -> bool {
     static ON: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
     *ON.get_or_init(|| std::env::var_os("WOW_TAB_TRACE").is_some())
 }
 
-/// Which side a press is looking for — the reference's **mode** argument, and the only thing that
-/// forks on the whole path.
-///
-/// The four `TargetNearest*` shims are one function with one changed immediate: `0x489a80`
-/// (`TargetNearestEnemy`) pushes `edx = 1`, `0x489aa0` (`TargetNearestFriend`) pushes `edx = 2`,
-/// and `0x489ac0`/`0x489ae0` push 3 and 4 for the party and raid siblings — every one of them then
-/// calls the single cycler `0x493f60(ecx = reverse, edx = mode)`. The mode reaches exactly one
-/// 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.
-///
-/// 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.
+/// The reference's scan mode: the `TargetNearest*` shims (`0x489a80` enemy 1, `0x489aa0` friend 2,
+/// `0x489ac0`/`0x489ae0` party and raid 3/4) all call one cycler, `0x493f60(reverse, mode)`, and
+/// the mode reaches only the per-candidate filter `0x493e40`. Modes 3 and 4 are not built.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(crate) enum ScanSide {
-    /// **Mode 1** (`0x493e73`) — the liveness triple (`0x605f90`, health, dynflag/stand-state) and
-    /// `CanAttack 0x606980`.
+    /// Mode 1 (`0x493e73`): alive by the reads-dead triple `0x605f90`, and `CanAttack 0x606980`.
     Enemy,
-    /// **Mode 2** (`0x493eca`) — `CanAssist 0x6066f0`, then `UNIT_FIELD_HEALTH > 0`, and nothing
-    /// else. Two things fall out of that being *shorter* than mode 1 rather than its mirror: a
-    /// **feigning** friendly (health > 0, `UNIT_DYNFLAG_DEAD` set) is still a candidate, because
-    /// mode 2 has no dynflag leg; and `CanAssist`'s own ladder is **friendly or better** — neutral
-    /// fails (`0x60671e cmp eax,4; jge`, on the internal 0-based rank, so Lua's FRIENDLY(5) is
-    /// internal 4). Its NPC arm is `IsPvP 0x605ff0` on the candidate (owner-chased), so a friendly
-    /// creature with no `UNIT_FLAG_PVP` is NOT a `TargetNearestFriend` candidate at all — the
-    /// same predicate that already denies its buffs (decision 1035).
+    /// Mode 2 (`0x493eca`): `CanAssist 0x6066f0`, friendly or better (`0x60671e`), whose
+    /// `IsPvP 0x605ff0` leg refuses a creature without `UNIT_FLAG_PVP`; then health > 0 with no
+    /// dynflag leg, so a feigning ally counts.
     Friend,
 }
 
-/// One scored candidate. `score`: lower is better. `on_screen`: inside the pulled-in frustum
-/// (the tier-1 gate). The fighting-me bonus is already folded into `score` at build time.
+/// `score`, lower is better, includes the fighting-me bonus; `on_screen` is the tier-1 gate.
 #[derive(Clone, Copy, Debug)]
 struct Candidate {
     entity: Entity,
@@ -137,9 +72,7 @@ struct Candidate {
     score: f32,
 }
 
-/// The priority value (`TargetPriorityValueBank` stand-in): screen off-centerness (absent for
-/// off-screen candidates — the tier gate keeps them apart, so their mutual order is distance +
-/// combat only) + normalized distance − the attacking-me bonus. Lowest wins.
+/// Off-centerness (none off-screen) plus normalized distance, minus the fighting-me bonus.
 fn priority_score(off_center: Option<f32>, dist: f32, combat_with_me: bool) -> f32 {
     off_center.map_or(0.0, |c| W_SCREEN * c) + W_DIST * (dist / TAB_RANGE)
         - if combat_with_me {
@@ -149,21 +82,14 @@ fn priority_score(off_center: Option<f32>, dist: f32, combat_with_me: bool) -> f
         }
 }
 
-/// The sort: tier first (on-screen before off-screen — `AllowAnyOnScreen` keeps the fallback
-/// tier from ever outranking a "100% correct" pick), then ascending score.
+/// On-screen before off-screen, then ascending score.
 fn candidate_order(a: &Candidate, b: &Candidate) -> std::cmp::Ordering {
     b.on_screen
         .cmp(&a.on_screen)
         .then(a.score.total_cmp(&b.score))
 }
 
-/// The press's pick pool from the sorted candidates: the on-screen tier when it exists, else
-/// everything (`AllowAnyOnScreen=1` — "if no 100% correct target is available, allow selecting
-/// any valid in-range target"). Classic's HARD combat lock (`TargetPriorityCombatLock` — the
-/// pool restricted to in-combat units while starting from one) was implemented and then
-/// **retired by the director's feel** (decision 0568): with a single attacker it pinned TAB to
-/// that mob with no way off. The fighting-me *score bonus* stays — attackers come first, but
-/// the history walks you off them.
+/// The on-screen tier when it is not empty, else every candidate (`AllowAnyOnScreen` = 1).
 fn select_pool(cands: &[Candidate]) -> Vec<Candidate> {
     if cands.iter().any(|c| c.on_screen) {
         cands.iter().filter(|c| c.on_screen).copied().collect()
@@ -172,10 +98,8 @@ fn select_pool(cands: &[Candidate]) -> Vec<Candidate> {
     }
 }
 
-/// The forward pick over a sorted pool: the best candidate that is neither the current
-/// selection nor recently visited; all visited → the wrap (best non-current, history to be
-/// cleared by the caller); only the current one left → itself (the commit dedups to a no-op).
-/// Returns `(index, wrapped)`.
+/// The best candidate neither current nor visited; else the best non-current, wrapped (the caller
+/// clears the history); else the current one itself.
 fn pick_forward(
     pool: &[Candidate],
     visited: &[u64],
@@ -196,15 +120,8 @@ fn pick_forward(
     Some((0, true))
 }
 
-/// The **backward** pick (Shift-TAB / `TargetNearestFriend(1)` — the reference's `reverse` flag):
-/// walk the history newest-first for a guid that is neither the current selection nor gone from
-/// the pool. `None` = nothing to step back to, and the caller falls through to [`pick_forward`],
-/// which is what makes the very first reverse press behave like a forward one.
-///
-/// The reference cycles a *snapshot list* by a cursor and simply decrements it (`cursor == 0 ?
-/// count-1 : cursor-1`, no timer check — the asymmetry is its own); decision 0567 replaced the
-/// snapshot with this history, so "back" means "the target before this one" rather than "the
-/// previous array slot". Pure, and beside its forward twin, so the two are read together.
+/// The reverse pick: the newest history guid neither current nor gone from the pool, `None` falling
+/// through to [`pick_forward`]. The reference steps its snapshot cursor back one slot instead.
 fn pick_back(visited: &[u64], pool: &[Candidate], current: Option<u64>) -> Option<usize> {
     visited.iter().rev().find_map(|g| {
         (Some(*g) != current)
@@ -213,24 +130,16 @@ fn pick_back(visited: &[u64], pool: &[Candidate], current: Option<u64>) -> Optio
     })
 }
 
-/// "Fighting me": the unit's UNIT_FIELD_TARGET is my guid AND its in-combat flag
-/// (UNIT_FLAG_IN_COMBAT, bit 19) is set — the `TargetPriorityCombatLock=2` notion ("in-combat
-/// with player"), the one that matters solo.
+/// The unit targets me and has `UNIT_FLAG_IN_COMBAT` (bit 19) set.
 fn combat_with_me(store: &ObjectStore, me: Option<u64>) -> bool {
     me.is_some() && store.0.unit_target() == me && store.0.unit_flags() & (1 << 19) != 0
 }
 
-/// The CreatureType.dbc flags table (see `benilla-formats`); absent (load failure) = no
-/// 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";
-/// the code was always reading the flag rather than a type list, so only the
-/// words were wrong.
+/// `CreatureType.dbc`'s flags, whose no-TAB bit is set on type 8, Critter, alone (Totem reads 0).
+/// Absent after a load failure, when nothing is filtered.
 #[derive(Resource)]
 pub(crate) struct CreatureTypes(CreatureTypeFlags);
 
-/// Startup (after the MPQ chain opens): load CreatureType.dbc for the critter TAB filter.
 pub(super) fn load_creature_types(mut commands: Commands, world_assets: Option<Res<WorldAssets>>) {
     let Some(world_assets) = world_assets else {
         return;
@@ -245,29 +154,13 @@ pub(super) fn load_creature_types(mut commands: Commands, world_assets: Option<R
     }
 }
 
-/// Everything the scan core reads, bundled (the TAB and attack-acquire systems share it).
+/// Everything the scan reads, shared by TAB, the attack acquire and the pet bar's Attack.
 ///
-/// `pub(crate)` rather than `pub(super)` because the **pet bar's** ATTACK arm runs the same
-/// `TargetNearestEnemy()` the player's does ([`attack_order_target`]), and its drain lives in
-/// `ui_pet`.
-///
-/// # `Without<SelfPlayer>` is a divergence, and a deliberate one
-///
-/// **The reference's friendly cycler can select YOU.** Nothing on the `0x493f60` chain excludes
-/// 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. (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 `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).
+/// Deviation: our own body is never a candidate. The reference's friendly scan picks the player at
+/// some facings (`CanAssist(P, P)` is true, `0x6061e0`; the cone test `0x47f220`), but our scoring
+/// always puts the player dead centre at distance 0, so CTRL-TAB would pick us on every press.
 #[derive(SystemParam)]
-#[allow(clippy::type_complexity)] // one bundled system param — the app's convention for big query sets
+#[allow(clippy::type_complexity)] // one bundled system param, the app's convention
 pub(crate) struct TargetScan<'w, 's> {
     units: Query<
         'w,
@@ -291,8 +184,7 @@ pub(crate) struct TargetScan<'w, 's> {
         ),
         With<SelfPlayer>,
     >,
-    /// The live world camera — the in-view check's frustum. Absent (glue screens, headless):
-    /// nothing projects, everything is fallback-tier, and the pick degrades to distance+combat.
+    /// The in-view check's camera; without one every candidate is fallback tier.
     camera: Query<
         'w,
         's,
@@ -303,18 +195,14 @@ pub(crate) struct TargetScan<'w, 's> {
     reputations: Res<'w, Reputations>,
     names: Res<'w, NameCache>,
     creature_types: Option<Res<'w, CreatureTypes>>,
-    /// Every store, ours included — read only by the friend arm's `CanAssist`, whose `IsPvP` leg
-    /// chases the candidate's owner. `units` above cannot serve: it excludes our own body, which
-    /// is exactly who owns our pet.
+    /// Every store, ours included: `CanAssist`'s owner chase must reach our body.
     stores: Query<'w, 's, &'static ObjectStore>,
-    /// The guid → entity map the owner chase lands in. `Option` for the same reason
-    /// [`crate::ui_unit::UnitTokens`] carries it that way — a UI-only harness runs with no net
-    /// stack, and a bare `Res` would turn that into a system-validation panic.
+    /// The owner chase's guid → entity map; `Option` because a UI-only harness has no net stack.
     index: Option<Res<'w, GuidIndex>>,
 }
 
 impl TargetScan<'_, '_> {
-    /// The `0x493e40` per-candidate validity filter, both arms — the one thing [`ScanSide`] forks.
+    /// The per-candidate filter (`0x493e40`), the one place [`ScanSide`] forks.
     fn is_valid(
         &self,
         side: ScanSide,
@@ -322,10 +210,7 @@ impl TargetScan<'_, '_> {
         self_store: Option<&ObjectStore>,
     ) -> bool {
         match side {
-            // Mode 1 (`0x493e73`) — liveness + hostility (kept byte-law). The liveness leg is the
-            // reference's own reads-dead triple `0x605f90` — health, the `UNIT_DYNFLAG_DEAD` bit
-            // (feign death) and stand state 7 — the shared predicate rather than a third
-            // transcription of it (decision 1022).
+            // Mode 1 (`0x493e73`): the reads-dead triple `0x605f90`, then `CanAttack`.
             ScanSide::Enemy => {
                 if store.is_some_and(|s| s.0.unit_reads_dead()) {
                     return false;
@@ -337,10 +222,7 @@ impl TargetScan<'_, '_> {
                     self_store,
                 )
             }
-            // Mode 2 (`0x493eca`) — `CanAssist 0x6066f0` first, then `[[cand+0x110]+0x40] > 0`.
-            // The order is the reference's and so is the *narrowness* of the liveness leg: it
-            // reads raw HEALTH, not the reads-dead triple, so this deliberately does NOT reuse
-            // `unit_reads_dead` (see [`ScanSide::Friend`]).
+            // Mode 2 (`0x493eca`): `CanAssist 0x6066f0`, then raw health (no reads-dead triple).
             ScanSide::Friend => {
                 can_assist(
                     store,
@@ -353,19 +235,16 @@ impl TargetScan<'_, '_> {
         }
     }
 
-    /// A guid's streamed descriptor, whichever entity holds it — `CanAssist`'s owner chase.
+    /// A guid's descriptor, whichever entity holds it: `CanAssist`'s owner chase.
     fn store_of(&self, guid: u64) -> Option<&ObjectStore> {
         let entity = *self.index.as_ref()?.0.get(&guid)?;
         self.stores.get(entity).ok()
     }
 
-    /// Our own descriptor, for whichever leg needs the reaction's second party outside [`build`].
     fn self_store(&self) -> Option<&ObjectStore> {
         self.self_q.single().ok().and_then(|(_, store, _)| store)
     }
 
-    /// Our own guid — `IsSelectable`'s `CREATEDBY` clause needs the active player's, and so does
-    /// the commit's self-target exception.
     fn self_guid(&self) -> Option<u64> {
         self.self_q
             .single()
@@ -374,32 +253,15 @@ impl TargetScan<'_, '_> {
             .map(|g| g.0)
     }
 
-    /// An entity's streamed descriptor — the commit gate's `IsSelectable` input.
     fn store_at(&self, entity: Entity) -> Option<&ObjectStore> {
         self.stores.get(entity).ok()
     }
 
-    /// `0x6130a3`'s keep-or-drop test on a guid we are already holding: is the actor hostile to it?
-    ///
-    /// The reference reads `0x6061e0(actor, target) >= 4` — the **reaction alone**, not the full
-    /// `0x606980` CanAttack, which it saves for the final gate at `0x613167`. A guid whose unit is
-    /// not streamed answers `false`, which is the same exit `0x613099` takes when its object lookup
-    /// misses.
-    ///
-    /// **The direction is ACTOR → target**, byte-read at the call: `0x61309b push eax` (the
-    /// candidate) `; mov ecx,edi` (the actor) `; call 0x6061e0`, then `cmp eax,4; jl keep`. So it is
-    /// [`reaction_from_player`], the leg-3 direction that answers a reputation-slot faction with the
-    /// **at-war bit** — *not* [`ring_reaction`], which this used to call and which reads the
-    /// standing from the other side (1674; the two are deliberately not each other's mirror, and
-    /// substituting one for the other is the defect 1530 named). With the standing here, pressing
-    /// Attack while holding a not-at-war Cenarion Circle NPC kept it as the target and then failed
-    /// the final gate; the reference drops it and goes and finds a real enemy.
-    ///
-    /// **The actor is the player here, and in the reference it is the caller's** — the pet on the
-    /// pet arm (`0x4bd40d` passes the pet object). The two agree: vmangos gives a pet its owner's
-    /// faction template outright (`Pet.cpp:248`), and the reputation leg is the owner's by
-    /// definition. Reading the pet's own store instead would also fight [`build`], whose entire
-    /// candidate scan is player-relative (screen, distance, "fighting me").
+    /// `0x6130a3`'s keep test: the actor's reaction to the held guid alone (`0x61309b`), not the
+    /// final gate's `CanAttack`; an unstreamed guid is not hostile (`0x613099`). Actor → target is
+    /// [`reaction_from_player`] (the at-war bit), never `ring_reaction`. The reference's actor is
+    /// the caller, a pet on the pet arm (`0x4bd40d`), which vmangos gives its owner's faction
+    /// (`Pet.cpp:248`).
     fn reaction_hostile(&self, guid: u64) -> bool {
         let self_store = self.self_store();
         self.units
@@ -415,7 +277,6 @@ impl TargetScan<'_, '_> {
             })
     }
 
-    /// The streamed unit behind a guid, as `(entity, store)` — the final gate's input.
     fn unit_by_guid(&self, guid: u64) -> Option<(Entity, Option<&ObjectStore>)> {
         self.units
             .iter()
@@ -423,29 +284,15 @@ impl TargetScan<'_, '_> {
             .map(|(e, _, _, _, store)| (e, store))
     }
 
-    /// The full build: walk every known unit, filter (the kept 1.12 legality laws), project
-    /// through the live camera, score, sort (tier, then score). Fresh every press — the live
-    /// world is the list (no snapshot to go stale).
-    ///
-    /// `side` reaches exactly one line — [`Self::is_valid`] — which is the reference's own shape:
-    /// the mode byte forks `0x493e40` and nothing else on the path.
-    ///
-    /// **Our own body is never a candidate**: the query is `Without<SelfPlayer>`. For the enemy
-    /// side that is free (`CanAttack(me, me)` is false anyway); for the friend side it is a
-    /// 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.
+    /// Filter, project, score and sort every known unit, fresh each press.
     fn build(&self, side: ScanSide) -> Vec<Candidate> {
         let Ok((self_tf, self_store, self_guid)) = self.self_q.single() else {
             return Vec::new();
         };
         let me = self_guid.map(|g| g.0);
         let cam = self.camera.single().ok();
-        // Normalized off-centerness of a world point on the pulled-in screen: `None` when
-        // off-screen / behind the camera / outside the pulled-in frustum; `Some(0)` at the
-        // viewport center, ~1 at a corner. The point is the unit's root + 1 yd (chest-ish) so
-        // a mob whose feet sit just below the pulled-in bottom edge still reads as on-screen.
+        // Off-centerness on the pulled-in screen, 0 at the centre and about 1 at a corner, `None`
+        // outside it. Callers project the root + 1 yd, so feet just below the edge still count.
         let project = |world: Vec3| -> Option<f32> {
             let (camera, cam_pose) = cam?;
             let cam_tf = GlobalTransform::from(*cam_pose);
@@ -487,9 +334,7 @@ impl TargetScan<'_, '_> {
                 );
                 continue;
             }
-            // The creature-type gate (CreatureType.dbc flag bit 0 — critters; kept byte-law).
-            // An unresolved type (name not yet queried) passes, like the client's
-            // out-of-range table index.
+            // The critter gate; an unresolved type passes, like the client's out-of-range index.
             if guid::is_creature_or_pet(guid_c.0) {
                 if let (Some(types), Some(ty)) = (
                     self.creature_types.as_deref(),
@@ -501,24 +346,15 @@ impl TargetScan<'_, '_> {
                     }
                 }
             }
-            // **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.
+            // Deviation: no scene-attach gate (the reference's `0x6704c0`), because the draw
+            // election hides every body outside the frustum, which would empty the off-screen tier.
             let dist = (tf.translation - self_tf.translation).length();
             if dist > TAB_RANGE {
                 trace_unit(guid_c.0, tf, "REJECT range (41 yd)");
                 continue;
             }
             let off_center = project(tf.translation + Vec3::Y);
-            // **Enemy side only.** The bonus exists to surface *the thing attacking me*
-            // (`TargetPriorityCombatLock`'s spirit, decisions 0567/0568) — a notion with no
-            // friendly meaning, and the reference has no such term on either side. Left ungated it
-            // would fire on an ally who is in combat and targeting me — a healer on you — and
-            // shove them to the head of the CTRL-TAB pool ahead of everyone, by accident rather
-            // than by anybody's decision.
+            // Enemy side only: a healer in combat and targeting you would head the CTRL-TAB pool.
             let cwm = side == ScanSide::Enemy && store.is_some_and(|s| combat_with_me(s, me));
             let score = priority_score(off_center, dist, cwm);
             if trace {
@@ -557,17 +393,12 @@ impl TargetScan<'_, '_> {
     }
 }
 
-/// The recent-TAB history (`TargetPriorityHighlightHistoryMs`): guids picked within
-/// [`HISTORY_SECS`], skipped by the forward pick so repeated presses walk fresh targets; a wrap
-/// clears it. Replaces the 1.12 snapshot list + cursor (decision 0567).
+/// Recently picked guids, skipped by the forward pick: the stand-in for 1.12's snapshot cursor.
 #[derive(Resource, Default)]
 pub(super) struct TabHistory {
-    /// `(guid, when)` — insertion-ordered; the back is the most recent (Shift-TAB's walk).
+    /// `(guid, when)`, oldest first.
     visited: Vec<(u64, f64)>,
-    /// Which side the standing history belongs to. **One history, cleared on a side switch** —
-    /// the reference's `cachedMode != mode` rebuild condition (`0x493f60`), which resets the
-    /// cursor to 0 and drops the candidate list whenever the mode byte changes. Without it a
-    /// CTRL-TAB through the friendly pool would poison the enemy cycle's skip set.
+    /// A side switch clears the history, as `0x493f60` rebuilds its list on a mode change.
     side: Option<ScanSide>,
 }
 
@@ -575,7 +406,6 @@ impl TabHistory {
     fn prune(&mut self, now: f64) {
         self.visited.retain(|&(_, t)| now - t < HISTORY_SECS);
     }
-    /// `0x493f60`'s cached-mode check: a press on the other side starts from nothing.
     fn enter(&mut self, side: ScanSide) {
         if self.side != Some(side) {
             self.visited.clear();
@@ -585,51 +415,29 @@ impl TabHistory {
     fn guids(&self) -> Vec<u64> {
         self.visited.iter().map(|&(g, _)| g).collect()
     }
-    /// Record a visit (re-visiting moves the guid to most-recent).
+    /// Record a visit; a re-visit moves the guid to most recent.
     fn push(&mut self, guid: u64, now: f64) {
         self.visited.retain(|&(g, _)| g != guid);
         self.visited.push((guid, now));
     }
 }
 
-/// What one [`commit`] did: whether the selection changed, and whether the engaged-switch law
-/// already re-pointed the swing (`CMSG_ATTACKSWING` at the new target) — the attack branches
-/// read `swung` to avoid double-sending their own swing.
+/// What one [`commit`] did; `swung` means it already sent `CMSG_ATTACKSWING`, so a caller must not.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub(super) struct CommitOutcome {
     pub(super) changed: bool,
     pub(super) swung: bool,
 }
 
-/// 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:
+/// Commit a target through `SetSelection` (`0x493540`). A switch while attacking is stop, select,
+/// re-swing: StopAttack `0x5ecac0` (`0x493a08`) flags a stop in flight (`[player+0xc54]`),
+/// `CMSG_SET_SELECTION` goes out (`0x493857`), then unless the new target is us `Attack 0x5ecb70`
+/// swings past its already-attacking gate, or stops if `new_attackable` is false (`0x4938a1`).
 ///
-/// 1. `0x493637–0x4936ac` latches "attacking AND the old target is still a live attackable unit"
-///    into `[ebp-1]` before anything changes;
-/// 2. the silent old-target clear (`0x493910(current, ecx=0)`) calls **StopAttack `0x5ecac0`
-///    unconditionally at `0x493a08`** (engaged-gated internally) → `CMSG_ATTACKSTOP`, and its
-///    builder `0x624370` sets `[player+0xc54] = 1` ("stop in flight");
-/// 3. the new guid lands in the globals and `CMSG_SET_SELECTION` goes out (`0x493857`);
-/// 4. the tail `0x4938a1–0x4938c8`: iff `[ebp-1]` and the new selection is not MYSELF →
-///    `Attack 0x5ecb70`, which validates the NEW target (alive-or-feign + `CanAttack 0x606980`,
-///    `5ecc10–5ecc35` — an invalid one STOPS instead, `5ecc37`) and then **sends
-///    `CMSG_ATTACKSWING` at it** — `[+0xc54]` bypasses the already-attacking gate (`5eccda`) so
-///    the swing goes out despite the still-set old lock, and the lock re-stores to the new guid
-///    (`5ecd4b`). The swing FOLLOWS the switch (no sheath ceremony: engaged means the weapon is
-///    already out). The `new_attackable` param carries Attack's new-target validation — callers
-///    pass their already-computed classification (the cursor's Attack kind / the scan's
-///    alive+hostile) rather than re-deriving it here.
-///
-/// Approximations, disclosed: `[ebp-1]`'s old-target legs (alive-or-feign + `CanAttack` + the
-/// `0x605f30`/`+0x1fc` player-state gates) collapse to "an old selection existed" — on vmangos
-/// the victim's death tears `Engaged` down via the echoed `SMSG_ATTACKSTOP` before a human can
-/// TAB, so `engaged && had_old` covers the same observable; our `engaged` is the server-echoed
-/// [`Engaged`], not the ref's instant local lock (one-RTT lag on a switch fired mid-attack-
-/// start); and the ref's invalid-new-target Attack sends a second (duplicate) ATTACKSTOP we
-/// don't. Shared with the UI's `TargetUnit` drain (`super::target_unit_requests`) so every
-/// non-mouse selection writer commits identically — a `TargetUnit("player")` mid-combat stops
-/// the swing and does NOT re-point (the tail's self exception).
+/// The latch (`0x493637`) reduces to `engaged && had_old`: vmangos ends [`Engaged`] when the
+/// victim dies, before a TAB can land, so the old target's own legs change nothing seen.
+/// `engaged` is the server's echo, a round trip behind the reference's local lock, and the
+/// reference's second `CMSG_ATTACKSTOP` for an invalid new target is not sent here.
 pub(super) fn commit(
     selection: &mut Selection,
     seam: &mut crate::creature_anim::AttackSeam,
@@ -640,39 +448,26 @@ pub(super) fn commit(
     self_guid: Option<u64>,
     new_attackable: bool,
 ) -> CommitOutcome {
-    // **`IsSelectable`, and it comes BEFORE the dedup** — `0x4935ec`–`0x4935f3`, the third of
-    // `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.
-    //
-    // This is the one gate, at the one place the reference puts it, so every writer — the click,
-    // the right-click, TAB, `TargetUnit`/`/target`/`/assist`, the attack auto-acquire and the
-    // ATTACKERSTATEUPDATE self-defence acquire — is covered without knowing it exists. Without it
-    // a Stratholme Baron Rivendare in his pre-event state (vmangos gives him `NOT_SELECTABLE |
-    // SPAWNING` until the ziggurats fall) took a target on the very swing he opened with.
+    // `IsSelectable`, before the dedup (`0x4935ec`–`0x4935f3`): a non-selectable unit is a complete
+    // no-op that keeps the current target, for every selection writer.
     if !super::relations::is_selectable(target_store, self_guid) {
         return CommitOutcome::default();
     }
     if selection.guid == Some(guid) {
-        return CommitOutcome::default(); // the setter's dedup: bail if already current
+        return CommitOutcome::default(); // the setter's dedup
     }
     let had_old = selection.guid.is_some();
     selection.target = Some(entity);
     selection.guid = Some(guid);
     let stop_and_repoint = engaged && had_old;
     if stop_and_repoint {
-        // `0x493a08 call 0x5ecac0` — the real StopAttack, so the switch also cancels a queued
-        // on-next-swing strike (the seam's `0x6e6f30` tail). Before this routed through the seam
-        // it was a bare `CMSG_ATTACKSTOP` and a queued Heroic Strike survived the switch.
+        // `0x493a08`: the real StopAttack, which also un-queues a next-swing strike (`0x6e6f30`).
         seam.stop(engaged);
     }
     let _ = seam.net.0.send(ClientCommand::SetSelection { guid });
     let swung = stop_and_repoint && new_attackable && self_guid != Some(guid);
     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 —
-        // this chain does reach `0x6ea080`, which a direct-callers-only census misses.
+        // `0x4938c8`: the swing goes out despite the lock, and cancels auto-repeat (`0x6ea080`).
         seam.start(guid, engaged, true);
     }
     CommitOutcome {
@@ -681,13 +476,8 @@ pub(super) fn commit(
     }
 }
 
-/// **One press, either side** — the whole of the Classic-priority cycle, shared by the enemy TAB
-/// ([`tab_target`]) and the friendly one ([`target_nearest_friend_requests`]) because the
-/// reference shares it too: all four `TargetNearest*` shims are one call into `0x493f60` with a
-/// different mode byte, and the byte reaches only the per-candidate filter ([`ScanSide`]).
-///
-/// Re-score the live world, pool by tier, skip the recent history forward (or walk it backward),
-/// commit through the byte-law [`commit`].
+/// One press on either side, as every `TargetNearest*` shim shares `0x493f60`: score the live
+/// world, pool by tier, walk the history forward or back, and [`commit`].
 fn cycle(
     side: ScanSide,
     reverse: bool,
@@ -728,8 +518,7 @@ fn cycle(
             }
         );
     }
-    // The pick. Reverse walks the history back ([`pick_back`]); an empty walk falls through to the
-    // forward rule.
+    // Reverse walks the history back; an empty walk falls through to the forward pick.
     let visited = history.guids();
     let back = reverse
         .then(|| pick_back(&visited, &pool, selection.guid))
@@ -746,8 +535,7 @@ fn cycle(
     if wrapped {
         history.visited.clear();
     }
-    // The outgoing selection joins the history — a clicked target counts as visited once
-    // tabbed away from (`TargetPriorityContinueFromManualTarget`'s observable).
+    // The outgoing selection joins the history (`TargetPriorityContinueFromManualTarget`).
     if let Some(old) = selection.guid {
         history.push(old, now);
     }
@@ -758,17 +546,11 @@ fn cycle(
         guid,
         scan.store_at(entity),
         engaged,
-        // The real guid, where this used to pass `None`: `IsSelectable`'s `CREATEDBY` clause reads
-        // it. Inert for the swing leg it was already feeding — the candidate query excludes our own
-        // body, so a TAB pick can never *be* us.
+        // `IsSelectable`'s `CREATEDBY` clause reads it.
         scan.self_guid(),
-        // Attack `0x5ecb70`'s new-target validation, which is what this flag carries: a mode-2
-        // pick can never pass it. `CanAssist` demands reaction ≥ 4 and `CanAttack`'s mixed arm
-        // demands < 4, so the two candidate sets are disjoint on that leg — a CTRL-TAB in the
-        // middle of a fight moves the selection and must NOT re-point the swing at an ally.
-        // (Disclosed corner: `CanAttack`'s duel / FFA-PvP arms don't read the reaction, so a
-        // duelling friendly is attackable AND assistable; we still refuse the re-swing there,
-        // which is the conservative half.)
+        // `Attack 0x5ecb70`'s validation, which a mode-2 pick fails (reaction >= 4 against
+        // `CanAttack`'s < 4). A duelling friendly passes `CanAttack`'s duel arm, which reads no
+        // reaction, so the reference's `Attack` would re-swing at it; here it gets none.
         side == ScanSide::Enemy,
     );
     if out.changed {
@@ -788,9 +570,8 @@ fn cycle(
     }
 }
 
-/// TARGETNEARESTENEMY / TARGETPREVIOUSENEMY (0997: two commands through the binding table now,
-/// defaults TAB / SHIFT-TAB — no shift fork here anymore). The dispatch already applied the typing
-/// gate (a focused EditBox owns TAB) and the exact-modifier law.
+/// The `TARGETNEARESTENEMY` and `TARGETPREVIOUSENEMY` bindings (TAB, SHIFT-TAB); the dispatch has
+/// already applied the typing gate and the modifier match.
 pub(super) fn tab_target(
     binds: Res<crate::bindings::BindingsState>,
     time: Res<Time>,
@@ -816,17 +597,8 @@ pub(super) fn tab_target(
     );
 }
 
-/// Drain `TargetNearestFriend([reverse])` — the same cycle with mode 2 (`0x489aa0` →
-/// `0x493f60(reverse, 2)`).
-///
-/// Lua-driven rather than binding-driven, because that is where the reference puts it: TAB reaches
-/// the enemy scan through a Rust command here only because 0997 wired the two enemy commands
-/// straight to [`tab_target`]; the friendly pair's `Bindings.xml` bodies are literally
-/// `TargetNearestFriend()` and `TargetNearestFriend(1)`, so a binding row for them needs no new
-/// mechanism — it needs the global, which now exists. Every FrameXML and addon caller lands here
-/// too.
-///
-/// Each queued press is one cycle, in call order, exactly as repeated key presses would be.
+/// Drain `TargetNearestFriend([reverse])` (`0x489aa0` → `0x493f60(reverse, 2)`), one cycle per
+/// call in call order; the stock bindings reach it through their `Bindings.xml` bodies.
 pub(super) fn target_nearest_friend_requests(
     script: Option<NonSendMut<benilla_ui::script::UiScript>>,
     time: Res<Time>,
@@ -859,24 +631,9 @@ pub(super) fn target_nearest_friend_requests(
     }
 }
 
-/// `0x6130b5` — **`TargetNearestEnemy()` itself**, and the whole of "pressing Attack at nothing
-/// finds something in front of you".
-///
-/// The acquire the validator runs is not a private helper: it is `0x493f60(ecx = 0, edx = 1)`, the
-/// same cycler the four Lua `TargetNearest*` bindings drive (`0x489a80`–`0x489af3` are the same
-/// call with `edx = 1..4` for enemy / friend / party / raid, and `ecx` the *reverse* flag). So
-/// "in front of me" is not a separate rule with its own cone — it is this module's priority scan,
-/// which is why the acquire commits through [`commit`] like any press: `CMSG_SET_SELECTION` goes
-/// out and **your** target really moves, which is what lets the pet's order and your own swing
-/// aim at the same thing.
-///
-/// Returns the committed `(entity, guid)`, or `None` after raising `0x6130d9`'s
-/// `ERR_NO_ATTACK_TARGET`.
-///
-/// Divergence, deliberate and inherited: the reference's cycler keeps a cached, time-expiring
-/// candidate list and a cursor into it, so a *repeated* acquire walks; ours re-scores the live
-/// world every call and always hands back the head. That is decision 0567's trade for the whole
-/// module (history cycling replaces the snapshot cursor), and an acquire is a fresh pick in both.
+/// The attack acquire (`0x6130b5`) is `TargetNearestEnemy()` itself, `0x493f60(0, 1)`, so it moves
+/// the player's target. Deviation: a repeated acquire returns the same head, where the reference's
+/// cursor walks on, because this module re-scores the live world on every call.
 fn acquire_nearest_enemy(
     scan: &TargetScan,
     selection: &mut Selection,
@@ -885,17 +642,14 @@ fn acquire_nearest_enemy(
 ) -> Option<(Entity, u64)> {
     let cands = scan.build(ScanSide::Enemy);
     let Some(c) = cands.first() else {
-        // `0x6130d9` — the acquire ran and came back empty, so the selection re-read at `0x6130c1`
-        // still finds nothing: errorId `0xa0` `ERR_NO_ATTACK_TARGET`.
+        // `0x6130d9`: still nothing after the acquire, error `0xa0`.
         debug!("attack acquire: nothing to attack (ERR_NO_ATTACK_TARGET)");
         errors
             .0
             .push(crate::ui_action::UiError::key("ERR_NO_ATTACK_TARGET"));
         return None;
     };
-    // `engaged = false`: the switch law only fires when we were already swinging at the OLD
-    // selection, and every path that reaches here had no selection or a non-hostile one — neither
-    // is a thing you can be engaged with.
+    // Not engaged: every path here held no selection or a non-hostile one.
     commit(
         selection,
         seam,
@@ -909,50 +663,21 @@ fn acquire_nearest_enemy(
     Some((c.entity, c.guid))
 }
 
-/// `0x612df0`'s **Phase B** — the attack order's *target* arm, and the reason pressing the pet's
-/// Attack button at nothing still sends the pet at something.
-///
-/// Phase A (the actor's own eligibility — [`crate::ui_action::attack_actor_refusal`]) has already
-/// run by the time this is reached; what is left is choosing **what** to attack. The candidate the
-/// caller passes is `{0,0}` for a bare press, and it gets replaced by the current selection twice
-/// over — once by `CastPetAction` itself for a nil Lua argument (`0x4bd212`), once by the
-/// validator for a `{0,0}` candidate (`0x61306b`) — so the candidate *is* the selection:
-///
-/// ```text
-/// 0x61306b  candidate == 0             -> candidate = the current selection
-/// 0x61309b  0x6061e0(actor, candidate) -> the actor's reaction toward it
-/// 0x6130a3  reaction >= 4              -> candidate = 0   (friendly or neutral is not a target)
-/// 0x613100  else 0x493540(candidate)   ; promote it into the selection (a dedup when it came from there)
-/// 0x6130b5  candidate == 0             -> 0x493f60(0, 1) == TargetNearestEnemy()
-/// 0x6130c1  re-read the selection      ; whatever the acquire committed
-/// 0x6130d9  still nothing              -> ERR_NO_ATTACK_TARGET, EAX = 0, no packet
-/// 0x613167  final gate                 -> ERR_INVALID_ATTACK_TARGET, EAX = 0, no packet
-/// ```
-///
-/// Two things fall out that are worth knowing before looking at it in game. **Pressing Attack
-/// while you hold a friendly target retargets you** — the reaction test drops it and the acquire
-/// runs, so your selection moves to the nearest enemy. And the guid this returns is what goes in
-/// the packet: the validator writes its answer back through the caller's out-param (`0x6130c6`),
-/// and `0x4bd491` reads that slot when it builds `CMSG_PET_ACTION`.
-///
-/// The final gate is transcribed rather than folded into the reaction test above it, because the
-/// reference deliberately keeps them apart: a *dead* selection is `ERR_INVALID_ATTACK_TARGET`, not
-/// a reason to go find something else. `0x613159`'s odd second leg is verbatim — a zero-health
-/// target passes iff `UNIT_DYNAMIC_FLAGS` bit 5 is set.
+/// `0x612df0`'s target arm: the selection (`0x61306b`) if the actor is hostile to it (`0x6130a3`),
+/// else an acquire (`0x6130b5`), then the final gate (`0x613167`). The result is the guid
+/// `CMSG_PET_ACTION` carries (`0x4bd491`); a dead selection is `ERR_INVALID_ATTACK_TARGET`, not a
+/// reason to acquire.
 pub(crate) fn attack_order_target(
     scan: &TargetScan,
     selection: &mut Selection,
     seam: &mut crate::creature_anim::AttackSeam,
     errors: &mut crate::ui_action::UiErrorKeys,
 ) -> Option<u64> {
-    // `0x61306b` + `0x6130a3`: the selection is the candidate, and it survives only if the actor is
-    // hostile to it. Otherwise `0x6130b5` acquires.
     let guid = match keeps_held_target(selection.guid, |g| scan.reaction_hostile(g)) {
         Some(kept) => kept,
         None => acquire_nearest_enemy(scan, selection, seam, errors)?.1,
     };
-    // `0x613167`'s final gate on whatever we ended up with. `0x61312e`'s legs are the ACTOR's and
-    // are Phase A's, already run by the caller; these two are the target's.
+    // `0x613167`'s target legs; its actor legs (`0x61312e`) ran in the caller.
     let store = scan.unit_by_guid(guid).and_then(|(_, s)| s);
     if !attack_target_valid(
         store,
@@ -969,29 +694,15 @@ pub(crate) fn attack_order_target(
     Some(guid)
 }
 
-/// `0x6130a3`'s fork on its own: keep what you are holding, or fall through to the acquire.
-///
-/// The whole content is that **the reaction alone decides**, and it decides against the *actor*.
-/// A friendly or neutral selection is not "an invalid target" — the reference zeroes the candidate
-/// (`0x6130a8`) and goes looking, which is why pressing pet-Attack while you have a quest giver
-/// selected moves your target to the nearest mob instead of raising an error.
+/// `0x6130a3`: keep a selection the actor is hostile to. A friendly or neutral one is dropped
+/// (`0x6130a8`) and the acquire runs, so pet-Attack with a quest giver selected retargets a mob.
 fn keeps_held_target(selection: Option<u64>, hostile: impl Fn(u64) -> bool) -> Option<u64> {
     selection.filter(|&g| hostile(g))
 }
 
-/// `0x613152`–`0x613169` — the final gate's two **target** legs, whatever route the guid arrived
-/// by.
-///
-/// - alive, transcribed verbatim including its odd second half: a zero-health target passes iff
-///   `UNIT_DYNAMIC_FLAGS` bit 5 is set (`0x613159 shr edx,5; test dl,1`);
-/// - `CanAttack 0x606980` — the full predicate this time, not the bare reaction the fork above uses.
-///
-/// A target with no streamed descriptor is alive by the first leg (nothing known to disqualify) and
-/// then **refused by the second**, which is [`can_attack`]'s own missing-data posture since 1674:
-/// the reference reaches this gate holding two live CGUnits and has no null path at all, so the
-/// honest stand-in is to refuse rather than to swing at an object we know nothing about. The result
-/// is `ERR_INVALID_ATTACK_TARGET`, which is the same answer the gate gives for every other way a
-/// target can be wrong.
+/// The final gate's target legs (`0x613152`–`0x613169`): alive, where a zero-health target passes
+/// iff `UNIT_DYNAMIC_FLAGS` bit 5 is set (`0x613159`), and the full `CanAttack 0x606980`. A target
+/// with no descriptor fails [`can_attack`]; the reference always holds a live unit here.
 fn attack_target_valid(
     store: Option<&ObjectStore>,
     factions: Option<&Factions>,
@@ -1004,17 +715,11 @@ fn attack_target_valid(
     alive && can_attack(store, factions, reputations, self_store)
 }
 
-/// Request from the action layer: the attack action fired with NO selection — pick the best
-/// candidate and swing at it (`0x612df0` @ `6130b5`).
+/// The attack action fired with no selection: acquire and swing (`0x612df0` at `0x6130b5`).
 #[derive(Message)]
 pub(crate) struct AttackNearestRequest;
 
-/// Auto-acquire on attack (behavior 1): a fresh scan, commit the best candidate (the sort's
-/// head — best on-screen, else best overall), then the attack-start pair (auto-draw +
-/// `CMSG_ATTACKSWING`, exactly the action-bar attack's path). None found ⇒ the reference shows
-/// error `0xa0` "There is nothing to attack" (we log; the red error banner is its own arc). The
-/// TAB history is not touched — an auto-pick is not a press (Classic's
-/// `TargetPriorityAutoTargetIgnoreWindow` nuance, disclosed unmodeled).
+/// Acquire the best candidate and start attacking it; the TAB history is untouched.
 pub(super) fn acquire_and_attack(
     mut requests: MessageReader<AttackNearestRequest>,
     scan: TargetScan,
@@ -1027,12 +732,9 @@ pub(super) fn acquire_and_attack(
         return;
     }
     if selection.guid.is_some() {
-        return; // something got selected between the action and this frame — the normal path owns it
+        return; // selected since the action: the normal path owns it
     }
-    // The actor-eligibility block (decision 0481, widened to `0x612df0`'s full Phase A): every one
-    // of its refusals sits BEFORE the nearest-core `0x6130b5` — a mounted, stunned or dead press
-    // never even scans. Gated at the responder so every requester (the Attack button's no-target
-    // arm, the melee probe) shares it. The actor here is us.
+    // `0x612df0`'s actor checks precede the acquire: a mounted, stunned or dead press never scans.
     let self_guid = scan
         .self_q
         .iter()
@@ -1046,67 +748,27 @@ pub(super) fn acquire_and_attack(
     ) {
         return;
     }
-    // `0x6130b5` and `0x6130d9`, shared with the pet bar's ATTACK arm — see
-    // [`acquire_nearest_enemy`]. The selection is empty (checked above), which is exactly the
-    // `candidate == 0` leg of [`attack_order_target`]; the follow-through below is what differs.
     let Some((_, guid)) =
         acquire_nearest_enemy(&scan, &mut selection, &mut seam, &mut ui_error_keys)
     else {
         return;
     };
     debug!("attack acquire: best candidate {guid:#x} → select + swing");
-    // `0x6131a0`'s continuation — StartAttack through the one seam, so the acquire path gets the
-    // auto-draw AND the auto-repeat cancel its hand-rolled copy used to miss. The selection was
-    // empty on entry, so we cannot have been engaged: no stop is in flight.
+    // `0x6131a0`: StartAttack through the seam, with no stop in flight.
     seam.start(guid, false, false);
 }
 
-/// **`TargetLastEnemy`'s memory** — the last *attackable* unit that was selected.
-///
-/// 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). 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.
-///
-/// **A stale guid is never cleared and never resurrects anything.** The reference's globals are
-/// plain guids that nothing zeroes when the unit despawns; what protects it is the shim's route
-/// through the select-if-resolves helper `0x489a40`, whose third arm — the guid resolves to no
-/// streamed object and is on no roster — is a bare `ret`: **not a deselect**. So we keep the guid
-/// and let the drain no-op on it (`crate::target::click`), which is the same observable.
+/// `TargetLastEnemy`'s memory, the reference's last-attackable guid `[0xb4e2e8]`, read at
+/// `0x489b45` and written at `0x49377d` in `SetSelection`. Never cleared: an unresolved guid is a
+/// bare `ret` in the select helper `0x489a40`, not a deselect.
 #[derive(Resource, Default)]
 pub(crate) struct LastEnemy(pub(crate) Option<u64>);
 
-/// Stamp [`LastEnemy`] from the frame's settled selection — the `0x49377d` write, sampled at the
-/// end of the target chain rather than threaded through [`commit`].
+/// Stamp [`LastEnemy`] behind the five-conjunct gate `0x49372f`–`0x493778`. Runs before
+/// `ring::update_ring`'s death-clear: a hostile that dies while selected stays remembered.
 ///
-/// Sampling is not a shortcut: the observable "the last attackable guid I had selected" is the
-/// same either way, because the only guid a commit could stamp is the one still standing here.
-/// What it buys is that every present and future selection writer — the click, TAB, the two
-/// auto-acquires, `TargetUnit`, `/target`, `/assist` — is covered without knowing this exists.
-///
-/// **Ordered before `ring::update_ring`'s death-clear on purpose**: a hostile that dies while
-/// selected must still be remembered, because the reference's shim has no liveness gate either —
-/// `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: 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
-/// dead or ghost, or targeting an already-dead one — which is a `TargetLastEnemy` that lands
-/// somewhere the real client's would not.
-///
-/// The odd-looking fourth conjunct is transcribed rather than simplified: `HEALTH > 0` **or** the
-/// dead-looking dynflag, so a feigning unit stays remembered while a genuinely dead one does not.
-///
-/// One disclosed divergence from a commit-time stamp remains, and it is the sampling itself: a
-/// unit selected while neutral that *turns* hostile while still selected is remembered here and
-/// would not be at the reference's write, which runs once at `SetSelection`. That is the better
-/// answer of the two, and it is the only case where they differ.
+/// Deviation: sampled each frame, not stamped in `SetSelection`, so every selection writer is
+/// covered; a selected unit that turns hostile is remembered, where the reference's is not.
 pub(super) fn remember_last_enemy(
     selection: Res<Selection>,
     stores: Query<&ObjectStore>,
@@ -1118,38 +780,33 @@ pub(super) fn remember_last_enemy(
     let Some((entity, guid)) = selection.target.zip(selection.guid) else {
         return;
     };
-    // Conjunct 1: the player object resolves at all.
+    // Conjunct 1: the player object resolves.
     let Some(me) = self_store.iter().next() else {
         return;
     };
-    // Conjuncts 2 and 3 — the two states of OUR body that suppress the stamp. `player_is_ghost`
-    // is its own read because a ghost's wire health is 1, so `unit_is_dead` is false for one
-    // (`player.rs`'s note on the UnitIsDead/UnitIsGhost/UnitIsDeadOrGhost trio).
+    // Conjuncts 2 and 3: not dead or a ghost (a ghost's wire health is 1), and not mounted.
     if me.0.unit_is_dead() || me.0.player_is_ghost() || me.0.unit_mount_display_id() != 0 {
         return;
     }
     let store = stores.get(entity).ok();
-    // Conjunct 4 — the new target is not a corpse. Verbatim: health, OR the dead-looking flag.
+    // Conjunct 4: health, or the dead-looking flag, so a feigning target stays remembered.
     let alive_enough = store.is_some_and(|s| !s.0.unit_is_dead() || s.0.unit_dynflag_dead());
     if !alive_enough {
         return;
     }
-    // Conjunct 5.
+    // Conjunct 5: `CanAttack(player, new)`.
     if can_attack(store, factions.as_deref(), &reputations, Some(me)) {
         last.0 = Some(guid);
     }
 }
 
-/// Auto-acquire the attacker (behavior 2): the ATTACKERSTATEUPDATE victim handler's
-/// self-defense block (`6259c9`–`6259fe`) — packet victim == me AND my selection strictly
-/// empty → `SetSelection(attacker)`. Selection only: no counter-attack, never overwrites.
+/// The ATTACKERSTATEUPDATE self-defence acquire (`0x6259c9`–`0x6259fe`): when we are the victim
+/// and hold no selection, select the attacker, with no counter-attack.
 pub(super) fn auto_acquire_attacker(
     mut swings: MessageReader<SwingMessage>,
     self_player: Query<(Entity, &Guid), With<SelfPlayer>>,
     guids: Query<&Guid>,
-    // The attacker's descriptor — `0x493540`'s `IsSelectable` gate reads it. A mob that swings at
-    // us while flagged `NOT_SELECTABLE` must not become our target: this is the acquire the
-    // Stratholme Baron's opening hit came in on.
+    // For `IsSelectable`: a `NOT_SELECTABLE` attacker is not acquired.
     stores: Query<&ObjectStore>,
     mut selection: ResMut<Selection>,
     mut seam: crate::creature_anim::AttackSeam,
@@ -1171,7 +828,7 @@ pub(super) fn auto_acquire_attacker(
             "auto-target: attacker {:#x} (victim = me, no target)",
             guid.0
         );
-        // Selection is empty here (checked above): no engaged-switch law, selection only.
+        // The selection was empty, so no switch law: selection only.
         commit(
             &mut selection,
             &mut seam,
@@ -1201,8 +858,8 @@ mod tests {
         go_with(world, guid, None, engaged, self_guid, attackable)
     }
 
-    /// …and the same with a descriptor for the new target, which is what `IsSelectable` reads.
-    /// `None` is the reference's *unresolved* object (`0x4935c8`), which skips the vcall.
+    /// `go` with the new target's descriptor; `None` is an unresolved object, which skips
+    /// `IsSelectable` (`0x4935c8`).
     fn go_with(
         world: &mut World,
         guid: u64,
@@ -1231,7 +888,7 @@ mod tests {
             .expect("commit runs as a one-shot system")
     }
 
-    /// A world with everything the seams need, and nothing else — both commit tests' fixture.
+    /// A world with just what the seams need.
     fn commit_world() -> (World, crossbeam_channel::Receiver<ClientCommand>) {
         let (tx, rx) = crossbeam_channel::unbounded();
         let mut world = World::new();
@@ -1245,18 +902,8 @@ mod tests {
         (world, rx)
     }
 
-    /// The `SetSelection` wire law, byte-read from `0x493540` (the director's "TAB while
-    /// auto-attacking kills the attack" bug): an engaged SWITCH is **stop → select → re-swing**
-    /// — the attack follows the new target — while a plain select sends only the selection, a
-    /// self-target stops without re-pointing, and an unattackable new target (Attack `0x5ecb70`'s
-    /// validation) switches and stops but never swings.
-    ///
-    /// Driven through a World because `commit` now runs the two real seams
-    /// ([`crate::creature_anim::AttackSeam`]) rather than emitting bare packets — which is what
-    /// the second half of this test pins: the switch's stop un-queues an on-next-swing strike
-    /// (`0x493a08 call 0x5ecac0` → `0x6e6f30`) and its re-swing cancels a running auto-repeat
-    /// (`0x4938c8 call 0x5ecb70` → `0x5ecd8c`). Both were missing while this path hand-rolled
-    /// its own packets.
+    /// `0x493540`: an engaged switch is stop, select, re-swing; the stop un-queues an on-next-swing
+    /// strike (`0x6e6f30`) and the re-swing cancels auto-repeat (`0x5ecd8c`).
     #[test]
     fn commit_follows_the_stop_select_reswing_law() {
         let (mut world, rx) = commit_world();
@@ -1280,12 +927,12 @@ mod tests {
         assert!(!go(&mut world, 0xB, false, Some(1), true).changed);
         assert_eq!(drain(&rx), ["select", "select"]);
 
-        // Engaged switch onto an attackable unit: the byte order stop → select → swing.
+        // Engaged switch onto an attackable unit: stop, select, swing.
         let out = go(&mut world, 0xC, true, Some(1), true);
         assert!(out.changed && out.swung);
         assert_eq!(drain(&rx), ["stop", "select", "swing"]);
 
-        // Engaged switch onto MYSELF (TargetUnit("player") mid-combat): stop, no re-point.
+        // Engaged switch onto myself (`TargetUnit("player")` mid-combat): stop, no re-point.
         let out = go(&mut world, 0x1, true, Some(1), true);
         assert!(out.changed && !out.swung);
         assert_eq!(drain(&rx), ["stop", "select"]);
@@ -1295,15 +942,13 @@ mod tests {
         assert!(out.changed && !out.swung);
         assert_eq!(drain(&rx), ["stop", "select"]);
 
-        // Engaged FIRST select (no old target): the [ebp-1] latch is off — selection only.
+        // Engaged first select, no old target: the latch is off, selection only.
         *world.resource_mut::<Selection>() = Selection::default();
         let out = go(&mut world, 0xE, true, Some(1), true);
         assert!(out.changed && !out.swung);
         assert_eq!(drain(&rx), ["select"]);
 
-        // **The two edges the seam brought.** A queued strike and a running auto-repeat, then an
-        // engaged switch onto an attackable unit: the stop un-queues the strike, the re-swing
-        // kills the repeat.
+        // A queued strike and auto-repeat: the stop un-queues one, the re-swing ends the other.
         world
             .resource_mut::<crate::spell::QueuedMeleeSpell>()
             .arm(78);
@@ -1326,13 +971,9 @@ mod tests {
         );
     }
 
-    /// **`IsSelectable` refuses the whole commit** — `0x493540`'s third early-out
-    /// (`0x4935ee`/`0x4935f3`), which sits *before* the dedup, so the refusal is a complete no-op:
-    /// nothing on the wire, no `PLAYER_TARGET_CHANGED`, and the target already in hand survives.
-    ///
-    /// The reported case is Stratholme's Baron Rivendare before the ziggurats fall — vmangos gives
-    /// him `UNIT_FLAG_NOT_SELECTABLE | UNIT_FLAG_SPAWNING` (`instance_stratholme.cpp`), so on the
-    /// real client he can be neither clicked, tabbed, nor auto-acquired when he opens on you.
+    /// `IsSelectable` refuses the whole commit before the dedup (`0x4935ee`/`0x4935f3`): nothing is
+    /// sent and the held target survives. vmangos flags the pre-event Baron Rivendare this way
+    /// (`instance_stratholme.cpp:224`).
     #[test]
     fn not_selectable_refuses_the_commit_and_keeps_the_old_target() {
         use benilla_protocol::ObjectFields;
@@ -1340,8 +981,7 @@ mod tests {
         const CREATEDBY: u16 = 14;
         const OBJECT_TYPE: u16 = 2;
         const NOT_SELECTABLE: u32 = 1 << 25;
-        // `OBJECT_FIELD_TYPE` bit 3 = a CGUnit_C, the only kind whose slot `+0x58` is not the
-        // `xor eax,eax` base stub.
+        // `OBJECT_FIELD_TYPE` bit 3, a unit: the only kind whose `+0x58` slot is not the base stub.
         let unit = |pairs: &[(u16, u32)]| {
             let mut all = vec![(OBJECT_TYPE, 0x8u32)];
             all.extend_from_slice(pairs);
@@ -1351,12 +991,11 @@ mod tests {
         let (mut world, rx) = commit_world();
         let sent = |rx: &crossbeam_channel::Receiver<ClientCommand>| rx.try_iter().count();
 
-        // A plain live mob commits.
         let plain = unit(&[]);
         assert!(go_with(&mut world, 0xA, Some(plain), false, Some(1), true).changed);
         assert_eq!(sent(&rx), 1);
 
-        // The Baron: flagged, created by nobody. Refused outright — and 0xA is still the target.
+        // The Baron: flagged, created by nobody, refused; 0xA is still the target.
         let baron = unit(&[(FLAGS, NOT_SELECTABLE | 0x2)]);
         let out = go_with(&mut world, 0xB, Some(baron), true, Some(1), true);
         assert!(!out.changed && !out.swung, "the commit is a complete no-op");
@@ -1367,7 +1006,7 @@ mod tests {
             "the target already in hand survives the refused click"
         );
 
-        // The `CREATEDBY` clause: the same flag on a unit **I** created still selects (my totem).
+        // The `CREATEDBY` clause: the same flag on a unit I created still selects (my totem).
         let mine = unit(&[(FLAGS, NOT_SELECTABLE), (CREATEDBY, 1), (CREATEDBY + 1, 0)]);
         assert!(go_with(&mut world, 0xC, Some(mine), false, Some(1), true).changed);
         assert_eq!(sent(&rx), 1);
@@ -1377,12 +1016,12 @@ mod tests {
         assert!(!go_with(&mut world, 0xD, Some(theirs), false, Some(1), true).changed);
         assert_eq!(sent(&rx), 0);
 
-        // A non-unit object answers the base stub — a GameObject guid can never be the selection.
+        // A non-unit object answers the base stub: a GameObject is never the selection.
         let go_obj = ObjectStore(ObjectFields::from_pairs(&[(OBJECT_TYPE, 0x20)]));
         assert!(!go_with(&mut world, 0xE, Some(go_obj), false, Some(1), true).changed);
         assert_eq!(sent(&rx), 0);
 
-        // And an unresolved object skips the vcall entirely (the out-of-range party member).
+        // An unresolved object (an out-of-range party member) skips the check.
         assert!(go_with(&mut world, 0xF, None, false, Some(1), true).changed);
         assert_eq!(sent(&rx), 1);
     }
@@ -1396,28 +1035,21 @@ mod tests {
         }
     }
 
-    /// The priority value: a centered far mob beats a screen-edge close one; a close central
-    /// mob beats a far central one; the fighting-me bonus dominates both terms.
     #[test]
     fn priority_score_weighs_center_distance_and_combat() {
-        // Dead-center at 30 yd vs near-the-edge at 3 yd: center wins.
         assert!(
             priority_score(Some(0.05), 30.0, false) < priority_score(Some(0.9), 3.0, false),
             "a centered far mob outranks a screen-edge close one"
         );
-        // Same centrality: nearest wins.
+        // Same centrality: the nearest wins.
         assert!(priority_score(Some(0.2), 5.0, false) < priority_score(Some(0.2), 35.0, false));
-        // Fighting-me beats a perfectly centered peaceful mob at any position in range.
         assert!(
             priority_score(Some(0.9), 40.0, true) < priority_score(Some(0.0), 1.0, false),
             "the combat bonus dominates the geometric terms"
         );
     }
 
-    /// The sort and the pool: on-screen candidates always precede off-screen ones; the pool is
-    /// the on-screen tier when it exists (AllowAnyOnScreen=1), everything otherwise. NO combat
-    /// lock (decision 0568): a fighting-me attacker in the pool never restricts it — TAB can
-    /// always walk off an attacker onto a fresh target (the bonus orders, the history moves).
+    /// No combat lock: an attacker in the pool never shrinks it.
     #[test]
     fn tier_pool_never_locks() {
         let mut v = [cand(1, 0.1, false), cand(2, 5.0, true), cand(3, 0.5, true)];
@@ -1431,12 +1063,11 @@ mod tests {
         // Tier: with any on-screen candidate, off-screen ones drop out of the pool.
         let pool = select_pool(&v);
         assert_eq!(pool.iter().map(|c| c.guid).collect::<Vec<_>>(), [3, 2]);
-        // No on-screen candidates at all → the fallback tier is everything.
+        // No on-screen candidates at all: the fallback tier is everything.
         let off = [cand(1, 0.3, false), cand(2, 0.1, false)];
         assert_eq!(select_pool(&off).len(), 2);
 
-        // An attacker (fighting-me) in the pool does NOT shrink it — the 0568 unlock: with the
-        // attacker current and visited, the pick walks onto the peaceful mob.
+        // With the attacker current and visited, the pick walks onto the peaceful mob.
         let mixed = [cand(1, -2.0, true), cand(2, 0.2, true)];
         let pool = select_pool(&mixed);
         assert_eq!(pool.len(), 2, "no combat lock — the full tier stays");
@@ -1447,9 +1078,6 @@ mod tests {
         );
     }
 
-    /// The forward pick: best unvisited non-current first; exhausted history wraps (caller
-    /// clears it) to the best non-current; a pool of only the current selection returns it
-    /// (the commit dedups to a no-op).
     #[test]
     fn forward_pick_skips_history_then_wraps() {
         let pool = [
@@ -1471,18 +1099,13 @@ mod tests {
             pick_forward(&pool, &[0xA, 0xB, 0xC], Some(0xC)),
             Some((0, true))
         );
-        // Only the current selection in the pool: itself, wrapped (dedup no-op downstream).
+        // Only the current selection in the pool: itself, wrapped, which the commit dedups.
         let solo = [cand(0xA, 0.1, true)];
         assert_eq!(pick_forward(&solo, &[0xA], Some(0xA)), Some((0, true)));
         assert_eq!(pick_forward(&[], &[], None), None);
     }
 
-    /// **Phase B's fork** (`0x6130a3`): a hostile selection is kept, everything else acquires.
-    ///
-    /// The case that reads wrong until you have read the binary is the *friendly* one — it is not
-    /// an error, it is a reason to go find a real target. That is what makes "press Attack with no
-    /// target and the pet goes for what is in front of you" the same code path as "press Attack
-    /// while talking to a vendor and your target jumps to the wolf behind him".
+    /// `0x6130a3`: a friendly selection is a reason to acquire, not an error.
     #[test]
     fn phase_b_keeps_only_a_hostile_selection() {
         let hostile = |g: u64| g == 0xBAD;
@@ -1491,8 +1114,7 @@ mod tests {
         assert_eq!(keeps_held_target(None, hostile), None, "no selection");
     }
 
-    /// The final gate's target legs (`0x613152`–`0x613169`), including the transcribed oddity: a
-    /// zero-health target is invalid **unless** dynamic-flag bit 5 is set.
+    /// `0x613152`–`0x613169`: a zero-health target is invalid unless dynamic-flag bit 5 is set.
     #[test]
     fn the_attack_orders_final_gate_reads_health_then_can_attack() {
         use benilla_protocol::ObjectFields;
@@ -1502,9 +1124,8 @@ mod tests {
         const TPL: u16 = 35;
         let reps = Reputations::default();
         let unit = |pairs: &[(u16, u32)]| ObjectStore(ObjectFields::from_pairs(pairs));
-        // `CanAttack` needs both sides now (1674), and with no catalog both reactions resolve to
-        // neutral — the mixed arm's `< 4`, so a plain live mob is attackable and the legs below
-        // are the ones actually under test.
+        // With no catalog both reactions are neutral, which `CanAttack`'s mixed arm (< 4) admits,
+        // so the legs below decide.
         let me = unit(&[(TPL, 1), (FLAGS, 1 << 3)]);
         let valid = |s: &ObjectStore| attack_target_valid(Some(s), None, &reps, Some(&me));
 
@@ -1518,9 +1139,7 @@ mod tests {
             !valid(&unit(&[(HEALTH, 120), (FLAGS, 1 << 25)])),
             "NOT_SELECTABLE is one of CanAttack's disqualifiers"
         );
-        // No descriptor on either side is a REFUSAL now — see the fn doc. The reference holds two
-        // live CGUnits here and has no null path; swinging at an object we know nothing about was
-        // the approximation's posture, not the binary's.
+        // No descriptor on either side is refused.
         assert!(!attack_target_valid(None, None, &reps, Some(&me)));
         assert!(!attack_target_valid(
             Some(&unit(&[(HEALTH, 120)])),
@@ -1530,14 +1149,8 @@ mod tests {
         ));
     }
 
-    /// The **backward** pick, beside its forward twin: newest-first through the history, skipping
-    /// the current selection and anything that has left the pool; nothing to step back to ⇒ `None`,
-    /// which is what makes the first reverse press fall through to the forward rule.
-    ///
-    /// This is the whole of `reverse` — the flag `TargetNearestEnemy`/`TargetNearestFriend` take as
-    /// their optional Lua argument (`0x489a80`/`0x489aa0` fetch it with `0x6f1c10`, default 0) and
-    /// hand to the one cycler as `ecx`. Forward and backward walk the same order in opposite
-    /// directions: with A,B,C visited in that order, back from C is B and back from B is A.
+    /// `reverse` is the optional Lua argument of `TargetNearestEnemy` and `TargetNearestFriend`
+    /// (fetched with `0x6f1c10`, default 0): back walks the forward order in reverse.
     #[test]
     fn pick_back_walks_the_history_newest_first() {
         let pool = [
@@ -1545,14 +1158,14 @@ mod tests {
             cand(0xB, 0.2, true),
             cand(0xC, 0.3, true),
         ];
-        // Forward over a fresh pool visits A, then B, then C — the order `pick_back` reverses.
+        // Forward over a fresh pool visits A, then B, then C.
         assert_eq!(pick_forward(&pool, &[], None), Some((0, false)));
         assert_eq!(pick_forward(&pool, &[0xA], Some(0xA)), Some((1, false)));
         assert_eq!(
             pick_forward(&pool, &[0xA, 0xB], Some(0xB)),
             Some((2, false))
         );
-        // Back from C is B; back from B is A — the exact reverse of the walk above.
+        // Back from C is B, and back from B is A.
         assert_eq!(pick_back(&[0xA, 0xB, 0xC], &pool, Some(0xC)), Some(1));
         assert_eq!(pick_back(&[0xA, 0xB], &pool, Some(0xB)), Some(0));
         // Nothing behind us: the caller falls through to the forward rule.
@@ -1563,9 +1176,7 @@ mod tests {
         assert_eq!(pick_back(&[0xA, 0xB, 0xC], &shrunk, Some(0xC)), Some(0));
     }
 
-    /// The history is **per side**: a friendly press wipes the enemy cycle's skip set and vice
-    /// versa — the reference's `cachedMode != mode` rebuild condition (`0x493f60`), which drops the
-    /// candidate list and resets the cursor whenever the mode byte changes.
+    /// `0x493f60` rebuilds its list when the mode changes.
     #[test]
     fn a_side_switch_clears_the_history() {
         let mut h = TabHistory::default();
@@ -1588,8 +1199,8 @@ mod tests {
     const F_DUEL_ARBITER: u16 = 188;
     const F_PLAYER_FLAGS: u16 = 190;
     const F_DUEL_TEAM: u16 = 196;
-    /// `UNIT_FLAG_PVP_ATTACKABLE` — behaviourally "player-controlled"; the wire always carries it
-    /// on a player, which is what selects `CanAttack`'s and `CanAssist`'s player arms.
+    /// `UNIT_FLAG_PVP_ATTACKABLE`, always on a player: it selects the player arms of `CanAttack`
+    /// and `CanAssist`.
     const CONTROLLED: u32 = 0x8;
     /// `OBJECT_FIELD_TYPE` for a Player object (OBJECT|UNIT|PLAYER).
     const TYPE_PLAYER: u32 = 0x19;
@@ -1598,23 +1209,9 @@ mod tests {
         ObjectStore(benilla_protocol::ObjectFields::from_pairs(pairs))
     }
 
-    /// **The two sides of one scan, over one world** — the mode byte is the only fork, so this
-    /// drives the real [`TargetScan::build`] twice and asserts each side's pool.
-    ///
-    /// With no `FactionTemplate.dbc` loaded every reaction resolves to neutral, which is exactly
-    /// the regime that separates the two filters: neutral is **attackable** (`CanAttack`'s mixed
-    /// arm is `< 4`) and **not assistable** (`CanAssist`'s ladder is `>= 4`). To get a genuinely
-    /// friendly reaction with no catalog the ally here is a **same-team duel partner** — the one
-    /// rung of `UnitReaction 0x6061e0` that answers 4 off descriptor fields alone (decision 0633).
-    /// It is also a fair model of the real case: `TargetNearestFriend` is mostly about players.
-    ///
-    /// Four candidates pin four separate claims:
-    /// * the neutral mob is an enemy candidate and never a friendly one — **the control that must
-    ///   not change**;
-    /// * the friendly player is a friendly candidate and never an enemy one;
-    /// * a friendly **corpse** is out — mode 2's `UNIT_FIELD_HEALTH > 0` leg;
-    /// * a friendly **feigner** is IN — mode 2 has no `UNIT_DYNFLAG_DEAD` leg, though mode 1's
-    ///   reads-dead triple does. That asymmetry is transcribed, not tidied.
+    /// With no `FactionTemplate.dbc` every reaction is neutral: attackable (`CanAttack`'s mixed
+    /// arm is < 4), not assistable (`CanAssist` needs >= 4). A same-team duel partner is friendly
+    /// from descriptor fields alone (`0x6061e0`). Mode 2 keeps a feigning ally and drops a corpse.
     #[test]
     fn the_two_sides_of_the_scan_never_pick_each_others_units() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1683,20 +1280,12 @@ mod tests {
                 .expect("the scan runs as a one-shot system")
         };
 
-        // Mode 1: the neutral mob only. Every duel-team ally is refused by `CanAttack`'s
-        // both-player-controlled arm (a friendly reaction returns 0 outright).
+        // Mode 1: the neutral mob only; `CanAttack`'s player arm refuses every duel-team ally.
         assert_eq!(pool(&mut world, ScanSide::Enemy), [MOB]);
-        // Mode 2: the live ally and the feigning one — never the mob, never the corpse. With no
-        // camera in the world nothing projects, so the order is pure distance (ALLY at 10 yd
-        // before ALLY_FEIGN at 20).
+        // Mode 2: with no camera the order is pure distance.
         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;
@@ -1725,7 +1314,7 @@ mod tests {
             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).
+            // The election's out-of-view verdict.
             Visibility::Hidden,
         ));
         let pool = world
@@ -1739,13 +1328,7 @@ mod tests {
         assert_eq!(pool, [MOB]);
     }
 
-    /// [`LastEnemy`] tracks the last **attackable** selection and nothing else — `TargetLastEnemy`'s
-    /// whole memory (`[0xb4e2e8]/[0xb4e2ec]`, `0x49377d`).
-    ///
-    /// The three claims that make the verb behave: it follows a hostile switch; a **friendly**
-    /// selection does not overwrite it (that is what separates it from `TargetLastTarget`'s pair);
-    /// and **clearing the target leaves it standing**, which is the whole point — you press `G`
-    /// after an Esc, not before one.
+    /// It follows a hostile switch and survives a friendly selection and a clear (`0x49377d`).
     #[test]
     fn last_enemy_remembers_the_last_attackable_selection_across_a_clear() {
         use bevy::ecs::system::RunSystemOnce;
@@ -1802,15 +1385,12 @@ mod tests {
         );
         assert_eq!(select(&mut world, Some((a, 0xA))), Some(0xA));
         assert_eq!(select(&mut world, Some((b, 0xB))), Some(0xB));
-        // A friendly selection is not an enemy — the memory holds at B.
+        // A friendly selection: the memory holds at B.
         assert_eq!(select(&mut world, Some((friend, 0xF))), Some(0xB));
-        // …and neither is an empty one. This is the case the verb exists for.
+        // So does a clear.
         assert_eq!(select(&mut world, None), Some(0xB));
 
-        // **The four conjuncts besides `CanAttack`** (`0x49372f`-`0x493778`). Each is asserted by
-        // moving one state and re-selecting an ordinary hostile that would otherwise stamp: the
-        // memory has to hold at B every time. Written as one test rather than four because the
-        // whole point is that they are one gate, and a gate with a leg missing is what shipped.
+        // The four conjuncts besides `CanAttack` (`0x49372f`-`0x493778`), one state at a time.
         let dead_mob = world
             .spawn(store(&[(F_HEALTH, 0), (F_MAXHEALTH, 100)]))
             .id();
@@ -1819,7 +1399,7 @@ mod tests {
             Some(0xB),
             "a corpse is not remembered — the target's health leg"
         );
-        // …unless it carries the dead-looking dynflag, which is a FEIGN and stays remembered.
+        // A feigner, with the dead-looking dynflag, is remembered.
         let feigner = world
             .spawn(store(&[
                 (F_HEALTH, 0),
@@ -1833,8 +1413,7 @@ mod tests {
             "`HEALTH > 0 || dynflag 0x20` is an OR, transcribed not simplified"
         );
 
-        // Our own body's three states. Each is set, a live hostile selected, and the memory must
-        // not move off 0xE.
+        // Our own body's three states: with each set, selecting a live hostile leaves 0xE.
         let with_self = |world: &mut World, fields: &[(u16, u32)]| {
             let me = world
                 .query_filtered::<Entity, With<SelfPlayer>>()
@@ -1879,7 +1458,6 @@ mod tests {
         );
     }
 
-    /// The history: pruning honors the window, a re-visit moves to most-recent.
     #[test]
     fn history_prunes_and_reorders() {
         let mut h = TabHistory::default();