diff --git a/CLAUDE.md b/CLAUDE.md
index 2e8df1d..213f325 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -159,24 +159,6 @@ these, ideally all four:
   atlases, shader patterns. Most useful for "how do I do this GL thing
   with Silk.NET on net10 idiomatically?" Less useful for protocol or
   character appearance (dat editor, not game client).
-- **`references/WorldBuilder-ACME-Edition/`** — **Fork of WorldBuilder
-  with decompiled AC client source code.** THE most authoritative
-  reference for any terrain/rendering algorithm. Key files:
-    - `WorldBuilder.Tests/ClientReference.cs` — faithful C# port of
-      decompiled `CLandBlockStruct.cpp` with exact offsets. Ground truth
-      for split direction, palCode, vertex height, vertex position.
-      **Check this BEFORE implementing any terrain algorithm.**
-    - `WorldBuilder.Tests/TerrainConformanceTests.cs` — exhaustive
-      sweeps (4M+ cells) proving ACME matches the retail client.
-    - `StaticObjectManager.cs` — complete GfxObj+Setup rendering with
-      CreaturePalette assembly (the ObjDesc pipeline).
-    - `EnvCellManager.cs` — dungeon cell rendering with portal
-      visibility traversal and collision mesh caching.
-    - `TerrainGeometryGenerator.cs` — `GetHeight()` and `GetNormal()`
-      that match the mesh index buffer exactly.
-  Already proved its value: solved the triangle-boundary Z bug that
-  resisted 5 other fix attempts. Use as the oracle for ALL dat
-  interpretation algorithms.
 - **`references/Chorizite.ACProtocol/`** — clean-room C# protocol
   library generated from a protocol XML description. Useful sanity check
   on field order, packed-dword conventions, type-prefix handling. The
@@ -216,3 +198,65 @@ BEFORE writing acdream code. A single reference can be misleading; the
 intersection of all four is almost always the truth. The user has
 repeatedly had to remind me about this when I narrowly searched one ref
 and missed obvious answers in another.
+
+### Reference hierarchy by domain
+
+**NEVER GUESS an algorithm, formula, constant, wire format, or coordinate
+convention.** Every AC-specific behavior has a reference implementation in
+one of the repos below. If you find yourself writing AC-specific code
+without having read the matching reference first, STOP and read it. The
+triangle-boundary Z bug cost 5 failed fix attempts because we guessed
+instead of checking ACME's `ClientReference.cs` — which had the exact
+decompiled client code and would have fixed it in minutes.
+
+**The rule: read the reference FIRST, write code SECOND. Always.**
+
+| Domain | Primary Oracle | Secondary | Notes |
+|--------|---------------|-----------|-------|
+| **Terrain** (split direction, height sampling, palCode, vertex position, normals) | **ACME `ClientReference.cs`** — decompiled retail client with exact offsets | ACME `TerrainGeometryGenerator.cs` (matches the mesh index buffer) | WorldBuilder original is SUPERSEDED for terrain algorithms. AC2D confirms the same formula. |
+| **Terrain blending** (texture atlas, alpha masks, road overlays) | **ACME `LandSurfaceManager.cs`** | WorldBuilder original `LandSurfaceManager.cs` (same code, less tested) | Both use the same TexMerge pipeline. ACME has conformance tests. |
+| **GfxObj / Setup rendering** (mesh extraction, multi-part assembly, ObjDesc) | **ACME `StaticObjectManager.cs`** — includes CreaturePalette, GfxObjRemapping, HiddenParts | ACViewer `Render/` namespace | ACME has the complete creature appearance pipeline in one file. |
+| **Texture decoding** (INDEX16, P8, DXT, BGRA, alpha) | **ACME `TextureHelpers.cs`** | ACViewer `Render/TextureCache.cs` (palette overlay = `IndexToColor`) | For subpalette overlay specifically, ACViewer's `IndexToColor` is the canonical algorithm. |
+| **EnvCell / dungeon rendering** (cell geometry, portal visibility, collision mesh) | **ACME `EnvCellManager.cs`** — portal traversal, mixed landblock detection, collision cache | ACViewer `Physics/Common/EnvCell.cs` | ACME is significantly more complete than original WorldBuilder for dungeons. |
+| **Network protocol** (wire format, packet framing, fragment assembly, ISAAC) | **holtburger** `crates/holtburger-session/` | AC2D `cNetwork.cpp` (simpler, good for cross-check) | ACE shows the server side; holtburger + AC2D show the client side. |
+| **Client behavior** (what to send when, login flow, ack pattern, keepalive) | **holtburger** `crates/holtburger-core/src/client/` | AC2D `cNetwork.cpp` + `cInterface.cpp` | holtburger is the most complete; AC2D is simpler but confirmed working. |
+| **Movement** (MoveToState format, AutonomousPosition, sequence counters, speed) | **holtburger** `client/movement/` | AC2D `cNetwork.cpp:2592-2664` (0xF61C format) | See `docs/research/2026-04-12-movement-deep-dive.md` for the full cross-reference. |
+| **Server expectations** (what ACE accepts/rejects, validation thresholds) | **ACE** `Source/ACE.Server/Network/` | — | Only ACE knows what the server actually validates. |
+| **Silk.NET / .NET 10 idioms** (GL calls, shader setup, VAO patterns) | **WorldBuilder original** | ACME (same stack) | Both use the same backend; original has cleaner isolated examples. |
+| **Protocol field order** (packed dwords, type prefixes, flag enums) | **Chorizite.ACProtocol** `Types/*.cs` | holtburger (cross-check) | Generated from protocol XML; has accurate field comments. |
+
+### ACME key files quick reference
+
+These are the files you should open FIRST when working on any rendering
+or dat-interpretation task:
+
+- **`WorldBuilder.Tests/ClientReference.cs`** — decompiled retail AC
+  client C# port. `IsSWtoNECut`, `GetPalCode`, `GetVertexHeight`,
+  `GetVertexPosition`. **The ground truth.** If your code disagrees
+  with this file, your code is wrong.
+- **`WorldBuilder.Tests/TerrainConformanceTests.cs`** — 4M+ cell sweep
+  proving ACME matches retail. Port these into acdream's test suite for
+  any algorithm you touch.
+- **`StaticObjectManager.cs`** — GfxObj+Setup+CreaturePalette pipeline.
+- **`EnvCellManager.cs`** — dungeon cells + portal visibility.
+- **`TerrainGeometryGenerator.cs`** — `GetHeight()`, `GetNormal()`,
+  `CalculateSplitDirection()` matching the mesh index buffer.
+- **`TextureHelpers.cs`** — INDEX16, BGRA, DXT decode helpers.
+
+### holtburger key files quick reference
+
+These are the files you should open FIRST when working on any networking
+or client-behavior task:
+
+- **`client/movement/system.rs`** — the movement state machine (when to
+  send MoveToState vs AutonomousPosition, deduplication logic).
+- **`client/movement/actions.rs`** — MoveToState, AutonomousPosition,
+  Jump wire format builders.
+- **`client/movement/types.rs`** — RawMotionState packed format with
+  all flag bits documented.
+- **`session/send.rs`** — packet construction, checksum, ISAAC, ACK
+  piggybacking.
+- **`client/messages.rs`** — post-login message handlers (PlayerCreate
+  → LoginComplete, DddInterrogation → response, PlayerTeleport).
+- **`spatial/physics.rs`** — dead-reckoning solver (how the client
+  advances position between server updates).