docs(CLAUDE.md): consolidated reference hierarchy + never-guess policy

Rewrote the reference repos section with:

1. Clear domain-to-oracle mapping table — every domain (terrain, rendering,
   networking, movement, etc.) has a named primary oracle and secondary
   reference. No ambiguity about which repo to check first.

2. NEVER GUESS policy: "read the reference FIRST, write code SECOND.
   Always." Explicitly calls out the triangle-boundary Z bug as the
   cautionary tale (5 failed fix attempts from guessing vs 1 fix from
   checking ACME's ClientReference.cs).

3. Quick-reference file lists for ACME (6 key files) and holtburger
   (6 key files) so future sessions can jump straight to the right code.

4. WorldBuilder original explicitly marked as SUPERSEDED for terrain
   algorithms (ACME has conformance tests, original doesn't).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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).