docs(architecture): WorldBuilder inventory + CLAUDE.md alignment

Saves the comprehensive inventory of what WorldBuilder provides
(terrain, scenery, static objects, EnvCells, portals, sky, particles,
texture decode, mesh extraction, visibility) vs what acdream still
ports from retail decomp (network, physics, animation, movement, UI,
plugin, audio, chat).

This is the load-bearing reference for the strategic shift from
"port retail algorithms ourselves" to "rely on WorldBuilder for
rendering + dat-handling, port only what WB doesn't cover."

Updates CLAUDE.md:
- Adds top-level instruction: read the inventory FIRST before
  re-porting anything in the 🟢 list
- Reframes references/WorldBuilder/ as acdream's rendering BASE,
  not just a reference repo
- Updates the "Reference hierarchy by domain" table to point
  rendering/dat questions at WorldBuilder, with retail decomp as
  cross-check

Subsequent commits will fork WorldBuilder and replace our terrain/
scenery/object rendering with calls into the fork.

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

CLAUDE.md

@@ -25,6 +25,19 @@ single source of truth for how the client is structured. All work must
 align with this document. When the architecture doc and reality diverge,
 update one or the other — never leave them out of sync.
 
+**WorldBuilder is acdream's rendering + dat-handling base** as of
+2026-05-08. Before re-implementing any AC-specific rendering or
+dat-handling algorithm, **read `docs/architecture/worldbuilder-inventory.md`
+FIRST**. If WorldBuilder has it, port from WorldBuilder (or call into
+our fork once wired up), not from retail decomp. WorldBuilder is
+MIT-licensed, verified to render the world correctly, and uses the same
+Silk.NET stack we target. Re-porting from retail decomp when WB already
+has a tested port is how subtle bugs (the scenery edge-vertex bug, the
+triangle-Z bug) keep slipping in. Retail decomp remains the oracle for
+network, physics, animation, movement, UI, plugin, audio, chat — see
+the inventory doc's 🔴 list for the full scope of "we still write this
+ourselves".
+
 **Execution phases:** R1→R8 in the architecture doc. Each phase has clear
 goals, test criteria, and builds on the previous. Don't skip phases.
 
@@ -625,11 +638,18 @@ these, ideally all four:
   for the palette-indexed formats. See
   `ACViewer/Render/TextureCache.cs::IndexToColor` for the canonical
   subpalette overlay algorithm.
-- **`references/WorldBuilder/`** — C# + Silk.NET dat editor. Exact-stack
-  match to acdream for rendering approaches: terrain blending, texture
-  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/`** — **acdream's rendering + dat-handling
+  BASE (not just a reference).** As of 2026-05-08 acdream is moving to
+  fork WorldBuilder upstream and depend on the fork for terrain,
+  scenery, static objects, EnvCells, portals, sky, particles, texture
+  decoding, mesh extraction, visibility/culling. WorldBuilder is
+  MIT-licensed, exact-stack match (Silk.NET + .NET), and verified to
+  render the world correctly. **Before re-porting any rendering or
+  dat-handling algorithm from retail decomp, check
+  `docs/architecture/worldbuilder-inventory.md` first.** If WB has it,
+  use WB's port. If WB doesn't have it (network, physics, animation,
+  movement, UI, plugin, audio, chat), port from retail decomp as
+  before.
 - **`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
@@ -684,12 +704,15 @@ decompiled client code and would have fixed it in minutes.
 
 | Domain | Primary Oracle | Secondary | Notes |
 |--------|---------------|-----------|-------|
-| **Any AC-specific algorithm** | **`docs/research/named-retail/`** (PDB-named decomp + verbatim retail header structs from Sept 2013 EoR build) | the existing references below | The retail client itself, fully named. 18,366 functions + 5,371 struct types + 1.4 M lines of pseudo-C in one searchable tree. Beats every other reference for "what does the real client do." |
-| **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. |
+| **Any AC-specific algorithm** | **`docs/research/named-retail/`** (PDB-named decomp + verbatim retail header structs from Sept 2013 EoR build) | the existing references below | The retail client itself, fully named. 18,366 functions + 5,371 struct types + 1.4 M lines of pseudo-C in one searchable tree. Beats every other reference for "what does the real client do." Use for everything in the 🔴 list (network, physics, animation, movement, UI, plugin, audio, chat). |
+| **Terrain** (split direction, height sampling, palCode, vertex position, normals) | **WorldBuilder `TerrainGeometryGenerator.cs` + `TerrainUtils.cs`** | retail decomp for cross-check | WB is acdream's terrain base. ACME's port is older/SUPERSEDED by WB. |
+| **Terrain blending** (texture atlas, alpha masks, road overlays) | **WorldBuilder `LandSurfaceManager.cs`** | ACME `LandSurfaceManager.cs` (same algo, less complete) | WB is acdream's blending base. |
+| **Scenery** (procedural placement: trees, bushes, rocks, fences) | **WorldBuilder `SceneryRenderManager.cs` + `SceneryHelpers.cs`** | retail decomp `CLandBlock::get_land_scenes` | WB is acdream's scenery base. Re-porting from retail decomp is what caused the edge-vertex bug. |
+| **GfxObj / Setup rendering** (mesh extraction, multi-part assembly, ObjDesc) | **WorldBuilder `StaticObjectRenderManager.cs` + `ObjectMeshManager.cs`** | ACME `StaticObjectManager.cs` (includes CreaturePalette, GfxObjRemapping, HiddenParts — useful for character appearance which WB doesn't cover) | WB for static objects, ACME for character appearance. |
+| **Texture decoding** (INDEX16, P8, DXT, BGRA, alpha) | **WorldBuilder `TextureHelpers.cs`** | ACME `TextureHelpers.cs`; ACViewer's `IndexToColor` is canonical for subpalette overlay | WB is acdream's decode base. |
+| **EnvCell / dungeon rendering** (cell geometry, portal visibility, collision mesh) | **WorldBuilder `EnvCellRenderManager.cs` + `PortalRenderManager.cs`** | ACME `EnvCellManager.cs` (more complete for collision); ACViewer `Physics/Common/EnvCell.cs` | WB is acdream's geometry base; ACME for collision until ported. |
+| **Particles / sky** (particle systems, weather, sky particles) | **WorldBuilder `SkyboxRenderManager.cs` + `ParticleEmitterRenderer.cs` + `ParticleBatcher.cs`** | retail decomp | WB is acdream's particle base. |
+| **Visibility / culling** (frustum, cell visibility) | **WorldBuilder `VisibilityManager.cs` + `Frustum.cs`** | — | WB. |
 | **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. |