917 changed files with 4178 additions and 1831542 deletions
--- a/.gitattributes
+++ b/.gitattributes
@ -1 +0,0 @@
 .github/workflows/*.lock.yml linguist-generated=true merge=ours
--- a/.github/agents/agentic-workflows.agent.md
+++ b/.github/agents/agentic-workflows.agent.md
@ -1,236 +0,0 @@
 ---
 description: GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade AI-powered workflows with intelligent prompt routing
 disable-model-invocation: true
 ---
 # GitHub Agentic Workflows Agent
 This agent helps you work with **GitHub Agentic Workflows (gh-aw)**, a CLI extension for creating AI-powered workflows in natural language using markdown files.
 ## What This Agent Does
 This is a **dispatcher agent** that routes your request to the appropriate specialized prompt based on your task:
 - **Creating new workflows**: Routes to `create` prompt
 - **Updating existing workflows**: Routes to `update` prompt
 - **Debugging workflows**: Routes to `debug` prompt  
 - **Upgrading workflows**: Routes to `upgrade-agentic-workflows` prompt
 - **Creating report-generating workflows**: Routes to `report` prompt — consult this whenever the workflow posts status updates, audits, analyses, or any structured output as issues, discussions, or comments
 - **Creating shared components**: Routes to `create-shared-agentic-workflow` prompt
 - **Fixing Dependabot PRs**: Routes to `dependabot` prompt — use this when Dependabot opens PRs that modify generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`). Never merge those PRs directly; instead update the source `.md` files and rerun `gh aw compile --dependabot` to bundle all fixes
 - **Analyzing test coverage**: Routes to `test-coverage` prompt — consult this whenever the workflow reads, analyzes, or reports on test coverage data from PRs or CI runs
 - **Rendering ASCII charts in markdown**: Routes to `asciicharts` guide — consult this whenever the workflow needs compact charts that render reliably in GitHub issues, comments, or discussions
 - **CLI commands and triggering workflows**: Routes to `cli-commands` guide — consult this whenever the user asks how to run, compile, debug, or manage workflows from the command line, or when they need the MCP tool equivalent of a `gh aw` command
 - **Reducing token consumption / cost optimization**: Routes to `token-optimization` guide — consult this whenever the user asks how to reduce token usage, lower costs, speed up workflows, or measure the impact of prompt changes with experiments
 - **Choosing workflow architectures and design patterns**: Routes to `patterns` guide — consult this whenever the user asks for strategy, architecture, operating models, or pattern selection for agentic workflows
 > [!IMPORTANT]
 > For architecture/pattern-selection requests, load `https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/patterns.md` first.
 Workflows may optionally include:
 - **Project tracking / monitoring** (GitHub Projects updates, status reporting)
 - **Orchestration / coordination** (one workflow assigning agents or dispatching and coordinating other workflows)
 ## Files This Applies To
 - Workflow files: `.github/workflows/*.md` and `.github/workflows/**/*.md`
 - Workflow lock files: `.github/workflows/*.lock.yml`
 - Shared components: `.github/workflows/shared/*.md`
 - Configuration: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/github-agentic-workflows.md
 ## Problems This Solves
 - **Workflow Creation**: Design secure, validated agentic workflows with proper triggers, tools, and permissions
 - **Workflow Debugging**: Analyze logs, identify missing tools, investigate failures, and fix configuration issues
 - **Version Upgrades**: Migrate workflows to new gh-aw versions, apply codemods, fix breaking changes
 - **Component Design**: Create reusable shared workflow components that wrap MCP servers
 ## How to Use
 When you interact with this agent, it will:
 1. **Understand your intent** - Determine what kind of task you're trying to accomplish
 2. **Route to the right prompt** - Load the specialized prompt file for your task
 3. **Execute the task** - Follow the detailed instructions in the loaded prompt
 ## Available Prompts
 ### Create New Workflow
 **Load when**: User wants to create a new workflow from scratch, add automation, or design a workflow that doesn't exist yet
 **Prompt file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/create-agentic-workflow.md
 **Use cases**:
 - "Create a workflow that triages issues"
 - "I need a workflow to label pull requests"
 - "Design a weekly research automation"
 ### Update Existing Workflow  
 **Load when**: User wants to modify, improve, or refactor an existing workflow
 **Prompt file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/update-agentic-workflow.md
 **Use cases**:
 - "Add web-fetch tool to the issue-classifier workflow"
 - "Update the PR reviewer to use discussions instead of issues"
 - "Improve the prompt for the weekly-research workflow"
 ### Debug Workflow  
 **Load when**: User needs to investigate, audit, debug, or understand a workflow, troubleshoot issues, analyze logs, or fix errors
 **Prompt file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/debug-agentic-workflow.md
 **Use cases**:
 - "Why is this workflow failing?"
 - "Analyze the logs for workflow X"
 - "Investigate missing tool calls in run #12345"
 ### Upgrade Agentic Workflows
 **Load when**: User wants to upgrade workflows to a new gh-aw version or fix deprecations
 **Prompt file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/upgrade-agentic-workflows.md
 **Use cases**:
 - "Upgrade all workflows to the latest version"
 - "Fix deprecated fields in workflows"
 - "Apply breaking changes from the new release"
 ### Create a Report-Generating Workflow
 **Load when**: The workflow being created or updated produces reports — recurring status updates, audit summaries, analyses, or any structured output posted as a GitHub issue, discussion, or comment
 **Prompt file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/report.md
 **Use cases**:
 - "Create a weekly CI health report"
 - "Post a daily security audit to Discussions"
 - "Add a status update comment to open PRs"
 ### Create Shared Agentic Workflow
 **Load when**: User wants to create a reusable workflow component or wrap an MCP server
 **Prompt file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/create-shared-agentic-workflow.md
 **Use cases**:
 - "Create a shared component for Notion integration"
 - "Wrap the Slack MCP server as a reusable component"
 - "Design a shared workflow for database queries"
 ### Fix Dependabot PRs
 **Load when**: User needs to close or fix open Dependabot PRs that update dependencies in generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`)
 **Prompt file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/dependabot.md
 **Use cases**:
 - "Fix the open Dependabot PRs for npm dependencies"
 - "Bundle and close the Dependabot PRs for workflow dependencies"
 - "Update @playwright/test to fix the Dependabot PR"
 ### Analyze Test Coverage
 **Load when**: The workflow reads, analyzes, or reports test coverage — whether triggered by a PR, a schedule, or a slash command. Always consult this prompt before designing the coverage data strategy.
 **Prompt file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/test-coverage.md
 **Use cases**:
 - "Create a workflow that comments coverage on PRs"
 - "Analyze coverage trends over time"
 - "Add a coverage gate that blocks PRs below a threshold"
 ### Render ASCII Charts in Markdown
 **Load when**: The workflow needs in-markdown charts (sparklines, bars, table+trend views) that must align cleanly and render reliably across GitHub surfaces, including mobile.
 **Reference file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/asciicharts.md
 **Use cases**:
 - "Show a compact trend chart in an issue comment"
 - "Render a dashboard table with sparkline trends"
 - "Generate aligned ASCII bars for service metrics"
 ### CLI Commands Reference
 **Load when**: The user asks how to run, compile, debug, or manage workflows from the command line; needs the MCP tool equivalent of a `gh aw` command; or is in a restricted environment (e.g., Copilot Cloud) without direct CLI access.
 **Reference file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/cli-commands.md
 **Use cases**:
 - "How do I trigger workflow X on the main branch?"
 - "What's the MCP equivalent of `gh aw logs`?"
 - "I'm in Copilot Cloud — how do I compile a workflow?"
 - "Show me all available gh aw commands"
 ### Token Consumption Optimization
 **Load when**: The user asks how to reduce token usage, lower workflow costs, make a workflow faster or cheaper, or measure the impact of prompt or configuration changes.
 **Reference file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/token-optimization.md
 **Use cases**:
 - "How do I reduce the token cost of this workflow?"
 - "My workflow is too expensive — how do I optimize it?"
 - "How do I compare token usage between two runs?"
 - "Should I use gh-proxy or the MCP server?"
 - "How do I use sub-agents to reduce costs?"
 - "How do I measure the impact of a prompt change?"
 ### Workflow Pattern Selection
 **Load when**: The user asks for architecture, strategy, operating model selection, or pattern recommendations for building agentic workflows.
 **Reference file**: https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/patterns.md
 **Use cases**:
 - "Which pattern should I use for multi-repo rollout?"
 - "How should I structure this workflow architecture?"
 - "What pattern fits slash-command triage?"
 - "Should this be DispatchOps or DailyOps?"
 ## Instructions
 When a user interacts with you:
 1. **Identify the task type** from the user's request
 2. **Load the appropriate prompt** from the GitHub repository URLs listed above
 3. **Follow the loaded prompt's instructions** exactly
 4. **If uncertain**, ask clarifying questions to determine the right prompt
 ## Quick Reference
 ```bash
 # Initialize repository for agentic workflows
 gh aw init
 # Generate the lock file for a workflow
 gh aw compile [workflow-name]
 # Trigger a workflow on demand (preferred over gh workflow run)
 gh aw run <workflow-name>             # interactive input collection
 gh aw run <workflow-name> --ref main  # run on a specific branch
 # Debug workflow runs
 gh aw logs [workflow-name]
 gh aw audit <run-id>
 # Upgrade workflows
 gh aw fix --write
 gh aw compile --validate
 ```
 ## Key Features of gh-aw
 - **Natural Language Workflows**: Write workflows in markdown with YAML frontmatter
 - **AI Engine Support**: Copilot, Claude, Codex, or custom engines
 - **MCP Server Integration**: Connect to Model Context Protocol servers for tools
 - **Safe Outputs**: Structured communication between AI and GitHub API
 - **Strict Mode**: Security-first validation and sandboxing
 - **Shared Components**: Reusable workflow building blocks
 - **Repo Memory**: Persistent git-backed storage for agents
 - **Sandboxed Execution**: All workflows run in the Agent Workflow Firewall (AWF) sandbox, enabling full `bash` and `edit` tools by default
 ## Important Notes
 - Always reference the instructions file at https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/github-agentic-workflows.md for complete documentation
 - Use the MCP tool `agentic-workflows` when running in GitHub Copilot Cloud
 - Workflows must be compiled to `.lock.yml` files before running in GitHub Actions
 - **Bash tools are enabled by default** - Don't restrict bash commands unnecessarily since workflows are sandboxed by the AWF
 - Follow security best practices: minimal permissions, explicit network access, no template injection
 - **Network configuration**: Use ecosystem identifiers (`node`, `python`, `go`, etc.) or explicit FQDNs in `network.allowed`. Bare shorthands like `npm` or `pypi` are **not** valid. See https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/network.md for the full list of valid ecosystem identifiers and domain patterns.
 - **Single-file output**: When creating a workflow, produce exactly **one** workflow `.md` file. Do not create separate documentation files (architecture docs, runbooks, usage guides, etc.). If documentation is needed, add a brief `## Usage` section inside the workflow file itself.
 - **Triggering runs**: Always use `gh aw run <workflow-name>` to trigger a workflow on demand — not `gh workflow run <file>.lock.yml`. `gh aw run` handles workflow resolution by short name, input parsing and validation, and correct run-tracking for agentic workflows. Use `--ref <branch>` to run on a specific branch.
 - **CLI commands reference**: For a complete guide on all `gh aw` commands and their MCP tool equivalents (for restricted environments), see https://github.com/github/gh-aw/blob/v0.74.8/.github/aw/cli-commands.md
--- a/.github/mcp.json
+++ b/.github/mcp.json
@ -1,11 +0,0 @@
 {
  "mcpServers": {
    "github-agentic-workflows": {
      "command": "gh",
      "args": [
        "aw",
        "mcp-server"
      ]
    }
  }
 }
--- a/.github/workflows/aw.json
+++ b/.github/workflows/aw.json
@ -1,3 +0,0 @@
 {
  "ghes": false
 }
--- a/.github/workflows/copilot-setup-steps.yml
+++ b/.github/workflows/copilot-setup-steps.yml
@ -1,26 +0,0 @@
 name: "Copilot Setup Steps"
 # This workflow configures the environment for GitHub Copilot Agent with gh-aw MCP server
 on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
 jobs:
  # The job MUST be called 'copilot-setup-steps' to be recognized by GitHub Copilot Agent
  copilot-setup-steps:
    runs-on: ubuntu-latest
    # Set minimal permissions for setup steps
    # Copilot Agent receives its own token with appropriate permissions
    permissions:
      contents: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
      - name: Install gh-aw extension
        uses: github/gh-aw-actions/setup-cli@efa55847f72aadb03490d955263ff911bf758700 # v0.74.8
        with:
          version: v0.74.8
--- a/.github/workflows/hygiene-assessment.lock.yml
+++ b/.github/workflows/hygiene-assessment.lock.yml
--- a/.github/workflows/hygiene-assessment.md
+++ b/.github/workflows/hygiene-assessment.md
@ -1,146 +0,0 @@
 ---
 description: Daily hygiene assessment of acdream's main branch — flag workarounds,
  ungrounded code, Phase/roadmap drift, and architecture violations.
 on:
  schedule: daily
  workflow_dispatch: {}
 permissions: read-all
 network:
  allowed:
    - defaults
    - dotnet
 tools:
  github:
    toolsets: [default]
 safe-outputs:
  create-issue:
    max: 1
    close-older-issues: true
    labels:
      - ai
      - hygiene
 engine:
  id: copilot
  model: gpt-5.3-codex
 ---
 # acdream Hygiene Assessment
 You are **DereLint**, a focused AI auditor for the acdream Asheron's Call client.
 Your job: scan `main` once a day and produce a single rolling report on hygiene
 drift. Engineer-grade tone. No persona slang. The audience is a senior C# /
 systems engineer who already operates under a strict retail-faithfulness rule.
 ## Mission
 acdream's core rule (from `CLAUDE.md`): **"The code is modern. The behavior is
 retail."** Every AC-specific algorithm must be ported from
 `docs/research/named-retail/` (the Sept 2013 EoR PDB) and never guessed. The
 roadmap drives one phase at a time. Workarounds are forbidden unless the user
 has explicitly approved them. Drift from any of that is what you flag.
 Before you start your analysis: `git fetch origin main && git checkout main`.
 Then read these to ground yourself:
 - `CLAUDE.md` — the project's operating instructions (most important)
 - `docs/plans/2026-04-11-roadmap.md` — current phase, agreed order
 - `docs/plans/2026-05-12-milestones.md` — current milestone
 - `docs/ISSUES.md` — open issues you must NOT re-file
 - `docs/architecture/acdream-architecture.md` — architecture source of truth
 ## What to look for
 Five categories. For each finding, cite `file:line`.
 ### 1. Workaround patterns (CLAUDE.md forbids these unless user-approved)
 - `// WORKAROUND` / `// HACK` / `// FIXME` / `// XXX` comments
 - Guard early-returns at symptom sites (`if (badState) return;`) that look like
  band-aids rather than root-cause fixes
 - `try/catch` blocks swallowing exceptions silently
 - "grace period" timers / "settle delay" sleeps
 - Flags named like `_suppressXDuringY` that mask wire-level mistakes
 ### 2. Ungrounded retail-port code
 - AC-specific algorithm code (collision, animation, motion, dat-decode,
  rendering math) that has **no decomp citation** in comments. Every
  retail-faithful port should reference a symbol from
  `docs/research/named-retail/symbols.json` or a function address from
  `docs/research/decompiled/`.
 - Magic numbers in physics / motion / wire-format paths that aren't cited
  against a retail source.
 ### 3. Roadmap drift
 - Phase markers in code (`// Phase L.5:`, `// Phase N.4:`) that reference
  phases no longer matching the roadmap.
 - Sections of `docs/plans/2026-04-11-roadmap.md` flagged "ahead" / "active"
  that don't match what the last 20 commits actually touched.
 - The "Currently working toward" line in `CLAUDE.md` vs. what the last 20
  commit subjects actually touched. If they disagree, flag it.
 ### 4. Test / build hygiene
 - `dotnet build` warnings (the project should build with zero warnings).
 - Tests in failing state (`dotnet test`).
 - Test count regression below the baseline documented in `CLAUDE.md`.
 - Build / launch needing `--no-build` workarounds anywhere.
 ### 5. Architecture drift
 - `using WorldBuilder.*` outside `src/AcDream.App/Rendering/Wb/` and
  `src/AcDream.Core/Rendering/Wb/` (Phase O extracted WB code into those
  directories — references outside are a regression).
 - `Environment.GetEnvironmentVariable("ACDREAM_*")` calls outside diagnostic
  owner classes (per `CLAUDE.md` "Code Structure Rules" item 5).
 - `IDatReaderWriter` consumers that should be using `DatCollection`
  (post-Phase O: `DatCollection` is the only dat reader).
 - Code in `AcDream.Core` that references `AcDream.App` or GL types directly
  (layer separation violation per `CLAUDE.md` Code Structure Rules item 2).
 ## Accepted exceptions
 If `docs/ISSUES.md` already has an OPEN entry for a finding, **don't re-file
 it**. Mention it under "Known accepted exceptions" instead. Same for items
 explicitly listed as deferred in the roadmap.
 ## Output
 Create one GitHub Issue titled `acdream Hygiene Report YYYY-MM-DD`. The
 framework will close any prior `ai+hygiene`-labeled issues automatically.
 Body structure:
 ### Executive Summary
 Two sentences on overall hygiene. Concrete; no fluff.
 ### Findings
 For each: **Location** (file:line, linked to the source), **Category** (1-5),
 **Problem** (one sentence), **Recommendation** (one sentence),
 **Decomp/Doc reference** (where applicable — cite the named symbol or doc).
 ### Roadmap reality check
 Currently-working-toward line vs. recent commit subjects. State whether they
 match or where they diverge.
 ### Known accepted exceptions
 Issues already filed in `docs/ISSUES.md` that you observed during the scan.
 Name them by ID, don't re-file.
 ### Suggested next step
 ONE concrete action the team should take. If everything is clean, call the
 `noop` safe-output with "All clear — no hygiene drift found." instead of
 creating an issue.
 ## Style
 - Engineer tone. No slang.
 - Be specific. "Workaround in PhysicsEngine.cs:142" beats "physics has issues."
 - Be conservative. If you're unsure something is a workaround vs. an
  intentional retail-faithful port, say so — don't assert.
 - Keep the report under 1500 words. The team wants signal, not a wall of text.
--- a/.gitignore
+++ b/.gitignore
@ -18,31 +18,13 @@ packages/
 Thumbs.db
 # Reference repos and retail client (large, not our code, separate licenses)
-# WorldBuilder is exempt — it's a load-bearing dependency tracked as a git
+references/
 # submodule pointing at our fork (Phase N, see docs/architecture/worldbuilder-inventory.md).
 references/*
 !references/WorldBuilder
 !references/WorldBuilder/
 # Claude Code session state
 .claude/
 # Superpowers brainstorm visual-companion scratch (mockups regenerate; not source)
 /.superpowers/
 launch.log
 launch-*.log
 proveout*.log
 launch.utf8.log
 n4-verify*.log
 # A6.P5 (2026-05-25) — door-stuck reproduction captures (multi-MB);
 # the 3-record fixture extracted from these lives at
 # tests/AcDream.Core.Tests/Fixtures/door-bug/over-penetration-capture.jsonl
 door-stuck-capture.jsonl
 door-stuck-*.launch.log
 door-stuck-*.launch.utf8.log
 door-fix-*.launch.log
 door-fix-*.jsonl
 door-walkthrough.*
 # ImGui auto-saved window/docking state (per-user, not source)
 imgui.ini
@ -64,8 +46,6 @@ tmp/
 # The committed reference workflow lives in CLAUDE.md "Retail debugger toolchain";
 # session-specific traces should not pollute the repo.
 *.cdb
 # tools/cdb/ holds committed reference scripts — exempt them from the blanket rule above.
 !tools/cdb/*.cdb
 launch_*.log
 launch_*.err
 launch_*.ps1
@ -84,9 +64,3 @@ substep_trace*
 sg_built.txt
 # Stray bash-mangled path artifacts from PowerShell-via-bash escaping
 C[-]*
 # Obsidian vault config (personal, not project-wide)
 .obsidian/
 # Junction to Claude Code per-project memory (Obsidian vault visibility)
 claude-memory
--- a/.gitmodules
+++ b/.gitmodules
@ -1,4 +0,0 @@
 [submodule "references/WorldBuilder"]
 	path = references/WorldBuilder
 	url = git@github.com:eriknihlen/WorldBuilder.git
 	branch = acdream
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@ -1,5 +0,0 @@
 {
    "github.copilot.enable": {
        "markdown": true
    }
 }
--- a/AcDream.slnx
+++ b/AcDream.slnx
@ -13,7 +13,6 @@
    <Project Path="tools/RetailTimeProbe/RetailTimeProbe.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/AcDream.App.Tests/AcDream.App.Tests.csproj" />
    <Project Path="tests/AcDream.Core.Tests.Fixtures.HelloPlugin/AcDream.Core.Tests.Fixtures.HelloPlugin.csproj" />
    <Project Path="tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj" />
    <Project Path="tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj" />
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -1,4 +1,4 @@
-# acdream — project instructions for Claude
+# acdream — project instructions for Claude
 ## Goal
@ -25,74 +25,30 @@ 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 code lives in our tree.** Phase O extracted ~33 WB files
+**Execution phases:** R1→R8 in the architecture doc. Each phase has clear
-(~7.7K LOC) into our own namespaces and dropped the two external project
+goals, test criteria, and builds on the previous. Don't skip phases.
 references. `DatCollection` is the **only** dat reader in process —
 `DefaultDatReaderWriter` is gone. `references/WorldBuilder/` remains
 in-tree as a read-reference (MIT-licensed; grep it freely), but nothing
 in `src/AcDream.*` references it as a project dependency.
-**Where the extracted code lives (post-Phase O):**
+The codebase is organized by layer (see architecture doc). Current phase
- `src/AcDream.Core/Rendering/Wb/` — pure dat/mesh helpers (5 files,
+state lives in memory (`memory/project_*.md`), plans in `docs/plans/`,
-  ~782 LOC): `TerrainUtils`, `TerrainEntry`, `RegionInfo`,
+research in `docs/research/`.
  `SceneryHelpers`, `TextureHelpers`. No GL dependency; safe to use
  from Core.
 - `src/AcDream.App/Rendering/Wb/` — GL infrastructure + mesh pipeline
  (~27 files, ~7K LOC): `ObjectMeshManager`, `WbMeshAdapter`,
  `WbDrawDispatcher`, `LandblockSpawnAdapter`, `EntitySpawnAdapter`,
  `TextureCache`, `GlobalMeshBuffer`, shader infrastructure, and the
  EnvCell/portal/scenery/terrain-blending pipeline classes.
 **Modern rendering path is MANDATORY** as of the N.5 ship amendment.
 `WbFoundationFlag`, `InstancedMeshRenderer`, and `StaticMeshRenderer`
 are deleted. Missing `GL_ARB_bindless_texture` or
 `GL_ARB_shader_draw_parameters` throws `NotSupportedException` at
 startup. There is no legacy fallback. Engineering cribs (WbMeshAdapter
 seams, N.5 SSBO layout, translucency model, gotchas) live in
 `memory/reference_modern_rendering_pipeline.md`.
 Before re-implementing any AC-specific rendering or dat-handling
 algorithm, **read `docs/architecture/worldbuilder-inventory.md` FIRST**.
 The inventory describes what we extracted (now in our tree) and what we
 still write ourselves. Re-porting from retail decomp when we already
 have 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.
 **Execution model:** the active source of truth is the **milestones doc**
 (`docs/plans/2026-05-12-milestones.md`) for "what are we building right
 now" and the **strategic roadmap** (`docs/plans/2026-04-11-roadmap.md`)
 for the per-phase ledger of what's shipped, what's in flight, and what
 comes next. **Ignore the old "R1→R8" sequence** — it was an early refactor
 sketch that no longer matches reality (see the "Roadmap Model" section in
 `docs/architecture/acdream-architecture.md`). Per-phase detailed specs
 live under `docs/superpowers/specs/`.
 The codebase is organized by layer (see architecture doc + the **Code
 Structure Rules** section below). Plans live in `docs/plans/`,
 research in `docs/research/`, persistent project memory in `memory/`
 and `~/.claude/projects/.../memory/` (the latter is browsable in
 Obsidian via the `claude-memory/` junction in the repo root; see
 `memory/reference_obsidian_vault.md`).
 **UI strategy:** three-layer split — swappable backend (ImGui.NET +
 `Silk.NET.OpenGL.Extensions.ImGui` for Phase D.2a, custom retail-look
 toolkit for D.2b later) / stable `AcDream.UI.Abstractions` layer
 (ViewModels + Commands + `IPanel` / `IPanelRenderer`) / unchanged game
-state. **As of Phase I, ImGui hosts every dev/debug panel** — Vitals,
+state. **As of Phase I (2026-04-25), ImGui hosts every dev/debug
-Chat, Debug. The previous custom-StbTrueTypeSharp `DebugOverlay` was
+panel** — Vitals, Chat, Debug. The previous custom-StbTrueTypeSharp
-deleted in I.2; `TextRenderer` + `BitmapFont` are kept alive
+`DebugOverlay` was deleted in I.2; `TextRenderer` + `BitmapFont` are
-specifically for the future world-space HUD (D.6 — damage floaters,
+kept alive specifically for the future world-space HUD (D.6 — damage
-name plates) where ImGui can't reach into the 3D scene. D.2b remains
+floaters, name plates) where ImGui can't reach into the 3D scene.
-the long-term retail-look path (panels reskinned one at a time using
+D.2b remains the long-term retail-look path (panels reskinned one at a
-dat assets); ImGui persists forever as the `ACDREAM_DEVTOOLS=1`
+time using dat assets); ImGui persists forever as the
-overlay. **All plugin-facing UI targets `AcDream.UI.Abstractions` —
+`ACDREAM_DEVTOOLS=1` overlay. **All plugin-facing UI targets
-never import a backend namespace from a panel.** Full design:
+`AcDream.UI.Abstractions` — never import a backend namespace from a
-[`docs/plans/2026-04-24-ui-framework.md`](docs/plans/2026-04-24-ui-framework.md).
+panel.** Full design: `docs/plans/2026-04-24-ui-framework.md`.
-Memory cribs: `memory/project_chat_pipeline.md` (chat pipeline as of
+Memory cribs: `memory/project_ui_architecture.md` (architecture),
-Phase I), `memory/project_input_pipeline.md` (input pipeline as of
+`memory/project_chat_pipeline.md` (chat pipeline as of Phase I),
-Phase K).
+`memory/project_input_pipeline.md` (input pipeline as of Phase K).
 **Input pipeline:** `src/AcDream.UI.Abstractions/Input/` (action enum,
 `KeyChord`, `KeyBindings`, multicast `InputDispatcher` with scope
@ -102,131 +58,16 @@ stack + modal capture for rebind UX) + `src/AcDream.App/Input/`
 `KeyBindings.RetailDefaults()` matching
 `docs/research/named-retail/retail-default.keymap.txt`). The Settings
 panel (F11 / View → Settings) lets users remap any action via
-click-to-rebind. As of Phase K, ALL keyboard / mouse input flows
+click-to-rebind. As of Phase K (2026-04-26), ALL keyboard / mouse
-through the dispatcher — no IsKeyPressed polling outside the per-frame
+input flows through the dispatcher — no IsKeyPressed polling outside
-movement queries.
+the per-frame movement queries.
 ## Current state
 **Currently working toward: M1.5 — Indoor world feels right.** Dungeons RENDER +
 are navigable; **login into a dungeon** now loads + places the player and is
 **FPS-steady from the start** (#135 pre-collapse + indoor cell-floor spawn gate,
 `712f17f`+`2c92375`). The dungeon **"red cone"** was an editor-only placement marker
 acdream inherited from WB (retail hides it via distance degrade) — FIXED (#136 `6f81e2c`).
 REMAINING for M1.5: **A7 dungeon lighting** (LightBake Core landed `3b93f91`; per-vertex
 bake integration + the per-pixel torch OVER-blow still open — #79/#93); **#137 dungeon
 collision** (doors / wall openings); **#138 teleport-OUT of a dungeon** loads the outdoor
 world incompletely + position desync (the collapse→EXPAND gap — same machinery as #135).
 M2 (CombatMath) deferred. Detail in ISSUES (#135–#138) + the render/physics digests.
 Recent closes (2026-06-14): #135, #136. Keep this paragraph ≤6 lines + pointers — detail
 in the docs below, NOT here.
 For canonical state, read in this order:
 - [`docs/plans/2026-05-12-milestones.md`](docs/plans/2026-05-12-milestones.md) — milestone targets + freeze list per milestone
 - [`docs/plans/2026-04-11-roadmap.md`](docs/plans/2026-04-11-roadmap.md) — what's shipped, what's in flight, what's next
 - [`docs/ISSUES.md`](docs/ISSUES.md) — open + recently closed bugs (tactical)
 - [`docs/architecture/retail-divergence-register.md`](docs/architecture/retail-divergence-register.md) — every known acdream-vs-retail deviation (see the register rules in the workflow section)
 **Domain entry points (START HERE before domain work):**
 - `claude-memory/project_render_pipeline_digest.md` — indoor render / doorway-FLAP / portal flood SSOT, with the DO-NOT-RETRY table
 - `claude-memory/project_physics_collision_digest.md` — physics / collision / cell-membership SSOT, with the DO-NOT-RETRY table
 For engineering reference (read on demand, not at session start):
 - `memory/reference_modern_rendering_pipeline.md` — N.4/N.5 bindless+MDI dispatch, WbMeshAdapter/WbDrawDispatcher, translucency model
 - `memory/reference_two_tier_streaming.md` — Phase A.5 streaming architecture
 - `memory/reference_indoor_cell_tracking.md` — Phase 2 + A4 portal-based cell tracking + multi-cell BSP iteration
 - `memory/reference_obsidian_vault.md` — Obsidian-as-memory-viewer setup + the memory-handling protocol
 - `memory/reference_ghidra_projects.md` — Ghidra + GhidraMCP for acclient RE
 - `memory/reference_repos.md` — what each `references/*` repo is for
 The memory dir also holds `feedback_*.md` lessons-learned (cross-cutting
 patterns the project has agreed on) and `project_*.md` per-subsystem
 cribs (chat pipeline, input pipeline, interaction pipeline, etc.).
 See `memory/MEMORY.md` for the index.
 ## Code Structure Rules
 These are the structural rules the project commits to. They are
 **process rules** (where code goes, what depends on what), not style
 rules (formatting / naming). They exist to keep the layer split honest
 and to stop `GameWindow.cs` from continuing to grow into a 10k-line
 god object. The full rationale + the extraction sequence we're
 pursuing live in [`docs/architecture/code-structure.md`](docs/architecture/code-structure.md).
 1. **No new substantial feature bodies in `GameWindow.cs`.** It is
   already over 10,000 lines and owns runtime wiring. New runtime
   work goes into a dedicated controller / sink / orchestrator class
   in `src/AcDream.App/` (or deeper in `AcDream.Core` when it's pure
   logic). Adding a handful of fields and a one-paragraph method to
   wire an extracted class in is fine; adding a new ~200-line feature
   directly is not. When in doubt, file a small follow-up extraction
   as part of the change.
 2. **`AcDream.Core` must not depend on the window / GL / backend
   projects, except via documented interop seams.** As of Phase O,
   the only allowed seams are the extracted helpers in
   `src/AcDream.Core/Rendering/Wb/` (`TerrainUtils`, `TerrainEntry`,
   `RegionInfo`, `SceneryHelpers`, `TextureHelpers` — stateless, no GL).
   The former `WorldBuilder.Shared` and `Chorizite.OpenGLSDLBackend.Lib`
   project references are gone; their code now lives in our tree at those
   paths. New Core code that needs a GL surface must define an interface
   in Core and let `AcDream.App` implement it — never the reverse. If you
   need to add a project reference to Core, the change must come with an
   inventory-doc update explaining why.
 3. **UI panels target `AcDream.UI.Abstractions` only.** No panel may
   import `AcDream.UI.ImGui` or any backend namespace. ViewModels,
   commands, and the `IPanel` / `IPanelRenderer` contract are the
   surface; everything else is backend. This is what lets us swap
   D.2a (ImGui) for D.2b (retail-look) later without rewriting
   panels.
 4. **Startup environment variables enter through a typed options
   object.** `AcDream.App.RuntimeOptions` is the single source of
   truth for startup configuration. `Program.cs` reads the
   environment once into `RuntimeOptions` and passes it into
   `GameWindow`. Don't sprinkle `Environment.GetEnvironmentVariable`
   reads through new code paths; add a field to `RuntimeOptions` and
   pipe it through.
 5. **Runtime probes (diagnostic toggles) belong in diagnostic owner
   classes.** Today `AcDream.Core.Physics.PhysicsDiagnostics` owns the
   `ACDREAM_PROBE_*` family. The pattern: one static class per
   subsystem, exposing typed bool/int properties read from env vars
   once at startup (with optional runtime-toggleable counterparts for
   the DebugPanel). Per-call-site `Environment.GetEnvironmentVariable`
   reads in new code are a process smell — if a flag survives one
   phase, promote it to a diagnostic owner. The dozens of existing
   `ACDREAM_DUMP_*` reads scattered through `GameWindow` are tech
   debt; do not add more.
 6. **Tests live in the project matching the layer under test.** Core
   tests in `tests/AcDream.Core.Tests/`, UI tests in
   `tests/AcDream.UI.Abstractions.Tests/`, network tests in
   `tests/AcDream.Core.Net.Tests/`. App-layer tests (RuntimeOptions
   parsing, etc.) belong in `tests/AcDream.App.Tests/`. When adding a
   new test project, register it in `AcDream.slnx`.
 ## How to operate
 **Memory — read the digests before domain work.** Durable project knowledge
 lives in `claude-memory/` (the auto-loaded index is `MEMORY.md`). Before starting
 work in a domain that has a **digest**, read it first: `project_render_pipeline_digest.md`
 (indoor render / doorway FLAP) and `project_physics_collision_digest.md`
 (physics / collision / membership). Each digest is current-truth-on-top
 plus a DO-NOT-RETRY table — it supersedes dated banners. The memory-handling
 protocol (distill-don't-journal, the digest pattern, tags, recall + capture)
 is in `reference_obsidian_vault.md`. **Do NOT add new dated status banners to
 this file — update the relevant digest (or the Current state pointer list)
 instead.** Obsidian (auto-started in the main repo via a SessionStart hook) is
 the live search / graph / tag lens over `claude-memory/` through the
 `mcp__obsidian__*` tools when it's running; the files read and write the same
 with it closed.
 **You are the lead engineer AND architect on this project at all times.**
 You own the architecture (`docs/architecture/acdream-architecture.md`),
-the execution plan (milestones doc + strategic roadmap), the development
+the execution plan (phases R1–R8), the development workflow, and all
-workflow, and all technical decisions. Stop as little as possible. Drive work autonomously and continuously through full phases and
+technical decisions. Stop as little as possible. Drive work autonomously and continuously through full phases and
 across commit boundaries. Do not stop mid-phase for routine progress check-ins,
 permission asks on low-stakes design calls, or "should I continue?" confirmations.
 The user has repeatedly authorized direct-to-main commits, multi-commit sessions,
@ -236,26 +77,6 @@ The only thing that genuinely requires stopping is **visual confirmation** — t
 user needs to look at the running client and tell you whether it matches
 retail. Everything else is your call.
 **No workarounds without explicit approval.** When you spot a bug or
 encounter a behavioral mismatch, fix the underlying cause — do not ship a
 band-aid, suppression flag, grace period, retry loop, or any other "make
 the symptom go away" shortcut, unless the user has explicitly approved
 that shape OR you are building a NEW feature with a different design.
 This rule exists because every workaround creates architectural debt that
 masks the real issue, makes future refactors harder, and erodes the
 codebase's retail-faithfulness. Examples of disallowed shortcuts: an
 `if (problematicState) return early` guard at the symptom site instead of
 investigating why the state happened; a timer-based "settle period" to
 hide a race; a flag like `_suppressXDuringY` to mask a wire-level mistake;
 a `try/catch` swallowing an exception that signals a real problem. If you
 notice a fix is starting to look like a workaround mid-implementation,
 stop, file the proper investigation as an issue with full reproduction
 notes, and either (a) ask the user before shipping the workaround, or
 (b) invest the time to fix the root cause. The user has explicitly
 authorized "spend more time, get it right" over "ship a shortcut and
 file the cleanup." Quote them: "we should have no workarounds unless I
 say so or we want a different feature."
 **Only stop and wait for the user when:**
 - Visual verification is the acceptance test ("does the drudge look right now?")
@ -266,23 +87,12 @@ say so or we want a different feature."
  files, reverting multiple commits)
 - Memory or committed history shows a clear user preference you're about to
  diverge from
 - **The request is an investigation, audit, analysis, review, or "report-only"**
  — no edits, no writes, no diagnostic code drops until you've delivered the
  report and the user explicitly approves a fix. Use the `/investigate` skill
  (`.claude/skills/investigate/SKILL.md`) to enter this mode cleanly.
 - **A referenced commit, file path, branch, or doc doesn't exist** where the
  user said it would. Ask one short question; don't go hunting across branches
  or worktrees. A 1-line clarification beats 30 minutes of wrong-branch
  exploration.
 **Things you should just do without asking:**
 - Continue to the next planned sub-step of a phase after the previous one
  lands clean — including immediately starting work on the next phase if the
-  current one is done. **You pick what comes next** per the Milestone
+  current one is done
  discipline section — never present the user a menu like "should we do X
  or Y?" or ask "what next?". Just choose and announce the choice in one
  sentence. Work-order selection is Claude's job, not the user's.
 - Pick between two roughly equivalent implementations; justify the choice in
  the commit message
 - Refactor small amounts of surrounding code when genuinely needed to land a
@ -354,9 +164,9 @@ The triangle-boundary Z bug cost 5 failed fix attempts from guessing.
 The animation frame-swap bug cost 4 failed attempts. Every time we
 checked the decompiled code first, we got it right on the first try.
 **Now we have named retail symbols too — Step 0 cuts most lookups
-from 30 minutes to 5 seconds. When "what does retail actually DO at
+from 30 minutes to 5 seconds. And as of 2026-04-30, when "what does
-runtime?" is the question and decomp alone isn't enough, attach cdb
+retail actually DO at runtime?" is the question and decomp alone
-to a live retail client (Step -1).**
+isn't enough, attach cdb to a live retail client (Step -1).**
 ### For each new feature or bug fix:
@ -418,28 +228,6 @@ to a live retail client (Step -1).**
   source was safe; replacing the entire transform composition broke
   everything.
 ### The divergence register (mandatory bookkeeping)
 [`docs/architecture/retail-divergence-register.md`](docs/architecture/retail-divergence-register.md)
 is the single auditable list of every KNOWN place acdream's runtime
 behavior can deviate from retail (108 rows at creation, 2026-06-12:
 intentional architecture / adaptation / approximation / stopgap /
 unclear). Two rules, both binding on subagents too:
 1. **Any commit that introduces a deviation** (an adaptation, an
   approximation, a stopgap, a "retail does X but we...") **adds its
   register row IN THE SAME COMMIT.** Any commit that ports the retail
   mechanism deletes the row in the same commit. A deviation found
   without a row is a bug twice over.
 2. **Any unexplained visual/physics symptom → scan the register BEFORE
   instrumenting.** The "Risk if assumption breaks" column is written as
   the symptom you'd observe (the #119 vanishing staircase, the #112
   transparent cottage, and the knife-edge flap all lived in rows of
   this register's scope before they had names).
 The register holds one-line rows and pointers — detail lives at the
 cited `file:line` and in the digests, never in the register itself.
 ### What NOT to do:
 - **Do not guess** at AC-specific algorithms, formulas, constants, wire
@ -458,14 +246,6 @@ cited `file:line` and in the digests, never in the register itself.
  context of the existing code it's modifying. The first animation
  sequencer integration was done by a subagent that didn't understand
  the transform pipeline — it broke everything.
 - **Do not replace working retail-faithful logic with a modern redesign**
  without explicit user approval. Two campaigns (267 min remote-entity
  prediction+rubber-band replacing hard-snap; speculative shader edits in
  the sky-fog work) had to be reverted in full because the redesign
  regressed behavior the original port had right. When you see "I could
  simplify this with X" on a retail-port, flag the tradeoff and ask
  before deleting the existing path. Retail-faithful first; "cleaner"
  second.
 ### Phase completion checklist:
@ -474,9 +254,6 @@ Before marking any phase as done:
 - [ ] Every AC-specific algorithm has a decompiled reference cited in
      comments (named symbol + address from `named-retail/symbols.json`,
      OR function address + chunk file from older `decompiled/` chunks)
 - [ ] Every retail deviation this phase introduced has a row in
      `docs/architecture/retail-divergence-register.md` (and every
      deviation it retired had its row deleted)
 - [ ] Conformance tests exist for the critical paths
 - [ ] The code was cross-referenced against at least 2 reference repos
 - [ ] `dotnet build` green, `dotnet test` green
@ -489,10 +266,10 @@ Before marking any phase as done:
 **When the question is "what does retail actually DO frame-by-frame?"**
 the decomp alone is often not enough — code paths interact with state
 (LastKnownContactPlane, transient flags, accumulated counters) in ways
-that aren't obvious from reading. We have a working toolchain to attach
+that aren't obvious from reading. As of 2026-04-30 we have a working
-Windows' console debugger (cdb.exe) to a live retail acclient.exe with
+toolchain to attach Windows' console debugger (cdb.exe) to a live
-full PDB symbols and capture state at any breakpoint. **Use this when
+retail acclient.exe with full PDB symbols and capture state at any
-guessing has failed twice in a row.**
+breakpoint. **Use this when guessing has failed twice in a row.**
 ### What we have
@ -597,65 +374,10 @@ guessing has failed twice in a row.**
 - **Network protocol questions** — `holtburger` references + ACE source
  + Wireshark are the right tools, not cdb.
-## MCP servers (live tooling)
+This toolchain was used to settle the L.5 steep-roof investigation:
-
+30Hz physics tick (vs our 60Hz), `kill_velocity` gating,
-Two MCP servers extend the static decomp + cdb workflow with live
+`set_collide` rate per minute. See commit history around 2026-04-30
-introspection. **Ghidra MCP** requires Ghidra to be running with a
+for the trace data and the decisions it drove.
 CodeBrowser open in the target project; **WireMCP** auto-loads at
 Claude Code startup.
 ### Ghidra MCP (LaurieWired v1.4, HTTP)
 Starts an HTTP server on **port 8080** (or **8081** if 8080 is
 taken — first-open-wins) when a CodeBrowser tool opens a program.
 Currently serving **`patchmem.gpr`** — the 2013 v11.4186 build with
 full PDB applied, same source as `docs/research/named-retail/`. Use
 this when grep'ing `acclient_2013_pseudo_c.txt` returns too much
 noise and you want the decomp for one specific function or address
 without dumping the whole file into context.
 Probe: `curl http://127.0.0.1:8081/methods?limit=3`
 Useful endpoints (GET unless noted):
 - `/methods?limit=N` — function names
 - `/list_functions?limit=N` — `Name at HHHHHHHH` lines
 - `/decompile_function?address=0xHHHHHHHH` — decompiled C for one function
 - `/function_xrefs?name=...` — callers / callees
 - `/classes`, `/namespaces`, `/strings`
 - POST `/rename_function_by_address`, POST `/set_decompiler_comment`
 NO endpoints for: signature setting, namespace setting, script
 execution, save-project. Those still require Ghidra's GUI or
 `analyzeHeadless`. Full endpoint catalog + Ghidra project layout in
 `memory/reference_ghidra_projects.md`.
 ### WireMCP (stdio, Node, user-scope)
 Wraps `tshark` at `C:\Program Files\Wireshark\tshark.exe`
 (auto-detected via the Windows fallback path in `WireMCP/index.js`).
 Direct fit for ACE wire-protocol work — capture loopback
 (`127.0.0.1:9000`) to cross-check inbound message parsing (`0xF61C`
 movement, `0xF74A` pickup despawn, `0xF7DE` chat, etc.) against the
 actual bytes, or diff ACE's outbound vs. the holtburger reference.
 Replaces ad-hoc Wireshark sessions in the conversation.
 Tools exposed:
 - `capture_packets` — short live capture on an interface, returns JSON
 - `get_summary_stats` — protocol hierarchy stats
 - `get_conversations` — TCP/UDP conversation table
 - `analyze_pcap` — parse a saved `.pcap` file
 - `check_threats`, `check_ip_threats` — URLhaus / threat-feed lookups
 - `extract_credentials` — grep for creds across protocols (rarely relevant)
 Installed at `C:\Users\erikn\source\repos\WireMCP\` (clone of
 `0xKoda/WireMCP`). Registered via `claude mcp add wiremcp --scope user`.
 **When NOT to use WireMCP:** decoding the AC packet *format* — that
 lives in `holtburger`, ACE, and `Chorizite.ACProtocol`. WireMCP shows
 you the bytes on the wire; the reference repos tell you what they
 mean.
 ## Subagent policy
@ -686,76 +408,6 @@ spec path, the files it should read, the acceptance criteria (build + test
 green), and the commit message style. Subagents inherit CLAUDE.md so they
 follow the same rules.
 ## Milestone discipline
 acdream operates at **two altitudes** above the daily commit:
 - **`docs/plans/2026-05-12-milestones.md`** — the morale + scope layer.
  Seven milestones (M0–M7) from "Connect & explore" to "v1.0", each
  defined by a concrete playable scenario and ~6–10 weeks of work. This
  is where you orient when the project feels half-built and you're not
  sure what to work on. Phases are too granular to feel like progress;
  this doc is the multi-week target.
 - **`docs/plans/2026-04-11-roadmap.md`** — the strategic roadmap.
  Phase-level index. This is where you orient when you know the
  milestone and need the next concrete sub-phase.
 **Work-order autonomy — the meta-rule.** You decide what to work on
 next, always. **The user does NOT pick between phases, milestones, or
 "what's next?" alternatives.** The milestone discipline + the
 per-milestone phase list + the roadmap IS the work order — drive it.
 Never ask the user "want me to start X or Y?" or present a menu of
 options. If two next steps are genuinely equivalent, state which one
 you picked and why in one sentence and start — don't ask. The user
 retains the right to redirect if they think you're wrong, but the
 default is **Claude drives, user reviews**. The user finds decision
 fatigue from constant work-order choices draining — that's literally
 what triggered the milestones doc on 2026-05-12. Honoring this rule is
 the single biggest morale lever. This is the meta-rule that makes the
 four below actually work.
 **The four motivation-keeping rules:**
 1. **One active milestone at a time.** Work that isn't on the critical
   path to the current milestone gets filed in `docs/ISSUES.md` with
   the appropriate `post-Mx` tag and muted. This is the single rule
   that kills the "jumping between things" feeling. If a phase isn't
   part of the current milestone, it doesn't get touched — even if
   it's tempting, even if it would be "quick", even if it would be
   "while I'm here."
 2. **Frozen phases are off-limits.** Shipped-milestone phases are
   frozen until M7's polish pass. Concretely: no rework on streaming,
   chat, input, the WB rendering migration, sky/lighting, the particle
   system, or the network handshake. Those are done. Don't revisit them
   — even if you see something that could be 10% better. Visual
   nice-to-haves and architecture second-guesses on frozen phases are
   explicitly post-M7. The freeze list per milestone lives in the
   milestones doc.
 3. **Crossing a milestone is a textual event, not a video event.**
   When a milestone's demo scenario is functionally complete, update
   `2026-05-12-milestones.md` with a one-paragraph writeup describing
   what works end-to-end, flip the freeze list, and update the
   "currently working toward" line in this CLAUDE.md's **Current
   state** section to the next milestone. Do NOT ask the user to
   record a demo video — they find it pointless. The milestones doc
   + the CLAUDE.md flip ARE the milestone artifact. Phases ship;
   milestones land.
 4. **State both altitudes at session start.** First action of any
   session: "Currently working toward [milestone]. Current phase:
   [phase]. Next concrete step: [whatever]." This keeps the high-level
   orientation visible alongside the immediate task and makes
   mid-session drift obvious. The **Current state** section at the
   top of this file is the always-current snapshot.
 When reality and the milestones diverge — a phase grows beyond the
 milestone's scope, a demo scenario turns out to be unreachable without
 a new sub-phase, the order needs reshuffling — update the milestones
 doc in the same session you discover the divergence. Same rule as the
 roadmap.
 ## Roadmap discipline
 acdream's plan lives in two files committed to the repo:
@ -860,50 +512,20 @@ for the window to close.
 ### Logout-before-reconnect
-**ACE keeps your last session alive after a disconnect, and the duration
+**ACE keeps your last session alive briefly after a disconnect.** If you
-depends on HOW the client exited.** Two cases:
+relaunch the client within a few seconds of the last close, the handshake
-
+fails with `live: session failed: CharacterList not received` and the
-1. **Graceful close (client sent logout packet to ACE):** session clears
+process exits with code 29. Wait ~3–5 seconds between launches, or explicitly
-   in ~3–5 seconds. Wait briefly between launches.
+kill stale processes:
 2. **Hard kill (Stop-Process, crash, force-close):** no logout packet
   reached ACE. ACE keeps the session marked logged-in until its own
   timeout — observed in practice at ~3+ minutes. Subsequent relaunches
   fail with `live: session failed: CharacterList not received` (exit 29)
   the entire time. **There is no admin command available to us to kick
   the stale session.** Either wait it out, or use the graceful path
   below.
 **Prefer the graceful close path when ending a launch.** PowerShell's
 `Stop-Process` is a hard kill — it bypasses the client's shutdown hook
 which is where the logout packet would have been sent. The graceful
 alternative sends WM_CLOSE so the window's close handler runs:
 ```powershell
-$proc = Get-Process -Name AcDream.App -ErrorAction SilentlyContinue
+Get-Process -Name AcDream.App -ErrorAction SilentlyContinue | Stop-Process -Force
 if ($proc) {
    $proc.CloseMainWindow() | Out-Null
    if (-not $proc.WaitForExit(5000)) {
        # Fell through to hard-kill — session WILL be stuck on ACE.
        $proc | Stop-Process -Force
    }
 }
 Start-Sleep -Seconds 3
 # ... then launch ...
 ```
-If `WaitForExit(5000)` returns false (the client didn't exit in 5 seconds
+The user has repeatedly confirmed this — don't treat exit-29-after-rapid-relaunch
-after WM_CLOSE), the client is unresponsive and a hard kill is the only
+as a code bug. It's a server-side session-cleanup delay.
 option — accept that ACE will be unhappy for a few minutes.
 **When recovering from a hard-killed session that ACE still considers
 active:** the only honest answer is to wait. Don't bother retrying every
 30 seconds — make a single retry attempt ~3 minutes after the kill, and
 if it still fails wait another 2 minutes before trying again. The user
 will likely volunteer when ACE has cleared the session if you ask.
 The user has repeatedly confirmed this — don't treat exit-29-after-relaunch
 as a code bug. It's a server-side session-cleanup delay whose duration is
 governed by whether the previous shutdown was graceful or forced.
 ### Test character
@ -930,39 +552,14 @@ via `PlayerMovementController.ApplyServerRunRate`) or from
  diagnostics (`[UM_RAW]`, `[SCFAST]`, `[SCFULL]`, `[SETCYCLE]`,
  `[FWD_WIRE]`, `[OMEGA_DIAG]`, `[SEQSTATE]`, `[PARTSDIAG]`,
  `[VEL_DIAG]`, `[UPCYCLE]`). Heavy.
- `ACDREAM_PROBE_RESOLVE=1` — one `[resolve]` line per
+- *(retired 2026-05-05 by L.3 M2/M3)* `ACDREAM_INTERP_MANAGER` was an
-  `PhysicsEngine.ResolveWithTransition` call: input + target + output
+  env-var gate on an experimental per-tick remote motion path. L.3 M2
-  position/cell, ok-vs-partial, grounded-in, contact-plane status,
+  (commit 40d88b9) replaced both gates (`OnLivePositionUpdated` +
-  wall normal if hit, **responsible entity guid**, env flag, walkable
+  `TickAnimations`) with `IsPlayerGuid(...)` so player remotes use the
-  polygon valid. Heavy (~30 Hz × every entity). Runtime-toggleable via
+  retail-faithful queue routing (InterpolationManager queue catch-up +
-  the DebugPanel "Diagnostics" section if `ACDREAM_DEVTOOLS=1`.
+  PositionManager combiner) unconditionally. NPCs and airborne player
- `ACDREAM_PROBE_CELL=1` — one `[cell-transit]` line per
+  remotes still flow through the legacy `apply_current_movement` +
-  `PlayerMovementController.CellId` change: old → new cell, world
+  `ResolveWithTransition` path. The env-var no longer toggles anything.
  position, reason tag (`resolver` / `teleport`). Low volume — only
  fires on actual cell crossings. Runtime-toggleable via the same
  DebugPanel section.
 - `ACDREAM_PROBE_PUSH_BACK=1` — emits three line types per physics
  tick: `[push-back]` (per `BSPQuery.AdjustSphereToPlane` call),
  `[push-back-disp]` (per `BSPQuery.FindCollisions` dispatch),
  `[push-back-cell]` (per `Transition.CheckOtherCells` off-cell hit).
  Heavy under motion (~100–500 lines/sec). Pair with retail's cdb
  breakpoint set at `tools/cdb/a6-probe.cdb` for the A6.P1 capture
  protocol. Runtime-toggleable via the DebugPanel.
 - `ACDREAM_PROBE_FLAP=1` — capture probe for indoor visibility
  decisions at frame boundaries. Used to converge the U.4c flap fix
  (root indoor visibility at player's cell, not eye).
 - `ACDREAM_CAPTURE_RESOLVE=<path>` — live capture of every player-side
  `PhysicsEngine.ResolveWithTransition` call. Each call appends one
  JSON Lines record with full inputs, PhysicsBody snapshot before AND
  after, plus the `ResolveResult`. Filtered to `IsPlayer` mover flag
  — NPC / remote DR calls don't pollute. Pairs with the trajectory
  replay harness comparison tests to diff captured vs harness state
  per field — the first divergence pinpoints missing apparatus state.
  Capture is OFF when the env var is unset (one null-check cost per
  call).
 - `ACDREAM_DUMP_CELLS=<path>` / `ACDREAM_DUMP_GFXOBJS=<path>` — dump
  resolved cell/GfxObj polygon tables as JSON when ids cache. Used
  for harness fixture extraction.
 ### Outbound motion wire format (acdream → ACE)
@ -981,8 +578,8 @@ when relaying to remote observers. So our INBOUND parser sees
 When the local player toggles Shift while keeping W held (Run↔Walk
 demote/promote), acdream sends a fresh `MoveToState` with the new
 HoldKey + ForwardSpeed. Retail's outbound likely does the same, but
-ACE's behavior on relay is uncertain — see open issues in `docs/ISSUES.md`
+ACE's behavior on relay is uncertain — see `#L.X` in ISSUES.md for
-for the Run↔Walk cycle bug on observed retail-driven remotes.
+the open Run↔Walk cycle bug on observed retail-driven remotes.
 ### Visual verification workflow
@ -1011,19 +608,13 @@ already-running ACE session via the handshake race.
  stop transitions, and keep their visual position tracked smoothly
  between the 5–10 Hz UpdatePosition bursts (dead-reckoning).
-## Reference repos: cross-check the relevant ones
+## Reference repos: check ALL FOUR, not just one
-The `references/` tree holds **six** vendored projects (ACE, ACViewer,
+When researching a protocol detail, dat format, rendering algorithm, or
-WorldBuilder, Chorizite.ACProtocol, holtburger, AC2D). They overlap in
+any "how does AC do X" question, **check all four of the vendored
-some areas and disagree in others. Before committing to an approach,
+references in `references/`** before committing to an approach. Do not
-**cross-reference at least two of them** for the domain you're working
+settle on the first hit and move on — cross-reference at least two of
-in — the per-domain hierarchy in the next section tells you which to
+these, ideally all four:
 read first. A single reference can be misleading; the intersection of
 the relevant references 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.
 The six references:
 - **`references/ACE/`** — ACEmulator server. Authority on the wire
  protocol (packet framing, ISAAC, game message opcodes, serialization
@ -1034,22 +625,11 @@ The six references:
  for the palette-indexed formats. See
  `ACViewer/Render/TextureCache.cs::IndexToColor` for the canonical
  subpalette overlay algorithm.
- **`references/WorldBuilder/`** — **acdream's rendering + dat-handling
+- **`references/WorldBuilder/`** — C# + Silk.NET dat editor. Exact-stack
-  base.** WorldBuilder is not just a reference: `ObjectMeshManager` is
+  match to acdream for rendering approaches: terrain blending, texture
-  the production mesh pipeline, `WbMeshAdapter` is the seam, and
+  atlases, shader patterns. Most useful for "how do I do this GL thing
-  `WbDrawDispatcher` is the production draw path. The modern path is
+  with Silk.NET on net10 idiomatically?" Less useful for protocol or
-  **mandatory** — missing bindless throws at startup, there is no
+  character appearance (dat editor, not game client).
  legacy fallback. **Before re-porting any rendering or dat-handling
  algorithm from retail decomp, read
  `docs/architecture/worldbuilder-inventory.md` first.** The inventory
  tells you what WB covers (terrain, scenery, static objects, EnvCells,
  portals, sky, particles, texture decoding, mesh extraction,
  visibility/culling) and what we still write ourselves (the 🔴 list:
  network, physics, animation, movement, UI, plugin, audio, chat).
  WorldBuilder is MIT-licensed and exact-stack with us (Silk.NET +
  .NET); the divergences we've documented (e.g. WB's terrain split
  formula vs retail's `FSplitNESW`) are called out in the inventory
  doc.
 - **`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
@ -1083,6 +663,13 @@ The six references:
  and uses the server's authoritative Z. See
  `docs/research/2026-04-12-movement-deep-dive.md` for the full analysis.
 Pattern: when you encounter an unknown behavior, grep all four for the
 relevant term, read each hit, and compose a multi-source understanding
 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
@ -1097,15 +684,12 @@ 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." Use for everything in the 🔴 list (network, physics, animation, movement, UI, plugin, audio, chat). |
+| **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) | **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** (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) | **WorldBuilder `LandSurfaceManager.cs`** | ACME `LandSurfaceManager.cs` (same algo, less complete) | WB is acdream's blending base. |
+| **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. |
-| **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) | **ACME `StaticObjectManager.cs`** — includes CreaturePalette, GfxObjRemapping, HiddenParts | ACViewer `Render/` namespace | ACME has the complete creature appearance pipeline in one file. |
-| **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) | **ACME `TextureHelpers.cs`** | ACViewer `Render/TextureCache.cs` (palette overlay = `IndexToColor`) | For subpalette overlay specifically, ACViewer's `IndexToColor` is the canonical algorithm. |
-| **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) | **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. |
 | **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. |
--- a/NOTICE.md
+++ b/NOTICE.md
@ -1,45 +0,0 @@
 # Third-Party Notices
 This file lists third-party software used by acdream, along with their
 license terms and copyright notices.
 ---
 ## WorldBuilder
 Portions of acdream's rendering and dat-handling code are copied from
 WorldBuilder (https://github.com/Chorizite/WorldBuilder), MIT-licensed.
 The extracted code lives under:
 - `src/AcDream.Core/Rendering/Wb/` — pure helpers (texture decode,
  scenery transforms, terrain math).
 - `src/AcDream.App/Rendering/Wb/` — GL infrastructure and mesh pipeline.
 Original copyright holders: Chorizite contributors (see WorldBuilder's
 LICENSE file). Adapted by acdream maintainers to consume our
 `DatCollection` directly (replacing WB's `DefaultDatReaderWriter`) and
 to remove editor-only code paths.
 Original MIT license text:
 MIT License
 Copyright (c) Chorizite contributors
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
--- a/analyze_flap_live.py
+++ b/analyze_flap_live.py
@ -1,44 +0,0 @@
 import sys, re, math
 from collections import Counter
 pat = re.compile(
    r'outRoot=(\w) flood=(\d+) eye=\(([^)]+)\) player=\(([^)]+)\) '
    r'rawPlayer=\(([^)]+)\) yaw=([-\d.]+)')
 rows = []
 for l in sys.stdin:
    m = pat.search(l)
    if not m:
        continue
    rows.append((
        m.group(1), int(m.group(2)),
        tuple(float(x) for x in m.group(3).split(',')),   # eye
        tuple(float(x) for x in m.group(4).split(',')),   # player (RenderPosition)
        tuple(float(x) for x in m.group(5).split(',')),   # rawPlayer (physics body)
        float(m.group(6))))                                # yaw
 print("parsed pv-input rows:", len(rows))
 if not rows:
    raise SystemExit
 print("flood histogram (outRoot,flood)->count:", dict(Counter((r[0], r[1]) for r in rows)))
 def rng(idx):
    return [max(r[idx][k] for r in rows) - min(r[idx][k] for r in rows) for k in range(3)]
 print(f"eye        range over window (m): {[round(v,6) for v in rng(2)]}")
 print(f"render-pos range over window (m): {[round(v,6) for v in rng(3)]}")
 print(f"raw-phys   range over window (m): {[round(v,6) for v in rng(4)]}")
 print(f"yaw        range over window (rad): {round(max(r[5] for r in rows)-min(r[5] for r in rows),6)}")
 flips = 0
 samples = []
 for i in range(1, len(rows)):
    a, b = rows[i-1], rows[i]
    if a[1] == b[1]:
        continue
    flips += 1
    ed = math.dist(a[2], b[2]); pd = math.dist(a[3], b[3])
    rd = math.dist(a[4], b[4]); yd = abs(b[5]-a[5])
    if len(samples) < 18:
        samples.append(f"{b[0]} {a[1]}->{b[1]:<2} eye={ed*1000:7.3f}mm rend={pd*1e6:8.1f}um raw={rd*1e6:8.1f}um yaw={yd*1000:8.4f}mrad")
 print(f"flood flips in window: {flips}")
 for s in samples:
    print("  ", s)
--- a/docs/ISSUES.md
+++ b/docs/ISSUES.md
--- a/docs/architecture/acdream-architecture.md
+++ b/docs/architecture/acdream-architecture.md
@ -95,8 +95,8 @@ designed 2026-04-24. Full design: `docs/plans/2026-04-24-ui-framework.md`.
 The backend is pluggable; ViewModels / Commands / `IPanelRenderer` are
 stable across the swap. ImGui persists forever as the
 `ACDREAM_DEVTOOLS=1` devtools overlay regardless of which backend owns
-the game UI. The full UI design lives in
+the game UI. See `memory/project_ui_architecture.md` for the session
-`docs/plans/2026-04-24-ui-framework.md`.
+crib-sheet version.
 ---
@ -311,51 +311,6 @@ The plugin API exposes them as `WorldEntitySnapshot`. GameWindow becomes thin.
 ---
 ## Render Pipeline (SSOT — current state + unified-PView target)
 > **The per-frame render step above is STALE** (it names deleted classes
 > `TerrainRenderer` / `StaticMeshRenderer`). The modern path (Phase N.5, mandatory) is
 > `WbDrawDispatcher` (entities) + `EnvCellRenderer` (indoor cell shells) +
 > `TerrainModernRenderer` (terrain), fed by the portal-visibility stack. This section is
 > the authoritative description of how indoor/outdoor rendering is *supposed* to work and
 > where the code currently diverges. Canonical reset handoff:
 > `docs/research/2026-05-31-render-architecture-reset-handoff.md`.
 **The principle (retail PView).** acdream must render the world the way retail does —
 through **one** portal-visibility traversal whose output **gates every geometry type
 uniformly**. From the player's cell, walk the portal graph; each visible cell carries a
 screen-space clip region (its portal opening, recursively intersected); the **outside**
 (terrain + outdoor scenery) is reached only through **exit portals** and is clipped to
 those openings. Interior cell shells, interior statics, and the outside are **all**
 clipped to their PView region. This is why retail is **seamless by construction**. Decomp
 anchors: `PView::ConstructView` (`:433750`), `InitCell` (`:432896`), `DrawCells`
 (`:432715`), `CEnvCell::find_visible_child_cell` (`:311397`), `SmartBox::update_viewer`
 (`:92761`). Reference port acdream owns but never invokes: WB `RenderInsideOut` /
 `VisibilityManager`.
 **The one rule:** *compute visibility once; enforce it once, for all geometry.* Indoors,
 you see the outside **only** through portal openings (clipped); an empty outside-view
 (windowless interior) draws **no** outdoor geometry. Outdoors, the gate is "everything."
 **Current divergence (the patchwork — what the reset must fix).** acdream computes the
 visibility correctly (`CellVisibility.ComputeVisibility` → `PortalVisibilityBuilder.Build`,
 a `ConstructView` port → `ClipFrameAssembler`) but then **enforces it three different,
 inconsistent ways**:
 1. `TerrainModernRenderer` — gated by `TerrainClipMode {Skip|Scissor|Planes}` (the Scissor
   fallback over-includes).
 2. `EnvCellRenderer` — gated by the per-cell clip slot (≈correct; the shells DO render —
   proven by the `[shell]` probe, `ACDREAM_PROBE_SHELL`).
 3. `WbDrawDispatcher` — gated by `ParentCellId ∈ visibleCellIds`, **but outdoor stabs
   (`ParentCellId==null`) bypass the gate** → outdoor scenery/terrain shows from inside
   (issue #78).
 Three gates that must agree but don't → structural seams (transparent walls,
 terrain-through-floor, grey enclosure). **The reset consolidates them into the single
 PView gate** (outside content clipped to the `OutsideView` region; no `ParentCellId==null`
 bypass; no Scissor over-include). This is a **consolidation of existing machinery**
 (`PortalVisibilityBuilder` + `ClipFrame`), not a rewrite. Do NOT add a fourth special-case
 gate to mask a seam — that anti-pattern produced the patchwork.
 ## Roadmap Model
 The old R1-R8 architecture sequence was a useful early refactor sketch, but it
--- a/docs/architecture/code-structure.md
+++ b/docs/architecture/code-structure.md
@ -1,376 +0,0 @@
 # acdream — code structure & extraction sequence
 **Status:** Living document. Created 2026-05-16 as the companion to the
 "Code Structure Rules" section in `CLAUDE.md`.
 **Purpose:** Describe the desired structural state of the App layer,
 explain the rules we've adopted, and lay out the safe extraction
 sequence from today's reality (one 10,304-line `GameWindow.cs`) to the
 target (thin `GameWindow`, small focused collaborators).
 **Companion to:** [`acdream-architecture.md`](acdream-architecture.md)
 (the layered architecture) and
 [`worldbuilder-inventory.md`](worldbuilder-inventory.md) (what we take
 from WB vs port ourselves).
 ---
 ## 1. The structural problem we're solving
 The layered architecture works: `AcDream.Core` is GL-free, the network
 layer is wire-compatible, the UI has a stable contract, plugins load.
 The structural debt is concentrated in **one file**:
 ```
 src/AcDream.App/Rendering/GameWindow.cs   10,304 lines
 ```
 `GameWindow` is the single object that:
 - Owns the GL context, the window, input, and shaders.
 - Reads ~40 different environment variables across its lifetime.
 - Hosts the live network session (`WorldSession`) and the offline
  pre-login state.
 - Owns parallel dictionaries for entity lookup (`_entitiesByServerGuid`,
  the per-landblock entity lists in `GpuWorldState`, plus the player
  controller's own state).
 - Drives selection / interaction (`WorldPicker`, `SendUse`,
  `SendPickUp`).
 - Drives per-frame render orchestration (sky → terrain → opaque mesh →
  transparent mesh → particles → debug lines → UI).
 - Wires up every plugin hook sink, every diagnostic, every panel.
 Almost every M1 / M2 bug touches this file. Every new feature adds a
 field plus a method plus a wiring call. It is not getting better on its
 own.
 The fix is **not** "rewrite `GameWindow` in one pass" — that's a
 high-risk change that would block M2. The fix is to **extract one
 collaborator at a time**, verify behavior is unchanged, ship, and
 move on. This document defines that sequence.
 ---
 ## 2. Code Structure Rules — the discipline
 Recap of the rules from `CLAUDE.md` with the rationale:
 ### Rule 1: No new substantial feature bodies in `GameWindow.cs`
 **Why:** Every line we add to `GameWindow` makes the eventual decomposition
 harder. New features that "live in" `GameWindow` instead of being
 extracted are the reason the file is 10k lines.
 **How to apply:** A new feature gets its own class under
 `src/AcDream.App/<Subsystem>/` (or deeper in `AcDream.Core` if it's pure
 logic). `GameWindow` owns a field and a wiring call, nothing more. If
 you find yourself adding a 200-line method to `GameWindow`, stop and
 extract.
 **Exemption:** Trivial wiring that *must* stay in `GameWindow` because
 it touches GL state during `OnLoad` is acceptable, but should still
 delegate to a collaborator for the substance.
 ### Rule 2: `AcDream.Core` must not depend on window / GL / backend projects
 **Why:** Core is the GL-free, testable layer. The moment Core imports
 a GL or windowing namespace, we've lost the ability to test it without
 a graphics context, and the layer split becomes fiction.
 **How to apply:** The only currently-allowed seams from Core into the
 WB / GL world are:
 - `WorldBuilder.Shared` — stateless helpers (`TerrainUtils`,
  `TerrainEntry`, `RegionInfo`).
 - `Chorizite.OpenGLSDLBackend.Lib` — stateless helpers
  (`SceneryHelpers`, `TextureHelpers`).
 Both are leaf namespaces with no GL state. If you need a new seam (e.g.
 WB's `ObjectMeshManager` needs to be visible from Core), the change
 **must** come with an inventory-doc update justifying it and ideally a
 slim interface in Core that the App layer implements.
 **Current reality:** `src/AcDream.Core/AcDream.Core.csproj` references
 `Chorizite.OpenGLSDLBackend` (not just `OpenGLSDLBackend.Lib`). This is
 historical. Two Core files import from it:
 - `World/SceneryGenerator.cs` — `Chorizite.OpenGLSDLBackend.Lib`
 - `Textures/SurfaceDecoder.cs` — `Chorizite.OpenGLSDLBackend.Lib`
 Both use the stateless `Lib` namespace only. The full project reference
 is wider than it needs to be; tightening it to just `WorldBuilder.Shared`
 + a stateless-helpers shim is a candidate future cut, but not urgent.
 ### Rule 3: UI panels target `AcDream.UI.Abstractions` only
 **Why:** This is the one rule that keeps D.2b (the future retail-look
 backend) viable. Every panel that imports `ImGuiNET` directly is a panel
 we'd have to rewrite when the backend swaps.
 **How to apply:** A panel's `using` block must mention
 `AcDream.UI.Abstractions.*` and nothing from `AcDream.UI.ImGui`. The
 panel writes against `IPanelRenderer`. The `ImGuiPanelRenderer`
 translates those calls to ImGui at runtime. Plugin-facing UI follows the
 same rule.
 ### Rule 4: Startup env vars enter through `RuntimeOptions`
 **Why:** Environment variables are global mutable state. Reading them
 at random call sites means (a) duplicated `Environment.GetEnvironmentVariable`
 boilerplate, (b) no single place to see "what flags does the client
 respond to?", (c) impossible to unit-test parsing.
 **How to apply:** `src/AcDream.App/RuntimeOptions.cs` is the typed
 options object. `Program.cs` builds it once from args + env and passes
 it to `GameWindow`. New startup flags add a field to `RuntimeOptions`
 and a parser in `RuntimeOptions.FromEnvironment`. They don't add
 `Environment.GetEnvironmentVariable` reads.
 **Scope:** `RuntimeOptions` is for **startup-time** configuration —
 things that don't change once the window is up. Runtime diagnostic
 toggles are Rule 5's domain.
 ### Rule 5: Runtime diagnostic toggles live in diagnostic owner classes
 **Why:** Diagnostic flags (`ACDREAM_DUMP_MOTION`, `ACDREAM_PROBE_*`,
 etc.) need to be both env-readable at startup *and* runtime-toggleable
 from the DebugPanel. Per-call-site env reads can't be runtime-toggled.
 **How to apply:** Today's template is
 `src/AcDream.Core/Physics/PhysicsDiagnostics.cs` — one static class with
 typed `Probe*` properties read from env vars once at startup, plus
 runtime setters that the DebugPanel binds. New diagnostic flags follow
 this shape, not the per-call-site pattern that dominates `GameWindow.cs`.
 **Cleanup direction:** The dozens of existing `ACDREAM_DUMP_*` reads
 inside `GameWindow.cs` are tech debt. We do NOT bulk-migrate them as
 part of this refactor — they're working, they're scattered, and
 moving them carries risk without a current acceptor. We migrate them
 opportunistically: when a `GameWindow` extraction lands and a diagnostic
 moves with it, route it through the new owner's diagnostic class.
 ### Rule 6: Tests live in the project matching the layer
 **Why:** Test discoverability + dependency hygiene. A test for a Core
 class belongs next to other Core tests; a test for an App class belongs
 in an App test project. Co-locating tests across layers makes the
 dependency graph dishonest.
 **How to apply:** One test project per source project that has tests.
 Today:
 - `tests/AcDream.Core.Tests/` ← `src/AcDream.Core/`
 - `tests/AcDream.Core.Net.Tests/` ← `src/AcDream.Core.Net/`
 - `tests/AcDream.UI.Abstractions.Tests/` ← `src/AcDream.UI.Abstractions/`
 `AcDream.App` does **not** yet have a test project. The RuntimeOptions
 extraction is the trigger to create `tests/AcDream.App.Tests/`. Future
 App-layer tests (LiveSessionController, SelectionInteractionController,
 etc.) go there.
 ---
 ## 3. Target structure of the App layer
 The end state — not what we're shipping in one pass, but the shape
 we're aiming at.
 ```
 src/AcDream.App/
 ├── Program.cs                          # parse args + env → RuntimeOptions, build GameWindow
 ├── RuntimeOptions.cs                   # typed startup options (Rule 4)
 ├── Rendering/
 │   ├── GameWindow.cs                   # thin: GL/window lifecycle + delegates per-frame to RenderFrameOrchestrator
 │   ├── RenderFrameOrchestrator.cs      # per-frame draw order (sky → terrain → opaque → trans → particles → debug → UI)
 │   ├── TerrainModernRenderer.cs        # (already exists)
 │   ├── TextureCache.cs                 # (already exists)
 │   ├── ParticleRenderer.cs             # (already exists)
 │   ├── Sky/                            # (already exists)
 │   ├── Wb/                             # (already exists — WB seam)
 │   └── Vfx/                            # (already exists)
 ├── Net/
 │   └── LiveSessionController.cs        # owns WorldSession lifecycle, login/handshake, reconnect
 ├── World/
 │   └── LiveEntityRuntime.cs            # owns per-entity state dicts + ServerGuid↔entity.Id translation
 ├── Interaction/
 │   └── SelectionInteractionController.cs  # owns WorldPicker, selection state, Use/PickUp dispatch
 ├── Streaming/                          # (already exists)
 ├── Input/                              # (already exists)
 ├── Audio/                              # (already exists)
 └── Plugins/                            # (already exists)
 ```
 What `GameWindow` keeps:
 - `IWindow` / `GL` / `IInputContext` lifecycle (constructor + `OnLoad` +
  `Run` + `OnClosing`).
 - `RuntimeOptions` reference (the typed startup config).
 - One field per collaborator (`_liveSessionController`,
  `_liveEntityRuntime`, `_selectionInteraction`,
  `_renderFrameOrchestrator`).
 - The Silk.NET event-handler stubs that delegate to collaborators.
 What `GameWindow` loses:
 - The 7 startup-time env var fields → moved into `RuntimeOptions`.
 - `TryStartLiveSession` + the post-login network drain → moved into
  `LiveSessionController`.
 - `_entitiesByServerGuid` + per-entity dictionaries + ServerGuid↔Id
  translation → moved into `LiveEntityRuntime`.
 - `WorldPicker` + `_selectedGuid` + `SendUse` / `SendPickUp` → moved
  into `SelectionInteractionController`.
 - Per-frame draw orchestration → moved into `RenderFrameOrchestrator`.
 The eventual `GameEntity` aggregation (target state described in
 `acdream-architecture.md` §"GameEntity: The Unified Entity") happens
 **after** `LiveEntityRuntime` is the single owner of entity state.
 Until then, the parallel-dicts problem is bounded inside one class
 instead of spread across `GameWindow`.
 ---
 ## 4. Extraction sequence — safest first
 Each step is **one PR-sized refactor**. Each must build clean, all
 tests pass, and visual verification at Holtburg looks identical to
 the previous step. Don't bundle two steps.
 ### Step 1 — `RuntimeOptions` (this PR)
 **Scope:** Replace startup-time env var reads with a typed options
 object built once in `Program.cs`.
 **Behavior change:** None. Same env vars, same defaults, same effects.
 **Risk:** Low. Mechanical substitution at ~10-15 call sites in
 `GameWindow.cs` + one constructor signature change.
 **Test:** Unit tests for `RuntimeOptions.FromEnvironment` parsing (the
 new `tests/AcDream.App.Tests/` project).
 **Verification:** `dotnet build` + `dotnet test` green. Visual launch
 verifies live mode + dat dir resolution still work.
 ### Step 2 — `LiveSessionController`
 **Scope:** Extract `TryStartLiveSession` + the WorldSession ownership +
 the post-EnterWorld drain (`OnLiveStateUpdated`, `OnLiveEntityDeleted`,
 etc.) into a controller class.
 **Behavior change:** None. Same wire behavior, same handshake.
 **Risk:** Medium. WorldSession lifecycle is load-bearing — every
 session-state crash would surface here. The change is a class
 extraction with the same event subscriptions, not a rewrite.
 **Test:** Existing `AcDream.Core.Net.Tests` already cover the wire
 layer. The controller itself gets a smoke test that verifies it can be
 constructed without a live socket (offline mode).
 **Verification:** Visual login + Holtburg traversal + door interaction
 identical to pre-extraction.
 ### Step 3 — `LiveEntityRuntime` (or `EntityRuntimeRegistry`)
 **Scope:** Centralize the parallel dictionaries — `_entitiesByServerGuid`,
 the streaming entity lists, the player controller's player entity —
 into one owner. Surface the ServerGuid↔entity.Id translation as a
 single API (eliminating the trap from L.2g slice 1c).
 **Behavior change:** None.
 **Risk:** Medium-high. Entity lookup is in every hot path. The change
 is structural (one owner instead of three) but the lookup semantics
 must be byte-identical.
 **Test:** Entity-spawn / despawn / lookup tests in
 `tests/AcDream.App.Tests/`. Existing visual verification at Holtburg
 catches any drift in interaction.
 **Verification:** Walk Holtburg, click NPC, open door, pick up item.
 All four M1 demo targets must still work.
 ### Step 4 — `SelectionInteractionController`
 **Scope:** Extract `WorldPicker`, `_selectedGuid`, `SendUse`,
 `SendPickUp`, and the `InputAction.Select*` / `UseSelected` /
 `SelectionPickUp` switch cases into one controller. Depends on Step 3
 (uses `LiveEntityRuntime`).
 **Behavior change:** None.
 **Risk:** Low-medium. Selection state is local to interactions; the
 network outbound side is well-defined (`InteractRequests.BuildUse` /
 `BuildPickUp`).
 **Test:** Selection state machine tests in `tests/AcDream.App.Tests/`.
 **Verification:** Click-to-select, double-click-to-Use, F-key pickup
 all still work.
 ### Step 5 — `RenderFrameOrchestrator`
 **Scope:** Extract the per-frame draw sequence (sky → terrain →
 opaque mesh → translucent mesh → particles → debug → UI) into a
 dedicated orchestrator that `GameWindow.OnRender` delegates to.
 **Behavior change:** None. Same draw order, same GL state.
 **Risk:** Medium. GL state management is touchy; the orchestrator
 must hand the GL context to the same renderers in the same order with
 the same per-pass state setup.
 **Test:** Visual verification only. Render orchestration is hard to
 unit-test without a GL context.
 **Verification:** Holtburg at radius 4, radius 8, radius 12 looks
 identical across all four quality presets.
 ### Step 6 — `GameEntity` aggregation (the big one)
 **Scope:** Consolidate `WorldEntity` + `AnimatedEntity` + the per-entity
 state in `LiveEntityRuntime` into one `GameEntity` class (the target
 described in `acdream-architecture.md`). Every entity in the world —
 player, NPC, monster, door, item — becomes a single `GameEntity`.
 **Behavior change:** None at the wire / visual level; substantial at
 the call-site level (everyone moves to the new entity API).
 **Risk:** High. Touches every system that reads entity state.
 **Test:** All existing tests + the new `AcDream.App.Tests` suite. Visual
 verification at every M1 / M2 scenario.
 **Verification:** Full M2 demo loop (equip sword, kill drudge, pick up
 loot, open inventory) works identically.
 ---
 ## 5. Rules of the road during the extraction
 1. **One step at a time.** A PR that ships Step 1 ships only Step 1.
   Bundling steps makes failures hard to isolate.
 2. **Behavior preservation is the acceptance criterion.** Every step
   must build clean, all tests pass, and visual verification at the
   appropriate M1 / M2 scenarios must succeed. We're moving code, not
   changing it.
 3. **No new features during an extraction step.** If you spot a real
   bug while extracting, file it in `docs/ISSUES.md` and address it in
   a separate commit (before or after the extraction, not folded into
   it).
 4. **Diagnostic toggle migrations are opportunistic.** When a method
   moves to a new owner, the diagnostic flag inside it can move to a
   diagnostic class as part of the same commit. We do not do a bulk
   diagnostic-cleanup pass.
 5. **Update this document when the plan changes.** If Step 3 turns out
   to need a different shape than described above, update §4 in the
   same session you discover the divergence.
 ---
 ## 6. What this document is **not**
 - **Not a full rewrite plan.** The point is the *opposite* — small
  steps, verified at each boundary.
 - **Not blocking M2.** Step 1 is small enough to ship without
  disrupting M2 work. Later steps interleave with M2 / M3 phases as
  the corresponding code paths come into focus.
 - **Not a substitute for the milestones / roadmap.** Those drive the
  feature work. This drives the structural work that runs underneath.
--- a/docs/architecture/retail-divergence-register.md
+++ b/docs/architecture/retail-divergence-register.md
@ -1,244 +0,0 @@
 # Retail Divergence Register — 2026-06-12
 **What this is.** The single auditable register of every known place acdream's
 runtime behavior can deviate from the retail client (Sept 2013 EoR build,
 `docs/research/named-retail/`). It was triggered by a week of "small things"
 surfacing one at a time through playtesting — a ±5 m culling-box promise
 (#119), an epsilon eye-clip + rescue (knife-edge port), a half-ported cell
 walk — each of which was a *known* deviation that lived only in a code
 comment until it produced a visible symptom.
 **The rule.** Every intentional deviation from retail behavior gets a row in
 this register. A deviation discovered without a row here is a bug twice over:
 once for the behavior, once for the missing row. When you add a deviation
 (new adaptation, new stopgap, new approximation), add the row in the same
 commit. When you retire one (port the retail mechanism), delete the row in
 the same commit.
 **The review trigger.** Any unexplained visual or physics symptom → scan this
 register FIRST, before instrumenting. Filter by the subsystem you're staring
 at; each row's "Risk if assumption breaks" column is written as the symptom
 you would observe. Most of the historical multi-session sagas (#119 vanishing
 staircase, #98 cellar ascent, the doorway FLAP) began as a deviation in
 exactly this register's scope.
 **Kinds.**
 - **Intentional architecture** — deliberate design choices we stand behind; retiring them would be a redesign, not a fix.
 - **Adaptation** — required by a real structural difference (async streaming vs synchronous load, ACE vs retail server semantics, GL vs D3D). Correct *given the difference*; each carries an equivalence argument.
 - **Documented approximation** — we know retail's mechanism and chose a cheaper/safer stand-in with a recorded justification.
 - **Temporary stopgap** — known-incomplete; explicitly awaiting a port/phase. These are scheduled debt.
 - **Unclear** — the recorded justification is missing, contradictory, or never argued. These are the most dangerous rows and head the retire list.
 Dedup convention: one divergence = one row at its primary site; secondary
 sites listed in parentheses. Issue numbers in **bold** are the symptom
 history. Sources: 5-area code sweep 2026-06-12 +
 `docs/architecture/worldbuilder-inventory.md` + `docs/ISSUES.md`
 accepted-divergence entries (#96, #49, #50).
 ---
 ## 1. Intentional architecture (IA) — 17 rows
 | # | Divergence | Where (file:line) | Why it is safe / justified | Risk if assumption breaks | Retail oracle |
 |---|---|---|---|---|---|
 | IA-1 | Contact-plane pre-seed on grounded movers (**#96 ACCEPTED** per ISSUES.md) — retail's `CTransition::init` clears `contact_plane_valid`; we seed from the body's previous-frame plane | `src/AcDream.Core/Physics/PhysicsEngine.cs:919` | Removing it broke last-step stair `step_up` (`892019b`, reverted); seed propagates the body's *real current* plane, behavior matched retail in the A6.P3 gates | A stale pre-seeded plane lets `AdjustOffset` project sub-step 1 onto a plane retail wouldn't have yet — wrong slope motion / step-up acceptance right after leaving a surface | `CTransition::init`, pc:272547 family |
 | IA-2 | Lateral self-heal beyond retail's keep-curr: when no candidate contains the sphere, try `FindVisibleChildCell` over the claim's stab-list before keeping the claim | `src/AcDream.Core/Physics/CellTransit.cs:912` | Reuses the recovery retail's own `AdjustPosition` performs (:280028 stab-list mode), applied at the `find_cell_list` site to heal near-miss claims without a doorway crossing | In containment-gap geometry, membership flips to a neighbouring room where retail keeps curr — wrong render root / collision cell at gap positions | `find_cell_list` keep-curr pc:308788-308825; `find_visible_child_cell` :311444 |
 | IA-3 | `get_state_velocity` prefers dat cycle velocity (`MotionData.Velocity × speedMod`) over the decompiled constant; constant kept only as max-speed clamp | `src/AcDream.Core/Physics/MotionInterpreter.cs:315` | Retail's constant equals the Humanoid RunForward `MotionData.Velocity`, so both paths agree on retail dats; dat is ground truth for other MotionTables (r03 §1.3) | Where dat velocity ≠ constant, body speed differs from the retail binary — DR / observer drift on exotic creatures or modded dats | `FUN_00528960`; `_DAT_007c96e0` RunAnimSpeed |
 | IA-4 | `MultiplyFramerate` omits retail's negative-factor StartFrame↔EndFrame swap (direction encoded in Framerate sign instead) | `src/AcDream.Core/Physics/AnimationSequencer.cs:129` | Our callers (ForwardSpeed updates) only pass positive factors; Advance loop handles negative framerates against StartFrame as lower bound | A future negative-factor caller (reverse playback) scales without swapping bounds — wrong frame range traversal instead of clean reversal | `FUN_005267E0`; ACE Sequence.cs L277-287 |
 | IA-5 | Per-ENTITY vertex-derived AABB culling (+5 m animated-drift margin; animated entities bypass cull) vs retail per-PART dat drawing spheres | `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs:693` (bounds at `src/AcDream.Core/World/WorldEntity.cs:153`, `src/AcDream.Core/Meshing/GfxObjBounds.cs:14`; dead `PerEntityCullRadius=5.0f` at dispatcher :210) | Batched MDI rendering can't cheaply cull per part; bounds derive from the SAME dat vertex data that gets drawn (containment by construction — the **#119** fix, `6a9b529`; memory: feedback_culling_bounds_from_drawn_data) | Geometry escaping bounds+margin (pose drift >5 m, a hydration path skipping `SetLocalBounds`) makes the whole entity vanish on-screen — the #119 vanishing-staircase class | `CGfxObj.drawing_sphere` / viewconeCheck 0x005a09a4 |
 | IA-6 | Chat scrollback 500 lines vs retail ~200 (configurable) | `src/AcDream.Core/Chat/ChatLog.cs:19` | Strictly more useful for a dev client + plugins; deliberate default | Negligible — only if a plugin/UI behavior is ever specified against retail's exact retention cap | retail chat scrollback (~200) |
 | IA-7 | PhysicsScript replay keyed by (scriptId, entityId) replaces the prior instance; retail's ScriptManager linked list could hold duplicates | `src/AcDream.Core/Vfx/PhysicsScriptRunner.cs:51` | Prevents duplicate-stacking on server retriggers; flat keyed list simpler than retail's linked schedule; hedged to retail's common path | A server intentionally layering the same script on the same object shows ONE effect where retail shows several (overlapping casts/impacts) | `ScriptManager::Start` FUN_0051be40 / tick FUN_0051bfb0 |
 | IA-8 | Synthetic outdoor cell node as render root (outdoor-as-cell, Option A): one unified `DrawInside` path; retail roots at a real CLandCell with a separate outdoor pipeline | `src/AcDream.App/Rendering/OutdoorCellNode.cs:23` | Eliminating the inside/outside render branch kills the indoor FLAP by construction (2026-06-07 cutover); R-A2 restored retail's per-building flood topology | Any consumer assuming the root is a real cell mis-handles the synthetic node — historically the 2↔6 flood-depth oscillation and doorway-flap class | `SmartBox::RenderNormalMode` → DrawInside, decomp:92635; `LScape::draw` 0x00506330; ConstructView(CBldPortal) decomp:433827 |
 | IA-9 | One unified camera matrix for terrain — retail's separate `LScape::update_viewpoint` landscape viewpoint does not exist | `src/AcDream.App/Rendering/TerrainModernRenderer.cs:266` | Phase W T4.2: with one matrix everywhere, viewpoint-desync bugs are unrepresentable — the unification IS the correctness argument | Anything retail derives from the landcell-relative viewpoint (float precision at extreme coords, viewpoint-keyed state) has no analogue; a future port expecting it silently reads the camera | `LScape::update_viewpoint`; `LScape::draw` 0x00506330 |
 | IA-10 | Transparent groups sorted back-to-front per GROUP by first-instance position (no within-group sort) vs retail per-poly BSP-order draw | `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs:1364` (comparer :1662) | One MDI call per pass requires group-granularity ordering; per-poly sorting is incompatible with instanced multi-draw; works when group instances are spatially coherent | Spatially spread or interleaved transparent groups composite in the wrong order — popping / wrong see-through layering as the camera moves | retail per-poly BSP-order transparent draw (D3DPolyRender / PView::DrawCells) |
 | IA-11 | Tier-1 cross-frame batch-classification cache for static entities (retail re-walks part arrays every frame) | `src/AcDream.App/Rendering/Wb/EntityClassificationCache.cs:12` | Issue #53 perf tier; invariants documented (keys = EntityId + OWNING-landblock hint post-**#119** fix `2163308`; invalidation at despawn/LB-unload; mutation audit 2026-05-10) | Key collision or missed invalidation serves one entity another's batches — session-sticky wrong meshes (the #119 broken-stairs/water-barrel symptom) | retail per-frame part-array classification (no cache) |
 | IA-12 | UI toolkit mirrors retail behavior from research docs, not a byte-port — keystone.dll is outside decomp coverage; observed constants embedded (drag 3 px, tooltip 1000 ms) | `src/AcDream.App/UI/README.md:3` | keystone.dll has no PDB/decomp; semantics reconstructed from the six `docs/research/retail-ui/` deep-dives, keeping retail's event-type constants so panel switch-cases transplant cleanly | Edge-case input semantics the research under-specified (drag threshold, tooltip timing, focus hand-off, capture corners) differ silently with no oracle to diff against | keystone.dll Device DAT_00837ff4; docs/research/retail-ui/04-input-events.md |
 | IA-13 | GameEventType registry deliberately omits event types retail ignores; unknown events fall through unhandled | `src/AcDream.Core.Net/Messages/GameEventType.cs:11` | Retail also ignores them — dropping matches retail by construction | If the "retail ignores X" judgment is wrong for any opcode (or a server mod uses one), the event is silently dropped with no diagnostic pointing at the omission | retail GameEvent dispatch (ignored-event set) |
 | IA-14 | Rendering + dat-handling base is WorldBuilder's tested port, not a fresh retail-decomp port (Phase N.4/O design stance) | `docs/architecture/worldbuilder-inventory.md` (code at `src/AcDream.{Core,App}/Rendering/Wb/`) | WB visually verified on the AC world, MIT, same stack; known WB↔retail deltas resolved case-by-case — terrain split kept retail `FSplitNESW` (**#51**, pinned by `SplitFormulaDivergenceTest`), scenery drift accepted (AP-31) | A WB-upstream divergence not yet caught ships silently as "our" behavior; guard = the inventory doc's 🟢/🔴 split + per-formula divergence tests | retail decomp per algorithm; `tests/.../SplitFormulaDivergenceTest.cs` |
 | IA-15 | D.2b retail UI is our own UiHost/UiElement retained-mode tree drawing dat-sprite window frames, not a byte-port of keystone.dll's LayoutDesc binary tree. Both the vitals window (`LayoutDesc 0x2100006C`) and the chat window (`LayoutDesc 0x21000006`) are rendered by the LayoutDesc importer; `UiNineSlicePanel`/`RetailChromeSprites` now back only plugin panels | `src/AcDream.App/UI/Layout/LayoutImporter.cs` (vitals + chat) + `src/AcDream.App/UI/Layout/ChatWindowController.cs` | keystone.dll has no PDB/decomp so a byte-port is impossible by definition; we mirror retail's ElementDesc field model + controls.ini tokens, and the chrome sprites ARE the real dat RenderSurfaces (Step-0 prove-out 2026-06-14 confirmed 0x06004CC2 center + 0x060074BF..C6 bevel). The 8-piece edge/corner→position mapping is DATA-DRIVEN from the dat: the `LayoutImporter` reads `LayoutDesc 0x2100006C`/`0x21000006` and resolves chrome element positions + sprite ids directly from parsed dat fields; vitals locked by the conformance fixture `tests/AcDream.App.Tests/UI/Layout/fixtures/vitals_2100006C.json` | Remaining residual risk: anchor resolution at non-800×600 and the controls.ini cascade still lack an oracle — layout scaling at non-reference resolution and stylesheet token inheritance differ silently | `LayoutDesc 0x2100006C`/`0x21000006` (SHIPPED); `docs/research/2026-06-15-layoutdesc-format.md`; controls.ini tokens; keystone.dll layout eval (no PDB) |
 | IA-17 | Toolbar window FRAME is toolkit-supplied (per-window UiNineSlicePanel 8-piece bevel, drawn over content via UiElement.OnDrawAfterChildren) rather than the window-manager-owned chrome retail paints uniformly around every window | `src/AcDream.App/Rendering/GameWindow.cs` (toolbar mount) + `src/AcDream.App/UI/UiNineSlicePanel.cs` | LayoutDesc 0x21000016 has NO baked frame; retail's toolbar frame is window-manager chrome (keystone.dll). We draw the same reusable 8-piece bevel chat/vitals use; border drawn over content so the toolbar's 2px-wide row-2 right cap (W=8) can't poke through. Same pattern as the chat window. | Until a central window manager owns chrome uniformly, per-window wraps can drift (size/offset/z-order) from each other and from retail; the border-over-content rule is the toolkit's, not the WM's | gmToolbarUI WM chrome (keystone.dll, no PDB); no bevel ids in LayoutDesc 0x21000016 (toolbar dump) |
 | IA-18 | Effect overlay tile (enum 0x10000005) is a `ReplaceColor` SURFACE SOURCE — pure-white pixels in the composited drag icon are replaced PER-PIXEL with the same (x,y) pixel of the effect tile (the SURFACE overload `SurfaceWindow::ReplaceColor` 0x004415b0), preserving the tile's texture/gradient; the tile itself is NOT blitted as an additional layer. This IS faithful retail behavior. **Anti-regression: do NOT re-implement this as a blit layer NOR as a flat-color replace (it is a per-pixel surface copy).** | `src/AcDream.App/UI/IconComposer.cs` (`ReplaceWhiteFromSurface`) | Faithful port of `IconData::RenderIcons` @407614 → the SURFACE overload `ReplaceColor` 0x004415b0 (`dst[x,y]=src[x,y]` where `dst==white`); confirmed via clean Ghidra decompile + named decomp + visual (the Energy Crystal's blue is a gradient, 2026-06-17). | A blit-layer or flat-color re-implementation would show the wrong effect look (no gradient) — the visual-verification regression that retired the mean-color approximation | `IconData::RenderIcons` acclient_2013_pseudo_c.txt:407524; `ReplaceColor` SURFACE overload 0x004415b0:71656; `docs/research/2026-06-17-stateful-icon-RESOLVED.md` |
 ---
 ## 2. Adaptation (AD) — 28 rows
 | # | Divergence | Where (file:line) | Why it is safe / justified | Risk if assumption breaks | Retail oracle |
 |---|---|---|---|---|---|
 | AD-1 | Lost-cell machinery replaced by recoverable outdoor demote (**#107** safety net) + outdoor-restore `max(terrainZ, z)` under-terrain lift; retail goes `GotoLostCell` | `src/AcDream.Core/Physics/PhysicsEngine.cs:553` (+ :808) | acdream has no lost-cell state machine; outdoor landcell is the recoverable equivalent; the #107 auto-entry hold should make the demote branch unreachable | Gap in the hold → player committed to outdoor terrain inside/under a building (fake-grounded spawn, fall-through); a legit below-heightmap server restore is silently lifted — upward warp vs server | `GotoLostCell` pc:283418; `SetPositionInternal` 0x00515bd0, pc:283892-283945 |
 | AD-2 | Async spawn gates replacing retail's synchronous cell load. **#135 refinement:** an INDOOR spawn/teleport (cell ≥ 0x0100, hydratable) gates ONLY on the EnvCell floor (`IsSpawnCellReady`), NOT the terrain heightmap; an OUTDOOR spawn (or an unhydratable indoor claim that demotes outdoor) gates on the terrain-ready hold (**#106**). A dungeon's negative-offset cells can place the spawn's WORLD position in a neighbour terrain landblock the #135 dungeon collapse doesn't load, so a terrain requirement would hang indoor login/teleport forever (cellReady true, terrain null) — the player lands on the cell floor, terrain is irrelevant indoors. Claims beyond NumCells skip the gate (demoted) | `src/AcDream.App/Rendering/GameWindow.cs` (`isSpawnGroundReady` lambda ~1010 + `TeleportArrivalReadiness` ~5012) (+ `src/AcDream.App/Input/PlayerModeAutoEntry.cs:69`, `src/AcDream.Core/Physics/PhysicsEngine.cs:468`) | Entering earlier integrates gravity against an empty world (free-fall into void); the gate is the async-streaming equivalent of retail's blocking load; a looser "any struct present" version reproduced the transparent-interior wedge. Indoor-on-cellReady is the faithful equivalent of retail's synchronous cell load + place-on-floor (terrain under a dungeon is meaningless; the pre-#135 terrain hold only passed because the 25×25 window streamed the neighbour terrain) | Gate opens early → raw claim commit → outdoor demote mid-building; predicate never satisfied (streamer stall, dat edge case) → login wedges in pre-player mode; an indoor spawn whose cell never hydrates now holds on cellReady alone (no terrain backstop) — but that path is exactly the #107 hold | retail synchronous cell load before SetPosition (no gate exists) |
 | AD-3 | Outdoor seeds always walk the transit array (retail skips the walk when the seed CLandCell is null/unloaded); per-cell lookups no-op on unhydrated data | `src/AcDream.Core/Physics/CellTransit.cs:503` | Equivalence argument: with nothing hydrated every lookup inside the walk no-ops, so the result matches retail's skipped walk | Near partially-streamed landblocks, building-transit promotion silently can't fire until structs hydrate — membership stays outdoor while the player is inside a building | `CObjCell::find_cell_list` 0052b535-0052b56c (null-CLandCell case) |
 | AD-4 | `point_in_cell` against an unhydrated CellBSP returns false (skip) rather than the null-node "inside" default; retail never queries unloaded cells | `src/AcDream.Core/Physics/CellTransit.cs:588` | The null-node default would make an unhydrated cell spuriously claim every point; skipping is the conservative streaming-safe choice | During hydration, a point genuinely inside a not-yet-loaded cell resolves outdoor/stale — transient membership misclassification driving wrong collision set and render root | `CEnvCell::find_visible_child_cell` :311397; cell-BSP vtable[0x84] |
 | AD-5 | Outdoor `point_in_cell` is an identity compare against the global XY-column cell from `LandDefs.AdjustToOutside` (no per-cell containment test) | `src/AcDream.Core/Physics/CellTransit.cs:865` | Landcells are disjoint 24 m columns — identity-compare against the column under the sphere centre is exactly equivalent to retail's per-candidate test | If block-origin/lcoord math is wrong at a landblock seam, the compare silently never matches — outdoor membership freezes at boundaries (the pre-#106 symptom) | `find_cell_list` pick pc:308788-308825; `CLandCell::point_in_cell` (get_block_offset pc:308804) |
 | AD-6 | Per-LANDBLOCK shadow re-flood on hydration vs retail per-CELL `recalc_cross_cells` | `src/AcDream.Core/Physics/ShadowObjectRegistry.cs:339` | The streaming unit IS the landblock; one hook per hydration event covers both race directions (entity-before-cells, cells-after-spawn) | Any cell-hydration path that doesn't raise the landblock hook leaves an entity's shadow set stale — walk-through / missing collisions in just-streamed cells | `CObjCell::init_objects` → `recalc_cross_cells`, 0x0052b420 / 0x00515a30 |
 | AD-7 | Full collision exemption on ETHEREAL alone; retail requires ETHEREAL_PS **and** IGNORE_COLLISIONS_PS (ETHEREAL-alone takes the unported `obstruction_ethereal` path) | `src/AcDream.Core/Physics/CollisionExemption.cs:78` | ACE's `Door.Open()` broadcasts ETHEREAL only (0x0001000C); without the shortcut, opened doors stay solid on ACE | ETHEREAL-only targets generate NO contact where retail records contact-but-allows-passage; against a retail-semantics server the bit means something different than we implement | pc:276782 (combined gate), :276795 (obstruction_ethereal) |
 | AD-8 | MoveTo arrival gate `max(minDistance, distanceToObject)`; retail tests `dist <= min_distance` only | `src/AcDream.Core/Physics/RemoteMoveToDriver.cs:161` | ACE ships the threshold in `distance_to_object` with `min_distance == 0`; without the max, monsters never "arrive" and oscillate at melee range (user-reported 2026-04-28) | A server using both wire fields with retail semantics + large `distance_to_object` makes remotes stop short of the retail arrival point | `MoveToManager::HandleMoveToPosition` chase-arrival |
 | AD-9 | 1.5 s stale-destination give-up timer on remote MoveTo (retail's MoveToManager runs until cancelled) | `src/AcDream.Core/Physics/RemoteMoveToDriver.cs:136` | Liveness guard sized to ACE's ~1 Hz re-emit cadence; prevents steering toward a stale destination after a missed cancel (the run-in-place symptom) | A server emitting MoveTo slower than ~1.5 s makes remotes freeze mid-chase and snap later instead of steering continuously | MoveToManager (no equivalent timeout) |
 | AD-10 | Remote slope projection relocated to the queue-empty/head-reached combiner boundary; retail projects inside `CTransition::adjust_offset` during the sweep | `src/AcDream.Core/Physics/PositionManager.cs:47` | Remote bodies don't run a full local transition sweep; boundary projection removes the ~5 Hz Z staircase on slopes, no-op on flat ground | The single-point terrain-normal sample can differ from the sweep's contact plane (cell boundaries, props underfoot) — remote Z drift / stair-stepping | `CTransition::adjust_offset` pc:272296-272346 |
 | AD-11 | Useability fallback: retail blocks Use entirely on null/zero useability; we allow it (behavioral fallback in the `IsUseableTarget` caller; justification recorded here) | `src/AcDream.Core/Physics/PhysicsDiagnostics.cs:163` | ACE's seed DB ships many weenies with `_useability` unset; without the fallback doors/lifestones/creatures are un-Useable on ACE | Objects a retail-faithful server intentionally marks non-useable become useable in acdream — wrong interaction gating when the ACE-ships-null assumption stops holding | `ItemHolder::UseObject` pc:402923 |
 | AD-12 | SecondaryAttributeTable coefficients hardcoded (Health=End×0.5, Stam=End×1.0, Mana=Self×1.0) instead of dat-read; unknown attributes contribute 0 | `src/AcDream.Core/Player/LocalPlayerState.cs:279` | Coefficients never vary across retail dat versions; re-confirmed by ACE AttributeFormula.cs + holtburger; dat port can replace later | A customized portal.dat with modified vital formulas silently yields wrong max-vitals; a missing attribute snapshot underestimates max | SecondaryAttributeTable portal.dat 0x0E0..0x0E2; `CreatureVital::GetMaxValue` 0x0058F2DD |
 | AD-13 | 1-second dedup window for identical system chat messages (retail has none) | `src/AcDream.Core/Chat/ChatLog.cs:29` | ACE dual-sends the same system text (0xF7E0 + 0x02EB) for back-compat; without dedup every line doubled (Phase J compromise) | Two genuinely distinct but textually identical system messages within 1 s collapse to one line where retail shows both | ACE dual-send 0xF7E0 + 0x02EB |
 | AD-14 | Script anchor world position cached at `Play()` time; retail fires hooks via vtable dispatch on the live owning PhysicsObj | `src/AcDream.Core/Vfx/PhysicsScriptRunner.cs:55` | Core's runner is decoupled from the entity graph; documented contract pushes per-frame anchor refresh to the owning subsystem (done for AttachLocal) | Any caller that forgets the per-frame refresh strands long-running effects at the spawn position while the entity walks away | FUN_0051bfb0 per-frame hook dispatch on owner |
 | AD-15 | `IsEnv` masks low-16 of the cell id (`(Id & 0xFFFF) >= 0x100`) where retail tests the full id | `src/AcDream.Core/World/Cells/ObjCell.cs:25` | Every real prefixed EnvCell id has low-16 ≥ 0x100 and every outdoor cell ≤ 0x40 — identical answers for all real dat ids, works for both bare and prefixed forms | None for real dat data; a hypothetical convention-violating id would route to the wrong (BSP vs terrain) point-in-cell logic | `CObjCell::GetVisible` pc:308215 |
 | AD-16 | Building-flood gate is a CPU frustum test on each building's `PortalBounds` AABB; retail floods exactly when the shell draws and an aperture survives (no bounds constant anywhere) | `src/AcDream.App/Rendering/GameWindow.cs:7634` | Documented as the tight equivalent of the shell viewconeCheck for flood purposes (the FPS fix the Chebyshev≤1 hack approximated); per-portal admission still goes through BuildFromExterior's screen clip; missing-bounds buildings always flood (safe over-include) | A too-small/stale PortalBounds AABB means the interior never floods — doorway shows a hole/black aperture from outside (inverse of the vanishing-staircase class) | `DrawBuilding` 0x0059f2a0; `BSPPORTAL::portal_draw_portals_only` 0x53d870 |
 | AD-17 | ≤8 GPU `gl_ClipDistance` half-planes per view region, degrading to a union-AABB scissor (over-include) on multi-polygon / >8-edge views; particles always scissor; scissor slices disable per-object viewcone culling. Retail CPU-clips against the exact portal polygon | `src/AcDream.App/Rendering/ClipPlaneSet.cs:23` | GL guarantees only 8 simultaneous clip planes; invariant documented: over-inclusion is safe, under-inclusion is the bug class | Fallback on complex multi-aperture views draws terrain/sky/particles/objects outside the true aperture but inside its AABB — background/interior bleed strips at doorways (the **#130** family) | `ACRender::polyClipFinish` decomp:702749; PView portal_view slices |
 | AD-18 | Aperture far-Z punch is two-pass stencil-gated with an invented mark bias: 0.0005 NDC capped to a 0.5 m EYE-SPACE span (`MarkBiasNdc`); retail's single DEPTHTEST_ALWAYS punch is safe only under painter's far→near order we don't have | `src/AcDream.App/Rendering/PortalDepthMaskRenderer.cs:149` | **#117** (2026-06-11): the unconditional punch erased nearer occluders, painting interiors through them; the two-pass form is the z-buffered equivalent of retail's ordering safety. **#129** (2026-06-12): the constant-NDC bias spanned ~190 m of eye depth at a landblock (non-linear depth) → distant occluders punched; the eye-space cap bounds the reach (`Issue129PunchBiasTests`). DO-NOT-RETRY: punch must stay depth-gated (ISSUES #108) | Door-plane-hugging geometry beyond the 0.5 m cap re-occludes the aperture (a **#108**-class regression at >10 m viewing range); an occluder within the cap in front of a distant aperture still punches through | `D3DPolyRender::DrawPortalPolyInternal` 0x0059bc90 (maxZ1=7 / maxZ2=6) |
 | AD-19 | Under outdoor roots, ALL dynamics draw in one z-buffered final pass; retail draws objects painter-ordered per landcell inside the landscape pass (interior roots route per **#118**) | `src/AcDream.App/Rendering/RetailPViewRenderer.cs:126` | The dynamics-drawn-LAST invariant is what makes the aperture depth punch safe (first BR-2 attempt punched after dynamics and erased the player, reverted `88be519`); z-buffer substitutes for painter's order on opaque geometry | Punch/seal correctness hinges on an ordering invariant — any pass added after DrawDynamicsLast, or alpha content needing painter order, gets erased inside apertures or composites wrong | `LScape::draw` → `DrawBlock` 0x005a17c0 → DrawSortCell pc:430124; `PView::DrawCells` 0x005a4840 |
 | AD-20 | Camera sweep fallback seeds the eye's `AdjustPosition` from the PLAYER's cell; retail re-seats at the sought eye's own tracked cell (rest of function is a verbatim `update_viewer` port) | `src/AcDream.App/Rendering/PhysicsCameraCollisionProbe.cs:97` | acdream's camera doesn't track the sought-eye's cell separately; the eye is near the player so the player-cell stab list is assumed to cover it | An eye outside the player cell's stab-list coverage (boundary corners, cross-landblock pull-back) seats in the wrong cell — and the viewer cell roots the whole render: one-frame wrong root (flap-class flash) | `SmartBox::update_viewer` 0x00453ce0, pc:92878-92883 |
 | AD-21 | Null-clipRoot legacy outdoor safety path (no portal visibility, no punches/seals, no-clip terrain) for pre-spawn / login / legacy cameras; in-world retail always has a viewer_cell root | `src/AcDream.App/Rendering/GameWindow.cs:7671` | Result is null ONLY when neither an interior root nor the synthetic outdoor node exists; kept so the login screen shows the live sky | If viewer-root resolution ever returns null in-world (membership bug, fly-camera edge), the frame silently degrades — interiors stop drawing through doorways; the old two-branch FLAP reappears for those frames | `SmartBox::RenderNormalMode` decomp:92635 |
 | AD-22 | Async streamed mesh loading with point-of-use self-heal (`EnsureLoaded` re-request in the dispatcher's per-frame meshMissing path, **#128**); retail loads synchronously — geometry is never absent | `src/AcDream.App/Rendering/Wb/WbMeshAdapter.cs:211` | Documented convergence argument: the self-heal makes absence transient, converging the async pipeline to retail's never-absent guarantee | A missing mesh referenced OUTSIDE the dispatcher's walk (a future consumer not touching meshMissing) stays permanently invisible — the #119/#128 broken-stairs class; best case, late pop-in | retail synchronous content load (note at WbMeshAdapter.cs:211) |
 | AD-23 | Live entities with `ServerGuid != 0` and null `ParentCellId` are culled (ClipSlotCull) while indoor clip routing is active; retail objects are always cell-resident (synchronous add-to-cell at creation) | `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs:484` | Phase U.4 policy: parentless = unresolved indoors, equivalent to retail's not-in-any-visible-cell ⇒ not drawn, *given membership resolves promptly* | An entity whose membership lags (late CreateObject hydration, resolver hiccup) blinks invisible while the player is indoors, even in plain sight | retail per-cell object lists in PView traversal |
 | AD-24 | EnvCell shell geometry hash-deduplicated ((environmentId, structure, surface overrides) → 31-multiplier hash) and instanced; retail draws each CEnvCell's own structure directly | `src/AcDream.App/Rendering/Wb/EnvCellRenderer.cs:276` | Verbatim WB EnvCellRenderManager port (Phase A8); dedup is what makes the single-VAO MDI cell pipeline cheap; intended visuals identical | A hash collision between distinct tuples renders the wrong interior shell in some room with NO diagnostic firing — wrong walls/floor in a dungeon room | retail `PView::DrawCells` → per-cell drawing_bsp (cited at :319) |
 | AD-25 | Wall-bounce velocity reflection suppressed on landing (fires only airborne-before AND airborne-after); retail bounces unless grounded→grounded-and-not-sledding | `src/AcDream.App/Input/PlayerMovementController.cs:1212` | Our per-frame architecture amplifies the artifact (post-reflection +Z defeats the `Velocity.Z <= 0` landing-snap gate → micro-bounce death spiral); at elasticity 0.05 retail's landing bounce is imperceptible; sledding reverts to retail rule | Landing-reflection-dependent behavior (slope-landing momentum, high-elasticity surfaces) won't reproduce; the suppression masks the landing-snap gate fragility and could outlive its reason | `handle_all_collisions` pc:282699-282715; ACE PhysicsObj.cs:2656-2721 |
 | AD-26 | Auto-walk arrival requires facing alignment (invented 5° arrive / 30° walk-while-turning bands); retail's check is `dist <= radius` exact | `src/AcDream.App/Input/PlayerMovementController.cs:575` | ACE does the final `Rotate(target)` server-side before the Use callback; without a local gate the body used items while facing away (user feedback 2026-05-15). Thresholds are NOT retail constants | Arrival delayed by the rotation phase; if heading convergence fights another yaw writer, `AutoWalkArrived` never fires and the queued Use/PickUp never completes | `MoveToManager::HandleMoveToPosition`; `apply_interpreted_movement` |
 | AD-27 | Use/PickUp action re-sent on natural auto-walk arrival; retail sends the action once (server MoveToChain callback completes it) | `src/AcDream.App/Input/PlayerMovementController.cs:322` | ACE's server-side chain may have timed out by the time our body arrives; the close-range re-send hits ACE's WithinUseRadius fast-path | If the server's chain has NOT timed out, the action executes twice — door toggles open-then-closed, use-once interactions double-fire; protocol noise on non-ACE servers | ACE CreateMoveToChain / WithinUseRadius |
 | AD-28 | Chat transcript (`UiText`) and input (`UiChatInput`) are two separate widget classes placed inside their dat-authored container panels; retail's `ChatInterface` uses a single mode-flagged `UIElement_Text` (Type-12) that switches between read and edit mode | `src/AcDream.App/UI/Layout/ChatWindowController.cs:135` (transcript) + `:150` (input) | `UIElement_Text` is inside keystone.dll with no PDB/decomp; a two-widget split is functionally equivalent (read-only scroll, editable input) and is the structural adaptation required by our UiElement architecture | A future consumer expecting a single widget for both read/write (e.g. a plugin calling the chat API and getting one widget back) must be written to the two-widget contract | `UIElement_Text` (Type-12) @ keystone.dll; `gmMainChatUI::PostInit` @0x4ce130 |
 | AD-29 | `ClientObjectTable` fires global `ObjectAdded`/`ObjectUpdated`/`ObjectRemoved` events; consumers filter by guid on their end. Retail dispatches per-object via `NoticeRegistrar` observer dispatch — each UI cell observes only its specific object guid | `src/AcDream.Core/Items/ClientObjectTable.cs:48` (events); `src/AcDream.App/UI/Layout/ToolbarController.cs:115` (guid filter) | `NoticeRegistrar` is inside keystone.dll with no PDB/decomp; global broadcast + consumer-side filter is functionally equivalent for the current panel count and object volumes seen in practice | At high object counts (>1 000 objects), every `ObjectUpdated` wakes every subscribed consumer — O(n·m) notification cost instead of retail's O(1) per-observer dispatch; a consumer that forgets the guid filter processes all objects (a latent correctness bug) | `NoticeRegistrar` (keystone.dll, no PDB); retail per-object observer registration in `CObjectMaint` |
 ---
 ## 3. Documented approximation (AP) — 42 rows
 | # | Divergence | Where (file:line) | Why it is safe / justified | Risk if assumption breaks | Retail oracle |
 |---|---|---|---|---|---|
 | AP-1 | Snap-path Z settle: validated claims ground on their own walkable polys, but floor-less claims (thresholds, stair lips) fall through to a legacy nearest-in-Z scan over every CellSurface in the landblock; retail settles via `CheckPositionInternal` → `find_valid_position` | `src/AcDream.Core/Physics/PhysicsEngine.cs:614` | `find_valid_position` unported; the **#111** fix narrowed the legacy pick's blast radius (validated claims bypass it) rather than replacing it | A threshold/stair-lip snap can still pick a neighbouring cell's same-height floor by iteration order — wrong cell or Z at login/teleport arrival (the #111 clobber class) | `SetPositionInternal` :283426 → find_valid_position |
 | AP-2 | Visual-AABB fallback collision shape for Setups with no retail physics data; retail emits NO shapes (phantom). **#101** fixed the GfxObj-only class; the Setup-without-shapes fallback remains | `src/AcDream.Core/Physics/PhysicsDataCache.cs:96` | Lets the player collide with decorative meshes shipping no CylSphere/part-BSP instead of walking through furniture-like props | Retail-phantom entities block movement (the **#100/#101** family), and the synthetic box gives non-retail push-out normals when it collides | `CPartArray::InitParts` (cited at PhysicsDataCache.cs:386-389) |
 | AP-3 | Step-down chain triggered only when contact is invalid OR steeper than walkable; retail's `transitional_insert` OK-path ALWAYS runs it | `src/AcDream.Core/Physics/TransitionTypes.cs:1197` | Conditional preserves the observed-to-matter cases (edge departure, steep cliff-slide) without running the chain every step (per pc:273191 agent reports) | Steps where retail runs step-down despite a valid walkable contact (bump maintenance, edge-slide arming) are skipped — float-off or missed edge slides in untested geometry | `transitional_insert` OK-path pc:273191 |
 | AP-4 | CliffSlide check moved BEFORE retail's Branch-1 (`!OnWalkable` → restore+OK) gate, compensating our L.2.3i FloorZ OnWalkable bookkeeping | `src/AcDream.Core/Physics/TransitionTypes.cs:1316` | Retail's order with our incomplete OnWalkable stops the player dead every frame on steep slopes ("stay on the roof"); reorder restores downhill drift | CliffSlide fires in states where retail's Branch 1 would restore-and-OK — body slides where retail holds, e.g. contact-plane-bearing steep geometry near edges | retail EdgeSlide dispatch order (transitional_insert step-down failure) |
 | AP-5 | Step-down skips Placement validation for the contact-maintenance call (`runPlacement=false`); ACE/retail run it unconditionally (kept for DoStepUp) | `src/AcDream.Core/Physics/TransitionTypes.cs:3393` | Residual wall-slide artifacts made Placement misfire, leaving players stuck near walls; the skip was the targeted L.2.3h fix | Step-down can settle into positions Placement would reject — slight wall embedding, or accepting a step-down through overlap geometry retail catches | `CTransition::step_down` pc:272952; ACE Transition.cs:731-741 |
 | AP-6 | Analytic swept-sphere cylinder collision (XY overlap + step-over + wall-slide) instead of retail CylSphere functions via the 6-path dispatcher; A6.P6 step-over branch ports `step_sphere_up`'s clearance check | `src/AcDream.Core/Physics/TransitionTypes.cs:2601` | Claimed to match retail for the exercised cases (trunks, NPC bodies, door foot-colliders); step-over and step_up_slide fallback retro-fitted from retail when the door phantom surfaced | Unported branches (push direction, interpenetration resolution) differ from retail against cylinder entities — the phantom-collision / sticky-NPC family | `CCylSphere::step_sphere_up` pc:324516-324538 |
 | AP-7 | `calc_friction` threshold 0.0 with retail's state gate missing; retail uses 0.25 gated by an undecoded state check | `src/AcDream.Core/Physics/PhysicsBody.cs:307` | Bumping the threshold without the gate hammered normal walking (3 → 0.16 m/s); as-read 0.0 kept; locomotion probably state-exempted in retail. Filed L.3c-followup | Friction engages under different conditions — post-landing slides, knockback decay, sledding speeds mismatch retail's deceleration | pc:276702-276705 (state gate + 0.25) |
 | AP-8 | Remote MoveTo driver is a minimum viable subset: no target re-tracking, no sticky/StickTo, no fail-distance detector, no sphere-cylinder distance variant | `src/AcDream.Core/Physics/RemoteMoveToDriver.cs:44` | All server-side concerns the local body needn't model; ACE re-emits MoveTo ~1 Hz with refreshed origins, substituting for re-tracking | If the re-emit cadence assumption breaks (or sticky-follow packets appear), chase/flee motion visibly diverges — orbiting, overshoot, giving up where retail tracks | `MoveToManager::HandleMoveToPosition` 0x00529d80 |
 | AP-9 | Fixed π/2 rad/s in-motion turn rate; per-creature TurnSpeed unwired | `src/AcDream.Core/Physics/RemoteMoveToDriver.cs:77` | Matches ACE's monster TurnSpeed default; field hook documented for the future port | Creatures with non-default turn speeds rotate at the wrong rate — facing-correction mismatch vs retail observers | run_turn_factor 0x007c8914; `apply_run_to_command` 0x00527be0 |
 | AP-10 | Dry-corner water depth: retail's 0.1 m allowed sink-in collapsed to 0 | `src/AcDream.Core/Physics/TerrainSurface.cs:481` | The 0.1 offset destabilizes the feet-exactly-on-plane contact-touch check (dist > EPSILON → SetContactPlane never fires → float/fall); retail's ~10 cm sink-in is visually indistinguishable | Masks a contact-touch epsilon fragility — other water-depth values exercising the same instability could oscillate shoreline walkable validation; retail's wet/dry corner sink-in visual absent | `ObjCell.get_water_depth` / `calc_water_depth` (via ACE port) |
 | AP-11 | Hand-authored 4-keyframe fallback sky set (sunrise/noon/sunset, fog ~80–350 m) when the Region dat isn't loaded yet | `src/AcDream.Core/World/SkyState.cs:167` | A renderable sky is needed during boot before the Region dat parses; safety net on region-load failure | Any window where the fallback is active shows sky/fog lighting only roughly resembling retail's dat-driven values | SkyTimeOfDay keyframes, Region dat 0x13000000 |
 | AP-12 | Enchantment family-stacking tiebreak by largest SpellId; retail picks highest Generation, tie-broken by latest cast | `src/AcDream.Core/Spells/EnchantmentMath.cs:89` | `ActiveEnchantmentRecord` doesn't carry Generation; SpellId correlates with generation level in practice | Where spell ids don't track power within a family (or same-generation re-cast), the wrong buff wins — vital-max / stat values diverge from retail | `CEnchantmentRegistry::EnchantAttribute` 0x00594570 (pc:416110) |
 | AP-13 | `ComputeDamage` is a simplified retail damage formula (no augmentations/ratings) — verified DEAD CODE as of 2026-06-04, M2 scaffolding | `src/AcDream.Core/Combat/CombatModel.cs:184` | Not on the critical path; stubbed from r02 §5 + ACE CombatManager for the future M2 predictive display | If wired into the M2 attack-bar estimate as-is, predicted numbers diverge whenever augs/ratings apply | r02 §5; ACE CombatManager |
 | AP-14 | Encumbrance multiplier is a rough piecewise-linear stand-in (1.0→50%, ~0.7@100%, 0.1@300%) for retail's exact curve | `src/AcDream.Core/Items/ItemInstance.cs:187` | Hand-fit segments capture the curve's shape for scaffolding | Client-side burden-scaled effects (speed prediction) differ from retail at most burden ratios when loaded | r06 §6 (retail encumbered multiplier curve) |
 | AP-15 | WeenieError translation table covers only ~30 common codes (from ACE enum docs, not retail string_table.bin); unknown codes render raw hex | `src/AcDream.Core/Chat/WeenieErrorMessages.cs:26` | Untranslated codes are rare, fall back losslessly, 30-second add when reported | Server messages outside the table show as raw hex instead of the retail sentence | retail string_table.bin; ACE WeenieError*.cs |
 | AP-16 | Point/spot lights selected per-object / per-cell as the **8 nearest reaching lights** (sphere-overlap, nearest-first) via `LightManager.SelectForObject`, capped at `MaxLightsPerObject=8`; called from `WbDrawDispatcher.ComputeEntityLightSet` (objects) and `EnvCellRenderer.GetCellLightSet` (cell shells). Retail's bake (`SetStaticLightingVertexColors`) sums ALL reaching static lights per vertex with no count cap. Retail's *hardware* path (`minimize_object_lighting` 0x0054d480) DOES cap at 8 per object, so the cap is faithful to retail's hardware path — not to its bake path. The `LightManager.Tick` UBO path survives for DIRECTIONAL (sun) lights only; `mesh_modern.vert`'s UBO loop skips point/spot entries (`posAndKind.w != 0 → continue`) — point lights reach the shader exclusively via the per-object SSBO (binding 5) | `src/AcDream.Core/Lighting/LightManager.cs:234` (`SelectForObject`); `MaxLightsPerObject` ~line 174; call sites `WbDrawDispatcher.ComputeEntityLightSet` + `EnvCellRenderer.GetCellLightSet` | Matches retail's hardware constraint (8 lights per object/cell); selection is nearest-sphere-overlap which faithfully allocates lights to the surfaces that actually see them | Surfaces reached by >8 point lights are dimmer than retail's uncapped bake — rare (a dungeon room has a handful of torches), but real; see AP-35 for the bake-vs-GPU-evaluate architecture difference | `minimize_object_lighting` 0x0054d480 (retail's 8-light hardware cap); `SetStaticLightingVertexColors` 0x0059cfe0 (retail's bake, no count cap) |
 | AP-17 | Spell metadata from third-party CSV (3,956 rows, bad rows silently skipped), not the portal.dat SpellTable; Family feeds stacking decisions | `src/AcDream.Core/Spells/SpellTable.cs:10` | The dat spell-table port (obfuscated/encrypted aspects) wasn't done; CSV closed #11 fast and unblocked #6 stacking | Any CSV↔dat drift (wrong Family, missing rows) silently produces wrong buff-stacking winners and wrong panel info | portal.dat SpellTable 0x0E00000E |
 | AP-18 | Radar/indicator RGBA hand-tuned from screenshots; dispatch order ports `GetBlipColor` exactly but the real `RGBAColor_Radar*` static data is unrecovered | `src/AcDream.Core/Ui/RadarBlipColors.cs:33` | Color constants live in retail static data not yet extracted; comment invites tightening when recovered | Blip/indicator hues differ subtly from retail color cues | `gmRadarUI::GetBlipColor` 0x004d76f0; RGBAColor_Radar* (unrecovered) |
 | AP-19 | `PortalSideEpsilon` 0.01 (≈1 cm) instead of retail F_EPSILON ≈ 0.0002 — a documented render-root-lag tolerance, NOT a retail constant. DO-NOT-RETRY: T2 (BR-4) tried the retail value; CornerFloodReplay refuted it | `src/AcDream.App/Rendering/PortalVisibilityBuilder.cs:49` | Retail's tight epsilon only works with eye-exact swept curr_cell tracking; our viewer cell lags the eye by up to ~1 cm at pressed corners. Tighten after the #108-membership family + cdstW near-clip pin land | A 1 cm misclassification band at portal planes can flood or cull a portal the eye hasn't crossed — one-frame leaks / grey flashes at knife-edge doorway/corner positions | F_EPSILON @0x007c8c70; `PView::InitCell` 0x005a4b70 |
 | AP-20 | Sub-pixel view-polygon vertex merge fixed at 1080p-reference NDC units (2/1080); retail merges at ~1 actual screen pixel | `src/AcDream.App/Rendering/PortalProjection.cs:179` | Unit approximation whose coarseness only strengthens convergence — the merge is the flood's fixpoint floor (replaced MaxReprocessPerCell=16) | At 4K+ a legitimately visible 1–2 px sliver aperture collapses to degenerate and rejects — a thin/distant doorway stops admitting its flood slightly earlier than retail | `Render::copy_view` 0x0054dfc0 |
 | AP-21 | Entity translucency: two-pass alpha-test (N.5 Decision 2, invented 0.95/0.05 thresholds); AlphaBlend + Additive + InvAlpha all composite under (SrcAlpha, 1−SrcAlpha) — retail applies per-surface D3D blend incl. true additive. EnvCellRenderer + ParticleBatcher DO switch to additive; divergence confined to GfxObj/Setup entities via WbDrawDispatcher | `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs:1563` (+ `Shaders/mesh_modern.frag:10`; #52 amendment removed the α≥0.95 discard) | Matches original WB's model; keeps the bindless MDI pipeline at two indirect draws; spec §6 documents the falsifiable fallback — a third indirect call with `glBlendFunc(SrcAlpha, One)` (~30 min) on a magic-content regression | Additive glow/magic entity surfaces composite darker / occlude instead of brightening — the predicted regression once spell VFX density increases; α<0.05 discard drops faint fringes retail blends | SurfaceType.Additive → D3DBLEND_ONE per-surface routing |
 | AP-22 | Invented `setup.Radius` cylinder (height = Height or Radius×2) for shapeless live entities; shape + height formula not from the retail shape walk | `src/AcDream.App/Rendering/GameWindow.cs:3250` | ShadowShapeBuilder (faithful walk) only emits CylSphere/Sphere/Part-BSP; the legacy cylinder preserves prior behavior so rare decorative props don't lose collision | Those props collide with an invented footprint (especially the Radius×2 height guess) — slides/blocks at non-retail distances | `find_obj_collisions` → `CPartArray::FindObjCollisions` pc:286236 |
 | AP-23 | Invented per-type use-radius heuristic (3 m creatures / 2 m doors-lifestones-portals-corpses / 0.6 m rest) for close-range gating + speculative turn-to-target | `src/AcDream.App/Rendering/GameWindow.cs:11120` | ACE broadcasts nothing actionable on the close branch (WithinUseRadius shortcut); the true radius arrives only on the far MoveToObject branch — a local stand-in is required (B.6) | A target whose real UseRadius differs from the bucket misjudges the gate — Use/PickUp deferred for an auto-walk that never comes, or fires early into a server "too far" | ACE Player_Move.cs:66; wire MoveToObject (type 6) carries the true radius |
 | AP-24 | Jump charge fill rate guessed at 2.0 extent/s (full in 0.5 s); retail's divisor illegible (clobbered x87 in `GetPowerBarLevel`). Height→velocity formula is byte-faithful | `src/AcDream.App/Input/PlayerMovementController.cs:170` | Only time-to-fill diverges; 2.0/s matched retail muscle memory better than 1.0/s; targeted Ghidra decompile of 0x0056ADE0 already flagged (M2 research) | Every held-spacebar jump reaches a different extent than the same hold in retail — fence/gap jumps succeed/fail differently until the constant is recovered | FUN_0056ade0 (GetPowerBarLevel) |
 | AP-25 | Run/Jump skill pushed to movement = attributeBonus + Init + Ranks — no augmentations, multipliers, or vitae | `src/AcDream.Core.Net/GameEventWiring.cs:346` | Closest to ACE's CreatureSkill.Current short of porting the full Aug/Multiplier/Vitae chain (K-fix7/13) | A character with augs or post-death vitae predicts wrong local run speed / jump arc — dying would NOT slow the local player though the server moves them slower: drift + snap-back | ACE CreatureSkill.Current; ACE Skill.cs (Jump=22, Run=24) |
 | AP-26 | DDD interrogation answered with an empty dat-version list (count=0); retail reports actual dat iteration state | `src/AcDream.Core.Net/Messages/DddInterrogationResponse.cs:18` | ACE is satisfied by the empty ack; pattern from holtburger | A dat-patching-enabled server could push a full patch or reject on version mismatch — the lie is harmless only while the server never acts on it | DDD flow 0xF7E5/0xF7E6 |
 | AP-27 | PlayerDescription trailer: GameplayOptions skipped by a 4-byte-aligned heuristic scan for a valid inventory parse; options blob captured opaque, never decoded (retail decodes + applies UI options) | `src/AcDream.Core.Net/Messages/PlayerDescriptionParser.cs:69` | Variable-length opaque blobs; mirrors holtburger's heuristics; follow-up issue extends when panels consume those sections | An options blob that coincidentally parses as a valid inventory (or inventory not landing at EOF) yields wrong/empty inventory+equipped at login; retail-persisted UI options silently ignored | ACE GameEventPlayerDescription.WriteEventBody; holtburger events.rs:195-218 |
 | AP-28 | 3D audio falloff via OpenAL InverseDistanceClamped with picked constants (ref 2 m, max 1000 m, rolloff 1); voice pool/eviction IS cited to retail | `src/AcDream.App/Audio/OpenAlAudioEngine.cs:146` | Stands in for retail's DirectSound-era attenuation; r05 §5.3 documents inverse-square behavior but the three AL params were picked, not ported | Sounds attenuate at a different rate — too loud/quiet at range side-by-side; gain-driven eviction comparisons inherit the skew | FUN_00550ad0 (voice pool only); r05 §5.3 |
 | AP-29 | Target-indicator fallback for entities with no baked selection sphere: invented 1.5 m × scale box + 16/12 px screen floors (primary path is a faithful `GetObjectBoundingBox` port) | `src/AcDream.App/UI/TargetIndicatorPanel.cs:86` | Fallback only fires when the Setup didn't bake a selection sphere — rare in practice | Sphere-less entities get a non-retail indicator size/placement; the pixel floors prevent retail's far-distance collapse | `SmartBox::GetObjectBoundingBox` 0x00452e20; `GetSelectionSphere` |
 | AP-30 | AutonomousPosition diff cadence compares with epsilons (1 mm pos, 1e-4 normal, 1 mm dist); retail's `Frame::is_equal` is an exact float compare | `src/AcDream.App/Input/PlayerMovementController.cs:1541` | Sub-millimeter epsilon is well below any movement worth suppressing; comparisons are against last-SENT state so drift accumulates past the epsilon | Sub-epsilon drift suppresses an AP send retail would have made — negligible today; a consumer expecting retail's exact send-on-any-change cadence sees fewer packets | `Frame::is_equal` pc:700263 |
 | AP-31 | Scenery placement drift + the 0xA9B1 road-edge tree — WB-upstream divergences from retail, ACCEPTED (**#49/#50**, 2026-05-11) | `src/AcDream.Core/World/SceneryGenerator.cs` (via `WbSceneryAdapter`) | Piecemeal patching against WB upstream is net-negative (the `e279c46` road-check attempt over-suppressed scenery elsewhere, reverted `677a726`); visible impact = a handful of trees a few meters off | The same WB-upstream class could hide a *larger* placement divergence elsewhere; revisit only via a coherent ACME-style per-vertex filter port | `CLandBlock::get_land_scenes`; ACME GameScene.cs:1074 per-vertex road filter |
 | AP-32 | Cell shells DRAW +0.02 m above the dat EnvCell origin (`ShellDrawLiftZ`, z-fight vs coplanar terrain); retail draws at the origin verbatim. Split invariant: PHYSICS + visibility graph UNLIFTED (f35cb8b, **#119**-residual), every DRAW-space consumer of portal/cell geometry LIFTED (OutsideView color gate via `Build(drawLiftZ)`, seal/punch fans — **#130**) | `src/AcDream.App/Rendering/GameWindow.cs:5604` (const at `PortalVisibilityBuilder.ShellDrawLiftZ`) | Shell floors coplanar with terrain z-fight in our z-buffered frame; the 2 cm lift is the documented stand-in | A new draw-space consumer of portal/cell polygons that forgets the lift re-opens a 2 cm seam at horizontal aperture edges (the #130 top-edge strip, ~7 px at 2.4 m); a visibility consumer that picks up the LIFTED transform re-opens the #119-residual horizontal-portal side-cull | retail draws cell geometry at the dat EnvCell origin (no lift) |
 | AP-33 | Interior-root look-in cells (**#124** sub-pass) draw their statics + DYNAMICS + emitters WHOLE — no per-part/per-object viewcone check; retail viewconeCheck's each vs the installed view (the **#131** portal closure: a server object in a look-in cell drew nowhere — dynamics-last culls cells absent from the main cone, and post-seal it z-fails anyway) | `src/AcDream.App/Rendering/RetailPViewRenderer.cs` (`DrawBuildingLookIns`) | The main viewcone has no entries for look-in cells; over-include is the safe direction (z-correct, repainted outside apertures by the root's shells); look-in cell counts are small (~1-3 cells) | A few wasted draws on content outside the doorway region (repainted); no under-draw direction remains | `viewconeCheck` 0x0054c250; nested `DrawCells` objects pc:432878 |
 | AP-34 | Landscape-stage alpha deferral is a TWO-PHASE slice split (statics-early / dynamics+particles+weather-late around the **#124** look-ins) + outdoor-root attached scene emitters moved to the post-frame pass, not retail's single deferred alpha flush. Residual: building exteriors' / outside-stage dynamics' own translucent MESH batches still draw within their stage draw call (before later stage content) | `src/AcDream.App/Rendering/RetailPViewRenderer.cs` (`DrawLandscapeThroughOutsideView` late loop) + `GameWindow` post-frame Scene pass | The MDI dispatcher draws translucency inside each Draw call; a faithful FlushAlphaList port needs a global deferred alpha list across all landscape draws — the split covers the user-visible cases (#131 portal swirl, #132 candle flame indoors + outdoors) | Translucent landscape content drawn early and screen-overlapped by content drawn later in the stage gets overpainted (no depth self-protection) — the portal-swirl/candle-flame class re-appears in the residual configurations | `D3DPolyRender::FlushAlphaList` (DrawCells pc:432722) |
 | AP-36 | Dungeon streaming gate triggers on the player's CURRENT cell being a sealed EnvCell (`CurrCell.IsEnv && !SeenOutside`), an approximation of ACE's full landblock `IsDungeon` (all-heights-zero + NumCells>0 + Buildings.Count==0). The retail BEHAVIOR (a dungeon loads no adjacent landblocks) is faithful — only the runtime TRIGGER is the cheap cell predicate instead of classifying the center landblock. **#135 pre-collapse:** at login/teleport the same collapse is triggered EARLY (the instant the streaming center is recentered onto the spawn/dest cell) via `IsSealedDungeonCell` reading the EnvCell **dat** `SeenOutside` flag — because the physics `CurrCell` is null until placement, which waits for hydration; without the early trigger the full 25×25 ocean-grid window loads then unloads (the ~30 s login FPS ramp) | `src/AcDream.App/Rendering/GameWindow.cs:6895` (per-frame predicate) + `:IsSealedDungeonCell` + `:OnLiveEntitySpawnedLocked`/`:OnLivePositionUpdated` (login/teleport pre-collapse hooks) + `src/AcDream.App/Streaming/StreamingController.cs` (collapse/expand/`PreCollapseToDungeon`) | The predicate is already computed for sun/sky gating (playerInsideCell) and exactly matches for sealed dungeons vs windowed building interiors (SeenOutside=true → not gated); no landblock re-classification needed. The dat-flag read is the same `EnvCellFlags.SeenOutside` the hydrated `ObjCell.SeenOutside` is built from (`EnvCell.cs:72`/`PhysicsDataCache.cs:224`), so the pre-collapse decision matches the eventual per-frame gate exactly | A dungeon cell that reports SeenOutside (an entrance cell open to the surface) briefly un-collapses and re-streams the window; a hypothetical windowless building back-room (IsEnv && !SeenOutside but HasBuildings) would wrongly collapse its outdoor neighbors; a sealed-dungeon entrance cell that is itself SeenOutside is simply MISSED by the early trigger and falls back to the existing late collapse (no worse than before #135) | ACE `LandblockManager.GetAdjacentIDs` (dungeons→empty) Landblock.cs:577-582; `IsDungeon` Landblock.cs:1264-1277 |
 | AP-43 | Per-object torch (point/spot) lighting is gated on the OBJECT's own cell: an object selects the static wall-torches ONLY when its `ParentCellId` is an EnvCell (`(id & 0xFFFF) >= 0x0100`); outdoor objects (building exterior shells with null ParentCellId, outdoor scenery, outdoor creatures) get the SUN + ambient and NO torches. This is the faithful port of retail's `useSunlight` gate — `DrawMeshInternal` (0x0059f398) calls `minimize_object_lighting` only `if (Render::useSunlight == 0)`, and the outdoor landscape stage runs `useSunlightSet(1)` (`PView::DrawCells` 0x005a485a, before `LScape::draw`) so outdoor objects are never torch-lit (closes the Holtburg meeting-hall facade torch-flood — A7 Fix D round 2, the dat's intensity-100 `falloff 6` orange torches were washing the exterior shell). **Residual approximation:** the sun/no-sun half is a per-FRAME global keyed on the PLAYER being inside a cell (`UpdateSunFromSky` zeroes the sun when `playerInsideCell`), NOT retail's per-draw-STAGE `useSunlight` toggle. So a mixed-stage frame (standing in a doorway / look-in) lights through-aperture objects with the player's regime, not the object's stage regime | `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs` (`IndoorObjectReceivesTorches` + `ComputeEntityLightSet`); sun half `src/AcDream.App/Rendering/GameWindow.cs:10421` (`UpdateSunFromSky`) | The visible case — player OUTSIDE, looking at an outdoor building/scenery — is now exactly faithful (sun+ambient, no torches); player INSIDE a cell gets torches with the sun globally killed = faithful indoor regime. Cross-aperture mismatch only affects objects seen THROUGH a doorway from the other lighting context | A through-aperture interior object viewed from outside gets the sun (player outside) instead of retail's indoor torches-no-sun; an outdoor object viewed from inside gets no sun (player inside) instead of retail's sunlit outside stage — doorway/look-in frames only, not the standalone outdoor or indoor case | `useSunlight` gate `DrawMeshInternal` 0x0059f398; `useSunlightSet` 0x0054d450; outside stage `PView::DrawCells` 0x005a485a (`useSunlightSet(1)`); `minimize_object_lighting` 0x0054d480; `config_hardware_light` Range=falloff×`rangeAdjust`(1.5) 0x0059ad30 |
 | AP-35 | Point/spot lights are now PER-VERTEX Gouraud (`pointContribution` ~line 153 of `mesh_modern.vert`) matching retail's `SetStaticLightingVertexColors` bake path. Half-Lambert wrap (`(1/1.5)·(N·D + 0.5·d)`) AND norm distance attenuation (`distsq>1 ? distsq·d : d`) ARE ported (A7 Fix A, `aa94ced`). Point-light sum clamped to [0,1] on its own accumulator before adding ambient+sun (A7 Fix D D-1, mirrors retail's per-vertex bake clamp). CPU oracle: `src/AcDream.Core/Lighting/LightBake.cs`, locked by `tests/AcDream.Core.Tests/Lighting/LightBakeConformanceTests.cs`. **Residual (two parts):** (a) acdream lights in-shader each frame (per-frame GPU evaluate); retail bakes into the vertex buffer ONCE — an architecture/performance difference; the wrap + norm + clamp formula is the same, but bake-once is cheaper for static geometry; (b) acdream's `SelectForObject` keeps only the 8 NEAREST reaching point/spot lights per object/cell (`MaxLightsPerObject=8`, see AP-16), whereas retail's bake sums ALL reaching static lights per vertex — a surface reached by >8 point lights is dimmer in acdream than retail's bake result (rare in practice; a room has a handful of torches) | `src/AcDream.App/Rendering/Shaders/mesh_modern.vert` (`pointContribution` ~line 153; wrap ~line 163; norm ~line 167; point-sum clamp line 210) | Per-vertex Gouraud + wrap + norm + clamp all match retail. The two residuals are: (a) per-frame GPU vs bake-once — architecture/perf only; (b) 8-light cap dimming when >8 lights reach one surface — rare. `LightInfoLoader.cs:81` folds static_light_factor 1.3 into Range | (a) A new frame-time consumer bypassing `accumulateLights` would need to replicate the wrap + norm formula; per-frame GPU re-evaluate has higher per-frame cost than bake for static geometry. (b) A densely lit scene (>8 torches reaching one wall) renders dimmer than retail — see AP-16 for the 8-cap ownership | `calc_point_light` 0x0059c8b0 (line 0x0059c9a2 ramp; 0x0059c925 wrap); `SetStaticLightingVertexColors` 0x0059cfe0; static_light_factor 0x00820e24 |
 | AP-37 | LayoutDesc importer collapses the dat's nested meter structure (Type-7 meter → two Type-3 container children → three Type-3 image-slice grandchildren each) into `UiMeter`'s programmatic 3-slice fields (`BackLeft..FrontRight`) + reuses `UiMeter.DrawHBar`'s scissor-fill, instead of building those child nodes generically and porting `UIElement_Meter::DrawChildren`. Vitals number elements are meter children (not recursed); `VitalsController` attaches a centered `UiText` child for the cur/max number (Task 8 landed — retail `gmVitalsUI` uses `UIElement_Text`), so `UiMeter.Label` is no longer used for vitals (`UiText.Centered` reuses the meter's former centering formula → pixel-identical, user-confirmed). The inheritance `Merge` treats Width/Height==0 as "inherit from base", diverging from format-doc §12 rule 2 (documented inline in `ElementReader.cs`) | `src/AcDream.App/UI/Layout/DatWidgetFactory.cs` (`BuildMeter`/`SliceIds`) + `src/AcDream.App/UI/Layout/LayoutImporter.cs` (`BuildWidget` meter-child skip) | Reuses the tested `UiMeter` render that already visually matches retail's stacked vitals bars; the full nested-element + `DrawChildren` scissor port is deferred to Plan 2. Locked by the conformance fixture (`tests/AcDream.App.Tests/UI/Layout/fixtures/vitals_2100006C.json`) | A LayoutDesc whose meter structure differs from the vitals 2-container/3-slice shape renders an empty/wrong meter — no oracle diff until the Plan-2 port lands | `UIElement_Meter::DrawChildren` @0x46fbd0; `docs/research/2026-06-15-layoutdesc-format.md` |
 | AP-38 | Chat transcript renders pre-split `ChatLog` lines 1:1; no in-element word-wrap at the panel's current pixel width | `src/AcDream.App/UI/UiText.cs` | Retail does in-element wrap via `UIElement_Text::SizeToFit`; our pre-split lines are always shorter than 440 px in practice; a line that overflows clips at the edge rather than wrapping | Very long server system messages (server shutdowns, broadcast announcements) clip rather than wrapping — no information loss, just visual truncation | `UIElement_Text::SizeToFit` @0x467980; `gmMainChatUI` layout |
 | AP-39 | Chat lines carry one color per `ChatKind` (per-line solid color); retail `UIElement_Text` supports per-glyph styled runs (bold, different hue per segment) | `src/AcDream.App/UI/UiText.cs:13` | Retail glyph-run parsing lives inside keystone.dll with no PDB/decomp; per-line per-kind coloring is the correct tonal palette and covers all existing chat types | Chat lines retail renders with multiple colors or bold names (e.g. "PlayerName says: text") render as one flat color; subtle visual difference but functionally complete | `UIElement_Text` glyph-run styling (keystone.dll, no decomp) |
 | AP-40 | Single default translucency for the chat window chrome; no focused/unfocused opacity transition; dat font face/size taken from the vitals `vitalsDatFont` (same dat font, not a chat-specific size lookup) | `src/AcDream.App/Rendering/GameWindow.cs` (chatController binding line) | Retail fades the chat window to ~80% alpha when unfocused (`gmMainChatUI::UpdateAlpha @0x4cdea0`); the opacity animation deferred to the Plan-2 window-manager input integration; sharing `vitalsDatFont` is safe — retail uses the same AC-default font for both | The chat window is always fully opaque/same-font rather than subtly fading when idle; no wrong text, but the focused/unfocused breathing rhythm is absent | `gmMainChatUI::UpdateAlpha` @0x4cdea0; `UCF::SetAceFont @0x4d3940` |
 | AP-41 | Scrollbar thumb 3-slice cap fallback only: single-tile draw (`0x06004C63`) used only when `ThumbTopSprite`/`ThumbBotSprite` are unset; the chat controller passes all three cap ids so the 3-slice path is drawn in practice | `src/AcDream.App/UI/UiScrollbar.cs:35` | The fallback single-tile path is unreachable when caps are bound (chat controller always sets them); the 3-slice path is the active code path | Only if a future caller omits the cap ids will the fallback fire — no visual regression in the chat window | `UIElement_Scrollbar::UpdateLayout @0x4710d0`; cap sprites `0x06004C60` (top) + `0x06004C66` (bottom) from base layout `0x2100003E` |
 | AP-42 | `UiMenu` item model is flat (label + opaque payload, single-level popup); retail `UIElement_Menu::MakePopup @0x46d310` supports hierarchical nested submenus via recursive popup chain | `src/AcDream.App/UI/UiMenu.cs` | The chat talk-focus menu is single-level (14 rows, 2 columns, no submenu); hierarchy is latent and unreachable through the chat window — no behavioral difference in the current usage | A future menu with nested submenus would render flat (only the top-level items drawn, no drill-down) | `UIElement_Menu::MakePopup` @0x46d310 |
 | AP-45 | `PublicUpdatePropertyInt (0x02CE)` sequence byte parsed-past but not honored; last update wins (no freshness check against sequence number) | `src/AcDream.Core.Net/Messages/PublicUpdatePropertyInt.cs` | Loopback ACE rarely reorders; latest-wins matches `PrivateUpdateVital`/`UpdatePosition`'s existing non-sequence behavior. Sequence tracking added when needed alongside TS-26. | A reordered 0x02CE on a real network could apply a stale UiEffects value — item icon temporarily shows the wrong effect state, corrected on next update | `PublicUpdatePropertyInt` sequence byte (ACE GameMessagePublicUpdatePropertyInt) |
 | AP-46 | Health-meter gate approximation: retail shows the health meter for `IsPlayer() || pet_owner || ClientCombatSystem::ObjectIsAttackable()` (full PK/faction logic); acdream's `GameWindow.IsHealthBarTarget` uses the server PWD bits `BF_ATTACKABLE (0x10)` OR `BF_PLAYER (0x8)` | `src/AcDream.App/Rendering/GameWindow.cs` (`IsHealthBarTarget`) → `SelectedObjectController` | The PWD `BF_ATTACKABLE`/`BF_PLAYER` bits distinguish monsters + players (bar) from friendly/vendor NPCs (name-only) for the M1.5 dev loop; the pet case and the full ObjectIsAttackable PK/faction refinement (free-PK, PK-vs-PK, PKLite) are not ported | A PK/faction edge (e.g. a hostile-flagged player whose `BF_ATTACKABLE` is unset, or a pet) could show/hide the bar where retail differs — no impact on the non-PK PvE dev loop | `ClientCombatSystem::ObjectIsAttackable` acclient_2013_pseudo_c.txt:375385; `BF_ATTACKABLE` acclient.h:6437 |
 ---
 ## 4. Temporary stopgap (TS) — 31 rows
 | # | Divergence | Where (file:line) | Why it is safe / justified | Risk if assumption breaks | Retail oracle |
 |---|---|---|---|---|---|
 | TS-1 | PrecipiceSlide context missing — conservative stop-at-edge instead of retail's EdgeSlide → PrecipiceSlide / CliffSlide | `src/AcDream.Core/Physics/TransitionTypes.cs:1254` | Awaiting the next L.2c slice; a diagnostic records which ingredient (precipice context / steep plane / EdgeSlide flag) is missing | Player stops dead at precipice edges where retail slides along/over — visible mismatch at cliff and roof edges | retail EdgeSlide → PrecipiceSlide chain |
 | TS-2 | `BspOnlyDispatch` reduces retail's `(HAS_PHYSICS_BSP_PS && !pvpTargetPlayer && !missileIgnore)` to the flag test alone (M1.5 scope: no PK, no missiles) | `src/AcDream.Core/Physics/TransitionTypes.cs:660` | Both omitted terms are genuinely false pre-M2; comment directs wiring them with PK (M2+) and missiles (F.3) | If PK or missiles land without the terms, flagged entities get BSP-only where retail tests cyl+sphere — pass-through / wrong blocking in PvP/missile interactions | `FindObjCollisions` pc:276861; HAS_PHYSICS_BSP_PS acclient.h:2833 |
 | TS-3 | `FramesStationaryFall` accounting absent (`moved = true` unconditionally in the accepted-move branch) | `src/AcDream.Core/Physics/TransitionTypes.cs:3691` | Explicitly deferred to the full physics port | A body wedged falling-in-place never triggers retail's stuck-fall escalation — indefinite falling-animation wedges | CPhysicsObj frames_stationary_fall |
 | TS-4 | Path-6 steep-poly slide-tangent shortcut: airborne hits on >FloorZ polys skip retail's SetCollide → Path-4 → ContactPlane landing chain, returning Slid in place | `src/AcDream.Core/Physics/BSPQuery.cs:2001` | Deliberate deviation: our faithful port DID wedge (missing step_up_slide / cliff_slide details on grounded-steep); validated against the 2026-04-30 retail cdb trace (retail body didn't wedge). Filed L.5+ for retail-strict | Airborne steep contact never commits Contact / lands as retail — roof-bounce trajectories, landing events, grounded-steep transitions diverge | `BSPTREE::find_collisions` SetCollide pc:323783-323821 |
 | TS-5 | `CanJump` always true — burden/stamina gating deferred (stat plumbing incomplete pre-M2) | `src/AcDream.Core/Physics/PlayerWeenie.cs:44` | Marked deferred; harmless until stats matter | Client launches jumps retail refuses (exhausted/overburdened) — server rejection / rubber-band; divergent jump availability vs retail muscle memory | CMotionInterp jump path stamina/burden inquiry |
 | TS-6 | Weather particle emission suppressed — all weathery DayGroups map to Overcast (correct fog/cloud tone, no precipitation); retail's camera-attached weather subsystem not yet located in the decomp | `src/AcDream.Core/World/WeatherState.cs:200` | Decomp research verified the sky loop never reads `DefaultPesObjectId`; an earlier name-based rain spawn regressed (rained where retail didn't, 2026-04-23) — inventing a name→rain path is forbidden until the real subsystem is found | Rainy/snowy/stormy days never show retail's precipitation effects (permanent missing visuals until the subsystem is found and ported) | FUN_00508010 / FUN_0051bed0→FUN_0051bfb0 (negative findings) |
 | TS-7 | SkyObject `weather_enabled` gate not honored — weather-flagged sky objects (bit 0x04) always instantiate | `src/AcDream.Core/World/SkyDescLoader.cs:50` | No weather_enabled toggle exists yet; IsWeather flag parsed + documented as the gate to wire | Weather-only sky meshes (rain cylinders) appear where retail-with-weather-off suppresses them | `GameSky::MakeObject` 0x00506ee0, guard at decomp:268630 |
 | TS-8 | `MagicUpdateEnchantment` (0x02C2) records carry no StatMod — mid-session buffs don't move vital max until relog (**#7/#12**) | `src/AcDream.Core/Spells/Spellbook.cs:150` | The wire parser hasn't been extended to the full ~60-64 byte Enchantment payload; PlayerDescription's block IS parsed | Vitals HUD percent reads differently from retail for the whole session after any buff cast | `EnchantAttribute` 0x00594570; holtburger magic/types.rs |
 | TS-9 | MP3 (0x55) and MS-ADPCM (0x02) waves undecoded — affected sounds skipped; retail decoded both via winmm ACM | `src/AcDream.Core/Audio/WaveDecoder.cs:33` | Managed decoder (NAudio or similar) deferred; PCM covers the vast majority of ~3500 waves | Any MP3 (common for music-ish clips) or ADPCM cue plays as silence where retail plays it | winmm ACM path (r05 §2.1) |
 | TS-10 | Setup lights anchored at entity root — per-light Frames not transformed through the animated part chain | `src/AcDream.Core/Lighting/LightInfoLoader.cs:31` | Per-part world transforms aren't exposed to the lighting layer; awaiting animation hook integration | A carried torch glows from the character origin, not the hand, and doesn't track swing/idle animations | LightInfo.ViewSpaceLocation per-part Frame (r13 §1) |
 | TS-11 | `CreateBlockingParticleHook` consumed as a no-op; no sequencer implements the pause retail performs (consistent with the missing pending_motions chain, 2026-06-04 deep-dive) | `src/AcDream.Core/Vfx/ParticleHookSink.cs:112` | Responsibility assigned to the (future) sequencer layer when the sink was written | Animations retail pauses on a particle (cast/effect beats) run straight through — visual beat desynced from the effect | retail sequencer blocking-particle handling (r04 §6) |
 | TS-12 | Animated entities' emitters use rest-pose part transforms anchored at entity root; retail attaches to the live animated part (per-tick refresh deferred; statics fixed by C.1.5b/#56) | `src/AcDream.Core/Vfx/ParticleHookSink.cs:80` (+ :20) | The renderer doesn't expose per-part world transforms to VFX; root + precomputed matrices reproduce retail placement for everything that doesn't animate | Effects hooked to animated parts (swinging hand, nodding head) emit from the rest pose / float at spawn offsets instead of tracking motion | `ParticleEmitter::UpdateParticles` 0x0051d2d4 |
 | TS-13 | `DefaultScriptHook` / `DefaultScriptPartHook` / `CallPESHook` animation hooks dropped (no OnHook case); blocker comment predates PhysicsScriptRunner (C.1.5a) and may be STALE | `src/AcDream.Core/Vfx/ParticleHookSink.cs:130` | Originally blocked on PhysicsScript dat exposure; spawn-time DefaultScript firing landed via EntityScriptActivator, the animation-frame path never did | VFX retail triggers from specific animation frames (mid-animation script calls) never appear | CallPES / DefaultScript hook dispatch (r04 §6) |
 | TS-14 | Setup `Flatten` ignores ParentIndex part hierarchy (treats every placement as root-local); still in production use (GameWindow hydration, SkyRenderer) | `src/AcDream.Core/Meshing/SetupMesh.cs:15` | Most Setups are flat single-level rigs where root-local equals composed; hierarchical composition deferred ("Phase 3") | Any Setup with genuinely nested parts renders them at wrong offsets — mis-assembled multi-part objects in the Flatten paths | retail Setup ParentIndex chain composition |
 | TS-15 | No distance-driven degrade (LOD): always close-detail slot 0; plus the **#47** static `Degrades[0]` swap for 34-part humanoids only (structural sentinel detector) | `src/AcDream.Core/Meshing/GfxObjDegradeResolver.cs:57` (+ `src/AcDream.App/Rendering/GameWindow.cs:2608`) | LOD plumbing doesn't exist; slot 0 is correct for player + nearby NPCs; #47 closed the visible low-detail-arms bug without porting UpdateViewerDistance | Distant objects render max-detail (perf + wrong visuals where far meshes intentionally differ/hide parts); a future 34-part non-humanoid matching the sentinel gets the wrong mesh swap | `CPhysicsPart::UpdateViewerDistance` 0x0050E030; ::Draw 0x0050D7A0; ::LoadGfxObjArray 0x0050DCF0 |
 | TS-16 | Click picking is Stage A only: ray-vs-fixed-radius spheres (0.7–1.0 m) + screen rect matched to the indicator; retail's per-polygon refine deferred (**#71**); rect-over-circle is a user-approved UX divergence | `src/AcDream.Core/Selection/WorldPicker.cs:199` | Stage B only needed if visual testing surfaces Stage-A over-picks; sphere/rect + cell-BSP occlusion adequate so far | Clicks near (not on) an entity still select it; fixed radii can mis-prioritize overlapping candidates vs retail's polygon-accurate test | `CPolygon::polygon_hits_ray` 0x0054c889 |
 | TS-17 | AttackConditions suffix always empty in combat chat — formatting ported, wire bitflag not plumbed (Phase I.7 follow-up) | `src/AcDream.Core/Chat/CombatChatTranslator.cs:233` | Only the wire plumbing is missing; the holtburger-ported formatter is ready | Combat log omits "[Sneak Attack]"-style suffixes retail displays — hidden combat-mechanic feedback | holtburger chat.rs:588-595 |
 | TS-18 | `LandCell.BuildingCellId` (CSortCell building bridge) declared but never populated — always null in Stage 1 | `src/AcDream.Core/World/Cells/LandCell.cs:19` | Cell graph shipped in stages; population is explicitly membership Stage 2 (the outdoor→indoor entry path the physics digest flags as unvalidated) | Cell-graph paths that should discover a building's EnvCells from the outdoor cell silently find nothing — the doorway-entry bug class | CSortCell (acclient.h:31880) |
 | TS-19 | Legacy non-retail ChaseCamera (invented pitch/distance, K-fix12 airborne Z-pin) retained behind `ACDREAM_RETAIL_CHASE=0` / DebugPanel toggle; both update every frame | `src/AcDream.App/Rendering/ChaseCamera.cs:49` | Diagnostic before/after comparison path, "pending the follow-up deletion commit" | When toggled on, the eye diverges from retail's spring-arm — and the render roots at the VIEWER cell, so a non-retail eye changes the render root near doorways, masking or manufacturing flap symptoms during debugging | `CameraManager::UpdateCamera` (retail path in RetailChaseCamera.cs) |
 | TS-20 | GfxObj polys drawn by dictionary iteration, not DrawingBSP traversal (**#113**): physics/no-draw polys referenced by no BSP node render as visible surfaces; the `CollectDrawingBspPolygonIds` filter exists (:1004) but is NOT applied (naive walk made doors disappear, `e46d3d9` un-applied, user-gated 2026-06-11) | `src/AcDream.App/Rendering/Wb/ObjectMeshManager.cs:1027` | Correct fix is full BSP-traversal-order drawing per the holistic port handoff (docs/research/2026-06-11-building-render-holistic-port-handoff.md); the id filter must first be diagnosed on a door GfxObj (Issue113PhantomStairsDumpTests) | Phantom geometry visible NOW (Holtburg meeting-hall "staircase" wall ramp 0x010014C3; 8 orphan polys on hill cottage 0x01000827); draw order also diverges from retail's BSP order | D3DPolyRender drawing-BSP traversal; ConstructMesh 0x0059dfa0 |
 | TS-21 | Default run/jump skills 200/300 tuned to feel until the first PlayerDescription lands; "we don't parse yet" comment is STALE (K-fix7 parses PD → SetCharacterSkills) | `src/AcDream.App/Input/PlayerMovementController.cs:341` | Defaults rule only pre-PD or on PD parse failure; jump bumped 200→300 on user complaint (3.01 m max felt too low) | Any window with defaults live predicts run/jump speeds the server disagrees with — observer rubber-banding, local snap-backs | retail height = (skill/(skill+1300))×22.2 + 0.05 |
 | TS-22 | `adjust_motion` not ported — backward (×−0.65) / strafe (×−1) translation hand-mirrored at controller call sites; `get_state_velocity` returns (0,0,0) for backward/strafe-left | `src/AcDream.App/Input/PlayerMovementController.cs:1021` | Duplication exists because LeaveGround through the unported path wiped strafe/backward jump velocity (straight-up backward jumps) | Any NEW `get_state_velocity` consumer during backward/strafe motion silently gets zero velocity (the exact prior bug class); hand-mirrored formulas can drift from the grounded block they copy | FUN_00528010 (adjust_motion); FUN_00528960 |
 | TS-23 | PK/PKLite/Impenetrable mover bits never set (PlayerKillerStatus not parsed from PD); moverFlags always `IsPlayer ∣ EdgeSlide` | `src/AcDream.App/Input/PlayerMovementController.cs:1128` | Non-PK pair walks through other non-PK players — retail's default for ACE's character-creation defaults too | On a PK/PKLite character, local client lets players walk through where retail collides — prediction vs server disagree the moment PvP statuses enter play | PWD._bitfield acclient.h:6431-6463; pc:406898-406918 |
 | TS-24 | RawMotionState command list always empty (bits 11-31 = 0) — discrete motion events (emotes, one-shots) never packed outbound | `src/AcDream.Core.Net/Messages/MoveToState.cs:34` | Discrete client-initiated motions aren't implemented yet; documented builder scope | When player-triggered emotes land, they silently never broadcast — observers see idle while the local client animates | RawMotionState pack (holtburger types.rs) |
 | TS-25 | `FlagCurrentStyle` (stance, bit 0x2) never written to outbound MoveToState | `src/AcDream.Core.Net/Messages/MoveToState.cs:130` | Stance switching is M2 combat scope | Once combat-mode switching ships, mid-stance MoveToStates omit the style — server/observers keep the stale stance, wrong cycle family for every subsequent movement | RawMotionFlags CurrentStyle 0x2 (holtburger) |
 | TS-26 | UpdatePosition's four u16 sequence numbers parsed but never checked for freshness; retail rejects stale/out-of-order packets | `src/AcDream.Core.Net/Messages/UpdatePosition.cs:30` | Loopback ACE rarely reorders, so the gap is invisible in the dev loop | On a real network, a reordered/post-teleport straggler applies as-is — remotes snap backward / flicker; a teleport-vs-position race renders an entity in the wrong cell | PositionPack trailer (ACE PositionPack.cs::Write) |
 | TS-27 | Retransmit handling absent: `RetransmitRequests`/`RejectRetransmit` parsed, but nothing re-sends lost outbound or requests missing inbound sequences (class-doc gap list otherwise stale — ack/position/chat exist) | `src/AcDream.Core.Net/WorldSession.cs:29` | Deferred since the one-shot test harness; dev loop is loopback (no loss) | On any lossy link a dropped fragment is gone forever — entities never spawn, chat vanishes, reassembly stalls; server retransmit requests ignored until session timeout. Stale doc list also misleads readers | PacketHeaderFlags RequestRetransmit 0x1000 / Retransmission 0x1 |
 | TS-28 | LoginComplete sent on PlayerCreate (0xF746) arrival; retail sends it after the portal-space transition animation finishes (no such animation exists yet) | `src/AcDream.Core.Net/Messages/GameActionLoginComplete.cs:30` | acdream has no portal-space animation; "InWorld" phrasing in the file is slightly stale (trigger is PlayerCreate) | Server flips the character out of the loading state and pushes initial updates while the client may still be streaming — server logic assuming retail's load-screen duration fires against a half-initialized client | retail post-EnterWorld flow (holtburger messages.rs:391-422) |
 | TS-29 | Background music (MIDI) + ambient loops not ported: PlayMusic/StopMusic no-op; StartAmbient reserves a handle that never plays | `src/AcDream.App/Audio/OpenAlAudioEngine.cs:331` | Explicitly outside R5 audio-phase scope; a landblock-attached ambient system is planned separately | Silent world where retail has music/atmosphere; code trusting StartAmbient's handle to mean "playing" is already subtly wrong (StopAmbient looks up a never-created source) | retail MIDI + ambient system (r05) |
 | TS-30 | Numbered chat tabs (element ids `0x10000522`–`0x10000525`) render as clickable buttons but do not switch channel filter or affect the transcript — tab state is a no-op | `src/AcDream.App/UI/Layout/ChatWindowController.cs:210` | Retail's tab switching routes transcript lines by chat channel (`gmMainChatUI::gmScrollWindow` sub-windows per tab); the tab wiring is D.5 scope | Tab clicks produce no visible transcript change; retail would filter to the selected channel — all chat always shows in all tabs | `gmMainChatUI::PostInit` tab setup @0x4ce2a0; holtburger chat tab handling |
 | TS-31 | Squelch toggle absent (no `/squelch` slash command, no clickable name-tags to silence); retail's squelch list filters incoming chat lines | `src/AcDream.Core/Chat/ChatLog.cs` | Squelch is a social / moderation feature deferred to post-M1.5; the data structure (`ChatLog`) has no squelch set today | Any player can spam all clients; clickable-name-tag contextual menu (used in retail to squelch, tell, add-to-friends) is absent | `ChatFilter::IsSquelched`; retail right-click player name → Squelch menu |
 | TS-32 | `ClientObjectTable` has no pre-queue for a child `CreateObject` that arrives before its parent (out-of-order PARENTED create); such objects are ingested as root objects and their `ContainerId` links a not-yet-known container. Retail's `null_object_table` + `null_weenie_object_table` hold unresolvable objects until the parent arrives | `src/AcDream.Core/Items/ClientObjectTable.cs` (`Ingest`) | PD↔`CreateObject` ordering is handled (upsert semantics); out-of-order PARENTED creates are observed only at high packet loss or in vendor/corpse multi-object bursts on non-loopback links; deferred to D.5.5+ | A container's child object arriving before the container is ingested as a root item — it won't appear in `GetContents` until the next `RecordMembership` or a move event corrects the parent link | `CObjectMaint::null_object_table` / `null_weenie_object_table` (acclient.h / named-retail pc) |
 ---
 ## 5. Unclear (UN) — 5 rows
 These rows have a missing, contradictory, or never-argued justification.
 They are the highest-priority audits: each needs either a recorded
 equivalence argument (promote to AD/AP) or a fix.
 | # | Divergence | Where (file:line) | Recorded justification (deficient) | Risk if assumption breaks | Retail oracle |
 |---|---|---|---|---|---|
 | UN-1 | `CheckOtherCells` iterates the overlap set SORTED by cell id; retail walks the CELLARRAY in build order — and the loop halts on the first non-OK result, so order is behavior-bearing | `src/AcDream.Core/Physics/CellTransit.cs:1718` | Justified only as "deterministic order for greppable probe logs" — no equivalence argument vs retail's array order recorded | A sphere straddling two cells that would each return a different non-OK result halts on a different cell than retail — different collision normal / slide direction at multi-cell straddles | `CTransition::check_other_cells` pc:272717-272798 |
 | UN-3 | AdminEnvirons fog-override RGB tints hardcoded with no retail constant cited (RedFog 0.60/0.05/0.05 etc.); Snapshot replaces fog COLOR only, keeping keyframe distances on an unverified assumption | `src/AcDream.Core/World/WeatherState.cs:350` | Enum semantics cite ACE EnvironChangeType + r12 §5.2; no source for the RGB values or the color-only override scope | A server-forced fog event renders the wrong hue and/or wrong density vs what retail clients showed for the same packet | AdminEnvirons 0xEA60; ACE EnvironChangeType.cs |
 | UN-4 | GfxObj double-sided/negative-surface handling keeps WB's legacy logic (cull-mode double-siding, no reversed-winding duplicate, different neg-surface predicate) while the CellStruct path follows the retail-cited `ConstructMesh` reading | `src/AcDream.App/Rendering/Wb/ObjectMeshManager.cs:1059` (CellStruct contrast :1396-1410) | No recorded justification on the GfxObj side — it is the unmodified WB extraction; the retail citation was added only to the CellStruct path | GfxObj models retail draws via duplicated-reversed-winding get wrong back-face lighting (normals not inverted) or missing/extra negative faces — dark or absent faces from behind | `D3DPolyRender::ConstructMesh` 0x0059dfa0 |
 | UN-5 | Run multiplier applied to backward (and strafe) speed while the wire reports speed 1.0; the 0.65 backward factor IS retail's, the runMul on top is justified only by feel ("~2.4× ratio felt wrong"); strafe cites holtburger, backward cites nothing | `src/AcDream.App/Input/PlayerMovementController.cs:909` | Feel fix (K-fix3); no retail citation for run-scaling backward movement | If retail does NOT run-scale backward, the local body moves up to ~2.4× faster backward than the wire declares — observers dead-reckon slower and see lag/teleport when backing up at run | adjust_motion FUN_00528010 (0.65 only); holtburger common.rs (sidestep) |
 | UN-6 | Fixed 200 ms sleep between ConnectRequest and ConnectResponse; retail inserts no delay. Annotated only as "with 200ms race delay"; the 2026-06-04 audit flagged it, the follow-up refuted "forbidden workaround" but wrote no fuller rationale back | `src/AcDream.Core.Net/WorldSession.cs:484` | Presumed ACE port+1 listener race guard — four words, no citation | Every login eats a flat 200 ms; if the race needs longer on a loaded server, the handshake fails intermittently (ConnectResponse ignored → CharacterList never arrives, exit-29 shape) with no retry — a timing constant masking an unconfirmed root cause | (none recorded) |
 | UN-7 | Outdoor OBJECT point lighting uses `calc_point_light` (wrap/norm + per-channel cap, `~1/d²`) for ALL meshes including static buildings, but retail's object path is unconfirmed — `config_hardware_light` (0x0059ad30) sets D3D-FF point lights (`Diffuse=color×intensity`, `Attenuation=(0,1,0)`⇒`1/d`, `Range=falloff×1.5`, `material.diffuse=white`) yet that math would blow walls WHITE while retail stays DIM, so static buildings may instead use the `SetStaticLightingVertexColors` bake. Model + the brightness-scaling factor both UNRESOLVED (issue #140 / Fix D) | `src/AcDream.App/Rendering/Shaders/mesh_modern.vert` (`pointContribution`); `src/AcDream.Core/Lighting/LightManager.cs` (`SelectForObject`) | Fix A/B ported calc_point_light + per-object selection for objects without confirming retail uses that model for static buildings; cdb captured the D3D-FF path but it contradicts the observed dim result | Outdoor buildings blow out warm near torches (the #140 meeting-hall symptom); whichever model is wrong, the object torch contribution is too strong | `config_hardware_light` 0x0059ad30; `SetStaticLightingVertexColors` 0x0059cfe0; `rangeAdjust=1.5` 0x00820cc4 — see docs/research/2026-06-18-lighting-a7-fixABC-shipped-fixD-handoff.md |
 ---
 ## 6. Retire-next shortlist
 Temporary-stopgap + unclear rows, ordered by risk (symptom severity ×
 likelihood the guarding assumption breaks). Items below the line are
 phase-gated — they carry their trigger in their row and should land
 WITH that phase, not before.
 1. **TS-20 — GfxObj DrawingBSP traversal (#113)** — phantom geometry is visible in Holtburg RIGHT NOW; the holistic port handoff already specs the fix; first diagnose the id filter against a door GfxObj.
 2. **TS-27 — Retransmit handling** — sole hard blocker for any non-loopback play; failure mode is silent permanent stalls (entities never spawn). Also fix the stale class-doc gap list while there.
 3. **TS-4 — Path-6 steep slide-tangent shortcut** — landing/contact state diverges on every airborne-steep hit; the L.5+ retail-strict followup is already filed with the missing-ingredient analysis.
 4. **UN-5 — Backward/strafe run multiplier** — potential ~2.4× local-vs-wire speed mismatch on a common input (S at run); one cdb session against retail answers it.
 5. **UN-1 — CheckOtherCells iteration order** — behavior-bearing halt order with a log-cosmetics justification; trivial to fix (iterate CELLARRAY build order, sort only in probe output).
 6. **TS-1 — PrecipiceSlide stop-at-edge** — visible movement mismatch at every cliff/roof edge; diagnostic already records which ingredient is missing.
 7. **TS-22 — adjust_motion port** — active bug-class generator: any new `get_state_velocity` consumer during backward/strafe silently gets zero velocity.
 8. **TS-26 — Position sequence freshness** — real-network correctness; pairs naturally with TS-27 in one transport-hardening pass.
 9. **UN-6 — 200 ms ConnectResponse sleep** — unexplained constant on every login with an intermittent-failure shape; either find the ACE race and cite it, or replace with an acknowledged-ready check.
 10. **UN-4 — GfxObj sides/negative-surface logic** — diagnose against the retail-cited CellStruct interpretation on a known double-sided GfxObj; promote to AP with a citation or align it.
 11. **TS-8 — MagicUpdateEnchantment StatMod parse (#7/#12)** — vitals wrong for the whole session after any buff; parser shape is known from holtburger.
 12. **TS-13 — CallPES/DefaultScript animation hooks** — the blocker comment is stale since C.1.5a shipped PhysicsScriptRunner; possibly a cheap wire-up now.
 13. **UN-3 — AdminEnvirons tints** — invented RGB constants + unverified color-only scope; one decomp lookup against the 0xEA60 handler.
 14. **TS-19 — Legacy ChaseCamera deletion** — already marked "pending the follow-up deletion commit"; its continued existence can mask or manufacture flap symptoms during debugging.
 **Phase-gated (do WITH the phase, flagged here so they aren't forgotten):**
 M2 combat must land TS-2 (BspOnlyDispatch terms), TS-5 (CanJump gating),
 TS-23 (PK bits), TS-25 (stance in MoveToState), TS-17 (AttackConditions),
 and revisit AP-13 (ComputeDamage) + AP-24 (jump-charge constant via the
 0x0056ADE0 decompile). Emote work must land TS-24 (command-list packing).
 Membership Stage 2 must land TS-18 (BuildingCellId).
 The audio phase lands TS-9/TS-29; the animation-hook layer lands
 TS-10/TS-11/TS-12/TS-13/TS-14.
 ---
 *Maintenance: this register is part of the definition of done for any
 phase that adds or removes a divergence. Sources merged 2026-06-12:
 5-area code sweep, `docs/architecture/worldbuilder-inventory.md`,
 `docs/ISSUES.md` accepted-divergence entries (#96, #49, #50).*
--- a/docs/architecture/worldbuilder-inventory.md
+++ b/docs/architecture/worldbuilder-inventory.md
@ -1,281 +0,0 @@
 # WorldBuilder Inventory — what we extracted, adapted, or left behind
 > **Phase O shipped 2026-05-21.** The ~33 WB files we actually use have
 > been extracted into our tree. `references/WorldBuilder/` stays as a
 > **read-reference only** — nothing in `src/AcDream.*` references it as a
 > project dependency. `DatCollection` is now the only dat reader in process.
 >
 > Use this document to:
 > 1. Know **where our extracted code lives** (look for the "Extracted to"
 >    column / notes in each section below).
 > 2. Know **what WB still has** that we haven't needed yet — grep
 >    `references/WorldBuilder/` if you ever need to add something.
 > 3. Know **what WB never had** (the 🔴 list) — those are always ours.
 **Pre-O status (archived for context):** As of Phase N.4 (2026-05-08)
 acdream relied heavily on WorldBuilder as a project reference for rendering
 and dat-handling. WorldBuilder is MIT-licensed, verified by visual inspection
 to render the AC world correctly (terrain, scenery, slabs, dungeons, slopes,
 particles), and uses the same Silk.NET + .NET stack we target.
 **Post-O integration model:** Extracted WB code lives in two locations in
 our tree (see CLAUDE.md for the full breakdown):
 - `src/AcDream.Core/Rendering/Wb/` — pure helpers (no GL): `TerrainUtils`,
  `TerrainEntry`, `RegionInfo`, `SceneryHelpers`, `TextureHelpers`.
 - `src/AcDream.App/Rendering/Wb/` — GL infrastructure + mesh pipeline:
  `ObjectMeshManager`, `WbMeshAdapter`, `WbDrawDispatcher`, texture cache,
  shader infra, EnvCell/portal/scenery/terrain-blending pipeline classes.
 `DatCollectionAdapter` bridges our `IDatCollection` to the `IDatReaderWriter`
 interface WB's internals expect (O-D7 fallback; `ObjectMeshManager` has 26
 internal `_dats.*` call sites — above the 20-site inline-swap threshold).
 **Workflow:** Before re-implementing any AC-specific rendering or dat-handling
 algorithm, **check this inventory first**. If we already extracted it (🟢
 sections), it's in `src/AcDream.App/Rendering/Wb/` — use our copy. If WB has
 it but we haven't extracted it yet, grep `references/WorldBuilder/` and extract
 as needed. Retail decomp remains the oracle for things WB never had (🔴 list).
 Attribution: WorldBuilder is MIT-licensed. `NOTICE.md` includes WB attribution.
 ---
 ## Read-reference layout (under `references/WorldBuilder/`, not project-referenced)
 - **`Chorizite.OpenGLSDLBackend/`** — full OpenGL renderer (Silk.NET). The
  components we use are extracted into `src/AcDream.App/Rendering/Wb/`.
 - **`WorldBuilder.Shared/`** — data models, dat parsers, landscape module.
  The helpers we use are extracted into `src/AcDream.Core/Rendering/Wb/`.
 - **`WorldBuilder/`** — Avalonia desktop app shell (not taken).
 - **`WorldBuilder.{Windows,Linux,Mac}/`** — platform entry points (not taken).
 - **`WorldBuilder.Server/`** — collab editing backend (not taken).
 - **`Tests/` + `WorldBuilder.Shared.Benchmarks/`** — test harness (study only).
 **Upstream NuGet dependencies** (these stay as NuGet packages, we don't
 vendor them):
 | Package | Version | Purpose |
 |---|---|---|
 | `Chorizite.Core` | 0.0.18 | Plugin framework — contains `Chorizite.Core.Lib.BoundingBox`, `Chorizite.Core.Render.*` interfaces used by every render manager |
 | `Chorizite.DatReaderWriter` | 2.1.x | dat parsing (we already use 2.1.7) |
 | `Chorizite.DatReaderWriter.Extensions` | 1.1.x | extra dat helpers |
 | `BCnEncoder.Net` | 2.2.x | DXT decode (we already use) |
 | `SixLabors.ImageSharp` | 3.1.x | image loading |
 | `Silk.NET.OpenGL` + `Silk.NET.SDL` | 2.23.x | GL + windowing (we use Silk's own windowing, they use SDL) |
 | `MP3Sharp` | 1.0.5 | MP3 decode |
 ---
 ## 🟢 RENDERING — take wholesale or adapt
 These are what makes WB "perfect". Anything in this section, we should
 use from WB rather than re-implement.
 ### Terrain
 | Component | What it does |
 |---|---|
 | `TerrainRenderManager` | Full pipeline (per-chunk GPU buffers, draw orchestration) |
 | `LandSurfaceManager` | Texture blending atlas (palCode, alpha masks, road overlays) |
 | `TerrainGeometryGenerator` | Heightmap → mesh, normals, OnRoad, GetHeight, GetNormal |
 | `TerrainChunk` | 16×16 landblock chunk geometry |
 | `TextureAtlasManager` | Texture atlas builder |
 | `VertexLandscape` | Terrain vertex format |
 ### Scenery (procedural placement: trees, bushes, rocks, fences)
 | Component | What it does |
 |---|---|
 | `SceneryRenderManager` | Generate + render per-vertex scenery |
 | `SceneryHelpers` | Displace / RotateObj / ScaleObj / ObjAlign / CheckSlope |
 | `SceneryInstance` | Per-spawn instance data |
 ### Static objects (buildings, slabs, props — Setup + GfxObj + ObjDesc)
 | Component | What it does |
 |---|---|
 | `StaticObjectRenderManager` | Master pipeline for static objects |
 | `ObjectRenderManagerBase` + `BaseObjectRenderManager` | Common render base |
 | `ObjectMeshManager` | Mesh extraction from Setup/GfxObj, ObjDesc application |
 ### Dungeons / interiors
 | Component | What it does |
 |---|---|
 | `EnvCellRenderManager` | Dungeon interior cell geometry |
 | `PortalRenderManager` | Portal traversal / visibility |
 ### Sky + atmosphere
 | Component | What it does |
 |---|---|
 | `SkyboxRenderManager` | Skybox rendering |
 | `ParticleEmitterRenderer` + `ParticleBatcher` + `ActiveParticleEmitter` | Particle systems (sky particles, weather, magic) |
 ### Visibility / culling
 | Component | What it does |
 |---|---|
 | `VisibilityManager` + `VisibilitySnapshot` | Frustum + cell visibility |
 | `Frustum` | Frustum-cull math |
 ### Other rendering helpers
 | Component | What it does |
 |---|---|
 | `MinimapRenderer` | Top-down minimap |
 | `GlobalMeshBuffer` | Shared GPU mesh buffer |
 | `GpuResourceManager` | GPU resource lifecycle |
 | `InstanceData` | Instanced draw data |
 | `TextureHelpers` | INDEX16, P8, BGRA, DXT decode + alpha (canonical port) |
 | `DebugRenderer` + `DebugRendererLineDrawer` + `EdgeLineBuilder` | Debug primitives |
 ### Shaders (22 total)
 Located at `Chorizite.OpenGLSDLBackend/Shaders/`:
 `Landscape.{vert,frag}` · `StaticObject.{vert,frag}` · `StaticObjectModern.{vert,frag}` · `Particle.{vert,frag}` · `PortalStencil.{vert,frag}` · `Outline.{vert,frag}` · `Simple3D.{vert,frag}` · `InstancedLine.{vert,frag}` · `Text.{vert,frag}` · `UI.{vert,frag}` · `Gizmo.{vert,frag}` (editor-only)
 ---
 ## 🟢 LOW-LEVEL GL / FRAMEWORK — take or replace with our own
 Either take WB's wrappers wholesale, or keep our own and adapt the
 render managers to use ours. These wrappers are stateless or
 near-stateless and are the easiest to swap.
 | Component | What it does |
 |---|---|
 | `OpenGLGraphicsDevice` | Silk.NET.OpenGL wrapper |
 | `OpenGLRenderer` | Render orchestration |
 | `GLSLShader` | Shader compile/link/uniforms |
 | `GLHelpers` + `GLStateScope` | GL state utility |
 | `ManagedGLFrameBuffer` / `ManagedGLIndexBuffer` / `ManagedGLTexture` / `ManagedGLTextureArray` / `ManagedGLUniformBuffer` / `ManagedGLVertexArray` / `ManagedGLVertexBuffer` | GL resource wrappers |
 | `TextureParameters` | Sampler config |
 | `GpuMemoryTracker` | Memory tracking |
 | `Camera2D` / `Camera3D` / `CameraBase` / `ICamera` / `CameraController` | Camera primitives |
 | `GameScene` + `SingleObjectScene` + `SceneData` + `ModernRenderData` + `RenderPass` | Scene / pass structures |
 ---
 ## 🟢 GEOMETRY / MATH UTILS — take wholesale
 | Component | File |
 |---|---|
 | `TerrainUtils` (OnRoad, GetNormal, GetHeight, GetRoad, palCode) | `WorldBuilder.Shared/Modules/Landscape/Lib/TerrainUtils.cs` |
 | `TerrainCacheManager` | `…/Lib/TerrainCacheManager.cs` |
 | `TerrainRaycast` | `…/Lib/TerrainRaycast.cs` |
 | `GeometryUtils` | `WorldBuilder.Shared/Lib/GeometryUtils.cs` |
 | `RaycastingUtils` (ray-vs-sphere/AABB/triangle) | `WorldBuilder.Shared/Lib/RaycastingUtils.cs` |
 | `DoubleNumerics` (double-precision Vector/Matrix) | `WorldBuilder.Shared/Lib/DoubleNumerics.cs` |
 | `DatUtils` | `WorldBuilder.Shared/Lib/DatUtils.cs` |
 | `BoundingBoxExtensions` | `Chorizite.OpenGLSDLBackend/Lib/BoundingBoxExtensions.cs` |
 ---
 ## 🟢 DATA MODELS — take selectively
 | Component | What it does |
 |---|---|
 | `RegionInfo` | Landblock metadata wrapper (LandblockSizeInUnits, CellSizeInUnits, etc.) |
 | `TerrainEntry` | Per-vertex terrain (Type/Scenery/Road/Height) |
 | `MergedLandblock` | Merged dat data |
 | `CellSplitDirection` | SW-NE vs NE-SW |
 | `Cell` | Generic cell wrapper |
 | `ObjectId` | Object identifier |
 | `Position` | World position |
 | `ACEnums` | AC-specific enums |
 | `WbBuildingPortal` / `WbCellPortal` | Portal structures |
 | `BuildingObject` | Building data |
 ---
 ## 🟡 EDITOR-ONLY — leave behind / delete in fork
 These exist for the editor experience and have no place in a game
 client. Delete in fork.
 - **`Modules/Landscape/Tools/*`** — `BrushTool`, `BucketFillTool`,
  `RoadLineTool`, `RoadVertexTool`, `InspectorTool`,
  `ObjectManipulationTool`, `Gizmo*` (DragHandler, HitTester, Renderer,
  State), `TexturePainting*`, `SceneRaycaster`,
  `LandscapeBrush`, `LandscapeToolBase`, `LandscapeToolContext`,
  `IToolSettingsProvider`, `ILandscapeBrush`, `ILandscapeEditorService`,
  `ILandscapeRaycastService`, `ILandscapeTool`, `ITexturePaintingTool`
 - **`Modules/Landscape/Commands/*`** — undo/redo command pattern for
  editor (Add/Delete/Move/Rename/Reorder/etc.)
 - **`LandscapeDocument` + `LandscapeLayer` + `LandscapeLayerGroup` + `LandscapeChunk` + `LandscapeLayerChunk` + `LandscapeLayerBase`** — editor document model
 - **`Modules/Landscape/Models/TerrainPatch*` + `LandblockChangedEventArgs`** — editor mutation events
 - **`Modules/Landscape/Services/ILandscapeCacheService` + `ILandscapeDataProvider` + `ILandscapeObjectService` + impls** — editor data flow
 - **All `Migrations/*`** — SQLite schema migrations (project file format)
 - **`Repositories/*`** + **`Services/*`** — project storage, dat repository, AceDb, SignalR sync, document manager, undo stack, world coordinates, keyword DB, project migration, semantic kernel AI helpers
 - **`Hubs/*`** — collaborative editing via SignalR
 - **`StaticObject` (editor model)** — replace with our own scene-state data model fed from network
 - **`BackendGizmoDrawer` + `GizmoRenderer`** — editor gizmos
 - **`ProjectStructures, IProject, Project`** — editor project files
 - **`KeyBinding`** — editor input binding
 - **`ViewportInputEvent[Extensions]`** — editor viewport input
 - **`EditorState`** — editor state container
 ---
 ## 🟡 AUDIO / FONT — we already have alternatives
 Keep ours; don't take theirs.
 - **`AudioPlaybackEngine`** — uses MP3Sharp. We have OpenAL.
 - **`FontRenderer`** — uses ImageSharp. We have BitmapFont/StbTrueTypeSharp + ImGui.
 ---
 ## 🔴 NOT IN WORLDBUILDER — port from retail decomp ourselves
 WorldBuilder is a dat editor; it does not have:
 - **Network protocol** — UDP framing, ISAAC, packet codec, ACE message
  layer (we have this; oracle is `references/holtburger`)
 - **Physics** — collision (CPhysicsObj transitions, BSP queries, sphere
  sweeps), step-up, walkable validation (we have partial; oracle is the
  retail decomp at `docs/research/named-retail/`)
 - **Animation** — motion sequencer, cycle/non-cycle parts, animation
  frame interpolation (we have this; oracle is retail decomp)
 - **Movement** — local player WASD → MoveToState wire, remote-entity
  motion via UpdateMotion + dead-reckoning (we have this; oracle is
  `references/holtburger` + retail decomp)
 - **Game UI** — chat, vitals, inventory, spell book, allegiance, options
  (we have this; ImGui-based today, custom-toolkit later)
 - **Plugin API** — `IGameState`, `IEvents`, `IActions`, `IPacketPipeline`,
  `IOverlay` (we have this — acdream-unique)
 - **Game events** — combat, allegiance, spell casting, quest events
  (we have this; oracle is ACE for opcodes + retail for client behavior)
 - **Audio** — OpenAL pipeline, sound triggers (we have this)
 - **TurbineChat** + **slash commands** (we have this)
 - **Login + character selection flow** (we have this)
 ---
 ## What this means for the workflow (post-Phase O)
 The CLAUDE.md "grep named → decompile → verify → port" workflow stays
 the rule for everything in the 🔴 list (network, physics, animation,
 movement, UI, plugin, audio, chat).
 For anything in 🟢 that we've already extracted: **the code is in our
 tree at `src/AcDream.{Core,App}/Rendering/Wb/`**. Read it there — don't
 grep `references/WorldBuilder/` unless you want to compare against the
 original. Re-porting from retail decomp when we already have a tested
 port is still how we'd get the scenery edge-vertex bug back.
 For anything in 🟢 that we have NOT yet extracted: grep
 `references/WorldBuilder/` to find the source, then extract it using the
 Phase O pattern (verbatim copy → adapt constructor to accept
 `IDatCollection` via `DatCollectionAdapter` where needed → add to
 `src/AcDream.App/Rendering/Wb/`). Do NOT add a new project reference back
 to `WorldBuilder.Shared` or `Chorizite.OpenGLSDLBackend` — Phase O
 permanently removed those.
 When we discover a behavior mismatch with retail (rare — the extracted
 code is the same as the original), the resolution is: reconcile extracted
 code ↔ retail decomp ↔ holtburger ↔ ACE ↔ ACViewer (the existing
 reference hierarchy in CLAUDE.md). Our extracted code ranks at the top
 of that hierarchy for anything 🟢.
--- a/docs/plans/2026-04-11-roadmap.md
+++ b/docs/plans/2026-04-11-roadmap.md
@ -1,34 +1,10 @@
 # acdream — strategic roadmap
-**Status:** Living document. Updated 2026-05-19. **Between phases.** **Since the last header update:** Indoor walkable-plane BSP port FOUNDATION shipped (6 commits, `ff548b9` → `f845b22`) but visual verification failed — cellar descent, 2nd-floor walking, single-floor cottage regressions all confirm the shipped fix doesn't address the user-reported indoor bugs. Root cause now diagnosed as deeper than originally thought: `TryFindIndoorWalkablePlane` exists as a Phase 2 stop-gap that retail doesn't have an analog for. Retail retains ContactPlane state across frames; we re-synthesize per frame. Foundation work (BSP walker + probe + tests) remains useful; next phase needs to port retail's ContactPlane retention mechanism and likely eliminate `TryFindIndoorWalkablePlane` entirely. Handoff: [`docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md`](../research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md). ISSUES #83 remains OPEN with deeper diagnosis. **Earlier:** Indoor cell rendering Phase 1 (diagnostics) + Phase 2 (fix) shipped — root cause was a one-line WB bug at `ObjectMeshManager.cs:1223` (blind `TryGet<Setup>` on GfxObj-prefixed stab ids threw `ArgumentOutOfRangeException` which WB's outer catch silently swallowed, causing 26/123 Holtburg cells to fail upload). Identified via diagnostic chain (5 `[indoor-*]` probes + a `ContinueWith` exception surfacer + a `ConsoleErrorLogger` injected into WB), fixed with a Setup-prefix guard. User visually confirmed floors render. Surfaced 9 pre-existing indoor bugs filed in `docs/ISSUES.md`. **Earlier:** C.1.5b shipped (issue #56 per-part transforms for multi-emitter PES + `EntityScriptActivator` extended to dat-hydrated EnvCell statics & exterior stabs — portal swirl, inn fireplace flames, cottage chimney smoke, spell-cast particles all match retail). post-A.5 polish completed (#52 lifestone, #54 JobKind, #53 Tier 1 cache); N.6 slice 1 shipped (gpu_us fix + radius=12 perf baseline, conclusion CPU dominates GPU 30–50×); C.1.5a shipped (portal PES wiring; surfaced #56 → resolved in C.1.5b).
+**Status:** Living document. Updated 2026-05-02 for Phase M network-stack conformance planning.
 **Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file.
 ---
 ## Current program: Phase W — Unified Cell Graph (UCG)
 **Pivot (2026-06-02).** The render-pipeline reset stalled because the indoor "world from
 below" is a cell-**membership** disagreement between the render-side `CellVisibility` and
 the physics-side `ResolveCellId` — not any single draw gate (pixel-grounded evidence:
 [`docs/research/2026-06-02-render-cell-membership-evidence.md`](../research/2026-06-02-render-cell-membership-evidence.md)).
 We committed to a full migration onto **one retail `CObjCell` cell graph** shared by
 physics + collision + render + streaming. **Supersedes** the render-only "Phase U" framing
 and the abandoned A8 two-pipe (#103). Five verify-each stages on branch
 `claude/thirsty-goldberg-51bb9b`:
 | Stage | What | Status |
 |---|---|---|
 | **W1** | `ObjCell` scaffold — Core `ObjCell`/`EnvCell`/`LandCell`/`CellPortal`/`CellGraph` built alongside the legacy systems, consumed by nobody (zero behavior change). | **Shipped 2026-06-02** (`9cb1571`→`f2663b7`; 22 tests; Opus-reviewed) |
 | W2 | One membership — player `curr_cell` via retail `find_cell_list` + `change_cell` + doorway hysteresis; collapses `ResolveCellId` + `FindCameraCell` into one answer. *First behavior-changing stage.* | **W2a shipped + visually verified 2026-06-02** (`0e27a6c`+`02acac5`: render reads physics `CurrCell`; the indoor "world from below" is FIXED — cellar/stairs seal walls+floor). **W2b next** (doorway hysteresis — ping-pong `0170↔0031` confirmed). Baseline+handoff: [`docs/research/2026-06-02-phase-w-w2a-shipped-baseline-handoff.md`](../research/2026-06-02-phase-w-w2a-shipped-baseline-handoff.md) |
 | W3 | Render on the graph — PView walk + **one gate** for terrain/shells/entities. **The visible M1.5 indoor fix.** | Planned |
 | W4 | Collision on the graph — physics queries the same `ObjCell`s; retire parallel `CellPhysics`. | Planned |
 | W5 | Streaming → `ObjCell`s — terrain as `LandCell`; the frozen-streaming rewrite. | Planned |
 W1 spec: [`docs/superpowers/specs/2026-06-02-unified-cell-graph-stage1-design.md`](../superpowers/specs/2026-06-02-unified-cell-graph-stage1-design.md) ·
 W1 plan: [`docs/superpowers/plans/2026-06-02-unified-cell-graph-stage1.md`](../superpowers/plans/2026-06-02-unified-cell-graph-stage1.md).
 ---
 ## Phases already shipped
 | Phase | What landed | Verification |
@ -55,7 +31,6 @@ W1 plan: [`docs/superpowers/plans/2026-06-02-unified-cell-graph-stage1.md`](../s
 | A.1 | Streaming landblock loader — runtime-configurable visible window (default 5×5, `ACDREAM_STREAM_RADIUS`), camera-centered offline / player-centered live, hysteresis-based unloads, pending-spawn list for late CreateObject events | Live ✓ |
 | A.2 | Frustum culling — per-landblock AABB test (Gribb-Hartmann), terrain + static-mesh renderers skip culled landblocks, perf overlay in window title | Visual ✓ |
 | A.3 | Background net receive thread — dedicated daemon thread buffers UDP into Channel, render thread drains | Visual ✓ |
 | A.5 | Two-tier streaming + horizon LOD — N₁=4 (full detail, 81 LBs) + N₂=12 (terrain only, 544 LBs); fog blend at N₁; per-LB entity dispatcher walk tightened (Change #1 animated-walk fix + Change #2 cached AABB); single-worker off-thread mesh build; mipmaps + 16x anisotropic on TerrainAtlas; A2C with MSAA 4x on foliage; depth-write audit + lock-in test; **NEW T22.5: QualityPreset system** (Low/Medium/High/Ultra) with per-preset radii + MSAA + anisotropic + A2C + completions; env-var overrides per field; F11 mid-session re-apply. **Bug fixes post-T26 ship-prep**: (Bug A) far-tier worker now strips entities from far-tier loads — without this fix, far-tier LBs were loading their full entity layer (~71K entities) defeating the two-tier optimization; (Bug B) WalkEntities switched from per-frame fresh-list allocation to caller-provided scratch list (eliminated ~480 KB/frame GC pressure). **Deferred to post-A.5**: Tier 1 entity-classification cache (first attempt broke animation; revert + redo with animation-mutation audit), lifestone visual (missing in render), JobKind plumbing through BuildLandblockForStreaming (proper Bug A fix), Tier 2/3 perf optimizations (roadmap at docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md). Plan archived at docs/superpowers/plans/2026-05-09-phase-a5-two-tier-streaming.md. | Live ✓ |
 | B.3 | Physics MVP resolver foundation — terrain contact, CellSurface prototype, streaming-populated collision inputs, and first `PhysicsEngine` resolver path. Not the complete retail collision system. | Tests ✓ |
 | B.2 | Player movement mode — Tab-toggled WASD ground walking, walk/run/idle animations, third-person chase camera, MoveToState + AutonomousPosition outbound, portal entry. Outdoor-only MVP. | Live ✓ |
 | D.1 | 2D ortho overlay + font rendering (StbTrueTypeSharp atlas + TextRenderer + DebugOverlay) | Visual ✓ |
@ -82,23 +57,6 @@ W1 plan: [`docs/superpowers/plans/2026-06-02-unified-cell-graph-stage1.md`](../s
 | K | Input architecture — `Action` enum, `KeyChord`, `KeyBindings`, multicast `InputDispatcher` with scope-stack + modal capture, retail-default keymap (152 bindings), `keybinds.json` persistence, F11 Settings panel with click-to-rebind + conflict detection, main menu bar + View menu | Live ✓ |
 | L.0 | Full retail-style Settings interface — F11 tabbed panel with 6 tabs (Keybinds + Display + Audio + Gameplay + Chat + Character). `settings.json` at `%LOCALAPPDATA%\acdream\`, per-toon `Character` keying (swapped on EnterWorld). Display GL knobs (Resolution / Fullscreen / VSync / FOV / ShowFps) + Audio (Master / SFX) live-wired; Gameplay / Chat / Character settings persist for server-sync wiring later. Tab API extension to `IPanelRenderer`; chat Copy mode (read-only multi-line); per-panel layout reset; FramebufferResize handler keeps GL viewport + camera aspect + panel positions in sync. | Live ✓ |
 | C.1 | PES particle system + sky-pass refinements — retail-faithful `ParticleEmitterInfo` unpack with all 13 motion integrators (`Particle::Init`/`Update` ports of `0x0051c290`/`0x0051c930`), `PhysicsScriptRunner` with `CallPES` self-loop semantics, `ParticleHookSink` with `EmitterDied` cleanup, instanced billboard `ParticleRenderer` with material-derived blend (DAT emitters never default additive — pulled from particle GfxObj surface), global back-to-front sort, BC clipmap alpha-keying, AttachLocal `is_parent_local=1` live-parent follow via `UpdateEmitterAnchor`. Sky pass: `Translucent+ClipMap` → alpha-blend cloud sheet (matches `D3DPolyRender::SetSurface` `0x0059c4d0`), raw-`Additive` fog-skip (matches `0x0059c882`), per-keyframe `SkyObjectReplace` Translucency/Luminosity/MaxBright divide-by-100, bit `0x01` pre/post-scene split (matches `GameSky::CreateDeletePhysicsObjects` `0x005073c0`), Setup-backed (`0x020xxxxx`) sky objects via `SetupMesh.Flatten`, persistent GL sampler objects (Wrap + ClampToEdge) replace per-frame wrap-mode mutation (ported from WorldBuilder's `OpenGLGraphicsDevice`), post-scene Z-offset gated on `(Properties & 4) != 0 && (Properties & 8) == 0` per `GameSky::UpdatePosition` `0x00506dd0`. Sky-PES playback disabled by default (named-retail proves `GameSky` drops `pes_id`); `ACDREAM_ENABLE_SKY_PES=1` opens the experimental path. 1325 → 1331 tests. | Live ✓ |
 | N.1 | WorldBuilder-backed scenery (Chorizite/WorldBuilder fork as submodule, SceneryHelpers + TerrainUtils replace our inline ports) | Live ✓ |
 | N.3 | WorldBuilder-backed texture decode — `SurfaceDecoder` delegates INDEX16 / P8 / A8R8G8B8 / R8G8B8 / A8(+Additive) to `TextureHelpers.Fill*`; `isAdditive` threaded through (terrain alpha → `FillA8Additive`, non-additive entity surfaces → `FillA8`). R5G6B5 + A4R4G4B4 newly handled (previously magenta). X8R8G8B8, DXT1/3/5, SolidColor remain ours (no WB equivalent). 9 conformance tests prove byte-identical equivalence per format. | Live ✓ |
 | N.4 | Rendering pipeline foundation — adopted WB's `ObjectMeshManager` as the production mesh pipeline behind `ACDREAM_USE_WB_FOUNDATION` (default-on). `WbMeshAdapter` is the single seam (owns `ObjectMeshManager`, drains the staged-upload queue per frame, populates `AcSurfaceMetadataTable` with per-batch translucency / luminosity / fog metadata). `WbDrawDispatcher` is the production draw path: groups all visible (entity, batch) pairs, single-uploads the matrix buffer, fires one `glDrawElementsInstancedBaseVertexBaseInstance` per group with `BaseInstance` slicing into the shared instance VBO. `LandblockSpawnAdapter` + `EntitySpawnAdapter` bridge spawn lifecycle to WB ref-counts (atlas tier vs per-instance). Perf wins shipped as part of N.4: per-entity frustum cull, opaque front-to-back sort, palette-hash memoization (compute once per entity, reuse across batches). Visual verification at Holtburg passed: scenery + connected characters with full close-detail geometry (Issue #47 regression resolved). Legacy `InstancedMeshRenderer` retained as `ACDREAM_USE_WB_FOUNDATION=0` escape hatch until N.6 (retired early in N.5 ship amendment). | Live ✓ |
 | N.5 | Modern rendering path — lifted `WbDrawDispatcher` onto bindless textures (`GL_ARB_bindless_texture`) + `glMultiDrawElementsIndirect`. Per-frame entity rendering: 3 SSBO uploads (instance matrices @ binding=0, batch data @ binding=1, indirect commands) + 2 indirect draw calls (opaque + transparent). ~12-15 GL calls per frame regardless of group count, down from hundreds-of-per-group in N.4. CPU dispatcher: 1.23 ms/frame median at Holtburg courtyard (1662 groups, ~810 fps sustained). All textures on the WB modern path use 1-layer `Texture2DArray` + `sampler2DArray`. Legacy callers keep `Texture2D` / `sampler2D` via the parallel `TextureCache` path until N.6 retires them. Three gotchas captured in memory: texture target lock-in, bindless Dispose order (two-phase non-resident before delete), GL_TIME_ELAPSED double-buffering. **Ship amendment 2026-05-08:** legacy renderers (`InstancedMeshRenderer`, `StaticMeshRenderer`, `WbFoundationFlag`) retired within N.5 — modern path is mandatory; missing bindless throws `NotSupportedException` at startup. N.6 scope narrowed accordingly. Plan archived at `docs/superpowers/plans/2026-05-08-phase-n5-modern-rendering.md`. | Live ✓ |
 | N.5b | Terrain on the modern rendering path — `TerrainModernRenderer` replaces `TerrainChunkRenderer` (the latter plus `TerrainRenderer` + `terrain.vert/.frag` deleted). Single global VBO/EBO with slot allocator (one slot per landblock), per-frame `DrawElementsIndirectCommand[]` upload + `glMultiDrawElementsIndirect`, bindless atlas handles passed as `uvec2` uniforms reconstructed via `sampler2DArray(handle)`. **Path C** chosen: mirrors WB's `TerrainRenderManager` pattern but consumes `LandblockMesh.Build` so retail's `FSplitNESW` formula is preserved (closes ISSUE #51). Path A killed by 49.98% measured divergence between WB's `CalculateSplitDirection` and retail's at addr `00531d10`; Path B (fork-patch WB) rejected for permanent maintenance burden. Perf at Holtburg radius=5 (commit `da56063`): modern 6.4-7.0 µs / 9-14 µs p95 vs legacy 1.5 µs / 3.0 µs — **modern is ~4× SLOWER on CPU at radius=5** because legacy's 16×16-LB chunking collapsed visible LBs to one `glDrawElements`. Architectural wins (zero `glBindTexture`/frame, constant-cost dispatch, per-LB frustum cull) manifest at higher radius (A.5 territory). Spec acceptance criterion 5 ("≥10% lower CPU at radius=5") amended via `docs/plans/2026-05-09-phase-n5b-perf-baseline.md`. Three gotchas captured in memory: `uniform sampler2DArray` + `glProgramUniformHandleARB` GL_INVALID_OPERATIONs on at least one driver (use `uniform uvec2` + `sampler2DArray(handle)` constructor instead — N.5's mesh_modern pattern); `MaybeFlushTerrainDiag` median-calc underflow on first sample; visual gates need actual visual confirmation, not assent. Plan archived at `docs/superpowers/plans/2026-05-09-phase-n5b-terrain-modern.md`. | Live ✓ |
 | N.6 slice 1 | GPU timing fix + radius=12 perf baseline. Fixed the gpu_us double-buffering bug in `WbDrawDispatcher` (ring-of-3 query slots, read-before-overwrite, vendor-neutral across AMD/NVIDIA/Intel desktop GL). Added env-gated `ACDREAM_DUMP_SURFACES=1` one-shot surface-format histogram dump in `TextureCache` for the atlas-opportunity audit. Captured authoritative baseline at Holtburg radii 4 / 8 / 12 (standstill + walking) with the now-working `gpu_us` diagnostic; baseline doc concludes CPU dominates GPU by 30–50× at every radius and recommends C.1.5 next then reduced-scope slice 2 (atlas + persistent-mapped buffers dropped). Baseline numbers at [docs/plans/2026-05-11-phase-n6-perf-baseline.md](2026-05-11-phase-n6-perf-baseline.md). Plan archived at `docs/superpowers/plans/2026-05-11-phase-n6-slice1.md`. | Live ✓ |
 | C.1.5a | Portal PES wiring — server-spawned `WorldEntity` entities now fire their `Setup.DefaultScript` through the already-shipped `PhysicsScriptRunner` on enter-world. New ~70-line [`EntityScriptActivator`](../../src/AcDream.App/Rendering/Vfx/EntityScriptActivator.cs) class wires into `GpuWorldState`'s spawn lifecycle (`AppendLiveEntity` → `OnCreate`, `RemoveEntityByServerGuid` → `OnRemove`). Resolver lambda in `GameWindow` hits `_dats.Get<Setup>(...)?.DefaultScript.DataId` with defensive try/catch returning `0u` on miss. Activator also seeds `_particleSink.SetEntityRotation` so hook offsets transform from entity-local to world space correctly. **Verified at the Holtburg Town network portal**: 10-hook portal script fires end-to-end with correct color, persistence, orientation, multi-emitter dispatch. **Known limitation surfaced and filed as issue #56**: `ParticleHookSink` ignores `CreateParticleHook.PartIndex`, so the 10 emitters collapse to one root position instead of distributing across the portal Setup's parts — visually produces a compressed, partly-ground-buried swirl. Mechanism is correct; per-part transform handling is the next vfx-pipeline work (blocks slice 2 visual delight; affects every multi-emitter PES). Spec: [`docs/superpowers/specs/2026-05-12-phase-c1.5a-portals-design.md`](../superpowers/specs/2026-05-12-phase-c1.5a-portals-design.md). Plan: [`docs/superpowers/plans/2026-05-12-phase-c1.5a-portals.md`](../superpowers/plans/2026-05-12-phase-c1.5a-portals.md). | Live ✓ (with #56) |
 | B.4b | Outbound Use handler wiring + 4 bonus fixes (L.2g slices 1b+1c, double-click detection, DoubleClick gate fix). Shipped 2026-05-13 (branch `claude/compassionate-wilson-23ff99`, merge pending). Closes #57. Files #58 (door swing animation, M1-deferred). `WorldPicker.BuildRay` + `Pick` (ray-sphere entity pick with inside-sphere guard); `GameWindow.OnInputAction` switch cases for `SelectLeft` / `SelectDblLeft` / `UseSelected`; `_entitiesByServerGuid` reverse-lookup dict + ServerGuid→entity.Id translation in `OnLiveStateUpdated` (L.2g slice 1c — THE actual blocker); `InputDispatcher` double-click detection 500ms threshold (binding was dead code without it); `CollisionExemption.ShouldSkip` widened to ETHEREAL-alone (ACE Door.Open() sends `state=0x0001000C`, not `0x14`). M1 demo target "open the inn door" verified at Holtburg inn doorway. Plan: [`docs/superpowers/plans/2026-05-13-phase-b4b-plan.md`](../superpowers/plans/2026-05-13-phase-b4b-plan.md). Handoff: [`docs/research/2026-05-13-b4b-shipped-handoff.md`](../research/2026-05-13-b4b-shipped-handoff.md). | Live ✓ |
 | B.4c | Door swing animation. Shipped 2026-05-13 (branch `claude/phase-b4c-door-anim`, merge pending). Closes #58. Files #61 (AnimationSequencer link→cycle boundary flash; low-severity polish) + #62 (PARTSDIAG null-guard; latent). Spawn-time `AnimationSequencer` registration for door entities in `GameWindow.OnLiveEntitySpawnedLocked`: initial cycle seeded from `spawn.PhysicsState` (Off for closed, On for open). Shared `IsDoorName` / `IsDoorSpawn` helpers. `[door-cycle]` diagnostic in `OnLiveMotionUpdated` (gated on `ACDREAM_PROBE_BUILDING`). Bonus stance-value fix: `NonCombat = 0x3D` not `0x01` (wrong value caused doors to render halfway underground via empty sequencer frames). Visual-verified 2026-05-13 at Holtburg inn doorway: swing-open + swing-close cycles both play. M1 demo target "open the inn door" now has full visual feedback. Plan: [`docs/superpowers/plans/2026-05-13-phase-b4c-plan.md`](../superpowers/plans/2026-05-13-phase-b4c-plan.md). Handoff: [`docs/research/2026-05-13-b4c-shipped-handoff.md`](../research/2026-05-13-b4c-shipped-handoff.md). | Live ✓ |
 | B.5 | Ground-item pickup (F-key, close-range path). Shipped 2026-05-14 (branch `claude/phase-b5-pickup`, merge pending). Closes M1 demo target 4/4 *"pick up an item"*. New `InteractRequests.BuildPickUp(seq, itemGuid, containerGuid, placement)` builds the 24-byte `PutItemInContainer (0xF7B1/0x0019)` wire body verified against `references/ACE/Source/ACE.Server/Network/GameAction/Actions/GameActionPutItemInContainer.cs`. New private `GameWindow.SendPickUp(uint itemGuid)` helper mirrors `SendUse`'s gate-on-InWorld pattern; `case InputAction.SelectionPickUp` in `OnInputAction` switch routes the F-key through `_selectedGuid`. **Bonus wire-handler fix (Task 2b):** ACE despawns picked-up items via `GameMessagePickupEvent (0xF74A)`, not the `GameMessageDeleteObject (0xF747)` we already handled — surfaced during visual testing (item kept rendering on ground after successful server-side pickup). New `PickupEvent.cs` parser + `WorldSession` dispatch branch adapt to `DeleteObject.Parsed` and reuse the existing `EntityDeleted → OnLiveEntityDeleted → RemoveLiveEntityByServerGuid` chain. Files #63 (server-initiated `MoveToObject` auto-walk not honored — out-of-range pickup / double-click fails server-side timeout) + #64 (local-player pickup animation does not render). Visual-verified 2026-05-14 at Holtburg: 3 successful close-range pickups (Pink Taper + Violet Tapers), item despawns locally as ACE acks. Plan: [`docs/superpowers/plans/2026-05-14-phase-b5-pickup.md`](../superpowers/plans/2026-05-14-phase-b5-pickup.md). Handoff: [`docs/research/2026-05-14-b5-shipped-handoff.md`](../research/2026-05-14-b5-shipped-handoff.md). | Live ✓ |
 | Indoor lighting + rendering — Phase 1 (diagnostics) | Five `[indoor-*]` probes wired through new `AcDream.Core.Rendering.RenderingDiagnostics` static class + DebugVM mirrors + DebugPanel checkboxes. `WbMeshAdapter` emits `[indoor-upload] requested/completed`; `WbDrawDispatcher` emits `[indoor-walk]`, `[indoor-lookup]`, `[indoor-xform]`, `[indoor-cull]` per cell entity. All rate-limited via per-cellId frame counter; lookup probe uses high-bit-tagged key namespace to avoid cross-probe suppression. Holtburg `ACDREAM_PROBE_INDOOR_ALL=1` capture identified 26/123 cells silently failing — confirmed H1 (WB swallowed exception). Spec: [`docs/superpowers/specs/2026-05-19-indoor-cell-rendering-fix-design.md`](../superpowers/specs/2026-05-19-indoor-cell-rendering-fix-design.md). Plan: [`docs/superpowers/plans/2026-05-19-indoor-cell-rendering-phase1-diagnostics.md`](../superpowers/plans/2026-05-19-indoor-cell-rendering-phase1-diagnostics.md). Capture: [`docs/research/2026-05-19-indoor-cell-rendering-probe-capture.md`](../research/2026-05-19-indoor-cell-rendering-probe-capture.md). | Tests ✓ |
 | Indoor lighting + rendering — Phase 2 (fix) | Three-component diagnostic-driven fix for missing-floor bug. Component 1: `WbMeshAdapter` captures the `Task<ObjectMeshData?>` from `PrepareMeshDataAsync` and attaches a `ContinueWith` for EnvCell ids — surfaces faulted-task exceptions + clean-null returns. Component 2: replaced `NullLogger<ObjectMeshManager>` with a Console-backed `ConsoleErrorLogger<T>` so WB's intentional `_logger.LogError(ex, ...)` at the swallow site at `ObjectMeshManager.cs:589` writes `[wb-error]` lines. **Root cause definitively identified in one capture: `ArgumentOutOfRangeException` from `DatReaderWriter.Setup.Unpack` at WB's `PrepareEnvCellMeshData` line 1223 — `TryGet<Setup>(stab.Id, ...)` was called blindly on every `envCell.StaticObjects` id without checking the Setup-prefix bit. GfxObj-typed stabs (0x01xxxxxx) caused mid-deserialization throws, bubbling up to PrepareMeshData's outer catch which silently returned null. Entire cell upload failed, room mesh never reached `_renderData`.** Component 3 fix: one-line type-check guard `(stab.Id & 0xFF000000u) == 0x02000000u && _dats.Portal.TryGet<Setup>(stab.Id, out var stabSetup)`. Committed to WB submodule on branch `acdream-fix-floor-rendering` at SHA `34460c4` — needs submodule pointer advance at merge time. **Verification: 0 [wb-error] (was 385), 0 NULL_RESULT (was 55), Holtburg 123/123 cells complete (was 97/123). User visually confirmed floors render in Holtburg Inn.** Surfaced 9 pre-existing indoor bugs (see-through floor, indoor collision, stairs, walls, click-thru, indoor lighting artifacts, atmospheric-lighting-on-stabs, slope terrain lighting) — all filed in `docs/ISSUES.md` for follow-up phases. Cause report: [`docs/research/2026-05-19-indoor-cell-rendering-cause.md`](../research/2026-05-19-indoor-cell-rendering-cause.md). Verification: [`docs/research/2026-05-19-indoor-cell-rendering-verification.md`](../research/2026-05-19-indoor-cell-rendering-verification.md). Plan: [`docs/superpowers/plans/2026-05-19-phase2-indoor-cell-rendering-fix.md`](../superpowers/plans/2026-05-19-phase2-indoor-cell-rendering-fix.md). | Live ✓ |
 | C.1.5b | Per-part PES transforms + dat-hydrated entity DefaultScript dispatch. Closes issue #56. Shipped 2026-05-12 across 5 commits (`1e3c33b` docs+plan, `f3bc15e` SetupPartTransforms helper, `11521f4` ParticleHookSink applies `CreateParticleHook.PartIndex`, `5ca5827` activator refactor + GameWindow resolver lambda, `8735c39` GpuWorldState 4 new fire-sites). **Slice A** — new [`SetupPartTransforms.Compute(setup)`](../../src/AcDream.Core/Meshing/SetupPartTransforms.cs) walks `PlacementFrames[Resting]` → `[Default]` → first-available (mirrors `SetupMesh.Flatten` priority) and returns `Matrix4x4` per part; new `ParticleHookSink.SetEntityPartTransforms(entityId, partTransforms)` mirrors the existing `_rotationByEntity` pattern; `SpawnFromHook` now transforms hook offset through `partTransforms[partIndex]` before applying entity rotation. **Slice B** — activator's `ServerGuid==0` guard relaxed: keys by `entity.ServerGuid` when non-zero, else `entity.Id` (collision-free with server guids in the `0x40xxxxxx` interior / `0x80xxxxxx` scenery / `0xC0xxxxxx` ranges). Resolver delegate refactored to return `ScriptActivationInfo(ScriptId, PartTransforms)` so one dat lookup yields both pieces. `GpuWorldState` fires the activator from 4 new sites: `AddLandblock` + `AddEntitiesToExistingLandblock` (Far→Near promotion) for OnCreate, `RemoveLandblock` + `RemoveEntitiesFromLandblock` (Near→Far demotion) for OnRemove. ServerGuid==0 filter on AddLandblock avoids double-firing pending-bucket merges. **Reality discovery folded into spec §3**: EnvCell `StaticObjects` are already hydrated as `WorldEntity` instances by `GameWindow.BuildInteriorEntitiesForStreaming` (with stable `entity.Id` in `0x40xxxxxx`) — no synthetic-ID scheme or separate walker class needed (handoff §4 Q1/Q2 mooted). **Visual verification 2026-05-12**: Holtburg Town network portal swirl distributes across the arch (no ground-burial), Inn fireplace flames render over the firebox, cottage chimney smoke columns render, spell-cast animation-hook particles all match retail. 18 new + 4 updated tests, all Vfx/Meshing/Streaming/Activator green. Spec: [`docs/superpowers/specs/2026-05-13-phase-c1.5b-design.md`](../superpowers/specs/2026-05-13-phase-c1.5b-design.md). Plan: [`docs/superpowers/plans/2026-05-13-phase-c1.5b.md`](../superpowers/plans/2026-05-13-phase-c1.5b.md). | Live ✓ |
 | Indoor walking Phase 1 — BSP cluster (partial) | 2026-05-19. Probe + WorldPicker cell-BSP occlusion (#86 closed) + CellId promotion via AABB containment (partial #84 fix). Seven commits across 5 phases: `18a2e28` plan, `27d7de1` Phase A `[indoor-bsp]` probe + toggle, `3764867` Phase B CellBspRayOccluder in WorldPicker, `4e308d5` Phase B screen-rect tests, `c19d6fb` Phase D AABB containment + L.2e bare-low-byte fix, `fda6af7` Phase E `[cell-cache]` diagnostic, `1f11ba9` Phase E extended AABB/bsphere/poly-count fields. **#86 closed** (picker occlusion). **#84 partially closed** (spawn-in-building stuck-above-floor resolved; threshold/doorway walls remain open under #87). **#85 open** (wall pass-through root cause confirmed as same as #84 remaining symptom — CellId doesn't stay promoted during outdoor→indoor walking). **#87 filed** (portal-based indoor cell tracking — retail-faithful follow-up). `[indoor-bsp]` + `[cell-cache]` probes stay in place as scaffolding for the follow-up phase. Handoff: [`docs/research/2026-05-19-cluster-a-shipped-handoff.md`](../research/2026-05-19-cluster-a-shipped-handoff.md). Plan: [`docs/superpowers/plans/2026-05-19-indoor-walking-phase1-bsp-cluster.md`](../superpowers/plans/2026-05-19-indoor-walking-phase1-bsp-cluster.md). | Tests ✓ |
 | Indoor walking Phase 2 — Portal-based cell tracking | 2026-05-19. Portal-graph traversal replaces Phase D's AABB containment. Six commits: `1969c55` CellBSP+Portals wired into CellPhysics; `aad6976` CellTransit.FindCellList + FindTransitCellsSphere + AddAllOutsideCells + ResolveCellId rename; `069534a` BuildingPhysics + CheckBuildingTransit for outdoor→indoor entry; `702b30a` code-review polish; `3ffe1e4` pass foot-sphere center to ResolveCellId (critical fix — was passing CheckPos instead of GlobalSphere[0].Origin, causing PointInsideCellBsp to return false at floor level); `eb0f772` TryFindIndoorWalkablePlane synthesizes walkable plane from cell floor poly so the resolver doesn't fall through to outdoor SampleTerrainWalkable. **Closes #87, #85, and the wall-pass-through portion of #84 (fully closes #84).** Files #88 (indoor static object vibration — pre-existing) and #89 (BSPQuery.SphereIntersectsCellBsp — approximation in CheckBuildingTransit). `[cell-transit]`, `[indoor-bsp]`, `[check-bldg]`, `[cell-cache]` probes stay in place. Handoff: [`docs/research/2026-05-19-indoor-walking-phase2-shipped-handoff.md`](../research/2026-05-19-indoor-walking-phase2-shipped-handoff.md). | Live ✓ |
 | Indoor walking Phase A4 — Multi-cell BSP iteration | 2026-05-20. Ports retail's `CTransition::check_other_cells` (`acclient_2013_pseudo_c.txt:272717-272798`). After the primary cell's BSP returns OK, every other cell the foot-sphere overlaps is queried via `BSPQuery.FindCollisions`. Halt on first Collided/Adjusted/Slid; Slid clears the contact-plane fields. Three commits land the slices: `e6369e2` `CellTransit.FindCellSet` overload (refactor `FindCellList` to expose the candidate set); `493c5e5` `Transition.CheckOtherCells` + `ApplyOtherCellResult` combine helper; `691493e` (orig `967d065`, then `3add110` revert, then this reapply) wires `CheckOtherCells` into `FindEnvCollisions`. 10 new unit tests; 1139 + 8 baseline maintained. **Visual verification surfaced a separate, pre-existing M2 blocker:** at the Holtburg inn doorway the CellId ping-pongs between outdoor `0xA9B40022` and indoor vestibule `0xA9B40164` rapidly because indoor BSP push-back exits the indoor CellBSP volume → ResolveCellId reclassifies as outdoor → wall checks bypassed on outdoor ticks. Bug reproduces fully with A4 reverted (`launch-revert2.log`), confirming A4 is not the cause. A4 is correct and tested but **dormant in practice** until the ping-pong is fixed. Handoff: [`docs/research/2026-05-20-phase-a4-shipped-cell-pingpong-finding.md`](../research/2026-05-20-phase-a4-shipped-cell-pingpong-finding.md). Spec: [`docs/superpowers/specs/2026-05-20-phase-a4-multi-cell-bsp-design.md`](../superpowers/specs/2026-05-20-phase-a4-multi-cell-bsp-design.md). Plan: [`docs/superpowers/plans/2026-05-20-phase-a4-multi-cell-bsp.md`](../superpowers/plans/2026-05-20-phase-a4-multi-cell-bsp.md). | Live ✓ (dormant pending cell-tracking fix) |
 | Phase O — DatPath Unification | 2026-05-21. ONE thing touches the DATs. Extracted ~33 WB files / ~7.7K LOC into `src/AcDream.{Core,App}/Rendering/Wb/`. Dropped project references to `WorldBuilder.Shared` + `Chorizite.OpenGLSDLBackend` from `AcDream.App.csproj` and `AcDream.Core.csproj`. `DefaultDatReaderWriter` eliminated; `DatCollection` is the only dat reader. `WbMeshAdapter` consumes it via `DatCollectionAdapter` (O-D7 fallback; `ObjectMeshManager` has 26 internal `_dats.*` call sites exceeding the 20-site inline-swap threshold). `references/WorldBuilder/` stays in-tree as read-reference. **Visual side-by-side passed**: Holtburg town, inn interior, dungeon all render identically to pre-O. `NOTICE.md` includes WB MIT attribution. Spec: [`docs/superpowers/specs/2026-05-21-phase-o-dat-path-unification-design.md`](../superpowers/specs/2026-05-21-phase-o-dat-path-unification-design.md). Audit: [`docs/superpowers/specs/2026-05-21-phase-o-t1-wb-audit.md`](../superpowers/specs/2026-05-21-phase-o-t1-wb-audit.md). Plan: [`docs/superpowers/plans/2026-05-21-phase-o-plan.md`](../superpowers/plans/2026-05-21-phase-o-plan.md). | Live ✓ |
 Plus polish that doesn't get its own phase number:
 - FlyCamera default speed lowered + Shift-to-boost
@ -110,227 +68,6 @@ Plus polish that doesn't get its own phase number:
 ## Phases ahead — agreed order
 ### Phase O — DatPath Unification — SHIPPED 2026-05-21
 **Tagline:** ONE thing touches the DATs.
 **Filed:** 2026-05-21. **Status:** SHIPPED. **Spec:** [`docs/superpowers/specs/2026-05-21-phase-o-dat-path-unification-design.md`](../superpowers/specs/2026-05-21-phase-o-dat-path-unification-design.md).
 See the shipped-table entry above for the full summary. Phase O is
 complete; M1.5 (indoor walking, paused for Phase O) resumes from
 the 2026-05-20 baseline.
 **Acceptance met** (full list in spec §6):
 - `dotnet build` + `dotnet test` green; ~1147 test count maintained.
 - Zero `using WorldBuilder.*` or `Chorizite.OpenGLSDLBackend.*` in `src/AcDream.*`.
 - `DefaultDatReaderWriter` referenced in zero places in our source.
 - Resident memory at `radius=4 + 50 entities visible`: **≥ 50 MB reduction** vs. pre-O main.
 - Visual side-by-side identical for the three reference scenes; user confirms.
 - `NOTICE.md` includes WB MIT attribution.
 **Non-goals** (explicit, spec §8): re-porting from retail decomp;
 performance optimization of extracted code; API cleanup. Verbatim
 copy + swap to `DatCollection` only. Refactors in follow-up phases.
 **After Phase O ships:** M1.5 resumes from its 2026-05-20 baseline
 with no code changes lost — M1.5 doesn't touch WB-extracted territory.
 ### Milestone M1.5 — "Indoor world feels right" (ACTIVE — Phase O shipped; resuming from 2026-05-20 baseline)
 The current top of the work order. M2 ("kill a drudge") is deferred until M1.5
 lands — drudges live in dungeons and the M2 demo target requires solid indoor
 navigation. Full milestone block in
 [`docs/plans/2026-05-12-milestones.md`](2026-05-12-milestones.md).
 **2026-05-30 — render-pipeline pivot.** Indoor *rendering* (the seamless in/out
 seam: the flap, missing/transparent walls, terrain bleed) is NO LONGER pursued via
 the WB-inherited two-pipe (inside/outside) split. That whole approach (Phase A8/A8.F,
 issue #103) is **abandoned**. Indoor rendering is now **Phase U** below. Phase A6
 (physics) and A7 (lighting) inside M1.5 are unaffected.
 #### Phase U — Unified retail-faithful render pipeline (NEW — supersedes A8/A8.F)
 **Decision (2026-05-30):** replace the two render paths (outdoor `Draw` +
 `RenderInsideOut` stencil, toggled on `cameraInsideBuilding`) with ONE pipeline driven
 by retail's portal-visibility view (`PView::ConstructView` / `ClipPortals` / `GetClip`;
 `CEnvCell::find_visible_child_cell`). The camera's cell is just the root of a recursive
 per-portal clip-region traversal; all visible cells (indoor + outdoor) draw in one pass.
 Seamless in/out **by construction** — no inside/outside branch. Modern code, retail
 behavior.
 - **Why:** the two-pipe split is a WB-editor inheritance, not a game-client design; you
  cannot make two pipes hand off seamlessly at a doorway. Retail never splits. The A8.F
  attempt to graft retail recursion onto the WB stencil failed its visual gate (#103).
 - **Keep:** WB mesh/dat pipeline (ObjectMeshManager/WbDrawDispatcher/terrain), the
  2026-05-30 camera-collision + physics work. **Salvage (verify):** the A8.F CPU
  clip-builder (PortalProjection/ScreenPolygonClip/ViewPolygon/PortalVisibilityBuilder —
  unit-test-correct). **Task 1:** delete the dead two-pipe code (RenderInsideOutAcdream,
  the cameraInsideBuilding branch, IndoorCellStencilPipeline, the ACDREAM_A8_INDOOR_BRANCH
  kill-switch) — audit first; some A8 commits fixed real bugs (BuildingId stamping, pool
  aliasing) that stay.
 - **Scope + next-session pickup:**
  [`docs/research/2026-05-30-unified-render-pipeline-decision-and-handoff.md`](../research/2026-05-30-unified-render-pipeline-decision-and-handoff.md).
  Start with `superpowers:brainstorming`; visual verification at Holtburg
  cottage/cellar/inn + a portal dungeon is the acceptance gate (unit tests did not
  catch #103).
 - **Camera-collision (shipped 2026-05-30, kept):** retail `SmartBox::update_viewer`
  swept-sphere spring arm (`CameraDiagnostics.CollideCamera`, `PhysicsCameraCollisionProbe`,
  `RetailChaseCamera` integration) + viewer/sight bypass of the 30-step transition cap.
  Specs: [`2026-05-29-a8f-camera-collision-design.md`](../superpowers/specs/2026-05-29-a8f-camera-collision-design.md).
 **Today's pre-M1.5 baseline** (2026-05-20 — committed in this
 session): A4 multi-cell BSP iteration (`691493e`), #89 sphere-overlap
 in CheckBuildingTransit (`7ac8f54`), #90 sphere-overlap stickiness in
 ResolveCellId (`4ca3596` — **WORKAROUND**, scheduled for removal in
 A6.P4), #91 indoor cell shadows in FindObjCollisions (`c0d8405`),
 #92 server cell id at player-mode entry (`23ab173`). 1147 + 8 baseline
 maintained. Holtburg inn + cottage interiors visually verified
 2026-05-20.
 #### Phase A6 — Indoor physics fidelity (cdb-driven)
 **Hypothesis:** Our `BSPQuery.FindCollisions` 6-path dispatcher (and
 its callers) produce collision responses that systematically diverge
 from retail's. Symptoms in different geometry (doorways, stairs,
 multi-Z, cellars, dungeons) share one underlying mechanism — most
 likely push-back distance / direction / CP synthesis.
 **Investigation methodology:** cdb-attached comparison. Toolchain
 documented in CLAUDE.md's "Retail debugger toolchain" section. Used
 successfully 2026-04-30 for the steep-roof case. Matching binaries
 (acclient.exe v11.4186) + PDB present.
 **Sub-pieces (slices):**
 - **✓ SHIPPED — A6.P1 — cdb probe spike** (2026-05-21). Built cdb
  scripts (`tools/cdb/a6-probe.cdb` v4 with PDB-verified offsets +
  hex-bits float output + Python decoder), PowerShell runner with
  ASCII encoding, PDB-match verification, and the new
  `[push-back]`/`[push-back-disp]`/`[push-back-cell]` acdream probe
  family (env `ACDREAM_PROBE_PUSH_BACK=1`). Captured 5 of 9 scenarios
  with paired retail+acdream traces (scen1 inn doorway, scen2 inn
  stairs, scen3 inn 2nd floor, scen4 cottage cellar, scen5 town
  network portal as substitute for Holtburg Sewer entry). Scen6-9
  cancelled — Holtburg Sewer doesn't exist on this server, and any
  substitute dungeon hits issue #95 (portal-graph visibility blowup)
  on portal entry, making physics-only analysis impossible. Five
  captures are sufficient evidence for A6.P2. Commits: infra Tasks
  1-14 + cdb iterations + scen1 capture (prior session); scen2-5
  captures (`a9a427f`, `297d1c5`, `4b5aebc`, `46c6e08`, `35d5c58`)
  + issue #95 filing (`5be784e`) (this session).
 - **✓ SHIPPED — A6.P2 — Analysis report** (2026-05-21, `184933d`).
  Output: [`docs/research/2026-05-21-a6-cdb-capture-findings.md`](../research/2026-05-21-a6-cdb-capture-findings.md).
  Four findings ready for A6.P3: Finding 2 (ContactPlane resynthesis
  blowup — 250× to ∞× more CP writes in acdream; primary M1.5 root
  cause) is HIGH severity and the highest-confidence single-cause
  fix candidate. Finding 1 (dispatcher entry frequency mismatch —
  4× to 281× fewer dispatcher entries in acdream) is likely a
  secondary effect of Finding 2's missing retention paths. Finding 3
  (indoor cell-resolver sling-out captured in scen4) — HIGH severity,
  separate fix surface in ResolveCellId/CheckBuildingTransit.
  Finding 4 (portal-graph visibility blowup discovered incidentally
  in scen5) — filed as issue #95, scope-adjacent, handled outside A6.
  Tables 1+2 (per-site push-back delta + path-frequency diff)
  deferred to optional A6.P1.5 (entry+exit BPs in cdb script);
  not blocking A6.P3. M1.5 symptom coverage matrix shows every
  in-scope physics symptom mapped to at least one finding.
 - **A6.P3 — Fix the BSP correction paths** (~3–5 days). Multi-slice.
  - **✓ SHIPPED — A6.P3 slice 1 — Indoor ContactPlane retention**
    (2026-05-21, commits `ba9655f` plan + `6b4be7f`/`c6bc2b9` T1
    research + `869edd9` T2 counter + `36975ef`/`a32f569` T3 test +
    `5aba071` T4 Mechanism B + `5f7722a`/`39fc037`/`bd5fe2e` T5 strip
    + `066568a` scen2 postfix proof + `<this commit>` T8 bookkeeping).
    Stripped `TryFindIndoorWalkablePlane` synthesis path from
    `Transition.FindEnvCollisions` indoor branch (matches retail's
    tiny `CEnvCell::find_env_collisions` shape at acclient_2013_pseudo_c.txt:309573).
    Added Mechanism B (LKCP restore) in `Transition.ValidateTransition`
    matching retail's pattern at acclient_2013_pseudo_c.txt:272565-272583.
    Per-unit-of-activity CP-write rate dropped 63×. **Unexpected win:
    stairs + cellar descent now WORK in acdream** (user happy-test
    confirmed). A6.P2 Finding 1 (dispatcher entry frequency mismatch)
    CLOSED as side-effect (dispatcher shape now retail-like). Finding 2
    PARTIALLY CLOSED — 99.3% of remaining cp-writes come from L622
    per-tick body-CP seed at `PhysicsEngine.ResolveWithTransition:622`
    (filed as issue #96 for slice 2).
  - **✓ SHIPPED — A6.P3 slice 2 — L622 seed investigation + no-op guard**
    (2026-05-22, commits `892019b` v1 + `f8d669b` v2). v1 removed the
    L622 seed entirely; broke BSP step_up at the last step of stairs
    (user happy-test surfaced the regression). v2 reverted v1 + added
    a no-op-if-unchanged guard inside `CollisionInfo.SetContactPlane`.
    **#96 PARTIALLY ADDRESSED — accepted as documented retail
    divergence.** The seed is load-bearing for `AdjustOffset`
    slope-projection on sub-step 1 which BSP step_up depends on.
    Matching retail would require deeper refactor (e.g. AdjustOffset
    fallback to body.ContactPlane). Guard is benign improvement;
    further #96 closure deferred.
  - **✓ SHIPPED — A6.P3 slice 3 — cell-resolver stickiness**
    (2026-05-22, commits `8898166` v1 + `3e140cf` v2). Added
    point-in stickiness check at top of `ResolveCellId`'s indoor
    branch. Cell-resolver ping-pong FULLY CLOSED (data: scen4 cellar
    capture shows 1 cell-transit vs 20+ pre-fix). **Outcomes:**
    Finding 3 (cell-resolver instability) closed. #90 workaround
    redundant (deferred A6.P4 removal). #97 phantom collisions
    hypothesis pending re-test (likely closed too). #98 cellar-up
    symptom PERSISTS but with NEW diagnosis (re-filed in #98 as BSP
    step-physics at cellar stair top — sloped step-face mis-handling,
    NOT cell-resolver).
  - **A6.P3 slice 4 (or A6.P4)? — BSP step-physics at cellar
    stair top (#98 new diagnosis)** (NEXT or DEFERRED). Investigate
    why step-down probe consumes all walk-interp at cellar stair top.
    Evidence: scen4 cottage_cellar_slice3v2 push-back trace. May
    require reading BSP step_up + step_down decomp + comparing to
    cellar stair geometry. Could be its own slice or merged into a
    broader A6.P4 cleanup phase.
  - Issue #95 (visibility blowup) NOT in A6.P3 scope — separate work
    surface.
 - **A6.P4 — Remove workarounds + visual verification** (~1 day after
  P3). Revert #90 sphere-overlap stickiness in
  `PhysicsEngine.ResolveCellId`. Delete `Transition.TryFindIndoorWalkablePlane`
  + its caller in `FindEnvCollisions`. Visual verification at Holtburg
  inn + cellar + (if #95 is also fixed by then) a dungeon. The
  original A6.P4 plan named "Holtburg Sewer end-to-end" as the
  acceptance walk; since the sewer doesn't exist, the M1.5 demo
  scenario needs an alternative (see milestones doc).
 #### Phase A7 — Indoor lighting fidelity (RenderDoc + retail-decomp driven)
 **Hypothesis layers (less mapped than physics):**
 - Per-cell environment-light tag association — indoor cells should
  inherit only their own env lights, not outdoor day-cycle.
 - Light visibility culling — what lights actually contribute to each
  cell's render.
 - Per-entity light direction transform — held-item-spotlight bug
  (#L-spotlight) is per-entity attribution gone wrong.
 - Static-stab atmospheric inheritance (#81).
 **Investigation methodology:** less existing infrastructure than
 physics. Requires:
 - New `[indoor-light]` probe (per-frame dump of active lights for the
  player's cell + each visible entity: position, color, attenuation,
  direction).
 - RenderDoc frame capture at the same 9 scenarios as A6.
 - Grep retail's `Render::lighting_*` family in
  `acclient_2013_pseudo_c.txt` to map per-cell light selection logic.
 **Sub-pieces (slices):**
 - **A7.L1 — Lighting probe spike** (~3–5 days). Build `[indoor-light]`
  probe. Capture baselines at all 9 scenarios. RenderDoc captures
  paired with each. Decomp study of retail's lighting selection.
 - **A7.L2 — Analysis report** (~1–2 days). Likely surfaces 2–4
  distinct bugs across the lighting issues.
 - **A7.L3 — Fix lighting paths** (~3–7 days). Wide variance because
  the surface area is unknown. Could touch indoor env-light parsing,
  `LightingHookSink`, WB rendering pipeline, shader uniforms.
 **M1.5 acceptance criterion (shared by A6 + A7):** Walk Holtburg Sewer
 end-to-end. Walls block (physics). Stairs work (physics). Items
 block (physics). Lighting reads correctly throughout (lighting).
 Cell transitions are smooth (physics). No regressions in M1 outdoor
 behavior. Estimated 17–26 days focused work, 3–5 weeks calendar.
 **Specs:** to be written 2026-05-20 (after milestone commit lands).
 ---
 ### Phase A — Foundation (in progress)
 **Goal:** walk across 10+ landblocks without crashes, without hitches at landblock boundaries, and without framerate cratering.
@ -340,7 +77,6 @@ behavior. Estimated 17–26 days focused work, 3–5 weeks calendar.
 - **✓ SHIPPED — A.2 — Frustum culling.** Per-landblock AABB test (Gribb-Hartmann plane extraction + positive-vertex AABB test) in both `TerrainRenderer.Draw` and `StaticMeshRenderer.Draw`. Per-entity culling deferred. LOD deferred to Phase C. Performance overlay in window title shows FPS, frame time, visible/total landblock ratio, entity count, animated count. ~160fps uncapped at 5×5 radius.
 - **✓ SHIPPED — A.3 — Background net receive thread.** Dedicated daemon thread continuously pulls raw UDP datagrams from the kernel buffer into a `Channel<byte[]>`. Render thread's `Tick()` drains the channel. All decode, fragment assembly, ISAAC crypto, event dispatch, and ack-sending remain on the render thread — minimal change that prevents packet drops during frame stalls. Thread starts after `EnterWorld()` completes; `PumpOnce()` during handshake still reads the socket directly.
 - **A.4 — Async dat decoding.** Folded into the streaming worker — it's the worker's read path, not a separate subsystem. Called out here because regressions in dat caching could land on this surface.
 - **✓ SHIPPED — A.5 — Two-tier streaming + horizon LOD.** Shipped 2026-05-10. See shipped table above for full description. Plan archived at `docs/superpowers/plans/2026-05-09-phase-a5-two-tier-streaming.md`.
 **Acceptance:**
 - Walk across 10+ landblocks in any direction, no crashes, no empty voids.
@ -377,10 +113,6 @@ behavior. Estimated 17–26 days focused work, 3–5 weeks calendar.
 **Sub-pieces:**
 - **✓ SHIPPED — C.1 — VFX / particle system + sky-pass refinements.** Retail-faithful `ParticleEmitterInfo` runtime + 13-type motion integrator port + `PhysicsScript` runner + instanced billboard renderer with material-derived blend + global back-to-front sort + AttachLocal live-parent follow. Sky-pass refinements: Translucent+ClipMap alpha-blend, raw-Additive fog-skip, per-keyframe SkyObjectReplace divide-by-100, sampler-object wrap selection (ported from WorldBuilder), gated post-scene Z-offset. Sky-PES disabled by default — named-retail decomp proves `GameSky` drops `pes_id`. **Portal swirls, chimney smoke, fireplace flames** still need a Phase C.1.5 follow-up to wire entity-attached emitters to retail effect IDs (the data layer is ready; only the wiring is deferred). Lands as merge `feat(vfx): Phase C.1 — PES particle renderer + post-review fixes` (`ec1bbb4`) + `refactor(sky): replace per-frame wrap-mode mutation with persistent samplers` (`3d21c13`).
 - **C.1.5 — entity-attached PES wiring (sliced).** Three sub-slices wiring `PhysicsScript` / `DefaultScript` dispatch to the entity lifecycle so portals, chimneys, fireplaces, and sky effects animate per retail:
    - **✓ SHIPPED — C.1.5a (portals)** — 2026-05-11 (merge `88bda12`). `EntityScriptActivator` fires `Setup.DefaultScript` on every server-spawned `WorldEntity` via `PhysicsScriptRunner`. Visual-verified at Holtburg Town network portal. Surfaced known limitation as issue #56 (per-part transform handling) — addressed in C.1.5b. Plan archived at [`docs/superpowers/plans/2026-05-12-phase-c1.5a-portals.md`](../superpowers/plans/2026-05-12-phase-c1.5a-portals.md).
    - **✓ SHIPPED — C.1.5b (per-part transforms + EnvCell statics)** — 2026-05-12. Closes #56. `SetupPartTransforms.Compute` + `ParticleHookSink.SetEntityPartTransforms` + `SpawnFromHook` part-transform application — multi-emitter scripts now distribute across mesh parts. `EntityScriptActivator` `ServerGuid==0` guard relaxed (keys by `entity.Id` when ServerGuid is zero) + 4 new `GpuWorldState` fire-sites pick up dat-hydrated entities (EnvCell statics + exterior stabs) — fireplaces and chimneys now fire their `DefaultScript` automatically. Reality discovery during design: EnvCell statics are already hydrated as `WorldEntity` items by `BuildInteriorEntitiesForStreaming`, so no synthetic-ID scheme or separate walker was needed. Visual-verified at Holtburg portal + Inn fireplace + cottage chimney + spell cast. Plan archived at [`docs/superpowers/plans/2026-05-13-phase-c1.5b.md`](../superpowers/plans/2026-05-13-phase-c1.5b.md).
    - **PLANNED — C.1.5c (sky-PES dispatch chain).** Promoted from former issue #36 (2026-05-11 triage). Ports retail's persistent-emitter creation on celestial / sky objects + the PES timeline driver (`CallPESHook::Execute` → `CPhysicsObj::CallPES` → `create_particle_emitter`) that drives them ~150×/min. Decomp anchors + live-trace evidence + 6-step impl outline in closed issue [#36](../ISSUES.md#36). **Closes #2 (lightning), #28 (aurora), #29 (cloud thinness) when shipped.** Does NOT close #4 (sky horizon-glow fog) — that's shader work, not PES.
 - **C.2 — Dynamic point lights.** Fireplaces and lamps need local lighting; small upgrade to the mesh shader to accumulate N (e.g., 4) nearest point lights per draw. Uniform-buffer or UBO-friendly layout.
 - **C.3 — Palette range tuning.** Small per-range offset/length tweaks to match retail skin/hair/eye colors. Mostly diff and verify work, no architecture change.
 - **C.4 — Double-sided translucent polys.** Edge case left by Phase 9.2: neg-side translucent polys are culled because cull is always BACK. Fix by tracking per-sub-mesh `CullMode` and flipping GL state per draw (or drawing twice with opposite cull). Minor.
@ -424,19 +156,10 @@ behavior. Estimated 17–26 days focused work, 3–5 weeks calendar.
 **Sub-pieces:**
 - **D.1 — 2D ortho overlay + font rendering.** ✅ SHIPPED 2026-04-17 as the dev-facing debug overlay (StbTrueTypeSharp system-font atlas + `TextRenderer` + `DebugOverlay`).
 - **✓ SHIPPED — D.2a — ImGui scaffold + `AcDream.UI.Abstractions` layer.** Shipped 2026-04-25. Wires ImGui as the short-term backend behind `ACDREAM_DEVTOOLS=1`. Defines `IPanel` / `IPanelHost` / `IPanelRenderer` / `ICommandBus` + the first ViewModel (`VitalsVM`) in the new `AcDream.UI.Abstractions` project. First real panel: `VitalsPanel` reading HP from `CombatState.GetHealthPercent`. **Backend pivoted Hexa.NET.ImGui → ImGui.NET + `Silk.NET.OpenGL.Extensions.ImGui` during integration** — Hexa's native OpenGL3 backend does its own GL function resolution via GLFW/SDL and crashed with `0xC0000005` in `ImGuiImplOpenGL3.InitNative` against Silk.NET (no GLFW/SDL present). The Silk.NET extension is purpose-built for this scenario and is the `ImGui.NET` mitigation path that `docs/plans/2026-04-24-ui-framework.md` already called out as a "one-morning operation". Stam/Mana return `float?` null in D.2a because absolute values need `LocalPlayerState` + `PlayerDescription (0x0013)` parsing (filed post-D.2a). 11 new `AcDream.UI.Abstractions.Tests` green.
- **✓ SHIPPED — D.2b — Custom retail-look backend (Spec 1: markup engine + first panel).** Shipped 2026-06-14 (`626d06e`→`019350f`). Wired the dormant `UiHost`/`UiElement` tree into `GameWindow` (`ACDREAM_RETAIL_UI=1`) and built the **Approach-C markup engine**: `MarkupDocument` (XML → `UiElement` subtree, `{Binding}` reflection) + `ControlsIni` stylesheet loader + an `IUiRegistry` plugin UI surface (plugins ship markup + a binding, drained into the same `UiRoot`). First retail-faithful panel: a markup-driven Vitals window (`vitals.xml`) — 8-piece dat-sprite frame (`UiNineSlicePanel`) + three `UiMeter` bars (red/gold/blue + cur/max numbers) bound to `VitalsVM`, rendering live over the 3D world and coexisting with the ImGui devtools path. Retired divergence TS-30, added IA-15. Spec `docs/superpowers/specs/2026-06-14-d2b-retail-panel-frame-design.md`; plan `docs/superpowers/plans/2026-06-14-d2b-retail-panel-frame-plan.md`. NOTE the prove-out corrected two stale "facts": retail vitals are **bars not orbs**, stamina is **gold not cyan**. **Remaining: D.3 (AcFont — using the stb stopgap for now) + the glassy gradient bar sprite / brightness tune (polish); input integration (movable/clickable windows — the `UiRoot` drag/click machinery exists but isn't bridged to the Phase-K dispatcher yet); and the rest of the panels (D.5).**
+- **D.2b — Custom retail-look backend.** Implements the same `IPanel` / `IPanelRenderer` contracts using a custom retained-mode toolkit sourced from retail dat assets. Requires D.2a shipped. Panels get reskinned one at a time; ImGui stays as the `ACDREAM_DEVTOOLS=1` overlay forever. The original 2026-04-17 scaffold research (`UiRoot` / `UiElement` / `UiPanel` / `UiHost` + retail event codes + focus / drag-drop state machine + `WorldMouseFallThrough`) is the implementation foundation here — see `docs/research/retail-ui/`.
 - **✓ SHIPPED — D.2b LayoutDesc importer (Plan 1 + default flip).** Plan 1 shipped 2026-06-15. *Retroactive registration — the spec requested this phase but it was not pre-registered before implementation.* Data-driven vitals window from `LayoutDesc 0x2100006C`: `LayoutImporter` resolves `BaseElement`/`BaseLayoutId` inheritance, walks the `ElementDesc` tree, and builds a live `UiElement` tree via `DatWidgetFactory` (Type 7 → `UiMeter`; all others → `UiDatElement` generic renderer). `VitalsController` binds live HP/Stamina/Mana by element id (mirrors retail `gmVitalsUI`). A/B visual gate **PASSED**: pixel-identical to the hand-authored window. **Default flip shipped 2026-06-15 (`bf77a23`):** the importer is now the default vitals window at `ACDREAM_RETAIL_UI=1`; the hand-authored `vitals.xml` and the `ACDREAM_RETAIL_UI_IMPORTER` flag were retired (`vitals.xml` recoverable from git history). The window is movable (Anchors=None + Draggable) AND horizontally resizable (Resizable/ResizeX, `8aa643f`): the dat edge-anchors reflow the pieces on width change per retail `UIElement::UpdateForParentSizeChange @0x00462640` (an earlier "fixed-size" note was wrong — inverted edge-flag reading, corrected; stretch is `RightEdge==1`). Faithful grip/dragbar-*driven* drag/resize INPUT is Plan 2. Post-flip number-render fixes (`43064ba`, `34243f2`): submission-order sprite draw (stamina/mana numbers had been overpainted by their own bars) + glyph pixel-snap (sharp at all resize widths). `MarkupDocument`/`UiNineSlicePanel` remain for the chat window + plugin panels. Spec: `docs/superpowers/specs/2026-06-15-layoutdesc-importer-design.md`; plan: `docs/superpowers/plans/2026-06-15-layoutdesc-importer.md`.
 - **✓ SHIPPED — D.2b LayoutDesc importer (Plan 2 — chat-window re-drive).** Shipped 2026-06-15. `GameWindow`'s hand-authored chat block (`UiNineSlicePanel` + inline `UiChatView`) replaced by `ChatWindowController.Bind(LayoutDesc 0x21000006, …)` — the same importer path as vitals. `ChatWindowController` places `UiChatView` (transcript) + `UiChatInput` (text entry + on-submit) + `UiChatScrollbar` (scrollbar thumb) + `UiChannelMenu` (channel selector) inside the dat-authored chrome; dead local statics `BuildRetailChatLines`/`RetailChatColor` deleted from `GameWindow` (moved into the controller). Wired to `_commandBus` (same `LiveCommandBus` as the ImGui `ChatPanel`) so type+Enter dispatches `SendChatCmd` server-ward. Transcript keyboard set from `_uiHost.Keyboard` for Ctrl+C/Ctrl+A. 392 tests green. Added divergence rows AD-28 / AP-38–40 / TS-30–31; updated IA-15.
 - **✓ SHIPPED — D.2b LayoutDesc importer (Plan 2 — widget generalization).** Shipped 2026-06-16 (`b7f7e2b`→`89626cd`). The hand-named chat widgets became GENERIC, Type-registered widgets built by `DatWidgetFactory` (`1→UiButton`, `6→UiMenu`, `7→UiMeter`, `11→UiScrollbar`, `12→UiText`); `UiField` (editable) ships controller-placed. `ChatWindowController` + `VitalsController` collapsed to thin `gm*UI::PostInit`-style find-by-id binders — this is the reusable toolkit + assembly pattern the future inventory/vendor/spell-bar windows build on. New `UiElement.ConsumesDatChildren` leaf-widget rule: behavioral widgets reproduce their dat sub-elements procedurally, so the importer must not build their children (an invisible Menu label child was swallowing the button click → dropdown wouldn't open). **Type 3 deliberately NOT registered** → `UiField` (acdream's Type-3 elements are inert sprite-bearing chrome/containers → stay `UiDatElement`; a subagent's Type-3→`UiField` registration was reverted — it blanked the vitals bevel + masked the regression by weakening a test). The editable input resolves to Type 12 → controller-placed `UiField` (Variant B). Vitals numbers rewired to a centered `UiText` (Task 8) — `UiText.Centered` reuses the meter's former centering formula, pixel-identical. Both visual gates (chat + vitals) **user-confirmed**; 404 tests green; new `chat_21000006.json` golden fixture. Amended AP-37, narrowed AP-41, added AP-42. Spec/plan: `docs/superpowers/{specs,plans}/2026-06-16-d2b-widget-generalization*.md`.
 - **D.3 — AcFont from portal.dat.** Replace stb_truetype system font with retail `Font` DBObjs (`0x40000000..0x40000FFF`) baked from `RenderSurface` source sheets — see research slice 03 §4. Preserves retail visual identity. **(D.2b dependency — needs the custom renderer.)**
- **✓ SHIPPED — D.4 — Dat sprites + 9-slice panel backgrounds.** Shipped 2026-06-14 with D.2b. `TextureCache.GetOrUploadRenderSurface(id, out w, out h)` decodes `RenderSurface` (`0x06xxxxxx`) **directly** (not via the Surface→SurfaceTexture chain — the prove-out finding) → GL `Texture2D`; `DrawSprite` (explicit UV-rect, per-texture batch) added to `TextRenderer` + `UiRenderContext` + a `uUseTexture=2` RGBA frag branch; `UiNineSlicePanel` composes the universal 8-piece bevel (corners `0x060074C3..C6`, edges `0x060074BF/C0/C1/C2`, center `0x06004CC2`). Remaining art polish: the glassy gradient bar fill sprite (D.2b polish).
+- **D.4 — Dat sprites + 9-slice panel backgrounds.** Load `RenderSurface` (`0x06xxxxxx`) as GL textures; add `DrawSprite` to `UiRenderContext`. Enables retail panel art. **(D.2b dependency.)**
 - **D.5 — Core panels.** Attributes (`chunk_00470000.c:FUN_0047ba70`), Skills (same), Paperdoll (`chunk_004A0000.c:FUN_004A5200`), Inventory, Spellbook (`chunk_004C0000.c`), Fellowship, Allegiance. Each uses the port sketches in slice 05. **(Targets `AcDream.UI.Abstractions` — ships with D.2a using ImGui-rendered widgets; reskinned by D.2b.)** The *chat* panel originally listed under D.5 shipped early in Phase I (I.4 input + I.7 combat translator superseded the chat-panel design here); this entry now covers Attributes / Skills / Paperdoll / Inventory / Spellbook / Fellowship / Allegiance only.
 - **✓ SHIPPED — D.5.1 — Toolbar (action bar).** Shipped 2026-06-16/17 (`30b28c2`→`0e7a083`, branch claude/hopeful-maxwell-214a12). First data-driven *game* panel: `gmToolbarUI` (`LayoutDesc 0x21000016`) — 18 shortcut slots from the persisted `PlayerDescription` SHORTCUT block, real **composited** item icons (opaque type-default underlay via the `EnumIDMap 0x10000004` resolve), **occupancy-gated slot numbers 1–9** (occupied = dark-box peace/war `0x10000042/43`; empty = background `0x1000005e` from cell composite `0x10000341`), **click-to-use** (`ItemHolder::UseObject` → `0x0036`), **peace/war stance** indicator live-wired to `CombatState`, **movable**, and a **chrome frame** (UiNineSlicePanel drawn over content via the new `UiElement.OnDrawAfterChildren` hook). New shared widgets `UiItemSlot` (`UIElement_UIItem` 0x10000032, procedural leaf) + `UiItemList` (`UIElement_ItemList` 0x10000031, factory branch) + `IconComposer` (CPU layered composite). `CreateObject.TryParse` extended to the full ACE-order weenie-header tail to capture `IconId`/`IconOverlay`/`IconUnderlay` → `ItemRepository.EnrichItem` → re-render. Spec/plan `docs/superpowers/{specs,plans}/2026-06-16-d2b-toolbar-phase1*.md`; research drop `docs/research/2026-06-16-*deep-dive.md` + synthesis. Divergence IA-16/IA-17 added. **User-confirmed** (numbers, icons, frame). Per-task spec+code-review throughout.
 - **✓ SHIPPED — D.5.2 — Stateful item-icon system.** Shipped 2026-06-17/18 (`419c3ac`..`fb288ad`, branch claude/hopeful-maxwell-214a12; **visually verified on a live Coldeve server**). Faithful retail icon composite (`IconData::RenderIcons` @0x0058d180): (1) `UiEffects` bitfield captured from the `CreateObject` weenie header (was discarded) → `ItemInstance.Effects`; (2) `IconComposer.GetIcon` rewritten as a 2-stage composite — Stage 1 = drag icon (base + custom overlay) + the effect treatment, Stage 2 = type-default underlay + custom underlay + drag. The effect treatment ports the **surface overload** of `SurfaceWindow::ReplaceColor` (`0x004415b0`): the textured effect tile (`EnumIDMap 0x10000005` by `LowestSetBit(effects)+1`, fallback `0x21` solid-black) is copied **per-pixel** into the icon's pure-white pixels — magical items take the tile's GRADIENT hue, mundane items go black; (3) `PublicUpdatePropertyInt (0x02CE)` parser + `WorldSession.ObjectIntPropertyUpdated` event + `GameWindow` subscription → `ItemRepository.UpdateIntProperty` → icon re-composites live. **Appraise (`0x00C9`) carries NO icon data** (ACE proof: `Icon`/`IconOverlay`/`IconUnderlay`/`UiEffects` all lack `[AssessmentProperty]`) — dropped as a no-op. **Two visual-verification fixes landed after the subagent build:** the `effects==0` recolor MUST run (mundane white edges → black, `40c97a5`) and the tint is a per-pixel GRADIENT not a flat color (the surface overload, `fb288ad`) — both confirmed via clean Ghidra + named decomp. Divergence: IA-16 retired; IA-18 (per-pixel surface-copy anti-regression) + AP-45 (0x02CE sequence) added; **AP-43/AP-44 retired by the visual fixes**. Spec/plan/research: `docs/superpowers/{specs,plans}/2026-06-17-d2b-stateful-icon*.md`, `docs/research/2026-06-17-stateful-icon-RESOLVED.md`.
 - **D.5 remaining — sub-phase ledger.** D.5.1 (toolbar + the `UiItemSlot`/`UiItemList`/`IconComposer` spine) ✅, D.5.2 (stateful icons) ✅, and D.5.4 (client object/item data model) ✅ are shipped. Build order from here: **(b) finish the bar: D.5.3 selected-object + spell shortcuts → (c) window manager → (d) core panels.** Each ☐ below gets its own brainstorm → spec → plan.
 - **✓ SHIPPED — D.5.4 — Client object/item data model (foundation).** Shipped 2026-06-18 (`b506f53`..`a33e897`, 11 commits). Renamed `ItemRepository`→`ClientObjectTable` / `ItemInstance`→`ClientObject`; broadened the table to hold EVERY server object (retail `weenie_object_table` shape). `CreateObject` is now the canonical merge-upsert (`ClientObjectTable.Ingest`, retail `SetWeenieDesc` semantics) via a new Core.Net `ObjectTableWiring` (off GameWindow); `DeleteObject` evicts; `PlayerDescription` is a membership manifest (`RecordMembership`); live container-membership index (`GetContents`, retail `object_inventory_table`). `_liveEntityInfoByGuid` retired (selection/describe resolve from the one table). Root fix: the old enrich-existing-only `EnrichItem` dropped `CreateObject`s for items with no `PlayerDescription` stub — live-Coldeve 4/6 hotbar slots blank; items are now created, not dropped. **Crux resolved:** retail is TWO tables (`object_table` + `weenie_object_table`), NOT one — acdream's `WorldEntity` (3D system) + `ClientObjectTable` (data/UI) split was already architecturally faithful; the fix was the ingestion path, not a table unification. 2671 tests green.
 - **☐ D.5.3 — Toolbar selected-object display (issue #140) + spell shortcuts.** Wire the B.4 `WorldPicker`/selection state → the two hidden meters (`0x100001A1` health / `0x100001A2` mana) + the stack slider (`0x100001A4`) + the object-name line, so the bar shows the player's currently-selected world object. Plus **spell shortcuts** — pinned *spells* (vs items) don't render their glyphs yet (`ToolbarController.Populate` skips `ObjectGuid==0`). Together these finish "the bar." (Click-to-use + the peace/war stance indicator landed in D.5.1.)
 - **☐ D.5.5+ — Core panels.** Inventory (`gmInventoryUI`/`gmBackpackUI`), equipment/paperdoll (`gmPaperDollUI`/`gm3DItemsUI` + the `UiViewport` 3D doll), vendor, trade, spellbook. Research drop done (`docs/research/2026-06-16-*`). Depends on **D.5.4** (data model) + the item-slot/list/icon spine (D.5.1/D.5.2) + the **window manager** (Plan 2: open/close/z-order/persist + faithful grip/dragbar drag-resize) + the drag-drop spine wired (`UiRoot` has the chain; the per-cell accept/drop hooks are still stubs in `UiField`). Also deferred from D.5.1: drag/reorder + the `AddShortcut`/`RemoveShortcut` mutate wire.
 - **D.6 — HUD.** Vital orbs (scissor-rect partial fill, dat sprites `0x060013B2`), radar (`0x06001388` / `0x06004CC1`, 1.18× range factor), compass strip (scrolling U), target name plate, damage floaters, selection indicator. See slice 06. **(Targets `AcDream.UI.Abstractions` — ships with D.2a; reskinned by D.2b.)** Phase I.2 retired the StbTrueTypeSharp `DebugOverlay` but kept `TextRenderer` + `BitmapFont` alive specifically for D.6's world-space HUD elements (damage floaters, name plates) — they need raw GL text drawing that ImGui can't reach into the 3D scene.
 - **D.7 — Cursor manager.** OS + dat-sourced custom cursors (`FUN_0043c1c0` GDI HCURSOR builder pattern from slice 03). **(D.2b dependency.)**
 - ~~**D.8 — Sound.**~~ **Superseded — shipped as Phase E.2** (`SoundTable`/`Sound` dat decode, OpenAL 16-voice engine, per-entity 3D positional audio via `AudioHookSink`). Entry kept here for history; see the shipped table.
@ -472,7 +195,6 @@ Research: R1 + R2 + R6 + R8 + UI slices 04/05.
 - **F.3 — Combat math + damage flow.** Damage formula, per-body-part AL, crit, hit-chance sigmoid. Server broadcasts damage events; client displays + HP bar. See `r02-combat-system.md` + `src/AcDream.Core/Combat/`.
 - **F.4 — Spell cast state machine.** `SpellCastStateMachine` + active buff tracking. Buffs + recalls first, projectile spells later. Fizzle sigmoid + mana conversion. See `r01-spell-system.md` + `src/AcDream.Core/Spells/`.
 - **F.5 — Core panels.** Attributes / Skills / Paperdoll / Inventory / Spellbook — using the retail-ui framework from Phase D.2. See `05-panels.md` under retail-ui. **(Targets `AcDream.UI.Abstractions`; unblocked by D.2a — ships with ImGui widgets — and reskinned when D.2b lands.)**
  - **F.5a — Visible-at-login dev panels.** First deliverable on top of #13 (PD trailer parser shipped 2026-05-10): wire `PlayerDescriptionParser.Parsed.{Inventory, Equipped, Shortcuts, HotbarSpells, DesiredComps, Options1, Options2, SpellbookFilters}` and `ItemRepository.Items` into minimal ImGui dev panels under `ACDREAM_DEVTOOLS=1` so the parsed data is observable in-game without a real retail-skin panel. Establishes the binding pattern (`AcDream.UI.Abstractions` ViewModels → ImGui renderer) the eventual D.2b retail-skinned panels reuse. Acceptance: log in, open dev overlay, see your inventory list / hotbars / shortcuts / character-options bitfields populated from the live PD message. **Targets:** `src/AcDream.UI.Abstractions/` (ViewModels) + `src/AcDream.App/UI/ImGui/` (panels). Spec to brainstorm before code.
 **Acceptance:** equip a weapon, swing at a monster, see damage numbers, buff yourself, recall to the lifestone.
@ -482,8 +204,7 @@ Research: R9 + R12 + R13.
 - **✓ SHIPPED — G.1 — Sky + weather + day-night.** Deterministic client-side from Portal Year time. Sky dome geometry + keyframe gradients + rain/snow particles. See `r12-weather-daynight.md`. Full data + visual stack shipped: Region dat loader, keyframe interp, WeatherSystem with 5-kind PDF + transitions + storm flashes, WorldSession→WorldTimeService sync via ConnectRequest+TimeSync, SkyRenderer with sky-object arcs + UV scroll, rain/snow billboard renderer, F7/F10 debug cycle keys.
 - **✓ SHIPPED — G.2 — Dynamic lighting.** 8-light D3D-style fixed pipeline. Hard-cutoff at Range, no attenuation inside. Cell ambient. Shader UBO per frame. See `r13-dynamic-lighting.md`. SceneLightingUbo std140 at binding=1 feeds terrain + mesh + mesh_instanced + sky shaders. LightingHookSink auto-registers Setup.Lights at entity stream-in, flips IsLit on SetLightHook, unregisters on landblock unload.
- **Indoor portal-based cell tracking (follow-up to Indoor walking Phase 1 / issue #87).** Replace `PhysicsDataCache.TryFindContainingCell` AABB containment with retail's `CObjMaint::HandleObjectEnterCell` portal traversal. When the player crosses a cell portal boundary, `CellId` propagates through the `CEnvCell` portal connectivity graph. Prerequisite for wall collision from outside (#85) and the remaining #84 threshold symptom. PDB symbols and `acclient.h` `CCellStructure` refs are in place (see #87). **Unblocks G.3.**
+- **G.3 — Dungeon streaming + portal space.** `EnvCellStreamer`, portal-visibility BFS, `PlayerTeleport (0xF751)` handling with `LoginComplete` re-send, "pink bubble" loading state. **Blocked on L.2e** for trustworthy `cell_bsp`, indoor/outdoor portal transit, adjacent-cell ownership, and building entry/exit collision boundaries. See `r09-dungeon-portal-space.md`.
 - **G.3 — Dungeon streaming + portal space.** `EnvCellStreamer`, portal-visibility BFS, `PlayerTeleport (0xF751)` handling with `LoginComplete` re-send, "pink bubble" loading state. **Blocked on indoor portal-based cell tracking above** (and previously on L.2e) for trustworthy indoor/outdoor portal transit, adjacent-cell ownership, and building entry/exit collision boundaries. See `r09-dungeon-portal-space.md`.
 **Acceptance:** walk outside at dusk, see the sky gradient + sun moving; enter a torch-lit dungeon via portal; leave back to daylight.
@ -703,40 +424,19 @@ EchoRequest/EchoResponse handling, runtime ping/timeout policy, and a typed
 protocol/action layer. These gaps will become expensive as movement, dungeons,
 inventory, combat, and plugins depend on stable packet semantics.
-**Plan of record:** Detailed design spec at
+**Plan of record:** create
-[`docs/superpowers/specs/2026-05-10-phase-m-network-stack-design.md`](../superpowers/specs/2026-05-10-phase-m-network-stack-design.md)
+`docs/superpowers/specs/2026-05-02-network-stack-conformance.md` before
-(supersedes the planned-but-never-written `2026-05-02-network-stack-conformance.md`
+implementation starts. Treat holtburger as the client-behavior oracle for this
-the original entry referenced). The spec defines: **Bar C** ("wireable on demand")
+phase; cross-check wire details against named retail, ACE, Chorizite, and AC2D
-as the completeness target; a **three-layer architecture** (`INetTransport` /
+before porting.
 `IReliableSession` / `IGameProtocol`) with `WorldSession` as a thin behavior
 consumer on top; a **worktree-branch big-bang** migration model on
 `claude/phase-m-network-stack` with weekly rebase cadence and single-merge ship;
 per-sub-phase entry/exit gates with hour estimates; conformance test plan
 (golden vectors + live capture replay + live ACE smoke); risk register; and a
 **256-hour / ~6.4-week single-developer cost estimate** (4–6 weeks calendar
 with subagent parallelization on M.1 and M.6). Treat holtburger as the
 client-behavior oracle, ACE as server-outbound authority, named retail decomp
 as wire-format ground truth.
-**2026-05-10 update:** holtburger pulled to `629695a` (+237 commits since
+**Sub-lanes:**
-last audit). First parity-pass at
+- **M.1 — Audit & parity map.** Produce a source-by-source comparison of
-[`docs/research/2026-05-10-holtburger-network-stack-study.md`](../research/2026-05-10-holtburger-network-stack-study.md);
+  acdream `AcDream.Core.Net` and holtburger `holtburger-session`,
-formal opcode coverage matrix (M.1's main deliverable) under construction
+  `holtburger-protocol`, and `holtburger-core` networking code. Inventory each
-at `docs/research/2026-05-10-phase-m-opcode-matrix.md` via parallel
+  packet flag, optional header, session transition, control packet, fragment
-class-by-class agent dispatch. Most relevant recent holtburger commits:
+  path, game message, and game action. Mark each as `parity`, `partial`,
-`99974cc` (session crate split + retransmit core), `403bc98` (port-switch
+  `missing`, or `intentional divergence`.
 race), `336cbad` (turning + locomotion fix), `797aece` (disconnect
 carries client_id). Six "Tier 1" quick-wins identified by the study
 (originally tracked as M.0) are folded into M.3 / M.4 / M.6 per the
 spec — they no longer ship as a separate sub-phase.
 **Sub-lanes:** *(brief summary; the spec has full entry/exit criteria,
 conformance gates, and hour estimates for each.)*
 - **M.1 — Audit & opcode matrix.** Build the per-opcode coverage table
  citing holtburger / ACE / named retail / acdream-today / Phase M target.
  Status: parity-pass done; matrix construction in flight via per-class
  agent dispatch (transport flags + optional headers, GameMessages,
  GameEvents, GameActions). 16h.
 - **M.2 — Layer extraction.** Split the low-level stack under `WorldSession`
  into testable components: `INetTransport`, `PacketCodec`,
  `ReliablePacketSession`, `FragmentSession`, `GameMessageSession`, and the
@ -798,227 +498,6 @@ conformance gates, and hour estimates for each.)*
 ---
 ### Phase N — WorldBuilder Rendering Migration
 **Goal:** Stop re-porting AC-specific rendering / dat-handling
 algorithms. Depend on a fork of `Chorizite/WorldBuilder` (MIT) for
 terrain, scenery, static objects, EnvCells, portals, sky, particles,
 texture decoding, mesh extraction, and visibility. Acdream keeps its
 own network, physics, animation, motion, UI, plugin, audio, chat
 layers (those aren't in WB).
 **Why now (2026-05-08):** the scenery edge-vertex bug at landblock
 `0xA9B1` was the third subtle porting bug in a quarter (after the
 triangle-Z bug and the hover-over-terrain bug). Even when our code
 looked byte-identical to WB's, our output diverged. WB renders the
 world correctly; the cost of "we re-port retail algorithms" is now
 higher than "we depend on WB's tested port."
 **Design + inventory:**
 - `docs/architecture/worldbuilder-inventory.md` — full taxonomy of
  what WB has and what we keep porting ourselves.
 - `docs/superpowers/specs/2026-05-08-phase-n-worldbuilder-migration-design.md` —
  parent design doc.
 - `docs/superpowers/specs/2026-05-08-phase-n1-scenery-via-wb-helpers-design.md` —
  N.1 detailed design.
 **Integration model:** fork at
 `https://github.com/eriknihlen/WorldBuilder` (already created), git
 submodule replacing `references/WorldBuilder/` snapshot, project
 references in our solution. Long-lived `acdream` branch in the fork
 for our deletions/additions; merge upstream `master` periodically.
 **Lessons from N.1 (apply to N.2-N.10):**
 1. **Per-helper conformance tests work.** The N.1 conformance test caught a
   ~180° rotation bug in our retail port that had been silently wrong
   forever. Write the conformance test BEFORE the substitution in each
   sub-phase.
 2. **ACME ≠ Chorizite/WorldBuilder.** ACME is a downstream fork of WB with
   additional retail-faithful filters that upstream WB (our submodule)
   doesn't have. When a visual discrepancy appears, check ACME's source
   (`references/WorldBuilder-ACME-Edition/`) for delta filters BEFORE
   investigating retail decomp directly. ACME's deltas tend to come as
   coherent units — porting one filter without its companions can
   over-suppress.
 3. **"Whackamole" is the warning sign.** If a phase generates 3+ visual
   regressions on default-on, stop, accept the cosmetic deltas as
   ISSUES.md entries, ship the migration. Bugs we leave behind are
   debuggable; bugs we never ship are forgotten.
 4. **Subagent-driven execution holds up at this scope.** Fresh subagent
   per task with the full task text inline keeps quality high without
   polluting the controller's context. Each task should be self-contained
   enough that a subagent without session history can complete it.
 **Sub-phases (strangler-fig with feature flags):**
 - **✓ SHIPPED — N.0 — Setup.** Shipped 2026-05-08 (commit `c8782c9`).
  WorldBuilder fork at `github.com/eriknihlen/WorldBuilder.git` registered
  as git submodule at `references/WorldBuilder/` tracking the `acdream`
  branch. `AcDream.Core.csproj` references `WorldBuilder.Shared` +
  `Chorizite.OpenGLSDLBackend`. Build green, all 28 scenery/terrain tests
  passing.
 - **✓ SHIPPED — N.1 — Scenery algorithm calls.** Shipped 2026-05-08.
  Replaced `IsOnRoad` / `DisplaceObject` / slope-normal calc / rotation /
  scale inside `SceneryGenerator.Generate()` with calls to WB's
  `SceneryHelpers` + `TerrainUtils`. Adapter `WbSceneryAdapter` produces
  `TerrainEntry[]`. Visual verification at Holtburg confirmed Issue #49's
  previously missing edge-vertex trees still visible after the migration;
  rotation bug fixed (our retail port's `yawDeg = -(450-degrees)%360`
  formula was ~180° off from retail's actual `Frame::set_heading` atan2
  round-trip). One known cosmetic difference filed in ISSUES.md
  (road-edge tree at landblock 0xA9B1).
 - **N.2 — Terrain math helpers.** ⚠️ **Blocked on N.5 — do not attempt
  in isolation.** Originally scoped as a 1-2 day low-risk substitution
  of `TerrainSurface.SampleZ` / `SampleSurface` / `SampleSurfacePolygon`
  with WB's `TerrainUtils.GetHeight` / `GetNormal`. Audit during N.3
  follow-up uncovered that **WB's `CalculateSplitDirection` uses a
  different formula than retail's `FSplitNESW`** (the AC2D-cited
  polynomial `0x0CCAC033` / `0x421BE3BD` / `0x6C1AC587` / `0x519B8F25`
  that our visual terrain mesh and physics already share). The
  formulas pick different cell-diagonals on disputed cells, producing
  up to ~2m Z divergence at the same world position. Substituting
  physics-side alone would un-sync physics from the still-ours visual
  mesh — exactly the triangle-Z hover bug class. N.1's conformance
  test proved WB's `GetNormal` is good enough for slope-filtering
  (boolean walkable check) but NOT that WB's height formula matches
  retail. Resolution: fold this work into **N.5** when the visual
  mesh switches to WB's renderer in lockstep with physics. Until
  then, leave `TerrainSurface` alone. See ISSUE #51.
 - **✓ SHIPPED — N.3 — Texture decoding.** Shipped 2026-05-08. `SurfaceDecoder`
  now delegates INDEX16 / P8 / A8R8G8B8 / R8G8B8 / A8 to WB's
  `TextureHelpers.Fill*`. The A8 divergence (our old code did R=G=B=A=val
  always; WB splits additive vs non-additive) was resolved by threading an
  `isAdditive` parameter through `DecodeRenderSurface`: terrain alpha masks
  pass `isAdditive: true` (matches our prior behavior, preserves the
  shader's `.r` blend-weight read), entity surfaces pass
  `surface.Type.HasFlag(SurfaceType.Additive)`. Bonus: R5G6B5 + A4R4G4B4
  formats now decode (previously fell to magenta). X8R8G8B8, DXT1/3/5, and
  SolidColor remain ours (no WB equivalent). **9 conformance tests prove
  byte-identical equivalence per format** before substitution; updated
  `SurfaceDecoderTests` to match the new A8 split semantics. Visual
  verification at Holtburg passed 2026-05-08 — no texture regressions.
 - **✓ SHIPPED — N.4 — Rendering pipeline foundation.** Shipped 2026-05-08.
  WB's `ObjectMeshManager` is integrated as the production mesh pipeline
  behind `ACDREAM_USE_WB_FOUNDATION=1` (default-on). The integration is
  three pieces: `WbMeshAdapter` (single seam owning the WB pipeline,
  drains the staged-upload queue per frame, populates
  `AcSurfaceMetadataTable` for translucency / luminosity / fog),
  `WbDrawDispatcher` (production draw path — groups all visible
  (entity, batch) pairs, uploads matrices in a single `glBufferData`,
  fires one `glDrawElementsInstancedBaseVertexBaseInstance` per group
  with `BaseInstance` slicing the shared instance VBO), and the
  `LandblockSpawnAdapter` + `EntitySpawnAdapter` bridge that wires our
  streaming loader to WB's `IncrementRefCount` / `PrepareMeshDataAsync`
  lifecycle (atlas tier vs per-instance customized).
  Issue #47 (close-detail mesh) preserved; sky pass structurally
  independent of the WB foundation. Perf wins shipped as part of N.4:
  per-entity AABB frustum cull, opaque front-to-back sort, palette-hash
  memoization. Legacy `InstancedMeshRenderer` retained as flag-off
  fallback until N.6 fully retires it. Plan archived at
  `docs/superpowers/plans/2026-05-08-phase-n4-rendering-foundation.md`.
 - **✓ SHIPPED — N.5 — Modern rendering path.** Shipped 2026-05-08.
  **Rebranded from "Terrain rendering" 2026-05-08 after N.4 perf
  review.** Lifted `WbDrawDispatcher` onto bindless textures
  (`GL_ARB_bindless_texture`) + `glMultiDrawElementsIndirect`. Per-frame
  entity rendering: 3 SSBO uploads (instance matrices @ binding=0, batch
  data @ binding=1, indirect commands) + 2 indirect calls (opaque +
  transparent). ~12-15 GL calls per frame regardless of group count, down
  from hundreds-of-per-group in N.4. CPU dispatcher: 1.23 ms/frame median
  at Holtburg (1662 groups, ~810 fps). All textures on the modern path use
  1-layer `Texture2DArray` + `sampler2DArray`; legacy callers retain
  `Texture2D` via the parallel `TextureCache` path until N.6 retires them.
  Three gotchas in memory (`project_phase_n5_state.md`): texture target
  lock-in, bindless Dispose two-phase order, GL_TIME_ELAPSED double-
  buffering. Plan archived at
  `docs/superpowers/plans/2026-05-08-phase-n5-modern-rendering.md`.
 - **✓ SHIPPED — N.5b — Terrain on the modern rendering path.** Shipped
  2026-05-09. **Path C** (mirror WB's `TerrainRenderManager` pattern but
  consume `LandblockMesh.Build` for retail-formula compliance). Path A
  (substitute WB's `CalculateSplitDirection`) killed during pre-implementation
  divergence test: WB's formula disagrees with retail's `FSplitNESW`
  (addr `00531d10`) on **49.98%** of cells across `tests/AcDream.Core.Tests/Terrain/SplitFormulaDivergenceTest.cs`'s
  sweep — wholly incompatible with our shared physics + visual mesh.
  Path B (fork-patch WB to use retail's formula) rejected for permanent
  maintenance burden. Path C ships the architectural pattern (single
  global VBO/EBO + slot allocator + bindless atlas + `glMultiDrawElementsIndirect`)
  while keeping retail's formula via `LandblockMesh.Build` →
  `TerrainBlending.CalculateSplitDirection`. `TerrainModernRenderer` +
  `terrain_modern.vert/.frag` shipped, `TerrainChunkRenderer` +
  `TerrainRenderer` + legacy `terrain.vert/.frag` deleted in T9.
  Closes ISSUE #51. **Perf reality check:** at radius=5 in Holtburg,
  modern is ~4× SLOWER on CPU than legacy was (6.4 µs vs 1.5 µs median;
  legacy collapsed radius=5's visible LBs into one `glDrawElements`
  via 16×16-LB chunking). Architectural wins (zero `glBindTexture`/frame,
  constant-cost dispatch as A.5 raises radius, per-LB frustum cull)
  manifest at higher radius. Spec acceptance criterion #5 was wrong;
  amended via `docs/plans/2026-05-09-phase-n5b-perf-baseline.md`. Plan
  archived at `docs/superpowers/plans/2026-05-09-phase-n5b-terrain-modern.md`.
 - **✓ SHIPPED — N.6 slice 1 — GPU timing fix + radius=12 perf baseline.** Shipped 2026-05-11.
  Fixed the gpu_us double-buffering bug in `WbDrawDispatcher` (ring-of-3
  query slots, read-before-overwrite, vendor-neutral across AMD/NVIDIA/Intel
  desktop GL). Added env-gated surface-format histogram dump in `TextureCache`
  for atlas-opportunity audit. Captured authoritative baseline at Holtburg
  radii 4 / 8 / 12 (standstill + walking) with the now-working `gpu_us`
  diagnostic. Plan + spec at `docs/superpowers/{specs,plans}/2026-05-11-phase-n6-slice1-*.md`.
  Baseline numbers + next-phase recommendation at
  [docs/plans/2026-05-11-phase-n6-perf-baseline.md](2026-05-11-phase-n6-perf-baseline.md).
 - **N.6 slice 2 — Perf polish cleanup.** **Planned — deferred until after C.1.5
  (PES emitter wiring) per the baseline doc's recommendation.** Builds on
  slice 1's measurement. Scope: retire the legacy `Texture2D`/`sampler2D` path
  in `TextureCache` (currently kept for Sky + Debug + particle paths now that
  Terrain has migrated); delete orphan `mesh.frag` (verify zero callers post-N.5
  amendment); decide bindless-everywhere vs legacy-island for the remaining
  `sampler2D` consumers. **Dropped from slice 2 scope per baseline data**:
  WB atlas adoption and persistent-mapped buffers — both target GPU/sampler
  throughput but the baseline shows GPU is wildly under-utilized (max gpu_us
  p95 ~600 µs vs 16,600 µs frame budget). Slice 2 reduces to a ~1-day cleanup.
  Plan + spec written when work begins. **Estimate: ~1 day once C.1.5 lands.**
 - **N.7 — EnvCells / dungeons.** Replace EnvCell rendering with WB's
  `EnvCellRenderManager` + `PortalRenderManager` on top of N.4's
  foundation. **Estimate: 1-2 weeks** (was 2-3 — naturally smaller now
  that infrastructure is shared).
 - **N.8 — Sky + particles.** Replace sky rendering + particle pipeline
  (#36 / C.1 work) with WB's `SkyboxRenderManager` +
  `ParticleEmitterRenderer`. **Estimate: ~1 week** (was 1.5-2 — C.1
  already shipped most of this; N.8 is glue + sampler-object reuse).
 - **N.9 — Visibility / culling.** Replace `CellVisibility` +
  `FrustumCuller` with WB's `VisibilityManager`. **Estimate: ~1 week**
  (was 3-5 days, slight bump for streaming-loader interaction).
 - **N.10 — GL infrastructure consolidation (optional).** Replace our
  `Shader` / `TextureCache` / `SamplerCache` plumbing with WB's
  `ManagedGL*` wrappers + `OpenGLGraphicsDevice`. **Largely subsumed by
  N.4** — `OpenGLGraphicsDevice` arrives as the host of `ObjectMeshManager`
  and atlas. May not need a dedicated phase; revisit after N.6.
 **Estimated calendar:** **2.5-3 months / 9-13 engineering weeks for
 N.4-N.9 (N.10 likely subsumed; N.2 folded into N.5; N.3 shipped).**
 Revised 2026-05-08 after recognizing N.4-N.6 are one rendering rebuild
 on shared infrastructure rather than three independent substitutions.
 **Each sub-phase:**
 - Ships behind `ACDREAM_USE_WB_<NAME>=1` flag.
 - Has its own conformance test (side-by-side against existing path).
 - Visual verification before flag becomes default-on.
 - Old code deleted after default-on lands cleanly.
 **N.2-N.10 detailed specs are NOT yet written** — each gets its own
 brainstorm + spec when we reach it.
 **Acceptance:**
 - All 10 sub-phases shipped, feature flags removed, old rendering code
  paths deleted.
 - Visual verification at Holtburg + Foundry statue + a representative
  dungeon shows no regression vs Phase C.1.
 - WB upstream merges into our `acdream` branch are clean (or have
  documented conflict-resolution patterns).
 ---
 ### Phase J — Long-tail (deferred / low-priority)
 Not detailed here; each gets its own brainstorm when it becomes relevant.
--- a/docs/plans/2026-04-29-movement-collision-conformance.md
+++ b/docs/plans/2026-04-29-movement-collision-conformance.md
@ -92,35 +92,6 @@ Goal: make every bad movement outcome explainable.
 - Build real-DAT fixture capture for known walls, building ledges, rooftops,
  slopes, landblock seams, and dungeon entrances.
 Current shipped slices:
 - 2026-04-30: cdb + TTD retail-observer toolchain (`tools/pdb-extract/`,
  `tools/ttd-record.ps1`, `tools/ttd-query.ps1`) with PDB pairing checker
  and ring-buffer trace replay. The "retail observer harness" line item.
 - 2026-04 (pre-L.2 rename): `ACDREAM_DUMP_MOVE_TRUTH` paired
  outbound/server-echo dumper in `GameWindow` covers outbound packet
  fields + server echo + correction delta with cell-id mismatch.
 - Pre-L.2: scenario-specific dumps `ACDREAM_DUMP_MOTION`,
  `ACDREAM_DUMP_STEEP_ROOF`, `ACDREAM_DUMP_STEPUP`,
  `ACDREAM_DUMP_EDGE_SLIDE` for the codepaths hit during prior bug chases.
 - 2026-05-12 (slice 1): general-purpose probes via new
  `AcDream.Core.Physics.PhysicsDiagnostics` static class.
  `ACDREAM_PROBE_RESOLVE` emits one `[resolve]` line per
  `PhysicsEngine.ResolveWithTransition` call (input/output pos+cell,
  ok-vs-partial, grounded-in, contact-plane status, wall normal if hit,
  walkable polygon valid, moving entity id).
  `ACDREAM_PROBE_CELL` emits one `[cell-transit]` line per
  `PlayerMovementController.CellId` change with old→new + position +
  reason tag (`resolver`/`teleport`). Both flippable live via the
  DebugPanel "Diagnostics" section — checkbox toggles take effect on
  the next resolve, no relaunch required.
 Remaining L.2a work: contact-plane probe (general, not just steep-roof),
 ShadowObjectRegistry hit log ("you collided with entity X"), water probe,
 real-DAT fixture-capture pipeline, and folding the older sticky-at-startup
 `ACDREAM_DUMP_*` flags into `PhysicsDiagnostics` for unified runtime
 toggling.
 ### L.2b - Movement Wire / Contact Authority
 Goal: stop sending movement packets that claim more certainty than the local
@ -169,41 +140,6 @@ fallback.
 - Audit `Setup.Radius` and cylinder fallback behavior against retail before
  relying on them for conformance.
 Current sub-direction (revised 2026-05-13 evening after slice 1 + 1.5
 shipped and Holtburg-doorway capture analyzed — third reframe):
 L.2d as scoped ("shape fidelity: Sphere / CylSphere / Building Objects")
 is **essentially closed at the Holtburg site that motivated this phase**.
 Building BSP collision works correctly — the slice-1.5 probe captured
 real triangles in plausible world positions for `gfxObj=0x01000A2B` with
 `bspR=13.99m`. The 121 wall hits the L.2a probe attributed to
 `obj=0xA9B47900` were **side effects of the player already being pushed
 back by a separate Door cylinder entity** at the same doorway threshold.
 The actual blocker is a server-spawned **Door** entity — Setup
 `0x020019FF` named `"Door"` — that ACE places at each Holtburg-town
 building threshold (five doors total observed across `0xA9B40029`,
 `0xA9B40154`, `0xA9B40155`). It registers as a Cylinder shadow entry
 via the server-spawn path; its Cylinder collision blocks the player
 walking into the doorway. That's **door-state handling**, a different
 class of problem from L.2d's shape-fidelity scope — it touches network
 (`CreateObject` PhysicsState bits), interaction (Use action on door
 entity), animation (door open/close), and collision-state-toggle.
 Recommend: **leave L.2d in "watch-and-wait" mode** with slice 1's probe
 infrastructure in place. No more L.2d slices until a NEW shape-fidelity
 bug is observed at a different site (dungeon walls, stairs, roofs) with
 the probe-armed client. The door-state work becomes its own sub-phase
 (probably nested under B.4 interaction or filed as a new L.2 sub-phase
 like L.2g) scoped separately.
 Full slice 1 + 1.5 handoff:
 [docs/research/2026-05-13-l2d-slice1-shipped-handoff.md](../research/2026-05-13-l2d-slice1-shipped-handoff.md).
 Design spec (now mostly historical, framing was wrong but probe
 infrastructure shipped from it):
 [docs/superpowers/specs/2026-05-13-l2d-cbuildingobj-collision-design.md](../superpowers/specs/2026-05-13-l2d-cbuildingobj-collision-design.md).
 Predecessor L.2a handoff:
 [docs/research/2026-05-12-l2a-shipped-l2d-handoff.md](../research/2026-05-12-l2a-shipped-l2d-handoff.md).
 ### L.2e - Cell Ownership: Outdoor Seams, CELLARRAY, cell_bsp
 Goal: the resolver knows which cell owns the movement and which adjacent cells
@ -228,62 +164,6 @@ client sees when observing acdream.
 - Require conformance notes in tests or research docs for every AC-specific
  algorithm ported under L.2.
 ### L.2g - Dynamic PhysicsState Toggling
 Goal: server-driven post-spawn state changes (chiefly `ETHEREAL` flips) are
 honored by the local collision stack.
 Triggered 2026-05-12 evening by the L.2d slice 1.5 trace: the Holtburg
 doorway blocker is a closed Door entity (Setup `0x020019FF`) whose
 `PhysicsState.Ethereal` bit flips when the player Uses the door. The L.2d
 shape-fidelity work doesn't cover this — the door's collision shape is
 already correct; what's missing is honoring the *runtime* state change.
 Scope is intentionally narrow:
 - Parse inbound `GameMessageSetState (opcode 0xF74B)`.
 - Plumb the new `PhysicsState` value into `ShadowObjectRegistry`'s cached
  per-entity state so the existing `CollisionExemption.IsExempt(...)` check
  sees the up-to-date bits.
 - Verify the Holtburg inn-door scenario: walk into doorway → blocked, Use
  door → door swings open AND player can walk through, auto-close after
  30s → door closes AND player is blocked again.
 - Confirm the existing `UpdateMotion` pipeline drives `(NonCombat, On/Off)`
  on non-creature entities (door swing animation). If not, one-line fix.
 Excluded from L.2g scope (deferred):
 - Door-specific UX polish: "door is locked" sound, creature-AI bump-open.
 - Any Door-specific class hierarchy — generic state-flip infrastructure
  is enough; doors are the verification scenario, not a privileged case.
 Lane: informal sixth lane "dynamic state." The existing five-lane table
 treats per-entity state as static-after-spawn; L.2g makes it dynamic.
 Full design spec:
 [docs/superpowers/specs/2026-05-12-l2g-dynamic-physicsstate-design.md](../superpowers/specs/2026-05-12-l2g-dynamic-physicsstate-design.md).
 M1 critical path: this slice unblocks the *"open the inn door"* demo
 scenario.
 Current shipped slice (2026-05-12):
 | Commit | Subject |
 |---|---|
 | `2459f28` | `feat(phys L.2g slice 1): inbound SetState (0xF74B) parser` |
 | `d538915` | `feat(phys L.2g slice 1): ShadowObjectRegistry.UpdatePhysicsState` |
 | `536a608` | `feat(phys L.2g slice 1): WorldSession dispatches SetState (0xF74B) + hex probe` |
 | `108e386` | `feat(phys L.2g slice 1): GameWindow routes SetState + extends [entity-source] log` |
 Slice 1 is CODE-COMPLETE: parser + registry mutator + WorldSession
 dispatcher + GameWindow subscriber. 6 new tests pass (3 parser + 3
 registry). Build clean. Per-commit + final integration code reviews
 all approved. **Visual verification deferred to Phase B.4b** — the
 inbound SetState chain can't fire at runtime until B.4b finishes the
 outbound Use handler. See
 [docs/research/2026-05-12-l2g-slice1-shipped-handoff.md](../research/2026-05-12-l2g-slice1-shipped-handoff.md)
 for full evidence + the 4 minor + 1 Important review notes.
 ## Named Retail Anchors
 Primary source: `docs/research/named-retail/acclient_2013_pseudo_c.txt`.
--- a/docs/plans/2026-05-08-phase-n5-perf-baseline.md
+++ b/docs/plans/2026-05-08-phase-n5-perf-baseline.md
@ -1,72 +0,0 @@
 # Phase N.5 perf baseline
 **Captured:** 2026-05-08, against N.5 head (post-Task 12) on local machine.
 **Method:** `ACDREAM_WB_DIAG=1` + character at Holtburg spawn position +
 roaming. Numbers below are 5-second window medians from `[WB-DIAG]`.
 ## Holtburg courtyard (steady state)
 | Metric | N.5 measured | N.4 (estimated*) | Gate |
 |---|---|---|---|
 | CPU dispatcher (median) | **1227 µs / frame** | ≥2500 µs / frame | ≤70% of N.4 → **PASS** |
 | CPU dispatcher (p95) | 1303 µs / frame | — | — |
 | GPU rendering (median) | unmeasured (see below) | — | within ±10% — **DEFERRED** |
 | `drawsIssued` per 5s | 4.85M (= 1662 groups × ~580 fps) | far higher per frame | — |
 | `drawsIssued` per pass (CPU GL calls) | **2** (1 opaque + 1 transparent indirect) | ~hundreds per pass | ≤5 → **PASS** |
 | `groups` (working set) | 1662 | ~similar | sanity |
 | Frame rate (inferred) | ~810 fps | ~100-200 fps | substantial uplift |
 *N.4 baseline NOT measured directly in this run. The "≥2500 µs / frame"
 estimate assumes N.4's per-group glBindTexture + glBindBuffer +
 glDrawElementsInstancedBaseVertexBaseInstance hot path costs ≥1.5 µs per
 group and N.4 has ~1700 groups in this scene, putting the GL portion alone
 at ~2.5 ms before adding the entity-walk overhead. N.5's measurement
 includes ALL dispatcher work (entity walk + group bucketing + 3 SSBO
 uploads + 2 indirect calls + state changes) at 1230 µs total — comfortably
 half of the lower bound estimate.
 ## Acceptance gates (spec §8.3)
 - [x] **Visual identity to N.4** — confirmed at Task 10 USER GATE: Holtburg
      courtyard renders identical, no missing entities, no z-fighting, no
      exploded parts.
 - [x] **CPU dispatcher time ≤ 70% of N.4** — N.5 measures 1.23 ms/frame
      median; estimated N.4 ≥2.5 ms/frame; **comfortably under 70%**.
 - [ ] **GPU rendering time within ±10% of N.4** — DEFERRED. The
      `GL_TIME_ELAPSED` query polling never reports `avail != 0` in our
      single-frame poll loop; the driver hasn't finalized the result by the
      time we check. The fix is double-buffering (issue queryA on frame N,
      read result on frame N+2). N.6 perf polish item.
 - [x] **`drawsIssued` ≤ 5 per pass (CPU GL calls)** — exactly 2 indirect
      calls per frame regardless of scene size.
 - [x] **All tests green** — 70/70 in
      `FullyQualifiedName~Wb|FullyQualifiedName~MatrixComposition`.
      8 pre-existing failures in `MotionInterpreter` / `BSPStepUp` /
      `PositionManager` / `PlayerMovementController` / `Dispatcher` are
      carry-forward from before N.5 and unrelated to rendering.
 - [N/A] **`ACDREAM_USE_WB_FOUNDATION=0` still works** — escape hatch
      formally retired in N.5 ship amendment. `InstancedMeshRenderer`,
      `StaticMeshRenderer`, and `WbFoundationFlag` deleted. Missing
      bindless throws `NotSupportedException` at startup with a clear
      error message. No fallback path.
 ## Visual verification (Task 14)
 - [x] **Holtburg courtyard** — PASS at Task 10 USER GATE.
 - [ ] **Foundry interior / dense static-object scene** — TODO Task 14.
 - [ ] **Indoor → outdoor cell transition** — TODO Task 14.
 - [ ] **Drudge / character close-up (Issue #47 close-detail mesh)** — TODO Task 14.
 - [ ] **Magic content (Decision 2 additive fallback check)** — TODO Task 14.
 - [ ] **Long-session sanity** — DEFERRED (N.6 watchlist; not load-bearing for ship).
 ## Open follow-ups for N.6
 1. **GPU timer query double-buffering** — the current single-frame poll
   pattern never sees `QueryResultAvailable=true`. Issue queryA on frame N,
   queryB on frame N+1, read queryA on frame N+2. ~30 lines of state.
 2. **Direct N.4 vs N.5 perf comparison** — re-run with `git checkout`ed N.4
   SHIP (`c445364`) for a side-by-side measurement. Not load-bearing but
   useful for N.6 ship message.
 3. **Persistent-mapped buffers** — Decision 7 deferral. If profiling shows
   the per-frame `glBufferData` cost is the residual hot spot, layer it on
   top of the modern path.
--- a/docs/plans/2026-05-09-phase-n5b-perf-baseline.md
+++ b/docs/plans/2026-05-09-phase-n5b-perf-baseline.md
@ -1,98 +0,0 @@
 # Phase N.5b — terrain perf baseline
 **Captured:** 2026-05-09 at Holtburg town dueling field, radius=5, ~30s standstill.
 ## Methodology
 Same build (commit at perf measurement: `da56063`), `ACDREAM_WB_DIAG=1`. The build
 included a TEMPORARY `ACDREAM_LEGACY_TERRAIN=1` env-var toggle (since retired in T9
 deletion of the legacy renderer) that routed Draw through the legacy renderer for
 direct comparison. Both renderers were constructed and fed AddLandblock / RemoveLandblock
 in parallel; only one drew per frame; the same Stopwatch wrapped whichever ran.
 ## Numbers
 | Renderer | cpu_us median | cpu_us p95 | draws/frame | Visible LBs |
 |---|---|---|---|---|
 | **Legacy** (`TerrainChunkRenderer`) | 1.5 | 3.0 | 1 (1 chunk) | 132-143 (whole chunk) |
 | **Modern** (`TerrainModernRenderer`) | 6.4-7.0 | 9-14 | ~36-51 | 36-51 (per-LB cull) |
 (Legacy `draws=1` because its 16×16-LB chunking collapses radius=5's 121 visible
 landblocks into a single chunk, dispatched as one `glDrawElements`. Modern issues
 one `glMultiDrawElementsIndirect` with N=36-51 sub-commands.)
 ## Acceptance criterion
 The N.5b spec acceptance criterion 5 read: "CPU dispatcher time at radius=5 ≥10%
 lower than today's per-LB-binds path." The captured numbers show modern is ~4×
 HIGHER on CPU at radius=5. **The criterion was wrong** — at radius=5 in Holtburg,
 legacy's chunked path was already collapsed to one draw call. The architectural
 wins of multi-draw indirect manifest at higher chunk counts (A.5 territory).
 The spec is amended via this doc: ship N.5b on visual identity + structural
 correctness rather than CPU savings at radius=5.
 ## Architectural wins of the modern path (real, even when CPU is higher)
 1. **Zero `glBindTexture` per frame.** Bindless atlas handles are made resident
   once at startup; the modern shader samples via `sampler2DArray(uvec2 handle)`.
   Legacy issued 2 `glBindTexture(Texture2DArray)` calls per frame.
 2. **Constant-cost dispatch.** As A.5 raises the streaming radius (next phase),
   the visible chunk count grows. Legacy scales linearly: at radius=10 (4× chunks)
   it's 4 `glDrawElements` calls; at radius=15 (≥9 chunks) it's 9+ calls. Modern
   stays at exactly 1 `glMultiDrawElementsIndirect` regardless.
 3. **Per-LB frustum culling.** Legacy culled at chunk granularity (16×16 LBs);
   modern culls per-LB. At a typical Holtburg view, ~36-51 of 132 loaded LBs are
   actually visible; legacy drew the entire 132-LB chunk (3.5× the visible work
   pushed to GPU vertex/fragment stages, even though CPU dispatch was cheap).
 ## Why modern's CPU was higher at radius=5
 Per-frame work in modern (in microseconds-ish budget on this scene):
 - Walk all loaded slots checking visibility (~120 slots) → AABB test each
 - Build DEIC array (51 entries × 20 bytes = 1020 bytes)
 - `glBufferSubData(DRAW_INDIRECT_BUFFER, ...)` — driver memcpy
 - 2× `glProgramUniform2(..., handle.low, handle.high)` for atlas handles
 - `glBindVertexArray` + `glMemoryBarrier(GL_COMMAND_BARRIER_BIT)` + `glMultiDrawElementsIndirect`
 Legacy's per-frame work:
 - Bind 2 textures
 - Bind one VAO (the chunk)
 - One `glDrawElements`
 The DEIC array build + buffer upload alone is ~3-5µs at radius=5 on this hardware,
 which is the bulk of the modern overhead. At higher radius, this overhead amortizes:
 the buffer is similar size, but the alternative (legacy's N draws) grows.
 ## Follow-up work
 - **A.5 (next phase)** will exercise the higher-radius case where modern wins.
  Capture a fresh baseline at radius=8 / 10 once A.5 lands.
 - **N.6 perf polish** can investigate persistent-mapped buffers for the indirect
  buffer, which would eliminate the per-frame `glBufferSubData`. Likely small win
  at radius=5 (single ~1KB upload), bigger at higher radii.
 - **GPU-side culling** (compute shader generating the DEIC array directly into
  the indirect buffer) eliminates the CPU slot walk + DEIC build entirely. N.6 or
  later territory; only worth it if profiling shows the CPU walk is hot.
 ## Lessons captured to memory
 `memory/project_phase_n5b_state.md` records the high-value gotchas surfaced
 during N.5b implementation. Three particularly bitable ones:
 1. **`uniform sampler2DArray` + `glProgramUniformHandleARB` is unreliable.** Some
   drivers (NVIDIA Windows in this case) reject the combination with
   `GL_INVALID_OPERATION`. Use the `uniform uvec2` + `sampler2DArray(handle)`
   constructor pattern instead — N.5's mesh_modern uses this, and N.5b's
   terrain_modern adopted it after the black-terrain regression.
 2. **`MaybeFlushTerrainDiag` underflow.** A naive median calc (`copy[N - nz/2]`)
   underflows to `copy[N]` when only one sample has been recorded. Use
   `copy[N - 1 - (nz - 1) / 2]` instead.
 3. **Visual gate must actually be visually confirmed.** "Go" doesn't mean
   "verified." During N.5b's gate the user said "go" without launching, which
   masked the black-terrain regression for hours. The gate must include the
   user reporting actual visual confirmation, not assent to proceed.
--- a/docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md
+++ b/docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md
@ -1,195 +0,0 @@
 # Performance Tiers 2 + 3 — Future Roadmap
 **Created:** 2026-05-10 during Phase A.5 polish.
 **Status:** Future planning — not for current execution.
 **Context:** A.5 shipped two-tier streaming with the entity dispatcher landing at ~3.5ms median (post-Bug-A and Bug-B fixes). Tier 1 (entity-classification cache) lands as A.5 polish and brings the dispatcher inside the 2.0ms spec budget. Tiers 2 + 3 are the "next big perf wins" beyond Tier 1.
 ---
 ## Background — why this exists
 Discussion captured 2026-05-10: user observed 200-240 FPS at radius=12 on a Radeon 9070 XT @ 1440p and asked why an "old game like AC" doesn't deliver Unreal-level (1000+ FPS) on this hardware.
 The honest answer: the bottleneck is *architectural*, not hardware. The CPU is single-threaded and rebuilds the entire draw plan from scratch every frame. Modern engines pre-bake static-world batches at content-cook time and rebuild only what changes.
 AC's design — server-spawned per-entity world streamed at runtime — doesn't naturally batch the way Unreal's pre-cooked content does. Closing the gap requires backporting modern techniques while preserving AC's data model. Tiers 2 and 3 are that backporting work.
 ---
 ## Tier 2 — Static/dynamic split with persistent groups
 **Estimated effort:** ~10-15 days (2-week phase).
 **Estimated win:** entity dispatcher ~3.5ms → **~0.5-1ms median** at radius=12.
 **Total frame time:** ~4-5ms → **~2-3ms = 400-600 FPS at standstill.**
 ### The core idea
 Today, `WbDrawDispatcher._groups` (the dictionary of "(mesh + texture + blend) → list of instances to draw") is cleared and rebuilt from scratch every frame.
 For trees, rocks, buildings, and other static entities (~95% of the world), the answer is identical every frame forever. Tier 2 makes the static-group instance buffers **persistent GPU-resident data**, just like Unreal's pre-baked world. The CPU only orchestrates "which groups are visible" per frame.
 ### Architectural shift
 ```csharp
 class StaticInstancedGroup
 {
    public GroupKey Key;
    public Matrix4x4[] Matrices;          // grown as entities spawn
    public BitArray ActiveSlots;          // for free-list reuse
    public bool NeedsGpuUpload;           // dirty flag for delta upload
    public Dictionary<uint, int> EntityToSlot;   // for despawn lookup
    public uint InstanceBufferOffset;     // start of group's slice in global SSBO
 }
 ```
 **On entity spawn (atlas-tier static):** allocate a slot in each relevant group, write the matrix, mark dirty.
 **On entity despawn:** free the slot, mark dirty.
 **Per frame:**
 - Static groups: LB-cull each group (cheap). For visible groups, flag for draw. **No matrix copy. No list rebuild.**
 - Dynamic entities (~50 NPCs/players): today's per-frame walk-and-classify. Keeps the existing slow path for things that legitimately change every frame.
 - Upload only the dirty groups' matrix slices (delta upload, not full reupload).
 - Issue 2 multi-draw-indirect calls.
 ### Sub-decisions
 **Frustum cull granularity at the group level:** at group level you can't reject individual instances; you draw the whole group or none of it. Two strategies:
 - **Per-LB subgroups:** split each group into per-landblock subgroups. LB-frustum-culls reject subgroups whose LB is invisible. ~2K groups × ~5 LBs per group on average = ~10K subgroups. Each subgroup AABB cull is ~0.3 µs → ~3 ms per frame. Roughly a wash with today's per-entity cull.
 - **Per-instance GPU cull (Tier 3):** compute pre-pass on the GPU writes which instances are visible to a draw-indirect buffer. ~0.05ms CPU. The right long-term answer.
 For Tier 2 alone, per-LB subgroups are the recommended approach — keep CPU culling, just at coarser granularity than per-entity.
 **Dynamic entities crossing LB boundaries:** when an NPC walks across a landblock boundary, it stays in the same group key but its "spatial bucket" changes. Solution: dynamic entities are tracked in a single global "dynamic group" outside the per-LB structure; they don't need spatial bucketing because there are only ~50 of them.
 **Palette override invalidation:** server event swaps an NPC's clothing color → group key changes. Treat as despawn-from-old + spawn-into-new. NPCs are dynamic so this just rebuckets them.
 **Animation overrides on static entities:** static entities don't animate. Trees don't bend (foliage wave is a vertex shader effect, not a group-key change). Buildings don't move. So the static path never invalidates.
 **EnvCell visibility:** dungeon entities are gated by per-cell visibility state. Need to track which group instances are tied to which cell, and during visibility cull, gate per-cell. Keep using existing `ParentCellId` field on WorldEntity.
 **Streaming load/unload integration:** when an LB unloads, all its static entity matrices need to be removed from their groups. Free-list management. Matches existing `LandblockSpawnAdapter` lifecycle.
 ### Effort breakdown
 | Task | Days |
 |---|---|
 | Design + invariants document | 2 |
 | Spawn-time slot allocator + free-list | 3 |
 | Per-frame visibility + dirty-flag delta upload | 2 |
 | Dynamic entity path (NPCs, projectiles) | 2 |
 | Invalidation (palette/ObjDesc events) | 2 |
 | EnvCell visibility integration | 1 |
 | Streaming load/unload integration | 1 |
 | Conformance testing | 2-3 |
 | **Total** | **~10-15 days** |
 ### Risks
 - **Slot management bugs** = double-frees or leaks (entities draw at random positions — visible).
 - **Invalidation bugs** = stale matrices (entity teleports back to spawn point when palette changes).
 - **Dynamic entity tracking** adds complexity around the static/dynamic boundary.
 ### Mitigations
 - **Conformance test:** render a fixed scene through both pipelines, compare draw output. Adds CI infrastructure.
 - **Per-frame validation in debug:** walk all groups, assert no orphan slots.
 - **Hash invariant test:** static entities should produce stable group keys frame-over-frame. Add a debug assertion that fires once per frame in Debug builds.
 ---
 ## Tier 3 — GPU-side culling (compute pre-pass)
 **Estimated effort:** ~1 month (longer phase).
 **Estimated win:** entity dispatcher ~0.5-1ms (post-Tier-2) → **~0.05ms median.**
 **Total frame time:** ~2-3ms → **~1.5-2ms = 600-1000+ FPS at standstill.**
 ### The core idea
 Today (and after Tier 2), the CPU does per-LB or per-subgroup frustum culling and tells the GPU which groups to draw.
 Tier 3 moves per-instance frustum cull to the GPU via a compute shader pre-pass. The CPU just uploads "here are all 1M instance matrices" once; the GPU compute shader writes which ones are visible to a draw-indirect buffer; the rasterizer draws only those.
 This is the level Unreal is at. With this, per-frame CPU work for the entity dispatcher becomes essentially "tell the GPU what to do" + a tiny scratch upload.
 ### Why Tier 3 needs Tier 2 first
 Without Tier 2's persistent group structure, GPU culling has nothing stable to operate on. The compute shader needs an addressable "here are the static instances" buffer to read from; that buffer only exists after Tier 2.
 ### Sub-decisions to be made
 **Compute shader API:** OpenGL 4.3+ compute shaders are sufficient. We're already at GL 4.3+ for bindless. No additional capability requirement.
 **Indirect draw command generation:** the compute shader writes a `DrawElementsIndirectCommand[]` buffer per pass. Render thread issues `glMultiDrawElementsIndirect` reading from that buffer. No CPU readback.
 **LOD selection:** opportunity to add per-instance LOD selection in the compute shader (distance-based mesh detail). Not needed for A.5's scope; could be a Tier 4 follow-up.
 **Per-light shadow map culling:** if shadows ship, GPU culling extends naturally to per-light frustum cull. Significant win for shadow rendering.
 ### Effort breakdown
 | Task | Days |
 |---|---|
 | Compute shader design + GLSL implementation | 4 |
 | Buffer layout coordination with Tier 2 | 2 |
 | Silk.NET compute dispatch integration | 3 |
 | Indirect command compaction logic | 4 |
 | LOD selection (optional, ~stretch) | 4 |
 | Validation: per-instance cull matches CPU cull within epsilon | 3 |
 | Conformance + regression testing | 5 |
 | **Total** | **~21-25 days, ~1 month** |
 ### Risks
 - **GPU stalls** if the compute shader takes longer than expected (esp. on lower-end GPUs).
 - **Sync overhead** between compute pre-pass and rasterizer pass.
 - **Debugging difficulty** — GPU compute bugs are harder to diagnose than CPU bugs.
 ### Mitigations
 - **Profile-driven design:** measure compute shader runtime on target hardware before committing.
 - **Fallback path:** keep CPU cull as a runtime-toggleable option (env var) so we can A/B compare.
 - **GPU debugging tools:** RenderDoc captures + frame-by-frame compute shader inspection.
 ---
 ## When to schedule these
 **Tier 2:**
 - Best fit: dedicated 2-week phase after a SHIP cycle. Treat it like a Phase B/C/N (i.e., name it Phase A.6 or N.7).
 - Trigger: user wants to push radius beyond 12 (e.g., to 15 or 20 for true continent-scale horizon).
 - Trigger: user wants to add 100+ active NPCs in a city without dropping below 240Hz.
 **Tier 3:**
 - Best fit: after Tier 2 has been live and stable for at least one cycle.
 - Trigger: shadow map work begins (GPU cull + shadow cull share the same compute pre-pass infrastructure).
 - Trigger: user wants 500+ FPS sustained for very-high-refresh scenarios (360Hz monitors, future hardware).
 **Both:**
 - Don't bundle with other phases. These are dedicated perf phases with their own brainstorm + spec + plan + SHIP cycles.
 ---
 ## What's "free" or smaller (out of Tier 1/2/3 scope but worth noting)
 - **Plumb `JobKind` properly through `BuildLandblockForStreaming`** (~30 min). Today's Bug A patch wastes worker-thread CPU on hydration that gets thrown away for far-tier. Cleaner code, slight CPU savings on worker.
 - **Eliminate `ToEntries` adapter allocation in `Draw`** (~15 min). Tiny win (~25 KB / frame). Could fold into Tier 1.
 - **Persistent-mapped indirect buffer** (~2 days). Today's `glBufferData` per frame becomes a pre-mapped persistent buffer. Marginal win on RDNA 4; meaningful on lower-end GPUs.
 - **Multi-thread mesh-build worker pool** (~1 day). 2.7s first-traversal horizon-fill drops to 0.7s with 4 workers. UX win on first walk-into-region.
 These are good candidates for a "perf polish" mini-phase or to backfill into Tier 2.
 ---
 ## The architectural ceiling
 Even with all three tiers, **a faithful AC client written in C# with bindless OpenGL tops out around 800-1500 FPS at radius=12 on RDNA 4 hardware**. Beyond that requires:
 - Native C++ rendering core (eliminate .NET GC + JIT overhead)
 - DX12/Vulkan API (eliminate driver state validation)
 - Offline content cooking (eliminate runtime mesh/texture decode)
 Each of those is a several-month undertaking and represents "becoming a different engine." The realistic target for acdream is 240-500 FPS at the user's monitor refresh, comfortably ahead of the visible-stutter threshold. Tier 1 + Tier 2 alone should deliver that for radius=12-15.
 For "Unreal-level FPS at full quality," that's a different project.
--- a/docs/plans/2026-05-11-phase-n6-perf-baseline.md
+++ b/docs/plans/2026-05-11-phase-n6-perf-baseline.md
@ -1,193 +0,0 @@
 # Phase N.6 slice 1 — perf baseline at Holtburg
 **Created:** 2026-05-11.
 **Spec:** [docs/superpowers/specs/2026-05-11-phase-n6-slice1-design.md](../superpowers/specs/2026-05-11-phase-n6-slice1-design.md)
 **Measured against commit:** `25cb147` (Task 1 final — gpu_us fix + diag-gate symmetry follow-up)
 **Purpose:** Capture authoritative CPU+GPU dispatch numbers so the next-phase decision (slice 2 vs C.1.5 vs Tier 2) rests on real data.
 ---
 ## §1. Setup
 - **Hardware:** Radeon RX 9070 XT
 - **Resolution:** 1440p (2560×1440)
 - **Quality preset:** High (default)
 - **Connection:** live ACE at `127.0.0.1:9000`
 - **Character:** `+Acdream` at Holtburg
 - **Sky / time:** clear midday (F7 → Noon, F10 → Clear)
 - **Build:** Debug
 - **Date measured:** 2026-05-11
 - **Environment overrides:** `ACDREAM_WB_DIAG=1`, `ACDREAM_STREAM_RADIUS=<per-run>`
 Note: `ACDREAM_STREAM_RADIUS=N` forces N₁=N (all N near-tier landblocks at full detail).
 This is NOT the production A.5 default (N₁=4 / N₂=12), which was characterized in
 CLAUDE.md as comfortable 200–400 FPS at the default preset. These measurements
 characterize the scaling curve — what happens as near-tier radius grows — not current
 production behavior. FPS was not captured directly (no window-title screenshot per run);
 it can be derived from `(1e6 / total_frame_time_us)` but the dispatcher's `cpu_us` is
 only part of the frame (terrain, sky, particles, UI, GL submission overhead, and
 swap-buffer wait are not included).
 ## §2. Dispatch CPU / GPU numbers
 Each cell records the median of the last 3 `[WB-DIAG]` lines from a ~30s stable window.
 `entSeen / entDrawn / groups / drawsIssued` are also from those lines (values per 5s bucket).
 FPS column omitted — not captured per the note above.
 | Radius | Motion     | cpu_us median | cpu_us p95 | gpu_us median | gpu_us p95 | entSeen (per 5s) | entDrawn (per 5s) | groups | drawsIssued (per 5s) |
 |--------|------------|---------------|------------|---------------|------------|------------------|-------------------|--------|----------------------|
 | 4      | standstill | 3,208         | 3,313      | 93            | 95         | 16.9M            | 15.5M             | 1,216  | 1.65M                |
 | 4      | walking    | 2,967         | 3,112      | 95            | 120        | 13.9M            | 13.9M             | 1,850  | 1.45M                |
 | 8      | standstill | 6,732         | 7,199      | 126           | 130        | 19.8M            | 19.8M             | 333    | 218K                 |
 | 8      | walking    | 6,572         | 6,927      | 96            | 113        | 18.1M            | 18.0M             | 534    | 245K                 |
 | 12     | standstill | 12,853        | 13,525     | 344           | 507        | 19.6M            | 19.6M             | 541    | 184K                 |
 | 12     | walking    | 16,320        | 17,241     | 553           | 603        | 17.8M            | 17.8M             | 898    | 200K                 |
 **Notable:** `meshMissing` counts at r4 standstill (~1.45M per 5s) drop to near-zero while
 walking. This suggests the static-entity slow path's mesh-load lifecycle has some delay
 before populating for newly-streamed content. Not fatal — doesn't affect rendered output —
 but worth a follow-up issue in `docs/ISSUES.md` if it persists in normal play.
 ## §3. Surface-format histogram
 From `ACDREAM_DUMP_SURFACES=1` at radius=12, ~30s after enter-world.
 Output written to `%LOCALAPPDATA%\acdream\n6-surfaces.txt`.
 - **Total unique GL textures:** 760
 - **Total bytes (sum of W×H×4):** 96,387,584 (~96.4 MB)
 **Top 10 (W, H) dimension buckets:**
 | Dimensions | Count | Share |
 |------------|-------|-------|
 | 128×128    | 236   | 31%   |
 | 64×64      | 111   | 15%   |
 | 256×256    | 102   | 13%   |
 | 128×256    | 71    | 9%    |
 | 64×128     | 69    | 9%    |
 | 256×128    | 48    | 6%    |
 | 128×64     | 39    | 5%    |
 | 512×512    | 30    | 4%    |
 | 8×8        | 18    | 2%    |
 | 32×32      | 14    | 2%    |
 **Format distribution:**
 | Format        | Count | Share |
 |---------------|-------|-------|
 | RGBA8_DECODED | 760   | 100%  |
 All uploads land as RGBA8 regardless of source format (INDEX16, P8, DXT, BGRA, etc.
 all decode through `TextureHelpers` before upload). The source-format diversity is real
 but invisible to GL after the decode step.
 **Top 10 (W, H, format) triples — atlas-opportunity input:**
 Same as the dimension buckets above since there is only one format. The top-3 triples
 (128×128, 64×64, 256×256) cover 449 of 760 surfaces = **59%**.
 **Atlas-opportunity score: 59%** of surfaces fall into the top-3 (W, H, format) triples.
 A conventional rule-of-thumb is that >30% concentration into the top buckets makes atlas
 packing worth the implementation cost for memory savings; this measurement is well above
 that. However, see §4 for why atlas is not the right next step despite the high score.
 ## §4. Conclusion + next-phase recommendation
 ### What the data shows
 **The entity dispatcher is strongly CPU-bound.** At every radius, CPU dominates GPU by
 30–50×. At radius=12 standstill: 12.9 ms CPU vs 0.34 ms GPU. At radius=12 walking the
 ratio is 16.3 ms CPU vs 0.55 ms GPU. There is no GPU bottleneck.
 **GPU is wildly under-utilized.** The highest gpu_us p95 observed is 603 µs at radius=12
 walking — against a 16,600 µs frame budget at 60 FPS. The GPU is working at roughly
 3.6% of its 60fps capacity for entity rendering alone. Even accounting for terrain, sky,
 particles, UI, and swap-buffer overhead, there is substantial headroom. The "GPU
 comfortable" threshold (gpu_us p95 < 8,000 µs) is not even close to being challenged.
 **CPU grows more than linearly with N₁ (near-tier radius), but sublinearly with
 visible-LB count.** As N₁ grows from 4 → 8 → 12, median cpu_us grows from 3.2 ms →
 6.7 ms → 12.9 ms — roughly 1.0× → 2.1× → 4.0× the r4 baseline. The visible-LB count
 scales as `(2N+1)²`: 81 → 289 → 625, so CPU growth is sublinear in LB count (4.0×
 vs 7.7× expected if every LB cost the same). Frustum culling discards most far LBs
 early, but the outer per-LB walk still has to touch each one. The Tier 1 entity-
 classification cache (`EntityClassificationCache`, shipped as #53) wins on the inner
 loop (per-entity classification avoided on cache hits) but the outer walk dominates
 as N₁ grows. This is exactly what the Tier 2 plan (persistent groups) at
 `docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md` addresses by eliminating the
 per-frame LB scan entirely.
 **Radius=12 is not the production scenario.** `ACDREAM_STREAM_RADIUS=12` forces N₁=12
 (625 near LBs at full detail). The production A.5 default preset is N₁=4 / N₂=12 (81
 full-detail near + 544 terrain-only far), which CLAUDE.md already characterizes as
 comfortable 200–400 FPS at the default preset. The numbers above characterize the scaling
 curve for headroom analysis, not the experience a typical player sees.
 **Atlas opportunity is high (59%) but the win is memory-only — and modest.** With 96 MB
 of textures and 59% in the top-3 dimension buckets, atlas consolidation would let the
 top buckets share single `Texture2DArray` objects rather than each surface owning its
 own 1-layer array. The primary wins of atlas — fewer sampler switches, fewer texture
 binds — are already near-zero because bindless textures are made resident once at upload
 and never bound per draw. The remaining win is the per-array metadata overhead × N
 surfaces, which is bounded but not dramatic given all surfaces are already power-of-two
 and same-format (RGBA8). Even on the optimistic side, the absolute memory saving is on
 the order of low-MB to ~10 MB, not a 40–50% halving. GPU is not bottlenecked on sampler
 switches or memory bandwidth (0.6 ms gpu_us p95 at radius=12 walking demonstrates this
 directly), so atlas adoption would cost 1–2 weeks of implementation risk for a memory
 saving the process doesn't currently need at 96 MB.
 ### Recommendation
 **Primary: do C.1.5 next (PES emitter wiring — portals, chimneys, fireplaces).** Four
 reasons: (a) the production dispatcher is already comfortable at the default N₁=4 preset
 per the CLAUDE.md notes; (b) the two slice-2 items that were "conditional on baseline"
 data (atlas adoption and persistent-mapped buffers) are not justified — GPU is not
 bottlenecked; (c) C.1.5 fills a visible content gap that has been open since C.1 shipped
 and is in the roadmap queue ahead of N.6 slice 2; (d) C.1.5 stabilizes the particle path
 before any future shader migration work in slice 2 touches `particle.frag`. Starting
 point for C.1.5 scoping: `docs/plans/2026-04-27-phase-c1-pes-particles.md` lines 285–295.
 **Secondary (after C.1.5 lands): N.6 slice 2 with reduced scope.** The baseline data
 justifies dropping atlas adoption and persistent-mapped buffers from slice 2 entirely.
 What remains is a ~1-day cleanup: retire orphan `mesh.frag` (verify zero callers post-N.5
 amendment), collapse dead `_handlesByOverridden` / `_handlesByPalette` legacy caches once
 their callers are confirmed gone, migrate `particle.frag` to bindless sampling after C.1.5
 stabilizes the path. Slice 2 is a cleanup sprint, not a performance phase.
 **Tertiary option (if perf escalation becomes pressing): Tier 2 first.** The scaling
 curve (3.2 → 6.7 → 12.9 ms as N₁ grows 4 → 8 → 12) confirms the per-LB walk is the
 bottleneck — exactly what Tier 2's persistent-group structure at
 `docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md` addresses. Not urgent at the current
 default N₁=4; worth revisiting if a future quality preset wants N₁=8 as default or if the
 200–400 FPS range at N₁=4 shrinks after more content is streamed.
 **Decision rule for revisiting:** if future measurement at the default preset shows
 cpu_us median > 5,000 µs or gpu_us p95 > 8,000 µs, re-open the escalation question.
 Otherwise, hold the C.1.5 → reduced-slice-2 sequence.
 ## §5. Reproducing the measurements
 Raw `[WB-DIAG]` output from each run was inspected live during measurement and the
 median of the last three steady-state lines from each scenario was transcribed into §2.
 The raw launch logs were not preserved — the captured medians in §2 are the canonical
 record. To reproduce on the same hardware:
 ```powershell
 $env:ACDREAM_DAT_DIR   = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE      = "1"
 $env:ACDREAM_TEST_HOST = "127.0.0.1"
 $env:ACDREAM_TEST_PORT = "9000"
 $env:ACDREAM_TEST_USER = "testaccount"
 $env:ACDREAM_TEST_PASS = "testpassword"
 $env:ACDREAM_WB_DIAG   = "1"
 $env:ACDREAM_STREAM_RADIUS = "4"  # or 8, 12
 dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | Tee-Object -FilePath "baseline.log"
 ```
 Stand still for ~30 s at the target radius (60 s at radius 12 to let streaming settle),
 or walk N→E→S→W across one landblock. Then `Select-String -Path baseline.log -Pattern
 "\[WB-DIAG\]" | Select-Object -Last 3` captures the steady-state numbers.
 For the surface histogram, also set `$env:ACDREAM_DUMP_SURFACES = "1"`, stay in-world
 ~30 s after streaming has loaded ≥100 textures (the cache-size gate), then read
 `$env:LOCALAPPDATA\acdream\n6-surfaces.txt`.
--- a/docs/plans/2026-05-12-milestones.md
+++ b/docs/plans/2026-05-12-milestones.md
@ -1,552 +0,0 @@
 # acdream — milestones (morale + scope layer)
 **Status:** Living document. Created 2026-05-12.
 **Sits above:** [`docs/plans/2026-04-11-roadmap.md`](2026-04-11-roadmap.md) (the strategic phase index).
 **Currently working toward:** **M1.5 — Indoor world feels right.** The
 building/cellar demo is DONE + user-gated, but M1.5 was EXTENDED 2026-06-13
 to include **dungeon support (full Phase G.3)** — dungeons don't work yet
 (terrain-less dungeon landblocks aren't supported by the streaming/load
 pipeline; issue #133). M1.5 does NOT land until dungeons work. M2 stays
 deferred. (Correction: M1.5 was briefly marked landed 2026-06-13; the user
 reverted that — the indoor world isn't done while dungeons are broken.)
 ---
 ## Why this document exists
 The roadmap is a phase index — week- to month-scale, ~50 phases by the time
 v1.0 lands. Phases ship in vertical slices (architecture-first, horizontal
 completion deferred), which is the right strategy for a solo open-source
 project at this scale — but it leaves a chronic "everything is half-built"
 feeling because no single phase ship feels like a real milestone.
 This document sits **one altitude above** the roadmap. Each milestone is:
 - **~6–10 weeks of focused work** (not a single phase, not a whole year).
 - Defined by a **concrete playable scenario** — when the scenario works
  end-to-end, the milestone lands.
 - A **scope-freeze event**: when a milestone lands, the phases it covers go
  off-limits until v1.0's final polish pass (M7).
 Crossing a milestone is a textual event — milestones doc gets the writeup,
 the freeze list flips, CLAUDE.md's "currently working toward" line advances.
 Phases ship; milestones **land**.
 ---
 ## Operating rules
 1. **One active milestone at a time.** Everything not on the critical path to
   the current milestone gets filed in `docs/ISSUES.md` with a `post-MN` tag
   and explicitly muted until the milestone hits. This is what kills the
   jumping-between-things feeling.
 2. **Frozen phases are off-limits.** "Frozen" means no rework, no polish, no
   follow-up commits unless something is actively broken (player crash,
   regression). Visual nice-to-haves, "while I'm here" cleanups, and
   architecture second-guesses are all post-M7. The freeze is the discipline
   mechanism that makes the milestone meaningful — without it, M0's many
   shipped phases keep silently consuming attention.
 3. **The milestone log is the morale instrument.** When a milestone hits:
   - Pin a one-paragraph writeup at the top of this doc describing what
     works end-to-end (any caveats or known regressions are explicit).
   - Update the freeze list. Update CLAUDE.md's "currently working toward"
     line to the next milestone.
   - NO demo videos. User explicitly removed that requirement 2026-05-16
     ("pointless of recording videos, for what purpose?").
 4. **State both altitudes at session start.** "Currently working toward M1.
   Current phase: L.2 collision. Next concrete step: L.2d slice 1 spec." This
   keeps the high-level orientation visible alongside the immediate task and
   makes mid-session drift obvious.
 ---
 ## The milestones
 ### M0 — "Connect & explore" — ✅ DONE (crossed months ago)
 **Demo scenario:** Log in, walk Holtburg in chase camera, see other characters
 animate, send a chat message and see the echo, watch day turn to night,
 listen to footsteps and ambient audio.
 **Phases included (frozen):**
 | Phase | What landed |
 |---|---|
 | 1–3 | Terrain + per-vertex normals + per-cell texture blending |
 | 4 | UDP codec + handshake + character login + WorldSession |
 | 5 | ObjDesc: AnimPartChange + TextureChanges + SubPalettes + ObjScale |
 | 6.1–6.7 | Motion + animation foundation (idle, frame playback, slerp, UpdateMotion, UpdatePosition) |
 | 7.1 | EnvCell room geometry — walls/floors/ceilings |
 | 9.1–9.2 | Translucent render pass + back-face culling |
 | A.1–A.5 | Streaming landblock loader → two-tier streaming |
 | B.1–B.3 | Outbound ack pump + player movement + physics MVP resolver |
 | D.1, D.2a | 2D overlay + ImGui scaffold + `AcDream.UI.Abstractions` layer |
 | E.1–E.5 | Motion hooks + audio + particles + combat wire + spell wire |
 | F.1, F.2 | GameEvent dispatcher + item model + Appraise |
 | G.1, G.2 | Sky + day/night + weather + dynamic lighting |
 | H.1, I.1–I.8 | Chat wire + UI consolidation + holtburger inbound parity + combat translator |
 | K, L.0 | Input architecture + retail bindings + Settings panel |
 | N.0–N.6.1 | WB rendering migration (modern path mandatory) |
 | C.1, C.1.5a/b | Particle system + portal/EnvCell static-script wiring |
 | R.1–R.3 | Retail research infrastructure (PDB extract + named decomp) |
 **Status:** This is everything shipped through 2026-05-12. ~25 phase ships.
 **Worth saying out loud: this is the hard half of the project.** The engine
 runs, the world renders correctly, the network connects, the input is wired,
 the data layers for combat/spells/items/audio/particles all exist. What's
 missing is the gameplay loop on top.
 ---
 ### M1 — "Walkable + clickable world" — ✅ LANDED 2026-05-16
 **Landing writeup (2026-05-16, after Phase B.6 ship `d640ed7`):**
 All four M1 demo targets work end-to-end. You can log into `+Acdream`
 at Holtburg, walk freely without getting stuck (L.2 collision is
 retail-faithful through the doorway). Click any inn door at any
 range, press R, the character runs (or walks if close) toward it
 with the correct animation cycle including the leg-shuffle turn-first
 phase, opens the door via ACE's server-side `MoveToChain` callback.
 Same for clicking an NPC — runs over, body rotates to face, dialogue
 fires from ACE without any client-side retry. Pickup items at any
 range with F or R; spell components, food, money, weapons all work;
 signs and other `BF_STUCK` scenery correctly block at the gate.
 AP cadence matches retail (0 Hz idle, ~1 Hz smooth motion, per-event
 on cell/plane changes). Run/walk threshold matches retail observation
 (1m of distance left to walk). The earlier ladder of workarounds —
 client-side retry, per-frame chatty AP, MoveToState suppression
 grace period — all deleted via the Phase B.6 architectural refactor
 (`d640ed7`). M1's demo path is now bit-for-bit retail-faithful end
 to end.
 **Demo scenario:** Walk through Holtburg without getting stuck on the inn
 doorway. Open the inn door. Click an NPC and see selection feedback. Pick
 up an item from the ground.
 **Demo-target status (as of 2026-05-14):**
 | # | Target | Status | Evidence |
 |---|---|---|---|
 | 1 | Walk through Holtburg without getting stuck | ✅ met | L.2a/d/g shipped 2026-05-12; Holtburg doorway verified |
 | 2 | Open the inn door | ✅ met | B.4b (interaction) + B.4c (swing animation) shipped 2026-05-13 |
 | 3 | Click an NPC and see selection feedback | ✅ met | B.4b chain + chat handlers; verified 2026-05-14 (Tirenia + Royal Guard double-click → NPC dialogue in chat panel) |
 | 4 | Pick up an item from the ground | ✅ met (close-range path) | B.5 + post-B.5 `PickupEvent (0xF74A)` fix shipped 2026-05-14; visual-verified at Holtburg; creature-pickup guard added in `a01ebd5` |
 **Landing artifacts done 2026-05-16:**
 - ✅ Landing writeup pinned at top of this milestone block (above the table).
 - ✅ Freeze list applied (see below).
 - ✅ `CLAUDE.md`'s "currently working toward" advanced to M2.
 **Known polish items deferred to post-M7 (do not gate M1 landing):**
 - **#61** — AnimationSequencer link→cycle frame-0 flash on door swing. LOW.
 - **#62** — PARTSDIAG null-guard. Latent, not reachable today.
 - **#63** — ✅ CLOSED by Phase B.6 (`d640ed7`). Server-initiated
  `MoveToObject` is now honored end-to-end; ACE's `MoveToChain`
  callback fires server-side on arrival.
 - **#64** — Local-player pickup animation does not render (retail
  observers see it correctly). LOW.
 - **#69, #74, #75** — all closed by Phase B.6 (`d640ed7`). Turn-first
  animation, retail-narrow AP cadence, body-direct auto-walk
  architecture.
 **Phases that shipped to clear M1:**
 - **L.2 (a + d + g sub-lanes)** — Movement & Collision Conformance.
  L.2a slices 1+2+3 + L.2d slice 1+1.5 + L.2g slice 1+1b+1c shipped
  2026-05-12 / 2026-05-13. Visual-verified via the B.4b doorway test.
 - **B.4b** — outbound Use + `WorldPicker` + double-click detection +
  `CollisionExemption` widening + `ServerGuid→entity.Id` translation
  (the ID-mismatch trap surfaced during L.2g slice 1c). Shipped
  2026-05-13.
 - **B.4c** — door swing animation: spawn-time `AnimationSequencer`
  registration + stance-value fix (`NonCombat = 0x3D` not `0x01`, which
  had been causing doors to render halfway underground). Shipped
  2026-05-13.
 - **B.5** — `BuildPickUp` (PutItemInContainer 0x0019) + `SendPickUp`
  helper + F-key wiring + new `PickupEvent (0xF74A)` despawn handler.
  Shipped 2026-05-14.
 - **B.5 polish** (`a01ebd5`) — guard `SendPickUp` against creature
  targets so F-on-NPC produces a "Can't pick that up" toast instead of
  the malformed pickup that triggered ACE's `WeenieError 0x0029` + NPC
  emote chain. (Briefly visited adding "You pick up the X." chat /
  toast feedback for ground pickups in `87ba5c9`, then reverted in
  `20ecb23` — retail doesn't show that line for ground pickups; only
  for items received from NPCs / other characters, and that path is
  separate.)
 **Freeze on landing:**
 - L.2 zone (collision, cell ownership, transition parity, wire authority)
 - B.4 zone (interaction outbound)
 - B.5 zone (pickup outbound + inbound despawn)
 **What "M1 lands" looks like:** the existing Holtburg traversal works as a
 retail player would expect. Doorways are walkable. Buildings have solid
 walls. Outdoor cell seams report the right cell. Clicking an NPC selects it
 and produces NPC chat. The Use action opens doors. F picks up items at
 close range and the player sees "You pick up the X." in chat.
 ---
 ### M1.5 — "Indoor world feels right" — 🔵 ACTIVE (building/cellar demo DONE; EXTENDED 2026-06-13 to include dungeon support / Phase G.3)
 **EXTENDED 2026-06-13 — dungeons pulled into M1.5 scope.** The
 building/cellar demo (below) is DONE + user-gated, but attempting the
 dungeon demo surfaced that dungeons don't work AT ALL: terrain-less
 dungeon landblocks aren't supported anywhere in the streaming/load/
 render/physics pipeline (`LandblockLoader.Load` returns null with no
 `LandBlock` terrain record; the streamer fails with no terrain mesh; the
 teleport snap Resolves before hydration — issue #133). The user decided
 M1.5 is NOT done while the indoor world excludes dungeons, and chose the
 FULL Phase G.3 scope (dungeon streaming + portal-space loading screen +
 multi-landblock dungeon LOD + `PlayerTeleport` handling). Design in
 progress (`docs/superpowers/specs/` — dungeon-support spec). M1.5 lands
 when: building/cellar demo (DONE) + dungeon demo (enter via portal,
 navigate 3-5 rooms, walls block, smooth transitions) both pass.
 **Building/cellar demo — DONE + user-gated.** The indoor world reads as
 solid. Across the
 2026-06 sessions the holistic retail-faithful render port (Option A: ONE
 `DrawInside(viewer_cell)`, no inside/outside branch — BR-2..BR-7 / T1..T6)
 shipped and was user-gated, and the indoor physics/membership family was
 brought to retail fidelity (the A6.P4 per-cell shadow architecture; the
 #107/#111/#112 spawn + membership fixes; the cellar-lip wedge). End-to-end,
 user-gated this milestone: walk into a building and climb a multi-floor inn
 without sling-out or wall-clip; descend a cottage cellar and ascend it
 without falling through (the #98 + cellar-lip + #108 grass-window closes);
 walls block everywhere (indoor + stab-shell, the #99 door run-through
 closed); cell transitions are smooth (the doorway "flap" family killed —
 #119/#128, #112, #113, #124, #129/#130/#131/#132, #108-residual, #127 all
 closed with user gates). The #90-stickiness + `TryFindIndoorWalkablePlane`
 synthesis workarounds were removed by A6.P4. Remaining feel-level debt is
 tracked (#116 slide-response, partial Ghidra fix shipped; A7 indoor
 lighting fidelity not yet done — folded forward).
 **Still OPEN in M1.5 — dungeon support (Phase G.3, issue #133).** Dungeons
 don't work: the streaming/load/render/physics pipeline was built entirely
 around outdoor landblocks (terrain + scattered buildings) and has no path
 for terrain-less indoor-only dungeon landblocks. Confirmed gaps:
 `LandblockLoader.Load` returns null with no `LandBlock` record; the
 streamer fails with no terrain mesh; the teleport-arrival snap Resolves
 before the dungeon hydrates → places the player in the old frame over
 ocean. Full G.3 scope chosen by the user 2026-06-13 (streaming + portal-
 space loading screen + multi-landblock LOD + `PlayerTeleport` handling).
 Spec under `docs/superpowers/specs/`.
 ---
 #### (historical M1.5 working notes below)
 🔵 ACTIVE (resumed 2026-05-21 after Phase O ship)
 **2026-05-30 — render-pipeline pivot.** The indoor *rendering* seam (seamless
 in/out: the flap, missing/transparent walls, terrain bleed) will be solved by a
 **single unified retail-faithful render pipeline (Phase U)**, replacing the
 abandoned two-pipe inside/outside split (A8/A8.F, issue #103). The two-pipe split
 is a WorldBuilder inheritance; retail uses one portal-visibility pass and is
 seamless by construction. Decision + scope:
 [`docs/research/2026-05-30-unified-render-pipeline-decision-and-handoff.md`](../research/2026-05-30-unified-render-pipeline-decision-and-handoff.md).
 Camera-collision + a physics viewer-cap fix shipped 2026-05-30 and are kept (they
 were a detour from the real seam fix, but retail-faithful and worth keeping). A6
 (physics) and A7 (lighting) are unaffected.
 **Phase O — DatPath Unification — shipped 2026-05-21.** ONE thing
 touches the DATs. ~33 WB files (~7.7K LOC) extracted into
 `src/AcDream.{Core,App}/Rendering/Wb/`; project references to
 `WorldBuilder.Shared` + `Chorizite.OpenGLSDLBackend` dropped;
 `DefaultDatReaderWriter` eliminated. Visual side-by-side passed at
 Holtburg town, inn interior, and dungeon. Phase O pre-empted M1.5
 per user direction 2026-05-21; M1.5 now resumes from the 2026-05-20
 baseline with no code changes lost — Phase O did not touch dat-loading
 infrastructure for physics or collision, only the rendering pipeline.
 M1.5's planned phases (A6 + A7) are unaffected.
 **Demo scenario (updated 2026-05-21):** The original demo target was
 "enter the Holtburg Sewer dungeon" but that location doesn't exist on
 this ACE server (discovered during A6.P1 capture session). Additionally,
 A6.P1 surfaced **issue #95** (portal-graph visibility blowup) which makes
 ANY dungeon visually unusable on entry. Demo scenario revised in two
 parts:
 **Building/cellar demo (achievable after A6.P3 lands):**
 Walk into the Holtburg inn, climb to the 2nd floor, walk around without
 sling-out or wall-clip. Enter a cottage cellar, descend without falling
 through. Throughout:
 - Walls block — no walk-through anywhere, indoor or stab-shell.
 - Stairs work — ascend + descend without falling through or stuck-in-falling.
 - Items block — furniture, decorations.
 - Cell transitions are smooth — no CellId ping-pong, no flicker.
 - Lighting reads correctly — torchlit rooms are bright, no spotlight
  artifacts, static decorations participate in env lighting.
 **Dungeon demo (blocked on issue #95 fix; promote to post-M1.5 if
 the visibility bug isn't addressed in M1.5 scope):**
 Enter any dungeon via portal (substitute for "Holtburg Sewer"). Navigate
 ~3-5 rooms without rendering corruption (no see-through-walls, no
 other-dungeons-rendered-inside). Walls block, stairs work, items block,
 lighting correct, cell transitions smooth.
 **Why this is its own milestone:** M1 landed walkable + clickable as a
 specification (the doorways open, NPCs select, items pick up — all visible
 in the demo target). But continued indoor testing surfaced a deep family of
 physics + lighting bugs (BSP push-back distance probably diverges from
 retail, per-frame ContactPlane synthesis is a known unfaithful stop-gap,
 indoor lighting + item-spotlight bugs reported during 2026-05-21 sessions).
 Three workarounds shipped today (#89 sphere-overlap CheckBuildingTransit,
 #90 sphere-overlap stickiness, #92 spawn-cell-id seed) closed the visible
 symptom at Holtburg inn, but #90 specifically is a CLAUDE.md-rules
 workaround (explicit retail divergence) that needs a proper root-cause fix.
 The umbrella indoor-physics issue (#83) has been open since 2026-05-19 with
 multiple aborted fix attempts. Promoting this to milestone scope forces the
 fix to be central, retail-anchored, and complete — not another whack-a-mole
 patch.
 **Phases included:**
 | Phase | What it does |
 |---|---|
 | A6 — Indoor physics fidelity (cdb-driven) | Capture retail's per-tick BSP collision response state at 9 scenarios (4 buildings + 5 dungeon sites). Analyze the gap vs ours. Fix BSP correction paths. Remove #90 stickiness + `TryFindIndoorWalkablePlane` synthesis workarounds. |
 | A7 — Indoor lighting fidelity (RenderDoc + retail-decomp) | Capture per-cell light state + per-pixel attribution at the same 9 scenarios. Analyze cell-light association, visibility culling, per-entity light direction. Fix indoor lighting + #80 (upper-floor dark) + #81 (static-stab atmospheric) + the held-item-spotlight bug. |
 **Issues in scope (M1.5):**
 - **#80** — Camera on 2nd floor goes very dark
 - **#81** — Static building stabs don't react to atmospheric lighting
 - **#83** — Indoor multi-Z walking broken (cellars, 2nd floors, intermittent falling-stuck)
 - **#88** — Indoor static objects vibrate (suspected sub-step state corruption — A6.P2 maps to Finding 2 family)
 - **#90** — CellId ping-pong (workaround in place; remove during A6.P4)
 - **#95** — Portal-graph visibility blowup (filed 2026-05-21; **blocks the dungeon half of the M1.5 demo** but is NOT in A6 scope; either add a dedicated phase inside M1.5 to fix it OR promote the dungeon demo to post-M1.5)
 - **L-indoor** — Lighting indoors broken (file as new # during M1.5 kickoff)
 - **L-spotlight** — Items projecting spotlight on walls (file as new # during M1.5 kickoff)
 - **Stairs walk-through** — captured + characterized by A6.P2 (Finding 2 family); fix in A6.P3
 - **2nd-floor walking** — captured + characterized by A6.P2 (Finding 2 — scen3 shows infinite CP-write ratio on flat 2nd-floor walk); fix in A6.P3
 - **Cellar descent** — same physics family as stairs; fix in A6.P3
 - **Indoor sling-out** (new symptom from A6.P1 scen4) — captured + mapped to A6.P2 Finding 3 (cell-resolver in ResolveCellId / CheckBuildingTransit); fix in A6.P3
 - **`TryFindIndoorWalkablePlane`** — synthesis workaround removal (Bug A's original goal, finally unblocked; A6.P4)
 **Frozen phases during M1.5:** all M0 + M1 phases stay frozen. Plus
 specifically the recently-shipped A4 + #89 + #91 + #92 (today's work) — those
 land in main as the M1.5 baseline and shouldn't be revisited except as part
 of A6.P4 removal of the workarounds.
 **Estimated timeline:** 3–5 weeks calendar (17–26 days focused work). Bigger
 than a normal milestone because lighting is open-ended (less existing
 diagnostic infrastructure than physics). Could be shorter if the cdb
 analysis surfaces a single-fix opportunity.
 **What "M1.5 lands" looks like:** the indoor world reads as solid. Players
 can navigate buildings, basements, multi-floor inns, and dungeons without
 encountering walls they walk through, lighting that looks wrong, or
 position glitches. The two known workarounds (#90 stickiness +
 TryFindIndoorWalkablePlane synthesis) are removed; the codebase no longer
 has indoor-physics "duct-tape." Dungeons are usable enough to support M2's
 "kill a drudge" demo target (drudges live in dungeons; this milestone
 unblocks that).
 ---
 ### M2 — "Kill a drudge" — ⏸ DEFERRED until M1.5 lands (incl. dungeons)
 **Demo scenario:** Equip a sword. Walk to a drudge. Swing. See "You hit
 Drudge for 12 slashing damage (87%)" in chat. Watch the swing animation
 play. Drudge dies, drops loot. Pick up the loot. Open the inventory panel
 and see it.
 **First port target when M2 starts (per the M2 combat-math research memo,
 `docs/research/2026-06-04-combat-math-deep-dive.md`):**
 `CombatMath.ComputeDamage` — damage-calc + armor-resists are port-ready
 (ACE is the high-confidence oracle; two known scaffold bugs in
 `CombatModel.cs` identified — additive attributeBonus + subtractive armor).
 Hit-roll is well-documented client-side; the server sigmoid/crit +
 weapon-timing (the x87 `GetPowerBarLevel` artifact) come after. NOTE: M2
 was briefly started 2026-06-13 then re-deferred when M1.5 was extended to
 include dungeons.
 **Phases to ship:**
 - **F.2 (panels)** — Inventory panel reading `ItemRepository` (data already
  shipped in F.2 base; M2 ships the visual surface).
 - **F.3** — Combat math + damage flow.
 - **F.5a** — Visible-at-login dev panels (Attributes, Skills, Equipped,
  Inventory list) — minimal ImGui surfaces, retail-skin deferred to M5.
 - **L.1c** — Combat animation wiring (draw/sheath, attack swings by
  stance/power/height, hit reactions, evades).
 - **L.1b** — Command router + motion-state cleanup (prereq for L.1c).
 **Freeze on landing:**
 - Combat math zone
 - Inventory zone (data + dev panel; retail-skin reopens in M5)
 - L.1b/c combat-animation zone
 **What "M2 lands" looks like:** the gameplay loop is real. You can fight,
 take damage, kill things, see loot, manage your inventory. The game becomes
 a game.
 ---
 ### M3 — "Cast a spell" — 🔵 (~3–4 weeks after M2)
 **Demo scenario:** Cast Flame Bolt at a drudge. Watch the cast animation,
 the projectile, the impact. Self-cast a buff (Strength Self). See the
 enchantment in a buff list. Recall to lifestone — full recall animation,
 correct teleport, correct re-spawn.
 **Phases to ship:**
 - **F.4** — Spell cast state machine (buffs + recalls first, projectile
  spells second).
 - **L.1d** — Spell-casting animation wiring (cast command classification,
  windup, release, fizzle/interruption, recoil).
 - **F.5 (Spellbook panel)** — dev-skin surface for learned spells + active
  enchantments.
 **Freeze on landing:**
 - F.4 spell zone
 - L.1d cast-animation zone
 - Spellbook dev-panel surface
 **What "M3 lands" looks like:** mages are real characters. Buffs work,
 recalls work, the first projectile spells work. Combat from M2 + casting
 from M3 = retail-equivalent gameplay loop for melee and casters.
 ---
 ### M4 — "Live in the world" — 🔵 (~6–10 weeks)
 **Demo scenario:** Create a fresh character from scratch (no ACE admin).
 Spawn. Talk to an NPC. Accept a quest. Walk to a dungeon entrance. Portal
 in (pink-bubble loading). Walk through the dungeon. Complete the quest.
 Walk back out.
 **Phases to ship:**
 - **H.3** — Emote scripts + quests + dialogs (122 EmoteType × 39 Trigger
  mini-VM).
 - **G.3** — Dungeon streaming + portal space + `PlayerTeleport` handling.
  (Unblocked by L.2e from M1.)
 - **H.4** — Character creation (`0xE000002 CharGen` + heritages + appearance
  picker + preview).
 - **L.1e** — Emote + posture animation wiring.
 **Freeze on landing:**
 - H.3 dialog/quest zone
 - G.3 dungeon zone
 - H.4 character-creation zone
 - L.1e emote-animation zone
 **What "M4 lands" looks like:** the world feels populated and interactive.
 You can do quests, enter dungeons, create characters. Combined with M2/M3,
 the client is **functionally playable** — minus visual polish.
 ---
 ### M5 — "Looks like retail" — 🟢 PARALLELIZABLE WITH M3/M4 (~4–8 weeks)
 **Demo scenario:** Side-by-side screenshot of acdream vs retail at the same
 location, same time of day, same character. Hard to tell apart at a glance.
 Open the inventory panel — retail-skinned with the right font, icons, and
 9-slice panel borders.
 **Phases to ship:**
 - **C.1.5c** — Sky-PES dispatch chain (closes #2 lightning, #28 aurora,
  #29 cloud thinness).
 - **C.2** — Dynamic point lights (fireplaces, lamps, torches with proper
  local lighting).
 - **C.3** — Palette range tuning (skin/hair/eye colors match retail).
 - **C.4** — Double-sided translucent polys.
 - **D.2b** — Custom retail-look UI backend.
 - **D.3–D.7** — AcFont + dat sprites + core panels reskinned + HUD orbs +
  cursor manager.
 - **L.1f** — NPC/monster + item-use animation coverage.
 **Freeze on landing:**
 - Visual polish zone (C.1.5c, C.2, C.3, C.4)
 - D.2b → D.7 UI-skin zone
 - L.1f NPC-anim zone
 **What "M5 lands" looks like:** the client visually convinces. Screenshots
 become postable. The "old / broken vs retail" feeling that drives most of
 the chronic ISSUES.md entries is gone.
 ---
 ### M6 — "Plugins ship" — 🟢 (~4 weeks)
 **Demo scenario:** A third party (not you) writes a small plugin against
 the published API — XP tracker, loot logger, simple chat filter — and it
 loads cleanly. Sample plugin lives in the repo with documented build steps.
 **Phases to ship:**
 - Plugin API surface: stable contract over `AcDream.Core` + `AcDream.UI.Abstractions`,
  versioned, with the world-state interfaces exposed.
 - Plugin host: load isolation, lifecycle, error containment.
 - Sample plugin (XP tracker or loot logger) — proves the API by using it.
 - Plugin docs page.
 **Freeze on landing:**
 - Plugin API v1 surface (additive changes only post-freeze).
 **What "M6 lands" looks like:** the differentiator vs the retail client is
 real. acdream offers something retail never did, and the API is documented
 well enough that other people can build on it.
 ---
 ### M7 — "v1.0" — 🟢 (open-ended polish)
 **Demo scenario:** Long-running stress test: log in, play for 4 hours
 across outdoor + dungeon + portal + combat + spell + chat scenarios,
 reconnect once mid-session, log out clean. No crashes, no protocol errors,
 no visual regressions, no audio dropouts.
 **Phases to ship:**
 - **Phase M** — Network stack conformance (retransmit, ACK piggybacking,
  echo/keepalive, fragment splitting, typed actions). Deferred until now
  because ACE handles loss gracefully — but v1.0 needs proper network
  hardening.
 - **H.2** — Allegiance.
 - **N.6 slice 2 + N.7–N.10** — Finish WB rendering migration (EnvCells,
  sky/particles via WB, visibility manager, GL infrastructure
  consolidation).
 - **Phase J long-tail** — Player rig polish, group/fellowship UI, trade
  window, salvage/tinker UI, house ownership, society UI, dev-mode tools.
 - **L.1g** — Animation polish + conformance.
 - Final visual + audio polish pass against ISSUES.md chronic backlog.
 **What "M7 lands" looks like:** v1.0. Ship.
 ---
 ## Estimated timeline
 | Milestone | Effort | Cumulative |
 |---|---|---|
 | M0 | DONE | DONE |
 | M1 | ~4–6 wk | ~5 wk |
 | M2 | ~6–10 wk | ~13 wk |
 | M3 | ~3–4 wk | ~17 wk |
 | M4 | ~6–10 wk | ~25 wk |
 | M5 | ~4–8 wk (parallel) | overlaps M3/M4 |
 | M6 | ~4 wk | ~29 wk |
 | M7 | open-ended | v1.0 |
 **Roughly 9–12 months of focused solo work from 2026-05-12 to v1.0.** That's
 honest for an open-source project of this scale. The biggest single rock is
 M2 (combat math + animations + inventory panels lining up); M5 can be
 chipped at in parallel by subagents while you drive M3/M4.
 ---
 ## What this document is **not**
 - **Not a release schedule.** Internal morale + scope layer only. If acdream
  goes public-alpha at some point, that's a separate decision built on top
  of one of these milestones.
 - **Not immutable.** When reality and the milestones diverge, update the
  milestones in the same session you discover the divergence. Same rule as
  the roadmap.
 - **Not a replacement for the roadmap.** Phases are still where the
  implementation details live. This doc is the orientation layer above them.
 - **Not granular enough for daily work.** Daily work happens at the phase /
  sub-phase / commit level. The milestone is the multi-week target you're
  aiming at.
--- a/docs/plans/2026-05-12-phase-c1.5b-handoff.md
+++ b/docs/plans/2026-05-12-phase-c1.5b-handoff.md
@ -1,320 +0,0 @@
 # Phase C.1.5b handoff — issue #56 + EnvCell statics + animation-hook verification
 **Created:** 2026-05-12, immediately after Phase C.1.5a merged to `main` (commit `88bda12`).
 **Audience:** the fresh-session Claude (or human) picking up C.1.5b.
 **Predecessor:** [C.1.5a portal PES wiring](../superpowers/specs/2026-05-12-phase-c1.5a-portals-design.md) — slice 1, shipped.
 ---
 ## §1 Startup prompt (copy this into a fresh session)
 Everything below this fence is the prompt to paste into a new Claude Code session. The detailed context the session needs lives in §2+ of this same file.
 ```
 Pick up Phase C.1.5b — issue #56 (multi-emitter per-part collapse) first,
 then EnvCell static-object DefaultScript dispatch + animation-hook
 particle path verification.
 ## Context
 Phase C.1.5a (portal PES wiring) merged to main 2026-05-12 (merge commit
 88bda12). The PhysicsScriptRunner now fires Setup.DefaultScript on every
 server-spawned WorldEntity via the new EntityScriptActivator. Visual
 verification at the Holtburg Town network portal confirmed the mechanism
 works end-to-end (10-hook portal script fires correctly, color +
 persistence + orientation match retail), but exposed a pre-existing C.1
 limitation now tracked as ISSUE #56: ParticleHookSink ignores
 CreateParticleHook.PartIndex, so all 10 of the portal's emitters
 collapse to one root position → compressed, partly-ground-buried swirl.
 The C.1.5a final cross-task reviewer recommended #56 be resolved FIRST
 in this slice, before the EnvCell static-object walker, because slice
 2's natural visual gate (Holtburg inn interior fireplace, cottage
 chimney) uses the same multi-emitter pattern — without #56 fixed,
 slice 2 ships with the same visual gap.
 ## Read first (in order)
 1. docs/plans/2026-05-12-phase-c1.5b-handoff.md (this file's §2+)
 2. docs/ISSUES.md #56 (the per-part collapse problem with reproducible
   identifiers from the C.1.5a verification session)
 3. docs/superpowers/specs/2026-05-12-phase-c1.5a-portals-design.md §10
   (slice 2 preview written during C.1.5a brainstorming)
 4. docs/plans/2026-04-27-phase-c1-pes-particles.md lines 285–295 (the
   original C.1.5 scope source)
 ## Two slices in this session
 ### Slice A — issue #56 fix (per-part transform handling for static entities)
 For static entities (portals, EnvCell statics, building decorations —
 no animation), precompute the per-part offset from
 Setup.PlacementFrames[Resting] at spawn time and surface those offsets
 to the ParticleHookSink so SpawnFromHook can apply them. The handoff
 doc §3 has the suggested architecture + decision space.
 Acceptance: relaunch + walk to the Holtburg Town network portal. The
 10 emitters should distribute across the portal Setup's parts instead
 of collapsing — swirl extends vertically through the arch with
 retail-like shape, not buried in the ground.
 ### Slice B — EnvCell static-object DefaultScript dispatch + animation-hook verification
 Walk EnvCell.StaticObjects for newly-loaded landblocks; for each
 StaticObject whose Setup has a non-zero DefaultScript, fire the
 activator with a synthetic entity ID (suggested scheme: hash of
 (landblockId, cellIndex, staticIndex) with a high-bit marker so it
 doesn't collide with server guids — see handoff §4). Then verify the
 animation-hook particle path (already shipped in C.1; just needs
 visual confirmation): cast a spell on +Acdream and compare to retail.
 Acceptance: Holtburg inn fireplace flames, cottage chimney smoke, and
 a spell-cast particle effect on +Acdream all match retail.
 ## What this is NOT
 - Not a renderer change. particle.frag stays as-is; bindless migration
  waits for N.6 slice 2 after this slice lands.
 - Not a perf phase. The N.6 baseline at radius=4 still holds; the
  per-part precompute cost is bounded by N parts × M emitters per
  spawned entity (small).
 - Not adding new emitter types. Use the existing PES emitter data.
 - Not touching the animated-entity path. For animated entities (NPCs,
  monsters), per-part transforms vary per frame and would need a
  per-tick refresh similar to UpdateEntityAnchor. Defer to a future
  phase; C.1.5b stays scoped to static entities only.
 ## Suggested workflow
 1. Read the handoff doc + the four referenced docs above.
 2. Invoke superpowers:brainstorming to settle:
   - For slice A: precompute-per-part-at-spawn vs render-thread-side-table
     approach (handoff §3 has the tradeoff analysis).
   - For slice B: the synthetic-entity-id scheme; whether the EnvCell
     walker piggybacks LandblockSpawnAdapter or gets its own class.
   - Visual verification locations.
 3. After brainstorm: spec at
   docs/superpowers/specs/2026-05-13-phase-c1.5b-design.md (one spec
   for both slices since they share the activator and tests), then plan
   at docs/superpowers/plans/2026-05-13-phase-c1.5b.md, then execute
   via superpowers:subagent-driven-development.
 ## Open issues from C.1.5a worth knowing
 - #56 — multi-emitter per-part collapse. This slice's headline.
 - #55 — meshMissing diagnostic spam at radius=4 standstill. LOW
  severity, not blocking; only touch if you're already in the
  dispatcher for unrelated reasons.
 - Cold-path timing observation (C.1.5a Task 2 review): the activator
  fires DefaultScript before pending-bucket entities are merged into
  a loaded landblock. Mirrors existing _wbEntitySpawnAdapter pattern;
  not a regression; defer.
 ## Three doc-drift items from C.1.5a (trivial — fold into the new spec)
 1. C.1.5a spec §4 says "fifth (optional) parameter" — actually fourth.
 2. C.1.5a spec §4 says "~50 lines" — file ships at 93 lines.
 3. GpuWorldState.AddEntitiesToExistingLandblock (A.5 Far→Near
   promotion path) does not fire the activator. No-op today because
   promotion-tier entities are atlas-tier and the activator's
   ServerGuid==0 guard would skip them anyway, but worth a code
   comment explaining why the call is intentionally omitted there
   (parallel to existing comments at the RemoveEntitiesFromLandblock
   block in the same file).
 Start by reading the handoff doc, then ask me what slice-A/slice-B
 boundary feels right and what visual verification locations I want
 to target.
 ```
 ---
 ## §2 What shipped in C.1.5a (so you don't re-do it)
 ### Commits on `main` (oldest to newest under merge `88bda12`)
 | SHA | Title |
 |---|---|
 | `06d7fbd` | docs(vfx): Phase C.1.5a — portal PES wiring design spec |
 | `ed5335b` | docs(vfx #C.1.5a): implementation plan + spec wiring-location fixes |
 | `003c502` | feat(vfx #C.1.5a): add EntityScriptActivator (no wiring yet) |
 | `e0529b0` | test(vfx #C.1.5a): real-emitter verification in OnRemove test + unused using |
 | `44d8502` | feat(vfx #C.1.5a): wire EntityScriptActivator into GpuWorldState lifecycle |
 | `65d833d` | feat(vfx #C.1.5a): construct EntityScriptActivator in GameWindow |
 | `849690c` | refactor(vfx #C.1.5a): reuse SequencerFactory's capturedDats in resolver |
 | `334f0c6` | fix(vfx #C.1.5a): seed entity rotation in activator so hook offset rotates |
 | `9009318` | docs(vfx #C.1.5a): ship Phase C.1.5a + file issue #56 for per-part collapse |
 | `88bda12` | Merge branch 'claude/lucid-burnell-aab524' — Phase C.1.5a |
 ### New files
 - [`src/AcDream.App/Rendering/Vfx/EntityScriptActivator.cs`](../../src/AcDream.App/Rendering/Vfx/EntityScriptActivator.cs) — 93 lines including doc comments. Constructor `(PhysicsScriptRunner, ParticleHookSink, Func<WorldEntity, uint>)`; `OnCreate(WorldEntity)` resolves the entity's `Setup.DefaultScript.DataId`, seeds `_particleSink.SetEntityRotation(entity.ServerGuid, entity.Rotation)`, and calls `_scriptRunner.Play(scriptId, entity.ServerGuid, entity.Position)`; `OnRemove(uint serverGuid)` calls `_scriptRunner.StopAllForEntity(serverGuid)` + `_particleSink.StopAllForEntity(serverGuid, fadeOut: false)`.
 - [`tests/AcDream.Core.Tests/Rendering/Vfx/EntityScriptActivatorTests.cs`](../../tests/AcDream.Core.Tests/Rendering/Vfx/EntityScriptActivatorTests.cs) — 4 xUnit `[Fact]` tests with mutation-check teeth verified during the C.1.5a code-quality reviews.
 ### Modified files
 - [`src/AcDream.App/Streaming/GpuWorldState.cs`](../../src/AcDream.App/Streaming/GpuWorldState.cs) — fourth optional ctor parameter `EntityScriptActivator? entityScriptActivator = null`, field `_entityScriptActivator`, and two `?.OnCreate(entity)` / `?.OnRemove(serverGuid)` calls immediately after the matching `_wbEntitySpawnAdapter?.OnCreate` / `?.OnRemove` calls in `AppendLiveEntity` and `RemoveEntityByServerGuid`.
 - [`src/AcDream.App/Rendering/GameWindow.cs`](../../src/AcDream.App/Rendering/GameWindow.cs) — new field declaration alongside `_wbEntitySpawnAdapter` and inline construction of the activator + resolver lambda inside the existing `OnLoad` block (~line 1620), passed to `GpuWorldState` as a named argument.
 ### What's working
 - Server-spawned entities (`ServerGuid != 0`) with `Setup.DefaultScript.DataId != 0` fire that script through `PhysicsScriptRunner.Play` on enter-world.
 - Multi-hook scripts dispatch all their hooks in order (timed by `StartTime` offsets — more retail-faithful than WB's "all at once" collection).
 - `CreateParticleHook.Offset.Origin` rotates correctly from entity-local to world frame via the activator's `SetEntityRotation` seed.
 - Despawn cleanly stops all scripts + emitters for the entity.
 - 4 unit tests cover all three branches plus the rotation-seed correctness.
 - Visual verification at the Holtburg Town network portal passed for the mechanism: 10-hook portal script fires correctly with matching color, persistence, orientation, multi-emitter dispatch.
 ## §3 Issue #56 decision space (slice A)
 ### The problem
 `ParticleHookSink.SpawnFromHook` computes:
 ```csharp
 var rotation = _rotationByEntity.TryGetValue(entityId, out var rot) ? rot : Quaternion.Identity;
 var anchor = worldPos + Vector3.Transform(offset, rotation);
 ```
 …where `worldPos` is `entity.Position` and `offset` is `cph.Offset.Origin`. The `CreateParticleHook.PartIndex` field is recorded into the per-handle tracking dict but never applied to the anchor. Retail's intended geometry is:
 ```
 anchor = entityWorldPose × partLocalTransform[partIndex] × hookOffsetInPartLocal
 ```
 Without the part transform multiplication, every emitter in a multi-emitter script lands at the same root position. Visible symptom: the Holtburg portal's 10 emitters compress to one point and the swirl appears partially buried because the offset's local-up direction goes off in world axes instead of the part's local axes.
 ### Where part transforms come from
 For STATIC entities (no animation), per-part transforms come from `Setup.PlacementFrames[Resting].Frames[partIndex]` — see how `ObjectMeshManager.CollectParts` walks them in `references/WorldBuilder` (worktree-relative path; submodule must be initialized to read):
 - For each `i` in `0..setup.Parts.Count`, the per-part transform is `Matrix4x4.CreateScale(setup.DefaultScale[i]) * Matrix4x4.CreateFromQuaternion(placementFrame.Frames[i].Orientation) * Matrix4x4.CreateTranslation(placementFrame.Frames[i].Origin)`.
 - `DefaultScale` only applies when `SetupFlags.HasDefaultScale` is set.
 - Fall back to `PlacementFrames[Default]` if `Resting` isn't present.
 For ANIMATED entities (NPCs, monsters, the player), per-part transforms vary per animation frame and live in `AnimatedEntityState` / the animation tick. **Out of scope for C.1.5b.**
 ### Approach options
 **Option A — precompute per-spawn, pass at activator-call time.**
 `EntityScriptActivator` reads the Setup's `PlacementFrames[Resting]` once per spawn, builds a `Matrix4x4[] partTransforms` array, and passes it to a new sink method `_particleSink.SetEntityPartTransforms(entityId, partTransforms)` before calling `_scriptRunner.Play(...)`. `ParticleHookSink.SpawnFromHook` then reads `_partTransformsByEntity` to apply per-hook:
 ```csharp
 var partXf = _partTransformsByEntity.TryGetValue(entityId, out var pts) && partIndex < pts.Length
    ? pts[partIndex] : Matrix4x4.Identity;
 var anchor = worldPos + Vector3.Transform(Vector3.Transform(offset, partXf), rotation);
 ```
 Pros: clean ownership (activator owns the lifecycle of part transforms keyed by entityId), matches existing sink-state patterns (`_rotationByEntity`, `_renderPassByEntity`), small code surface, fully testable.
 Cons: stores per-entity array (matrix per part) — bounded but allocates. Doesn't compose with the animated-entity case (which would need per-tick refresh).
 **Option B — render-thread side-table populated by the dispatcher.**
 The `WbDrawDispatcher` already computes per-part world transforms each frame. Surface them via a side-table the sink queries. Per-frame.
 Pros: free composition with animated entities (the dispatcher transforms whether the entity is animated or not).
 Cons: render-thread / sink-thread coordination concern, bigger architectural surface, the dispatcher would need a new responsibility (publish part transforms) outside its draw-loop hot path. Risk of touching the modern bindless dispatcher's perf budget that N.5/N.5b worked to lock in.
 **Option C — sink-side dat lookup on demand.**
 `ParticleHookSink` calls `_dats.Get<Setup>(...)` on the hook fire to look up the part transform. Pros: zero state on activator. Cons: introduces dat coupling into the sink (currently dat-free), per-hook-fire dat lookup is a hidden allocation, doesn't compose with animated entities either, and we'd be reading the same Setup multiple times for the same entity.
 ### Recommended approach
 **Option A.** It's the smallest surface, matches the existing sink-state pattern, doesn't expand any other layer's responsibilities, and the "doesn't compose with animated entities" downside is intentional — animated entities are explicitly out of scope and will get their own treatment later, possibly via Option B at that time.
 ### Test approach
 Mirror the C.1.5a `OnCreate_SetsEntityRotationForHookOffsetTransform` test: construct an entity whose Setup has 2 parts (root at origin + part 1 lifted at (0, 0, 1)), fire a CreateParticleHook with `PartIndex=1` and `Offset.Origin=(0, 0, 0)`, assert the spawned particle's world position is `(0, 0, 1)` (the part's offset, not the root). Add a mutation check: delete the `SetEntityPartTransforms` line and confirm the test fails.
 ## §4 EnvCell static-object dispatch decision space (slice B)
 ### The problem
 `EnvCell.StaticObjects` are interior decoration objects inside dungeon / building cells. Each StaticObject has a Setup reference and a placement frame. They have NO `ServerGuid` — they're dat-hydrated, not server-spawned.
 Our `EntityScriptActivator.OnCreate` early-returns when `entity.ServerGuid == 0` (atlas-tier guard). So as-is, the activator won't fire DefaultScript for EnvCell statics.
 ### Two architectural questions
 **Q1 — synthetic entity ID for tracking + cleanup.**
 `PhysicsScriptRunner` keys active scripts by `(scriptId, entityId)`. `ParticleHookSink` keys per-entity emitter handles by `entityId`. EnvCell statics need a stable, unique 32-bit ID for these tables that won't collide with server guids (and won't collide between two EnvCell statics in different cells).
 Suggested scheme:
 ```
 uint syntheticId = 0xC0000000u
                 | ((landblockId & 0x0000FF00u) << 16)   // landblock X byte → bits 24-31 minus high marker
                 | ((landblockId & 0xFF000000u) >> 8)    // landblock Y byte → bits 16-23
                 | ((cellIndex   & 0x0000FFFFu) << 0);   // bits 0-15: cell index within landblock
 ```
 …leaving 4 bits for the static-object index within the cell. Adjust bit layout for the actual `(LandblockId, CellIndex, StaticIndex)` distribution. The `0xC0_______u` marker is **above** server guid range and **above** the anonymous-emitter range (`0x80_______u`) used by `ParticleHookSink._anonymousEmitterSerial`, so no collision.
 Sanity check: `WorldEntity.ServerGuid` is `uint`; the `(scriptId, entityId)` dedupe key in the runner only needs uniqueness, not semantic meaning. Either scheme works as long as it's collision-free.
 **Q2 — which adapter walks EnvCell.StaticObjects?**
 Three options:
 - **Option α — piggyback `LandblockSpawnAdapter`.** That adapter already walks `landblock.Entities` for atlas-tier mesh-ref counting. Extending it to also walk `EnvCell.StaticObjects` and fire DefaultScript via the activator keeps the per-landblock-load flow in one place. Cons: blurs the adapter's single responsibility.
 - **Option β — new `EnvCellStaticActivator` class.** Mirror `EntityScriptActivator`'s shape but key by synthetic-id, walking each loaded landblock's EnvCells on load and firing per-static-object. Cons: more code; slight duplication of the activator pattern.
 - **Option γ — `EntityScriptActivator` learns a "static-object" entry point.** Add `OnEnvCellStaticCreate(LoadedLandblock landblock, int cellIndex, int staticIndex, Setup setup, Vector3 worldPos, Quaternion worldRot)` to the existing activator. Compute the synthetic ID inside. Cons: signature creep on the activator.
 Recommended: **Option β.** Keeps the existing activator's `WorldEntity`-shaped contract pure; the new class has a clean per-static-object contract; both share `_scriptRunner` and `_particleSink` instances so no architectural duplication, just two thin orchestrators.
 ### Lifecycle
 EnvCell statics live as long as their parent landblock is loaded. On landblock unload, the new activator should stop all scripts for all its synthetic IDs from that landblock. Mirror `LandblockSpawnAdapter`'s `OnLandblockLoaded` / `OnLandblockUnloaded` lifecycle.
 ## §5 Animation-hook verification (slice B's quick half)
 Already shipped in C.1: `MotionInterpreter` fires per-keyframe hooks through `IAnimationHookSink` → `ParticleHookSink`. We just haven't verified visually in the current codebase state.
 Procedure:
 1. Cast a spell on `+Acdream` (the test character likely has at least one spell + components configured — check or grant if needed).
 2. Watch the cast-anim particle effect (sparkles, glyphs, etc.) — does it match retail's casting animation?
 3. Optional: trigger an emote with a particle hook (the `\dance` / `\drink` emotes are good candidates if they have particle data).
 If broken, file an issue with the symptom. If working, mark slice B complete on verification.
 ## §6 Verification locations
 All in or near Holtburg, within ~30s of `+Acdream`'s spawn:
 - **#56 fix re-verify** — the Town network portal used in C.1.5a. Same procedure as C.1.5a's Task 4 (see [the C.1.5a spec §8](../superpowers/specs/2026-05-12-phase-c1.5a-portals-design.md)).
 - **EnvCell chimney** — any cottage / inn within the Holtburg outer perimeter with a smoking chimney in retail. Confirm via dual-client.
 - **EnvCell fireplace** — Holtburg Inn interior. Walk inside and stand near the fireplace. Confirm flame particles match retail.
 - **Animation-hook verify** — cast a spell standing somewhere safe (outside any aggro range). Compare to retail.
 ## §7 File pointers for slice 2
 - Particle pipeline (Core): [`src/AcDream.Core/Vfx/ParticleSystem.cs`](../../src/AcDream.Core/Vfx/ParticleSystem.cs), [`ParticleHookSink.cs`](../../src/AcDream.Core/Vfx/ParticleHookSink.cs), [`PhysicsScriptRunner.cs`](../../src/AcDream.Core/Vfx/PhysicsScriptRunner.cs).
 - Activator (App): [`src/AcDream.App/Rendering/Vfx/EntityScriptActivator.cs`](../../src/AcDream.App/Rendering/Vfx/EntityScriptActivator.cs).
 - Streaming bridge (App): [`src/AcDream.App/Streaming/GpuWorldState.cs`](../../src/AcDream.App/Streaming/GpuWorldState.cs), [`LandblockSpawnAdapter.cs`](../../src/AcDream.App/Rendering/Wb/LandblockSpawnAdapter.cs).
 - Renderer: [`src/AcDream.App/Rendering/ParticleRenderer.cs`](../../src/AcDream.App/Rendering/ParticleRenderer.cs) — **don't touch** in C.1.5b; bindless migration is N.6 slice 2.
 - EnvCell loader: search for `LoadedCell` / `EnvCell.StaticObjects` in `src/AcDream.App/Streaming/` and `src/AcDream.Core/World/`.
 - C.1.5a tests as a reference: [`tests/AcDream.Core.Tests/Rendering/Vfx/EntityScriptActivatorTests.cs`](../../tests/AcDream.Core.Tests/Rendering/Vfx/EntityScriptActivatorTests.cs).
 ## §8 Open questions to surface during brainstorming
 - Slice A: does the C.1.5a final reviewer's "static-only fix is self-contained" claim hold up? (Section §3 Option A says yes; brainstorming should verify by checking `EntityScriptActivator`'s spawn path doesn't depend on animation state.)
 - Slice B: which Setup field actually lives on `EnvCell.StaticObjects` — is it a `SetupId` reference or an inline Setup? Different shape changes the synthetic-ID hash input.
 - Slice B: are EnvCell statics ALSO subject to the cold-path timing observation from C.1.5a Task 2 review (firing before the cell is rendered)?
 ## §9 Worktree cleanup reminder (one-time, from outside the worktree)
 The C.1.5a worktree directory at `C:/Users/erikn/source/repos/acdream/.claude/worktrees/lucid-burnell-aab524` was not auto-removed because the controller session held a file lock. After this session ends, from any other directory:
 ```powershell
 git -C "C:/Users/erikn/source/repos/acdream" worktree remove --force `
    "C:/Users/erikn/source/repos/acdream/.claude/worktrees/lucid-burnell-aab524"
 ```
 The branch `claude/lucid-burnell-aab524` was successfully deleted; only the worktree directory needs manual cleanup.
--- a/docs/plans/2026-06-11-building-render-port-plan.md
+++ b/docs/plans/2026-06-11-building-render-port-plan.md
@ -1,381 +0,0 @@
 # The holistic building-render port plan (Phase B) — one drawing discipline
 **EXECUTION STATUS (2026-06-11, post-BR-7): BR-2…BR-7 are ALL CODE-COMPLETE
 on the branch — the render arc as the fused tasks T1–T4 (T1 `579c8b0` frame
 order; T2 `cf8a2c3`/`529dfcf`/`88f3ce1` flood fidelity, two retail constants
 refuted by the conformance gate and kept at documented tolerances; T3
 `a6aec8c` viewconeCheck; T4 `4a307d3` one-gate deletions), and BR-7 (T6,
 collision A6.P4) as `6ec4cde` (signed OtherPortalId gate) + `abf36e2`
 (BuildShadowCellSet flood) + `dbfbf85` (per-cell architecture: flood
 registration, building channel, per-cell query, b3ce505 DELETED — closes
 #99) + `ca4b482` (straddle-only outside-add, A6.P5 widening + #90
 stickiness removed). Of the 4 #99-era Core reds, 3 flipped green as
 designed (door apparatus + tick-13558 + tick-22760's blocking invariant);
 the 4th (BSPStepUp D4) + 22760's lateral-slide delta proved to be a
 SEPARATE pre-existing slide-response family — filed #116, D4 skipped with
 the reference (probes show the cell-set layer innocent). Suites: Core
 1416/0/2skip, App 225, UI 420, Net 294.
 **T5 EXECUTED 2026-06-11 (the single comprehensive user gate) — PARTIAL
 PASS.** ✅ Confirmed by the user: doors block both ways incl. off-center
 (#99 visual), cellar descent/ascent clean + #108 grass-sweep GONE, inn
 2nd floor clean (#97 closed), interiors stable through doorways incl.
 edge-on, #109 far-door oscillation GONE, formerly-popping stairs now
 STABLE at all ranges (the distance-pop class is dead). ❌ Remaining —
 four filed render artifacts: **#117** aperture-shaped see-through
 (doors/interiors through terrain hills + through nearer buildings — the
 punch erases occluder depth), **#118** character clipped+vanishes for a
 moment on house exit, **#119** old-tower stairs partially invisible +
 extraneous barrel (pre-existing; `[up-null]` permanently-invisible mesh
 lead in the T5 log), **#120** `[pv-ERROR]` in-place-propagation
 convergence tripwire at depth 128 on the cottage cells (self-detected
 T2 invariant break — investigate first). Rain-indoors not verifiable
 (clear weather). NEXT: fix #120 → #117 → #118 → #119 at the mechanism
 level, then a focused re-gate on just those spots.**
 **Status: APPROVED + AMENDED (2026-06-11). EXECUTION DIRECTIVE CHANGED BY THE
 USER: "I don't care if it is non-playable… I want everything ported, then we
 test."** The per-phase playability constraint and per-phase user visual gates
 are DROPPED. BR-2 through BR-6 execute as ONE continuous port (the fused
 render discipline), with build + unit/conformance tests green at every commit
 (engineering hygiene, not gates), and **ONE comprehensive visual test pass at
 the end**. Rationale: the first BR-2 attempt failed precisely because the
 phase slicing cut retail's frame order in half (the punch shipped without
 entities-drawn-last and erased characters in apertures — reverted `88be519`);
 the installment-must-be-a-complete-retail-behavior rule replaces the
 playability rule. BR-7 (collision) runs as an independent track; BR-8b
 (lighting) still wants the verification resume first.
 Companion to the Phase A comparison:
 [`docs/research/2026-06-11-building-render-acdream-vs-retail-comparison.md`](../research/2026-06-11-building-render-acdream-vs-retail-comparison.md)
 (evidence appendices in
 [`docs/research/2026-06-11-holistic-map/`](../research/2026-06-11-holistic-map/)).
 Mandate: *"one solution that works every time I walk to a new landblock and
 walk into a dungeon"* (2026-06-11).
 ---
 ## 0. The invariant (what "one drawing discipline" means, retail-cited)
 Every phase below moves us toward — and no phase may move us away from — this
 frame shape, which is retail's (Ghidra-cited in the comparison doc §2):
 1. **Geometry is flattened at load** into surface-batched meshes (we already
   do this). World geometry is **never geometrically clipped at draw time**.
 2. **Untextured (solid) surface batches never draw** on building shells and
   cell meshes (`skipNoTexture`); they do draw on plain objects.
 3. **Portal polygons are not wall geometry.** They exist per frame only as
   (a) flood admission tests (`ConstructView`: eye-side ε=0.0002 → clip vs
   current view → cell loaded) and (b) **invisible depth writes** — far-Z
   *punch* before an interior draws through an aperture; true-depth *seal*
   on portals to the outside after the landscape draws.
 4. **Cells draw whole, far→near, once** (frame stamp); the z-buffer plus the
   punches/seals produce pixel-exact apertures.
 5. **Objects and particles are culled per portal view** (sphere vs the view's
   edge planes — `viewconeCheck`), never clipped, never scissored.
 6. **One visibility computation feeds everything** — the PView flood. No
   second BFS, no parallel gate, no distance constants in admission.
 ## 1. Keep-list (the code worth saving — explicitly not touched/rewritten)
 - **Mesh pipeline**: `ObjectMeshManager` flatten + global VAO + bindless MDI
  (`WbDrawDispatcher`) — retail-faithful architecture, confirmed by the
  `ConstructMesh`/`RemoveNonPortalNodes` finding.
 - **The flood port**: `PortalVisibilityBuilder` (homogeneous clipper, side
  tests, reciprocal clip, exact-match skip) + conformance gates
  (`CornerFloodReplayTests`, `Issue113MeetingHallFloodTests`) — BR-4 adjusts
  constants/heuristics, it does not rewrite the clipper.
 - **Membership** (P1 9/9 golden) + **straddle gate** (`414c3de`) +
  **camera collision sweep** (verbatim `update_viewer`) + **znear=0.1** +
  **#105 texture flush** + **two-tier streaming** + spawn/snap validation
  (#107/#111/#112).
 - Diagnostics/probes and the dat dump harness.
 The M0 freeze list is superseded *for rendering only* by the 2026-06-11
 mandate; nothing outside building/interior render + interior collision is in
 scope.
 ## 2. Phases
 Ordering rule: each phase lands green (build + full suites + named visual
 gate) and the client stays playable after every phase. Conformance pins come
 from the dat harness + the flood replay harnesses; retail constants are cited
 inline when ported.
 ### BR-1 — The surface gate — ✅ RESOLVED AS ALREADY-EQUIVALENT (2026-06-11, execution day 1)
 **Premise falsified before implementation (the BR-1 pre-check,
 `ReplicateProductionEmission_OnPortalFills`):** acdream **already suppresses
 every portal fill** — all four extraction paths skip `Stippling.NoPos`
 positive sides (`ObjectMeshManager.PrepareGfxObjMeshData:1046`,
 `PrepareCellStructMeshData:1394`, `CellMesh.Build:44`, `GfxObjMesh.Build:71`),
 and the Holtburg fills have no negative surface. The planned "draw-time
 surface gate" has nothing to gate.
 **What shipped instead — the equivalence pin**
 (`StipplingSurfaceEquivalenceTests`): 2,607 polys across 13 building models +
 13 environments, **zero violations both directions** — `NoPos ⇔ untextured
 surface`. Our build-time skip is therefore *proven equivalent* to retail's
 draw-time `skipNoTexture` rule on this content; the
 `portal-poly-suppression-criterion` divergence closes as
 equivalent-with-proof. The pin fails loudly if future content breaks the
 invariant (the cue to implement the draw-time gate then).
 **Consequences (the honest part):**
 - The **#113 phantom residual is NOT GfxObj fills** — it cannot be, they
  never reach a vertex buffer. The "root cause #2" attribution from the
  e46d3d9 session is corrected; the e46d3d9 user-gate observations (filter
  removed phantom/doors) were confounded — the filter was a provable mesh
  no-op on both shells and door parts.
 - The phantom's plausible true sites are cell-side: flood-admitted stair
  CELLS drawn with a pass-all slice when the assembler hands them no slot
  (`RetailPViewRenderer.cs:71` draws ALL visible cells; `NoClipSlice`
  default), and/or stair-cell STATICS drawn unclipped + un-viewcone'd by
  design (`object-lists-skip-portal-view-gate`, confirmed). **BR-2's first
  task is a 10-minute probe at the hall bisect spot pinning which** —
  the closure moves to BR-2/BR-3 (shells) and BR-5 (statics).
 - **Closes:** the `portal-poly-suppression-criterion` divergence (as
  proven-equivalent); #113's closure moves to BR-2/BR-3/BR-5.
 - **Shipped:** the pre-check + equivalence pin tests; no production code
  (none needed).
 ### BR-2 — Aperture depth machinery (punch / seal / clear)
 **What:** port the invisible depth writes:
 (a) wire `DrawExitPortalMasks` (today an unwired no-op) as a depth-only draw
 of each outside-leading portal polygon, software-clipped to its view slice
 (the `ClipToRegion` math already exists), at the portal's **true projected
 depth** (retail `maxZ2`) — after the landscape slices, indoor roots;
 (b) add the **far-Z punch** (retail `maxZ1`) on building-aperture flood
 success on the outdoor + look-in paths, before the interior cells draw;
 (c) replace the per-slice scissored `ClearDepthSlice` AABB clear with
 retail's discipline: one full depth clear between the outside stage and the
 interior stage, gated on whether any seal was drawn (`portalsDrawnCount`);
 (d) on the look-in path, draw interior-through-aperture **before** the shell
 mesh (retail `DrawBuilding` order) so the shell's depth closes everything
 outside the punch.
 - **First task (from BR-1's falsification):** the 10-minute probe at the
  hall bisect spot — when the phantom is visible, log per stair cell
  (0x100..0x106) whether it drew with a real clip slot or the pass-all
  `NoClipSlice`, and whether its statics drew — pinning the phantom's true
  draw site (shells → fixed here/BR-3; statics → BR-5).
 - **Closes:** #108 (outdoor terrain sweeping across the upstairs door — the
  missing true-depth seal is the confirmed `missing-portal-depth-fence`
  divergence); the outdoor-root depth-discipline gap; part of #109; the
  #113 phantom residual if the probe pins it on pass-all shell slices.
 - **Acceptance:** cellar↔main-floor walk shows no grass sweep (user gate);
  phantom-spot check at the hall (user gate, replaces the old BR-1
  acceptance); new harness fact: seal depth = portal plane depth inside the
  clipped aperture polygon (GL readback test or probe assertion); suites
  green.
 - **Size:** ~3 commits (~80 lines of GL + clipper reuse per the area
  estimate, plus the clear re-shape and order swap).
 ### BR-3 — Retire the geometric shell chop; whole-shell far→near draws
 **What:** remove `gl_ClipDistance` as the *enforcement* mechanism for cell
 shells (both the outdoor-scoped enable from `927fd8f`/`9ce335e` and the
 never-enabled indoor half — i.e. #114 closes by *deleting* the chop, not
 perfecting it). Shells draw whole, far→near per `OrderedVisibleCells`
 (already the order), drawn-once. Clip regions remain for admission, punch
 shapes, and (BR-5) object culling. The landscape-through-aperture pass keeps
 its per-slice plane clip for now (open Q: `LScape::draw` internals) — revisit
 after BR-2 proves the seal protects terrain.
 - **Closes:** #114 (chopped stairs / vanished candle area / barrel-through-
  wall were artifacts of clipping geometry retail never clips) — jointly
  with BR-2. Removes the 8-plane budget + slot-0 PASS-ALL as load-bearing
  for shells.
 - **Acceptance:** meeting-hall interior + multi-room cottages render
  unchopped from indoor and outdoor eyes (user gate vs the #114 screenshot
  set); phantom stays gone (BR-1 unaffected); flood replay gates green.
 - **Order constraint:** must not land before BR-2 (the depth fence replaces
  the chop's job at apertures).
 - **Size:** ~2 commits (mostly deletions + the draw-order assertion).
 ### BR-4 — Shell-draw-driven floods + flood fidelity
 **What:** make the building's own draw the flood trigger, retail-shaped:
 pair the shell GfxObj's `PortalRef.PortalIndex` with its `BuildInfo.Portals`
 entry (the `outdoor_portal_list` correspondence) and, when a shell survives
 the cull for a view slice, run each aperture through the ported
 `ConstructView(CBldPortal)` chain under that slice. Then remove the
 non-retail machinery the trigger replaces: the 48 m seed constant, the
 Chebyshev≤1 candidate gather, the `EyeInsidePortalOpening` full-view rescue;
 adopt retail constants (ε=0.0002; in-plane rejects for building portals);
 add the 1-px screen-space vertex dedup to `ClipToRegion` output (retail's
 fixpoint floor) and switch late view growth to in-place propagation
 (`AddToCell`/`FixCellList`/`AdjustCellView` shape), removing the
 `MaxReprocessPerCell=16` cap; make `MergeBuildingFrame` union views instead
 of first-wins and retire single-slot consumers (`CellIdToSlot[0]`); bind
 nested floods to their originating slot (the `building_view` latch).
 - **Closes:** #109 (binary 48 m pop + first-wins view loss + missing punch
  are its named mechanisms); the flood-stability family (edge-on doorway
  residuals); enables interior-visible-through-window parity.
 - **Acceptance:** flood replay harnesses extended: (a) building flood
  triggers with no distance constant — admission matches the
  clip-survival rule across an eye sweep; (b) two-aperture cell holds two
  views; (c) growth propagates without the cap on a portal-dense fixture;
  #109 spot user gate; suites green.
 - **Size:** ~4–5 commits (trigger + pairing; constants/dedup; growth
  in-place; merge union; deletions).
 ### BR-5 — Per-view object + particle culling (viewconeCheck)
 **What:** port `Render::viewconeCheck`: per view slice, lift the per-edge
 eye planes (each NDC edge + the eye defines a plane — the `view_vertex.plane`
 analog) and sphere-test every entity and emitter against the slice before
 draw; route particles through the same gate and the same clip/punch
 discipline (delete the `BeginDoorwayScissor` AABB path); fix the
 outdoor-root unattached-emitter drop; gate the weather pass on
 `is_player_outside` (player cell, not viewer root).
 - **Closes:** particles-through-walls (candle flames in other buildings);
  rain-indoors-through-doorways; the neighbour-room object over-inclusion
  half of the old #114 report.
 - **Acceptance:** flame-through-wall spot at Holtburg (user gate); a
  conformance fact pinning sphere-vs-slice culling on a fixture; no
  regression in entity draw counts outdoors (perf probe within noise).
 - **Size:** ~3 commits.
 ### BR-6 — One gate: consolidate visibility + delete legacy paths
 **What:** make the PView flood the only visibility computation:
 remove the per-frame ACME BFS (`CellVisibility.ComputeVisibilityFromRoot`)
 by folding its remaining consumers (lighting indoor flag etc.) onto PView/
 membership outputs; delete or quarantine the confirmed legacy remnants
 (`InteriorRenderer`, `IndoorDrawPlan` consumers of the old path, the
 `clipRoot==null` second render branch, the dormant exit-mask wiring once
 BR-2 rewires it, duplicate frustum implementation); one frustum, one
 center/radius window.
 - **Closes:** the `dual-live-visibility-computations` inconsistency class
  (the one-gate rule, `feedback_render_one_gate`); removes the surface area
  where two gates disagree (future flap-class bugs).
 - **Acceptance:** gate-audit re-run shows ONE visibility computation per
  frame; every deletion verified by a launch + the visual gate set; suites
  green.
 - **Size:** ~3 commits, mostly deletions (each independently revertable).
 ### BR-7 — Interior collision: per-cell shadow lists (A6.P4, verified) — ✅ CODE-COMPLETE 2026-06-11 (`6ec4cde`+`abf36e2`+`dbfbf85`+`ca4b482`; visual confirmation rides T5)
 **What:** ship the A6.P4 architecture with the investigation's corrections:
 registration builds the cell set by sphere-overlap portal flood (not an XY
 grid; crosses landblocks), per-cell `shadow_object_list` iteration on the
 query side (`CheckOtherCells` runs env AND shadow objects per other cell),
 buildings dispatch through a per-LandCell building channel
 (`CSortCell.building` shape), `OtherPortalId` widened to signed with the
 `>= 0` gate (sign-extension Ghidra-proven). Then remove the `b3ce505`
 stopgap, the A6.P5 `hasExitPortal` widening, and the #90 stickiness
 workaround.
 - **Closes:** #99 (doors block from both sides), very likely #97; retires
  three flagged workarounds.
 - **Acceptance:** A6.P4 spec acceptance (doors block both ways at Holtburg
  inn + cottages; #98 cellar ascent stays fixed — `CellarUp` harness green);
  capture/replay comparison on the door apparatus; suites green.
 - **Size:** the A6.P4 spec's estimate stands (~5 commits); independent of
  BR-2..BR-5 — may run in parallel with them.
 ### BR-8 — Feel tier: camera, lighting, LOD (post-discipline polish)
 - **BR-8a Camera (#115, verified root cause; can land any time):** damp the
  sought eye FROM the published collided viewer each frame (retail
  `PlayerPhysicsUpdatedCallback` shape) and apply the computed player fade
  over the 0.45→0.20 m band. Acceptance: cramped-interior turn feel (user
  gate). ~1–2 commits.
 - **BR-8b Lighting (pending verifier confirmation):** interior sun mask
  (never sun-light interiors), static cell-light burn-in (all lights, not
  8-nearest), viewer light, per-object light selection, surface
  luminosity/diffuse. Acceptance: side-by-side interior look vs retail
  screenshots. Phase-sized; spec before code.
 - **BR-8c LOD + dedup (low):** per-part degrade selection beyond humanoids;
  frame-stamp draw dedup. Optional per-cell interleave for draw-order parity
  is explicitly NOT planned (z-buffer makes it unnecessary; revisit only on
  evidence).
 - **Picking refinements** (all-low area): defer; file as issues when the
  port changes what is clickable.
 ## 3. What this plan deliberately does NOT do
 - No per-frame BSP traversal of ordinary geometry (retail doesn't either).
 - No rewrite of the mesh/MDI pipeline, the flood clipper, membership, or
  streaming (keep-list).
 - No `leaf_cells`/`CPartCell` port (path dormant in the 2013 binary — needs
  runtime proof first).
 - No transparency-sorting work yet — that area's map is still re-running;
  fold its findings in as a BR-9 candidate after review (the AlphaList
  deferral machinery is already decompiled in the Area 1 file).
 ## 4. Explicitly out of scope — tracked follow-ups (NOT covered by BR-1…BR-8)
 Completing BR-1 through BR-8 lands the building/interior **drawing
 discipline** and the collision rearchitecture. It does **not** cover the
 items below. They are named here so the boundary of what the campaign
 delivers is written down, not assumed — each becomes its own roadmap item or
 issue, none blocks BR-1…BR-8.
 - **FU-1 — Transparency / draw-sorting (→ BR-9 candidate).** Retail's
  `DrawSortCell` + AlphaList deferral (decompiled in
  `2026-06-11-holistic-map/wf1-gfxobj-draw.md`) governs water surfaces,
  translucent windows, and alpha-blend ordering. The area's *map never
  completed* (agent hit the token limit), so there are no divergences yet —
  scope it before promoting to BR-9. **Severity: medium; user-visible as
  wrong window/water compositing.**
 - **FU-2 — Dungeon visibility scaling (#95).** The 8 phases are
  Holtburg-building-shaped. Dungeons share the EnvCell/portal discipline so
  they benefit *automatically*, and BR-4's tighter flood admission
  (no-distance-constant + screen-clip rejection + cell-loaded gate)
  **plausibly** shrinks #95's 135-cells/frame blowup — but #95 is a
  disconnected-landblock *seeding* problem that BR-4 is not guaranteed to
  fix. **Re-measure #95 after BR-4/BR-6 land; if still blown, it needs its
  own phase.** Do not assume the building port closes it.
 - **FU-3 — Distance LOD / degrades (= BR-8c, optional).** Per-part degrade
  selection beyond humanoids; far models stay base-detail until picked up.
 - **FU-4 — Picking refinements** (4 low-severity divergences,
  `wf2-picking-selection.md`). Defer; file as issues if/when the port
  changes what is clickable (e.g. building shells, baked fills).
 - **FU-5 — The ~30 open questions** live in the comparison doc §6
  (`2026-06-11-building-render-acdream-vs-retail-comparison.md`). The
  load-bearing ones are referenced inline in the phases that consume them
  (e.g. `LScape::draw` clip behavior for BR-2/BR-3, the near-W constant,
  `DrawPortal` mode-3 seal-on-failure for unstreamed interiors); the rest
  are pinned during implementation, not before.
 - **FU-6 — Verification top-up.** ~36/76 divergences remain UNVERIFIED (the
  overnight resume was stopped to preserve budget; both runs are resumable
  by ID — see comparison §7). Run a cheap resume before **BR-8b lighting**
  scoping (the one phase that leans on unverified rows) and before promoting
  FU-1 to BR-9.
 ## 5. Sequencing summary
 ```
 BR-1 (surface gate)          — ✅ RESOLVED as already-equivalent (pin shipped,
                               no production code; #113 closure moved to
                               BR-2/3/5 — see BR-1 section)
 BR-2 (depth punch/seal)      — FIRST implementation phase; opens with the
                               phantom-site probe; enables BR-3
 BR-3 (delete shell chop)     — closes #114 with BR-2
 BR-4 (draw-driven floods)    — closes #109; flood fidelity
 BR-5 (viewconeCheck)         — particles/objects through the same gate;
                               closes the phantom if it is statics-side
 BR-6 (one gate + deletions)  — consolidation after the discipline is in
 BR-7 (collision A6.P4)       — independent track; may interleave with BR-2..5
 BR-8 (camera/lighting/LOD)   — feel tier; BR-8a may land early
 ```
 Every phase: `dotnet build` + full suites green, conformance pins added with
 retail citations, named user visual gate, roadmap/ISSUES updated in the same
 session, and the render digest updated when a phase closes one of the named
 bugs.
 ## 6. Approval asks
 1. Approve the plan shape + ordering (BR-1 → BR-8, BR-7 parallel-capable).
 2. Approve the deletions implied by BR-3/BR-6 (shell-chop enforcement,
   ACME BFS visibility, legacy render branches) — all on the strength of the
   cited evidence that retail has no counterpart.
 3. Note the verification caveat: ~36/76 divergences still carry UNVERIFIED
   (resume in flight); BR-1..BR-3's load-bearing claims are either verified
   or dat-confirmed locally, so approval need not wait on the rest.
--- a/docs/research/2026-05-08-phase-n3-handoff.md
+++ b/docs/research/2026-05-08-phase-n3-handoff.md
@ -1,132 +0,0 @@
 # Phase N.3 handoff — texture decoding via WorldBuilder
 **Use this whole document as the prompt** when handing off to a fresh
 agent. Everything they need to pick up cold is below.
 ---
 ## Background you'll need
 You're working in `acdream`, a from-scratch C# .NET 10 reimplementation
 of Asheron's Call's retail client. The project's house rule (in
 `CLAUDE.md`) is **the code is modern, the behavior is retail**.
 acdream just shipped **Phase N.1** (commits `26cf2b8` through `ad8b931`),
 the first sub-phase of a strategic migration to fork WorldBuilder
 (`github.com/Chorizite/WorldBuilder`, MIT) and depend on its tested
 rendering + dat-handling code instead of porting algorithms from retail
 decomp ourselves.
 **Read first:**
 - `docs/architecture/worldbuilder-inventory.md` — the full taxonomy of
  what WB has and what we keep porting ourselves
 - `docs/superpowers/specs/2026-05-08-phase-n-worldbuilder-migration-design.md`
  — the parent design doc for Phase N
 - `CLAUDE.md` — especially the "Reference repos" section (now points at
  WB as the rendering BASE) and the workflow rules
 **Phase N.1 commit history (just shipped):** read
 `git log --oneline c8782c9..ad8b931` to see how N.0 + N.1 were
 structured. The pattern repeats for N.3.
 ## What N.3 is
 Replace acdream's texture decoding pipeline with WorldBuilder's
 `Chorizite.OpenGLSDLBackend.Lib.TextureHelpers`. WB handles INDEX16,
 P8, BGRA, DXT, and alpha-channel decoding. Our existing implementations
 of these are scattered across `src/AcDream.App/Rendering/TextureCache.cs`
 and possibly `src/AcDream.Core/Meshing/` — find them with
 `grep -rln "INDEX16\|P8 decode\|DXT\|BGRA" src/`.
 ## Acceptance criteria
 - Build green (`dotnet build`)
 - All existing tests green (the 8 pre-existing `DispatcherToMovementIntegrationTests`
  failures don't count — they exist on main)
 - New conformance tests added per format that's substituted (one xUnit
  Theory per: INDEX16, P8, BGRA, DXT). Each compares a fixed input byte
  array decoded by our path vs WB's path; assertions on output pixel array.
 - Visual verification at Holtburg (or wherever) shows no texture
  regressions: terrain texturing, mesh texturing, particle textures all
  look the same.
 - ISSUES.md updated with any known cosmetic deltas (the N.1 pattern —
  if WB and retail disagree on something subtle, file it, don't try
  to fix it inline).
 ## Tasks (suggested decomposition)
 Follow the N.1 plan structure (`docs/superpowers/plans/2026-05-08-phase-n1-scenery-via-wb-helpers.md`)
 as the template. Concretely:
 1. **Audit our texture decode paths.** Grep, list every file/method that
   decodes a texture. Map each to the WB equivalent in
   `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TextureHelpers.cs`
   (read it end to end first).
 2. **Per-format conformance test.** TDD style: write the test, run it
   to fail, then plumb the substitution. Conformance test fixture inputs
   should include real-dat byte sequences (read a known-good texture from
   a dat, encode the bytes as a hex blob in the test).
 3. **Substitution.** Replace each decode site with the WB call. Keep our
   GL upload pathways — those are NOT WB's responsibility.
 4. **Visual verification.** Launch the client at Holtburg, walk around,
   look at a tree (mesh texture), the ground (atlas texture), particles
   (the recent C.1 rain/clouds/aurora work), and a building (composite
   texture). Compare against retail or against a screenshot before the
   change.
 5. **Delete legacy decoders** once visual verification passes.
 6. **Update roadmap + ISSUES** as the final commit.
 ## Watchouts (lessons from N.1)
 - **ACME has a downstream fork with extra filters** (`references/WorldBuilder-ACME-Edition/`).
  WB's `TextureHelpers` may have ACME-specific patches not yet in upstream.
  Compare both before assuming WB's version is canonical. We forked
  upstream WB; ACME is reference-only.
 - **Conformance tests are non-negotiable.** Phase N.1's rotation bug was
  caught by the conformance test. Don't skip them. If a test fails, it's
  a real divergence — investigate before "fixing" the test.
 - **Whackamole stops the migration.** If 3+ visual regressions appear on
  default-on, stop, file as ISSUES, ship. The migration goal is "use WB's
  tested code"; pixel-perfect equivalence with our broken hand-ports is
  not the goal.
 - **`Setup.SortingSphere` ≠ `Setup.CylSphere`.** The N.1 attempt at
  `obj_within_block` over-suppressed because we used the wrong radius
  source (sorting sphere too large). For texture decoding this likely
  doesn't matter, but the general lesson is: read WB's full source
  carefully before adapting; don't assume parallel methods do parallel
  things.
 - **Per-vertex road check — STOP signal.** If you find yourself reading
  ACME for "what's missing" and considering a per-vertex filter, STOP.
  N.1 tried this (commit `e279c46`), regressed visually, reverted in
  `677a726`. ACME's filter set works as a coherent unit; pick-and-choose
  fails. If the N.3 work uncovers a similar ACME-only filter, file it
  in ISSUES and move on, don't port it inline.
 ## Where to start
 1. `git pull` on main to get the latest (Phase N.1 just merged).
 2. Create a new worktree for the work:
   `git worktree add .claude/worktrees/<your-name> -b claude/<your-name>`.
 3. Read the three "read first" docs above.
 4. Run `dotnet build && dotnet test` to confirm clean baseline.
 5. Read `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TextureHelpers.cs`
   end to end. Take notes on the public API surface.
 6. Run the audit task (#1 in Tasks above). Output should be a markdown
   table of "our function / file:line / WB equivalent / format covered."
 7. Use `superpowers:writing-plans` to convert the audit into a concrete
   per-format plan. Then use `superpowers:subagent-driven-development`
   to execute it with fresh subagents per format.
 ## Useful greps
 - `grep -rln "INDEX16\|IndexedSurface\|P8\|DXT\|BGRA\|TextureFormat" src/` — find decode paths
 - `grep -rln "TextureCache" src/` — find our cache layer
 - `grep -n "public static.*Decode\|public static.*Convert" references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TextureHelpers.cs` — WB's public API
 ## Open question to resolve early
 Does `Chorizite.OpenGLSDLBackend.Lib.TextureHelpers` cover ALL the
 formats we use, or does it have gaps? Audit our texture types against
 WB's API in step 1. If WB is missing a format we need, the migration for
 that format gets deferred (file in ISSUES; keep our decoder for it; note
 in the roadmap).
--- a/docs/research/2026-05-08-phase-n4-week4-handoff.md
+++ b/docs/research/2026-05-08-phase-n4-week4-handoff.md
@ -1,318 +0,0 @@
 # Phase N.4 Week 4 handoff — full draw dispatcher + visual verification + ship
 **Use this whole document as the prompt** when handing off to a fresh
 agent. Everything they need to pick up cold is below.
 ---
 ## Background you'll need
 You're working in `acdream`, a from-scratch C# .NET 10 reimplementation
 of Asheron's Call's retail client. The project's house rule (in
 `CLAUDE.md`) is **the code is modern, the behavior is retail**.
 acdream is in the middle of Phase N.4 — the rendering pipeline
 foundation migration to WorldBuilder's `ObjectMeshManager` +
 `TextureAtlasManager`. **Three of the four planned weeks have shipped
 this session (2026-05-08)**:
 - Week 1 (commits up through `c49c6ed`): foundation types — feature
  flag, surface metadata side-table, mesh-extraction + setup-flatten
  conformance tests, `WbMeshAdapter` constructed against the real WB
  pipeline.
 - Week 2 (commits up through `36f7a60`): streaming integration —
  `LandblockSpawnAdapter` routes atlas-tier (procedural / `ServerGuid==0`)
  GfxObjs to WB's ref-count lifecycle. `WbMeshAdapter.Tick()` drains
  the WB pipeline's main-thread queues per frame (fixes a real memory
  leak).
 - Week 3 (commits up through `d30fcb2`): per-instance tier hookup —
  `AnimatedEntityState` holds per-server-spawned-entity overrides;
  `EntitySpawnAdapter` routes server-spawned entities through the
  existing `TextureCache.GetOrUploadWithPaletteOverride` decode path.
 **Current state at `main`:** build green, **947 tests pass**, 8
 pre-existing failures only (unchanged from pre-N.4 main). Default-off
 behavior is byte-identical to pre-N.4 main; flag-on (`ACDREAM_USE_WB_FOUNDATION=1`)
 runs both rendering pipelines in parallel — WB silently prepares
 content, but nothing is yet drawn through it.
 **Read first:**
 - [docs/superpowers/plans/2026-05-08-phase-n4-rendering-foundation.md](../superpowers/plans/2026-05-08-phase-n4-rendering-foundation.md) —
  the **living-document** plan. Top of file has a Progress table
  showing Tasks 1-21 ✅ shipped with commit SHAs. Adjustments 1-5
  document architectural surprises caught during execution. **Read the
  Adjustments before writing any Task 22 code** — they explain why the
  current architecture is what it is.
 - [docs/superpowers/specs/2026-05-08-phase-n4-rendering-foundation-design.md](../superpowers/specs/2026-05-08-phase-n4-rendering-foundation-design.md) —
  the design spec. Architecture / two-tier split / animation handling /
  data-flow diagrams. Strategic source of truth for "how the pieces
  fit together."
 - [CLAUDE.md](../../CLAUDE.md) — project-wide rules. The "Currently in
  flight" section near the top points at the plan.
 ## What Week 4 is
 Seven tasks (22-28). **Task 22 alone is the biggest single task in the
 entire 28-task plan** — it's the moment we flip from "WB is silently
 preparing content" to "WB is drawing content to your screen."
 The remaining six tasks are smaller: surface-metadata side-table
 population, sky-pass preservation check, micro-tests round-out, visual
 verification at 5 named locations, flag default-on, delete legacy
 code, finalize plan + memory + ISSUES.
 **Task 22 also unlocks the Adjustment 3 mitigation.** Right now
 flag-on has a real FPS regression because both rendering pipelines run
 in parallel (legacy renderer still does atlas-tier upload + draw,
 even though WB is also building atlas state). When Task 22 lands the
 dispatcher AND wires the legacy-renderer short-circuit for atlas-tier
 content, that double-work disappears.
 ## Two unresolved decisions before Task 22 starts
 These need a brainstorm checkpoint at the start of Week 4, NOT a
 "just dispatch":
 1. **Adjustment 4 plumbing.** `WorldEntity` doesn't carry
   `HiddenPartsMask` or `AnimPartChanges` — those live on the
   network-layer spawn record and don't make it to the render-side
   entity. Two options:
   - **A**: add `HiddenPartsMask` + `AnimPartChanges` fields to
     `WorldEntity`, populate at spawn time. Cleaner long-term; small
     network→render plumbing change.
   - **B**: thread them as separate parameters into
     `EntitySpawnAdapter.OnCreate(entity, hiddenMask, animPartChanges)`.
     Sidesteps the `WorldEntity` change but couples the spawn-handler
     to the adapter API.
   Decide before writing Task 22 because the dispatcher reads from
   `AnimatedEntityState` which currently holds defaults (empty mask +
   empty override map). Without this resolved, hidden parts won't
   actually be hidden flag-on.
 2. **Surface-metadata side-table population strategy** (Task 23). The
   spec proposes: when `WbMeshAdapter.IncrementRefCount(id)` is first
   called for a GfxObj, walk its sub-meshes via `GfxObjMesh.Build`,
   write each `(gfxObjId, surfaceIdx) → AcSurfaceMetadata` entry into
   the side-table. The `_metadataPopulated: HashSet<ulong>` field
   tracks which ids have been processed.
   **But:** if the same GfxObj gets its ref count drop to zero and
   then re-incremented (LRU eviction + reload), do we re-populate?
   The metadata is invariant per-GfxObj (surface flags don't change
   with eviction), so probably no — the `HashSet` is fine. But
   verify before implementing.
 ## Watchouts (lessons from Weeks 1-3)
 These are real, observed gotchas. Read each before going deeper.
 - **The renderer is tier-blind by design (Adjustment 2).** Don't try
  to put routing decisions in `InstancedMeshRenderer` or any mesh
  uploader. Routing belongs at the **spawn-callback layer**:
  `LandblockSpawnAdapter` for atlas-tier, `EntitySpawnAdapter` for
  per-instance. Task 22's dispatcher reads from those adapters'
  per-entity state at draw time; it doesn't make tier decisions.
 - **Flag-off must stay byte-identical to pre-N.4.** Every Task-22 code
  path must have a `WbFoundationFlag.IsEnabled` gate. Default-off path
  is what users see; we can't regress it.
 - **WB's pipeline does work even when you're not draining its results.**
  Adjustment 3: `IncrementRefCount` triggers background mesh prep,
  texture decode, atlas allocation. `WbMeshAdapter.Tick()` already
  drains the upload queue per frame. The remaining FPS cost is
  pure dual-pipeline cost (legacy + WB doing the same upload work).
  Task 22's short-circuit fixes this.
 - **`MeshRef.SurfaceOverrides`** is the per-surface texture-swap data
  carried by spawned entities. `GfxObjSubMesh.SurfaceId` is what gets
  swapped. Task 22's draw loop must consult both: the entity's
  `MeshRef.SurfaceOverrides` for explicit swaps, and otherwise the
  mesh's built-in `SurfaceId`.
 - **Conformance tests catch divergences early.** Per N.1's rotation
  bug: write the conformance test BEFORE the substitution. The
  matrix-composition test (`(entityWorld) × (animation) × (restPose)`)
  is the load-bearing one for Task 22 — pin it before integrating.
 - **`WbMeshAdapter.Tick()` is required.** It's already wired into
  `GameWindow.OnRender`. Task 22's dispatcher needs the upload queue
  drained BEFORE it tries to draw, so order in OnRender is:
  `_wbMeshAdapter?.Tick()` → `_wbDrawDispatcher?.Draw(...)` → other
  draw work.
 - **Name retail decomp first; Phase N.4 doesn't change that rule.**
  Task 22's matrix composition uses standard graphics math — no AC-
  specific algorithms — so the "grep `named-retail/` first" workflow
  doesn't apply to the matrix code itself. But for any AC-specific
  question that surfaces during integration (e.g., "does retail
  render hidden parts as zero-alpha or skip them entirely?"), grep
  `docs/research/named-retail/acclient_2013_pseudo_c.txt` first.
 ## Acceptance criteria for Week 4
 From the plan:
 - [ ] All conformance tests pass (Tasks 3, 4, 20 — already shipped;
      verify still green after Task 22 lands).
 - [ ] All component micro-tests pass (Tasks 11, 17, 18, 19, 22 —
      Task 22 adds matrix-composition tests).
 - [ ] All existing tests still pass. 8 pre-existing failures don't
      count.
 - [ ] Build green throughout.
 - [ ] Visual verification at 5 named locations passes:
  1. Holtburg outdoor — terrain props, scenery, buildings, NPCs,
     characters all render correctly.
  2. Drudge Hideout (or comparable) — EnvCell + interior lighting +
     animated creatures.
  3. Foundry — heavy NPC traffic + customized appearances.
  4. A character with extreme palette overrides.
  5. Long roam (5+ minutes) — GPU memory stabilizes (LRU eviction
     fires).
 - [ ] Memory budget enforcement actually verified (Task 13 was
      deferred to here; Task 22 makes it testable because GL resources
      finally get allocated for LRU to evict).
 - [ ] Sky pass renders identically (load-bearing — sky's
      `Translucent+ClipMap` cloud sheet, raw-`Additive` fog skip,
      `Luminosity` keyframe handling all flow through the side-table
      via `AcSurfaceMetadata`).
 - [ ] Flag flipped to default-on at the end (Task 26).
 - [ ] Legacy code paths deleted (Task 27).
 - [ ] Roadmap + memory + ISSUES updated (Task 28).
 ## Tasks 22-28 — quick map
 Full detail is in the plan. Brief here:
 - **22 — `WbDrawDispatcher` full draw loop.** ~1-2 days. Atlas-tier
  + per-instance-tier draw with matrix composition. Reads from
  `WbMeshAdapter.GetRenderData(id)` for atlas content; reads from
  `EntitySpawnAdapter.GetState(serverGuid)` for per-instance state;
  composes per-part `(entity × animation × rest-pose)` matrices;
  pushes uniforms; issues GL draws. **Also wires the legacy-
  renderer short-circuit** for atlas-tier content (the Adjustment 3
  fix).
 - **23 — Surface-metadata side-table population.** ~half day. Hook
  into `WbMeshAdapter.IncrementRefCount` so that on first registration
  of a GfxObj, the side-table gets populated with one
  `AcSurfaceMetadata` per surfaceIdx (using `GfxObjMesh.Build`'s
  metadata as the source of truth).
 - **24 — Sky-pass preservation check.** ~half day. Verify the sky
  pass's `NeedsUvRepeat` / `DisableFog` / `Luminosity` flow through
  the side-table to `SkyRenderer` correctly. Likely no code change;
  smoke-test sky rendering with flag on, weather/day-night cycle.
 - **25 — Component micro-tests round-out.** Audit existing tests
  against the spec's Testing section. Probably nothing to add since
  Tasks 11/17/18/19/22 already cover the listed micro-tests.
 - **26 — Visual verification + flag default-on.** Human-in-the-loop
  walk through the 5 named locations. If clean, flip
  `WbFoundationFlag.IsEnabled` from `== "1"` to `!= "0"` so flag-on
  becomes the default.
 - **27 — Delete legacy code paths.** Remove the now-unused legacy
  upload code in `StaticMeshRenderer` + `InstancedMeshRenderer`.
  N.6 fully replaces these files anyway.
 - **28 — Update roadmap + memory + ISSUES + finalize plan.** Mark
  N.4 shipped in the roadmap's Live ✓ table. File any cosmetic
  deltas as ISSUES. Add a memory note if a durable lesson emerged.
  Flip the plan's status header from "Living document — work in
  progress" to "Final state — phase shipped (merge `<sha>`)".
 ## Where to start
 1. **Read the three "Read first" docs above end-to-end.** Especially
   the Adjustments section in the plan — those are the architectural
   constraints Task 22 must respect.
 2. **Decide Adjustment 4 plumbing** (option A vs B from above). This
   is a small brainstorm checkpoint, not a multi-question
   `superpowers:brainstorming` skill invocation. Document the choice
   inline in the plan as Adjustment 6.
 3. **Don't create a new worktree.** The existing branch
   `claude/quirky-jepsen-fd60f1` and worktree
   `.claude/worktrees/quirky-jepsen-fd60f1` are clean and ready.
   Submodule already initialized. Build green.
 4. **Use `superpowers:subagent-driven-development`** to execute Week 4
   task-by-task. Pattern from Weeks 1-3: dispatch one subagent per
   task (or batch of related tasks), use Sonnet for implementation,
   merge to main per logical chunk, update the plan's Progress table
   as commits land.
 5. **Pause for visual verification at Task 26.** This is a human-in-
   the-loop step — needs you to walk the 5 named locations.
 ## Open questions a fresh agent might hit
 - **Q: Why did Adjustment 5 mark Task 20 (per-instance decode
  conformance) as "structural"?** Because both old and new paths call
  the same `TextureCache.GetOrUploadWithPaletteOverride` function. We
  preserved the decode logic exactly; the seam is at the call site,
  not at the algorithm. Byte-equality is automatic.
 - **Q: Can I delete `InstancedMeshRenderer`?** Not in N.4. The plan
  marks it as "becomes a thin adapter in N.4, fully replaced in N.6."
  Task 27 deletes the legacy upload paths inside it but keeps the
  file as a draw-orchestration adapter until N.6.
 - **Q: What's the memory budget check actually checking?** GPU memory
  stabilizes during long roam. WB's `_maxGpuMemory = 1 GB` triggers
  LRU eviction once the cache exceeds that. We verify by walking
  for 5+ minutes at radius 7 (49 landblocks visible at any time) and
  confirming GPU memory in the title bar plateaus rather than
  growing unboundedly.
 - **Q: What happens if Task 22 takes longer than expected?** The
  living-document convention says document Adjustments inline. If
  Task 22 needs to split (e.g., atlas-tier draw lands first, per-
  instance tier in a follow-on commit), that's fine — just update
  the Progress table and add an Adjustment explaining the split.
 ## Useful greps and commands
 - `dotnet build --verbosity quiet 2>&1 | tail -3` — quick build check.
 - `dotnet test --verbosity quiet 2>&1 | tail -3` — full test suite.
 - `git -C C:\Users\erikn\source\repos\acdream log --oneline -10` —
  recent main commits.
 - `grep -rn "WbFoundationFlag.IsEnabled" src/` — every place we gate
  on the flag (audit before flipping default-on in Task 26).
 - `grep -rn "_wbMeshAdapter\|_wbSpawnAdapter\|_wbEntitySpawnAdapter" src/` —
  every WB adapter wiring point.
 ## Smoke-test launch (PowerShell)
 ```powershell
 # Kill any stale processes first
 Get-Process -Name AcDream.App -ErrorAction SilentlyContinue | Stop-Process -Force
 Start-Sleep -Seconds 4
 # Flag-on at radius 7 — Week 4 dev environment
 $env:ACDREAM_DAT_DIR   = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE      = "1"
 $env:ACDREAM_TEST_HOST = "127.0.0.1"
 $env:ACDREAM_TEST_PORT = "9000"
 $env:ACDREAM_TEST_USER = "testaccount"
 $env:ACDREAM_TEST_PASS = "testpassword"
 $env:ACDREAM_USE_WB_FOUNDATION = "1"
 $env:ACDREAM_STREAM_RADIUS = "7"
 dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
    Tee-Object -FilePath "n4-week4-smoke.log"
 ```
 (Drop the `ACDREAM_USE_WB_FOUNDATION` line for flag-off comparison.)
 ## Adjustments index — quick reference
 For full text, see the plan document (each is a `### Adjustment N`
 subsection under Task 6's old position, in chronological order):
 1. **`DefaultDatReaderWriter` discovery** (2026-05-08) — no
   dat-reader bridge needed; WB ships a usable concrete
   implementation.
 2. **Renderer is tier-blind** (2026-05-08) — routing belongs at
   spawn callbacks, not in the renderer.
 3. **FPS regression = dual-pipeline cost** (2026-05-08) — both
   pipelines run in parallel until Task 22's short-circuit lands.
 4. **`WorldEntity` lacks HiddenParts/AnimPartChange fields**
   (2026-05-08) — plumbing deferred; Task 22 needs to resolve
   (option A: add fields; option B: thread as separate args).
 5. **Task 20 is structural** (2026-05-08) — same function called
   both paths, byte-equality automatic, no test file needed.
--- a/docs/research/2026-05-08-phase-n5-handoff.md
+++ b/docs/research/2026-05-08-phase-n5-handoff.md
@ -1,495 +0,0 @@
 # Phase N.5 — Modern Rendering Path — Cold-Start Handoff
 **Created:** 2026-05-08, immediately after N.4 ship.
 **Audience:** the next agent picking up rendering perf work.
 **Purpose:** give you everything you need to start N.5 cold, without
 spelunking through five months of session history.
 ---
 ## TL;DR
 N.4 just shipped: WB's `ObjectMeshManager` is now acdream's production
 mesh pipeline, and `WbDrawDispatcher` is the production draw path. It
 works (Holtburg renders correctly, FPS substantially improved over the
 naïve dual-pipeline state we hit during week 4 verification) but it's
 still doing per-group state changes (`glBindTexture`, `glBindBuffer`
 for the IBO, `glDrawElementsInstancedBaseVertexBaseInstance` per group)
 and a fresh `glBufferData` upload per frame.
 **N.5's job: lift the dispatcher onto WB's modern rendering primitives
 that we're already paying GPU-feature-detection cost for.** Two big
 wins, paired:
 1. **Bindless textures** (`GL_ARB_bindless_texture`) — WB already
   populates `ObjectRenderBatch.BindlessTextureHandle`. Switch our
   shader to read texture handles from a per-instance attribute
   (`uvec2` → `sampler2D` via the bindless extension). Eliminates
   100% of `glBindTexture` calls.
 2. **Multi-draw indirect** (`glMultiDrawElementsIndirect`) — build a
   buffer of `DrawElementsIndirectCommand` structs (one per group),
   upload once, fire ONE `glMultiDrawElementsIndirect` call per pass.
   The driver pulls everything from the indirect buffer.
 Together they target a 2-5× CPU win on draw-heavy scenes (Holtburg
 courtyard, Foundry, dense dungeons). They're packaged together because
 both are "modern path" extensions we already gate on, both require
 the same shader rewrite, and they pair naturally — multi-draw indirect
 is a no-op CPU-win without bindless because per-group `glBindTexture`
 calls would still serialize.
 **Estimated scope: 2-3 weeks.** Plan + spec to be written by the
 brainstorm + spec steps below.
 ---
 ## Where N.4 left things
 ### Branch state
 If this handoff is being read on `main` after merging the N.4 worktree:
 N.4 commits land at the head of main. The relevant final commits:
 - `c445364` — N.4 SHIP (flag default-on, plan final, roadmap, memory)
 - `573526d` — perf pass 1-4 (drop dead lookup, sort, cull, hash memo)
 - `7b41efc` — FirstIndex/BaseVertex + Issue #47 + grouped instanced
 - `943652d` — load triggers + `batch.Key.SurfaceId` source
 - `01cff41` — Tasks 22+23 (`WbDrawDispatcher` + side-table)
 If the worktree branch (`claude/tender-mcclintock-a16839`) hasn't been
 merged yet, that's where the work is. Verify with `git log --oneline`.
 ### What works in N.4
 - `ACDREAM_USE_WB_FOUNDATION=1` is default-on. WB's `ObjectMeshManager`
  loads, decodes, and uploads every entity mesh. Our existing
  `TextureCache` decodes textures (palette-aware, per-instance overrides
  via `GetOrUploadWithPaletteOverride`).
 - `WbDrawDispatcher.Draw`:
  - Walks visible entities (per-landblock AABB cull + per-entity AABB
    cull + portal visibility)
  - Buckets every (entity × meshRef × batch) tuple by
    `GroupKey(Ibo, FirstIndex, BaseVertex, IndexCount, TextureHandle, Translucency)`
  - Single `glBufferData` upload of all matrices for the frame
  - Per group: `glActiveTexture(0) + glBindTexture(2D, handle) + glBindBuffer(EBO, ibo) + glDrawElementsInstancedBaseVertexBaseInstance(..., FirstInstance)`
  - Two passes: opaque (front-to-back sorted) + translucent
 - 940/948 tests pass (8 pre-existing failures unrelated to rendering).
 - Visual verification at Holtburg passed: scenery + characters render
  correctly with full close-detail geometry (Issue #47 preserved).
 ### What N.5 inherits
 These are levers N.5 will pull on:
 - **WB's modern rendering is already active.** `OpenGLGraphicsDevice`
  detected GL 4.3 + bindless on first run; WB's `_useModernRendering`
  is true; every mesh lives in WB's single `GlobalMeshBuffer` (one VAO,
  one VBO, one IBO).
 - **Bindless handles are already populated.** `ObjectRenderBatch.BindlessTextureHandle`
  is non-zero for batches WB owns the texture for. (See gotcha #2
  below for entities with palette overrides — those use acdream's
  `TextureCache` which doesn't expose bindless handles yet.)
 - **The instance VBO is acdream-owned** (`WbDrawDispatcher._instanceVbo`)
  with locations 3-6 patched onto WB's global VAO. Stride 64 bytes
  (one mat4). N.5 expands this to (mat4 + uvec2 handle) = 80 bytes.
 ### Three load-bearing WB API gotchas N.4 surfaced
 These bit us hard during Task 26 visual verification. Documented in
 CLAUDE.md "WB integration cribs" + plan adjustments 7-9 +
 `memory/project_phase_n4_state.md`. Re-stating here because they
 reshape the design space:
 1. **`ObjectMeshManager.IncrementRefCount(id)` is NOT lifecycle-aware.**
   It only bumps a usage counter. Mesh loading is fired separately
   via `PrepareMeshDataAsync(id, isSetup)`. The result auto-enqueues
   to `_stagedMeshData` (line 510 of `ObjectMeshManager.cs`); our
   existing `WbMeshAdapter.Tick()` drains it. `WbMeshAdapter.IncrementRefCount`
   already calls `PrepareMeshDataAsync`. **N.5 doesn't need to change
   this — just don't break it.**
 2. **`ObjectRenderBatch.SurfaceId` is unset.** WB constructs batches
   with `Key = batch.Key` (a `TextureAtlasManager.TextureKey` struct
   that has a `SurfaceId` field) but never populates the top-level
   `SurfaceId` property. Read `batch.Key.SurfaceId`. **N.5 keeps this
   pattern.**
 3. **WB's modern rendering packs every mesh into ONE global
   VAO/VBO/IBO.** Each batch's `IBO` field points to the global IBO;
   the batch's actual slice is identified by `FirstIndex` (offset into
   IBO, in *indices*) and `BaseVertex` (offset into VBO, in *vertices*).
   N.4's draw uses `glDrawElementsInstancedBaseVertexBaseInstance`
   with those offsets. **N.5's `DrawElementsIndirectCommand` per-group
   record will carry `firstIndex` + `baseVertex` for the same reason.**
 ---
 ## What N.5 is — technical detail
 ### The two-feature pairing
 **Bindless textures** (`GL_ARB_bindless_texture`):
 - Each texture handle is a 64-bit integer (`uvec2` in GLSL).
 - Shader declares `layout(bindless_sampler) uniform sampler2D ...` or
  receives the handle as a per-vertex-attribute `uvec2`.
 - No `glBindTexture` needed at draw time — the handle IS the binding.
 - Handle generation: `glGetTextureHandleARB(textureId)` followed by
  `glMakeTextureHandleResidentARB(handle)` (the texture must be
  resident on the GPU; non-resident handles produce GPU faults).
 **Multi-draw indirect** (`glMultiDrawElementsIndirect`):
 - Indirect command struct layout (must match `DrawElementsIndirectCommand`):
  ```c
  struct {
      uint count;          // index count for this draw
      uint instanceCount;  // number of instances
      uint firstIndex;     // offset into IBO, in indices
      int  baseVertex;     // vertex offset into VBO
      uint baseInstance;   // first instance ID (offsets per-instance attribs)
  };
  ```
 - Build a buffer of N of these structs (one per group), upload once,
  fire one GL call: `glMultiDrawElementsIndirect(mode, indexType, ptr, drawcount, stride)`.
 - The driver issues all N draws in one shot. Effectively zero CPU
  overhead per draw beyond uploading the indirect buffer.
 **Why pair them.** Multi-draw indirect doesn't let you change uniform
 state between draws. So if textures are bound via `glBindTexture` per
 group, you'd still need N CPU-side setup steps before each indirect
 call — defeating the purpose. Bindless removes that constraint by
 encoding the texture handle as per-instance data the shader reads
 directly. With both, the modern render loop becomes:
 ```
 1. Upload instance buffer (mat4 + uvec2 handle, per-instance) — once per frame
 2. Upload indirect command buffer (one DEIC per group) — once per frame
 3. glBindVertexArray(globalVAO) — once
 4. glMultiDrawElementsIndirect(...) — ONCE per pass
 ```
 That's it. No per-group state changes.
 ### Instance attribute layout
 Currently (N.4): location 3-6 = mat4 model matrix (16 floats = 64 bytes).
 N.5 (proposed): location 3-6 = mat4 + location 7 = uvec2 bindless
 handle = 16 floats + 2 uints = 72 bytes (16-aligned to 80 bytes per
 WB's `InstanceData` precedent).
 Or use std140-aligned struct:
 ```c
 struct InstanceData {
    mat4 transform;        // locations 3-6
    uvec2 textureHandle;   // location 7
    uvec2 _pad;            // padding to 80
 };
 ```
 Brainstorm should decide if we copy WB's `InstanceData` struct (Pack=16,
 80 bytes including CellId/Flags fields we don't use) or define our own
 minimal version. The 80-byte stride matches WB's so global VAO state
 configured by WB stays compatible if the legacy WB draw path ever runs.
 ### Per-instance entity texture handles
 Here's the wrinkle. N.4 uses `WbDrawDispatcher.ResolveTexture` to map
 each (entity, batch) to a GL texture handle:
 - Tree (no overrides): `_textures.GetOrUpload(surfaceId)` → 2D texture handle
 - NPC with palette override: `_textures.GetOrUploadWithPaletteOverride(...)` → composite-cached 2D texture handle
 - Anything with surface override: `_textures.GetOrUploadWithOrigTextureOverride(...)` → composite-cached 2D texture handle
 Those are all `GLuint` 32-bit GL texture *names*, not bindless handles.
 **N.5 needs `TextureCache` to publish bindless handles for everything
 it owns, not just WB-owned textures.**
 Implementation sketch:
 - `TextureCache` adds a parallel cache keyed identically but storing
  64-bit bindless handles. On first request, generate via
  `glGetTextureHandleARB(textureId)` + make resident.
 - New API: `GetBindlessHandle(uint surfaceId, ...)` returns the handle.
 - Or: change every `GetOrUpload*` method to return both the GL name
  and the bindless handle (or just the handle; let GL name fall out
  if anyone needs it later).
 WB's `ObjectRenderBatch.BindlessTextureHandle` covers the atlas-tier
 case. For per-instance entities, we use `TextureCache`'s handle.
 ### The new shader
 Reuse WB's `StaticObjectModern.vert` / `StaticObjectModern.frag` as a
 template. Read those files cold. They already do bindless + the
 instance-data layout. Adapt to acdream's `mesh_instanced.vert/frag`
 conventions:
 - Keep the `uViewProjection` uniform, lighting UBO at binding=1, fog
  uniforms.
 - Add `#version 430 core` + `#extension GL_ARB_bindless_texture : require`.
 - Replace `uniform sampler2D uDiffuse` with a `uvec2` per-vertex
  attribute (location 7) → reconstruct sampler in vertex shader OR
  pass through to fragment via flat varying.
 - Drop `uTranslucencyKind` uniform, OR keep it (still set per-pass —
  multi-draw indirect doesn't break uniforms; only state that varies
  per-draw is the constraint).
 ### Translucency
 Multi-draw indirect can't change blend state mid-draw. Solution:
 **still use two passes** (opaque + translucent), but within translucent
 keep the per-blendfunc sub-passes (additive, alpha-blend, inv-alpha).
 Three sub-passes within translucent. Each sub-pass = one
 `glMultiDrawElementsIndirect` over its filtered groups.
 Or: if perf allows, fold all four blend modes into the shader via
 per-instance blendmode int, sort all translucent groups by blendmode
 in the indirect buffer, switch blend state at sub-pass boundaries.
 Brainstorm decides the cleanest pattern.
 ---
 ## Files to read before brainstorming
 In rough order:
 1. **N.4 plan + spec** — `docs/superpowers/plans/2026-05-08-phase-n4-rendering-foundation.md`
   (status: Final). Adjustments 7-10 capture the gotchas. Spec at
   `docs/superpowers/specs/2026-05-08-phase-n4-rendering-foundation-design.md`.
 2. **N.4 dispatcher source** — `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs`.
   This is what you're modifying. Read end-to-end.
 3. **WB's modern rendering shaders** — `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Shaders/StaticObjectModern.vert`
   + `StaticObjectModern.frag`. The template you're adapting from.
 4. **WB's `ObjectMeshManager.UploadGfxObjMeshData`** — lines ~1654-1780
   of `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/ObjectMeshManager.cs`.
   Shows how WB sets up the modern path's VBO/IBO/VAO. Especially note
   how it patches in instance attribute slots (locations 3-6) on the
   global VAO and configures location 7+ for bindless handles.
 5. **WB's `ObjectRenderBatch`** — same file, lines ~166-184. Note the
   `BindlessTextureHandle` field — already populated when `_useModernRendering`
   is on.
 6. **Our `TextureCache`** — `src/AcDream.App/Rendering/TextureCache.cs`.
   Three composite caches: by surface id, by surface+origTex, by
   surface+origTex+palette. N.5 adds parallel bindless-handle caches.
 7. **CLAUDE.md "WB integration cribs"** section. Lines ~28-80. The
   three gotchas + the integration architecture in plain language.
 8. **Memory: `project_phase_n4_state.md`** — same content from a
   different angle. Reading both helps lock in the gotchas.
 ---
 ## Brainstorm questions
 These are the questions to resolve in the brainstorm step. Don't
 prejudge them — bring them to the user with options + recommendation:
 1. **Instance attribute layout.** Match WB's `InstanceData` struct
   (80 bytes including CellId/Flags fields we don't use) for global
   VAO compatibility, or define a minimal acdream-specific version
   (mat4 + handle = ~72 bytes padded to 80)?
 2. **Bindless handle generation strategy.**
   - At texture upload time? (Eager — every texture that lands in
     `TextureCache` gets a handle. Memory cost ~per-texture state.)
   - On first draw lookup? (Lazy — cache fills as scene exercises
     content. Possible first-use stall.)
   - At spawn time via the spawn adapter? (Tied to lifecycle. Cleanest
     but requires touching the spawn path.)
 3. **Translucent pass structure.** Three sub-indirect-draws (one per
   blend mode) or a single sorted indirect buffer with per-instance
   blend mode + state-flip at sub-pass boundaries? Or: just iterate
   per-group like N.4 for translucent only (translucent groups are a
   small fraction of total)?
 4. **Persistent-mapped indirect + instance buffers.** Use
   `GL_ARB_buffer_storage` + `MAP_PERSISTENT_BIT | MAP_COHERENT_BIT`?
   Triple-buffered ring + sync object? Or stick with `glBufferData`
   (still one upload per frame, just larger)? Persistent mapping is
   ~2-5% per-frame win in our context but adds buffer-management
   complexity.
 5. **Shader unification.** Keep `mesh_instanced` for legacy + add
   `mesh_indirect` for modern, or replace `mesh_instanced` entirely?
   Replacement requires the legacy `InstancedMeshRenderer` (escape
   hatch under `ACDREAM_USE_WB_FOUNDATION=0`) to also use the new
   shader, which... probably doesn't matter if we delete legacy in
   N.6 anyway. Brainstorm.
 6. **Conformance test strategy.** N.4 used visual verification at
   Holtburg as the gate. N.5's gate is "no visual regression vs N.4
   AND measurable CPU win." How do we measure CPU? `[WB-DIAG]`
   counters give draw count + group count; we need frame-time
   counters too. Add to the dispatcher? Use a profiler?
 7. **Per-instance entity bindless.** `TextureCache.GetOrUpload*`
   returns a GL name. The dispatcher (or `TextureCache` itself) needs
   to convert that to a bindless handle. Design questions:
   - Where does the conversion happen?
   - When is the texture made resident? (Residency is global state;
     too many resident textures hits driver limits.)
   - What about palette/surface overrides — same caching key as the
     name, just a parallel handle dictionary?
 8. **Escape hatch.** N.4 keeps `ACDREAM_USE_WB_FOUNDATION=0` as a
   fallback. N.5 needs to decide: does the new shader REPLACE the
   N.4 dispatcher's draw path (so flag-on means N.5 modern path,
   flag-off means legacy `InstancedMeshRenderer`)? Or do we add a
   separate flag (`ACDREAM_USE_MODERN_DRAW`) so users can toggle
   N.4 vs N.5 vs legacy independently? Three-way flag is more
   complex but useful for A/B during rollout.
 ---
 ## Spec structure
 After the brainstorm, the spec doc covers:
 1. **Architecture diagram** — how `WbDrawDispatcher` changes shape.
   Where the indirect buffer lives. Where bindless handles flow from.
 2. **Instance data layout** — exact struct, byte offsets, GL attribute
   pointer setup.
 3. **TextureCache changes** — new methods, new cache, residency
   policy.
 4. **Shader files** — name(s), version, extensions, in/out variables.
 5. **Conformance tests** — what to write, what coverage to claim.
 6. **Acceptance criteria** — visual identity to N.4 + measured CPU
   delta.
 7. **Risks** — driver bugs in bindless / indirect, residency limits,
   shader compile issues on weird GPUs, the legacy escape hatch
   breaking.
 Spec lives at: `docs/superpowers/specs/2026-05-XX-phase-n5-modern-rendering-design.md`.
 ## Plan structure
 After the spec, the plan doc lays out the week-by-week task list.
 Match N.4's plan structure (living document, task checkboxes, commit
 SHAs appended, adjustments documented inline). Plan lives at:
 `docs/superpowers/plans/2026-05-XX-phase-n5-modern-rendering.md`.
 Suggested initial breakdown (brainstorm + spec will refine):
 - **Week 1** — Plumbing: bindless handle generation in `TextureCache`,
  shader rewrite (compile + bind), instance-attrib layout updated to
  mat4+handle. Dispatcher still uses per-group draws but reads
  textures bindless. Validate: visual identical to N.4.
 - **Week 2** — Indirect: build `DrawElementsIndirectCommand` buffer
  per frame, switch to `glMultiDrawElementsIndirect`. Three-pass
  translucent (or whatever brainstorm decides). Validate: visual
  identical, draw-call count drops to 2-4 per frame.
 - **Week 3** — Polish + ship: persistent-mapped buffers if brainstorm
  voted yes, profiler/counters, visual verification, flag flip, plan
  finalization.
 ---
 ## Acceptance criteria for the whole phase
 - Visual output identical to N.4 (no character regressions, no
  scenery missing, no z-fighting introduced)
 - `[WB-DIAG]` shows `drawsIssued` ≤ ~5 per frame (down from N.4's
  few hundred)
 - Frame time measurably lower in dense scenes (specify what scenes
  to test in the spec — probably Holtburg courtyard + Foundry
  interior)
 - All tests still green (940/948 + any new conformance tests)
 - `ACDREAM_USE_WB_FOUNDATION=0` escape hatch still works
 - Plan doc finalized, roadmap updated, memory captured if N.5
  surfaces durable lessons (it almost certainly will — bindless
  + indirect both have well-known driver gotchas)
 ---
 ## What you'll be doing in the first 30 minutes
 1. Read this handoff in full.
 2. Read CLAUDE.md "WB integration cribs" section.
 3. Read `WbDrawDispatcher.cs` end-to-end.
 4. Skim WB's `StaticObjectModern.vert/frag` + `ObjectMeshManager.UploadGfxObjMeshData`
   to ground the reference.
 5. Verify build is green: `dotnet build`.
 6. Verify N.4 ship is intact: `dotnet test --filter "FullyQualifiedName~Wb|MatrixComposition"`
   should produce 60 passing tests, 0 failures.
 7. Invoke the `superpowers:brainstorming` skill with the user. Walk
   through the 8 brainstorm questions above. Capture decisions in a
   spec.
 8. Write the spec at the path above.
 9. Write the plan at the path above.
 10. Begin Week 1 implementation per the plan.
 Don't skip the brainstorm. Multi-draw indirect + bindless have several
 real driver-compatibility / API-shape decisions that need user input,
 not "the agent makes a call and goes." This phase is structurally the
 same shape as N.4 — brainstorm → spec → plan → tasks-with-checkboxes →
 commits-update-checkboxes → final SHIP commit.
 ---
 ## Things to NOT do
 - **Don't delete the legacy `InstancedMeshRenderer`.** It's the N.4
  escape hatch. N.6 retires it after N.5 is proven default-on.
 - **Don't fork WB.** N.4 deliberately avoided fork patches by using
  the side-table pattern (`AcSurfaceMetadataTable`). Stay on that
  path. If you need data WB doesn't expose, add a side-table or
  decode it yourself from dats.
 - **Don't try to make per-instance entities use WB's `TextureAtlasManager`.**
  That's N.6+ territory. acdream's `TextureCache` owns palette/surface
  overrides because WB's atlas is keyed by `(surfaceId, paletteId,
  stippling, isSolid)` and our overrides don't fit cleanly. Bindless
  handles let us escape that mismatch — handles for both atlas-tier
  AND per-instance-tier textures, no atlas adoption needed.
 - **Don't skip visual verification.** N.4 surfaced three bugs at
  visual verification that no test caught. Don't trust "build green +
  tests pass" — exercise the rendering path with the local ACE server.
 - **Don't extend the phase scope.** N.5 is bindless + indirect on
  the existing rendering pipeline. Texture array atlas, GPU-side
  culling, terrain wiring — all of those are subsequent phases. If
  the brainstorm tries to expand, push back.
 ---
 ## Reference: the N.4 dispatcher flow you're modifying
 ```
 Draw(camera, landblockEntries, frustum, ...) {
  // Phase 1: walk entities, build groups
  foreach (entity, meshRef, batch) {
    cull, classify into _groups[GroupKey]
  }
  // Phase 2: lay matrices contiguously
  // Phase 3: glBufferData(_instanceVbo, allMatrices)
  // Phase 4: bind global VAO once
  // Phase 5: opaque pass (sorted)
  foreach (group in _opaqueDraws) {
    glBindTexture(group.handle)
    glBindBuffer(EBO, group.ibo)
    glDrawElementsInstancedBaseVertexBaseInstance(...)
  }
  // Phase 6: translucent pass
 }
 ```
 After N.5, Phases 5 and 6 collapse to:
 ```
 glBindBuffer(DRAW_INDIRECT_BUFFER, _opaqueIndirect)
 glMultiDrawElementsIndirect(GL_TRIANGLES, GL_UNSIGNED_SHORT, 0, opaqueGroups.Count, sizeof(DEIC))
 glBindBuffer(DRAW_INDIRECT_BUFFER, _translucentIndirect)
 // 3 sub-calls for translucent or 1 if shader-folded
 glMultiDrawElementsIndirect(...)
 ```
 That's the destination. Get there cleanly.
 Good luck. Holler at the user if any of the brainstorm questions feel
 genuinely ambiguous after reading the references — they care about
 this phase landing right and will engage on design questions.
--- a/docs/research/2026-05-09-phase-n5b-handoff.md
+++ b/docs/research/2026-05-09-phase-n5b-handoff.md
@ -1,445 +0,0 @@
 # Phase N.5b — Terrain on the Modern Rendering Path — Cold-Start Handoff
 **Created:** 2026-05-09, immediately after N.5 ship + roadmap A.5 addition.
 **Audience:** the next agent picking up terrain rendering work.
 **Purpose:** give you everything you need to start N.5b cold, without
 spelunking through the N.5 session's history.
 ---
 ## TL;DR
 N.5 just shipped: `WbDrawDispatcher` lifts entity rendering onto bindless
 textures + `glMultiDrawElementsIndirect`. CPU dispatcher 1.23 ms / frame
 median at Holtburg courtyard, ~810 fps sustained. **Entities only —
 terrain is still on a separate legacy renderer.**
 **N.5b's job: port terrain rendering onto the same modern primitives that
 N.5 just delivered.** Concretely:
 1. Replace `TerrainRenderer` + `TerrainChunkRenderer` (per-landblock VAO,
   `glDrawElements`, `sampler2D` atlases) with a multi-draw-indirect
   dispatcher analogous to `WbDrawDispatcher`, sharing the modern path's
   bindless texture infrastructure where it makes sense.
 2. Keep terrain visually identical to today. The legacy `TerrainAtlas` +
   `terrain.vert/.frag` already render correctly; don't introduce visual
   regressions.
 3. Resolve issue #51 (WB's terrain split formula diverges from retail's
   `FSplitNESW`) — see "Load-bearing constraint" below.
 The roadmap estimate is **~1 week** because the modern-path primitives
 are already built. The actual work is porting + bridging + a real
 correctness decision on the split formula.
 ---
 ## Load-bearing constraint: Issue #51 (terrain split formula)
 This is the design decision that will dominate the brainstorm. **Read
 `docs/ISSUES.md` issue #51 in full before brainstorming.**
 The short version:
 - **acdream's terrain split formula** is the retail-decomp `FSplitNESW`
  (constants `0x0CCAC033` / `0x421BE3BD` / `0x6C1AC587` / `0x519B8F25`).
  Documented in `CLAUDE.md` as **the** real AC formula. Ours is degree-2
  polynomial in (x,y). Used by:
  - `src/AcDream.Core/Physics/TerrainSurface.cs:113-120` (physics —
    `IsSplitSWtoNE`)
  - `src/AcDream.Core/World/TerrainBlending.cs` (visual mesh)
 - **WB's terrain split formula** in `references/WorldBuilder/WorldBuilder.Shared/Modules/Landscape/Lib/TerrainUtils.cs:44`
  is LINEAR in (x,y). Different math; they cannot be algebraically
  equivalent. They disagree on a meaningful fraction of cells — up to
  ~2m height delta on sloped cells.
 - **WB's `TerrainGeometryGenerator`** (the obvious adoption target for
  N.5b's mesh path) uses WB's formula. If we adopt it wholesale, our
  visual terrain disagrees with our physics (which uses retail's
  formula). Player floats / sinks. Already-fixed bug class returns.
 **Three viable design paths** (the brainstorm has to pick one):
 - **Path A — Adopt WB's formula everywhere.** Switch both physics AND
  visual mesh to WB's `CalculateSplitDirection`. Use WB's
  `TerrainGeometryGenerator` directly. Visual + physics stay synced.
  Risk: physics now disagrees with retail server-authoritative Z by up
  to ~2m on sloped cells. Server-side validation (if any) might reject
  movements; the player might "snap" to server's Z when packets land.
  Need to confirm whether ACE actually validates Z or trusts the
  client. Lowest implementation effort.
 - **Path B — Keep retail's formula; fork-patch WB.** Patch
  `references/WorldBuilder/.../TerrainUtils.cs` to use retail's formula
  in our fork. Push the patch to the `acdream` branch of the fork (per
  the WB submodule plumbing fixed in the previous session). Submit
  upstream PR if Chorizite wants it. Most retail-faithful. Implementation
  effort: medium. Coordination overhead with upstream.
 - **Path C — Use WB's mesh layout but our formula.** Don't use WB's
  `TerrainGeometryGenerator` directly. Instead port WB's *mesh layout*
  (vertex buffer shape, index buffer per landblock, atlas integration)
  into a new acdream-side `TerrainGeometryGenerator` that uses retail's
  formula. Highest effort but cleanest separation — no fork patches.
 Recommendation in the brainstorm: probably **Path A** if quantification
 shows ACE doesn't validate Z aggressively (retail's network protocol
 is "client tells server position; server trusts within sanity bounds"),
 otherwise **Path B**. Path C is overengineered for the level of
 divergence.
 **Step 1 of the brainstorm:** quantify the divergence. Run WB's formula
 + retail's formula across all (lbX, lbY, cellX, cellY) tuples for
 several representative landblocks (Holtburg, Foundry, open landscape,
 some sloped terrain like Direlands). Record disagreement rate. If <5%
 of cells disagree, Path A's risk is bounded; if >20%, Path B becomes
 more attractive.
 ---
 ## Where N.5 left things
 ### Branch state
 After last session:
 - `main` is at `a64cd11` ("docs(roadmap): add A.5 — two-tier streaming")
 - N.5 SHIP at `27eaf4e` (merge commit)
 - N.5 ship-amendment at `e0dbc9c` (legacy renderers retired)
 - Legacy `InstancedMeshRenderer` + `StaticMeshRenderer` + `WbFoundationFlag`
  ARE GONE. Bindless is mandatory; missing extensions throws
  `NotSupportedException` at startup.
 ### What works in N.5
 - **Entity rendering:** `WbDrawDispatcher` does ~12-15 GL calls per frame
  for all visible entities regardless of scene complexity. Three SSBO
  uploads (instance matrices @ binding=0, batch data @ binding=1,
  indirect commands) + 2 `glMultiDrawElementsIndirect` calls (opaque +
  transparent passes).
 - **Bindless texture infrastructure:** `BindlessSupport` wrapper +
  `TextureCache` parallel `UploadRgba8AsLayer1Array` path + three
  `Bindless*` `GetOrUpload` methods + two-phase `Dispose`. All textures
  on the WB modern path are 1-layer `Texture2DArray` + `sampler2DArray`.
 - **mesh_modern.vert/.frag** preserves the full `SceneLighting` UBO
  (8 lights + fog + lightning flash + per-channel clamp) — visual
  identity to N.4 confirmed at user gates.
 - **Diagnostic:** CPU stopwatch + GL_TIME_ELAPSED queries logged via
  `[WB-DIAG]` (GPU timing currently shows 0/0 — query polling needs
  double-buffering, deferred to N.6).
 ### What N.5b inherits
 These are levers N.5b will pull on:
 - **`BindlessSupport`** at `src/AcDream.App/Rendering/Wb/BindlessSupport.cs`
  — already wraps `ArbBindlessTexture`. Reusable for terrain textures.
 - **`DrawElementsIndirectCommand` struct** at `src/AcDream.App/Rendering/Wb/DrawElementsIndirectCommand.cs`
  — 20-byte layout, ready to populate per-landblock terrain commands.
 - **`BuildIndirectArrays` helper** at `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs`
  — pure CPU layout helper, currently scoped to entities; could
  generalize for terrain.
 - **`TextureCache`** with parallel Texture2DArray bindless cache —
  but terrain has its own `TerrainAtlas` (multi-layer texture array
  for splat blending). N.5b decides whether to integrate or keep
  separate.
 - **`SceneLightingUbo`** at binding=1 — terrain.frag already consumes
  it; the new modern terrain shader continues that.
 - **Retail's `FSplitNESW`** in `src/AcDream.Core/World/TerrainBlending.cs`
  — the formula to preserve (or replace, per Path A/B/C decision).
 ### What still uses the legacy path (NOT N.5b's job)
 - **Sky rendering** (`SkyRenderer.cs`) — N.8 territory.
 - **Particles** (`ParticleRenderer.cs`) — N.8 territory.
 - **Debug lines** (`DebugLineRenderer.cs`) — fine as-is.
 - **UI / text** (`TextRenderer.cs` + ImGui) — fine as-is; ImGui has its
  own backend.
 ---
 ## What N.5b is — technical detail
 ### Today's terrain stack (1383 lines acdream + ~140 lines shaders)
 | File | Lines | Role |
 |---|---|---|
 | `src/AcDream.App/Rendering/TerrainRenderer.cs` | 247 | Top-level orchestration; per-landblock cull + draw |
 | `src/AcDream.App/Rendering/TerrainChunkRenderer.cs` | 454 | Per-landblock VAO + IBO management; `glDrawElements` per visible chunk |
 | `src/AcDream.App/Rendering/TerrainAtlas.cs` | 386 | Multi-layer `Texture2DArray` atlas for terrain splat textures |
 | `src/AcDream.App/Rendering/Shaders/terrain.vert` | 147 | Per-vertex world position, normal, UV, palCode |
 | `src/AcDream.App/Rendering/Shaders/terrain.frag` | 149 | Splat blending across 4 corner textures |
 **Per-frame today:** for each visible landblock, bind its VAO + IBO,
 bind the terrain texture atlas, set per-landblock uniforms, issue
 `glDrawElements`. With 25 landblocks at default radius=2, that's ~25
 draw calls per frame for terrain (cheap, but doesn't scale).
 ### WB's terrain stack (1937 lines + ~200 lines shaders)
 | File | Lines | Role |
 |---|---|---|
 | `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TerrainRenderManager.cs` | 1023 | Top-level coordinator; uses multi-draw-indirect already |
 | `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TerrainGeometryGenerator.cs` | 326 | Mesh generation per landblock (uses WB's split formula — see #51) |
 | `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/LandSurfaceManager.cs` | 588 | Texture atlas management + alpha mask generation for splat blending |
 | `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Shaders/Landscape.vert/.frag` | ~200 | Modern shader; consumes SSBO instance data + bindless atlas handle |
 WB's renderer is structurally close to what N.5b targets. Key differences
 from acdream:
 - WB uses **uint32 indices** (`DrawElementsType.UnsignedInt`) for
  terrain — landblocks have more vertices than fit in ushort range.
  N.5's `WbDrawDispatcher` uses `UnsignedShort` for entities.
 - WB packs all visible terrain into shared mesh buffers + dispatches
  via `glMultiDrawElementsIndirect`. We can mirror that pattern.
 - WB's `LandSurfaceManager` builds per-landblock alpha masks for splat
  blending; this is the bulk of its 588 lines. Different model from
  our `TerrainAtlas` which uses palCode-based blending in the fragment
  shader.
 ### What N.5b actually does
 Roughly four sub-pieces:
 1. **Terrain mesh on global VBO/IBO.** Following N.5's pattern, all
   visible terrain landblocks pack into a single global vertex buffer
   + index buffer. Per-landblock entries become `DrawElementsIndirectCommand`
   records with `firstIndex` + `baseVertex` offsets. One
   `glMultiDrawElementsIndirect` call per pass.
 2. **Bindless terrain atlas.** Either (a) port `TerrainAtlas` to use
   bindless handles + sampler2DArray (small change, keeps current
   blending math), or (b) adopt WB's `LandSurfaceManager` (bigger
   change, switches to alpha-mask blending). Brainstorm decides.
 3. **New shader `terrain_modern.vert/.frag`** that:
   - Reads per-landblock data from an SSBO (analogous to
     mesh_modern's `Batches[]`)
   - Samples the terrain atlas via bindless `sampler2DArray` handle
   - Continues to consume `SceneLighting` UBO @ binding=1 (no
     visual identity regression vs N.4 — same lighting math)
 4. **Resolve issue #51** per Path A/B/C decision in the brainstorm.
 ### Per-frame target shape
 ```
 // Once at init:
 Build global terrain VAO + VBO + IBO (resizable; grows as landblocks stream in)
 Generate bindless handles for terrain atlas
 // Per frame:
 1. Frustum cull landblocks (existing per-landblock AABB test)
 2. Build per-visible-landblock IndirectGroupInput list
 3. Upload _terrainBatchSsbo + _terrainIndirectBuffer
 4. glBindVertexArray(globalTerrainVao)
 5. glBindBufferBase(SHADER_STORAGE_BUFFER, 1, _terrainBatchSsbo)
 6. glBindBuffer(DRAW_INDIRECT_BUFFER, _terrainIndirectBuffer)
 7. glMultiDrawElementsIndirect(...)  // ONCE per pass — opaque pass
   (terrain has no transparent; one indirect call total)
 ```
 Total ~6-8 GL calls per frame for terrain regardless of scene size.
 At radius=5 (121 landblocks) this is the same number of GL calls as
 at radius=2 (25 landblocks).
 ---
 ## Files to read before brainstorming
 In rough order:
 1. **`docs/ISSUES.md` issue #51** (49-103). Load-bearing constraint.
 2. **`CLAUDE.md`** the "Reference hierarchy by domain" terrain row +
   "Reference repos: check ALL FOUR" — terrain math is one of the
   places where checking multiple references matters most.
 3. **acdream terrain stack:**
   - `src/AcDream.App/Rendering/TerrainRenderer.cs` (247 lines, easy
     read)
   - `src/AcDream.App/Rendering/TerrainChunkRenderer.cs` (454 lines —
     this is the per-landblock GL plumbing that goes away in N.5b)
   - `src/AcDream.App/Rendering/TerrainAtlas.cs` (386 lines —
     multi-layer atlas)
   - `src/AcDream.App/Rendering/Shaders/terrain.vert/.frag` (~300
     lines combined)
   - `src/AcDream.Core/World/TerrainBlending.cs` (the FSplitNESW
     side; preserve or replace)
 4. **WB terrain stack:**
   - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TerrainRenderManager.cs`
     (1023 lines — the model to mirror; multi-draw indirect already
     in place)
   - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TerrainGeometryGenerator.cs`
     (326 lines — uses WB's split formula; per #51)
   - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/LandSurfaceManager.cs`
     (588 lines — alpha-mask atlas; alternative to our `TerrainAtlas`)
   - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Shaders/Landscape.vert/.frag`
   - `references/WorldBuilder/WorldBuilder.Shared/Modules/Landscape/Lib/TerrainUtils.cs:44`
     (CalculateSplitDirection — WB's formula)
 5. **N.5 plan + spec** (cribs for the modern-path pattern):
   - `docs/superpowers/plans/2026-05-08-phase-n5-modern-rendering.md`
     (what we did, including amendments)
   - `docs/superpowers/specs/2026-05-08-phase-n5-modern-rendering-design.md`
     (decisions log)
 6. **Memory: `project_phase_n5_state.md`** — three high-value gotchas
   from N.5 (texture target lock-in, bindless Dispose order,
   GL_TIME_ELAPSED double-buffering). All apply to N.5b.
 ---
 ## Brainstorm questions
 These are the questions to resolve in the brainstorm step. Don't
 prejudge — bring them to the user with options + recommendation:
 1. **Path A vs B vs C** for issue #51 (the terrain split formula). The
   biggest decision; everything else flows from it. Should be
   informed by quantifying the divergence rate first (run both
   formulas across representative landblocks).
 2. **Atlas model.** Keep `TerrainAtlas` (palCode-based fragment shader
   blending) and just bindless-ify it, or adopt WB's `LandSurfaceManager`
   (alpha-mask blending)? Tradeoff: minimal change vs alignment with
   WB. Visual outcome should be identical either way.
 3. **Mesh ownership.** Use a single global VBO/IBO for all terrain
   (mirror N.5's pattern), or per-landblock VBO/IBO with multi-draw
   indirect over them? Single global is more cache-friendly + more
   like N.5, but requires resizable buffer management. Per-landblock
   is simpler but doesn't share the IBO across draws.
 4. **Index format.** N.5 uses `UnsignedShort` (max 64K verts per
   draw). Terrain landblocks have many more verts than that. WB uses
   `UnsignedInt`. Just commit to `UnsignedInt` for terrain?
 5. **Shader unification.** Separate `terrain_modern.vert/.frag` or
   merge with `mesh_modern.vert/.frag` via uniforms? Probably separate
   since the vertex layouts differ (terrain has palCode; entities
   have UV).
 6. **Streaming integration.** Today's `TerrainChunkRenderer` integrates
   with the streaming loader (landblocks come and go). N.5b's global
   buffer model needs a strategy for adding/removing landblocks from
   the global VBO/IBO without per-add reallocation. Free-list /
   compaction / fixed-slot allocator?
 7. **Conformance test.** Per the lessons from N.2, "WB's terrain
   formula differs from retail" — we need a test that proves our
   visual terrain matches our physics terrain (i.e., visual mesh Z
   at any (X,Y) equals `TerrainSurface.GetHeight(X,Y)`). Run a sweep
   across ~1M (X,Y) points; assert |delta| < epsilon.
 8. **Visual verification gate.** Holtburg + Foundry + sloped terrain
   (Direlands?) + cell transitions. The split-formula-disagreement
   bug class shows up as terrain "wobble" at cell boundaries — that's
   the specific thing to look for.
 ---
 ## Acceptance criteria for the whole phase
 - Visual terrain identical to current legacy path (no missing chunks,
  no z-fighting at cell boundaries, no texture seams)
 - `[WB-DIAG]` shows terrain accounting for ~6-8 GL calls per frame
  regardless of scene size (currently scales with visible landblock
  count, ~25-121 calls)
 - Frame time measurably lower in dense-terrain scenes (specify scenes
  in the spec — probably radius=5 outdoor roaming)
 - Conformance test: visual mesh Z agrees with `TerrainSurface.GetHeight`
  within epsilon across a 1M-point sweep
 - All existing tests still green
 - The split-formula decision (#51) is resolved with a clear writeup
  in the spec
 ---
 ## What you'll be doing in the first 30 minutes
 1. Read this handoff in full.
 2. Read `docs/ISSUES.md` issue #51 in full.
 3. Read CLAUDE.md "Reference hierarchy by domain" terrain row.
 4. Read `TerrainRenderer.cs` + `TerrainChunkRenderer.cs` end-to-end.
 5. Skim `TerrainRenderManager.cs` (WB's) — at least the multi-draw
   indirect dispatch section.
 6. Verify build is green: `dotnet build`.
 7. Verify N.5 ship is intact: `dotnet test --filter "FullyQualifiedName~Wb|FullyQualifiedName~MatrixComposition|FullyQualifiedName~TextureCacheBindless"` should produce 71 passing tests, 0 failures.
 8. Quantify the formula divergence (Path A/B/C decision input):
   write a one-shot test that runs both formulas across all
   (lbX, lbY, cellX, cellY) tuples for ~10 representative landblocks
   and reports disagreement rate.
 9. Invoke the `superpowers:brainstorming` skill with the user. Walk
   through the 8 brainstorm questions above. Bring the formula
   divergence number to inform the Path A/B/C decision.
 10. Write the spec.
 11. Write the plan.
 12. Begin Week 1 implementation per the plan.
 Don't skip the brainstorm. The terrain split formula decision (Path
 A/B/C) has real downstream consequences — physics, server-Z agreement,
 fork-patching of WB. Needs explicit user input, not "the agent makes
 a call and goes." This phase is structurally the same shape as N.5 —
 brainstorm → spec → plan → tasks-with-checkboxes → commits-update-checkboxes
 → final SHIP commit.
 ---
 ## Things to NOT do
 - **Don't adopt WB's terrain code wholesale without resolving #51
  first.** The split formula decision affects the entire pipeline;
  patching it after-the-fact requires re-doing visual + physics + the
  TerrainGeometryGenerator port.
 - **Don't introduce a per-cell wobble at landblock boundaries.** That's
  the visible signature of the formula disagreement. If you see it
  during visual verification, the formula isn't aligned between your
  physics and visual paths.
 - **Don't break the existing `[WB-DIAG]` instrumentation.** Add a
  separate counter for terrain (`terrainDrawsIssued`) so the entity
  + terrain perf can be observed independently.
 - **Don't bundle A.5 (two-tier streaming + horizon LOD) into this
  phase.** N.5b is "terrain on modern path"; A.5 is "split the radius
  + LOD." Different scopes, different brainstorms. A.5 might become
  natural to pick up next once N.5b lands.
 - **Don't try to re-port `FSplitNESW` if you're going Path A.** The
  whole point of Path A is to commit to WB's formula. If you keep
  retail's formula via Path B/C, do it once, definitively.
 - **Don't skip the formula-divergence quantification.** Step 8 of
  the first 30 minutes. The Path decision should be data-informed,
  not gut-feel. <5% divergence makes Path A bounded-risk; >20% makes
  Path B/C more attractive.
 - **Don't skip visual verification.** The split-formula bug class
  shows up as cell-boundary wobble that's hard to spot in screenshots
  but obvious in motion. Walk a sloped landblock during verification.
 - **Don't extend the phase scope.** N.5b is "terrain on modern path."
  Sky, particles, EnvCells — all subsequent phases. If the brainstorm
  tries to expand, push back.
 ---
 ## Reference: the N.5 dispatcher flow you're mirroring
 ```
 WbDrawDispatcher.Draw(...) {
  // Phase 1: walk entities, build groups
  // Phase 2: lay matrices contiguously
  // Phase 3: build BatchData + DEIC arrays via BuildIndirectArrays
  // Phase 4: upload 3 SSBOs (instances, batches, indirect)
  // Phase 5: bind global VAO + SSBOs
  // Phase 6: opaque pass — glMultiDrawElementsIndirect
  // Phase 7: transparent pass — glMultiDrawElementsIndirect
 }
 ```
 For terrain the shape is similar but simpler:
 ```
 TerrainModernDispatcher.Draw(...) {
  // Phase 1: walk visible landblocks, frustum cull
  // Phase 2: build per-landblock IndirectGroupInput list
  //          (one entry per visible landblock — typically 25-121)
  // Phase 3: upload 2 SSBOs (terrain batch data, indirect commands)
  //          (no per-instance buffer needed — terrain isn't instanced)
  // Phase 4: bind global terrain VAO + SSBOs
  // Phase 5: opaque pass ONLY — glMultiDrawElementsIndirect
 }
 ```
 Total ~6-8 GL calls per frame for terrain. That's the destination.
 Good luck. The split-formula decision is the only really hard call;
 everything else is mechanical port work on top of N.5's substrate.
 Holler at the user if anything in #51's three paths feels genuinely
 ambiguous after reading the references.
--- a/docs/research/2026-05-10-holtburger-network-stack-study.md
+++ b/docs/research/2026-05-10-holtburger-network-stack-study.md
@ -1,177 +0,0 @@
 # Holtburger network stack — study & port candidates for acdream
 **Date:** 2026-05-10
 **Holtburger reference:** github.com/merklejerk/holtburger, vendored at `references/holtburger/`, fast-forwarded from `88b19bd` → `629695a` (237 commits, ~3 months of work).
 **Method:** Four parallel research agents — three over holtburger's transport, handshake, and movement; one inventorying acdream's current `src/AcDream.Core.Net/`. Findings cross-referenced and ranked by ROI.
 ## TL;DR
 Holtburger has shipped real, citeable fixes since our last pin that we should adopt. The biggest tactical wins are:
 1. **A handful of one-line MoveToState fixes** that are likely candidates for the "remote retail observer sees acdream's player not perfect" issue (#L.X).
 2. **Three small handshake/transport corrections** — LoginComplete-on-teleport, EchoResponse reply, port-switch race — each <1 hour and each measurable.
 3. **A real retransmit subsystem we're missing entirely.** Our `WorldSession` parses retransmit requests, doesn't honor them, has no resend buffer, and never asks for a resend. Lost packets just vanish. Holtburger's `session/reliability.rs` is the reference-quality pattern.
 Separately, the audit surfaced one painful finding about acdream itself: **roughly half of our outbound `Messages/` library is dead code** — InteractRequests, InventoryActions, SocialActions, AllegianceRequests, CastSpellRequest, AppraiseRequest, and most of CharacterActions are built and unit-tested but have no `WorldSession.Send*` wrapper and no live caller. Phase B.4 (Use/UseWithTarget) per memory shipped, but the audit found no in-app caller. Either we left wiring on the table or there's an integration drift to investigate.
 The remainder of this doc is organized as: ranked port candidates → confirmations of what we got right → traps (where holtburger is wrong or stubbed) → recent commits worth knowing → recommended sequencing → cross-reference file map.
 ---
 ## 1. Ranked port candidates (highest ROI first)
 ### 1.1 Outbound MoveToState audit — concrete suspects for the "observer not perfect" bug
 Five specific items where holtburger's wire format is likely tighter than ours. Each is a small change in our `Messages/MoveToState.cs` builder; together they're the most likely cause of remote retail observers reporting our player "lagging forward" or "walking when running."
 | # | Suspect | Holtburger reference |
 |---|---------|----------------------|
 | a | **`current_hold_key` always set on non-stop MoveToState.** Holtburger's drive emit seeds `flags = CURRENT_HOLD_KEY` and writes `current_hold_key = HoldKey::Run`(2) for run, `HoldKey::None`(1) for walk. ACE's relay code may treat its absence as "unknown" and broadcast Walk to observers. | `crates/holtburger-core/src/client/movement/common.rs:151-153` |
 | b | **`commands[]` array MUST be empty on held WASD.** Holtburger never puts a `MotionItem` in `commands[]` for held movement — only for transient slash commands like `/dance`. If acdream is putting one in for held W (or letting movement_sequence bump per-frame), every observer's `apply_self_update_motion` re-applies the same sequence as a fresh interpolation start — exactly the symptom. | `system.rs:743-766` (`execute_transient_motion_at`) |
 | c | **`turn_speed` always emitted alongside `TURN_COMMAND`.** Holtburger writes 1.5 rad/s for Run, 1.0 rad/s for Walk; the `TURN_SPEED` flag is *always* set whenever `TURN_COMMAND` is. Omitting it lets ACE default to 0 → "smoothly but slowly" turn observed. | `common.rs:184-186, 226-231` |
 | d | **Dedup gate must include gait.** Holtburger's `should_send_motion_state_pulse` compares the full `(MotionState, MotionStyle)`. If acdream's dedup is keyed on only `(forward_command, hold_key)` it would suppress the Run→Walk transition (since `forward_command = WalkForward = 0x45000005` for both), explaining the Run↔Walk observer bug specifically. | `system.rs:916-926` |
 | e | **Don't emit `turning` field when locomotion is non-zero.** Recent fix in commit `336cbad`: `autonomous_wire_motion_state` no longer emits `turning` when locomotion ≠ 0 (avoids server-side double-correction where it interpolates turn AND locomotes). | `crates/holtburger-core/src/client/movement/common.rs` |
 **Recommended action:** a side-by-side audit of [WorldSession.cs:6067-6089](src/AcDream.Core.Net/WorldSession.cs:6067) (MoveToState builder) and [Messages/MoveToState.cs](src/AcDream.Core.Net/Messages/MoveToState.cs) against holtburger `common.rs:122-186` and `system.rs:710-1000`. File whichever items don't already match as `#L.X.a-e` issues.
 ### 1.2 LoginComplete on every PlayerTeleport, not just first PlayerCreate
 Holtburger sends `GameAction::LoginComplete` (0x00A1) **both** on first `PlayerCreate` (0xF746) AND on every `PlayerTeleport` (0xF74A) — no de-dup, server tolerates multiples. acdream sends it only on first PlayerCreate. Likely explains some portal-transition glitches.
 References: holtburger `messages.rs:433-467` (PlayerCreate), `messages.rs:480-487` (PlayerTeleport). acdream sends only at [WorldSession.cs:648](src/AcDream.Core.Net/WorldSession.cs:648).
 **Cost:** ~5 lines.
 ### 1.3 EchoRequest → EchoResponse reply
 We parse `EchoRequest` from the optional header but never reply. ACE pings periodically; the missing response is a likely contributor to Network Timeout drops in long sessions. Holtburger handles it inline in the recv-message dispatcher.
 Reference: holtburger `crates/holtburger-session/src/session/receive.rs::finalize_ordered_server_packet` and the optional-header iterator at `crates/holtburger-session/src/optional_header.rs:59-141`.
 **Cost:** ~30 lines (parse the EchoRequest payload, build EchoResponse with mirrored time, send as control packet).
 ### 1.4 Port-switch race fix (commit `403bc98`)
 On `ConnectRequest`, our `WorldSession` eagerly sets `_connectEndpoint = port+1`. Holtburger's recent fix introduces `pending_server_source_addr`: the new port is staged but `server_source_addr` is only updated when an actual packet arrives from the new port. ACE deployments occasionally send one more packet from `port` after the activation, and our code drops them.
 References: holtburger `session/auth.rs:42-47` (stage), `session/receive.rs:17-51` (confirm on first packet from new port).
 **Cost:** ~20 lines, one new field on `WorldSession`.
 ### 1.5 Non-blocking 200 ms handshake delay
 We use `Thread.Sleep(200)` between receiving ConnectRequest and sending ConnectResponse on `port+1`. Holtburger queues ConnectResponse with `ready_at = Instant::now() + 200ms` and lets the recv loop keep draining during the gap (handles any inbound TimeSync that arrives in the window).
 Reference: holtburger `session/auth.rs:42-66`, queued via `pending_control_packets` flushed by the recv loop. (Their old form, deleted in `99974cc`, used `tokio::time::sleep` and matched our blocking pattern.)
 **Cost:** ~40 lines (small "deferred control packet" queue + flush check).
 ### 1.6 AutonomousPosition cadence audit
 We have **three policies** in play, and at least two are wrong:
 - **acdream:** fixed 200 ms heartbeat (per `memory/project_retail_motion_outbound`)
 - **holtburger:** fixed 1 s heartbeat, unconditional regardless of motion (`common.rs:22`, `system.rs:858-893`)
 - **cdb retail trace (memory):** AutoPos appears gated on actual motion
 Most likely retail wins (cdb is observing real client behavior). If retail truly suppresses AutoPos when stationary, our 5× over-emission triggers ACE-side over-validation and may contribute to the observer-side jitter. **Recommended:** another cdb idle trace to confirm retail's exact behavior, then converge to it.
 ### 1.7 Retransmit machinery (entire subsystem)
 Largest delta from holtburger. We are missing:
 - **A retransmit cache.** Holtburger's `MAX_CACHED_PACKETS=512`, LRU-style, drops oldest when full (`reliability.rs:32-37`).
 - **Server-requested retransmits.** When the server asks for resends, holtburger re-encrypts with current ISAAC + RETRANSMISSION flag and replays from cache (`reliability.rs:135-186`).
 - **Client-issued retransmit requests.** When inbound seq has gaps, holtburger sends `RequestRetransmit` for up to 115 seqs in a 256-seq window, rate-limited to once per second (`MAX_RETRANSMIT_SEQUENCE_IDS=115`, `MAX_RETRANSMIT_SEQUENCE_WINDOW=256`, `REQUEST_RETRANSMIT_INTERVAL=1s`).
 - **`Iteration` field handling.** Our `PacketHeader.Iteration` is always 0; holtburger increments on retransmit.
 - **`ISAAC::search` for out-of-order ENCRYPTED_CHECKSUM packets.** Out-of-order packets have ISAAC keys that have already advanced. Holtburger scans forward up to 256 keys, stashing each skipped key in `xors: HashSet<u32>` for later out-of-order packets to consume via `consume_key_value` (`crypto.rs:73-93`). **A naive port either drops the out-of-order packet or corrupts the ISAAC stream.** If our IsaacRandom doesn't have a search-and-stash mode, this is a latent bug waiting for any UDP loss event.
 Our `WorldSession` class doc explicitly defers this work (`WorldSession.cs:29` "ACK pump, retransmit handling … deferred"). Symptoms when it's missing: any packet loss → silent state divergence, eventual desync, "purple haze" / Network Timeout drops.
 **Cost:** 1-2 days. The whole pattern is in holtburger's `reliability.rs` (196 lines) plus the ISAAC search-mode in `crypto.rs:73-93`.
 ### 1.8 Fragment assembler TTL + outbound multi-fragment split
 Two smaller correctness gaps:
 - **Inbound:** Our `FragmentAssembler` has no TTL. If a multi-fragment server message loses its middle fragment, the partials sit forever. Memory leak in any long session that sees UDP loss. Holtburger's reassembler tracks completion per `(sequence, id)` and lives inside `process_fragment` in `send.rs`.
 - **Outbound:** Our `GameMessageFragment.BuildSingleFragment` throws on body > 448 bytes. Anything that needs splitting (long /tells, big inventory queries, large appraisals) silently can't be sent. Note: **holtburger doesn't do outbound fragmentation either** (`send_message` always emits `count: 1`, `send.rs:298`) — they're betting on UDP-level fragmentation. So this isn't a holtburger crib; it's a hole in both. AC2D + Chorizite are the better references when we get there.
 ---
 ## 2. Confirmations — we're doing it right
 Three places where the audit confirmed our existing approach matches the reference:
 - **Run/walk encoding via WalkForward + HoldKey.Run/None.** Holtburger sends `forward_command = 0x45000005 (WalkForward)` for **both** walk and run; the distinction is in `forward_hold_key` (Run=2 vs None=1) and `forward_speed`. ACE upgrades server-side. Test pinning this contract: `holtburger system/tests.rs:404-428`.
 - **Two-step EnterWorld** (`0xF7C8 CharacterEnterWorldRequest` → wait for `0xF7DF ServerReady` → `0xF657 CharacterEnterWorld`).
 - **ACK on every received packet with seq > 0.** Holtburger's `recv_packet_with_addr` queues an ack for every received packet with `sequence > 0 && flags != ACK_SEQUENCE`. Outbound `send_message` auto-piggybacks the latest server seq onto the next data packet; standalone ACKs flush only when nothing naturally goes out. (Worth double-checking that our `SendAck` is called automatically on `ProcessDatagram`, not as a separate periodic pump.)
 One thing **worth re-verifying** because it's easy to invert: ISAAC seeding direction. Holtburger uses `isaac_c2s = Isaac::new(crd.client_seed)` and `isaac_s2c = Isaac::new(crd.server_seed)` — i.e. the wire field labelled `client_seed` seeds the C2S keystream, and vice versa. Worth a 30-second check that our `WorldSession` does the same.
 ---
 ## 3. Don't crib these (holtburger gaps / wrong)
 - **Outbound fragmentation:** holtburger doesn't do it. Hole in both projects. Use AC2D + Chorizite when needed.
 - **Jump (0xF61B):** holtburger never sends Jump. The TUI client can't jump. `JumpActionData` is decoder-only. Use cdb retail trace + Chorizite.ACProtocol for jump format reference.
 - **Initial run_rate_scalar fallback:** holtburger uses 4.5 (max-cap formula, run_skill ≥ 800); acdream uses 2.4-2.94 default. Retail formula: `(load_mod * (run_skill / (run_skill + 200) * 11) + 4) / 4`. The right pre-PlayerDescription default depends on what retail does — cdb trace will settle it.
 - **AutoPos cadence:** holtburger's 1-second unconditional heartbeat is probably wrong (cdb retail trace says gated on motion). Don't copy this verbatim; investigate first.
 ---
 ## 4. Recent commits worth knowing (last 237)
 | Commit | Date | Intent | Relevance |
 |--------|------|--------|-----------|
 | `99974cc` | 2026-04-06 | "Fix/session issues" — splits 673-line `lib.rs` into `session/{api,auth,receive,send,reliability,types}`. **Adds the missing C↔S retransmit logic.** Replaces `tokio::sleep(200ms)` with deferred control-packet queue. | Read this diff if you read only one. |
 | `403bc98` | 2026-04-21 | "do not switch ports prematurely" (#158). Pending vs confirmed source-port. | Apply same pattern to `WorldSession`. |
 | `336cbad` | 2026-04-?? | "fix: more movement fixes". `autonomous_wire_motion_state` no longer emits `turning` when locomotion ≠ 0. | Likely also a bug class in our outbound MoveToState. |
 | `797aece` | 2026-04-06 | DISCONNECT now carries `id = client_id` instead of 0. | One-line fix on our `Dispose` path. |
 | `854c1bb` | (older) | "Feat/simulation system" (#105) — added the entire 2222-LOC `client/movement/{common,system}.rs`. | Foundation everything else builds on. |
 Nothing in 237 commits changes LoginRequest payload, ConnectRequest parse, ISAAC seeding, or EnterWorld message ordering. The wire format is unchanged from what acdream targets — the deltas are internal architecture and bug fixes.
 ---
 ## 5. Recommended sequencing
 **Tier 1 — Quick wins (under an hour each, high signal-to-noise):**
 1. MoveToState audit fixes (1.1.a-e) — file as `#L.X.a-e`, batch into one PR
 2. LoginComplete on PlayerTeleport (1.2)
 3. EchoRequest → EchoResponse reply (1.3)
 4. Port-switch race fix (1.4)
 5. Non-blocking handshake delay (1.5)
 6. Disconnect carries client_id (`797aece` finding)
 **Tier 2 — Investigation, then fix:**
 7. AutoPos cadence — cdb idle trace, then converge (1.6)
 8. Audit "dead outbound builders" (Phase B.4 wiring drift) — separate from holtburger but surfaced by this study
 **Tier 3 — Bigger investment:**
 9. Retransmit subsystem (1.7) — port `reliability.rs` wholesale, including ISAAC search-mode (1-2 days)
 10. Fragment assembler TTL (1.8 inbound)
 The Tier 1 group is a cohesive "post-A.5 network polish" pass — cheap, high-confidence, and several of them are likely candidates for the longstanding observer-not-perfect issue.
 ---
 ## 6. File map for cross-reference
 | acdream | holtburger | Role |
 |---------|-----------|------|
 | `src/AcDream.Core.Net/WorldSession.cs:411-521` | `crates/holtburger-session/src/session/{api,auth}.rs` | Handshake driver |
 | `src/AcDream.Core.Net/WorldSession.cs:556-924` | `crates/holtburger-core/src/client/runtime.rs:91-200` + `messages.rs` | Recv loop + dispatch |
 | `src/AcDream.Core.Net/WorldSession.cs:1096-1156` | `crates/holtburger-session/src/session/send.rs` | Outbound transport (encode + ack piggyback) |
 | `src/AcDream.Core.Net/Cryptography/IsaacRandom.cs` | `crates/holtburger-protocol/src/crypto.rs` | ISAAC (we likely lack `search`-mode) |
 | `src/AcDream.Core.Net/Packets/PacketCodec.cs` | `session/{send,receive}.rs` + `optional_header.rs` | Encode/decode + optional header iteration |
 | `src/AcDream.Core.Net/Packets/FragmentAssembler.cs` | `session/send.rs::process_fragment` | Inbound reassembly |
 | `src/AcDream.Core.Net/Messages/MoveToState.cs` | `crates/holtburger-protocol/src/messages/movement/actions.rs:53-69` + `client/movement/common.rs:122-186` | MoveToState builder |
 | `src/AcDream.Core.Net/Messages/AutonomousPosition.cs` | `messages/movement/actions.rs:175-189` + `system.rs:858-893` | AutoPos builder + cadence |
 | **(missing)** | `crates/holtburger-session/src/session/reliability.rs` | **Retransmit machinery — entirely absent in acdream** |
 ---
 ## Method note
 This study used four parallel general-purpose agents on the day-of pull (2026-05-10, holtburger HEAD `629695a`). All citations are file paths + line numbers in that exact tree. If holtburger moves forward, line numbers will drift; commit hashes (especially `99974cc`, `403bc98`, `336cbad`, `797aece`) are stable anchors.
--- a/docs/research/2026-05-10-phase-a5-handoff.md
+++ b/docs/research/2026-05-10-phase-a5-handoff.md
@ -1,376 +0,0 @@
 # Phase A.5 — Two-tier Streaming + Horizon LOD — Cold-Start Handoff
 **Created:** 2026-05-10, immediately after N.5b ship.
 **Audience:** the next agent picking up streaming + horizon-LOD work.
 **Purpose:** brief you on where N.5b left things, what A.5 actually has to do
 to make the world look and feel great, and the load-bearing facts the
 brainstorm should be informed by.
 ---
 ## TL;DR
 N.5b just shipped: outdoor terrain rendering is on bindless + multi-draw
 indirect via `TerrainModernRenderer`. Constant-cost dispatch as the
 visible landblock count grows — radius=5 vs radius=15 are the same number
 of GL calls for terrain.
 **A.5's actual goal — verbatim from the user, 2026-05-09:**
 > "I just want great smooth HIGH fps visuals. Should look great. As long
 > as it scales and we get very high FPS"
 That reframes priorities. We are NOT optimizing the inner loop at radius=5
 (it's solved). We're scaling visual reach + scene density without the
 client falling off a perf cliff.
 **Concretely, A.5 ships three things:**
 1. **Two-tier streaming.** Near tier (≤ N₁ landblocks) loads everything as
   today (terrain + scenery + EnvCells + collision). Far tier (N₁ < r ≤ N₂)
   loads terrain mesh ONLY. No scenery generation, no collision, no
   entity registration for the far tier.
 2. **Per-LB entity bucketing for the WB dispatcher.** Today the entity
   dispatcher walks every loaded entity each frame for AABB cull —
   ~16K entities @ ~1µs/test = 4.3ms/frame, dominating the frame budget.
   Bucket entities by landblock so the cull is hierarchical: cull the LB
   first, then only walk entities inside surviving LBs.
 3. **Off-thread mesh build.** `LandblockMesh.Build` currently runs on the
   render thread when a new LB streams in. At today's radius=5 this is
   invisible; at A.5's higher N₂ it becomes a visible frame-time spike
   when 4-5 LBs stream simultaneously. Move the build to a worker pool;
   hand finished `LandblockMeshData` back via a queue.
 The headline win you're shooting for: **radius=15 sustains the user's
 target FPS in Holtburg with no streaming hitches.**
 ---
 ## Where N.5b left things
 ### Branch state (relative to main)
 After N.5b ships:
 - N.5b SHIP at `08b7362` (final commit; appended SHIP record to plan)
 - Roadmap entry, issue #51 closure, perf baseline doc all in place at `083c10c`
 - Legacy `TerrainChunkRenderer` + `TerrainRenderer` + `terrain.vert/.frag`
  deleted at `7dfa2af`. **The modern path is the only path.**
 ### Captured perf baseline (load-bearing for A.5's "what's actually hot")
 From `docs/plans/2026-05-09-phase-n5b-perf-baseline.md`, measured
 2026-05-09 at Holtburg town dueling field, radius=5, ~30s standstill:
 | Subsystem | cpu_us median per frame | Notes |
 |---|---|---|
 | **Entity dispatcher** (`WbDrawDispatcher`) | **~4,300** | 86% of frame budget. ~16K entities walked for AABB cull. THIS is the bottleneck. |
 | Terrain dispatcher (`TerrainModernRenderer`) | ~6.4 | <1% of frame. Constant-cost regardless of radius (proved in N.5b). |
 | Everything else (sky, particles, ImGui, swap, audio) | ~700 | Small. |
 **Actual FPS at radius=5 in Holtburg: ~200 fps** (frame time ≈ 5ms).
 NOT the "810 fps" inferred from the N.5 ship doc (that was 1/dispatcher_ms,
 which is only the WB dispatcher CPU cost in isolation, not real frame time).
 ### What naive radius increase does
 If you simply raised `ACDREAM_STREAM_RADIUS` to 15 today without A.5:
 - Loaded landblocks: 121 → ~961 (8× more). Acceptable.
 - Loaded entities: ~16K → ~125K (linear scaling with LB count). **NOT
  acceptable.** At ~1µs per AABB cull, the entity dispatcher would take
  ~125ms/frame = 8 FPS. Slideshow.
 - Memory footprint: similar 8× explosion in scenery instance buffers.
 So the perf cliff is real and immediate. A.5 has to address it BEFORE
 the radius can be safely raised.
 ### What N.5b set up that A.5 inherits
 - **Modern terrain dispatcher.** `TerrainModernRenderer` is O(1) GL calls
  in radius. As you add far-tier LBs (terrain only), the terrain
  dispatcher cost stays flat (~6µs/frame). This is the one subsystem
  that doesn't need any A.5 work — it just scales.
 - **Slot allocator for terrain GPU buffers.** Already grows by power-of-two
  doubling. Will absorb radius=15 (~961 slots × ~15 KB each = ~14 MB)
  without manual tuning.
 - **`[TERRAIN-DIAG]` instrumentation.** Reports per-frame median + p95 in
  microseconds. Use this to confirm A.5 doesn't regress terrain perf.
 - **Conformance sentinel.** `TerrainModernConformanceTests` proves visual
  mesh Z agrees with `TerrainSurface.SampleZFromHeightmap` to 0.015 mm.
  Don't break this — physics ↔ visual agreement must hold across both
  tiers.
 - **Bindless atlas.** `TerrainAtlas.GetBindlessHandles()`. The far tier
  shares the atlas (it's region-wide). Zero atlas-related per-LB cost.
 ---
 ## The brainstorm questions (the hard calls A.5 has to make)
 These are the questions to resolve in the brainstorm step. Bring them to
 the user with options + recommendation; don't prejudge.
 ### 1. Tier radii: what are N₁ and N₂?
 - **N₁** = near-tier radius (everything loads). Today's default `STREAM_RADIUS`.
  Probably stays at 5 (or maybe 4; maybe 3).
 - **N₂** = far-tier radius (terrain mesh only). Could be 8, 12, 15, 20.
 Tradeoffs: bigger N₂ = more world visible = looks better. But each far-tier
 LB still costs ~16 KB GPU memory + a frustum cull AABB + a slot allocation.
 At N₂=15, that's ~961 LBs × 16 KB = ~15 MB GPU mem (cheap) + ~961 cull
 tests (cheap, ~1ms total at 1µs each — and we'll do this per-LB cull
 anyway as part of #2 below).
 Verify against retail: cdb attach + check how many landblocks retail keeps
 loaded at a given vantage point. Probably around 10-12 per the AC2D
 references and the holtburger client's behavior.
 ### 2. Far tier: terrain only? Or also impostor scenery?
 Two options:
 - **Terrain only** (cleanest). Beyond N₁, no trees, no rocks. Skyline is the
  terrain mesh against the sky.
 - **Impostor scenery** (more retail-like). Beyond N₁, generate flat
  billboards or low-poly trees instead of full meshes. Adds substantial
  complexity (billboard pipeline, mesh-LOD generation, per-camera-angle
  rotation).
 Recommendation: start with terrain-only. Add impostors only if the
 horizon looks wrong (too bare). Retail definitely has SOME distant
 scenery but the cutoff is gradual; we can match it later if needed.
 ### 3. Entity bucketing structure
 Today: `WbDrawDispatcher` keeps a flat dictionary of all entities and
 walks all of them per frame. To bucket by LB, we need:
 - A `Dictionary<uint, List<EntityHandle>>` keyed by landblock ID
 - On `AddEntity(...)`, also stash it in the LB bucket (the spawn flow
  already knows the LB context)
 - On `RemoveEntity(...)`, remove from the LB bucket too
 - Per frame: cull at LB granularity first; then cull entities only inside
  surviving LBs
 LB-level AABBs are already computed (per the existing `_visibleSlots`
 logic in `TerrainModernRenderer` — the same AABB applies to entities,
 modulo a Z-range bump for trees/buildings).
 Open question: do entities outside a known LB exist? (Items dropped on the
 ground? Ephemeral effects? Player projectiles?) If yes, they need a
 fallback "unknown LB" bucket that's still walked every frame. Probably
 small.
 ### 4. Where does the off-thread mesh build land?
 Today `LandblockMesh.Build` runs synchronously inside `OnLandblockLoaded`
 on the render thread. To move it off:
 - `StreamingLoader` worker thread (already async for dat reads) signals
  "LB X is ready"
 - A new worker pool consumes that signal, builds the mesh on a worker
  thread, posts the finished `LandblockMeshData` to a `ConcurrentQueue`
 - Render thread drains the queue at the start of each frame, calling
  `_terrain.AddLandblock(...)` for each ready mesh
 Gotcha: the `TerrainBlendingContext` is shared. Need to confirm it's
 read-only (it is — built once at startup). Also `_surfaceCache` —
 currently a plain `Dictionary` populated lazily by `TerrainBlending.BuildSurface`.
 Either lock it, replace with `ConcurrentDictionary`, or pre-populate with
 all known palCodes at startup.
 ### 5. Streaming hysteresis at the tier boundary
 When the player crosses N₁ → near-tier shrinks, far-tier grows.
 LBs that were near-tier need to:
 - Drop their scenery (unregister entities)
 - Drop their EnvCells
 - Keep the terrain mesh (still in far tier)
 When the player crosses back: the LB needs scenery + EnvCells re-loaded.
 Hysteresis (don't churn at the exact boundary) is needed.
 The streaming loader already has hysteresis for full LB load/unload. A.5
 extends that: a separate hysteresis radius for the scenery/entity layer.
 ### 6. Visual quality wins to ride along
 A.5 is the natural place to land 2-3 nearly-free quality wins:
 - **Mipmapped terrain atlas + anisotropic 16x.** Today the atlas is
  `GL_LINEAR` no mipmaps; distant terrain shimmers. ~half-day fix.
  Big visible improvement at far tier.
 - **Tree alpha-test → alpha-to-coverage with MSAA.** Today tree edges are
  binary cutoff and pixel-edged. A2C with MSAA fixes them. ~one day.
 - **Correct depth-write for transparent foliage.** Some scenery passes
  may be writing depth incorrectly; confirm + fix.
 These are not strictly required for A.5 to ship, but they amplify the
 "looks great" payoff.
 ### 7. Acceptance metrics
 The user's goal is "smooth + high FPS + great-looking + scales." Pin
 this concretely:
 - Target FPS at radius (whatever final N₁ + N₂): ≥ user's monitor refresh
  (probably 144 or 240 Hz). Capture before/after numbers in a perf
  baseline doc parallel to N.5b's.
 - No frame-time spikes > 5ms during streaming (record a 60-second
  trace running through Holtburg → North Yanshi).
 - Visual horizon visible at the new N₂. Capture screenshots from the
  same vantage point at the start of A.5 (before) and at ship (after)
  for the SHIP record.
 ### 8. What's NOT in A.5
 A.5 does not need to ship:
 - GPU-side culling (compute-shader cull). Bigger lift; N.6 territory.
 - Persistent-mapped indirect buffer. N.6 territory.
 - Sky / particles / EnvCells migration. Separate N.7+ phases.
 - Shadow mapping. Separate visual phase.
 Don't let scope creep pull these in.
 ---
 ## Files to read before brainstorming
 In rough order of relevance:
 1. **`docs/research/2026-05-09-phase-n5b-handoff.md`** — N.5b's handoff
   (read for context on what was just shipped + the structure of these
   handoff docs).
 2. **`docs/plans/2026-05-09-phase-n5b-perf-baseline.md`** — captured
   perf numbers + the architectural reasoning for what A.5 inherits.
 3. **`memory/project_phase_n5b_state.md`** — three high-value gotchas
   captured during N.5b (especially #1: bindless uniform-sampler driver
   quirk; A.5 won't directly need this, but it's the prior art for any
   new shader code in the phase).
 4. **`docs/plans/2026-04-11-roadmap.md`** A.5 entry — the original A.5
   description.
 5. **The streaming loader** — `src/AcDream.Core/World/StreamingLoader.cs`
   (or wherever it lives; grep for `OnLandblockLoaded`). Understand the
   existing ring + hysteresis logic before extending it.
 6. **WB dispatcher entity flow** —
   `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs` lines covering
   `Draw` (the per-entity walk) and `EntitySpawnAdapter` (where entities
   get registered). The bucketing change lands here.
 7. **`LandblockMesh.Build`** — `src/AcDream.Core/Terrain/LandblockMesh.cs`.
   Its inputs (heightmap, ctx, surfaceCache) determine what the worker
   thread needs. ~150 lines.
 8. **WB's `SceneryRenderManager`** —
   `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/SceneryRenderManager.cs`.
   Has a render-distance cap; informs N₁ vs N₂ defaults.
 9. **`TerrainModernRenderer`** —
   `src/AcDream.App/Rendering/TerrainModernRenderer.cs`. Don't modify;
   confirm the slot allocator handles radius=15 cleanly.
 ---
 ## Acceptance criteria for the whole phase
 1. Build green; existing tests stay green; N.5b's conformance sentinel
   still passes (visual mesh Z = TerrainSurface Z within 1mm).
 2. **Far-tier LBs render terrain visibly past N₁** in user-driven visual
   verification.
 3. **Per-frame entity-dispatcher cpu_us at radius=N₁ drops** vs today
   (the bucketing should help even at the current radius).
 4. **Per-frame entity-dispatcher cpu_us at radius (N₁+N₂) is bounded**
   — does NOT scale linearly with total loaded LBs. Specifically:
   bucketed cull should be < 1.5× today's cost despite far-tier LBs
   loading.
 5. **No streaming hitch > 5ms** when running at run-speed across N₁/N₂
   tier boundaries simultaneously (capture a 60s trace).
 6. **`[TERRAIN-DIAG]` cpu_us stays flat** as N₂ grows — the terrain
   dispatcher proven O(1) (regression check).
 7. Visual identity at near-tier (no scenery missing inside N₁; no
   z-fighting; no cell-boundary wobble — N.5b sentinel still applies).
 8. SHIP record + perf baseline + memory entry written, mirroring N.5b's
   pattern.
 ---
 ## What you'll be doing in the first 30 minutes
 1. Read this handoff in full.
 2. Read `docs/research/2026-05-09-phase-n5b-handoff.md` for the structural
   pattern.
 3. Read `docs/plans/2026-05-09-phase-n5b-perf-baseline.md` for the captured
   numbers A.5 inherits.
 4. Read `memory/project_phase_n5b_state.md` for gotchas.
 5. Verify build is green: `dotnet build`.
 6. Verify N.5b ship is intact: `dotnet test --filter "FullyQualifiedName~TerrainSlot|FullyQualifiedName~TerrainModernConformance|FullyQualifiedName~Wb|FullyQualifiedName~MatrixComposition|FullyQualifiedName~TextureCacheBindless"` (target ≥114 passing, 0 failures).
 7. Capture a baseline radius=5 frame trace yourself (one launch, 30s
   standstill at Holtburg dueling field) so you have a "before" number
   in your own measurement environment, not just trusting N.5b's number.
 8. Invoke `superpowers:brainstorming` with the user. Walk through the
   8 brainstorm questions above. Present each with options + my
   recommendation; don't prejudge.
 9. After agreement, write the spec; then the plan; then execute
   task-by-task using `superpowers:subagent-driven-development`.
 Don't skip the brainstorm. The N₁/N₂ values, the bucketing structure
 trade-offs, and the worker-thread design are real decisions with
 downstream consequences that need user input — not "the agent makes a
 call and goes."
 ---
 ## Things to NOT do
 - **Don't raise `ACDREAM_STREAM_RADIUS` without A.5's tiered loading
  in place.** The entity-cull cliff is immediate and severe (8 FPS at
  naive radius=15).
 - **Don't put scenery in the far tier just to "look more retail" without
  a billboard/impostor pipeline.** Full-detail scenery in the far tier
  is what causes the cull cliff.
 - **Don't move `LandblockMesh.Build` to a worker thread without first
  auditing `TerrainBlendingContext` + `_surfaceCache` for thread
  safety.** Concurrent writes to the surfaceCache will produce
  silently-wrong terrain blending.
 - **Don't break the N.5b conformance sentinel.** If A.5 changes how
  meshes are built (e.g., for the worker thread), the conformance
  test must still pass — it's the load-bearing physics ↔ visual Z
  agreement guard.
 - **Don't bundle GPU-side culling, persistent-mapped buffers, or shadow
  mapping into A.5.** Those are N.6+ territory; A.5 is "make the world
  look big and not stutter."
 - **Don't ship without honest perf numbers.** If A.5 doesn't actually
  hit its FPS target, document why and ship N.6 next instead of
  papering over it. The N.5b precedent is honest reporting.
 - **Don't skip the visual verification gate.** Same lesson from N.5b's
  black-terrain regression: "go" doesn't mean "verified." User must
  actually launch the client at radius=N₂ and confirm the horizon
  looks great + FPS hits target.
 ---
 ## Reference: where the FPS budget actually goes today
 For brainstorming purposes, the per-frame breakdown at radius=5 / Holtburg
 (real measurement, 2026-05-09):
 ```
 ~5,000 µs total frame time (= 200 fps)
 ├── 4,300 µs  WbDrawDispatcher entity cull + dispatch  ← THE BOTTLENECK
 │             ~16K entity AABB tests / frame
 │             A.5's entity bucketing attacks this directly
 ├──     6 µs  TerrainModernRenderer
 │             O(1) in radius. Won't grow with A.5. Already solved.
 ├──   ~700 µs Sky, particles, ImGui, audio, swap-buffers, misc
 │             Mostly fixed cost; some VSync-related
 └──    rest   GPU side (we don't measure this — query plumbing
              deferred to N.6). Could be substantial.
 ```
 The first action of A.5 is to recognize that the perf claim "810 fps"
 from N.5 was misleading. Don't repeat the mistake — measure the actual
 frame time, not just one subsystem.
 ---
 Good luck. The phase is meaty (~2 weeks) but the structural work is
 well-shaped: tiered streaming has clear boundaries, entity bucketing is
 an isolated dispatcher change, off-thread mesh build is a well-understood
 worker pattern. The hard call is the N₁/N₂ values, and that's a
 brainstorm question — bring it to the user with data.
--- a/docs/research/2026-05-10-phase-m-opcode-matrix.md
+++ b/docs/research/2026-05-10-phase-m-opcode-matrix.md
@ -1,543 +0,0 @@
 # Phase M — Network Opcode Coverage Matrix
 **Date:** 2026-05-10
 **Status:** Initial population complete (4 parallel research agents). Spot-check pass + intentional-divergence ratification owed before M.1 closes.
 **Companion spec:** [`docs/superpowers/specs/2026-05-10-phase-m-network-stack-design.md`](../superpowers/specs/2026-05-10-phase-m-network-stack-design.md)
 **Companion study:** [`docs/research/2026-05-10-holtburger-network-stack-study.md`](2026-05-10-holtburger-network-stack-study.md)
 This matrix is the **source of truth for Phase M completeness**. Every row defines: what the opcode is, who currently sends/receives it across our three reference sources, what acdream does today, and what Phase M must do. The spec's M.6 work plan reduces to "for every row where `acdream today` ≠ `Phase M target`, implement the delta and add tests."
 ---
 ## Roll-up
 | Section | In-scope | Acdream today | Phase M delta |
 |---------|----------|---------------|---------------|
 | 1 — Transport flags | 22 | 14 parse / 5 build | 8 |
 | 2 — Optional-header fields | 12 | 10 partial | builder + decoder gaps |
 | 3 — GameMessage opcodes (top-level) | 51 | 21 implemented | 30 |
 | 4 — GameEvent sub-opcodes (inside 0xF7B0) | 103 | 27 parsed / 26 wired | 76 new (~50 deferable to gameplay phases) |
 | 5 — GameAction sub-opcodes (inside 0xF7B1) | 96 | 24 built / 8 live callers | 72 new + 16 dead-builder wirings |
 | **Total** | **~284** | **~96** | **~190** |
 Roughly **34% complete by raw opcode count.** The biggest single Phase-M unblocking step is wiring the 16 dead builders in section 5 (Phase B.4 surface — Use / UseWithTarget / Allegiance / Inventory / Social / Cast / Appraise / etc.).
 ---
 ## Cell-value vocabulary
 | Code | Meaning |
 |------|---------|
 | `P` | Parses inbound |
 | `B` | Builds outbound |
 | `PB` | Parses + builds (both directions) |
 | `W` | Wired — typed handler exists AND state is updated by it |
 | `H` | (ACE only) Server has a handler that processes this client-sent opcode |
 | `–` | Not implemented |
 | `N/A` | Not applicable for this side (e.g., server-only message in ACE column) |
 | `?` | Could not determine — needs verification |
 **Phase M target column:**
 | Target | Meaning |
 |--------|---------|
 | `PB+W` | Must parse, build (if outbound), wire to typed event by phase end |
 | `PB` | Must parse + build, no wiring required |
 | `P+W` | Inbound only, must parse + dispatch typed event |
 | `B+W` | Outbound only, must build + have a live caller |
 | `B` | Build only, no live caller required (typed for future use) |
 | `–defer:<phase>` | Explicitly deferred to a named gameplay phase |
 | `–skip:<reason>` | Out of scope, with justification |
 ---
 ## Section 1 — Transport flags
 In-scope: 22. Implemented in acdream: 14 (parse path + 5 build path). Phase M target delta: 8 (4 inbound parse gaps to wire, 4 outbound builders, plus 6 to retire/skip-justify).
 | Code | Direction | Name | Named-retail symbol | Holtburger | ACE | acdream today | Phase M target | Notes |
 |---|---|---|---|---|---|---|---|---|
 | `0x00000000` | N/A | None | – | N/A | N/A | N/A | N/A | Identity flag value [^t-a] |
 | `0x00000001` | both | Retransmission | – | P (set on retx) | PB+W | – | PB+W | We never echo/honor this bit [^t-b] |
 | `0x00000002` | both | EncryptedChecksum | `FlowQueue::EncryptChecksum` | PB | PB+W | PB+W | PB+W | Codec covers in/out + ISAAC |
 | `0x00000004` | both | BlobFragments | `MessageFragment` group | PB+W | PB+W | PB+W | PB+W | Fragment list parsed/built |
 | `0x00000100` | inbound | ServerSwitch | `ClientNet::HandleServerSwitch` | P (size-skip) | PB | P (size-skip) | P+W | Handler missing; just consumes 8 bytes |
 | `0x00000200` | inbound | LogonServerAddr | – | – | – | – | –defer:M2 | Login-server bounce; no client logic yet [^t-c] |
 | `0x00000400` | inbound | EmptyHeader1 | `CEmptyHeader<0x400,2>` | – | – | – | –skip:dead-flag | Retail struct exists, never sent |
 | `0x00000800` | inbound | Referral | `ClientNet::HandleReferral` | – | B only (server) | – | –defer:M2 | Server-only path until login bounce |
 | `0x00001000` | both | RequestRetransmit | `FlowQueue::TransmitNaks` | PB+W | PB+W | P (size-skip) | PB+W | NAK list parsed but ignored [^t-d] |
 | `0x00002000` | both | RejectRetransmit | `FlowQueue::EnqueueEmptyAck` | P+W | PB | P (size-skip) | P+W | Inbound only (server tells us "no") |
 | `0x00004000` | both | AckSequence | `FlowQueue::EnqueueAcks` | PB+W | PB+W | PB+W | PB+W | Per-packet ack pump shipped |
 | `0x00008000` | both | Disconnect | `Client::Disconnect` | – | P+W | B only | P+W | Inbound parse-and-tear-down missing [^t-e] |
 | `0x00010000` | outbound | LoginRequest | `ClientNet::SendLoginRequest` | B | P+W | B | B | Auth-only, parsed by server [^t-f] |
 | `0x00020000` | inbound | WorldLoginRequest | `CEmptyHeader<0x20000,1>` | – | P (8 bytes) | P (size-skip) | P (size-skip) | Server-only on relay [^t-g] |
 | `0x00040000` | inbound | ConnectRequest | `ClientNet::HandleConnectionRequest` | P+W | B | P+W | P+W | Handshake oracle, ISAAC seeded |
 | `0x00080000` | outbound | ConnectResponse | `ClientNet::SendConnectAck` | B | P+W | B | B | 8-byte cookie echo |
 | `0x00100000` | inbound | NetError | `NetError::UnPack` | – | – | – | P+W | Drop session + surface error to UI |
 | `0x00200000` | inbound | NetErrorDisconnect | `NetError::UnPack` | – | P+W | – | P+W | Same parse, hard-disconnect variant |
 | `0x00400000` | inbound | CICMDCommand | – | P (size-skip) | P+W | P (size-skip) | –defer:M3 | Server-debug only; not honored by retail clients |
 | `0x01000000` | inbound | TimeSync | `ClientNet::HandleTimeSynch` | P+W | P+W | P+W | P+W | Drives `WorldTimeService` |
 | `0x02000000` | inbound | EchoRequest | `CEchoRequestHeader::CreateFromData` | P+W (mirrors out) | P+W | P (no reply) | PB+W | Must build EchoResponse mirror [^t-h] |
 | `0x04000000` | outbound | EchoResponse | – | B | B | – | B | Reply path for incoming EchoRequest |
 | `0x08000000` | both | Flow | `FlowQueue::TransmitNewPackets` | P (size-skip) | P+W | P (size-skip) | –defer:M2 | Throttle hint; safe to ignore until M2 |
 **Footnotes:**
 [^t-a]: The `None=0` value isn't a wire bit, but it's in our enum so callers can default-initialize headers — keep it.
 [^t-b]: ACE sets `Retransmission` when re-sending a cached packet; clients should accept it as informational. We currently treat the bit as a no-op (works because we don't dedupe on it).
 [^t-c]: A login-server-side handshake step; only relevant when ACE adds login-bounce, which it doesn't today.
 [^t-d]: We need to actually retransmit on inbound NAK and need to send NAKs for our own missing inbound. M3 reliability-core phase.
 [^t-e]: Inbound `Disconnect` must close the session cleanly and notify upper layers; right now the connection just times out on client side too.
 [^t-f]: `LoginRequest` is a server-decode case but our codec consumes it on encode for hashing.
 [^t-g]: Retail server uses this for world-server entry confirmation; the holtburger ref has no parse, ACE writer-side is `Pack`. Our consumer just skips 8 bytes for hashing.
 [^t-h]: Servers do periodically EchoRequest to the client; we must mirror the 4-byte client-time as an `EchoResponse` per `FlowQueue::DequeueAck` semantics.
 ---
 ## Section 2 — Optional-header fields
 In-scope: 12. Implemented in acdream: 12 of 12 sized-skip; 6 of 12 surface decoded fields. Phase M target delta: needs (a) builders for the ones we only parse, (b) ConnectRequest + EchoRequest builder paths for symmetric tests, (c) golden-vector test file.
 | Code | Direction | Name | Named-retail symbol | Holtburger | ACE | acdream today | Phase M target | Notes |
 |---|---|---|---|---|---|---|---|---|
 | `0x100` | inbound | ServerSwitch (8 bytes) | `UCServerSwitchStruct` | P (skip) | PB | P (skip) | P (decode)+W | Decode `serverIp:u32, port:u16, pad:u16` [^o-a] |
 | `0x1000` | inbound | RequestRetransmit (4+N\*4) | `FlowQueue::TransmitNaks` | PB | PB | P (parsed list) | PB+W | List stored; build path missing |
 | `0x2000` | inbound | RejectRetransmit (4+N\*4) | `FlowQueue::CompileEmptyAcks` | P | PB | P (size-skip) | P (decode)+W | List currently consumed without storage |
 | `0x4000` | both | AckSequence (4 bytes) | `FlowQueue::EnqueueAcks` | PB | PB | PB | PB | Stored as `AckSequence:u32` |
 | `0x10000` | outbound | LoginRequest (rest of pkt) | `ClientNet::SendLoginRequest` | B | P (full) | B (via `LoginRequest.Build`) | B | Variable-length tail; raw bytes hashed |
 | `0x20000` | inbound | WorldLoginRequest (8 bytes) | `CEmptyHeader<0x20000,1>` | – | P (8B peek) | P (size-skip) | P (decode)+W | Decode purpose unknown, store raw |
 | `0x40000` | inbound | ConnectRequest (32 bytes) | `CConnectHeader` | P+W | B (server) | P+W | PB | We need encode path for round-trip tests |
 | `0x80000` | outbound | ConnectResponse (8 bytes) | – | B | P (8B peek) | B | PB | Decode on inbound test fixtures |
 | `0x400000` | inbound | CICMDCommand (8 bytes) | – | P (skip) | P (8B) | P (size-skip) | –defer:M3 | Decode + handler deferred |
 | `0x1000000` | inbound | TimeSync (8 bytes) | `CTimeSyncHeader` | P+W | P+W | P+W | PB | Add build for symmetry; double LE |
 | `0x2000000` | inbound | EchoRequest (4 bytes) | `CEchoRequestHeader` | P+W | P+W | P (no reply) | PB+W | Wire to `SendEchoResponse` builder |
 | `0x8000000` | both | Flow (6 bytes) | `UCFlowStruct` | P (skip) | P+W | P (decode) | –defer:M2 | `FlowBytes:u32, FlowInterval:u16` decoded |
 **Footnotes:**
 [^o-a]: ServerSwitch struct layout per retail `UCServerSwitchStruct` — confirmed via named-retail symbol `?CreateFromData@?$COnePrimHeader@$0BAA@$0GA@UCServerSwitchStruct@@@@`. M3 needs the IP/port to actually re-target the socket; today we'd silently drop traffic from a relocated server.
 **Cross-cutting Phase M deliverables for sections 1+2:**
 1. **Goldens fixture file** — `tests/AcDream.Core.Net.Tests/Packets/PacketHeaderOptionalTests.cs` does not exist; only indirect coverage via `PacketCodecTests` and `ConnectRequestTests`. M needs one fixture per non-skip flag covering parse + build symmetry.
 2. **Typed events** — currently the only `WorldSession`-side flag-driven event is `ServerTimeUpdated` (from `TimeSync`). Phase M target adds: `ServerSwitchRequested(ip, port)`, `ServerDisconnect(reason)`, `ServerNetError(NetErrorCode, message)`, `EchoRequested(clientTime)` (internal), `RetransmitRequested(seqs)`, `RetransmitRejected(seqs)`.
 3. **`PacketHeaderOptional` storage gaps** — `RejectRetransmit` list is consumed but discarded; `WorldLoginRequest` 8-byte body is skipped; `CICMDCommand` 8-byte body is skipped; `ConnectResponse` 8-byte cookie is decoded only inside `Connect()`'s send path, not on inbound parse. M target: lift each into a typed property on `PacketHeaderOptional`.
 4. **Builder-side parity** — `PacketHeaderOptional.Parse` exists; there is no `PacketHeaderOptional.Build` — every outbound flag's body bytes are hand-rolled at the call site (`SendAck`, `Connect`, `Dispose`). Phase M should add a single `Build(PacketHeaderFlags, body fields)` to mirror parse.
 ---
 ## Section 3 — GameMessage opcodes (top-level)
 In-scope: 51. Implemented in acdream: 21. Phase M target delta: 30.
 | Code | Direction | Name | Named-retail symbol | Holtburger | ACE | acdream today | Phase M target | Notes |
 |------|-----------|------|---------------------|------------|-----|---------------|----------------|-------|
 | 0x0000 | both | None | – | PB | N/A | – | –skip:heartbeat-only | Internal/heartbeat sentinel |
 | 0x0024 | inbound | InventoryRemoveObject | – | P | B | – | P+W | Out of bubble or destroyed |
 | 0x0197 | inbound | SetStackSize | – | P | B | – | P+W | Container stack size delta |
 | 0x019E | inbound | PlayerKilled | – | PB | B | P+W | P+W | victim+killer broadcast |
 | 0x01E0 | inbound | EmoteText | `CM_Communication::DispatchUI_HearEmote` | PB | B | P+W | P+W | Server-driven 3rd-person emote |
 | 0x01E2 | inbound | SoulEmote | `CM_Communication::DispatchUI_HearSoulEmote` | PB | B | P+W | P+W | Complex emote w/ animation |
 | 0x02BB | inbound | HearSpeech | `ClientCommunicationSystem::Handle_Communication__HearSpeech` | PB | B | P+W | P+W | Local chat |
 | 0x02BC | inbound | HearRangedSpeech | `ClientCommunicationSystem::Handle_Communication__HearRangedSpeech` | PB | B | P+W | P+W | Shouts; same parser as 0x02BB |
 | 0x02CD | inbound | PrivateUpdatePropertyInt | `ClientObjMaintSystem::Handle_Qualities__PrivateUpdateInt` | PB | B | – | P+W | Owner-only int property |
 | 0x02CE | inbound | PublicUpdatePropertyInt | – | PB | B | – | P+W | Broadcast int property |
 | 0x02CF | inbound | PrivateUpdatePropertyInt64 | – | PB | B | – | P+W | Owner-only int64 |
 | 0x02D0 | inbound | PublicUpdatePropertyInt64 | – | PB | B | – | P+W | Broadcast int64 |
 | 0x02D1 | inbound | PrivateUpdatePropertyBool | `ClientObjMaintSystem::Handle_Qualities__PrivateUpdateBool` | PB | B | – | P+W | Owner-only bool |
 | 0x02D2 | inbound | PublicUpdatePropertyBool | – | PB | B | – | P+W | Broadcast bool |
 | 0x02D3 | inbound | PrivateUpdatePropertyFloat | `ClientObjMaintSystem::Handle_Qualities__PrivateUpdateFloat` | PB | B | – | P+W | Owner-only float |
 | 0x02D4 | inbound | PublicUpdatePropertyFloat | – | PB | B | – | P+W | Broadcast float |
 | 0x02D5 | inbound | PrivateUpdatePropertyString | – | PB | B | – | P+W | Owner-only string |
 | 0x02D6 | inbound | PublicUpdatePropertyString | – | PB | B | – | P+W | Broadcast string |
 | 0x02D7 | inbound | PrivateUpdatePropertyDataID | – | PB | B | – | P+W | Owner-only DataID |
 | 0x02D8 | inbound | PublicUpdatePropertyDataID | – | PB | B | – | P+W | Broadcast DataID |
 | 0x02D9 | inbound | PrivateUpdatePropertyInstanceID | `CM_Qualities::DispatchUI_PrivateUpdateInstanceID` | PB | B | – | P+W | Owner-only InstanceID |
 | 0x02DA | inbound | PublicUpdateInstanceID | – | PB | B | – | P+W | Broadcast InstanceID |
 | 0x02DB | inbound | PrivateUpdatePosition | `CM_Qualities::DispatchUI_PrivateUpdatePosition` | PB | B | – | –defer:F.x | Owner-only position; redundant with 0xF748 |
 | 0x02DC | inbound | PublicUpdatePosition | – | PB | B | – | –defer:F.x | Public position; redundant with 0xF748 |
 | 0x02DD | inbound | PrivateUpdateSkill | – | PB | B | – | P+W | Owner-only skill XP |
 | 0x02DE | inbound | PublicUpdateSkill | – | PB | B | – | P+W | Public skill |
 | 0x02DF | inbound | PrivateUpdateSkillLevel | – | PB | B | – | P+W | Owner-only skill base level |
 | 0x02E0 | inbound | PublicUpdateSkillLevel | – | PB | B | – | P+W | Public skill base level |
 | 0x02E3 | inbound | PrivateUpdateAttribute | `ClientObjMaintSystem::Handle_Qualities__PrivateUpdateAttribute` | PB | B | – | P+W | Strength/Stamina/etc base |
 | 0x02E4 | inbound | PublicUpdateAttribute | – | PB | B | – | P+W | Public attribute |
 | 0x02E7 | inbound | PrivateUpdateVital | – | PB | B | P+W | P+W | Max HP/Stam/Mana — vitals panel |
 | 0x02E8 | inbound | PublicUpdateVital | – | PB | B | – | P+W | Public vital |
 | 0x02E9 | inbound | PrivateUpdateAttribute2ndLevel | `ClientObjMaintSystem::Handle_Qualities__PrivateUpdateAttribute2ndLevel` | PB [^m-1] | B | P+W | P+W | Current-only vital delta |
 | 0xEA60 | inbound | AdminEnvirons | `CPlayerSystem::Handle_Admin__Environs` | – | B | P+W | P+W | Fog presets / sound cues |
 | 0xF625 | inbound | ObjDescEvent | `SmartBox::HandleObjDescEvent` | PB | B | P+W | P+W | Per-entity appearance update |
 | 0xF643 | inbound | CharacterCreateResponse | – | PB | B | – | –defer:char-creation | Char-creation flow not yet built |
 | 0xF653 | outbound | CharacterLogOff | – | PB | P | B | PB+W | Sent on Dispose; ACE accepts |
 | 0xF655 | both | CharacterDelete | – | PB | P | – | –defer:char-mgmt | Char-management UI deferred |
 | 0xF656 | outbound | CharacterCreate | – | PB | P | – | –defer:char-creation | Char-creation flow not yet built |
 | 0xF657 | outbound | CharacterEnterWorld | `CM_Login::SendNotice_BeginEnterWorld` [^m-2] | PB | P | B | PB+W | Built; sent during handshake |
 | 0xF658 | inbound | CharacterList | `CPlayerSystem::Handle_Login__CharacterSet` | PB | B | P+W | P+W | Login char picker |
 | 0xF659 | inbound | CharacterError | `CPlayerSystem::Handle_CharacterError` | PB | B | – | P+W | Login/restore failures |
 | 0xF6EA | both | ForceObjectDescSend | – | PB | P | – | –defer:F.x | Server requests client re-send ObjDesc; rare |
 | 0xF745 | inbound | CreateObject (ObjectCreate) | `SmartBox::HandleCreateObject` | PB | B | P+W | P+W | Spawn entity in bubble |
 | 0xF746 | inbound | PlayerCreate | `SmartBox::HandleCreatePlayer` | PB | B | P+W [^m-3] | P+W | Triggers LoginComplete |
 | 0xF747 | inbound | DeleteObject (ObjectDelete) | `SmartBox::HandleDeleteObject` | PB | B | P+W | P+W | Despawn |
 | 0xF748 | inbound | UpdatePosition | `CM_Qualities::DispatchUI_UpdatePosition` | PB | B | P+W | P+W | Periodic position sync |
 | 0xF749 | inbound | ParentEvent | `SmartBox::HandleParentEvent` | PB | B | – | P+W | Equip/wield parent change |
 | 0xF74A | inbound | PickupEvent | `SmartBox::HandlePickupEvent` | PB | B | – | P+W | Pickup confirmation |
 | 0xF74B | inbound | SetState | `SmartBox::HandleSetState` | PB | B | – | P+W | Door open/close, container state |
 | 0xF74C | inbound | UpdateMotion (Motion) | – | PB | B | P+W | P+W | Animation cycle change |
 | 0xF74E | inbound | VectorUpdate | `SmartBox::HandleVectorUpdate` | PB | B | P+W | P+W | Remote jump velocity, missile arc |
 | 0xF750 | inbound | Sound | `SmartBox::HandleSoundEvent` | PB | B | – | P+W | Positional sound trigger |
 | 0xF751 | inbound | PlayerTeleport | `SmartBox::HandlePlayerTeleport` | PB | B | P+W | P+W | Portal/teleport screen |
 | 0xF752 | inbound | AutonomyLevel | `CommandInterpreter::SetAutonomyLevel` | P [^m-4] | – | – | P+W | Server tells client physics-trust level |
 | 0xF753 | both | AutonomousPosition | `CM_Movement::Event_AutonomousPosition` | PB | – | B | PB+W | Outbound built; inbound parser missing |
 | 0xF754 | inbound | PlayScript (PlayScriptId) | `SmartBox::HandlePlayScriptID` | – | – | P+W [^m-5] | P+W | Inline parser; lightning, spell FX, emotes |
 | 0xF755 | inbound | PlayEffect | – | PB | B | – | P+W | Particle/visual scripts; ACE uses for PlayScript wrapper |
 | 0xF7B0 | inbound | GameEvent (envelope) | – | PB | B | P+W | P+W | Envelope for sub-opcodes (see §4) |
 | 0xF7B1 | outbound | GameAction (envelope) | – | PB | P | B+W | PB+W | Envelope for sub-opcodes (see §5) |
 | 0xF7C1 | inbound | AccountBanned | – | – | B | – | –defer:F.x | ACE-only, rarely seen |
 | 0xF7C8 | outbound | CharacterEnterWorldRequest | – | PB | P | B | PB+W | Built; sent before 0xF657 |
 | 0xF7CC | both | GetServerVersion | `Proto_UI::SendAdminGetServerVersion` | – | P | – | –defer:F.x | Admin-only |
 | 0xF7CD | both | FriendsOld | – | – | P | – | –defer:F.x | Obsolete; ACE drops it |
 | 0xF7D9 | outbound | CharacterRestore | – | PB | P | – | –defer:char-mgmt | Char-management UI deferred |
 | 0xF7DB | inbound | UpdateObject | `SmartBox::HandleUpdateObject` | PB | B | – | P+W | Heavy re-send of object visual+physics |
 | 0xF7DC | inbound | AccountBoot | `CPlayerSystem::Handle_AccountBooted` | PB | B | – | P+W | Kicked from server |
 | 0xF7DE | both | TurbineChat | `CCommunicationSystem::IsUsingTurbineChat` | PB | PB [^m-6] | PB+W | PB+W | Global community chat |
 | 0xF7DF | inbound | CharacterEnterWorldServerReady | – | P [^m-7] | B | P+W [^m-8] | P+W | Handshake gate during enter-world |
 | 0xF7E0 | inbound | ServerMessage | – | PB | B | P+W | P+W | System message / announcements |
 | 0xF7E1 | inbound | ServerName | `ECM_Login::SendNotice_WorldName` | PB | B | – | P+W | Shard name during login |
 | 0xF7E2 | both | DDD_DataMessage | – | – | – | – | –defer:dat-streaming | DDD download channel (we ship dats locally) |
 | 0xF7E3 | both | DDD_RequestDataMessage | – | – | P | – | –defer:dat-streaming | Client requests dat data |
 | 0xF7E4 | both | DDD_ErrorMessage | – | – | – | – | –defer:dat-streaming | DDD error channel |
 | 0xF7E5 | inbound | DDD_Interrogation | `DDD_InterrogationMessage::Serialize` | PB [^m-9] | B | P+W | P+W | Server asks "what dat versions?" |
 | 0xF7E6 | outbound | DDD_InterrogationResponse | – | PB | P | B | PB+W | Built; sent in response to 0xF7E5 |
 | 0xF7E7 | both | DDD_BeginDDD | – | – | – | – | –defer:dat-streaming | DDD start |
 | 0xF7E8 | both | DDD_BeginPullDDD | – | – | – | – | –defer:dat-streaming | DDD pull start |
 | 0xF7E9 | both | DDD_IterationData | – | – | – | – | –defer:dat-streaming | DDD chunk iteration |
 | 0xF7EA | inbound | DDD_EndDDD | – | – | P | – | –defer:dat-streaming | DDD end signal |
 **Footnotes:**
 [^m-1]: ACE calls 0x02E9 `PrivateUpdateAttribute2ndLevel`; holtburger calls it `PrivateUpdateVitalCurrent` (current-only delta).
 [^m-2]: Retail-side trigger of the enter-world flow; the wire opcode 0xF657 is constructed from the request.
 [^m-3]: PlayerCreate fires LoginComplete when guid matches own char; CreateObject body is parsed for the player too.
 [^m-4]: AutonomyLevel is in holtburger's `GameMessage` enum + unpack/pack, but its enum value (0xF752) is mapped via opcode dispatch.
 [^m-5]: 0xF754 PlayScript is parsed inline in `WorldSession.cs:850` (no dedicated `Messages/PlayScript.cs`); routed to `PlayScriptReceived` event for VFX runtime.
 [^m-6]: ACE handles inbound TurbineChat via `TurbineChatHandler` and emits outbound via `GameMessageTurbineChat`, hence both directions.
 [^m-7]: CharacterEnterWorldServerReady is unit variant in holtburger (no payload); only an opcode marker.
 [^m-8]: acdream uses 0xF7DF as a handshake gate (`WorldSession.cs:495`), no dedicated parser file.
 [^m-9]: DddInterrogation in holtburger is a unit variant — opcode marker only, no payload to parse.
 **Caveats and unknowns:**
 - `0xF7C1 AccountBanned` is in ACE's enum + has a `GameMessageAccountBanned.cs`, but holtburger has it commented out. Marked `–defer` since the channel exists in retail but rarely fires.
 - `0xF7CC GetServerVersion`, `0xF7CD FriendsOld`: ACE has handlers for them (i.e. accepts them inbound from a client that sends them), but no acdream sends them today. Listed as `–defer`.
 - `0xF619 PositionAndMovement`: holtburger documents this as a "ghost" opcode (defined but never emitted by ACE/retail). Excluded from the table — confirmed dead code per holtburger comment + grep on ACE shows no `Writer.Write` site.
 - `0xF754 PlayScriptId` vs `0xF755 PlayEffect`: ACE has the `Script.cs` GameMessage tagged with `PlayEffect (0xF755)`, while retail's `SmartBox::HandlePlayScriptID` is the 0xF754 handler. acdream's inline parser at `WorldSession.cs:850` reads `[u32 opcode][u32 guid][u32 scriptId]` matching the 0xF754 layout.
 ---
 ## Section 4 — GameEvent sub-opcodes (inside 0xF7B0 envelope)
 In-scope: 103. Implemented (parsed) in acdream today: 27. Wired (`W`) in acdream today: 26. Phase M target delta: 76 new parsers + ~50 deferred to later phases.
 All rows are `inbound` direction (GameEvents are server→client only).
 | Code | Direction | Name | Named-retail symbol | Holtburger | ACE | acdream today | Phase M target | Notes |
 |---|---|---|---|---|---|---|---|---|
 | 0x0003 | inbound | AllegianceUpdateAborted | `ClientAllegianceSystem::Handle_Allegiance__AllegianceUpdateAborted` | – | W | – | –defer:Allegiance | scope deferred — no allegiance UI yet |
 | 0x0004 | inbound | PopupString | `ClientCommunicationSystem::Handle_Communication__PopUpString` | W | W | W | W | modal text → ChatLog.OnPopup |
 | 0x0013 | inbound | PlayerDescription | `CPlayerSystem::Handle_PlayerDescription` | W | W | W | W | full local-player snapshot at login [^e-a] |
 | 0x0020 | inbound | AllegianceUpdate | `ClientAllegianceSystem::Handle_Allegiance__AllegianceUpdate` | – | W | – | –defer:Allegiance | needs CAllegianceProfile parser |
 | 0x0021 | inbound | FriendsListUpdate | `CM_Social::SendNotice_UpdateFriendsList` | – | W | – | P+W | FriendDataList; small parser, high UX value |
 | 0x0022 | inbound | InventoryPutObjInContainer | – (CM_Inventory) | W | W | W | W | (item, container, slot) — items.MoveItem |
 | 0x0023 | inbound | WieldObject | – (CM_Inventory) | W | W | W | W | server-driven equip |
 | 0x0029 | inbound | CharacterTitle | `CM_Social::SendNotice_AddCharacterTitle` | – | W | – | –defer:Social | gmCharacterTitleUI |
 | 0x002B | inbound | UpdateTitle | `CM_Social::SendNotice_SetDisplayCharacterTitle` | – | W | – | –defer:Social | titles UI not yet built |
 | 0x0052 | inbound | CloseGroundContainer | – (gmInventoryUI) | W | W | P | P+W | parser exists, needs ItemRepository wiring |
 | 0x0062 | inbound | ApproachVendor | – (CM_Vendor) | W | W | – | –defer:VendorPanel | needs VendorProfile + ItemProfile list parser |
 | 0x0075 | inbound | StartBarber | `ClientUISystem::Handle_Character__StartBarber` | – | W | – | –defer:Barber | gmBarberUI not yet built |
 | 0x00A0 | inbound | InventoryServerSaveFailed | – (CM_Inventory) | W | W | P | P+W | parser exists; needs revert hook |
 | 0x00A3 | inbound | FellowshipQuit | `ClientFellowshipSystem::Handle_Fellowship__Quit` | W | W | – | –defer:Fellowship | scope deferred — no fellowship state |
 | 0x00A4 | inbound | FellowshipDismiss | `ClientFellowshipSystem::Handle_Fellowship__Dismiss` | W | W | – | –defer:Fellowship | scope deferred |
 | 0x00B4 | inbound | BookDataResponse | `CM_Writing::Event_BookData` | W | W | – | –defer:Books | gmBookUI not yet built |
 | 0x00B5 | inbound | BookModifyPageResponse | `CM_Writing::Event_BookModifyPage` | – | W | – | –defer:Books | |
 | 0x00B6 | inbound | BookAddPageResponse | `CM_Writing::SendNotice_BookAddPageResponse` | – | W | – | –defer:Books | |
 | 0x00B7 | inbound | BookDeletePageResponse | `CM_Writing::SendNotice_BookDeletePageResponse` | – | W | – | –defer:Books | |
 | 0x00B8 | inbound | BookPageDataResponse | `CM_Writing::SendNotice_BookPageDataResponse` | W | W | – | –defer:Books | |
 | 0x00C3 | inbound | GetInscriptionResponse | – | – | W | – | –defer:Books | inscription on caster items |
 | 0x00C9 | inbound | IdentifyObjectResponse | `ClientUISystem::Handle_Item__AppraiseDone` [^e-b] | W | W | W | W | AppraiseInfoParser feeds ItemRepository |
 | 0x0147 | inbound | ChannelBroadcast | `ClientCommunicationSystem::Handle_Communication__ChannelBroadcast` | W | W | W | W | (channelId, sender, msg) → ChatLog |
 | 0x0148 | inbound | ChannelList | `ClientCommunicationSystem::Handle_Communication__ChannelList` | – | W | – | P+W | PackableList<PStringBase>; admin/list response |
 | 0x0149 | inbound | ChannelIndex | `ClientCommunicationSystem::Handle_Communication__ChannelIndex` | – | W | – | P+W | PackableList<PStringBase> |
 | 0x0196 | inbound | ViewContents | `ClientUISystem::OnViewContents` | W | W | – | P+W | server view of remote container — needed for sidepacks |
 | 0x019A | inbound | InventoryPutObjectIn3D | – (CM_Inventory) | W | W | P | P+W | parser exists; needs spawn-into-world wiring |
 | 0x01A7 | inbound | AttackDone | – | W | W | W | W | combat seq complete |
 | 0x01A8 | inbound | MagicRemoveSpell | `ClientMagicSystem::Handle_Magic__RemoveSpell` | W | W | W | W | spell removed from spellbook |
 | 0x01AC | inbound | VictimNotification | `ClientCombatSystem::HandleVictimNotificationEvent` | W | W | W | W | death msg for victim |
 | 0x01AD | inbound | KillerNotification | `ClientCombatSystem::HandleKillerNotificationEvent` | W | W | W | W | death msg for killer |
 | 0x01B1 | inbound | AttackerNotification | `ClientCombatSystem::HandleAttackerNotificationEvent` | W | W | W | W | "you hit X" |
 | 0x01B2 | inbound | DefenderNotification | `ClientCombatSystem::HandleDefenderNotificationEvent` | W | W | W | W | "X hit you" |
 | 0x01B3 | inbound | EvasionAttackerNotification | `ClientCombatSystem::HandleEvasionAttackerNotificationEvent` | W | W | W | W | "X evaded" |
 | 0x01B4 | inbound | EvasionDefenderNotification | `ClientCombatSystem::HandleEvasionDefenderNotificationEvent` | W | W | W | W | "you evaded X" |
 | 0x01B8 | inbound | CombatCommenceAttack | – | W | W | W | W | empty payload |
 | 0x01C0 | inbound | UpdateHealth | `CM_Combat::SendNotice_UpdateObjectHealth` | W | W | W | W | (guid, healthPct) → CombatState |
 | 0x01C3 | inbound | QueryAgeResponse | `ClientCommunicationSystem::Handle_Character__QueryAgeResponse` | – | W | – | P | small string parser; chat panel display |
 | 0x01C7 | inbound | UseDone | `ClientUISystem::Handle_Item__UseDone` | W | W | P | P+W | parser exists; needs InteractionState wiring |
 | 0x01C8 | inbound | AllegianceUpdateDone | – | – | W | – | –defer:Allegiance | |
 | 0x01C9 | inbound | FellowshipFellowUpdateDone | `ClientFellowshipSystem::Handle_Fellowship__FellowUpdateDone` | W | W | – | –defer:Fellowship | empty payload |
 | 0x01CA | inbound | FellowshipFellowStatsDone | `ClientFellowshipSystem::Handle_Fellowship__FellowStatsDone` | W | W | – | –defer:Fellowship | empty payload |
 | 0x01CB | inbound | ItemAppraiseDone | `ClientUISystem::Handle_Item__AppraiseDone` | – | W | – | P | post-IdentifyObjectResponse signal |
 | 0x01E2 | inbound | Emote | `ClientCommunicationSystem::Handle_Communication__HearEmote` [^e-c] | – | W | – | P | "*X waves*" — chat broadcast |
 | 0x01EA | inbound | PingResponse | `ClientUISystem::Handle_Character__ReturnPing` | W | W | P | P+W | parser exists; needs latency/heartbeat wiring |
 | 0x01F4 | inbound | SetSquelchDB | `ClientCommunicationSystem::Handle_Communication__SetSquelchDB` | – | W | – | –defer:SquelchUI | SquelchDB blob; ignore-list state |
 | 0x01FD | inbound | RegisterTrade | `ClientTradeSystem::Handle_Trade__Recv_RegisterTrade` | W | W | – | –defer:TradePanel | (guid, accepterGuid, ackTimer) |
 | 0x01FE | inbound | OpenTrade | `ClientTradeSystem::Handle_Trade__Recv_OpenTrade` | W | W | – | –defer:TradePanel | initiator guid |
 | 0x01FF | inbound | CloseTrade | `ClientTradeSystem::Handle_Trade__Recv_CloseTrade` | W | W | – | –defer:TradePanel | closer guid |
 | 0x0200 | inbound | AddToTrade | `ClientTradeSystem::Handle_Trade__Recv_AddToTrade` | W | W | P | –defer:TradePanel | parser exists; needs TradeState |
 | 0x0201 | inbound | RemoveFromTrade | `ClientTradeSystem::Handle_Trade__Recv_RemoveFromTrade` | – | W | – | –defer:TradePanel | (initiatorGuid, itemGuid) |
 | 0x0202 | inbound | AcceptTrade | `ClientTradeSystem::Handle_Trade__Recv_AcceptTrade` | W | W | P | –defer:TradePanel | parser exists |
 | 0x0203 | inbound | DeclineTrade | `ClientTradeSystem::Handle_Trade__Recv_DeclineTrade` | W | W | – | –defer:TradePanel | initiator guid |
 | 0x0205 | inbound | ResetTrade | `ClientTradeSystem::Handle_Trade__Recv_ResetTrade` | W | W | – | –defer:TradePanel | reset to-trade list |
 | 0x0207 | inbound | TradeFailure | `ClientTradeSystem::Handle_Trade__Recv_TradeFailure` | W | W | P | –defer:TradePanel | parser exists |
 | 0x0208 | inbound | ClearTradeAcceptance | `ClientTradeSystem::Handle_Trade__Recv_ClearTradeAcceptance` | W | W | – | –defer:TradePanel | empty payload |
 | 0x021D | inbound | HouseProfile | `ClientHousingSystem::Handle_House__Recv_HouseProfile` | – | W | – | –defer:Housing | HouseProfile blob |
 | 0x0225 | inbound | HouseData | `ClientHousingSystem::Handle_House__Recv_HouseData` | – | W | – | –defer:Housing | HouseData blob |
 | 0x0226 | inbound | HouseStatus | `ClientHousingSystem::Handle_House__Recv_HouseStatus` | – | W | – | –defer:Housing | scalar status code |
 | 0x0227 | inbound | UpdateRentTime | `ClientHousingSystem::Handle_House__Recv_UpdateRentTime` | – | W | – | –defer:Housing | i32 timestamp |
 | 0x0228 | inbound | UpdateRentPayment | `ClientHousingSystem::Handle_House__Recv_UpdateRentPayment` | – | W | – | –defer:Housing | HousePaymentList |
 | 0x0248 | inbound | HouseUpdateRestrictions | `ClientHousingSystem::Handle_House__Recv_UpdateRestrictions` | – | W | – | –defer:Housing | RestrictionDB blob |
 | 0x0257 | inbound | UpdateHAR | `ClientHousingSystem::Handle_House__Recv_UpdateHAR` | – | W | – | –defer:Housing | HAR blob |
 | 0x0259 | inbound | HouseTransaction | `ClientHousingSystem::Handle_House__Recv_HouseTransaction` | – | W | – | –defer:Housing | scalar txn code |
 | 0x0264 | inbound | QueryItemManaResponse | `ClientUISystem::Handle_Item__QueryItemManaResponse` | W | W | P | P+W | parser exists; needs ItemRepository wiring |
 | 0x0271 | inbound | AvailableHouses | `ClientHousingSystem::Handle_House__Recv_AvailableHouses` | – | W | – | –defer:Housing | PackableList<u32> + flag |
 | 0x0274 | inbound | CharacterConfirmationRequest | `ClientUISystem::Handle_Character__ConfirmationRequest` | W | W | P | P+W | parser exists; needs modal-confirm wiring |
 | 0x0276 | inbound | CharacterConfirmationDone | `ClientUISystem::Handle_Character__ConfirmationDone` | W | W | – | P+W | (type, contextId); confirms client ACK |
 | 0x027A | inbound | AllegianceLoginNotification | `ClientAllegianceSystem::Handle_Allegiance__AllegianceLoginNotificationEvent` | – | W | – | –defer:Allegiance | (guid, login/logout flag) |
 | 0x027C | inbound | AllegianceInfoResponse | `ClientAllegianceSystem::Handle_Allegiance__AllegianceInfoResponseEvent` | – | W | – | –defer:Allegiance | CAllegianceProfile |
 | 0x0281 | inbound | JoinGameResponse | `ClientMiniGameSystem::Handle_Game__Recv_JoinGameResponse` | – | W | – | –defer:MiniGame | chess/dice/etc — minimal value |
 | 0x0282 | inbound | StartGame | `ClientMiniGameSystem::Handle_Game__Recv_StartGame` | W | W | – | –defer:MiniGame | empty payload |
 | 0x0283 | inbound | MoveResponse | `ClientMiniGameSystem::Handle_Game__Recv_MoveResponse` | – | W | – | –defer:MiniGame | minigame move ack |
 | 0x0284 | inbound | OpponentTurn | `ClientMiniGameSystem::Handle_Game__Recv_OpponentTurn` | – | W | – | –defer:MiniGame | GameMoveData blob |
 | 0x0285 | inbound | OpponentStalemate | `ClientMiniGameSystem::Handle_Game__Recv_OppenentStalemateState` | – | W | – | –defer:MiniGame | typo preserved (retail name) |
 | 0x028A | inbound | WeenieError | `ClientCommunicationSystem::Handle_Communication__WeenieError` | W | W | W | W | error code → ChatLog.OnWeenieError |
 | 0x028B | inbound | WeenieErrorWithString | `ClientCommunicationSystem::Handle_Communication__WeenieErrorWithString` | W | W | W | W | (code, interp) → ChatLog |
 | 0x028C | inbound | GameOver | `ClientMiniGameSystem::Handle_Game__Recv_GameOver` | – | W | – | –defer:MiniGame | (gameId, winner) |
 | 0x0295 | inbound | SetTurbineChatChannels | `ClientCommunicationSystem::Handle_Communication__Recv_ChatRoomTracker` [^e-d] | W | W | W | W | per-room ids → TurbineChatState |
 | 0x02AE | inbound | AdminQueryPluginList | – (admin tooling) | – | W | – | –skip:admin-only | server-admin path; not retail-emitted to player |
 | 0x02B1 | inbound | AdminQueryPlugin | – | – | W | – | –skip:admin-only | |
 | 0x02B3 | inbound | AdminQueryPluginResponse | – | – | W | – | –skip:admin-only | |
 | 0x02B4 | inbound | SalvageOperationsResult | `ClientUISystem::Handle_Inventory__Recv_SalvageOperationsResultData` | – | W | – | –defer:SalvageUI | SalvageOperationsResultData blob |
 | 0x02BD | inbound | Tell | – (CM_Communication) | W | W | W | W | direct whisper → ChatLog |
 | 0x02BE | inbound | FellowshipFullUpdate | `ClientFellowshipSystem::Handle_Fellowship__FullUpdate` | W | W | – | –defer:Fellowship | CFellowship blob |
 | 0x02BF | inbound | FellowshipDisband | `ClientFellowshipSystem::Handle_Fellowship__Disband` | W | W | – | –defer:Fellowship | empty payload |
 | 0x02C0 | inbound | FellowshipUpdateFellow | `ClientFellowshipSystem::Handle_Fellowship__UpdateFellow` | W | W | – | –defer:Fellowship | (memberGuid, Fellow, flag) |
 | 0x02C1 | inbound | MagicUpdateSpell | `ClientMagicSystem::Handle_Magic__UpdateSpell` | W | W | W | W | learned spellId → Spellbook |
 | 0x02C2 | inbound | MagicUpdateEnchantment | `ClientMagicSystem::Handle_Magic__UpdateEnchantment` | W | W | W | W | Enchantment blob → Spellbook |
 | 0x02C3 | inbound | MagicRemoveEnchantment | `ClientMagicSystem::Handle_Magic__RemoveEnchantment` | W | W | W | W | (layerId, spellId) |
 | 0x02C4 | inbound | MagicUpdateMultipleEnchantments | `ClientMagicSystem::Handle_Magic__UpdateMultipleEnchantments` | W | W | – | P+W | PackableList<Enchantment> |
 | 0x02C5 | inbound | MagicRemoveMultipleEnchantments | `ClientMagicSystem::Handle_Magic__RemoveMultipleEnchantments` | W | W | – | P+W | PackableList<u32> |
 | 0x02C6 | inbound | MagicPurgeEnchantments | `ClientMagicSystem::Handle_Magic__PurgeEnchantments` | W | W | W | W | empty payload → Spellbook.OnPurgeAll |
 | 0x02C7 | inbound | MagicDispelEnchantment | `ClientMagicSystem::Handle_Magic__DispelEnchantment` | W | W | W | W | shared parser w/ MagicRemoveEnchantment |
 | 0x02C8 | inbound | MagicDispelMultipleEnchantments | `ClientMagicSystem::Handle_Magic__DispelMultipleEnchantments` | W | W | – | P+W | PackableList<u32> |
 | 0x02C9 | inbound | PortalStormBrewing | `ClientUISystem::Handle_Misc__PortalStormBrewing` | – | W | – | P+W | float intensity → ChatLog system message |
 | 0x02CA | inbound | PortalStormImminent | `ClientUISystem::Handle_Misc__PortalStormImminent` | – | W | – | P+W | float intensity |
 | 0x02CB | inbound | PortalStorm | `ClientUISystem::Handle_Misc__PortalStorm` | – | W | – | P+W | empty payload — actual storm trigger |
 | 0x02CC | inbound | PortalStormSubsided | `ClientUISystem::Handle_Misc__PortalStormSubsided` | – | W | – | P+W | empty payload |
 | 0x02EB | inbound | CommunicationTransientString | `ClientCommunicationSystem::Handle_Communication__TransientString` | W | W | W | W | (msg, chatType) → ChatLog system msg |
 | 0x0312 | inbound | MagicPurgeBadEnchantments | `ClientMagicSystem::Handle_Magic__PurgeBadEnchantments` | W | W | – | P+W | empty payload |
 | 0x0314 | inbound | SendClientContractTrackerTable | `ClientUISystem::Handle_Social__SendClientContractTrackerTable` | – | W | – | –defer:Quests | CContractTrackerTable blob |
 | 0x0315 | inbound | SendClientContractTracker | `ClientUISystem::Handle_Social__SendClientContractTracker` | – | W | – | –defer:Quests | (CContractTracker, flag, flag) |
 **Footnotes:**
 [^e-a]: PlayerDescription has its own dedicated parser (`PlayerDescriptionParser.TryParse`) rather than living in `GameEvents.cs`. Wires into `LocalPlayerState` (vitals 7/8/9), `Spellbook` (learned spells + enchantments), `ItemRepository` (inventory + equipped), and the `onSkillsUpdated` callback (Run/Jump skills for movement).
 [^e-b]: IdentifyObjectResponse uses `AppraiseInfoParser.TryParse` (separate file) rather than the simple header-only parser in `GameEvents.cs`. Returns full property bundle (int / int64 / bool / float / string / DID tables) plus SpellBook list. The retail handler `Handle_Item__AppraiseDone` (0x01CB) is the post-arrival completion signal, not the data carrier itself.
 [^e-c]: 0x01E2 Emote sub-opcode is distinct from `HearEmote` (top-level GameMessage 0x02BC); the sub-opcode form is documented in ACE's `GameEventType.cs` but the named-retail decomp doesn't expose a dedicated handler — likely re-routed through the chat broadcast path.
 [^e-d]: Named retail's `Recv_ChatRoomTracker` is the underlying handler symbol; ACE/Holtburger renamed to `SetTurbineChatChannels` for clarity. Same wire payload (per-room session ids for General/Trade/LFG/Roleplay/Society/Olthoi/Allegiance).
 ---
 ## Section 5 — GameAction sub-opcodes (inside 0xF7B1 envelope)
 In-scope: 96. Implemented (built) in acdream: 24. Live callers in acdream: 8. Phase M target delta: 72 new builders + golden-vector tests.
 All rows are `outbound` direction (GameActions are client→server only).
 | Code | Direction | Name | Named-retail symbol | Holtburger | ACE | acdream today | Phase M target | Notes |
 |------|-----------|------|---------------------|------------|-----|---------------|----------------|-------|
 | 0x0005 | outbound | SetSingleCharacterOption | – | W | H | – | B | Per-option toggle; sibling of 0x01A1 bitmap |
 | 0x0008 | outbound | TargetedMeleeAttack | `CM_Combat::Event_TargetedMeleeAttack` | W | H | W | B+W | Wired in WorldSession.SendMeleeAttack |
 | 0x000A | outbound | TargetedMissileAttack | `CM_Combat::Event_TargetedMissileAttack` | W | H | W | B+W | Wired in WorldSession.SendMissileAttack |
 | 0x000F | outbound | SetAfkMode | `CM_Communication::Event_SetAFKMode` | – | H | – | B | Toggle AFK |
 | 0x0010 | outbound | SetAfkMessage | `CM_Communication::Event_SetAFKMessage` | – | H | – | B | Custom AFK string |
 | 0x0015 | outbound | Talk | `CM_Communication::Event_Talk` | W | H | W | B+W | Wired in WorldSession.SendTalk |
 | 0x0017 | outbound | RemoveFriend | `CM_Social::Event_RemoveFriend` | – | H | – | B | Friends list mutation |
 | 0x0018 | outbound | AddFriend | `CM_Social::Event_AddFriend` | – | H | – | B | Friends list mutation |
 | 0x0019 | outbound | PutItemInContainer | `CM_Inventory::Event_PutItemInContainer` | W | H | – | B | Inventory move; high priority |
 | 0x001A | outbound | GetAndWieldItem | `CM_Inventory::Event_GetAndWieldItem` | W | H | – | B | Equip item |
 | 0x001B | outbound | DropItem | `CM_Inventory::Event_DropItem` | W | H | – | B | Drop to ground |
 | 0x001D | outbound | SwearAllegiance | `CM_Allegiance::Event_SwearAllegiance` | W | H | B | B+W | AllegianceRequests dead [^a-1] |
 | 0x001E | outbound | BreakAllegiance | `CM_Allegiance::Event_BreakAllegiance` | W | H | B | B+W | AllegianceRequests dead [^a-1] |
 | 0x001F | outbound | AllegianceUpdateRequest | – | – | H | – | B | Refresh allegiance tree |
 | 0x0025 | outbound | RemoveAllFriends | – | – | H | – | B | Clear friends list |
 | 0x0026 | outbound | TeleToPklArena | – | W | H | – | B | PK-lite arena recall |
 | 0x0027 | outbound | TeleToPkArena | – | – | H | – | B | PK arena recall |
 | 0x002C | outbound | TitleSet | – | – | H | – | B | Equip title |
 | 0x0030 | outbound | QueryAllegianceName | `CM_Allegiance::Event_QueryAllegianceName` | – | H | – | B | – |
 | 0x0031 | outbound | ClearAllegianceName | `CM_Allegiance::Event_ClearAllegianceName` | – | H | – | B | Officer-only |
 | 0x0032 | outbound | TalkDirect | `CM_Communication::Event_TalkDirect` | – | H | – | B | Targeted /say (rarely used) |
 | 0x0033 | outbound | SetAllegianceName | `CM_Allegiance::Event_SetAllegianceName` | – | H | – | B | Monarch-only |
 | 0x0035 | outbound | UseWithTarget | `CM_Inventory::Event_UseWithTargetEvent` | W | H | B | B+W | InteractRequests dead [^a-1] |
 | 0x0036 | outbound | Use | `CM_Inventory::Event_UseEvent` | W | H | B | B+W | InteractRequests dead [^a-1] |
 | 0x003B | outbound | SetAllegianceOfficer | `CM_Allegiance::Event_SetAllegianceOfficer` | – | H | – | B | – |
 | 0x003C | outbound | SetAllegianceOfficerTitle | `CM_Allegiance::Event_SetAllegianceOfficerTitle` | – | H | – | B | – |
 | 0x003D | outbound | ListAllegianceOfficerTitles | `CM_Allegiance::Event_ListAllegianceOfficerTitles` | – | H | – | B | – |
 | 0x003E | outbound | ClearAllegianceOfficerTitles | `CM_Allegiance::Event_ClearAllegianceOfficerTitles` | – | H | – | B | – |
 | 0x003F | outbound | DoAllegianceLockAction | `CM_Allegiance::Event_DoAllegianceLockAction` | – | H | – | B | Lock recruitment |
 | 0x0040 | outbound | SetAllegianceApprovedVassal | `CM_Allegiance::Event_SetAllegianceApprovedVassal` | – | – | – | B | – |
 | 0x0041 | outbound | AllegianceChatGag | `CM_Allegiance::Event_AllegianceChatGag` | – | H | – | B | – |
 | 0x0042 | outbound | DoAllegianceHouseAction | `CM_Allegiance::Event_DoAllegianceHouseAction` | – | H | – | B | – |
 | 0x0044 | outbound | RaiseVital | – | W | H | B | B+W | CharacterActions builder dead [^a-1] |
 | 0x0045 | outbound | RaiseAttribute | – | W | H | B | B+W | CharacterActions builder dead [^a-1] |
 | 0x0046 | outbound | RaiseSkill | – | W | H | B | B+W | CharacterActions builder dead [^a-1] |
 | 0x0047 | outbound | TrainSkill | `CM_Train::Event_TrainSkill` | W | H | B | B+W | CharacterActions builder dead [^a-1] |
 | 0x0048 | outbound | CastUntargetedSpell | `CM_Magic::Event_CastUntargetedSpell` | W | H | B | B+W | CastSpellRequest builder dead [^a-1] |
 | 0x004A | outbound | CastTargetedSpell | `CM_Magic::Event_CastTargetedSpell` | W | H | B | B+W | CastSpellRequest builder dead [^a-1] |
 | 0x0053 | outbound | ChangeCombatMode | `CM_Combat::Event_ChangeCombatMode` | W | H | W | B+W | Wired in WorldSession.SendChangeCombatMode |
 | 0x0054 | outbound | StackableMerge | `CM_Inventory::Event_StackableMerge` | W | H | B | B+W | InventoryActions builder dead [^a-1] |
 | 0x0055 | outbound | StackableSplitToContainer | `CM_Inventory::Event_StackableSplitToContainer` | W | H | B | B+W | InventoryActions builder dead [^a-1] |
 | 0x0056 | outbound | StackableSplitTo3D | `CM_Inventory::Event_StackableSplitTo3D` | – | H | B | B+W | InventoryActions builder dead [^a-1] |
 | 0x0058 | outbound | ModifyCharacterSquelch | `CM_Communication::Event_ModifyCharacterSquelch` | – | H | – | B | Mute one player |
 | 0x0059 | outbound | ModifyAccountSquelch | `CM_Communication::Event_ModifyAccountSquelch` | – | H | – | B | Mute account |
 | 0x005B | outbound | ModifyGlobalSquelch | `CM_Communication::Event_ModifyGlobalSquelch` | – | H | – | B | Mute pattern |
 | 0x005D | outbound | Tell | – | W | H | W | B+W | Wired in WorldSession.SendTell [^a-2] |
 | 0x005F | outbound | Buy | `CM_Vendor::Event_Buy` | W | H | – | B | Vendor purchase |
 | 0x0060 | outbound | Sell | `CM_Vendor::Event_Sell` | W | H | – | B | Vendor sell |
 | 0x0063 | outbound | TeleToLifestone | `CM_Character::Event_TeleToLifestone` | W | H | B | B+W | InteractRequests builder dead [^a-1] |
 | 0x00A1 | outbound | LoginComplete | `CM_Character::Event_LoginCompleteNotification` | W | H | W | B+W | Wired in GameWindow.cs:4423 |
 | 0x00A2 | outbound | FellowshipCreate | `CM_Fellowship::Event_Create` | W | H | B | B+W | SocialActions builder dead [^a-1] |
 | 0x00A3 | outbound | FellowshipQuit | `CM_Fellowship::Event_Quit` | W | H | B | B+W | SocialActions builder dead [^a-1] |
 | 0x00A4 | outbound | FellowshipDismiss | `CM_Fellowship::Event_Dismiss` | W | H | B | B+W | SocialActions builder dead [^a-1] |
 | 0x00A5 | outbound | FellowshipRecruit | `CM_Fellowship::Event_Recruit` | W | H | B | B+W | SocialActions builder dead [^a-1] |
 | 0x00A6 | outbound | FellowshipUpdateRequest | `CM_Fellowship::Event_UpdateRequest` | W | H | B | B+W | SocialActions builder dead [^a-1] |
 | 0x00AA | outbound | BookData | `CM_Writing::Event_BookData` | – | H | – | B | Open book contents |
 | 0x00AB | outbound | BookModifyPage | `CM_Writing::Event_BookModifyPage` | – | H | – | B | Edit page text |
 | 0x00AC | outbound | BookAddPage | `CM_Writing::Event_BookAddPage` | – | H | – | B | – |
 | 0x00AD | outbound | BookDeletePage | `CM_Writing::Event_BookDeletePage` | – | H | – | B | – |
 | 0x00AE | outbound | BookPageData | `CM_Writing::Event_BookPageData` | W | – | – | B | Read one page |
 | 0x00B1 | outbound | TeleToPoi | – | – | – | B | B | InventoryActions builder dead; ACE handler unclear [^a-1][^a-3] |
 | 0x00BF | outbound | SetInscription | `CM_Writing::Event_SetInscription` | – | – | – | B | Inscribe item |
 | 0x00C8 | outbound | IdentifyObject | `CM_Item::Event_Appraise` | W | H | B | B+W | AppraiseRequest builder dead [^a-1] |
 | 0x00CD | outbound | GiveObjectRequest | `CM_Inventory::Event_GiveObjectRequest` | W | H | B | B+W | InventoryActions builder dead [^a-1] |
 | 0x00D6 | outbound | AdvocateTeleport | – | – | H | – | B | GM-only teleport |
 | 0x0140 | outbound | AbuseLogRequest | `CM_Character::Event_AbuseLogRequest` | – | – | – | B | Player report tool |
 | 0x0145 | outbound | AddChannel | `CM_Communication::Event_ChannelList` | – | H | B | B+W | SocialActions builder dead [^a-1][^a-4] |
 | 0x0146 | outbound | RemoveChannel | – | – | H | B | B+W | SocialActions builder dead [^a-1] |
 | 0x0147 | outbound | ChatChannel | `CM_Communication::Event_ChannelBroadcast` | W | H | W | B+W | Wired in WorldSession.SendChannel; same code as inbound 0x0147 [^a-5] |
 | 0x0148 | outbound | ListChannels | – | – | – | – | B | – |
 | 0x0149 | outbound | IndexChannels | `CM_Communication::Event_ChannelIndex` | – | – | – | B | – |
 | 0x0195 | outbound | NoLongerViewingContents | `CM_Inventory::Event_NoLongerViewingContents` | W | H | – | B | Container UI close |
 | 0x019B | outbound | StackableSplitToWield | `CM_Inventory::Event_StackableSplitToWield` | W | H | B | B+W | InventoryActions builder dead [^a-1] |
 | 0x019C | outbound | AddShortcut | `CM_Character::Event_AddShortCut` | – | H | B | B+W | InventoryActions builder dead [^a-1] |
 | 0x019D | outbound | RemoveShortcut | `CM_Character::Event_RemoveShortCut` | – | H | B | B+W | InventoryActions builder dead [^a-1] |
 | 0x01A1 | outbound | SetCharacterOptions | – | – | H | B | B+W | SocialActions builder dead [^a-1] |
 | 0x01A8 | outbound | RemoveSpellC2S | `CM_Magic::Event_RemoveSpell` | – | H | – | B | Self-cancel buff |
 | 0x01B7 | outbound | CancelAttack | `CM_Combat::Event_CancelAttack` | W | H | W | B+W | Wired in WorldSession.SendCancelAttack |
 | 0x01BF | outbound | QueryHealth | `CM_Combat::Event_QueryHealth` | W | H | B | B+W | SocialActions builder dead [^a-1] |
 | 0x01C2 | outbound | QueryAge | `CM_Character::Event_QueryAge` | – | H | – | B | – |
 | 0x01C4 | outbound | QueryBirth | `CM_Character::Event_QueryBirth` | – | H | – | B | – |
 | 0x01DF | outbound | Emote | `CM_Communication::Event_Emote` | W | H | – | B | Custom /e text |
 | 0x01E1 | outbound | SoulEmote | `CM_Communication::Event_SoulEmote` | W | H | – | B | /soulemote |
 | 0x01E3 | outbound | AddSpellFavorite | `CM_Character::Event_AddSpellFavorite` | – | H | – | B | Spellbook pin |
 | 0x01E4 | outbound | RemoveSpellFavorite | `CM_Character::Event_RemoveSpellFavorite` | – | – | – | B | Spellbook unpin |
 | 0x01E9 | outbound | PingRequest | – | W | H | B | B+W | SocialActions builder dead; keepalive [^a-1] |
 | 0x01F6 | outbound | OpenTradeNegotiations | `CM_Trade::Event_OpenTradeNegotiations` | W | H | – | B | Begin trade |
 | 0x01F7 | outbound | CloseTradeNegotiations | `CM_Trade::Event_CloseTradeNegotiations` | W | H | – | B | Cancel trade |
 | 0x01F8 | outbound | AddToTrade | `CM_Trade::Event_AddToTrade` | W | H | – | B | Add item to trade |
 | 0x01FA | outbound | AcceptTrade | `CM_Trade::Event_AcceptTrade` | W | H | – | B | Confirm trade |
 | 0x01FB | outbound | DeclineTrade | `CM_Trade::Event_DeclineTrade` | W | H | – | B | Reject trade |
 | 0x0204 | outbound | ResetTrade | `CM_Trade::Event_ResetTrade` | W | H | – | B | Clear pending items |
 | 0x0216 | outbound | ClearPlayerConsentList | `CM_Character::Event_ClearPlayerConsentList` | – | H | – | B | Resurrection consent |
 | 0x0217 | outbound | DisplayPlayerConsentList | `CM_Character::Event_DisplayPlayerConsentList` | – | H | – | B | – |
 | 0x0218 | outbound | RemoveFromPlayerConsentList | `CM_Character::Event_RemoveFromPlayerConsentList` | – | – | – | B | – |
 | 0x0219 | outbound | AddPlayerPermission | `CM_Character::Event_AddPlayerPermission` | W | H | – | B | Storage / consent perm |
 | 0x021A | outbound | RemovePlayerPermission | `CM_Character::Event_RemovePlayerPermission` | W | H | – | B | – |
 | 0x021C | outbound | BuyHouse | `CM_House::Event_BuyHouse` | – | H | – | –defer:Phase Q | Housing — out of M baseline scope |
 | 0x021E | outbound | HouseQuery | – | – | H | – | –defer:Phase Q | Housing |
 | 0x021F | outbound | AbandonHouse | `CM_House::Event_AbandonHouse` | – | H | – | –defer:Phase Q | Housing |
 | 0x0221 | outbound | RentHouse | `CM_House::Event_RentHouse` | – | – | – | –defer:Phase Q | Housing |
 | 0x0224 | outbound | SetDesiredComponentLevel | – | – | – | – | B | Component-buy preference |
 | 0x0245 | outbound | AddPermanentGuest | `CM_House::Event_AddPermanentGuest_Event` | – | H | – | –defer:Phase Q | Housing |
 | 0x0246 | outbound | RemovePermanentGuest | `CM_House::Event_RemovePermanentGuest_Event` | – | H | – | –defer:Phase Q | Housing |
 | 0x0247 | outbound | SetOpenHouseStatus | `CM_House::Event_SetOpenHouseStatus_Event` | – | H | – | –defer:Phase Q | Housing |
 | 0x0249 | outbound | ChangeStoragePermission | `CM_House::Event_ChangeStoragePermission_Event` | – | H | – | –defer:Phase Q | Housing |
 | 0x024A | outbound | BootSpecificHouseGuest | `CM_House::Event_BootSpecificHouseGuest_Event` | – | H | – | –defer:Phase Q | Housing |
 | 0x024C | outbound | RemoveAllStoragePermission | `CM_House::Event_RemoveAllStoragePermission` | – | H | – | –defer:Phase Q | Housing |
 | 0x024D | outbound | RequestFullGuestList | `CM_House::Event_RequestFullGuestList_Event` | – | – | – | –defer:Phase Q | Housing |
 | 0x0254 | outbound | SetMotd | `CM_Allegiance::Event_SetMotd` | – | – | – | B | Allegiance message-of-the-day |
 | 0x0255 | outbound | QueryMotd | `CM_Allegiance::Event_QueryMotd` | – | – | – | B | – |
 | 0x0256 | outbound | ClearMotd | `CM_Allegiance::Event_ClearMotd` | – | H | – | B | – |
 | 0x0258 | outbound | QueryLord | `CM_House::Event_QueryLord` | – | – | – | –defer:Phase Q | Housing |
 | 0x025C | outbound | AddAllStoragePermission | `CM_House::Event_AddAllStoragePermission` | – | – | – | –defer:Phase Q | Housing |
 | 0x025E | outbound | RemoveAllPermanentGuests | `CM_House::Event_RemoveAllPermanentGuests_Event` | – | H | – | –defer:Phase Q | Housing |
 | 0x025F | outbound | BootEveryone | `CM_House::Event_BootEveryone_Event` | – | H | – | –defer:Phase Q | Housing |
 | 0x0262 | outbound | TeleToHouse | `CM_House::Event_TeleToHouse_Event` | – | – | – | –defer:Phase Q | Housing |
 | 0x0263 | outbound | QueryItemMana | `CM_Item::Event_QueryItemMana` | W | H | – | B | Mana-meter check |
 | 0x0266 | outbound | SetHooksVisibility | `CM_House::Event_SetHooksVisibility` | – | H | – | –defer:Phase Q | Housing |
 | 0x0267 | outbound | ModifyAllegianceGuestPermission | `CM_House::Event_ModifyAllegianceGuestPermission` | – | – | – | –defer:Phase Q | Housing |
 | 0x0268 | outbound | ModifyAllegianceStoragePermission | `CM_House::Event_ModifyAllegianceStoragePermission` | – | – | – | –defer:Phase Q | Housing |
 | 0x0269 | outbound | ChessJoin | – | – | H | – | –skip:minigame | Chess |
 | 0x026A | outbound | ChessQuit | – | – | H | – | –skip:minigame | Chess |
 | 0x026B | outbound | ChessMove | – | – | H | – | –skip:minigame | Chess |
 | 0x026D | outbound | ChessMovePass | – | – | H | – | –skip:minigame | Chess |
 | 0x026E | outbound | ChessStalemate | – | – | H | – | –skip:minigame | Chess |
 | 0x0270 | outbound | ListAvailableHouses | `CM_House::Event_ListAvailableHouses` | – | – | – | –defer:Phase Q | Housing |
 | 0x0275 | outbound | ConfirmationResponse | `CM_Character::Event_ConfirmationResponse` | W | H | – | B | Yes/No popups |
 | 0x0277 | outbound | BreakAllegianceBoot | `CM_Allegiance::Event_BreakAllegianceBoot` | – | H | – | B | Officer kick |
 | 0x0278 | outbound | TeleToMansion | `CM_House::Event_TeleToMansion_Event` | W | – | – | –defer:Phase Q | Housing recall |
 | 0x0279 | outbound | Suicide | `CM_Character::Event_Suicide` | W | – | – | B | /suicide cmd |
 | 0x027B | outbound | AllegianceInfoRequest | `CM_Allegiance::Event_AllegianceInfoRequest` | – | H | – | B | Tree info |
 | 0x027D | outbound | CreateTinkeringTool / SalvageItemsWith | `CM_Inventory::Event_CreateTinkeringTool` | W | H | – | B | Salvage UI [^a-6] |
 | 0x0286 | outbound | SpellbookFilter | `CM_Character::Event_SpellbookFilterEvent` | – | – | – | B | School filter |
 | 0x028D | outbound | TeleToMarketPlace | – | W | – | – | B | MP recall |
 | 0x028F | outbound | EnterPkLite | – | W | – | – | B | PK-lite toggle |
 | 0x0290 | outbound | FellowshipAssignNewLeader | `CM_Fellowship::Event_AssignNewLeader` | W | H | – | B | – |
 | 0x0291 | outbound | FellowshipChangeOpenness | `CM_Fellowship::Event_ChangeFellowOpeness` | – | H | – | B | – |
 | 0x02A0 | outbound | AllegianceChatBoot | `CM_Allegiance::Event_AllegianceChatBoot` | – | – | – | B | Officer chat-mute |
 | 0x02A1 | outbound | AddAllegianceBan | `CM_Allegiance::Event_AddAllegianceBan` | – | H | – | B | – |
 | 0x02A2 | outbound | RemoveAllegianceBan | `CM_Allegiance::Event_RemoveAllegianceBan` | – | – | – | B | – |
 | 0x02A3 | outbound | ListAllegianceBans | `CM_Allegiance::Event_ListAllegianceBans` | – | – | – | B | – |
 | 0x02A5 | outbound | RemoveAllegianceOfficer | `CM_Allegiance::Event_RemoveAllegianceOfficer` | – | H | – | B | – |
 | 0x02A6 | outbound | ListAllegianceOfficers | `CM_Allegiance::Event_ListAllegianceOfficers` | – | – | – | B | – |
 | 0x02A7 | outbound | ClearAllegianceOfficers | `CM_Allegiance::Event_ClearAllegianceOfficers` | – | – | – | B | – |
 | 0x02AB | outbound | RecallAllegianceHometown | `CM_Allegiance::Event_RecallAllegianceHometown` | – | – | – | B | Bind to monarch lifestone |
 | 0x02AF | outbound | QueryPluginListResponse | `CM_Admin::Event_QueryPluginListResponse` | – | – | – | –skip:plugin-c2s | Decal-era plugin probe |
 | 0x02B2 | outbound | QueryPluginResponse | `CM_Admin::Event_QueryPluginResponse` | – | – | – | –skip:plugin-c2s | Decal-era plugin probe |
 | 0x0311 | outbound | FinishBarber | `CM_Character::Event_FinishBarber` | – | H | – | B | Char appearance commit |
 | 0x0316 | outbound | AbandonContract | `CM_Social::Event_AbandonContract` | – | H | – | B | Drop quest |
 **Footnotes:**
 [^a-1]: "Builder dead" = the byte-array builder is implemented in `src/AcDream.Core.Net/Messages/<file>.cs` but no caller in `src/AcDream.App/` or a `WorldSession.Send*` wrapper invokes it. Phase M wires these to game-state actions (UI clicks, command bus, key bindings) and adds golden-vector tests against holtburger fixtures.
 [^a-2]: ACE's wire field order for Tell is `message FIRST then target` (see `ChatRequests.BuildTell` doc comment). Sept-2013 PDB has no `Event_Tell` symbol — it routes through `CM_Communication::Event_TalkDirectByName` plus a server-side rename.
 [^a-3]: TeleToPoi (0x00B1) is listed in `InventoryActions.cs` but not in ACE's `GameActionType` enum. Cross-reference holtburger to confirm; may be a dead-letter opcode that retail's vendored 2013 ACE branch dropped. Verify before shipping the test vector.
 [^a-4]: AddChannel (0x0145) — named-retail's matching symbol is `Event_ChannelList` (0x0148 according to retail enum), so the symbol mapping is approximate; AddChannel in pseudo-C may be unsymbolicated. Confirm by greping `acclient_2013_pseudo_c.txt` before publishing.
 [^a-5]: 0x0147 ChannelBroadcast is the same numeric code in both directions (outbound GameAction = client sends to channel; inbound GameEvent = server broadcasts to channel members). Listed under outbound here per Section-5 scope; inbound version is in §4.
 [^a-6]: ACE GameActionType lists 0x027D as `CreateTinkeringTool`; holtburger names the same opcode `SalvageItemsWith`. Both behaviors funnel through the salvage UI in retail. Either name is acceptable in acdream; pick one and leave the other as an alias constant.
 ---
 ## Source attribution
 - **Holtburger** — `references/holtburger/` at `629695a` (2026-05-10). Primary client-behavior oracle.
 - **ACE** — `references/ACE/Source/ACE.Server/Network/`. Server-side authority for GameMessages, GameEvents, GameActions, and accept rules.
 - **Named retail decomp** — `docs/research/named-retail/` (Sept 2013 EoR PDB + Binary Ninja pseudo-C). Wire-format ground truth for the 2013 client.
 - **acdream current state** — `src/AcDream.Core.Net/` and `src/AcDream.App/`. Inventoried by parallel agents on 2026-05-10.
 ## Caveats
 This is the **initial population**, produced by four parallel research agents (one per opcode class) on 2026-05-10. Spot-check pass + intentional-divergence ratification is owed before M.1 closes. Specifically:
 - A handful of named-retail symbol citations are tentative (marked in footnotes); spot-check by greping `acclient_2013_pseudo_c.txt` and `symbols.json`.
 - Holtburger / ACE / acdream cells were determined by reading the actual code (not guessing); when an agent couldn't determine a value, it used `?`. The `?` cells need a follow-up read.
 - "Dead builder" calls (rows where acdream `B` but Phase M target is `B+W`) are based on a grep for `WorldSession.Send*` patterns and `worldSession.Send` calls in `src/AcDream.App/`. Edge cases (call sites in test code, command-bus indirection) may have been missed.
 - Total opcode count in scope (~284) is approximate; deduplication of cross-section codes (e.g., 0x0147 in §4 and §5) is tracked in footnotes but the headline count treats them as distinct rows.
 This matrix lives on as a long-term reference. Phase M.6 implementation tracks progress against it; gameplay phases consuming Phase M will reference the rows they wire as part of their phase acceptance.
--- a/docs/research/2026-05-10-post-a5-polish-handoff.md
+++ b/docs/research/2026-05-10-post-a5-polish-handoff.md
@ -1,307 +0,0 @@
 # Phase Post-A.5 Polish — Cold-Start Handoff
 **Created:** 2026-05-10, immediately after A.5 SHIP + merge to main (`d3d78fa`).
 **Audience:** the next agent picking up post-A.5 polish work.
 **Purpose:** give you everything you need to start the polish phase cold, without spelunking through the A.5 session's 200+ messages.
 ---
 ## TL;DR
 A.5 just shipped. Two-tier streaming is live (N₁=4 near, N₂=12 far) with a 2.3 km fog horizon, off-thread mesh build, entity dispatcher tightening, mipmaps + 16x AF, MSAA 4x + A2C foliage, depth-write audit, BUDGET_OVER diag, and a full Quality Preset system (Low/Medium/High/Ultra) with env-var overrides + F11 mid-session re-apply.
 **A.5 was an enormous phase** (29 numbered tasks + T22.5 mid-execution scope add + Bug A + Bug B post-T26 fixes). Spec at `docs/superpowers/specs/2026-05-09-phase-a5-two-tier-streaming-design.md` (~700 lines). Plan at `docs/superpowers/plans/2026-05-09-phase-a5-two-tier-streaming.md` (~2400 lines).
 **Three things were intentionally deferred to this phase:**
 1. **Lifestone visual missing (ISSUE #52).** The Holtburg lifestone — a known visual landmark — hasn't been rendering since earlier in A.5 development. User confirmed they noticed it earlier but didn't flag it; deferred to post-ship. **Highest user-perception value to fix.**
 2. **JobKind plumbing through `BuildLandblockForStreaming` (ISSUE #54).** Bug A's fix patches at the worker output by stripping entities from far-tier `LoadedLandblock`s after the full load runs. The worker still wastes CPU on hydration + scenery generation that gets thrown away. Cleaner fix: make the worker SKIP that work for far-tier loads. ~30 min - 1 hour. **Smallest cleanup, biggest worker-thread efficiency win.**
 3. **Tier 1 entity-classification cache retry (ISSUE #53).** First attempt (commit `3639a6f`, reverted at `9b49009`) cached `meshRef.PartTransform` which is mutated per frame for animated entities — froze animations. Retry needs a careful read of `AnimationSequencer` + `AnimationHookRouter` first to map ALL the per-frame mutations of MeshRef state, then design a cache that bypasses animated entities OR caches only the animation-invariant subset. **Biggest perf headroom available** — math says it should drop the entity dispatcher from 3.5ms to 1-1.5ms, hitting the spec's 2.0ms budget.
 The phase is sized ~1 week if all three land cleanly. Could be longer if Tier 1's animation audit reveals something subtle.
 ---
 ## Where A.5 left things
 ### Branch state
 - `main` is at `d3d78fa` ("Merge branch 'claude/hopeful-darwin-ae8b87' — Phase A.5 SHIP + Quality Preset system").
 - A.5 SHIP commit at `9245db5` (one commit before the merge bubble).
 - Roadmap entry: A.5 moved from "Phases ahead" → "Phases already shipped" table.
 - CLAUDE.md "Currently in flight" updated to "Post-A.5 polish — Tier 1 retry + lifestone fix + JobKind plumbing".
 ### What works in A.5 (final post-fix state)
 - **Two-tier streaming end-to-end:** `StreamingRegion` with `RecenterTo` returning a 5-list `TwoTierDiff` (ToLoadFar/ToLoadNear/ToPromote/ToDemote/ToUnload) with hysteresis radius+2 on both tiers; `StreamingController.Tick` routes by `LandblockStreamJobKind`; `LandblockStreamer` worker thread does dat reads + mesh build off the render thread.
 - **Bug A fixed:** `LandblockStreamer.HandleJob` strips entities for `LoadFar` results before posting Loaded. Far-tier ships terrain only as the spec promised.
 - **Bug B fixed:** `WalkEntities` uses `_walkScratch` field reused across frames, no per-frame List allocation.
 - **Quality Preset system:** Low / Medium / High / Ultra presets with per-preset radii + MSAA + anisotropic + A2C + max-completions. 6 env-var overrides per field. F11 → Display tab dropdown for mid-session change. `DisplaySettings.Quality` persists in settings.json. `GameWindow.ReapplyQualityPreset` rebuilds the streaming pipeline for radius changes.
 - **Visual quality stack:** mipmaps + 16x anisotropic on TerrainAtlas. MSAA 4x + alpha-to-coverage on foliage shader. Depth-write audit + lock-in test (5 cases).
 - **Fog horizon:** FogStart = N₁ × 192m × 0.7 ≈ 538m. FogEnd = N₂ × 192m × 0.95 ≈ 2188m. Tunable via `ACDREAM_FOG_START_MULT` / `ACDREAM_FOG_END_MULT`.
 - **DIAG:** `[WB-DIAG]` and `[TERRAIN-DIAG]` flag `BUDGET_OVER` when median exceeds the per-subsystem spec budget (entity 2.0ms, terrain 1.0ms).
 ### Final perf state at A.5 SHIP (horizon-safe Quality preset)
 User hardware: AMD Radeon RX 9070 XT, 240 Hz @ 2560×1440.
 Settings tested: `NEAR_RADIUS=4, FAR_RADIUS=12, MSAA=0, A2C=0, ANISOTROPIC=4, MAX_COMPLETIONS=2`.
 | Subsystem | cpu_us median | cpu_us p95 |
 |---|---|---|
 | Entity dispatcher | ~3500 µs (3.5 ms) | ~4000 µs |
 | Terrain dispatcher | ~21 µs | ~26 µs |
 Total frame time math: ~4-5 ms = ~200-240 FPS at standstill. User reported "Better now" — not the 240Hz spec target but a 5× improvement from the broken pre-Bug-A state (~40 FPS).
 The 1.5ms gap to the 2.0ms entity dispatcher budget is what Tier 1 closes (per ISSUE #53 + the perf-tier roadmap).
 ### What was NOT validated at SHIP
 - **Full High preset (radius=4/12, MSAA 4x, A2C on, anisotropic 16x).** Crashed the entire OS at first attempt earlier in A.5 development. Bug A was likely the trigger (CPU dispatcher saturating + GPU command queue overflowing). With Bug A fixed, this likely works — but never re-tested. **Re-testing is part of this phase's stretch goal.**
 - **Visual gate at full quality.** Same — only validated at horizon-safe settings.
 - **Walking trace at any preset.** Brief walking observed but not metric-captured.
 ### Three high-value gotchas captured in A.5 memory
 These are at `~/.claude/projects/.../memory/project_phase_a5_state.md`:
 1. **Worker-side JobKind routing was the load-bearing far-tier optimization.** T13/T16 wired the controller side; the worker never branched on Kind. ~5x perf regression that wasn't caught by spec/code reviews.
 2. **WalkEntities's "extract a list-producing helper" pattern is a perf antipattern.** ~480 KB / frame allocation. Implementer flagged "future N.6 optimization" in self-review; review should have caught that "future" was actually "now."
 3. **Caching mutable per-frame state silently breaks animation.** Tier 1's first attempt. The "trust MeshRefs as the source of truth" comment in the dispatcher is true but misleading — MeshRefs IS the source of truth, but it's mutated EVERY frame for animated entities.
 (Full memory entry has 5 gotchas; these three are the load-bearing ones for post-A.5.)
 ---
 ## Files to read before brainstorming
 In rough order:
 1. **`docs/superpowers/specs/2026-05-09-phase-a5-two-tier-streaming-design.md`** — A.5 spec, full design rationale + Quality Preset system (§4.10) + acceptance criteria reshape (§2). Skim for vocabulary; read §4.10 in full.
 2. **`docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md`** — Tier 2 (static/dynamic split) + Tier 3 (GPU compute culling) roadmap. Read for context on where Tier 1 fits in the perf optimization tower.
 3. **`docs/ISSUES.md` issues #52, #53, #54** — the three deferred items in tactical-list form.
 4. **`memory/project_phase_a5_state.md`** — the 5 gotchas. Critical for avoiding the same traps in this phase.
 5. **`src/AcDream.App/Streaming/LandblockStreamer.cs`** — `HandleJob` is where Bug A's patch lives + where ISSUE #54's cleaner fix will go.
 6. **`src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs`** — `WalkEntities` + `Draw`'s inner loop. Where Tier 1's retry will operate.
 7. **`src/AcDream.Core/Physics/AnimationSequencer.cs`** — the per-frame animation engine. Read this BEFORE designing Tier 1's retry. Pay specific attention to anywhere it touches `meshRef.PartTransform` or any other field that the dispatcher reads.
 8. **`src/AcDream.App/Animation/AnimationHookRouter.cs`** (or similar) — the hook fan-out from animation events. Same audit reason as #7.
 ---
 ## Per-priority detail
 ### Priority 1 — Lifestone missing (ISSUE #52)
 **Estimated effort:** 1-3 hours. Could be a 1-line fix or could surface a deeper issue.
 The Holtburg lifestone is a Setup-multi-part entity (the spinning blue crystal pillar). User reports it hasn't been rendering since earlier in A.5 development. They noticed but didn't flag during the session.
 Hypotheses:
 - **Bug A's strip caught a near-tier entity.** The current strip in `LandblockStreamer.HandleJob` only fires when `tier == LandblockStreamTier.Far`. Holtburg's lifestone is in a near-tier LB (Holtburg's center, ~LB 0xA9B4). Should NOT have been stripped. But verify — maybe the LB's tier resolution at first-tick is wrong.
 - **Earlier visual regression from a different commit.** User said it was missing in earlier runs too. Could be from N.5b, an N.5b follow-up, or even older. Requires a `git log -- docs/ISSUES.md` correlation with visible state.
 - **Setup-rendering edge case.** The lifestone has unusual properties (animated rotation, particle effects on top). Maybe it's a Setup with some sub-mesh that the dispatcher's `SetupParts` walk filters out.
 - **Dat-state mismatch.** The lifestone's GfxObj id might be in a part of the dat that's failing decode.
 **Investigation steps:**
 1. Launch the client + walk to Holtburg lifestone position.
 2. Check `[WB-DIAG]` for `meshMissing` count — if non-zero, some entity's mesh isn't loading.
 3. Use the cdb attach toolchain (per CLAUDE.md "Retail debugger toolchain") if needed to compare vs retail's lifestone rendering.
 4. Compare to ACViewer / WorldBuilder to see if the lifestone renders there. If yes, our renderer has a regression. If no, the issue is dat-side or in shared decode logic.
 5. Identify the GfxObj/Setup id for the lifestone (likely well-known retail ID; check `docs/research/named-retail/` or ACViewer reference).
 6. Trace: does `_meshAdapter.TryGetRenderData(lifestoneId)` return non-null? Does the resulting `renderData.Batches` have entries?
 **Acceptance:** lifestone renders correctly (visible spinning blue crystal at the Holtburg town center).
 ### Priority 2 — JobKind plumbing through `BuildLandblockForStreaming` (ISSUE #54)
 **Estimated effort:** 30 min - 1 hour.
 Currently `LandblockStreamer.HandleJob` strips entities POST-load for far-tier:
 ```csharp
 case LandblockStreamJob.Load load:
    var lb = _loadLandblock(load.LandblockId);  // full load
    var mesh = _buildMeshOrNull(load.LandblockId, lb);
    var tier = load.Kind == LandblockStreamJobKind.LoadFar ? Far : Near;
    if (tier == LandblockStreamTier.Far && lb.Entities.Count > 0)
    {
        // Strip entities — far-tier ships terrain only.
        lb = new LoadedLandblock(...empty entities...);
    }
    _outbox.Writer.TryWrite(new Loaded(... lb, mesh ...));
    break;
 ```
 The full `_loadLandblock` does:
 1. Read `LandBlock` heightmap (cheap).
 2. Read `LandBlockInfo` (medium).
 3. `LandblockLoader.BuildEntitiesFromInfo` (extract stabs/buildings).
 4. Hydrate stab/building meshRefs (medium).
 5. Run scenery generation (heavy — ~50-200 procedural entities × meshRef hydration).
 6. Build interior cell entities.
 For far-tier, only step 1 is needed. Steps 2-6 are wasted CPU on the worker thread.
 **Refactor plan:**
 1. Change the streamer's `_loadLandblock` factory to take `LandblockStreamJobKind`:
   ```csharp
   private readonly Func<uint, LandblockStreamJobKind, LoadedLandblock?> _loadLandblock;
   ```
 2. In `GameWindow`, the factory closure branches:
   ```csharp
   loadLandblock: (id, kind) => kind == LandblockStreamJobKind.LoadFar
       ? BuildLandblockHeightmapOnly(id)
       : BuildLandblockForStreaming(id),
   ```
 3. New `BuildLandblockHeightmapOnly` returns a `LoadedLandblock` with the heightmap dat record + empty entity list. Cheap — no LandBlockInfo read, no scenery generation.
 4. Remove the post-load strip in `HandleJob` (no longer needed).
 5. Worker-thread CPU drops measurably; horizon fill on first traversal speeds up.
 **Acceptance:**
 - Build green; existing 999+ tests pass.
 - Streaming worker thread is measurably faster on first-traversal (the user can validate with `[WB-DIAG]` worker queue depth or just feel the responsiveness when walking into virgin region).
 - Visible behavior unchanged — far tier looks the same as before.
 ### Priority 3 — Tier 1 entity-classification cache retry (ISSUE #53)
 **Estimated effort:** ~5-7 days. Substantial because the audit step is critical.
 This is the BIG perf win remaining for A.5's CPU dispatcher. Math says entity dispatcher 3.5ms → 1-1.5ms = ~300-400 FPS at standstill. Drops the dispatcher inside the spec's 2.0ms budget.
 **The first attempt's failure (commit 3639a6f, reverted at 9b49009):**
 Cached `meshRef.PartTransform` baked into per-(entity, batch) classification at first-frame visit. For static entities, this is stable forever. For animated entities, `meshRef.PartTransform` is updated EVERY FRAME by `AnimationSequencer` to apply the current skeletal pose. The cache froze the pose.
 User-visible symptoms:
 - NPCs / players stop animating.
 - Some buildings (likely those mistakenly in `animatedEntityIds`) draw at wrong positions.
 **The retry's audit step (do this BEFORE designing the cache):**
 Read `src/AcDream.Core/Physics/AnimationSequencer.cs` and trace EVERY assignment to `meshRef.PartTransform` (and any other field on `MeshRef`, `WorldEntity`, or related state that the dispatcher reads). Likely write sites:
 - `AnimationSequencer.TickAnimations` per-frame skeletal pose update
 - `AnimationHookRouter` for hooks like `AnimSetPose`
 - Live network handlers that mutate `entity.Position` / `entity.Rotation` (T18 already migrated these to `SetPosition` for AABB invalidation; double-check)
 - `EntitySpawnAdapter` for ObjDescEvent / palette swap
 For each write site, decide: is this entity STATIC (write only at spawn) or DYNAMIC (write per-frame or in response to network events)?
 **Cache design options after the audit:**
 (a) **Static-only cache.** Only cache entities where `animatedEntityIds.Contains(entity.Id) == false`. Animated entities use today's per-frame classification path. Cleanest, but requires `animatedEntityIds` to be a stable signal (it is — `_animatedEntities` dict in GameWindow is the source).
 (b) **Dynamic-aware cache with invalidation hooks.** Cache everything but expose `InvalidateEntity(uint)` / `RefreshEntityPalette(uint)` for the dispatcher's invalidation. Wire from the network layer (palette swap fires invalidation; ObjDesc event fires invalidation). More complex but might let animated entities also benefit.
 (c) **Static-only + animated-bypass + diagnostic check.** Like (a), but in DEBUG builds, log a warning every frame if a cached entity's `meshRef.PartTransform` differs from the cached value (catches mis-classified dynamics). Belt-and-suspenders.
 Recommendation: start with (a). Ship Tier 1 for static entities only. Animated path stays slow but correct. If perf gate finds the static-only Tier 1 isn't enough, escalate to (c) for safety + (b) later.
 **Acceptance:**
 - Build green; existing 999+ tests pass.
 - 1-3 new tests covering: cache hit for static entity, cache bypass for animated entity, cache invalidation on entity remove.
 - Visual gate: launch + walk Holtburg → North Yanshi at horizon-safe preset; confirm:
  - Animation works (NPCs, player character animate normally)
  - Buildings at correct positions
  - Lifestone (still depending on Priority 1 fix) renders correctly
  - No new visual regressions
 - Perf gate (with `[WB-DIAG]`):
  - Entity dispatcher cpu_us median drops from ~3.5ms to ≤2.0ms (matches spec budget).
  - p95 stays ≤ 2.5ms.
 ---
 ## What's NOT in this phase
 - **Tier 2 (static/dynamic split with persistent groups).** Separate ~2-week phase. See `docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md`.
 - **Tier 3 (GPU compute culling).** Separate ~1-month phase. Same roadmap.
 - **Full High preset crash investigation beyond casual retest.** Stretch goal: re-test the High preset with Bug A + B fixed, see if it's stable now. If it crashes, file a new issue and continue. Don't deep-dive in this phase.
 - **EnvCell modern path migration, Sky/Particles modern path, Shadow mapping** — all later phases.
 - **N.6 perf polish (the previously-flagged "next phase").** N.6 was the original CLAUDE.md "Currently in flight" target before A.5. Most of N.6's scope was rolled into A.5 (perf-tier work). What's left of N.6 (persistent-mapped indirect buffer, GPU-side culling) overlaps with Tier 2/3 and should be re-scoped after Tier 1 lands.
 ---
 ## Acceptance criteria (whole phase)
 - All three priorities (Lifestone, JobKind, Tier 1) shipped or one is explicitly deferred with documented reasoning.
 - Build green throughout. ~999+ tests pass; 8 pre-existing physics/input failures stay at 8.
 - N.5b conformance sentinel intact (TerrainSlot, TerrainModernConformance, Wb*, MatrixComposition, TextureCacheBindless, SplitFormulaDivergence — all clean).
 - Visual gate: lifestone renders; animation works; horizon visible at ~2.3km; smooth walking trace; no new artifacts.
 - Perf gate (post-Tier-1): entity dispatcher cpu_us median ≤ 2.0ms at horizon-safe preset, ~250-300 FPS at standstill.
 - Memory entry written + roadmap "shipped" row updated for the polish phase.
 ---
 ## What you'll be doing in the first 30 minutes
 1. Read this handoff in full.
 2. Verify build green: `dotnet build`. Verify ~999 tests pass: `dotnet test --no-build`.
 3. Read `docs/superpowers/specs/2026-05-09-phase-a5-two-tier-streaming-design.md` §2, §4.10, §11 (deferred section).
 4. Read `docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md` Tier 1 section.
 5. Read `docs/ISSUES.md` issues #52, #53, #54 in full.
 6. Read `memory/project_phase_a5_state.md` (5 gotchas).
 7. Read `src/AcDream.App/Streaming/LandblockStreamer.cs` HandleJob method.
 8. Read `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs` Draw + WalkEntitiesInto methods.
 9. Skim `src/AcDream.Core/Physics/AnimationSequencer.cs` for write-sites of `meshRef.PartTransform` (Tier 1 retry's audit prerequisite).
 10. Decide: which priority to start with? Recommendation order: 1 (lifestone, fast win), 2 (JobKind, easy cleanup), 3 (Tier 1, biggest perf win + most complex).
 11. Brainstorm with the user on the chosen priority before writing code.
 12. Write a small spec or just the implementation if the priority is small (1 + 2 are small enough to skip a formal spec). Tier 1 (priority 3) needs a spec because of the audit + invalidation design.
 Don't skip the audit step on Tier 1. The first attempt failed because of an incomplete read of the animation mutation graph; the second attempt should not repeat that.
 ---
 ## Things to NOT do
 - **Don't rush Tier 1.** Audit first. Write down which entities are static vs dynamic. Write tests that specifically verify animated entities still animate after caching is enabled.
 - **Don't bundle Tier 2 or Tier 3 into this phase.** Those are dedicated multi-week phases with their own brainstorm + spec + plan cycles.
 - **Don't break the N.5b conformance sentinel.** Run the filter on every commit:
  ```
  dotnet test --no-build --filter "FullyQualifiedName~TerrainSlot|FullyQualifiedName~TerrainModernConformance|FullyQualifiedName~Wb|FullyQualifiedName~MatrixComposition|FullyQualifiedName~TextureCacheBindless|FullyQualifiedName~SplitFormulaDivergence"
  ```
  Expect 89+ passing, 0 failures.
 - **Don't skip the visual gate.** Lifestone fix specifically requires looking at the lifestone in-game. Tier 1 retry requires confirming animation works on a moving NPC.
 - **Don't delete the `_walkScratch` field** added in Bug B fix. It's load-bearing — without it, Tier 1 retry would re-introduce the per-frame allocation bug.
 - **Don't re-add the `Tier1` cache that was reverted.** Start the retry with a fresh design after the animation audit. Cherry-picking the reverted code will re-introduce the bug.
 ---
 ## Reference: A.5's commit chain
 Final A.5 commit chain on `claude/hopeful-darwin-ae8b87` (merged into main at `d3d78fa`):
 | SHA | Subject |
 |---|---|
 | 9245db5 | phase(A.5): SHIP — two-tier streaming + horizon LOD + Quality Preset system |
 | d93d823 | docs(A.5 T27): roadmap + ISSUES + CLAUDE.md updates for A.5 ship |
 | a28a5b7 | docs(A.5 T27): spec + plan amendments for T22.5 + ship |
 | 9b49009 | Revert "feat(perf): Tier 1 entity classification cache" |
 | 3639a6f | feat(perf): Tier 1 entity classification cache (REVERTED) |
 | 462f9d6 | docs(perf): roadmap for Tier 2 + Tier 3 entity-dispatcher optimizations |
 | 0ad8c99 | fix(A.5): WalkEntities scratch-list pattern (Bug B — T17 GC pressure) |
 | 9217fd9 | fix(A.5): strip far-tier entities in worker (Bug A — far tier optimization) |
 | 28d2c60 | feat(A.5 T22.5): wire QualityPreset into renderer + streaming (commit 2/2) |
 | afa4200 | feat(A.5 T22.5): QualityPreset schema + tests (commit 1/2) |
 | c473fee | feat(A.5 T23): BUDGET_OVER flag in [WB-DIAG] / [TERRAIN-DIAG] |
 | 3b684db | feat(A.5 T22): fog wired from N₁/N₂ + ACDREAM_FOG_*_MULT env vars |
 | 1488ec6 | test(A.5 T21): lock in depth-write attribution per translucency kind |
 | 26b2871 | feat(A.5 T20): MSAA 4x + alpha-to-coverage on foliage |
 | 4b84e56 | feat(A.5 T19): mipmaps + 16x anisotropic on TerrainAtlas |
 | (...60+ commits earlier in the chain through T1-T18) | (see full log on the merge bubble) |
 The merge bubble preserves the full chain. To inspect any A.5 commit:
 ```
 git log d3d78fa^..d3d78fa
 git show <sha>
 ```
 ---
 Good luck. The phase is well-bounded; the audit step on Tier 1 is the single highest-leverage thing to invest in. The lifestone and JobKind cleanup should be quick wins. After this phase ships, the project is in a great position — A.5 + polish + Tier 2/3 roadmap covers the rendering + perf work for the next several months.
 Holler at the user if any of the three priorities reveals scope you didn't expect.
--- a/docs/research/2026-05-10-tier1-mutation-audit.md
+++ b/docs/research/2026-05-10-tier1-mutation-audit.md
@ -1,246 +0,0 @@
 # Tier 1 entity-classification cache — mutation audit
 **Created:** 2026-05-10, opening move of the ISSUE #53 retry session.
 **Purpose:** enumerate every code path that writes to `WorldEntity.MeshRefs` (the dispatcher's load-bearing per-entity input) and every adjacent state read by `WbDrawDispatcher.ClassifyBatches` / model-matrix composition, classify each as STATIC or DYNAMIC, and design the cache invalidation surface BEFORE touching renderer code.
 This audit is the load-bearing prerequisite the prior Tier 1 attempt (commit `3639a6f`, reverted at `9b49009`) skipped. Cache design follows from the audit, not the other way around.
 ---
 ## TL;DR — the invariant
 > **An entity's `MeshRefs` reference, `Position`, `Rotation`, `PaletteOverride`, `HiddenPartsMask`, `ParentCellId`, and `Scale` are stable from spawn to despawn IF AND ONLY IF the entity is NOT in `GameWindow._animatedEntities`.**
 That is the invariant the cache rides on. Animated entities (player + remote NPCs/players + animated dat scenery like the lifestone crystal) get a fresh `MeshRefs` list every frame from `TickAnimations` plus per-frame `Position`/`Rotation` writes from physics/dead-reckoning. Everything else — stabs, scenery, cell-mesh entities, interior static objects — touches none of those fields after construction.
 The cache should hold per-entity classification ONLY for entities whose `Id` is not in `_animatedEntities` at lookup time. Animated entities go through today's per-frame classification path unchanged.
 ---
 ## §1. `entity.MeshRefs = ...` write sites (the core question)
 `WorldEntity.MeshRefs` is `IReadOnlyList<MeshRef>` with a `set` accessor (see [src/AcDream.Core/World/WorldEntity.cs:28](../../src/AcDream.Core/World/WorldEntity.cs#L28)). `MeshRef` itself is a `readonly record struct` ([src/AcDream.Core/World/MeshRef.cs:15](../../src/AcDream.Core/World/MeshRef.cs#L15)) — its fields cannot be mutated in place. So every "MeshRefs change" is a whole-list replacement, not a per-element edit.
 Six write sites total in `src/`. Five STATIC, one DYNAMIC.
 ### Site 1 — `OnLiveEntitySpawnedLocked` (server-spawned entity hydration)
 **[src/AcDream.App/Rendering/GameWindow.cs:2578](../../src/AcDream.App/Rendering/GameWindow.cs#L2578)** — `MeshRefs = meshRefs` in the `WorldEntity { … }` constructor.
 **Classification:** **STATIC** at first spawn.
 **Trigger:** server's `0xF745 CreateObject` for any entity (NPC, monster, player, item, statue, lifestone). Also re-runs from `OnLiveAppearanceUpdated` (server's `0xF625 ObjDescEvent`) → spawn dedup at top of `OnLiveEntitySpawnedLocked` invokes `RemoveLiveEntityByServerGuid`, then re-spawns. Each invocation gets a NEW local `entity.Id` from `_liveEntityIdCounter++` (line 2573).
 **Implication for cache:** ObjDescEvent isn't a "mutate existing entity" event — it's a despawn+respawn pair. The despawn path (next subsection) clears the cache for the old Id; the respawn populates fresh under the new Id. The cache never sees a stale entry for a still-active Id from this path.
 **Pre-construction `parts[…]` mutations** at lines 2333 and 2365 (AnimPartChanges + DIDDegrade resolver) edit the *local* `parts` list before it becomes the `meshRefs` argument; they're not separate write sites.
 ### Site 2 — `BuildLandblockForStreaming` (stab hydration)
 **[src/AcDream.App/Rendering/GameWindow.cs:4748](../../src/AcDream.App/Rendering/GameWindow.cs#L4748)** — `MeshRefs = meshRefs` constructing dat-stab entities.
 **Classification:** **STATIC** at hydration. Worker-thread only.
 **Trigger:** streaming worker's near-tier load path (`LandblockStreamJobKind.LoadNear` or `PromoteToNear`). Single-GfxObj stabs use `Matrix4x4.Identity`; multi-part Setups go through `SetupMesh.Flatten` to produce per-part MeshRefs.
 **Lifetime:** lives until the entity's owning landblock is demoted (Near→Far) or unloaded — see Site invalidation §3.2.
 ### Site 3 — `BuildSceneryEntitiesForStreaming` (procedural scenery)
 **[src/AcDream.App/Rendering/GameWindow.cs:4951](../../src/AcDream.App/Rendering/GameWindow.cs#L4951)** — `MeshRefs = meshRefs` for trees / rocks / bushes / fences.
 **Classification:** **STATIC** at hydration. Worker-thread only.
 **Lifetime:** identical to Site 2.
 ### Site 4 — Interior cell-mesh entity
 **[src/AcDream.App/Rendering/GameWindow.cs:5023](../../src/AcDream.App/Rendering/GameWindow.cs#L5023)** — `MeshRefs = new[] { cellMeshRef }` for the EnvCell's own room geometry as a renderable entity.
 **Classification:** **STATIC** at hydration.
 ### Site 5 — Interior static-object entity
 **[src/AcDream.App/Rendering/GameWindow.cs:5083](../../src/AcDream.App/Rendering/GameWindow.cs#L5083)** — `MeshRefs = meshRefs` for static objects placed inside an EnvCell (furniture, fixtures).
 **Classification:** **STATIC** at hydration.
 ### Site 6 — `TickAnimations` per-frame rebuild
 **[src/AcDream.App/Rendering/GameWindow.cs:7580](../../src/AcDream.App/Rendering/GameWindow.cs#L7580)** — `ae.Entity.MeshRefs = newMeshRefs;` after constructing a fresh `List<MeshRef>(partCount)` at line 7501 from `sequencer.Advance(dt)` output.
 **Classification:** **DYNAMIC** every frame.
 **Trigger:** per-frame iteration over `_animatedEntities.Values` inside `TickAnimations`. If `entity.Id ∈ _animatedEntities`, this loop runs for that entity every frame (subject to motion-table presence). If `entity.Id ∉ _animatedEntities`, this loop never runs for it.
 **Consequence:** any cache that captures `entity.MeshRefs[i].PartTransform` for an entity in `_animatedEntities` will freeze the pose. **This is exactly what the prior Tier 1 attempt did.**
 ---
 ## §2. `_animatedEntities` membership transitions
 `_animatedEntities` at [GameWindow.cs:160](../../src/AcDream.App/Rendering/GameWindow.cs#L160) is the gating dict. The cache's "static" predicate is `! _animatedEntities.ContainsKey(entity.Id)`.
 ### Population
 - **[GameWindow.cs:2724](../../src/AcDream.App/Rendering/GameWindow.cs#L2724)** — `_animatedEntities[entity.Id] = new AnimatedEntity { … }` at server-spawn for entities with a non-empty motion table + a resolvable idle cycle.
 - **[GameWindow.cs:7685](../../src/AcDream.App/Rendering/GameWindow.cs#L7685)** — `_animatedEntities[pe.Id] = ae;` in `UpdatePlayerAnimation` to *re-add* the local player entity if a prior `UpdateMotion` removed it (the "Phase 6.8 stationary remove" pattern). This is the only path that can flip an entity from STATIC to ANIMATED mid-life.
 ### Removal
 - **[GameWindow.cs:2935](../../src/AcDream.App/Rendering/GameWindow.cs#L2935)** — `_animatedEntities.Remove(existingEntity.Id)` inside `RemoveLiveEntityByServerGuid`. Fires for `0xF747 DeleteObject` and as the dedup leg of `OnLiveAppearanceUpdated`.
 ### Cache implication
 Membership IS NOT cached by the dispatcher. The cache lookup checks `_animatedEntities.ContainsKey(entity.Id)` at lookup time. If the player flips STATIC→ANIMATED mid-session (Site 7685 above), a stale cache entry would still exist for the player Id but never be read; the next despawn (Site 2935) clears it. No special-casing needed.
 The reverse flip (ANIMATED→STATIC, e.g. a ground-state demote) leaves no cache entry; the dispatcher takes the cache-miss path on the first frame and populates fresh. Also no special-casing needed.
 ---
 ## §3. Position / Rotation write sites (matters for the cached model matrix)
 The dispatcher composes `model = meshRef.PartTransform * entityWorld` for non-Setup entities, and `model = restPose * meshRef.PartTransform * entityWorld` for Setup multi-parts (with `entityWorld = Rotation × Translation`). If `Position` or `Rotation` changes for a STATIC entity, a cached model matrix would be stale.
 Audit shows: **every Position/Rotation write site in `GameWindow.cs` operates on entities that are in `_animatedEntities`.** Static entities never have these fields touched after construction.
 | Line | Context | Animated? |
 |---|---|---|
 | 3992-3993 | `entity.SetPosition(worldPos); entity.Rotation = rot;` (player physics snap-on-arrival) | YES — `entity` is the local player |
 | 4116 | `entity.SetPosition(rmState.Body.Position);` (remote dead-reckon snap branch) | YES — remote NPC/player |
 | 4230 | same context, near-enqueue branch | YES |
 | 4362-4363 | remote dead-reckon physics tick body sync | YES |
 | 4407-4408 | local player position snap (teleport / GoHome) | YES |
 | 7045-7046 | `ae.Entity.SetPosition(rm.Body.Position); ae.Entity.Rotation = rm.Body.Orientation;` (TickAnimations body sync) | YES — `ae.Entity` is in `_animatedEntities` by definition |
 | 7373-7374 | same body-sync context, fall-through path | YES |
 No Position/Rotation writes happen on entities that are NOT in `_animatedEntities`. Confirmed via grep.
 ---
 ## §4. Other entity fields read by the dispatcher
 `WbDrawDispatcher.Draw` and `ClassifyBatches` read these `WorldEntity` fields beyond `MeshRefs`, `Position`, `Rotation`:
 | Field | Mutability | Cache impact |
 |---|---|---|
 | `PaletteOverride` | `init`-only ([WorldEntity.cs:37](../../src/AcDream.Core/World/WorldEntity.cs#L37)) | Stable post-spawn → safe to fold into cache key / texHandle resolution |
 | `HiddenPartsMask` | `init`-only ([WorldEntity.cs:73](../../src/AcDream.Core/World/WorldEntity.cs#L73)) | Stable; doesn't apply to dispatcher anyway (animation tick handles part-hide via `s_hidePartIndex` debug global, animated path only) |
 | `ParentCellId` | `init`-only ([WorldEntity.cs:45](../../src/AcDream.Core/World/WorldEntity.cs#L45)) | Stable; visibility filter input |
 | `AabbMin/AabbMax/AabbDirty` | Mutated lazily by `RefreshAabb` ([WorldEntity.cs:79-91](../../src/AcDream.Core/World/WorldEntity.cs#L79)) on `AabbDirty` flag, set by `SetPosition` | Read by `WalkEntitiesInto`, NOT used by classification. AABB stays static for static entities (Position never changes → never marked dirty after first refresh) |
 | `MeshRefs[i].SurfaceOverrides` | `init`-only on the MeshRef record struct | Stable for the lifetime of the MeshRef list (Sites 1-5) |
 | `MeshRefs[i].GfxObjId` | Stable (`readonly record struct`) | Forms part of the cache key |
 | `MeshRefs[i].PartTransform` | Stable for STATIC entities (the list is replaced atomically in Site 6 only for ANIMATED entities) | Cacheable for STATIC entities |
 No hidden mutability surface. The cache is safe for entities outside `_animatedEntities`.
 ---
 ## §5. Cache invalidation events (the wire-up)
 The cache is keyed by `entity.Id`. Only TWO event sources can invalidate a cached entry:
 ### §5.1 Per-entity despawn (live server entities)
 **[GameWindow.cs:2933-2935](../../src/AcDream.App/Rendering/GameWindow.cs#L2933)** — `_worldState.RemoveEntityByServerGuid(serverGuid); _worldGameState.RemoveById(...); _animatedEntities.Remove(...);`
 This block fires for:
 - `0xF747 DeleteObject` (server explicitly says entity is gone).
 - `0xF625 ObjDescEvent` (dedup leg before respawn).
 **Hook:** add `_wbDrawDispatcher.InvalidateEntity(existingEntity.Id)` to this block.
 ### §5.2 Landblock demote / unload (static dat entities)
 **[src/AcDream.App/Streaming/GpuWorldState.cs:373](../../src/AcDream.App/Streaming/GpuWorldState.cs#L373)** — `RemoveEntitiesFromLandblock(landblockId)` clears the entity list for a landblock. Called from `StreamingController.Tick` at [StreamingController.cs:116](../../src/AcDream.App/Streaming/StreamingController.cs#L116) for `ToDemote` (Near→Far) and via `_enqueueUnload` for `ToUnload`.
 **Hook:** add `_wbDrawDispatcher.InvalidateLandblock(landblockId)` adjacent to the `RemoveEntitiesFromLandblock` call. Walk the LB's pre-removal entity list; invalidate each Id.
 Implementation note: `RemoveEntitiesFromLandblock` already has the entity list in scope before zeroing it — adding the invalidation walk inside the method (or via a callback) is cheap. Alternative: `StreamingController` walks the LB's entries before invoking `RemoveEntitiesFromLandblock`. Either works; brainstorming will pick.
 ### §5.3 No other invalidation paths needed
 Confirmed:
 - `MarkPersistent` ([GameWindow.cs:2024](../../src/AcDream.App/Rendering/GameWindow.cs#L2024)) — keeps player Id pinned across LB unloads. No MeshRefs change.
 - `DrainRescued` ([GameWindow.cs:5885](../../src/AcDream.App/Rendering/GameWindow.cs#L5885)) — re-attaches rescued persistent entities. No MeshRefs change.
 - `RelocateEntity` ([GameWindow.cs:6026](../../src/AcDream.App/Rendering/GameWindow.cs#L6026)) — moves entity between landblocks. Doesn't change MeshRefs/Position/Rotation. Safe.
 - `AddEntitiesToExistingLandblock` ([GpuWorldState.cs:401](../../src/AcDream.App/Streaming/GpuWorldState.cs#L401)) — Far→Near promotion adds entities. New entries get cache-miss naturally.
 `AnimationSequencer` ([src/AcDream.Core/Physics/AnimationSequencer.cs](../../src/AcDream.Core/Physics/AnimationSequencer.cs)) does NOT write to `entity.MeshRefs` or `entity.Position`/`entity.Rotation` directly. It produces `PartTransform[]` frames consumed by `TickAnimations`. Confirmed via grep — only docstring mention of `MeshRef`. Sequencer is safe to ignore for cache design.
 `Core` library has zero `entity.MeshRefs = ...` writes. All writes are in the App layer, all in `GameWindow.cs`. Confirmed via grep.
 ---
 ## §6. Recommended cache shape (for brainstorming, not yet committed)
 Pre-spec recommendation; final design picks settle in the brainstorming session.
 ```csharp
 // Per-(entity, partIdx, batchIdx) classification result.
 private readonly record struct CachedBatch(
    GroupKey Key,                  // bucket identity
    ulong    BindlessTextureHandle, // resolved texture (via palette + override)
    Matrix4x4 RestPose);            // meshRef.PartTransform (or restPose * meshRef.PartTransform for Setup)
 // Per-entity cache value.
 private sealed class EntityCache
 {
    public List<CachedBatch> Batches = new(); // ordered: (part, batch) flat
    public uint LandblockHint;                 // for InvalidateLandblock
 }
 // Cache state.
 private readonly Dictionary<uint /*entityId*/, EntityCache> _entityCache = new();
 // Hot path:
 //   if (_animatedEntities.ContainsKey(entity.Id)) → today's path (full ClassifyBatches)
 //   else if (_entityCache.TryGetValue(entity.Id, out var cached)) →
 //        for each batch: append (cached.RestPose * entityWorld) to its group's matrices
 //   else → ClassifyBatches once, populate cache, then same fast path next frame.
 ```
 **Per-frame static cost:** dictionary lookup + per-batch matrix multiply + matrices.Add. No texture resolution, no group-key construction, no metaTable lookup.
 **Worst case:** if every entity is animated (e.g. a city full of NPCs), the cache adds one `ContainsKey` lookup per visible entity vs today's path. Negligible overhead. In practice ~10K entities total at radius=12 with ~50 animated → 99.5% cache hit rate on the static path.
 **Risk surface:** the cache invariant rests on TWO claims, both verified in the audit above:
 1. STATIC entity Position / Rotation never mutate post-spawn. Verified §3.
 2. STATIC entity MeshRefs reference never changes post-spawn. Verified §1 (only Site 6 writes, only for animated entities).
 If either claim breaks in a future change (e.g. someone adds an "earthquake" effect that mutates static-tree positions), the cache will quietly serve stale matrices. Defense:
 - **DEBUG-only assertion** in the cache hit path: `Debug.Assert(!_animatedEntities.ContainsKey(entity.Id))`.
 - **DEBUG-only cross-check**: in DEBUG builds, in the cache-hit path, also recompute the live model matrix and compare against `cached.RestPose * entityWorld`. Log a warning if they differ. Catches the "someone added a new mutation site" failure mode without paying the cost in Release.
 (Belt-and-suspenders option (c) from the original handoff. Recommended for the first retry given the prior bug.)
 ---
 ## §7. What does NOT need to be in the cache design
 - **Texture invalidation on bindless handle change.** Bindless handles are issued on first texture upload and remain valid for the texture's lifetime. `TextureCache` doesn't evict entries during normal play (only on shutdown). Static-entity texture handles never change.
 - **GfxObj re-decode.** `WbMeshAdapter.TryGetRenderData` returns the same `ObjectRenderData` instance for a given `gfxObjId` for the session. Static-entity batches never change.
 - **`SurfaceOverrides` reactivation.** Init-only on `MeshRef`, set at Site 1's hydration time, stable for the MeshRef's lifetime.
 - **Per-frame `Time` / `dt` inputs.** The dispatcher doesn't read time. Texture animation (e.g. animated UV scrolls) happens in the shader from `gl_Time`-equivalent uniforms, not from cached state.
 ---
 ## §8. Open questions for brainstorming
 These need a user decision before I write the spec:
 1. **Where do `InvalidateEntity` / `InvalidateLandblock` live?** On `WbDrawDispatcher` (cache lives there)? On a new `EntityClassificationCache` class injected into the dispatcher (separation of concerns; testable in isolation)? My lean: separate class, dispatcher gets it via ctor.
 2. **Static-only (option a) vs static-only + DEBUG cross-check (option c)?** Cross-check costs nothing in Release and catches the exact bug class that bit us last time. My lean: option (c).
 3. **Cache the full model matrix or the rest pose?** Full matrix saves a per-frame multiply but bakes Position/Rotation into the cache (theoretically violatable). Rest pose is safer + costs ~one mat4 mult per batch. My lean: rest pose.
 4. **Setup multi-part flattening: cache the per-part `setupPart.PartTransform * meshRef.PartTransform` product?** Today's `Draw` walks `renderData.SetupParts` per-frame even though that list is per-GfxObj-immutable. The cache could pre-flatten into the batch list. My lean: yes — that's where the visible CPU win is.
 5. **Test plan: where do new tests live?** `tests/AcDream.Core.Tests/Rendering/Wb/EntityClassificationCacheTests.cs`? Pure-CPU tests on the cache class without GL state? My lean: yes, separate test file in the existing Wb test directory.
 ---
 ## §9. Sentinel + baseline (verified at audit start, 2026-05-10)
 - `dotnet build`: green (after `git submodule update --init` for the WorldBuilder ref tree, which was missing in this fresh worktree).
 - `dotnet test --no-build`: 1688 passing, 8 pre-existing failures in `AcDream.Core.Tests`. Matches the post-#52/#54 baseline in the handoff.
 - N.5b sentinel filter (`TerrainSlot|TerrainModernConformance|Wb|MatrixComposition|TextureCacheBindless|SplitFormulaDivergence`): 94/94 passing. Matches the post-#52/#54 baseline.
 These are the floors the Tier 1 retry must keep clean throughout.
--- a/docs/research/2026-05-10-tier1-retry-handoff.md
+++ b/docs/research/2026-05-10-tier1-retry-handoff.md
@ -1,203 +0,0 @@
 # Phase Post-A.5 — Tier 1 Retry (ISSUE #53) — Cold-Start Handoff
 **Created:** 2026-05-10, immediately after closing ISSUES #52 (lifestone) + #54 (JobKind plumbing) and merging to main.
 **Audience:** the next agent picking up Priority 3 of the Post-A.5 polish phase.
 **Purpose:** drop straight into the Tier 1 entity-classification cache retry without re-litigating what the prior session settled.
 ---
 ## TL;DR
 Post-A.5 polish was sized at three priorities. **2 of 3 shipped to main** during the 2026-05-10 session; **only Priority 3 (Tier 1 retry, ISSUE #53) remains.** Tier 1 is the biggest perf headroom in the post-A.5 phase: it should drop the entity dispatcher cpu_us median from ~3.5 ms to ~1-1.5 ms, putting the dispatcher inside the spec's 2.0 ms budget and unlocking ~300-400 FPS at standstill.
 The first Tier 1 attempt (commit `3639a6f`, reverted at `9b49009`) broke animation. The next attempt MUST start with an animation-mutation audit. **This handoff has the audit pre-started** — there's specific evidence captured below that the previous handoff didn't have.
 Sized: ~5-7 days including audit + design + spec + implementation + visual gate.
 ---
 ## Where main is
 - **`main` HEAD: `da08490`** — Merge of `claude/cranky-varahamihira-fe423f`. Includes the lifestone fix + JobKind plumbing.
 - **CLAUDE.md "Currently in flight"** updated to *"Post-A.5 polish — Tier 1 retry (only remaining priority)"*.
 - **`docs/ISSUES.md`** has both #52 and #54 in *Recently closed* with full root-cause writeups; only #53 remains in *Active issues*.
 - **N.5b conformance sentinel: 94/94.** Full suite: 1688/1696 passing (8 pre-existing physics/input failures unchanged across all session work).
 Recent commit chain on main (newest first):
 | SHA | Subject |
 |---|---|
 | `da08490` | Merge branch 'claude/cranky-varahamihira-fe423f' — Post-A.5 polish: close #52 (lifestone) + #54 (JobKind plumbing) |
 | `9a55354` | docs(post-A.5 #54): close JobKind plumbing issue + update CLAUDE.md flight status |
 | `bf31e59` | fix(streaming): close #54 — plumb JobKind through BuildLandblockForStreaming |
 | `b19f1d1` | docs(post-A.5 #52): close lifestone issue + update CLAUDE.md flight status |
 | `e40159f` | fix(render): close #52 — lifestone visible (alpha-test + cull + uDrawIDOffset) |
 | `c111312` | docs(post-A.5): cold-start handoff for the next session (the prior handoff this work used) |
 ---
 ## What shipped this session
 ### Priority 1 — ISSUE #52 (lifestone missing) — closed by `e40159f`
 Three independent root causes regressed with the WB rendering migration (Phase N.5 retirement amendment, commit `dcae2b6`, 2026-05-08):
 1. **Alpha-test discard** in `mesh_modern.frag` transparent pass killed high-α pixels of dat-flagged transparent surfaces. The lifestone crystal core (surface `0x080011DE`) decoded with α≥0.95, so 100% of fragments were discarded. Fix: remove `α >= 0.95 discard` from transparent pass; keep `α < 0.05 discard` as a fragment-cost optimization.
 2. **Cull state regression**: `WbDrawDispatcher.Draw` Phase 8 had no GL cull state — Phase 9.2's `Enable(CullFace) + Back + CCW` setup (commit `6f1971a`, 2026-04-11) was lost when the legacy `StaticMeshRenderer` was deleted. Closed-shell translucents composited back-faces over front-faces in iteration order under `DepthMask(false)`. Fix: re-establish Phase 9.2's GL state at the top of Phase 8.
 3. **`uDrawIDOffset` indexing bug**: `gl_DrawIDARB` resets to 0 at the start of each `glMultiDrawElementsIndirect`, so the transparent pass was reading `Batches[0..transparentCount)` (the OPAQUE section) instead of `Batches[opaqueCount..end)`. The lifestone flickered to whatever opaque batch sorted to index 0 each frame. Fix: add `uniform int uDrawIDOffset` to `mesh_modern.vert`, set per-pass in dispatcher (0 for opaque, `_opaqueDrawCount` for transparent). Mirrors WB's `BaseObjectRenderManager.cs:845`.
 User-confirmed visually via `+Acdream` test character at the Holtburg outdoor lifestone (Z=94 platform).
 ### Priority 2 — ISSUE #54 (JobKind plumbing) — closed by `bf31e59`
 `LandblockStreamer.cs` primary ctor signature changed from `Func<uint, LoadedLandblock?>` to `Func<uint, LandblockStreamJobKind, LoadedLandblock?>`. A back-compat overload preserves the old signature for the 5 ctor sites in `LandblockStreamerTests.cs` (no test changes needed). `BuildLandblockForStreaming(uint, JobKind)` in `GameWindow.cs` early-outs for `LoadFar` with a heightmap-only path. The Bug A post-load entity strip in `LandblockStreamer.HandleJob` is retained as a `Debug.Assert` + Release safety net.
 Per-LB worker cost on far-tier dropped from ~tens of ms (full hydration including `LandBlockInfo` + `SceneryGenerator` + interior cells) to ~sub-ms (single `LandBlock` dat read).
 ### Memory entry from this session
 `feedback_wb_migration_state_audit.md` — captures the meta-lesson that WB-migration phases need a systematic GL-state and shader-uniform diff vs the legacy renderer being replaced. Future phases at risk: Sky/Particles modern path migration, EnvCell modern path, Shadow mapping. Also captures the workflow lesson: when the user says *"we had this nailed down before"*, the first move is `git log -- <legacy file>` BEFORE adding new diagnostic instrumentation.
 ---
 ## Priority 3 — ISSUE #53 — Tier 1 entity-classification cache retry
 ### What the first attempt was and why it failed
 Commit `3639a6f` (reverted at `9b49009`) cached `meshRef.PartTransform` baked into per-(entity, batch) classification at first-frame visit. For static entities this is stable; for animated entities the cache froze the pose and NPCs/players stopped animating. Some buildings also showed at wrong positions (likely entities incorrectly flagged as animated).
 The "trust MeshRefs as the source of truth" comment in the dispatcher gave false confidence. MeshRefs IS the source of truth, but it's mutated EVERY frame for animated entities.
 ### The audit (PRE-STARTED in the prior session — read this carefully)
 The previous handoff and ISSUE #53 describe the bug as *"AnimationSequencer mutates `meshRef.PartTransform` every frame to apply the current skeletal pose."* **That framing is technically wrong** in a way that matters for the retry design. Discovered during the post-A.5 lifestone session:
 - `MeshRef` at `src/AcDream.Core/World/MeshRef.cs:15` is a `readonly record struct` — its fields **cannot be mutated in place**:
  ```csharp
  public readonly record struct MeshRef(uint GfxObjId, Matrix4x4 PartTransform)
  ```
 - The actual per-frame mutation for animated entities is the **entire `MeshRefs` LIST replacement** at `src/AcDream.App/Rendering/GameWindow.cs:7474-7553`:
  ```csharp
  var newMeshRefs = new List<AcDream.Core.World.MeshRef>(partCount);
  // ... loop building per-part transforms from sequencer.Advance(dt) ...
  ae.Entity.MeshRefs = newMeshRefs;
  ```
 - The source of truth for *which* entities go through that per-frame path is the `_animatedEntities` dictionary at `GameWindow.cs:160`:
  ```csharp
  private readonly Dictionary<uint, AnimatedEntity> _animatedEntities = new();
  ```
  Population: `_animatedEntities[entity.Id] = new AnimatedEntity{...}` at GameWindow.cs:2724 (spawn). Removal: `_animatedEntities.Remove(...)` at GameWindow.cs:2935 (despawn).
 **Therefore: a static entity is one whose `Id` is NOT in `_animatedEntities`.** Its MeshRefs list is the same instance from spawn until rare events (ObjDesc / palette swap / part hide). Other static-entity write sites that must be invalidation-aware:
 - `src/AcDream.App/Rendering/GameWindow.cs:2333` and `:2365` — ObjDescEvent / AnimPartChange events rebuild a `MeshRef` element. Network-driven, infrequent.
 - `src/AcDream.App/Rendering/GameWindow.cs:2524` — entity scale apply at spawn (one-shot).
 - Lines 4682-4924, 4996-5074 — dat-side hydration paths in OnLoad / scenery / interior. Spawn-time only.
 ### What this means for cache design
 The cleanest design is now clearer than the original handoff suggested:
 **Recommended approach (option a from the original handoff): static-only cache with explicit invalidation hooks.**
 1. Cache the (entity, batch) → InstanceGroup-key + model-matrix mapping for entities where `_animatedEntities.ContainsKey(entity.Id) == false`.
 2. Animated entities skip the cache entirely; they go through today's per-frame `ClassifyBatches` path.
 3. Invalidate the cache for an entity on:
   - **ObjDesc / AnimPartChange events** (`GameWindow.cs:2333, 2365`) — rebuild that entity's cache entry.
   - **Palette override changes** (rare; usually only on initial server spawn or a re-equip event).
   - **Entity despawn** — drop the cache entry.
 4. Static entities never animate. The dispatcher's per-frame work for cached entities reduces from "walk + classify all batches" to "walk + lookup-and-emit-pre-classified".
 Why this is safer than the first attempt: the first attempt cached the POSE (model matrix). This attempt would cache only the (group key, texture handle, blend mode, per-part `meshRef.PartTransform * entityWorld` for the spawn-time stable subset). Animation never enters the cache surface.
 ### Cache design options reconsidered
 (a) **Static-only cache (recommended).** As described above. Clean invariant: animated entities skip the cache; static entities go through it. Requires careful enumeration of all writes to `entity.MeshRefs` for static entities (see audit list above) so each one fires invalidation.
 (b) **Dynamic-aware cache with invalidation hooks.** Cache everything but expose `InvalidateEntity(uint)` / `RefreshEntityPalette(uint)` hooks; wire from network handlers. More complex but might let some animated entities also benefit if their per-frame mutations are localized. NOT RECOMMENDED for a first retry — error-prone and the first attempt already failed at this scope.
 (c) **Static-only + animated-bypass + DEBUG cross-check.** Like (a), but in DEBUG builds, log a warning every frame if a cached entity's `MeshRefs` reference no longer matches the cached snapshot (catches mis-classified dynamics). Belt-and-suspenders. Recommended IF you're nervous about the audit being incomplete.
 ### Acceptance criteria (from the original handoff, refined)
 - Build green; existing 999+ tests pass; 8 pre-existing physics/input failures stay at 8.
 - 1-3 new tests covering: cache hit for static entity (lookup), cache bypass for animated entity (no-op), cache invalidation on entity despawn, cache invalidation on ObjDesc/palette event.
 - N.5b conformance sentinel intact (89+ tests; in this session it's 94/94 — must stay clean).
 - Visual gate: launch + walk Holtburg → North Yanshi at horizon-safe preset; confirm:
  - Animation works (NPCs, player character animate normally — including the lifestone crystal closed by #52).
  - Buildings at correct positions.
  - No new visual regressions.
 - Perf gate (with `[WB-DIAG]` under `ACDREAM_WB_DIAG=1`):
  - Entity dispatcher cpu_us median drops from ~3.5 ms to ≤2.0 ms (matches spec budget).
  - p95 stays ≤2.5 ms.
 ---
 ## Files to read before brainstorming
 In rough order:
 1. **This handoff** end-to-end — captures audit insights from the prior session that the original handoff didn't have.
 2. **`docs/research/2026-05-10-post-a5-polish-handoff.md`** — the prior handoff. §"Priority 3" has the original (slightly outdated) framing of the bug. Read for context but trust THIS handoff's audit insights over its.
 3. **`docs/ISSUES.md` issue #53** — the issue's own description (now updated post-#52/#54 close).
 4. **`docs/superpowers/specs/2026-05-09-phase-a5-two-tier-streaming-design.md`** — A.5 spec for the entity dispatcher's data-flow context (esp. §4.10 Quality Preset and §11 deferred items).
 5. **`docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md`** — the perf-tier roadmap. Tier 1 is in scope; Tier 2 + Tier 3 are explicitly NOT (those are dedicated multi-week phases).
 6. **`memory/feedback_wb_migration_state_audit.md`** — the new memory entry on WB migration state-loss patterns. Tier 1 doesn't touch the WB migration directly, but the meta-lesson "audit before assume" is exactly what this priority needs.
 7. **`memory/project_phase_a5_state.md`** — the 5 gotchas. **Critical for avoiding the same traps**, especially #3 (caching mutable per-frame state breaks animation silently) — the exact bug the first Tier 1 attempt hit.
 8. **`src/AcDream.Core/World/MeshRef.cs`** — confirm the `readonly record struct` shape; understand that "mutating PartTransform" actually means "replacing the whole MeshRef record."
 9. **`src/AcDream.App/Rendering/GameWindow.cs:7340-7560`** — the per-frame animation rebuild loop. Read this end-to-end for the audit. Find every line that writes to `entity.MeshRefs` for animated entities.
 10. **`src/AcDream.App/Rendering/GameWindow.cs:160` + lines 2710-2760, 2920-2940** — `_animatedEntities` declaration + spawn/despawn population.
 11. **`src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs`** — `Draw` and `ClassifyBatches`. Where the cache will land.
 12. **`src/AcDream.Core/Physics/AnimationSequencer.cs`** — the per-frame animation engine. Audit any field it mutates that the dispatcher reads.
 13. **`src/AcDream.Core/Physics/AnimationHookRouter.cs`** — secondary mutation source via animation hooks.
 ---
 ## Workflow for the next session
 1. **Read this handoff in full.**
 2. **Verify build green:** `dotnet build`. Verify ~1688 tests pass: `dotnet test --no-build`. Verify N.5b sentinel: filter `TerrainSlot|TerrainModernConformance|Wb|MatrixComposition|TextureCacheBindless|SplitFormulaDivergence` → expect 94 passing.
 3. **Read the files above** in order. Especially deep on §"Files to read" #8-#13.
 4. **Audit step (1-2 days):** open a fresh research note `docs/research/2026-05-10-tier1-mutation-audit.md` and write down:
   - Every code path that writes `entity.MeshRefs = ...` for any entity.
   - Tag each as **STATIC** (one-shot at spawn or rare event) or **DYNAMIC** (per-frame).
   - For each STATIC write, identify the trigger (network event, scale apply, etc.) and design the invalidation hook.
   - For each DYNAMIC write, confirm it fires only for entities in `_animatedEntities` (which means cache bypass is the right answer).
 5. **Spec (~1 day):** brainstorm the cache design with the user (use `superpowers:brainstorming`). Write `docs/superpowers/specs/2026-05-10-issue-53-tier1-cache-design.md`. Include the audit findings, the chosen cache approach (probably option (a)), the invariants, the invalidation API, the test plan, the perf-gate measurement plan.
 6. **Implement (~2-3 days):** TDD via `superpowers:test-driven-development`. Tests first for cache hit/miss/invalidation, then implementation in `WbDrawDispatcher`. Wire invalidation hooks into the relevant write sites in `GameWindow.cs`.
 7. **Visual gate:** launch + walk; confirm animation works on a moving NPC; confirm static buildings/scenery still render at correct positions; confirm lifestone (closed by #52) still renders.
 8. **Perf gate:** capture `[WB-DIAG]` cpu_us median + p95 with `ACDREAM_WB_DIAG=1` at horizon-safe preset (NEAR=4, FAR=12). Compare to today's ~3.5 ms baseline; expect ≤2.0 ms.
 9. **Ship:** commit, close #53 in ISSUES.md, update CLAUDE.md "Currently in flight" (this would close out the post-A.5 polish phase entirely), update memory with any new gotchas captured during the audit/implementation.
 10. **Next phase after #53 ships:** N.6 (perf polish) per the roadmap. Or escalate to Tier 2 (static/dynamic split with persistent groups) per `docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md` if Tier 1 alone doesn't hit the perf target.
 ---
 ## Things to NOT do
 - **Don't skip the audit.** The whole reason the first attempt failed was that the audit was implicit and incomplete. The audit step should produce a written list of every MeshRefs write site, classified static vs dynamic, before any cache code is written.
 - **Don't bundle Tier 2 or Tier 3 into this phase.** Those are dedicated multi-week phases per `docs/plans/2026-05-10-perf-tiers-2-3-roadmap.md`. If the audit reveals Tier 1 alone can't hit the perf target, file a follow-up issue and escalate as a separate phase.
 - **Don't re-add the `Tier1` cache that was reverted.** Start fresh after the audit. Cherry-picking commit `3639a6f` reintroduces the animation freeze.
 - **Don't break the N.5b conformance sentinel.** Run the filter on every commit:
  ```
  dotnet test --no-build --filter "FullyQualifiedName~TerrainSlot|FullyQualifiedName~TerrainModernConformance|FullyQualifiedName~Wb|FullyQualifiedName~MatrixComposition|FullyQualifiedName~TextureCacheBindless|FullyQualifiedName~SplitFormulaDivergence"
  ```
  Expect 94 passing, 0 failures.
 - **Don't skip the visual gate.** Animation has been the highest-risk regression in this codebase repeatedly (Tier 1 first attempt, the lifestone crystal in this session, the foundry statue earlier). Confirm visually with a moving animated NPC, a stationary building, and the lifestone before declaring done.
 - **Don't trust "it was working in prod before."** That was the first Tier 1 attempt's posture. The audit is what makes it actually safe.
 ---
 ## Reference: Tier 1 perf math
 Per the perf-tier roadmap and A.5 final state:
 - **Today** (post-A.5 ship + #52/#54): entity dispatcher cpu_us median ~3.5 ms at radius=12 on Radeon RX 9070 XT @ 1440p. ~200-240 FPS at standstill.
 - **After Tier 1**: ~1.0-1.5 ms median expected. ~300-400 FPS at standstill. Inside the spec's 2.0 ms budget.
 - **After Tier 2 (separate phase)**: ~0.5-1.0 ms. ~400-600 FPS.
 - **After Tier 3 (GPU compute culling, separate phase)**: ~0.05 ms. ~600-1000+ FPS.
 Tier 1 is the lowest-risk, highest-leverage perf win remaining for the post-A.5 polish phase.
 ---
 Good luck. The audit is the load-bearing thing — invest in it. The implementation is mechanical once the audit is solid.
 Holler at the user if any of the audit reveals a write site that doesn't fit the static/dynamic dichotomy cleanly.
--- a/docs/research/2026-05-12-l2a-shipped-l2d-handoff.md
+++ b/docs/research/2026-05-12-l2a-shipped-l2d-handoff.md
@ -1,176 +0,0 @@
 # L.2a shipped — L.2d direction confirmed — Cold-Start Handoff
 **Created:** 2026-05-12 evening, immediately after the L.2a-slice-1/2/3 work landed and visual-verified.
 **Audience:** the next agent picking up Phase L.2 (Movement & Collision Conformance).
 **Purpose:** give you everything you need to start L.2d brainstorming cold, without spelunking through this session's transcript.
 ---
 ## TL;DR
 Phase L.2a (Truth & Diagnostics) shipped three slices tonight. They surfaced **three concrete L.2 findings** with reproducible evidence — converting "we should look at this someday" theories into "here is the entity id, here is the wall normal, here is the cell id." With those findings in hand, the next concrete physics work in the L.2 roadmap is **L.2d slice 1 — port `CBuildingObj` collision so doorway gaps are walkable.** Brainstorm + spec, then port.
 **Three slices shipped to `claude/intelligent-poitras-b2c4f9`:**
 | Commit | What | Why |
 |---|---|---|
 | [`ebef820`](.) | L.2a slice 1: `[resolve]` + `[cell-transit]` probes + DebugPanel mirror | Foundation for every later L.2 change to be evidence-driven |
 | [`e0c08bc`](.) | L.2a slice 2: surface hit object guid in `[resolve]` line | Tell us WHICH entity is the wall, not just the wall normal |
 | [`a068292`](.) | L.2a slice 3: populate the previously-stub `CollisionInfo.CollideObjectGuids` / `LastCollidedObjectGuid` | Slice 2 found these fields were declared but never written — fixed the structural gap |
 ---
 ## Three findings from the L.2a probes
 All produced by walking around Holtburg + pushing W into a Town doorway with `ACDREAM_PROBE_RESOLVE=1 ACDREAM_PROBE_CELL=1`.
 ### Finding 1 — L.2e cell-id format gap (DEFINITIVE)
 The player's tracked `CellId` is being recorded as a **bare low byte** (`0x00000029`), with no landblock prefix. AC cell ids are normally `0xLLLLCCCC` — landblock id (4 hex digits) + cell-within-landblock (4 hex digits, `0x0001-0x00FF` outdoor or `0x0100+` indoor).
 Evidence from a tonight log:
 ```
 [cell-transit] 0x00000001 -> 0x00000029 pos=(132.585,21.015,94.000) reason=resolver
 ```
 NPCs in the same area show MIXED forms in their resolve lines:
 - `cell=0xA9B3000E` ← full landblock-prefixed (correct)
 - `cell=0x00000032` ← bare low byte (matches the bug shape)
 Likely source: `ResolveOutdoorCellId(...)` at [src/AcDream.Core/Physics/PhysicsEngine.cs:687](src/AcDream.Core/Physics/PhysicsEngine.cs:687) — that's the function that ResolveWithTransition routes the output cell id through before returning. Worth grepping for its body.
 This is the L.2e blocker per the plan-of-record:
 > *"Update low outdoor cell id across 24m cell boundaries and landblock seams. Port the retail adjacent-cell search: `find_cell_list`, `check_other_cells`, and `adjust_check_pos`."*
 ### Finding 2 — L.2c wall-slide is working
 The transition layer at this spot does the retail-faithful thing:
 ```
 [resolve] ent=0x000F4240 in=(132.067,17.567,94.000) cell=0x00000029
          tgt=(132.239,17.172,94.000)
          out=(131.938,17.567,94.000) cell=0x00000029
          ok=True groundedIn=True cp=valid hit=yes n=(0.00,1.00,0.00)
          obj=0xA9B47900 walkable=True
 ```
 - Wall normal `(0, 1, 0)` — vertical wall facing +Y, captured correctly.
 - `out` shows the position clamped along the wall: X slid back from 132.067 → 131.938, Y preserved.
 - `ok=True` — resolver completed normally (no `ok=False` anywhere in the trace, 0/140).
 **No L.2c work needed at this site.** Edge-slide / wall-slide port from earlier (per the plan-of-record's L.2c "Current shipped slice" note) is doing its job here.
 ### Finding 3 — L.2d sub-direction = CBuildingObj port (NOT door-toggle)
 All 140 hit=yes lines in the doorway-push test came back with the **same dominant `obj=` attribution**:
 | obj | hits | range | what it is |
 |---|---|---|---|
 | **`0xA9B47900`** | **126** | `0xLLLLxxxx` (landblock-baked static) | The Holtburg building itself — its baked collision mesh |
 | `0x000F4245` | 14 | `0x000Fxxxx` (local-spawn entity) | An NPC standing near the doorway |
 `0xA9B4` matches the Holtburg landblock prefix we logged at startup (`loading world view centered on 0xA9B4FFFF`). The `0x7900` low bytes is its landblock-local entity id. **It's the building's baked collision shape — not a door entity, not a creature.**
 **Implication:** the "doorway is blocked" symptom is NOT a door-collision-not-toggled bug (which would have shown a door-range entity id, typically `0xCC0Cxxxx`). It's a **building-mesh fidelity issue**: the building's baked collision data we're loading represents the building as a solid block with no walkable opening where the visual doorway is.
 Two non-mutually-exclusive interpretations:
 1. **Collision-mesh extraction is wrong** — we load building geometry but don't respect the BSP nodes that encode doorway openings.
 2. **`CBuildingObj` + per-cell walkability is not ported** — retail uses a per-cell `CObjCell` structure that maps "this interior cell is reachable" / "this exterior cell connects to those interior cells." Without that, we treat the building as one opaque collision volume.
 The plan-of-record's L.2d goal:
 > *"Preserve enough building identity to model `CBuildingObj` collision and `bldg_check` behavior."*
 points at interpretation 2 as the canonical fix.
 ---
 ## What this session deliberately did NOT do
 - **Other L.2a slices** (contact-plane probe, ShadowObject hit log, water probe, real-DAT fixture-capture pipeline). Slice 1 + 2 + 3 cover the most-load-bearing case (resolver outcomes + cell transits + entity attribution). The remaining diagnostics serve future L.2 work and can ship opportunistically.
 - **L.2d implementation or brainstorm.** Deliberately parked for a fresh session with this evidence as cold-start context.
 - **L.2e implementation.** The cell-id format finding is filed but not investigated.
 - **Pre-existing test failures.** 8 tests fail at the branch base (none from these slices — verified by stash + rerun on every test cycle). Not from this slice. See "Open concerns" below.
 ---
 ## Branch state at handoff
 - Branch: `claude/intelligent-poitras-b2c4f9`
 - Three slice commits ahead of `eab347d` (the C.1.5b merge into main), plus a docs commit that adds this handoff + the next-session prompt + plan-of-record / CLAUDE.md updates.
 - Tonight's last code commit was `a068292` (L.2a slice 3); docs commit follows.
 - Worktree clean post-docs-commit; merge to main is the user's planned next operation.
 ## What's now in the diagnostic surface
 Live env vars (both can be flipped at runtime via the DebugPanel "Diagnostics" section if `ACDREAM_DEVTOOLS=1`):
 - **`ACDREAM_PROBE_RESOLVE=1`** — one `[resolve]` line per `PhysicsEngine.ResolveWithTransition` call:
  ```
  [resolve] ent=0xEEEEEEEE in=(x,y,z) cell=0xCCCCCCCC tgt=(x,y,z) out=(x,y,z) cell=0xCCCCCCCC ok=Y/N groundedIn=Y/N cp=valid|lastKnown|none hit=yes n=(nx,ny,nz) obj=0xOOOOOOOO env nObj=N walkable=Y/N
  ```
  Heavy: fires for every entity's resolve per physics tick.
 - **`ACDREAM_PROBE_CELL=1`** — one `[cell-transit]` line per `PlayerMovementController.CellId` change:
  ```
  [cell-transit] 0xOLD -> 0xNEW pos=(x,y,z) reason=resolver|teleport
  ```
  Low volume — only fires on actual cell crossings.
 Both backed by `AcDream.Core.Physics.PhysicsDiagnostics` static class (initial from env var, set/get from anywhere at runtime).
 ## Files changed in this session
 ```
 src/AcDream.Core/Physics/PhysicsDiagnostics.cs              (new)
 src/AcDream.Core/Physics/PhysicsEngine.cs                   (modified — probe emission)
 src/AcDream.Core/Physics/TransitionTypes.cs                 (modified — entity attribution plumbing)
 src/AcDream.App/Input/PlayerMovementController.cs           (modified — UpdateCellId chokepoint)
 src/AcDream.UI.Abstractions/Panels/Debug/DebugVM.cs         (modified — Probe* forwarder props)
 src/AcDream.UI.Abstractions/Panels/Debug/DebugPanel.cs      (modified — two new checkboxes)
 docs/plans/2026-04-29-movement-collision-conformance.md     (modified — shipped-slice note + L.2d sub-direction)
 ```
 ## Open concerns flagged but NOT addressed in this session
 - **8 pre-existing test failures** on the branch base, verified by stash+rerun: `MotionInterpreterTests.GetMaxSpeed_*` (3), `PositionManagerTests.ComputeOffset_BothActive_Combined`, `PlayerMovementControllerTests.Update_ForwardInput_MovesInFacingDirection`, `DispatcherToMovementIntegrationTests.Dispatcher_W_held_produces_forward_motion`, `BSPStepUpTests.{D4_AirborneMover_TallWall_PersistsSlidingNormalAcrossFrames,C3_Path6_AirborneMoverHitsSteepSlope_SetsCollide}`. Most touch movement/physics code we're about to evolve in L.2b/L.2c/L.2d — **triage before further L.2 work** is recommended.
 - **Player entity id quirk.** Local player physics entity id observed as `0x000F4240` in the resolve probe, not the server guid `0x5000000A`. This is presumably the dat/local-spawn entity id — fine for diagnostic, worth keeping in mind for any future "is this the player?" check.
 ## Cold-start checklist for L.2d brainstorm
 1. Read this handoff.
 2. Read [docs/plans/2026-04-29-movement-collision-conformance.md](docs/plans/2026-04-29-movement-collision-conformance.md) — focus on L.2d section.
 3. Read the L.2d named-retail anchors:
   - `CCellStruct::point_in_cell`, `CCellStruct::sphere_intersects_cell`, `CCellStruct::box_intersects_cell`
   - `CBuildingObj::find_building_collisions`
   - `CObjCell::find_cell_list` (already shared with L.2e)
   Grep `docs/research/named-retail/acclient_2013_pseudo_c.txt` by `class::method`.
 4. Read [src/AcDream.Core/Physics/TransitionTypes.cs:1386](src/AcDream.Core/Physics/TransitionTypes.cs:1386) — current `FindObjCollisions` loop, where building objects currently route through generic BSP/Cylinder paths.
 5. Read [src/AcDream.Core/Physics/PhysicsDataCache.cs](src/AcDream.Core/Physics/PhysicsDataCache.cs) — how we currently load BSP / GfxObj data; figure out if building-specific data (interior cells, `CBuildingObj`) is loaded but not consumed.
 6. Cross-reference WorldBuilder (`references/WorldBuilder/`) for any building-cell handling already present.
 7. Brainstorm the slice (`superpowers:brainstorming` if useful) — scope, named-retail anchors, conformance tests, real-DAT fixtures.
 8. Write a spec at `docs/superpowers/specs/2026-05-13-l2d-cbuildingobj-collision-design.md`.
 9. Implement in slices with conformance citations in each commit.
 ## Reproducing the doorway evidence
 In case you want to re-capture the trace:
 ```powershell
 # In the project worktree
 $env:ACDREAM_DAT_DIR    = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE       = "1"
 $env:ACDREAM_TEST_HOST  = "127.0.0.1"
 $env:ACDREAM_TEST_PORT  = "9000"
 $env:ACDREAM_TEST_USER  = "testaccount"
 $env:ACDREAM_TEST_PASS  = "testpassword"
 $env:ACDREAM_DEVTOOLS   = "1"
 $env:ACDREAM_PROBE_CELL = "1"
 $env:ACDREAM_PROBE_RESOLVE = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | Tee-Object -FilePath "launch.log"
 ```
 Walk acdream up to a Holtburg building doorway. Hold W into it for ~2 seconds. Close. Grep `launch.log` for:
 - `cell-transit` — cell tracking
 - `\[resolve\].*hit=yes` — wall hits with object attribution
 Wall entity should appear as `obj=0xA9B47XXX` for the same Holtburg building, OR a different `0xA9Bxxxxx` for other buildings in the area.
--- a/docs/research/2026-05-12-l2d-next-session-prompt.md
+++ b/docs/research/2026-05-12-l2d-next-session-prompt.md
@ -1,51 +0,0 @@
 # Copy-paste prompt — next session for L.2d brainstorm
 **This file is meant to be pasted verbatim into a new Claude Code session.** It assumes the next session starts on a freshly-merged `main` with the L.2a-slice-1/2/3 work already landed.
 ---
 ## Prompt to paste
 > You are picking up Phase L.2d (Movement & Collision Conformance — Shape Fidelity: Sphere / CylSphere / Building Objects) for the acdream project.
 >
 > The previous session shipped L.2a-slice-1/2/3 (resolver + cell-transit probes + entity attribution plumbing) and used the probes to settle the L.2d sub-direction call: **the wall blocking us at building doorways is a landblock-baked static (`0xA9B47900` for the Holtburg test building), NOT a door entity.** The fix is to port `CBuildingObj` + per-cell walkability so the building's baked collision mesh has walkable openings where doorways are. Door-state-toggle is NOT the issue.
 >
 > Before writing any code:
 >
 > 1. **Read the handoff:** `docs/research/2026-05-12-l2a-shipped-l2d-handoff.md` — full context, evidence, file pointers.
 > 2. **Read the plan-of-record:** `docs/plans/2026-04-29-movement-collision-conformance.md` — focus on L.2d, and notice that L.2c already shipped most of its work + L.2a is now ~75% covered.
 > 3. **Read the named-retail anchors** (grep `docs/research/named-retail/acclient_2013_pseudo_c.txt` by `class::method`):
 >    - `CCellStruct::point_in_cell`
 >    - `CCellStruct::sphere_intersects_cell`
 >    - `CCellStruct::box_intersects_cell`
 >    - `CBuildingObj::find_building_collisions`
 >    - `CObjCell::find_cell_list`
 > 4. **Read current code:**
 >    - `src/AcDream.Core/Physics/TransitionTypes.cs:1386` — `FindObjCollisions` (where building objects currently flow through generic BSP path).
 >    - `src/AcDream.Core/Physics/PhysicsDataCache.cs` — what building-specific data we already load vs ignore.
 > 5. **Cross-reference WorldBuilder** at `references/WorldBuilder/` for any building-cell handling we can crib.
 >
 > Your deliverable for this session:
 >
 > 1. A brainstorm using `superpowers:brainstorming` if scope is unclear, then
 > 2. A design spec at `docs/superpowers/specs/2026-05-13-l2d-cbuildingobj-collision-design.md` covering:
 >    - Named-retail anchors with line numbers from the PDB pseudo-C
 >    - Component breakdown (CObjCell port, CBuildingObj port, integration with FindObjCollisions)
 >    - Conformance test plan (synthetic + real-DAT fixtures at known Holtburg buildings)
 >    - Slice plan (3-5 commits, each conformance-cited)
 >    - Acceptance criteria
 > 3. After spec approval, implement slice 1.
 >
 > **Before implementation,** verify the L.2a probes still work — relaunch with `ACDREAM_PROBE_RESOLVE=1 ACDREAM_PROBE_CELL=1 ACDREAM_DEVTOOLS=1`, walk up to the Holtburg test doorway, confirm `[resolve]` lines still show `obj=0xA9B4xxxx` for the wall hits. (Reproduction recipe in the handoff doc's last section.)
 >
 > Side note: **8 pre-existing test failures** exist on main (verified by stash+rerun in the prior session, none from L.2a slice work). Most touch movement/physics code we're about to evolve. **Triage them before sinking deep L.2d effort** — a recent baseline regression in this area could waste hours of L.2d work.
 ---
 ## Reading order if you only have 10 minutes
 1. `docs/research/2026-05-12-l2a-shipped-l2d-handoff.md` — TL;DR + Three findings sections (5 min).
 2. `docs/plans/2026-04-29-movement-collision-conformance.md` §L.2d (2 min).
 3. `src/AcDream.Core/Physics/TransitionTypes.cs:1386-1543` — current `FindObjCollisions` body (3 min).
 From there, decide whether to brainstorm or jump straight to the spec.
--- a/docs/research/2026-05-12-l2g-slice1-shipped-handoff.md
+++ b/docs/research/2026-05-12-l2g-slice1-shipped-handoff.md
@ -1,241 +0,0 @@
 # L.2g slice 1 shipped — handoff (code-complete; visual test deferred)
 **Date:** 2026-05-12 evening.
 **Branch:** `claude/gallant-mestorf-3bf2e3` (ready to merge to main).
 **Predecessors:**
 - [2026-05-13-l2d-slice1-shipped-handoff.md](2026-05-13-l2d-slice1-shipped-handoff.md) — the L.2d trace that identified Door entities as the Holtburg doorway blocker, motivating L.2g.
 - [docs/superpowers/specs/2026-05-12-l2g-dynamic-physicsstate-design.md](../superpowers/specs/2026-05-12-l2g-dynamic-physicsstate-design.md) — the L.2g design spec (commit `2c10dd4`).
 - [docs/superpowers/plans/2026-05-12-phase-l2g-slice1.md](../superpowers/plans/2026-05-12-phase-l2g-slice1.md) — the L.2g slice 1 implementation plan (commit `869677b`).
 ---
 ## TL;DR
 L.2g slice 1 **code is complete and unit-tested.** The four commits land
 the full inbound `SetState (0xF74B)` pipeline: parser → WorldSession
 event → GameWindow handler → `ShadowObjectRegistry.UpdatePhysicsState`.
 After this slice, the existing `CollisionExemption.ShouldSkip`
 short-circuit (cited at `acclient_2013_pseudo_c.txt:276782`) honors
 runtime ETHEREAL flips without any resolver-path edit.
 **The visual verification at Holtburg's inn doorway is deferred to the
 next session.** Cause: Phase B.4's outbound Use handler turns out to be
 unwired — clicking on a door silently does nothing because no
 production code subscribes to the `SelectLeft` / `SelectDblLeft` input
 actions. Without the outbound Use, the server never sees a "open the
 door" request, so the inbound SetState we just ported never fires.
 L.2g slice 1 is the inbound half of the round-trip. Phase **B.4b** (a
 small ~30-50 LOC slice) is the outbound half. Both halves are required
 for the M1 demo target *"open the inn door."* B.4b is the next session's
 work.
 ---
 ## What shipped on this branch
 | Commit | Subject |
 |---|---|
 | [`2459f28`](.) | `feat(phys L.2g slice 1): inbound SetState (0xF74B) parser` |
 | [`d538915`](.) | `feat(phys L.2g slice 1): ShadowObjectRegistry.UpdatePhysicsState` |
 | [`536a608`](.) | `feat(phys L.2g slice 1): WorldSession dispatches SetState (0xF74B) + hex probe` |
 | [`108e386`](.) | `feat(phys L.2g slice 1): GameWindow routes SetState + extends [entity-source] log` |
 Plus docs/scaffolding earlier in the session:
 - `2c10dd4` — L.2g design spec + L.2 plan-of-record + milestones + CLAUDE.md updates.
 - `869677b` — L.2g slice 1 implementation plan (this doc's companion).
 **Build:** clean. **Tests:** 6 new tests pass (3 for parser, 3 for
 registry mutator). Full suite: 1037 pass / 8 pre-existing-baseline fail.
 No regressions. Per-commit + final integration code reviews all approved.
 ---
 ## What the code now does end-to-end
 When the server broadcasts a `SetState (0xF74B)`:
 1. **Parse** — `WorldSession`'s dispatcher routes opcode `0xF74B` into
   `SetState.TryParse(body)`, which returns
   `SetState.Parsed(Guid, PhysicsState, InstanceSequence, StateSequence)`.
 2. **Probe** (gated on `ACDREAM_PROBE_BUILDING=1`) — one-shot per
   session, dumps the first message's body bytes as
   `[setstate-hex] body.len=N first-N-bytes: 4B F7 ...` for wire-format
   confidence.
 3. **Event** — `WorldSession.StateUpdated` fires with the parsed value.
 4. **Subscribe** — `GameWindow.OnLiveStateUpdated` (added to the live-
   session attach block alongside `OnLiveVectorUpdated`) calls
   `_physicsEngine.ShadowObjects.UpdatePhysicsState(parsed.Guid, parsed.PhysicsState)`.
 5. **Mutate** — `ShadowObjectRegistry.UpdatePhysicsState` walks every
   per-cell list the entity occupies and rewrites `list[i] with { State = newState }`.
 6. **Per-tick diagnostic** (same probe flag) — emits
   `[setstate] guid=0x... state=0x... instSeq=... stateSeq=...` for the
   greppable trail.
 7. **Resolver** — next physics tick, `FindObjCollisions` calls
   `CollisionExemption.ShouldSkip(entry.State, entry.Flags, moverState)`
   on the entity. The check is unchanged from L.2d slice 1; it
   short-circuits when `(state & ETHEREAL_PS) != 0 && (state & IGNORE_COLLISIONS_PS) != 0`.
 **Slice 0.5 freebie folded in:** all 6 `[entity-source]` probe-log
 sites in `GameWindow.cs` now emit `state=0x{state:X8} flags={flags}`
 so ETHEREAL flips are greppable end-to-end from spawn through state
 change.
 ---
 ## Why the visual test is deferred — the B.4 discovery
 Before launching the visual test, the user reported that right-click
 in-client was bound to camera orbit (correctly), and asked whether
 left-click should open a door. Investigation produced this finding:
 | Component | State |
 |---|---|
 | `InteractRequests.BuildUse(seq, guid)` wire builder | ✅ implemented + tested |
 | `SelectionState`, `WorldPicker` classes | ✅ exist in source |
 | `InputAction.SelectLeft` / `SelectDblLeft` / `SelectRight` enum | ✅ defined |
 | KeyBindings: LMB → `SelectLeft`, LMB-dblclick → `SelectDblLeft`, RMB → `SelectRight` | ✅ wired in `KeyBindings.cs:300-320` |
 | `GameWindow.OnInputAction` switch case for `Select*` | ❌ **missing** |
 | Any production caller of `SelectionState`, `WorldPicker`, `InteractRequests.BuildUse` | ❌ **none in `src/`** |
 The diagnostic line `[input] SelectLeft Press` fires on LMB-click — the
 dispatcher knows the action — but nothing downstream listens. The
 click silently does nothing. The R hotkey similarly does nothing
 because the corresponding `UseSelected` case is also absent from the
 switch.
 So the M1 outbound Use path is **half-shipped**: every component below
 the handler exists, but the handler that ties them together was never
 landed (despite a 2026-04-28 memory entry claiming "B.4 shipped").
 Phase B.4b is the slice that fixes this.
 This is **not** an L.2g defect. L.2g's code path is correct and unit-
 tested; it just can't be exercised at runtime until the outbound Use
 sends a SetState-triggering request to the server.
 ---
 ## Open notes from reviews (minor — defer to next polish pass)
 The per-commit and final integration code reviews approved every commit.
 Four observations flagged as Minor that are worth folding into a future
 polish pass:
 1. **`SetState.cs` "total body size" phrasing diverges from `VectorUpdate.cs`.**
   New form: `"Total body size: 16 bytes (4-byte opcode + 12-byte payload)"`.
   Sibling form: `"Total body size after opcode: 32 bytes"`. The new form
   is more self-documenting, but the spec asked to align with the
   sibling. Cosmetic.
 2. **`[setstate-hex]` log uses redundant `Math.Min(body.Length, 32)`.**
   Called twice in the same line; could be hoisted to a local.
   Harmless for a one-shot diagnostic.
 3. **`WorldSession.cs` uses the fully-qualified
   `AcDream.Core.Physics.PhysicsDiagnostics.ProbeBuildingEnabled`** instead
   of adding `using AcDream.Core.Physics;` and using the short form.
   Every other call site in `GameWindow.cs` and `BSPQuery.cs` uses the
   unqualified form. Style inconsistency.
 4. **`[setstate]` diagnostic emits guid + state as hex but instSeq +
   stateSeq as decimal.** Cosmetic.
 ### One Important review note (worth following up explicitly)
 The final integration reviewer flagged: the test
 `UpdatePhysicsState_FlipsEthereal_NextLookupSeesNewBits` asserts the
 cached state changes to `0x4` but does **not** verify the chain
 through `CollisionExemption.ShouldSkip`. That short-circuit requires
 **both** `ETHEREAL_PS (0x4)` AND `IGNORE_COLLISIONS_PS (0x10)` to be
 set simultaneously (`(state & 0x4) && (state & 0x10)`). A state of
 `0x4` alone does NOT exempt collision. Per the reviewer, ACE's
 `PhysicsObj.cs:787-791` may set both bits when doors open (broadcast
 value `0x14` or higher) — but this is not verified by the test suite.
 **The B.4b visual test will settle this definitively:** the slice-1
 hex-dump probe will capture the real `state=0x????????` wire value the
 first time a door opens. If ACE sends `0x14` or higher, the existing
 chain works as-is. If ACE sends `0x4` only, we need a tiny adjustment
 to `CollisionExemption.cs` (the `&&` would become `||`, OR we make the
 collision exemption fire on ETHEREAL alone, OR we widen the test).
 **Action for B.4b session:** after the door-open visual test, grep the
 launch log for `[setstate-hex]` and the `[setstate]` line that fires on
 the Use → confirm the state bits ACE actually sends. If `0x4` only,
 file a tiny L.2g slice 1b to widen `CollisionExemption.ShouldSkip` or
 the test's assertion.
 ---
 ## Next session
 **Pick: Phase B.4b — finish the outbound Use handler wiring.**
 Concretely:
 - Subscribe `InputAction.SelectDblLeft` in `GameWindow.OnInputAction`
  switch.
 - Build a world ray from current mouse position
  (`WorldPicker.BuildRay(mouse, vp, view, proj)`).
 - Pick the closest entity (`WorldPicker.Pick(ray, entities, cache, skipGuid, maxDist)`).
 - Store result in `_selection` (`SelectionState.Set(guid)`).
 - Call `InteractRequests.BuildUse(seq, guid)` + `_liveSession.SendGameMessage(body)`.
 - Probably also subscribe `InputAction.SelectLeft` for select-without-
  use (single-click selects; double-click selects + uses).
 - Optionally subscribe `InputAction.UseSelected` (R hotkey) to send Use
  on the already-selected guid.
 - Sequence-number management — there's a game-action sequence counter
  on `WorldSession` already used by the outbound chat path; reuse it.
 Estimate: 30-50 LOC, 1-2 subagent-driven implementations + reviews, ~30 min.
 Once B.4b lands, **immediately re-run the Holtburg inn doorway visual
 test** with `ACDREAM_PROBE_BUILDING=1`. Both L.2g slice 1 + B.4b are
 verified by the same scenario; no separate L.2g visual test needed.
 ---
 ## Reproducibility
 Same launch recipe as L.2d slice 1 (see CLAUDE.md "Running the client
 against the live server"). For visual test once B.4b lands:
 ```powershell
 $env:ACDREAM_DAT_DIR        = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE           = "1"
 $env:ACDREAM_TEST_HOST      = "127.0.0.1"
 $env:ACDREAM_TEST_PORT      = "9000"
 $env:ACDREAM_TEST_USER      = "testaccount"
 $env:ACDREAM_TEST_PASS      = "testpassword"
 $env:ACDREAM_DEVTOOLS       = "1"
 $env:ACDREAM_PROBE_BUILDING = "1"
 $env:ACDREAM_PROBE_RESOLVE  = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug 2>&1 |
  Tee-Object -FilePath "launch-l2g+b4b.log"
 ```
 Then walk into the Holtburg inn doorway, double-left-click the door,
 wait for the swing animation, walk through. After 30s, watch the
 auto-close fire.
 After closing the client:
 ```powershell
 Select-String -Path launch-l2g+b4b.log -Pattern "setstate-hex|setstate.*guid|entity-source.*Door|input.*SelectDblLeft"
 ```
 Expected matches:
 - One `[setstate-hex] body.len=16 ...` line (confirms holtburger's 12-byte payload).
 - One `[entity-source] name=Door ... state=0x00000000 flags=None ...` at spawn.
 - An `[input] SelectDblLeft Press` when you double-click.
 - A `[setstate] guid=0x000F... state=0x????????` after the door opens.
 - A second `[setstate] guid=0x000F... state=0x00000000` ~30s later when auto-close fires.
 ---
 ## Worktree state at handoff
 - Branch `claude/gallant-mestorf-3bf2e3` ready to merge to main.
 - 6 commits ahead of main: `2c10dd4` (spec + docs), `869677b` (plan),
  `2459f28` / `d538915` / `536a608` / `108e386` (L.2g slice 1 code).
 - One launch.log artifact (`launch-l2g-slice1.log`) in the working
  tree from the attempted visual test — **not committed** (gitignored
  or transient). Safe to discard; B.4b will produce a fresh log.
 User wants to start a fresh session for B.4b.
--- a/docs/research/2026-05-13-b4b-shipped-handoff.md
+++ b/docs/research/2026-05-13-b4b-shipped-handoff.md
@ -1,417 +0,0 @@
 # Phase B.4b shipped — handoff (visual-verified 2026-05-13)
 **Date:** 2026-05-13.
 **Branch:** `claude/compassionate-wilson-23ff99` (ready to merge to main; do NOT merge here — controller handles that after code review).
 **Predecessors:**
 - [docs/research/2026-05-12-l2g-slice1-shipped-handoff.md](2026-05-12-l2g-slice1-shipped-handoff.md) — L.2g slice 1 ship handoff that discovered the B.4 handler gap and deferred the Holtburg visual test to B.4b.
 - [docs/superpowers/specs/2026-05-13-phase-b4b-design.md](../superpowers/specs/2026-05-13-phase-b4b-design.md) — B.4b design spec.
 - [docs/superpowers/plans/2026-05-13-phase-b4b-plan.md](../superpowers/plans/2026-05-13-phase-b4b-plan.md) — B.4b implementation plan (6 tasks; Tasks 1-4 per plan + 2 bonus sets beyond the plan).
 ---
 ## TL;DR
 Phase B.4b **shipped end-to-end and is visual-verified 2026-05-13.** The M1
 demo target *"open the inn door"* is met. 9 commits on this branch implement
 and fix the complete round-trip: double-click door → `WorldPicker.Pick` →
 `InteractRequests.BuildUse` → ACE broadcasts `SetState (0xF74B)` with
 `ETHEREAL` bit → `ShadowObjectRegistry.UpdatePhysicsState` (L.2g slice 1)
 mutates cached state → `CollisionExemption.ShouldSkip` exempts the door →
 player walks through.
 The plan estimated "30-50 LOC, 1-2 subagent dispatches, ~30 min."
 Visual testing surfaced **four bonus discoveries** beyond the plan's
 Tasks 1-4:
 1. `InputDispatcher` had no double-click detection (the `SelectDblLeft`
   binding was dead code — the dispatcher never produced `DoubleClick`
   activations).
 2. `OnInputAction`'s early-return gate discarded `DoubleClick` activations
   before the switch reached the `SelectDblLeft` case.
 3. L.2g `CollisionExemption.ShouldSkip` required **both** `ETHEREAL` +
   `IGNORE_COLLISIONS` bits, but ACE's `Door.Open()` sends only `ETHEREAL`
   (`state=0x0001000C`).
 4. `OnLiveStateUpdated` passed a server GUID to `ShadowObjectRegistry` which
   is keyed by local entity ID — the registry lookup always missed → no-op
   → the door never became passable. **This was the actual blocker the user
   reported.**
 Fixes 1-4 were shipped as bonus commits 5-9 beyond the plan's Tasks 1-4.
 L.2g slice 1 and B.4b are now both fully verified by the same visual test.
 Issue #57 is closed. Issue #58 (door swing animation) is filed as M1-deferred
 polish.
 ---
 ## What shipped on this branch
 | # | Commit | Subject | Task |
 |---|---|---|---|
 | 1 | `f0b3bd9` | `feat(B.4b): WorldPicker.BuildRay — mouse-to-world ray unprojection` | Task 1 |
 | 2 | `221b641` | `feat(B.4b): WorldPicker.Pick — ray-sphere entity pick` | Task 2 |
 | 3 | `5821bdc` | `fix(B.4b): WorldPicker.Pick — handle inside-sphere origin + document normalize contract` | Task 2 review fix |
 | 4 | `7b4aff2` | `refactor(B.4b): unify _selectedTargetGuid -> _selectedGuid` | Task 3 |
 | 5 | `89d82e1` | `feat(B.4b): GameWindow wires Select/Use handlers via WorldPicker` | Task 4 |
 | 6 | `242ce70` | `feat(B.4b): InputDispatcher detects double-clicks` | Bonus: Task 4b |
 | 7 | `58b95bc` | `fix(B.4b): let DoubleClick activation pass the OnInputAction gate` | Bonus: Task 4c |
 | 8 | `a6e4b57` | `fix(phys L.2g slice 1b): widen CollisionExemption to ETHEREAL alone` | L.2g slice 1b |
 | 9 | `08be296` | `fix(phys L.2g slice 1c): translate ServerGuid -> entity.Id for ShadowObjectRegistry` | L.2g slice 1c |
 Plus plan/spec commits earlier in the branch session:
 - `4a1c594` — B.4b design spec.
 - `ffa404d` — corrected file paths in spec (WorldPicker is in `AcDream.Core.Selection`, not `AcDream.App/Rendering`).
 - `179e441` — B.4b implementation plan (6 tasks).
 **Build:** clean. **Tests:** 4 new double-click detection tests (commit `242ce70`, all pass). Full suite: builds green, no regressions. L.2g slice 1's 6 tests continue to pass.
 ---
 ## What the code does end-to-end
 When the user double-left-clicks a door entity in the Holtburg inn doorway,
 the following chain fires:
 1. **Double-click detection** — `InputDispatcher.OnMouseDown` checks the
   elapsed time since the previous `MouseLeft` press. If ≤500ms, the
   activation kind is `DoubleClick`; otherwise `Press`. This is new as
   of commit `242ce70`; prior to this the `SelectDblLeft` binding was dead
   code (the dispatcher never produced `DoubleClick` activations).
 2. **Action dispatch** — `InputDispatcher` resolves the chord
   `[MouseLeft, DoubleClick]` → `InputAction.SelectDblLeft` + activation
   `DoubleClick`. The multicast `InputAction` event fires, logged as:
   `[input] SelectDblLeft DoubleClick`.
 3. **OnInputAction gate** — `GameWindow.OnInputAction` receives the event.
   Prior to commit `58b95bc`, an early-return guard (`if (activation != Press) return;`)
   discarded all `DoubleClick` events. The fix widens the gate to
   `if (activation != Press && activation != DoubleClick) return;`.
   The switch now reaches the `SelectDblLeft` case.
 4. **Ray construction** — `WorldPicker.BuildRay(mousePos, viewport, viewMatrix, projMatrix)`
   unprojects the cursor pixel into a world-space ray origin + direction,
   using standard NDC→view→world unprojection. Numerically: the mouse pixel
   is mapped to `[-1,+1]` NDC, transformed through `inverse(proj)` to get
   a view-space direction, then through `inverse(view)` for world-space.
 5. **Entity pick** — `WorldPicker.Pick(ray, entities, maxDist=50m)` iterates
   all entities in `_gpuWorldState.GetAllEntities()`, tests each against a
   ray-sphere intersection with the entity's bounding radius, and returns
   the closest hit. A special-case inside-sphere origin guard (commit `5821bdc`)
   ensures the pick works even when the cursor origin is already inside an
   entity's bounding sphere (common for large portals or doors at close range).
   `[B.4b] pick guid=0x7A9B4015 name=Door` logged on hit.
 6. **Use message** — `GameWindow` stores `_selectedGuid = picked.Guid` and
   calls `InteractRequests.BuildUse(seq, guid)`. The resulting `0xF7B1 / 0x0036`
   game message is sent to ACE via `_liveSession.SendGameMessage(body)`.
   `[B.4b] use guid=0x7A9B4015 seq=N` logged.
 7. **ACE processes the Use** — ACE's `Door.Open()` flips the door's physics
   flags to `ETHEREAL | ...` and broadcasts `SetState (0xF74B)` with the
   new state value.
 8. **SetState arrives** — `WorldSession.OnSetState` parses the 12-byte
   payload (Guid + PhysicsState + InstanceSeq + StateSeq) and fires
   `WorldSession.StateUpdated`. `GameWindow.OnLiveStateUpdated` handles it.
   **New as of commit `08be296` (slice 1c):** the handler translates
   `parsed.Guid` (server GUID `0x7A9B4015`) to `entity.Id` (local entity ID
   `0x000F4245`) via `_entitiesByServerGuid` before calling
   `ShadowObjectRegistry.UpdatePhysicsState`. Without this translation the
   registry lookup always returned "not found" — a silent no-op.
   Log: `[setstate] guid=0x7A9B4015 entityId=0x000F4245 state=0x0001000C`.
 9. **Collision exemption** — next physics tick, `FindObjCollisions` calls
   `CollisionExemption.ShouldSkip(entry.State, entry.Flags, moverState)`.
   **New as of commit `a6e4b57` (slice 1b):** the check fires on
   `(state & ETHEREAL_PS) != 0` alone (widened from the original `ETHEREAL &&
   IGNORE_COLLISIONS` conjunction). Because ACE broadcasts only `ETHEREAL`
   in the low bits (`state=0x0001000C`), the original conjunction never fired;
   the door stayed solid.
 10. **Player walks through** — the resolver produces no wall-contact response
    for the door's collision geometry. User confirms: "Now I can walk through."
 ### Observed log evidence
 ```
 [input] SelectDblLeft DoubleClick
 [B.4b] pick guid=0x7A9B4015 name=Door
 [B.4b] use guid=0x7A9B4015 seq=N
 [setstate] guid=0x7A9B4015 entityId=0x000F4245 state=0x0001000C
 ```
 Player walks through the closed door after the `setstate` line.
 ---
 ## The four bonus discoveries
 ### 1. InputDispatcher had no double-click detection (`242ce70`)
 **Root cause:** `InputDispatcher.OnMouseDown` only looked up `Press` and
 `Hold` activations in the binding table. The `SelectDblLeft` binding was
 wired to the chord `[MouseLeft, DoubleClick]` in `KeyBindings.cs:300-320`
 (shipped in B.4, 2026-04-28), but the dispatcher's mouse-down handler
 never set activation to `DoubleClick` — it always produced `Press`.
 So `SelectDblLeft` was literally unreachable: the chord required
 `DoubleClick` to match, but the dispatcher never generated it.
 **Fix:** Added a `_lastMouseDownTime` (and `_lastMouseDownButton`) tracker
 to `InputDispatcher`. In `OnMouseDown`, if the same button fires within
 500ms of its last press, activation is `DoubleClick`; otherwise `Press`.
 500ms matches the standard Windows/macOS double-click threshold.
 **Rationale:** The fix is minimal and correct. A more faithful retail
 implementation might read the OS's configured double-click interval, but
 500ms is the retail default and was the right call for now. 4 new unit
 tests cover the timing logic: first click = Press, second click within
 500ms = DoubleClick, third click = Press again (resets the window), and
 button mismatch = Press.
 ### 2. OnInputAction gate discarded DoubleClick activations (`58b95bc`)
 **Root cause:** Even after discovery #1 was fixed and `SelectDblLeft DoubleClick`
 fired from the dispatcher, the event handler had an early-return guard at
 the top of `GameWindow.OnInputAction`:
 ```csharp
 if (activation != InputActivation.Press) return;
 ```
 This guard was introduced to prevent `Hold` repetition from triggering
 switch cases intended for one-shot actions. It correctly blocked `Hold`
 but also blocked `DoubleClick` — so the `SelectDblLeft` case was still
 unreachable even after the dispatcher started generating `DoubleClick`.
 **Fix:** Widened the guard to let both `Press` and `DoubleClick` through:
 ```csharp
 if (activation != InputActivation.Press && activation != InputActivation.DoubleClick) return;
 ```
 **Rationale:** `DoubleClick` is semantically a one-shot activation (fires
 once per double-click gesture), so it belongs in the same pass-through
 group as `Press`. `Hold` repetition remains blocked.
 ### 3. CollisionExemption required both ETHEREAL + IGNORE_COLLISIONS (`a6e4b57`)
 **Root cause:** The original `CollisionExemption.ShouldSkip` check was
 ported faithfully from `acclient_2013_pseudo_c.txt:276782`, which requires
 **both** `ETHEREAL_PS (0x4)` and `IGNORE_COLLISIONS_PS (0x10)` to be set
 simultaneously before short-circuiting collision detection. Retail servers
 send both bits when opening a door, so retail clients see `state ≥ 0x14`.
 However, ACE's `Door.Open()` broadcasts only the `ETHEREAL` bit in the
 low portion of the state word. The observed wire value was
 `state=0x0001000C`: bit `0x4` (ETHEREAL) is set, bit `0x10`
 (IGNORE_COLLISIONS) is not. The `&&` conjunction in `ShouldSkip` evaluated
 to false → door stayed solid even after the registry update.
 This was the exact scenario the L.2g slice 1 Important review note warned
 about (see L.2g handoff §"One Important review note"): *"ACE's
 `PhysicsObj.cs:787-791` may set both bits... but this is not verified by
 the test suite. The B.4b visual test will settle this definitively."*
 It settled as: ACE sends `0x4` alone, not `0x14`.
 **Fix:** Widened the short-circuit to fire on `ETHEREAL` alone:
 ```csharp
 // Widened from (ETHEREAL && IGNORE_COLLISIONS) — ACE Door.Open() sends
 // ETHEREAL alone (state=0x0001000C); retail servers send both.
 // Pragmatic choice: exempt on ETHEREAL-bit-alone until full retail
 // obstruction_ethereal flag path is ported.
 if ((state & ETHEREAL_PS) != 0) return true;
 ```
 **Rationale:** The deeper retail path (pseudo-C line 276795 sets
 `obstruction_ethereal=1` and routes through downstream movement handling)
 was not ported — that's a more invasive change requiring more testing. The
 pragmatic widening to ETHEREAL alone is correct for ACE's Door behavior and
 matches the spirit of the retail check (ETHEREAL means "pass through me").
 If a future retail-server emulator sends both bits, the widened check still
 fires (ETHEREAL is a subset of ETHEREAL+IGNORE_COLLISIONS).
 ### 4. ServerGuid → entity.Id translation missing in OnLiveStateUpdated (`08be296`) — THE actual blocker
 **Root cause:** `ShadowObjectRegistry` is keyed by local `entity.Id` (the
 per-session integer ID assigned by `GpuWorldState` at entity registration,
 e.g. `0x000F4245`). The `GameWindow.OnLiveStateUpdated` handler was passing
 `parsed.Guid` — the **server GUID** broadcasted in the `SetState` packet
 (e.g. `0x7A9B4015`) — directly to `UpdatePhysicsState`. Because the registry
 has no entry keyed by server GUID, the lookup always returned "not found"
 and the state mutation was silently dropped. The registry stayed at
 `state=0x00000000` (closed, solid) regardless of how many times the door
 was clicked.
 This is why discoveries 1-3 alone were insufficient: even with double-click
 detection working, the correct gate firing, and `CollisionExemption`
 widened, the registry still held the stale closed state and the door
 stayed solid.
 **Fix:** Used the pre-existing `_entitiesByServerGuid` reverse-lookup
 dictionary on `GameWindow` (populated at entity registration in
 `OnLiveCreateObject` since Phase 6.6/6.7). `OnLiveStateUpdated` now does:
 ```csharp
 if (_entitiesByServerGuid.TryGetValue(parsed.Guid, out var entity))
    _physicsEngine.ShadowObjects.UpdatePhysicsState(entity.Id, parsed.PhysicsState);
 ```
 The `entityId=` field was added to the `[setstate]` diagnostic log line
 specifically to make this translation visible and greppable:
 `[setstate] guid=0x7A9B4015 entityId=0x000F4245 state=0x0001000C`.
 **Why this was missed:** L.2g slice 1's unit tests operated at the
 `ShadowObjectRegistry` level directly, calling `UpdatePhysicsState` with
 an `entity.Id` (not a server GUID). The integration was never exercised
 end-to-end before B.4b's visual test. The two tests `UpdatePhysicsState_FlipsEthereal_*`
 were correct in isolation; the broken layer was one level above them
 (the handler → registry call site).
 **Why the "multiple doors" misdiagnosis occurred:** Before slice 1c was
 identified, the `[resolve]` probes showed wall hits attributed to
 `obj=0x000F4245` while the clicked door's ServerGuid was `0x7A9B4015`.
 Initial read: "these are two different entities blocking the threshold."
 Slice 1c clarified: both IDs refer to the same door — `0x000F4245` is
 the local entity ID, `0x7A9B4015` is the server GUID for the same entity.
 The ID-space mismatch was the cause of both the collision-not-clearing
 AND the "different object" misread.
 ---
 ## Open notes / follow-ups
 ### Door swing animation (#58)
 When ACE opens a door it broadcasts **two** packets, not one:
 1. `SetState (0xF74B)` — the collision-bit flip. **Handled by L.2g slice 1.**
 2. `UpdateMotion (0xF74D)` with stance/command `(NonCombat, On)` — the
   swing animation cycle. **NOT handled.**
 acdream's `UpdateMotion` pipeline is currently scoped to player + creature
 animation (Phase L.3). Non-creature entities like doors do not receive
 cycle commands. The door therefore opens (becomes passable) but has no
 visible swing animation.
 Filed as **issue #58**. Scope is unknown — routing `UpdateMotion` to
 non-creature `WorldEntity` instances could be quick (few lines), or the
 `AnimationSequencer` may have creature-specific assumptions that require
 audit first. Filed as M1-deferred polish; it does not block the demo
 scenario.
 ### Door toggle behavior
 ACE doors toggle on each Use: first double-click opens, subsequent
 double-click closes (re-sends `SetState` with `state=0x00000000`, restoring
 collision). This is correct ACE behavior and matches retail. No issue to file.
 Rapid double-clicks (faster than ACE's server-tick processing) will open
 then close in quick succession — each Use lands as a distinct game action.
 Expected behavior; no fix needed.
 ### Multiple-door misdiagnosis (historical note)
 While slice 1c was still unidentified, the `[resolve]` diagnostic showed:
 ```
 [resolve] ... obj=0x000F4245 wall hit
 [B.4b] use guid=0x7A9B4015 ...
 [setstate] guid=0x7A9B4015 state=0x0001000C
 [resolve] ... obj=0x000F4245 wall hit (unchanged!)
 ```
 Initial misdiagnosis: there must be a *different* door entity (`0x000F4245`)
 blocking the threshold whose state was never updated. Slice 1c revealed:
 both IDs refer to the same door — one is the server GUID (network space),
 the other is the local entity ID (registry space). The registry update was
 targeting the server GUID (which missed), so the local-ID-keyed entry
 stayed solid.
 ### Selection HUD / hover-highlight / brackets
 Out of B.4b scope per design spec §Non-goals. The `_selectedGuid` field on
 `GameWindow` is populated (stores the last-picked entity's server GUID), but
 nothing renders a selection bracket, hover highlight, or target nameplate.
 That is M2/M3 HUD work (Phase D.6).
 ### BuildPickUp (F key) + UseWithTarget UX
 `InteractRequests.BuildPickUp` exists (as an alias of `BuildUse`). The
 `SelectionPickUp` input action and the F-key binding exist. But
 `OnInputAction` has no case for `SelectionPickUp` — pick-up-by-F-key is
 still unimplemented. Same for `UseWithTarget` (requires a secondary target
 selection UX). Both deferred to a follow-up phase; not M1-blocking.
 ---
 ## Next session
 **M1 demo progress as of this branch:**
 - ✅ "walk through Holtburg without getting stuck" — Phase L.2 in progress (outdoor collision works; CBuildingObj interior still deferred to L.2d).
 - ✅ "open the inn door" — **done** (B.4b, this branch).
 - ⬜ "click an NPC" — pick + Use wiring exists now; depends on ACE NPC handler responding to Use.
 - ⬜ "pick up an item" — `BuildPickUp` + F-key wiring not yet in `OnInputAction`.
 **Recommended next steps (in M1 critical-path order):**
 1. **Door swing animation (#58)** — cosmetic M1 polish. Route
   `UpdateMotion (0xF74D)` to non-creature entities so the door visually
   swings. Could be quick (30 min) or moderate (2 hrs with AnimationSequencer
   audit). Worth a spike before committing to an estimate.
 2. **Chronic open-issue triage** — #2 (lightning), #4 (horizon-glow), #28
   (aurora), #29 (cloud thinness), #37 (humanoid coat), #41 (remote-motion
   blips) have been deferred since April/early-May. Link each to a future
   phase or downgrade. ~1 hour. Not M1-blocking but surfaces the real backlog.
 3. **More Phase C visual-fidelity** — C.2 (dynamic point lights), C.3
   (palette tuning), C.4 (double-sided translucent polys). World still reads
   "old" without local lighting on fireplaces/lamps.
 ---
 ## Reproducibility
 Same launch recipe as before. For reproducing the visual test:
 ```powershell
 $env:ACDREAM_DAT_DIR        = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE           = "1"
 $env:ACDREAM_TEST_HOST      = "127.0.0.1"
 $env:ACDREAM_TEST_PORT      = "9000"
 $env:ACDREAM_TEST_USER      = "testaccount"
 $env:ACDREAM_TEST_PASS      = "testpassword"
 $env:ACDREAM_DEVTOOLS       = "1"
 $env:ACDREAM_PROBE_BUILDING = "1"
 $env:ACDREAM_PROBE_RESOLVE  = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug 2>&1 |
  Tee-Object -FilePath "launch-b4b.log"
 ```
 Walk to the Holtburg inn doorway. Double-left-click the closed Door. Walk
 through. Subsequent double-clicks will close and re-open (ACE toggle).
 After closing the client, grep for:
 ```powershell
 Select-String -Path launch-b4b.log -Pattern "SelectDblLeft|pick guid|use guid|setstate.*entityId"
 ```
 Expected:
 - `[input] SelectDblLeft DoubleClick` — dispatcher fires on second click within 500ms.
 - `[B.4b] pick guid=0x7A9B4015 name=Door` — ray hits the door.
 - `[B.4b] use guid=0x7A9B4015 seq=N` — Use message sent.
 - `[setstate] guid=0x7A9B4015 entityId=0x000F4245 state=0x0001000C` — ACE reply processed, translation confirmed.
 ---
 ## Worktree state at handoff
 - Branch `claude/compassionate-wilson-23ff99`.
 - 9 implementation commits + 3 plan/spec commits ahead of `eea9b4d`
  (the L.2g slice 1 merge from the previous session).
 - Controller should run a code review, then merge to main.
 - Do NOT rebase or squash — each commit tells a diagnostic story that
  the next phase's debugging may need.
--- a/docs/research/2026-05-13-b4c-shipped-handoff.md
+++ b/docs/research/2026-05-13-b4c-shipped-handoff.md
@ -1,346 +0,0 @@
 # Phase B.4c shipped — handoff (visual-verified 2026-05-13)
 **Date:** 2026-05-13.
 **Branch:** `claude/phase-b4c-door-anim` (ready to merge to main; do NOT merge here — controller handles that after code review).
 **Predecessors:**
 - [docs/research/2026-05-13-b4b-shipped-handoff.md](2026-05-13-b4b-shipped-handoff.md) — B.4b shipped handoff; interaction was the upstream dependency (Use message, SetState handling, collision exemption, double-click detection — all shipped there).
 - [docs/superpowers/specs/2026-05-13-phase-b4c-design.md](../superpowers/specs/2026-05-13-phase-b4c-design.md) — B.4c design spec.
 - [docs/superpowers/plans/2026-05-13-phase-b4c-plan.md](../superpowers/plans/2026-05-13-phase-b4c-plan.md) — B.4c implementation plan (4 tasks).
 ---
 ## TL;DR
 Phase B.4c **shipped end-to-end and is visual-verified 2026-05-13.** The M1
 demo target *"open the inn door"* now has **full visual feedback** — the door
 swings open when double-clicked and swings closed again when ACE toggles it
 back. 4 implementation commits implement and fix door-specific spawn-time
 `AnimationSequencer` registration + `UpdateMotion` routing + stance-value
 correctness.
 The plan estimated "2 tasks, door spawn-time registration + UM diagnostic."
 Visual testing surfaced **two bonus discoveries** beyond the plan:
 1. The plan's `NonCombatStance` constant was wrong: `0x80000001` (from
   creature motion table conventions) should be `0x8000003D` (from AC's
   `MotionStance.NonCombat = 0x0000003D`). Wrong constant → wrong
   `HasCycle` lookup → `SetCycle` never fires → sequencer empty →
   per-frame part rebuild collapses to entity origin → doors render halfway
   underground.
 2. The `AnimationSequencer`'s link→cycle boundary transition produces a
   brief one-frame flash through the prior pose at the end of the door-swing
   animation. Not B.4c-specific — it is the sequencer's general link+cycle
   queue mechanics. Deferred as issue #61.
 Issue #58 (door swing animation) is closed. Issues #61 + #62 (cycle-boundary
 flash; PARTSDIAG null-guard) are filed as M1-deferred polish.
 ---
 ## What shipped on this branch
 | # | Commit | Subject | Task |
 |---|---|---|---|
 | 1 | `9053860` | `feat(B.4c): door spawn-time AnimationSequencer with state-seeded initial cycle` | Task 1 |
 | 2 | `b89f004` | `feat(B.4c): [door-cycle] diagnostic in OnLiveMotionUpdated` | Task 2 |
 | 3 | `8a9b15e` | `refactor(B.4c): share IsDoorName predicate + durable comment + use UM locals` | Task 2 review |
 | 4 | `454d88e` | `fix(B.4c): correct NonCombat stance value (0x3D, not 0x01) + read spawn.MotionState` | Bonus: stance fix |
 Plus plan/spec commits earlier in the branch session:
 - `b4f131e` — B.4c design spec.
 - `6ae38f7` — B.4c implementation plan (4 tasks).
 **Build:** clean. **Tests:** existing test suite passes; no new unit tests added
 (the door-cycle registration path runs in-process with a live GameWindow; pure
 unit tests would require a MotionTable + AnimationSequencer integration harness).
 ---
 ## What the code does end-to-end
 When the world loads, any entity whose name contains "Door" (checked via the
 shared `GameWindow.IsDoorName(string)` helper, committed as part of Task 2
 review) is registered in the **door-animation side-track** at spawn time. This
 happens inside `GameWindow.OnLiveEntitySpawnedLocked`, which branches on
 `IsDoorSpawn(spawn)` before reaching the standard creature/player paths.
 ### At world load (spawn time)
 1. `IsDoorSpawn(spawn)` — delegates to `IsDoorName(spawn.Name)`, which
   returns `name == "Door"`. Detection by server-sent name string only.
   Cheap, exact, no WeenieType lookup. If a future ACE localizes "Door"
   or sends a different name, those entities silently won't animate —
   acceptable per B.4c's "doors only at English Holtburg" scope.
 2. **Initial state seed** — the door's `PhysicsState` from `spawn` carries the
   open/closed bit. The code reads `spawn.PhysicsState` (or
   `spawn.MotionState?.Stance` as a fallback for unusual doors with explicit
   stance data) to determine whether to seed the sequencer with the `Off`
   (closed) or `On` (open) cycle.
 3. **AnimationSequencer registration** — a fresh `AnimationSequencer` is
   created for the door entity's `MotionTableId` (from `spawn`). Then:
   ```csharp
   var style = 0x80000000u | (uint)MotionStance.NonCombat; // = 0x8000003D
   var cycleCmd = isOpen ? MotionCommand.On : MotionCommand.Off;
   sequencer.SetCycle(style, (uint)cycleCmd, speed: 0f);
   ```
   The fully-initialized `AnimatedEntity` (with the seeded `Sequencer`) is
   registered into the existing `_animatedEntities` dict keyed by `entity.Id`
   — same dict that holds creatures and the player. `Animation = null!`
   (the null-forgiving suppression matches an existing pattern at
   `GameWindow.cs:7885` for sequencer-driven entities where the legacy
   `Animation` field is unused). At the first per-frame `Advance(dt)`
   call from `TickAnimations`, the sequencer produces the correct
   rest-pose frames for the door's current state.
 4. **Log evidence at spawn:**
   ```
   [door-anim] registered guid=0x7A9B403A entityId=0x000F4291 mtable=0x09000202 initialStyle=0x8000003D initialCycle=0x4000000C
   ```
   `0x4000000C` = `MotionCommand.Off` with the upper flag bits — the door is
   closed at spawn, matching the initial world state.
 ### When the door opens (UpdateMotion arrives)
 ACE broadcasts `UpdateMotion (0xF74D)` with `stance=0x003D` (NonCombat) and
 wire `cmd=0x000C` (which `MotionCommandResolver.ReconstructFullCommand`
 maps to full motion `0x4000000B` = `MotionCommand.On` = door open).
 B.4c does NOT add a new dispatch path here — the existing
 `OnLiveMotionUpdated` handler already routes via the `_animatedEntities`
 dict + per-entity `Sequencer`, the same code path creatures use. The
 only B.4c contribution at UM dispatch is the new `[door-cycle]`
 diagnostic gated on `IsDoorName(doorInfo.Name)`. Before B.4c, doors
 silently dropped at the `_animatedEntities.TryGetValue` check at
 `GameWindow.cs:3036` because doors weren't registered; B.4c's Task 1
 spawn-time branch fixed that.
 The sequencer transitions from the `Off` cycle (static closed pose) through
 the door-swing link animation to the `On` cycle (static open pose).
 **Log evidence:**
 ```
 UM guid=0x7A9B403A mt=0x00 stance=0x003D cmd=0x000C spd=0.00 | seq now style=0x8000003D motion=0x4000000B
 [door-cycle] guid=0x7A9B403A stance=0x003D cmd=0x000C
 ```
 The `[door-cycle]` line is the new B.4c diagnostic (gated on
 `ACDREAM_PROBE_BUILDING=1`). The `seq now motion=0x4000000B` shows the
 sequencer's current motion state after the `SetCycle` call.
 ### SetState chain (from B.4b + L.2g, unchanged)
 Simultaneously with `UpdateMotion`, ACE also sends `SetState (0xF74B)`:
 ```
 [setstate] guid=0x7A9B... state=0x0001000C
 ```
 This is the B.4b / L.2g chain: `ShadowObjectRegistry.UpdatePhysicsState` flips
 the door's cached state, `CollisionExemption.ShouldSkip` exempts on ETHEREAL-alone,
 and the player can walk through. B.4c is additive — it only adds the animation
 layer; it does not touch the collision path.
 ### When the door closes
 ACE toggles on the next Use: `UpdateMotion` with `cmd=0x000B` (Off = close).
 The sequencer transitions from the `On` cycle (open pose) through the door-swing
 link animation (reversed) to the `Off` cycle (closed pose).
 **Log evidence:**
 ```
 UM guid=0x7A9B403A mt=... cmd=0x000B ... motion=0x4000000C
 [door-cycle] guid=0x7A9B... cmd=0x000B
 [setstate] guid=0x7A9B... state=0x00010008
 ```
 ### Per-frame mesh rebuild
 The door sequencer integrates into `GameWindow.TickAnimations` via the same
 `_animatedEntities` dict that holds creatures. Each frame, `ae.Sequencer.Advance(dt)`
 is called and the resulting per-part transforms drive the same `MeshRefs` rebuild
 that creature entities use (sequencer branch at `GameWindow.cs:7497`; doors
 never enter the legacy slerp `else` branch). This is the reason the stance-value
 bug produced underground doors: with the wrong style key (`0x80000001`)
 `HasCycle` returned false, the sequencer was empty at spawn, `Advance` returned
 identity frames, and the per-frame part-matrix rebuild received `Vector3.Zero /
 Quaternion.Identity` for every part — collapsing them all to the entity origin.
 ---
 ## The two bonus discoveries
 ### 1. NonCombatStance constant was wrong: 0x01 vs 0x3D (`454d88e`) — THE render blocker
 **Root cause:** The B.4c design spec specified the initial-cycle style key as:
 ```csharp
 uint style = 0x80000000u | (uint)MotionStance.NonCombat; // spec said 0x80000001
 ```
 The spec's comment was wrong. `MotionStance.NonCombat` in acdream (and retail)
 is `0x0000003D`, not `0x00000001`. The value `0x01` is a creature-specific
 variant. The style key for the door's cycle lookup must be `0x8000003D`.
 With the wrong style key:
 - `sequencer.HasCycle(0x80000001, MotionCommand.Off)` → false.
 - `SetCycle(0x80000001, ...)` enqueued a cycle that was never reachable.
 - On first `Advance(dt)`, the sequencer returned 0 part-frames.
 - The per-frame mesh rebuild at `GameWindow.cs:7691` iterated 0 frames, leaving
  every door part at the entity root origin (which is the door's structural
  pivot, typically near the hinge). For inn doors this pivot is at roughly
  floor level, so all the door's mesh parts collapsed to that single point,
  rendering as a thin sliver partway underground.
 **Fix:** Corrected the constant. Additionally, added a defensive read of
 `spawn.MotionState?.Stance` as the source of the stance value where available,
 so unusual doors with explicit motion state (possible in custom ACE content) use
 their actual stance rather than the hardcoded NonCombat assumption:
 ```csharp
 var stance = spawn.MotionState?.Stance ?? MotionStance.NonCombat;
 uint style = 0x80000000u | (uint)stance;
 ```
 **Verification:** After this fix, the `[door-anim]` log line showed
 `initialStyle=0x8000003D` (correct), and doors appeared at the correct floor
 level and height at world load.
 ### 2. AnimationSequencer link→cycle boundary flash (deferred as #61)
 **Observed:** User reports "weird flapping at end of animation when it opens.
 It is like it flaps back to closed quickly then open. Like really quickly."
 Both open and close animations exhibit this flash.
 **Root cause hypothesis:** `AnimationSequencer.SetCycle` enqueues a transition
 link (the actual swing animation) followed by the target cycle (the door's
 rest pose — likely a single-frame static "open" or "closed" pose). At the link→
 cycle boundary, the sequencer evaluates the cycle's frame 0 before the cycle
 settles into its natural rest position. If the link's last frame and the
 cycle's frame 0 don't match exactly (which is common for one-shot door motions
 versus the continuous idle cycles the sequencer was designed for), the renderer
 sees one frame of the "wrong" pose at the link boundary.
 **Why not B.4c-specific:** This is the sequencer's general link+cycle queue
 boundary semantics. Any entity that uses a one-shot `SetCycle` transition
 (rather than a continuous idle cycle) will exhibit this if the link/cycle
 boundary frames diverge. The door case just makes it visible because the
 swing duration is short (1-2 seconds) and the user is watching closely.
 **Deferred:** Filed as issue #61. Workaround: the flash is brief (~1 frame,
 ~16ms at 60 FPS) and does not affect the door's usability. M1 is met without
 this fix.
 ---
 ## Open notes / follow-ups
 ### #61 — AnimationSequencer link→cycle frame-0 flash (filed this session)
 See Bonus discovery #2 above. Deferred as M1-deferred polish. Low severity.
 Acceptance: door swing animations play cleanly with no intermediate closed/open
 pose flash at the link→cycle transition.
 ### #62 — PARTSDIAG null-guard for sequencer-driven entities (filed this session)
 The PARTSDIAG block at `GameWindow.cs:7657` reads `ae.Animation.PartFrames`
 without a null-guard. B.4c introduced `Animation = null!` for sequencer-driven
 door entities. Today this is safe (doors never enter `_remoteDeadReckon` because
 ACE never sends UpdatePosition for them). Deferred as low-severity latent crash.
 One-line fix when addressed.
 ### Chests, levers, traps
 The `IsDoorName` / `IsDoorSpawn` predicate correctly gates on door entities only.
 Other interactable non-creature entities (chests, levers, traps) will still
 silently drop their `UpdateMotion` commands — they are not covered by B.4c and
 no issue has been filed for them yet. When those animations become relevant
 (M2/M3 inventory + dungeon content), the same spawn-time registration pattern
 can be extended: broaden the detection predicate beyond `name == "Door"` and
 register additional entity types in the existing `_animatedEntities` dict via
 the same sibling branch.
 ### Door toggle behavior
 Unchanged from B.4b. ACE doors toggle on each Use: first double-click opens,
 subsequent double-click closes. Both transitions now play the correct swing
 animation (open swing on open, close swing on close).
 ---
 ## Next session
 **M1 demo progress as of this branch:**
 - "Walk through Holtburg without getting stuck" — Phase L.2 in progress (outdoor collision works; `CBuildingObj` interior still deferred to L.2d).
 - "Open the inn door" — **DONE with full visual feedback** (B.4b interaction + B.4c animation, this branch). Door swings open AND closed.
 - "Click an NPC" — pick + Use wiring exists (from B.4b); depends on ACE NPC handler responding to Use correctly.
 - "Pick up an item" — `BuildPickUp` + F-key wiring not yet in `OnInputAction`. Post-B.4b/B.4c deferred.
 **Recommended next steps (in M1 critical-path order):**
 1. **"Click an NPC" verification spike** — B.4b's WorldPicker + Use messaging
   is already wired. The question is whether ACE NPCs respond to Use and what
   they broadcast back. A quick spike: stand near an NPC in Holtburg,
   double-click, check what ACE sends back. If ACE sends recognizable response
   messages, wire them; if it is silent, investigate ACE's NPC handler
   configuration for testaccount.
 2. **Phase B.5 — Ground item pickup (F key)** — `SelectionPickUp` input action
   + F-key binding exist but `OnInputAction` has no case. `BuildUse` is the
   same wire format as `BuildPickUp`. Adding the `SelectionPickUp` case to
   the switch and routing to `InteractRequests.BuildPickUp` is a one-commit
   addition.
 3. **Triage chronic open-issue list** — #2 (lightning), #4 (sky horizon-glow),
   #28 (aurora), #29 (cloud thinness), #37 (humanoid coat), #41
   (remote-motion blips) have been open since April/early-May. Link each to
   a future phase or downgrade. ~1 hour.
 4. **#61 fix (cycle-boundary flash)** — low-severity M1 polish. If the user
   finds the flash distracting during the M1 demo record, address before
   milestone wrap; otherwise defer to M2 animation quality pass.
 ---
 ## Reproducibility
 Same launch recipe as B.4b. For reproducing the visual test:
 ```powershell
 $env:ACDREAM_DAT_DIR        = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE           = "1"
 $env:ACDREAM_TEST_HOST      = "127.0.0.1"
 $env:ACDREAM_TEST_PORT      = "9000"
 $env:ACDREAM_TEST_USER      = "testaccount"
 $env:ACDREAM_TEST_PASS      = "testpassword"
 $env:ACDREAM_DEVTOOLS       = "1"
 $env:ACDREAM_PROBE_BUILDING = "1"
 $env:ACDREAM_PROBE_RESOLVE  = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug 2>&1 |
  Tee-Object -FilePath "launch-b4c.log"
 ```
 Walk to the Holtburg inn doorway. Watch the `[door-anim]` lines appear in the
 log as each door entity spawns (verifies correct style=0x8000003D and initial
 cycle). Double-left-click a closed door. Watch the swing animation. Walk
 through. Wait ~30s (ACE auto-close). Watch the close animation.
 After closing the client, grep for:
 ```powershell
 Select-String -Path launch-b4c.log -Pattern "door-anim|door-cycle|setstate"
 ```
 Expected:
 - `[door-anim] registered guid=... initialStyle=0x8000003D initialCycle=0x4000000C` — correct style + Off initial cycle for each closed door.
 - `[door-cycle] guid=... stance=0x003D cmd=0x000C` — open UpdateMotion processed.
 - `[setstate] guid=... state=0x0001000C` — ACE collision-flip processed (from B.4b / L.2g).
 - `[door-cycle] guid=... cmd=0x000B` — close UpdateMotion processed.
 - `[setstate] guid=... state=0x00010008` — ACE close collision-flip processed.
 ---
 ## Worktree state at handoff
 - Branch `claude/phase-b4c-door-anim`.
 - 6 commits ahead of `3e08e10` (the B.4b+L.2g merge from this morning):
  2 docs/spec/plan commits + 4 implementation commits.
 - Controller should run a code review, then merge to main.
 - Do NOT rebase or squash — each commit tells a diagnostic story that the
  next phase's debugging may need.
--- a/docs/research/2026-05-13-b5-pickup-handoff.md
+++ b/docs/research/2026-05-13-b5-pickup-handoff.md
@ -1,235 +0,0 @@
 # Phase B.5 — BuildPickUp + ground-item interaction — fresh-session handoff
 **Date:** 2026-05-13 evening (after B.4c ship).
 **Branch:** `claude/phase-b5-pickup` (renamed from `claude/investigate-npc-click`).
 **Worktree:** `C:\Users\erikn\source\repos\acdream\.claude\worktrees\investigate-npc-click` (directory name kept; only the branch was renamed).
 **Predecessor on main:** `e7842e0` — `Merge branch 'claude/phase-b4c-door-anim' — Phase B.4c door swing animation`.
 ---
 ## TL;DR
 After B.4c shipped (doors visibly swing open/close), three of M1's four
 demo targets are met: *walk through Holtburg*, *open the inn door*, and
 likely *click an NPC* (per the investigation below; not yet
 visual-verified). The remaining target is *pick up an item*, which
 needs a new outbound wire builder + F-key handler in `GameWindow`.
 Phase **B.5** is the slice that closes M1's "click + pickup" demo
 path. Scope: ~50 LOC across two existing files (no new files).
 Implementation pattern mirrors B.4b's outbound Use chain.
 ---
 ## Investigation findings (carry forward)
 Before starting B.5 work, the controller agent investigated whether
 B.4b's existing `BuildUse` chain already handles "click an NPC". Code
 reading produced this answer: **yes, the basic chat-dialogue case
 should already work end-to-end with zero new code**. Verify
 opportunistically during B.5's visual test by clicking an NPC while
 in-world.
 Specifically:
 - **ACE's `Creature.ActOnUse`** at
  `references/ACE/Source/ACE.Server/WorldObjects/Creature.cs:334`
  defers to `base.OnActivate → EmoteManager.OnUse()`. The emote
  manager walks the creature's emote table and emits `Tell`,
  `CommunicationTransientString`, `Motion`, and other game events.
 - **All those events are already wired** in
  `src/AcDream.Core.Net/GameEventWiring.cs`:
    - `Tell (0x0027)` → `chat.OnTellReceived` (line 78)
    - `CommunicationTransientString (0x028B)` → `chat.OnSystemMessage` (line 83)
    - `WeenieError / WeenieErrorWithString` → `chat.OnSystemMessage` (lines 139, 144)
  Plus `UpdateMotion (0xF74D)` is already routed for creature entities
  via `OnLiveMotionUpdated`.
 - **`UseDone (0x01C7)`** — the completion ack — has a parser at
  `GameEvents.ParseUseDone` but is **not registered** with the
  dispatcher. Silent drop. Harmless for the basic demo (the chat
  events arrive independently), but worth filing as a follow-up if not
  picked up by B.5.
 **Conclusion:** click-NPC chain is wired; no code change needed for the
 M1 demo target 3 acceptance. Verify in-world during B.5's launch.
 ---
 ## B.5 scope (decisions already made)
 | Decision | Value | Rationale |
 |---|---|---|
 | Trigger | F-key (`InputAction.SelectionPickUp`) | Already bound at `KeyBindings.cs:172` |
 | Target selection | Requires `_selectedGuid` (B.4b's renamed field) | Mirrors retail F-key behavior + B.4b's `UseSelected` pattern. User single-clicks the ground item to select, then F to pickup. |
 | Wire opcode | `GameAction.PutItemInContainer (0x0019)` | ACE source: `references/ACE/Source/ACE.Server/Network/GameAction/Actions/GameActionPutItemInContainer.cs` |
 | Wire payload | 12 bytes: `itemGuid (u32) + containerGuid (u32) + placement (i32)` | Same source |
 | Container destination | The player's own server guid (`_playerServerGuid`) | Single-bag pickup; bag-specific destinations are M2+ work |
 | Placement value | 0 (let server pick slot) | Simplest; placement-control UI is M2+ |
 | Visual feedback | Toast + `[pickup]` log line | No inventory UI yet; the existing `WieldObject` / `InventoryPutObjInContainer` server events already update `ItemRepository` so the state is correct internally |
 | Pick under cursor fallback | **NO** | Out of scope per user decision. Strict select-first UX. |
 Brainstorm explicitly **NOT** done with the user (interrupted before
 the design sections were presented). The new session should re-confirm
 these decisions are still desired before writing the spec — or just
 proceed if they remain obviously right.
 ---
 ## Three changes B.5 needs to land
 1. **`src/AcDream.Core.Net/Messages/InteractRequests.cs`** — add
   `BuildPickUp(uint gameActionSequence, uint itemGuid, uint containerGuid, int placement)`.
   Pattern: same as the existing `BuildUseWithTarget` builder at line
   51 of that file. 20-byte total body (`0xF7B1 envelope + seq + opcode
   0x0019 + 12-byte payload`).
 2. **`src/AcDream.App/Rendering/GameWindow.cs`** — add a private helper
   `SendPickUp(uint itemGuid)`:
   - Gate on `_liveSession?.CurrentState == InWorld` (same pattern as
     B.4b's `SendUse`).
   - `seq = _liveSession.NextGameActionSequence()`.
   - `body = InteractRequests.BuildPickUp(seq, itemGuid, _playerServerGuid, 0)`.
   - `_liveSession.SendGameAction(body)`.
   - Diagnostic: `Console.WriteLine($"[pickup] item=0x{itemGuid:X8} container=0x{_playerServerGuid:X8} seq={seq}")`.
 3. **`src/AcDream.App/Rendering/GameWindow.cs` `OnInputAction` switch**
   — add `case InputAction.SelectionPickUp:` near the other `Select*` /
   `UseSelected` cases (B.4b added those around line 8633+). Body:
   `if (_selectedGuid is uint sel) SendPickUp(sel); else _debugVm?.AddToast("Nothing selected");`.
 That's the whole code change. ~50 LOC including diagnostics.
 ---
 ## Likely ID-translation gotcha (the L.2g slice 1c pattern)
 B.4b's L.2g slice 1c surfaced an ID-space mismatch: the **`BuildUse`**
 wire builder takes a `targetGuid` which is `entity.ServerGuid`, but
 `ShadowObjectRegistry` keys by `entity.Id`. For `BuildPickUp`:
 - `itemGuid` argument must be `entity.ServerGuid` (the server's
  identifier — ACE looks it up in its world). ✅ B.4b's picker returns
  `ServerGuid`, so `_selectedGuid` already carries the right value.
 - `containerGuid` argument must be `_playerServerGuid` (the server's
  identifier for the player). ✅ Already a ServerGuid in `GameWindow`.
 So B.5 should NOT hit the same ID-mismatch trap L.2g slice 1c did. But
 re-check at implementation time.
 ---
 ## ACE inbound chain (already wired)
 After ACE processes a `BuildPickUp`, it broadcasts:
 - `0x019B InventoryPutObjInContainer` — moves the item record into the
  player's container. Already wired to
  `ItemRepository.MoveItem(itemGuid, containerGuid, placement)` at
  `GameEventWiring.cs:239`.
 - `RemoveObject` for the world-spawned item — already wired (existing
  despawn path removes the ground item from view).
 - Possibly `WieldObject` if the item auto-equips — already wired
  (`GameEventWiring.cs:231`).
 No new inbound wiring needed for the minimum demo. The user will see:
 1. Click ground item → selection updates.
 2. Press F → diagnostic logs, packet sent.
 3. ACE processes; sends inventory + despawn events.
 4. Item disappears from ground.
 5. (No inventory UI yet, but item is in `ItemRepository`.)
 ---
 ## Acceptance criteria
 - [ ] `dotnet build` green.
 - [ ] `dotnet test` green: 1046 / 8 pre-existing-baseline fail
  (unchanged from main HEAD).
 - [ ] At Holtburg, drop a test item on the ground (via `/drop` server
  command or have ACE spawn one for the test character), then:
  - [ ] Single-click the item — `_selectedGuid` updates, B.4b's
    `[pick]` diagnostic shows the item's guid.
  - [ ] Press F — log shows `[pickup] item=0x... container=0x5000000A
    seq=N`.
  - [ ] Item disappears from the ground.
  - [ ] No regressions on door interaction (B.4b/B.4c still work).
 - [ ] **Bonus: click-NPC verification.** While in-world, single-click
  an NPC and press F (or double-click). Expected: NPC chat appears in
  the chat panel. If it does → M1 demo target 3 confirmed met. If not
  → file the gap.
 - [ ] `docs/ISSUES.md` closure entry for whatever issue (if any) was
  filed for the pickup gap.
 - [ ] Roadmap + CLAUDE.md updated.
 ---
 ## Reproducibility
 Same launch recipe as B.4c. Per CLAUDE.md "Logout-before-reconnect",
 wait 20-45s between client launches to let ACE clear stale sessions.
 ```powershell
 Get-Process -Name AcDream.App -ErrorAction SilentlyContinue | Stop-Process -Force
 Start-Sleep -Seconds 20
 $env:ACDREAM_DAT_DIR        = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE           = "1"
 $env:ACDREAM_TEST_HOST      = "127.0.0.1"
 $env:ACDREAM_TEST_PORT      = "9000"
 $env:ACDREAM_TEST_USER      = "testaccount"
 $env:ACDREAM_TEST_PASS      = "testpassword"
 $env:ACDREAM_DEVTOOLS       = "1"
 $env:ACDREAM_PROBE_BUILDING = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug 2>&1 |
  Tee-Object -FilePath "launch-b5.log"
 ```
 Log grep:
 ```powershell
 Select-String -Path launch-b5.log -Pattern "pickup|\[pick\] guid=|UseDone|\[B.4b\] pick"
 ```
 ---
 ## Carry-overs from B.4c (don't lose track)
 - **#61** — AnimationSequencer link→cycle frame-0 flash on door swing.
  Visible as brief flap at end of swing animation. Low-severity polish.
 - **#62** — PARTSDIAG null-guard for sequencer-driven entities.
  Latent; not currently reachable for doors. One-line fix.
 - **Worktree at `.claude/worktrees/phase-b4c-door-anim`** still on disk
  (submodules blocked `git worktree remove` per B.4b precedent). Manual
  cleanup after this session: `rm -rf` the directory + `git worktree
  prune` + `git branch -D claude/phase-b4c-door-anim`.
 ---
 ## State at handoff
 - **Branch:** `claude/phase-b5-pickup` (renamed from
  `claude/investigate-npc-click`).
 - **Worktree directory:** `.claude/worktrees/investigate-npc-click`
  (cosmetic mismatch with branch name; harmless).
 - **Commits ahead of main:** 1 after this handoff lands.
 - **Main HEAD:** `e7842e0`.
 - **Build state:** worktree compiles cleanly (verified via
  `dotnet build -c Debug`). Tests at 1046/8 baseline.
 - **Submodule state:** `references/WorldBuilder` initialized.
  `references/ACE` NOT initialized in this worktree — use the main
  repo's `references/ACE` for ACE source reads, or init via
  `git submodule update --init --depth=1 references/ACE` if extensive
  reading is needed.
 ---
 ## Why a fresh session
 This session accumulated ~10 hours of context across L.2g, B.4b, and
 B.4c — the working set is large enough that starting B.5 cold lets the
 new session work with a clean context budget and avoids the compaction
 risk that hit the prior B.4b session.
 The prompt for the new session is in the controller's reply that
 created this handoff (the chat message immediately after this commit).
--- a/docs/research/2026-05-13-l2d-slice1-shipped-handoff.md
+++ b/docs/research/2026-05-13-l2d-slice1-shipped-handoff.md
@ -1,251 +0,0 @@
 # L.2d slice 1 + 1.5 shipped — handoff
 **Date:** 2026-05-13 evening, immediately after slice 1.5 + Holtburg verification.
 **Branch:** `claude/sharp-chatelet-023dda` (ready to merge to main).
 **Predecessor:** [2026-05-12-l2a-shipped-l2d-handoff.md](2026-05-12-l2a-shipped-l2d-handoff.md).
 ---
 ## TL;DR
 The "I can't walk through Holtburg doorways" symptom is **a closed Door
 entity blocking the threshold**, not a building-collision-mesh bug.
 Building BSP collision is healthy. The L.2a handoff's framing
 ("per-cell walkability missing") was wrong, the L.2d-slice-1 spec's
 reframe ("BSP shape fidelity, three hypotheses X/Y/Z") was also
 wrong, and the actual answer fell out of one capture once the probe
 labeling was fixed (slice 1.5). **L.2d as scoped is essentially
 closed.** The remaining work is door-state handling — a different
 sub-phase entirely.
 ---
 ## What shipped on this branch
 | Commit | What |
 |---|---|
 | [`92cd723`](.) | `docs(phys L.2d): design spec for slice 1 BSP-hit diagnostic + L.2d reframe` |
 | [`66dc23e`](.) | `feat(phys L.2d slice 1): BSP-hit diagnostic probe + plan-of-record correction` |
 | [`8bacef0`](.) | `fix(phys L.2d slice 1.5): probe captures hit poly under StepSphereUp recursion` |
 What slice 1 + 1.5 give the next agent:
 - **`ACDREAM_PROBE_BUILDING=1`** env var + DebugPanel checkbox: one
  multi-line `[resolve-bldg]` entry per attributed BSP shadow-entry hit
  (partIdx, hasPhys, bspR vs vAabbR, world-space entOrigin_lb, actual
  hit polygon vertices in both local and world coords). Reliable
  under `StepSphereUp` recursion after the slice 1.5 fix.
 - **`[entity-source]`** one-time log line per `ShadowObjects.Register`
  call, gated on the same flag. Makes `entityId=0xA9B479` in a
  probe line greppable to its WorldEntity source.
 - **`PhysicsDiagnostics.LastBspHitPoly`** — diagnostic side-channel
  for any future "what poly did BSPQuery hit" question.
 - **The two synthetic tests** in
  [PhysicsDiagnosticsTests.cs](../../tests/AcDream.Core.Tests/Physics/PhysicsDiagnosticsTests.cs)
  pin the side-channel API contract.
 ---
 ## What the trace actually showed
 After slice 1.5, walking acdream into a Holtburg town doorway
 captured 242 real BSP hit polys + 122 cylinder n/a. **Definitive
 finding:**
 ```
 live: spawn guid=0x7A9B4015 name="Door" setup=0x020019FF
      pos=(132.6,17.1,94.1)@0xA9B40029 itemType=0x00000080
 [entity-source] id=0x000F4244 entityId=0x000F4244 src=0x020019FF
      gfxObj=0x020019FF lb=0xA9B40029 type=Cylinder note=server-spawn-root
 ```
 The blocker is a **Door entity** — Setup `0x020019FF` named `"Door"` —
 server-spawned by ACE at the threshold of each Holtburg town building.
 **Five Doors** appear across Holtburg (landblock cells `0xA9B40029`,
 `0xA9B40154`, `0xA9B40155`); same Setup DID reused. ItemType
 `0x00000080` = Misc category in AC's ItemType flags.
 Each Door's Cylinder collision blocks the player. The building BSP
 *also* fires (the L.2a evidence the original handoff pointed at), but
 the BSP hits were the player **already pushed back by the Door
 cylinder** then grazing the doorframe — they look like wall collision
 but are a side effect of the Door cylinder push. Slice 1.5's per-tick
 multi-entity probe revealed this by showing `nObj=3` on every hit
 resolve: one Door + two sphere checks against the building BSP.
 The L.2a slice 2 handoff's expectation that doors would be in the
 `0xCC0Cxxxx` range was wrong; **doors are in `0x000Fxxxx`** (server-
 spawn-root range) because they're hydrated through the live
 `CreateObject` stream like NPCs, not the static landblock pipeline.
 ---
 ## What this means for L.2d
 L.2d as originally scoped ("Shape Fidelity: Sphere / CylSphere /
 Building Objects") is essentially **closed at this site**:
 - Building BSP is loaded, parsed, queried correctly. `bspR=13.99m` for
  GfxObj `0x01000A2B`, real triangles in real positions.
 - `Setup.CylSpheres` for Door (`0x020019FF`) is also loaded correctly
  — the cylinder is firing the cylinder collision path with sensible
  world-space radius.
 - No actual shape-fidelity bug observed at this test site.
 The remaining work is **door state handling**, which is a different
 class of problem entirely — it touches network (CreateObject
 PhysicsState bits), interaction (Use action on door entity), animation
 (door open/close animation state), and collision-state-toggle
 (ETHEREAL during open animation). That doesn't fit under L.2d's
 shape-fidelity umbrella.
 **Recommend reframing L.2d as "watch-and-wait":** keep the probes for
 future shape-fidelity work at other sites (dungeon walls, stairs,
 roofs), but don't plan more slices until a NEW shape-fidelity bug is
 observed with the probe-armed client.
 ---
 ## Side findings (latent bugs to file, not block this slice)
 ### 1. Building double-registration
 The trace shows the same WorldEntity registered TWICE in
 ShadowObjectRegistry:
 ```
 [entity-source] id=0xA9B47900 entityId=0xC0A9B479 ... type=BSP note=partIdx=0 hasPhys=true
 [entity-source] id=0xC0A9B479 entityId=0xC0A9B479 ... type=Cylinder note=mesh-aabb-fallback
 ```
 [GameWindow.cs:5625](../../src/AcDream.App/Rendering/GameWindow.cs:5625)
 gates the mesh-AABB-fallback on `entityBsp == 0`, but the BSP
 registration at [line 5530](../../src/AcDream.App/Rendering/GameWindow.cs:5530)
 DOES increment `entityBsp`. So the fallback shouldn't fire when BSP
 parts exist. Either `entityBsp` isn't being checked in the right
 scope, or there's a second mesh-AABB-fallback site that doesn't gate
 on `entityBsp`. Worth a short investigation + one-line fix.
 Filing as ISSUE candidate. Doesn't break anything observable yet
 (cylinder is too far from player to fire at this Holtburg site), but
 will cause confusion in any future "why does entity X have two
 ShadowEntries" trace.
 ### 2. PhysicsState / EntityCollisionFlags not in entity-source log
 The slice 1 `[entity-source]` log captures `id, entityId, src,
 gfxObj, lb, type, note, hasPhys` but **not** `state` (PhysicsState
 bits) or `flags` (EntityCollisionFlags). For any future
 ethereal-handling / IGNORE_COLLISIONS work — including the door
 state handling above — these would be required.
 Tiny slice 1.6 if the next agent needs them: add `state=0x{...:X8}
 flags={...}` to the format string. ~5 LOC, gated on the same
 ProbeBuilding flag.
 ---
 ## What the next session probably should NOT do
 - **Re-investigate Holtburg doorways with the same setup.** The
  evidence is conclusive; we're not going to find new information by
  re-running the probe at the same site.
 - **Port `CBuildingObj` or per-cell walkability infrastructure.**
  That was based on the original (wrong) hypothesis. ACE's
  `find_building_collisions` is six lines and doesn't use per-cell
  walkability; our equivalent is already in place implicitly.
 - **Start L.2d slice 2 as scoped in the design spec.** Hypotheses X /
  Y / Z don't apply — the trace ruled them all out. Update or close
  the spec.
 ---
 ## What the next session COULD do (in rough preference order)
 These are NOT prescribed; they're candidates for the project-level
 ordering discussion the user wants to have.
 1. **Door state handling sub-phase.** New phase (call it L.2g or
   nest under B.4). Touches: Use action → server door toggle,
   PhysicsState ETHEREAL bit honor, door open/close animation,
   collision-shape suppression during open animation. Probably
   2-3 commits.
 2. **Fix the building double-registration latent bug** (side
   finding #1). One-liner, no real impact today but cleaner trace
   later.
 3. **Capture slice 1.6** (state + flags in entity-source log) if
   any future ethereal-related work is on the immediate horizon.
   Otherwise defer.
 4. **Move to a different L.2 sub-phase entirely** — L.2e
   (cell ownership / `find_cell_list` / outdoor seam updates) or
   L.2f (real-DAT + retail-observer conformance). Both are scoped
   in [the L.2 plan-of-record](../plans/2026-04-29-movement-collision-conformance.md).
 5. **Triage the 8 pre-existing test failures** that have shadowed
   the last few sessions. Some are in physics modules that L.2d
   slice 2 (if it ever happens) would touch — fixing them first
   gives a cleaner baseline.
 6. **Pick from CLAUDE.md's "Next phase candidates"** list — non-L.2
   work like Phase C visual fidelity, N.6 slice 2, or perf tiers
   2/3. The session-level "I don't know what to do" feeling is
   often easier to resolve by **shipping something in a different
   area** for a session.
 ---
 ## Reproducibility
 Same recipe as L.2a + L.2d slice 1:
 ```powershell
 $env:ACDREAM_DAT_DIR        = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE           = "1"
 $env:ACDREAM_TEST_HOST      = "127.0.0.1"
 $env:ACDREAM_TEST_PORT      = "9000"
 $env:ACDREAM_TEST_USER      = "testaccount"
 $env:ACDREAM_TEST_PASS      = "testpassword"
 $env:ACDREAM_DEVTOOLS       = "1"
 $env:ACDREAM_PROBE_CELL     = "1"
 $env:ACDREAM_PROBE_RESOLVE  = "1"
 $env:ACDREAM_PROBE_BUILDING = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
  Tee-Object -FilePath "launch-l2d.log"
 ```
 Walk acdream toward any Holtburg building threshold. Hit `Ctrl+F2` to
 toggle collision wireframes — you'll see the Door cylinder right at
 the threshold. The `name="Door"` line appears in the log at startup
 during the `CreateObject` stream replay.
 ---
 ## Open questions / unresolved
 - **What `PhysicsState` bits is ACE sending for the Door entity?**
  Not captured in current logs. Slice 1.6 would answer this.
 - **Are these doors *supposed* to be open by default in retail?**
  If yes, ACE config issue. If no, retail clients see the same
  blocker and players had to open them manually.
 - **What does ACE's door-state state machine look like?** Probably
  documented in `references/ACE/Source/ACE.Server/Entity/Door.cs`
  or similar.
 These are doors-and-ACE-side questions; defer to the door-state
 sub-phase when (if) it gets scoped.
 ---
 ## Worktree state at handoff
 - All three slice 1 / 1.5 commits ready to merge to main.
 - WorldBuilder submodule initialized + 6 directory junctions in place
  for the gitignored peer reference dirs (created during slice 1
  prep). Worktree builds clean.
 - Three test artifacts (`launch-l2d-slice1.log`, `launch-l2d-slice1b.log`,
  `launch-l2d-slice1c.log`) are in working tree but **not committed** —
  they're large and ephemeral. Delete or preserve at the merge
  author's discretion.
--- a/docs/research/2026-05-14-b5-shipped-handoff.md
+++ b/docs/research/2026-05-14-b5-shipped-handoff.md
@ -1,252 +0,0 @@
 # Phase B.5 shipped — handoff (visual-verified 2026-05-14)
 **Date:** 2026-05-14.
 **Branch:** `claude/phase-b5-pickup` (ready to merge to main; controller handles the merge after this doc lands).
 **Predecessors:**
 - [docs/research/2026-05-13-b4c-shipped-handoff.md](2026-05-13-b4c-shipped-handoff.md) — B.4c (door swing) shipped immediately before.
 - [docs/research/2026-05-13-b5-pickup-handoff.md](2026-05-13-b5-pickup-handoff.md) — fresh-session handoff that scoped this phase.
 - [docs/superpowers/plans/2026-05-14-phase-b5-pickup.md](../superpowers/plans/2026-05-14-phase-b5-pickup.md) — implementation plan (2 tasks).
 ---
 ## TL;DR
 Phase B.5 **shipped end-to-end and is visual-verified 2026-05-14.** The
 M1 demo target *"pick up an item"* is met for the close-range path —
 single-click a ground item to select, walk within ~0.6 m of it, press
 F, and the item is removed from the world and added to the player's
 inventory.
 The plan budgeted 2 implementation tasks (~50 LOC). Visual testing
 surfaced **one wire-handler gap** that became Task 2b: ACE despawns
 picked-up items via `GameMessagePickupEvent (0xF74A)`, not the
 `GameMessageDeleteObject (0xF747)` we already handled — without that
 fix the pickup succeeded server-side but the item kept rendering on
 the ground locally. Caught and fixed in the same session.
 Two known gaps remain, filed as issues for follow-up:
 - **#63 (MEDIUM)** — Server-initiated auto-walk for out-of-range Use /
  PickUp not honored. Double-click a ground item from > 0.6 m and the
  character partially walks then snaps back; ACE's `MoveToChain` times
  out. This is a separate motion-handling phase, not a B.5 regression.
 - **#64 (LOW)** — Local-player pickup animation doesn't render
  (retail observers see it correctly; local view is silent). Likely a
  self-echo filter dropping `UpdateMotion(Pickup)` on the local player.
 ---
 ## What shipped on this branch
 | # | Commit | Subject | Task |
 |---|---|---|---|
 | 1 | `e8a20f2` | `feat(B.5): InteractRequests.BuildPickUp — PutItemInContainer 0x0019` | Task 1 |
 | 2 | `ced1b85` | `test(B.5): exercise i32 sign-correctness for BuildPickUp.placement` | Task 1 code-review fix |
 | 3 | `54d9bb9` | `feat(B.5): SendPickUp helper + F-key SelectionPickUp wiring` | Task 2 |
 | 4 | `5c24f6c` | `docs(B.5): implementation plan from writing-plans skill` | Plan doc |
 | 5 | `f7636a9` | `fix(B.5): handle PickupEvent 0xF74A so picked-up items despawn locally` | Task 2b (post-visual-test fix) |
 Plus the predecessor handoff (`86440ff`) that started the branch.
 **Build:** clean.
 **Tests:** `dotnet test -c Debug` shows AcDream.Core.Net.Tests 290/290
 passing (was 287 at branch start; +3 from Task 2b's PickupEvent tests;
 the two BuildPickUp tests landed inside the same project's existing
 file). Failure count unchanged at 8 pre-existing baseline in
 AcDream.Core.Tests.
 ---
 ## What the code does end-to-end
 **Outbound (Tasks 1 & 2):**
 1. User single-clicks a ground item near `+Acdream`.
   `case InputAction.SelectLeft → PickAndStoreSelection(useImmediately: false)`
   runs B.4b's `WorldPicker.Pick`, finds the item, sets `_selectedGuid`.
   Log: `[B.4b] pick guid=0x… name=…`.
 2. User presses F.
   `case InputAction.SelectionPickUp → SendPickUp(_selectedGuid)` builds
   the wire body via `InteractRequests.BuildPickUp(seq, itemGuid,
   _playerServerGuid, placement: 0)` and posts it through
   `_liveSession.SendGameAction`. Log: `[B.5] pickup item=… container=… seq=…`.
 3. Wire layout (24 bytes): `0xF7B1 envelope | seq | 0x0019 opcode |
   itemGuid u32 | containerGuid u32 | placement i32`. Verified against
   `references/ACE/Source/ACE.Server/Network/GameAction/Actions/GameActionPutItemInContainer.cs`.
 **Inbound (Task 2b — surfaced during visual test):**
 4. ACE runs `HandleActionPutItemInContainer`. If the player is within
   `WithinUseRadius` (~0.6 m), the close-range branch in
   `CreateMoveToChain` skips the auto-walk and runs the pickup chain
   directly: server-side `Landblock.RemoveWorldObject(item.Guid,
   adjacencyMove: false, fromPickup: true)` → per-player
   `Player_Tracking.RemoveTrackedObject(wo, fromPickup: true)` →
   broadcast `GameMessagePickupEvent (0xF74A)` to all observers.
 5. Our `WorldSession.Dispatch` now routes `0xF74A` (in addition to
   `0xF747 DeleteObject`) through the shared `EntityDeleted` event,
   adapting the `PickupEvent.Parsed` to a `DeleteObject.Parsed` so
   `OnLiveEntityDeleted → RemoveLiveEntityByServerGuid` runs unchanged.
   The item disappears from the local view.
 ---
 ## Wire-handler gap (Task 2b)
 ACE distinguishes two despawn opcodes:
 - `0xF747 GameMessageDeleteObject` — "object is gone" (timeout / death /
  out-of-LOS). Our existing handler.
 - `0xF74A GameMessagePickupEvent` — "object was picked up by a player."
  Sent by `Player_Tracking.RemoveTrackedObject(wo, fromPickup: true)`.
 Both are functionally identical from the client's view (remove the
 entity from the world), but only one was handled. Wire format adds
 one `u16 objectPositionSequence` field over DeleteObject's layout, so
 `PickupEvent.cs` is its own parser; the dispatcher adapts to
 `DeleteObject.Parsed` for the downstream consumer.
 This is exactly the kind of trap CLAUDE.md's reference-repo discipline
 exists to prevent — the handoff spec said "the existing despawn path
 removes the ground item from view," which was *almost* true. Took one
 visual-verification round-trip to surface, ten minutes to fix with a
 clean wire parser + 3 new unit tests.
 ---
 ## Visual verification — what was observed
 **Test scenario:** ACE dropped a Pink Taper, then a Violet Taper, then
 two more tapers near `+Acdream` at Holtburg. Player walked up close,
 single-clicked, pressed F. Three pickups completed in the post-fix
 log: items `0x80000725`, `0x8000072A`, `0x80000729`.
 **Before Task 2b:** Server-side pickup succeeded — `[B.5] pickup …
 seq=46` in log; retail observer saw item disappear from world. Local
 view still rendered the item on the ground.
 **After Task 2b:** Item disappears locally as soon as ACE acks the
 pickup. Three successful close-range pickups recorded in the log.
 **Door-interaction regression check (B.4c carry-forward):** Not
 explicitly re-tested this session; no code path touched by B.5
 affects door interaction.
 **Click-NPC bonus (M1 demo target 3 verification):** Not visually
 verified this session — log shows `[B.4b] use guid=… name=Novedion
 the Gem Seller seq=…` from B.4c testing but ACE response not
 re-confirmed here. Carry-forward to next session.
 ---
 ## What did NOT work (and why it's not B.5's bug)
 1. **Double-click on a ground item from any distance, or F from > 0.6 m.**
   ACE auto-walks the player toward the item (`CreateMoveToChain` →
   `PhysicsObj.MoveToObject` + `EnqueueBroadcastMotion(MoveToObject)`),
   but our client doesn't handle inbound `MoveToObject` motion broadcasts.
   ACE's MoveToChain times out, the chain's `success: false` path sends
   `InventoryServerSaveFailed (ActionCancelled)`, and the pickup never
   completes. Visible as "character drifts toward item then flips back."
   **Filed as #63.** Out of B.5's stated scope (which was: select-first
   + F-key wire chain). holtburger's `simulation.rs` has the reference
   implementation; would be its own phase (B.6 or similar).
 2. **Local-player pickup animation doesn't render.** Retail observers
   see `+Acdream` play the bend-down-and-grab animation; our local view
   shows nothing. ACE broadcasts `Motion(MotionCommand.Pickup)` via
   `EnqueueBroadcastMotion`, our motion routing probably filters
   self-echoes for the local player (motion is normally predicted
   locally, not echoed from server). Server-initiated one-shot motions
   like Pickup have no local prediction trigger, so they're dropped.
   **Filed as #64.** Visual feedback gap only; pickup completes
   correctly.
 Both are well-defined follow-up work; neither blocks M1.
 ---
 ## Carry-overs from B.4c
 Both pre-existed B.5; neither was touched.
 - **#61** — AnimationSequencer link→cycle boundary frame-0 flash on
  door swing. Low severity polish.
 - **#62** — PARTSDIAG null-guard for sequencer-driven entities.
  Latent; not currently reachable for doors.
 ---
 ## M1 status after B.5
 Demo targets:
 1. Walk through Holtburg — met (L.2a-d + L.2g shipped earlier)
 2. Open the inn door — met (B.4b + B.4c shipped 2026-05-13)
 3. Click an NPC — chain wired (B.4b), not visually re-verified this
   session
 4. Pick up an item — met, close-range path (this phase)
 Outstanding work for the M1 demo recording:
 - Optionally re-verify target 3 (NPC click) once and either confirm
  met or file a gap.
 - Optionally resolve #63 if the demo wants to show double-click /
  out-of-range pickup. The close-range path is sufficient for the
  scripted demo scenario.
 - Carry-overs #61, #62, #64 are polish; do before recording if
  visible on tape.
 ---
 ## Reproducibility
 ```powershell
 Get-Process -Name AcDream.App -ErrorAction SilentlyContinue | Stop-Process -Force
 Start-Sleep -Seconds 20
 $env:ACDREAM_DAT_DIR        = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE           = "1"
 $env:ACDREAM_TEST_HOST      = "127.0.0.1"
 $env:ACDREAM_TEST_PORT      = "9000"
 $env:ACDREAM_TEST_USER      = "testaccount"
 $env:ACDREAM_TEST_PASS      = "testpassword"
 $env:ACDREAM_DEVTOOLS       = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug 2>&1 |
  Tee-Object -FilePath "launch-b5.log"
 ```
 Log evidence:
 ```powershell
 Get-Content launch-b5.log -Encoding Unicode |
  Select-String -Pattern "\[B\.5\] pickup|\[B\.4b\] pick"
 ```
 Expected: a `[B.5] pickup item=… container=0x5000000A seq=…` line for
 each successful F-press, preceded by `[B.4b] pick guid=…` from the
 single-click that set the selection.
 ---
 ## Files touched this session
 - New: `src/AcDream.Core.Net/Messages/PickupEvent.cs`
 - New: `tests/AcDream.Core.Net.Tests/Messages/PickupEventTests.cs`
 - New: `docs/superpowers/plans/2026-05-14-phase-b5-pickup.md`
 - New: `docs/research/2026-05-14-b5-shipped-handoff.md` (this file)
 - Modified: `src/AcDream.Core.Net/Messages/InteractRequests.cs`
 - Modified: `src/AcDream.Core.Net/WorldSession.cs`
 - Modified: `src/AcDream.App/Rendering/GameWindow.cs`
 - Modified: `tests/AcDream.Core.Net.Tests/Messages/InteractRequestsTests.cs`
 - Modified: `docs/ISSUES.md` (added #63, #64)
 ---
 ## State at handoff
 - **Branch:** `claude/phase-b5-pickup`, 6 commits ahead of `main`
  (predecessor handoff + 5 implementation commits + this docs commit
  land in the same merge).
 - **Main HEAD before merge:** `e7842e0` — Merge B.4c.
 - **Build state:** worktree compiles cleanly under `dotnet build -c Debug`.
 - **Tests:** baseline + 3 new (PickupEvent) + 2 new (BuildPickUp +
  sign-correctness) — failure count unchanged.
 Ready for non-fast-forward merge into `main`.
--- a/docs/research/2026-05-15-b6-b7-shipped-handoff.md
+++ b/docs/research/2026-05-15-b6-b7-shipped-handoff.md
@ -1,382 +0,0 @@
 # Phase B.6 + B.7 + WorldPicker tightening — handoff (visual-verified 2026-05-15)
 **Date:** 2026-05-15 (session 06:08–18:21).
 **Branch:** commits live on `main` from `cf22f9c..e49c704` (36 commits).
 **Predecessors:**
 - [docs/research/2026-05-14-b5-shipped-handoff.md](2026-05-14-b5-shipped-handoff.md) — B.5 (pickup) shipped immediately before.
 - [docs/superpowers/specs/2026-05-14-phase-b6-design.md](../superpowers/specs/2026-05-14-phase-b6-design.md) — B.6 design with retail anchors + trace findings + 4-slice plan.
 - [docs/superpowers/specs/2026-05-15-phase-b7-target-indicator-design.md](../superpowers/specs/2026-05-15-phase-b7-target-indicator-design.md) — B.7 design (Vivid Target Indicator).
 ---
 ## TL;DR
 Three coupled improvements shipped end-to-end this session:
 - **Phase B.6 — Local-player auto-walk on inbound `MoveToObject` (issue #63 OPEN → working).** When the user double-clicks a far target or presses R/F on an out-of-range target, ACE sends `UpdateMotion (0xF74D)` with `MovementType=6` carrying the destination guid. We now synthesize `Forward+Run` input into `PlayerMovementController` to walk the body to the target, then fire the deferred Use/PickUp once the position has arrived AND the body has rotated to face. Smooth rotation (no snap), dual alignment thresholds (30° walk-while-turning, 5° fully aligned). 10 Hz position heartbeat while moving keeps ACE's server-side `WithinUseRadius` poll converging fast enough that doors / NPCs / items all complete the action.
 - **Phase B.7 — Vivid Target Indicator (MVP).** Four small corner triangles drawn around the selected entity, colour-coded by entity type using a port of `gmRadarUI::GetBlipColor` (`0x004d76f0`). Box size scales with projected entity height × scale, per-type base height (humanoid 1.8 m, door/lifestone/portal 2.4 m, small item 0.8 m, default 1.5 m). Drawn via ImGui background draw list — no new GL infrastructure. **Selection bug is now self-correcting**: the user can see *what* they actually clicked before pressing R/F.
 - **WorldPicker tightening (#59 closed).** 5 m fixed sphere radius → 0.7 m default → 1.0 m default with 0.9 m vertical offset (chest-height sphere centre). Per-entity radius/offset callbacks let doors / lifestones / portals get bigger spheres (1.5–2.0 m) and small items get tighter ones (0.4 m).
 The M1 demo target *"click an NPC"* + *"open the inn door"* is now reachable from ANY range (close-range or far-range). The visual flow matches retail: you click → indicator appears → you press R → if far, character walks to within use radius, turns to face, action fires; if near, character turns to face, action fires.
 **Honest faithfulness note (user-requested audit).** Several workarounds remain — arrival safety margin, deferred-wire-Use packet, AutonomousPosition flush on arrival, retry flag — all rooted in our 1 Hz position heartbeat. The 10 Hz bump retires the worst of them in practice. Per-tick outbound (or fixing whatever causes ACE to lose our position between heartbeats) would retire ALL of them. Documented below in **Workaround retirement plan**.
 ---
 ## What shipped on this branch (36 commits)
 Ordered oldest → newest. Each commit subject is its own retail-faithful unit; the "fix(B.6+B.7)" pairing means a single workaround serves both phases.
 | # | Commit | Subject |
 |---|---|---|
 | 1 | `87ba5c9` | `feat(B.5): pickup feedback chat line + toast ("You pick up the X.")` |
 | 2 | `7be1393` | `docs(M1): record all 4 demo targets met, list deferred polish` |
 | 3 | `20ecb23` | `Revert "feat(B.5): pickup feedback chat line + toast …"` — retail-faithful: no feedback. |
 | 4 | `a01ebd5` | `fix(B.5): block pickup of creatures client-side; show 'Can't pick that up' toast` |
 | 5 | `ab7c04f` | `docs(M1): reflect chat/toast revert + the actual B.5 polish (creature pickup guard)` |
 | 6 | `e55ad48` | `fix(B.5): make creature-pickup guard silent (retail-faithful)` |
 | 7 | `ec9fd52` | `fix #62: null-guard the PARTSDIAG read of ae.Animation` |
 | 8 | `5053e40` | `docs: close #62 — PARTSDIAG null-guard landed in ec9fd52` |
 | 9 | `281d125` | `docs(B.6): design spec for local-player MoveToObject auto-walk (issue #63)` |
 | 10 | `9e1d33a` | `docs(B.6): retail decomp settles Option A; revise spec with 4-slice plan` |
 | 11 | `eda8278` | `feat(B.6 slice 1): ACDREAM_PROBE_AUTOWALK diagnostic baseline` |
 | 12 | `1b4f3ba` | `feat(B.6 slice 1): DebugPanel mirror for ProbeAutoWalk checkbox` |
 | 13 | `d82b064` | `docs(B.6): record Slice 1 trace findings — ACE sends mtRun=0.00, no UP echo` |
 | 14 | `b936ef8` | `feat(B.6 slice 2): local-player auto-walk on inbound MoveToObject` — core feature lands. |
 | 15 | `f18de7c` | `fix(B.6 slice 2): don't cancel autowalk on the companion InterpretedMotionState` |
 | 16 | `5612ce7` | `feat(B.6): honor wire WalkRunThreshold — walk vs run per retail semantics` |
 | 17 | `37177a4` | `docs(B.7): design spec for Vivid Target Indicator (selection feedback)` |
 | 18 | `8544a78` | `feat(B.7): RadarBlipColors — port of gmRadarUI::GetBlipColor` |
 | 19 | `c7e5f9f` | `feat(B.7): TargetIndicatorPanel — corner triangles around selected entity` |
 | 20 | `4bc95ec` | `fix(B.7): scale indicator box from projected entity height, not fixed pixels` |
 | 21 | `5e29773` | `fix #59: tighten WorldPicker radius from 5 m to 0.7 m` |
 | 22 | `631571a` | `docs: close #59 — picker radius tightened in 5e29773` |
 | 23 | `23cb1e9` | `fix(B.7): square indicator box + bigger pick sphere for doors/lifestones/portals + diag` |
 | 24 | `1a0656a` | `fix(picker): lift sphere centre to mid-body so chest/head clicks hit` |
 | 25 | `211fe24` | `fix(B.6+B.7): run-all-the-way auto-walk, per-type indicator height, R = smart interact` |
 | 26 | `5f83766` | `docs: file #65 — local player doesn't turn to face on close-range Use` |
 | 27 | `2dc28bb` | `fix(B.6+B.7): re-send action on local arrival; scale indicator box by entity Scale` |
 | 28 | `a0fa3d6` | `fix(B.6+B.7): flush AutonomousPosition on arrival before re-sending action` |
 | 29 | `39ff3a5` | `fix(B.6+B.7): arrival predicate uses safety margin INSIDE ACE's WithinUseRadius` |
 | 30 | `64c9793` | `fix(B.6+B.7): shrink arrival safety margin; file #66 rotation, #67 door` |
 | 31 | `301281d` | `fix(B.6+B.7): bump AutonomousPosition heartbeat 1Hz -> 10Hz while moving` ← **single biggest fix** |
 | 32 | `32352af` | `fix(B.6): turn-first auto-walk + tiny margin; close #67 doors; file #68 remote arrival` |
 | 33 | `5b908bc` | `fix(B.6): close-range turn-to-face — install overlay on Use/PickUp send` |
 | 34 | `cffb10f` | `fix(B.6): tighter 5° alignment + defer Use until rotation completes; file #69 turn anim` |
 | 35 | `7158c46` | `fix(B.6): smooth local rotation — remove 20° snap-on-approach (not retail)` |
 | 36 | `e49c704` | `fix(B.6): speculative auto-walk uses WalkRunThreshold=15 to match ACE` |
 **Build:** clean.
 **Tests:** `dotnet test -c Debug` shows the new RadarBlipColors tests (8) and the existing B.5 BuildPickUp tests passing. Failure count unchanged at the 8 pre-existing baseline in `AcDream.Core.Tests`.
 ---
 ## Wire-format facts (what ACE sends, what we parse)
 | Wire | Field | Value | Our handling |
 |---|---|---|---|
 | `UpdateMotion (0xF74D)` | `MovementType` | `6` MoveToObject | Local: `BeginServerAutoWalk(...)` + speculative turn overlay. Remote: existing `RemoteMoveToDriver`. |
 | `UpdateMotion (0xF74D)` | `MovementType` | `7` MoveToPosition | Local: `BeginServerAutoWalk(...)` with a synthetic guid (positional destination only). |
 | `UpdateMotion (0xF74D)` | `MovementType` | `8` TurnToObject | **NOT YET PARSED** — issue #66. ACE sends this on close-range Use against an off-facing target. Our parser falls into the locomotion path and silently drops the rotation. |
 | `UpdateMotion (0xF74D)` | `MovementType` | `0` Interpreted | Companion locomotion echo after a MovementType=6 (RunForward command). We do NOT treat this as a cancel signal (commit f18de7c). |
 | `UpdateMotion (0xF74D)` | `WalkRunThreshold` | float meters | If `distance > threshold` → run, else walk. ACE default `15.0 m`. We honor it (commit 5612ce7) for inbound; we use it as the speculative-overlay walk/run gate too (commit e49c704). |
 | `GameAction (0xF7B1)` outbound | `0x0036 Use` | guid | Sent on R-key / double-click + close-range. For far-range we install the speculative overlay and defer the wire packet until arrival (commit cffb10f). |
 | `GameAction (0xF7B1)` outbound | `0x0019 PutItemInContainer` | item guid + container guid + placement | Sent on F-key. Same defer-on-far-range pattern. |
 | `AutonomousPosition (0xF7B1 0x0007)` outbound | position + heading | every 1 Hz idle / **10 Hz while moving** | The 10 Hz bump (commit 301281d) is what unblocks doors (#67) and lets ACE's `MoveToChain` see us arrive at the use radius without timing out. |
 **Retail anchors for the above:**
 - `MovementManager::PerformMovement` at `0x00524440` — dispatch switch on MovementType.
 - `MoveToManager::HandleMoveToObject` — MovementType=6 driver (turn-to-face → walk → stop).
 - `MoveToManager::HandleMoveToPosition` — MovementType=7 driver.
 - `MoveToManager::HandleTurnToHeading` at `0x0052a0c0` — turn-only driver used by MovementType=8.
 - `CPhysicsObj::MoveToObject` at `0x00512860` — high-level entry from physics.
 - `Player_Move.CreateMoveToChain` (ACE) at `Player_Move.cs:37–179` — server-side state machine that depends on our heartbeat to detect arrival.
 ---
 ## Local auto-walk state machine (current shape)
 `src/AcDream.App/Input/PlayerMovementController.cs`:
 ```csharp
 // State
 private bool _autoWalkActive;
 private Vector3 _autoWalkDestination;
 private float _autoWalkMinDistance;        // ACE's WithinUseRadius (per-type)
 private float _autoWalkDistanceToObject;   // initial distance, used for run/walk decision
 private bool  _autoWalkMoveTowards;
 private bool  _autoWalkInitiallyRunning;   // decided ONCE at Begin
 public event Action? AutoWalkArrived;      // GameWindow re-sends Use/PickUp on this
 // Per-frame overlay, called from top of Update
 private MovementInput ApplyAutoWalkOverlay(float dt, MovementInput input)
 {
    if (!_autoWalkActive) return input;
    // User-input override → cancel
    if (input.Forward || input.Back || input.StrafeL || input.StrafeR)
    {
        EndServerAutoWalk("user-input");
        return input;
    }
    // Compute delta yaw, distance, alignment
    Vector3 toTarget = _autoWalkDestination - Position;
    float dist = toTarget.Length();
    float targetYaw = MathF.Atan2(toTarget.Y, toTarget.X) - MathF.PI / 2f;
    float delta = NormalizeAngle(targetYaw - Yaw);
    // SMOOTH rotation (commit 7158c46 — no snap)
    float maxStep = RemoteMoveToDriver.TurnRateRadPerSec * dt;
    Yaw += MathF.Sign(delta) * MathF.Min(MathF.Abs(delta), maxStep);
    // Dual alignment thresholds (commit cffb10f)
    const float WalkWhileTurningRad = 30f * MathF.PI / 180f;
    const float FullyAlignedRad     =  5f * MathF.PI / 180f;
    bool walkAligned = MathF.Abs(delta) <= WalkWhileTurningRad;
    bool aligned     = MathF.Abs(delta) <= FullyAlignedRad;
    // Arrival predicate uses TIGHT 0.05 m safety margin INSIDE ACE's radius
    // (commit 39ff3a5 + 64c9793; works because of 10 Hz heartbeat from 301281d)
    bool withinArrival = dist <= (_autoWalkMinDistance - 0.05f);
    if (withinArrival && aligned)
    {
        EndServerAutoWalk("arrived");        // fires AutoWalkArrived event
        return input;
    }
    bool moveForward = walkAligned && !withinArrival;
    return input with
    {
        Forward = moveForward,
        Run = moveForward && _autoWalkInitiallyRunning,
        // Strafes left clear so we don't combine with other input
    };
 }
 ```
 `src/AcDream.App/Rendering/GameWindow.cs`:
 ```csharp
 // Wired in ctor:
 _playerController.AutoWalkArrived += OnAutoWalkArrivedReSendAction;
 private (uint Guid, bool IsPickup)? _pendingPostArrivalAction;
 // On Use/PickUp send: install speculative overlay + defer wire packet if close
 private void SendUse(uint guid, bool isRetryAfterArrival = false)
 {
    if (!isRetryAfterArrival)
    {
        InstallSpeculativeTurnToTarget(guid);        // BeginServerAutoWalk with tiny radius
        _pendingPostArrivalAction = (guid, false);
        if (IsCloseRangeTarget(guid))
            return;                                  // wire packet deferred until arrival
    }
    // ... build + send 0xF7B1/0x0036
 }
 private void OnAutoWalkArrivedReSendAction()
 {
    if (_pendingPostArrivalAction is not (uint guid, bool isPickup)) return;
    _pendingPostArrivalAction = null;
    SendAutonomousPositionNow();                     // flush position so ACE sees us at radius
    if (isPickup) SendPickUp(guid, isRetryAfterArrival: true);
    else          SendUse(guid, isRetryAfterArrival: true);
 }
 ```
 ---
 ## Picker (current shape)
 `src/AcDream.Core/Selection/WorldPicker.cs`:
 - `DefaultRadius = 1.0f` (up from 0.7 m to compensate for vertical-offset lift, commit 1a0656a).
 - `DefaultVerticalOffset = 0.9f` (chest-height humanoid mid-body — fixes the bug where clicking the head/chest of an NPC missed because the sphere was at the feet).
 - Per-entity callbacks (`radiusForGuid`, `verticalOffsetForGuid`) supplied by `GameWindow`:
  - Doors / lifestones / portals: **radius 1.5–2.0 m, vertical offset 1.2 m** (commit 23ce1e9).
  - Small dropped items (BF_ITEM-class): **radius 0.4 m, vertical offset 0.1 m** (item lies on ground).
  - Default (NPC / creature / sign / other): defaults 1.0 m / 0.9 m.
 - Inside-sphere origin handled (commit 5821bdc, pre-session): if `t_near < 0` use `t_far` so the entity is still pickable at point-blank range.
 ---
 ## Target indicator (current shape)
 `src/AcDream.App/UI/TargetIndicatorPanel.cs` + `src/AcDream.Core/Ui/RadarBlipColors.cs`:
 - `TargetInfo(WorldPosition, ItemType, ObjectDescriptionFlags, Scale)` record carries the inputs.
 - Box height = `EntityHeightFor(itemType, pwdBitfield, scale)`:
  - Creature (NPC / monster / player): **1.8 m × scale** (humanoid baseline).
  - Door / Lifestone / Portal (BF_DOOR=0x1000 | BF_LIFESTONE=0x4000 | BF_PORTAL=0x40000): **2.4 m × scale** (door-frame tall).
  - Small carry items (Weapon | Armor | Clothing | Jewelry | Food | Money | Misc | MissileWeapon | Container | Gem | SpellComponents | Writable | Key | Caster): **0.8 m × scale**.
  - Default (signs, scenery interactables, untyped): **1.5 m × scale**. ⚠️ User reports signs still feel too small — see follow-up below.
 - Box is **square** (`WidthHeightRatio = 1.0`, matches retail) — width = height.
 - Projection: project feet + head world points to screen, draw 4 right-angle triangles at corners via ImGui background draw list.
 - Min screen height clamp: 16 px (prevents collapse on far entities).
 - Off-screen / behind-camera: returns early; ±20% NDC margin so a tall entity whose feet are just off-screen still gets head projected.
 - Colour: from `RadarBlipColors.For(itemType, pwdBitfield)`. Port of `gmRadarUI::GetBlipColor (0x004d76f0)` — Portal → Vendor → Creature (yellow) → PlayerKiller (red) → PKLite → FriendlyPlayer → default Item (white-ish).
 - 8 unit tests in `tests/AcDream.Core.Tests/Ui/RadarBlipColorsTests.cs`.
 **MVP scope — explicitly deferred (per spec §3):** off-screen edge arrow (`m_pOffScreen`), DAT-loaded triangle sprite (today's are procedural), mesh-tint highlight on the target, player-option toggle.
 ---
 ## Faithfulness audit (user-requested honest comparison)
 This was the most important conversation thread of the session. User asked: *"How faithful are we to retail in this?"* and pushed back on every workaround I'd introduced. Direct answer: **The data path is retail-faithful, the timing isn't, and the workarounds are our bugs not ACE's.**
 | Piece | What retail did | What we do | Why we diverged | Resolution path |
 |---|---|---|---|---|
 | MoveToObject wire parse | `MovementManager::PerformMovement` switch on `MovementType` | We parse 6/7, miss 8 | Incremental delivery — B.6 scope didn't include TurnToObject | **Issue #66** — port MovementType=8 |
 | Local turn-to-face | Smooth interpolation animation (legs+arms cycle while body pivots) | Smooth Yaw step; no animation cycle (statue-pivot) | Motion interpreter not fed TurnLeft/TurnRight when overlay turns | **Issue #69** — synthesize TurnLeft/TurnRight |
 | Arrival predicate | Exact: stop when `dist ≤ radius` | `dist ≤ radius − 0.05 m` safety margin | Our client+server position drift would let retail's exact predicate fall through. 1 Hz heartbeat was the root cause; with 10 Hz it's mostly redundant. | **Drop the margin** once per-tick outbound lands. |
 | Action send timing | Once on player intent | Twice: once on intent (deferred if far) + once on arrival | Our `MoveToChain` poll on ACE side races against our position heartbeat. With 1 Hz we always lost. 10 Hz helps. | **Single-send** once per-tick outbound + a server-side action queue replaces the retry. |
 | AutonomousPosition flush | Continuous broadcast | One forced AP on arrival + 10 Hz during move | Same root cause: ACE polls at 0.1 s, we broadcast at 1 s default. | **Per-tick outbound** retires this entirely. |
 | Local-player TurnToObject | Server broadcasts MovementType=8; client rotates body | We drop the wire MovementType=8 | Incremental delivery — B.6 was scoped to MovementType=6 only | **Issue #66** — same fix as the parse gap above. |
 | Remote-player arrival animation | Client detects arrival from wire's distance threshold and transitions cycle | RemoteMoveToDriver `Arrived` state set but consumer doesn't flip cycle | Cycle-routing layer never wired to the arrival event | **Issue #68** — add `SetCycle(NonCombat, Ready)` on arrival. |
 | Local-player pickup animation | Server-initiated `Motion(Pickup)` broadcast → animates locally | Self-echo filter drops it | Pre-existing (B.5) | **Issue #64** — admit server-initiated one-shots through the filter. |
 **Bottom line: every workaround in this list traces to the position heartbeat or the missing MovementType=8 path. Neither is "ACE's bug" — they are gaps in our client.**
 ---
 ## Open follow-up issues filed this session
 | ID | Severity | Summary |
 |---|---|---|
 | **#66** | LOW-MED | Local + remote rotation flip-back / NPCs don't turn — port MovementType=8 TurnToObject |
 | **#68** | LOW-MED | Remote players' running animation doesn't stop on auto-walk arrival |
 | **#69** | LOW | Local player rotation isn't animated (statue-pivot vs leg-shuffle) — synthesize TurnLeft/TurnRight |
 | **#65** | LOW | Local-player no turn-to-face on close-range Use — superseded by #66 |
 **Closed this session:**
 - **#59** — `WorldPicker` 5 m over-pick → 1.0 m + vertical offset (`5e29773`, `1a0656a`, `23ce1e9`).
 - **#62** — PARTSDIAG null-guard for sequencer-driven entities (`ec9fd52`).
 - **#67** — Door Use action doesn't complete after auto-walk arrival → fixed by 10 Hz heartbeat (`301281d`).
 **Visual gripe still open (not filed as an issue yet):** signs still feel too small. Default 1.5 m × scale should probably be 2.5 m for sign-class objects — they're tall posts in retail. Wiring is there (just bump the constant in `EntityHeightFor` for the "everything else" branch, or add a sign-detection rule). User's most recent feedback before context-out was *"still when I select a sign the box is way to small."*
 ---
 ## Reproducibility — how to verify the shipped behaviour
 ```powershell
 # From C:\Users\erikn\source\repos\acdream
 Stop-Process -Name AcDream.App -ErrorAction SilentlyContinue
 Start-Sleep -Seconds 3
 $env:ACDREAM_DAT_DIR   = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE      = "1"
 $env:ACDREAM_TEST_HOST = "127.0.0.1"
 $env:ACDREAM_TEST_PORT = "9000"
 $env:ACDREAM_TEST_USER = "testaccount"
 $env:ACDREAM_TEST_PASS = "testpassword"
 # Optional diagnostic env vars (heavy)
 # $env:ACDREAM_PROBE_AUTOWALK = "1"   # one [autowalk] line per MoveToObject inbound + transition
 # $env:ACDREAM_DUMP_MOTION   = "1"
 dotnet build -c Debug; if ($?) {
  dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
    Tee-Object -FilePath "launch.log"
 }
 ```
 **Test scenarios (each verified visually during the session):**
 1. **Far-range Use on NPC.** Stand 5–10 m from Tirenia in the Holtburg inn. Click NPC → corner triangles appear (yellow). Press R. Character runs to within ~3 m, decelerates, turns to face, Use fires, dialogue appears.
 2. **Far-range pickup on item.** Stand 5–10 m from a dropped taper. Click item → corner triangles appear (white-ish). Press F. Character runs to within ~0.6 m, turns to face, PickUp fires, item despawns, inventory updates.
 3. **Door open.** Stand 3–5 m from the inn front door. Click door → corner triangles appear (white-ish, scaled to 2.4 m × scale). Press R. Character walks to within ~2 m, turns to face, Use fires, ACE broadcasts `SetState (ETHEREAL)`, character walks through.
 4. **Close-range Use.** Already within ~1 m of an NPC, facing away. Press R. Character turns to face → Use fires → dialogue. (Close-range branch — exercises `IsCloseRangeTarget` + deferred-wire-packet path.)
 5. **Far-range double-click on item.** Same as (2) but double-click — should behave identically to F-key (double-click activation passes through `OnInputAction` after `58b95bc`).
 **Diagnostic env vars active for this work:**
 - `ACDREAM_PROBE_AUTOWALK=1` — one `[autowalk]` line per inbound MoveToObject + state transition (commit `eda8278`). Also toggleable via DebugPanel.
 - `ACDREAM_DUMP_MOTION=1` — every inbound `UpdateMotion` (guid, stance, cmd, speed).
 - `ACDREAM_REMOTE_VEL_DIAG=1` — `[UPCYCLE]` traces for remote-arrival debug (relates to #68).
 ---
 ## Files touched this session
 **New files:**
 - `src/AcDream.Core/Ui/RadarBlipColors.cs` — colour table port.
 - `src/AcDream.App/UI/TargetIndicatorPanel.cs` — corner-triangle renderer.
 - `tests/AcDream.Core.Tests/Ui/RadarBlipColorsTests.cs` — 8 unit tests.
 - `docs/superpowers/specs/2026-05-14-phase-b6-design.md` — B.6 design + 4-slice plan.
 - `docs/superpowers/specs/2026-05-15-phase-b7-target-indicator-design.md` — B.7 design.
 **Modified:**
 - `src/AcDream.App/Input/PlayerMovementController.cs` — auto-walk overlay, smooth rotation, dual alignment, 10 Hz heartbeat.
 - `src/AcDream.App/Rendering/GameWindow.cs` — `SendUse`/`SendPickUp` defer logic, `_pendingPostArrivalAction`, `OnAutoWalkArrivedReSendAction`, `InstallSpeculativeTurnToTarget`, `IsCloseRangeTarget`, `SendAutonomousPositionNow`, `TargetIndicatorPanel` wiring, per-entity picker callbacks, `UseCurrentSelection` smart-R dispatch.
 - `src/AcDream.Core/Selection/WorldPicker.cs` — radius/vertical-offset callbacks, inside-sphere origin handling documented.
 - `src/AcDream.Core.Net/WorldSession.cs` — MovementType=6 routing into local auto-walk path.
 - `src/AcDream.Core/Physics/PhysicsDiagnostics.cs` — `ProbeAutoWalkEnabled` static property, `ACDREAM_PROBE_AUTOWALK` env var.
 - `src/AcDream.UI.Abstractions/Panels/Debug/DebugVM.cs` + `DebugPanel.cs` — DebugPanel checkbox mirror.
 - `docs/ISSUES.md` — closed #59, #62, #67; filed #65, #66, #68, #69; updated #63 with B.6 status.
 - `docs/plans/2026-05-12-milestones.md` — M1 four-of-four status reflected.
 - `CLAUDE.md` — updated "Currently in Phase…" line with B.6/B.7 ship facts.
 ---
 ## Workaround retirement plan
 The four workarounds that should NOT survive a per-tick-outbound + MovementType=8 phase:
 1. **Arrival safety margin (currently 0.05 m).** `ApplyAutoWalkOverlay` stops at `dist <= _autoWalkMinDistance - 0.05f`. Retail stops at `dist <= radius`. Drop the margin when our outbound position is fresh enough that ACE's `WithinUseRadius` poll always sees us inside the radius the moment we get there.
 2. **Re-send on arrival.** `_pendingPostArrivalAction` + `OnAutoWalkArrivedReSendAction` re-fire `SendUse`/`SendPickUp` after the body arrives. Retail's client sends the action once and lets the server-side `MoveToChain` complete. Drop when ACE consistently completes the chain from a single send.
 3. **AutonomousPosition flush on arrival.** `SendAutonomousPositionNow()` explicitly broadcasts position the moment we arrive. With per-tick outbound this happens naturally.
 4. **`isRetryAfterArrival` flag.** Branch in `SendUse`/`SendPickUp` to skip the speculative-overlay install on the retry. Goes away when the retry goes away.
 **Single fix that retires all four:** per-tick outbound position broadcast (probably at the physics tick rate of 60 Hz with a smaller payload, or 20–30 Hz with the full one). Currently `effectiveInterval = activelyMoving ? 0.1f : 1.0f` (10 Hz active / 1 Hz idle). Going to 20–30 Hz active would likely close the gap; per-tick is the upper bound.
 **Reference for retail's outbound cadence:** `docs/research/named-retail/` — search for `CPhysicsObj::send_movement_event` and `AutonomousPosition` send-site. Holtburger's `client/movement/system.rs` also sends at higher cadence than our default.
 ---
 ## Next-session entry points (in rough priority order)
 1. **Fix the sign indicator box.** User's last gripe. Bump `EntityHeightFor` default from 1.5 m to ~2.5 m, or add an explicit sign-detection rule. ~5 LOC. Verify in Holtburg by selecting one of the inn signs.
 2. **Issue #66 — MovementType=8 TurnToObject (local + remote).** Two-direction fix: stop local-player flip-back AND make NPCs turn to face. ~80–120 LOC + tests. Spec template is the B.6 spec with MovementType=8 substituted.
 3. **Issue #69 — animate rotation.** Synthesize `TurnLeft`/`TurnRight` input flags while the overlay turns the body. ~30 LOC in `ApplyAutoWalkOverlay` + verify retail's human motion table has the cycle. Pairs with #66 nicely.
 4. **Issue #68 — Remote players don't stop run animation on arrival.** Wire `RemoteMoveToDriver.Arrived` to `SetCycle(NonCombat, Ready)`. ~20 LOC. Small standalone fix.
 5. **Issue #64 — Local-player pickup animation.** Pre-existing B.5 gap; the self-echo filter drops `UpdateMotion(Pickup)`. Either (a) admit server-initiated one-shots through the filter, or (b) generate locally on send.
 6. **Per-tick outbound position broadcast.** The big one. Retires the four B.6 workarounds and probably fixes a class of "ACE doesn't see us" bugs we haven't even noticed yet. Probably its own design phase (call it B.8 or M.x). Read `docs/research/named-retail/` for retail's cadence first.
 7. **Investigate the running-in-circles bug.** User reported during B.6 slice 2 testing that auto-walk would occasionally "run in circles" before going straight. The fix in `211fe24` (run-all-the-way) appears to have fixed it but no regression test exists. Worth a one-session investigation with `ACDREAM_PROBE_AUTOWALK=1`.
 ---
 ## Predecessor reading order for a fresh session
 1. **This document** — the full picture of what's in main.
 2. [`docs/superpowers/specs/2026-05-14-phase-b6-design.md`](../superpowers/specs/2026-05-14-phase-b6-design.md) — retail anchors + decomp citations for auto-walk.
 3. [`docs/superpowers/specs/2026-05-15-phase-b7-target-indicator-design.md`](../superpowers/specs/2026-05-15-phase-b7-target-indicator-design.md) — B.7 design + deferred-MVP list.
 4. [`docs/research/2026-05-14-b5-shipped-handoff.md`](2026-05-14-b5-shipped-handoff.md) — B.5 (pickup, close-range path) preceded this work.
 5. [`docs/research/2026-05-13-b4b-shipped-handoff.md`](2026-05-13-b4b-shipped-handoff.md) — B.4b (Use outbound + WorldPicker) preceded that.
 **Retail decomp anchors for auto-walk:** `docs/research/named-retail/acclient_2013_pseudo_c.txt` searched by:
 - `MovementManager::PerformMovement` (`0x00524440`)
 - `MoveToManager::HandleMoveToObject`
 - `MoveToManager::HandleMoveToPosition`
 - `MoveToManager::HandleTurnToHeading` (`0x0052a0c0`)
 - `CPhysicsObj::MoveToObject` (`0x00512860`)
 - `VividTargetIndicator::SetSelected` (`0x004f5ce0`)
 - `gmRadarUI::GetBlipColor` (`0x004d76f0`)
 **ACE anchors:** `references/ACE/Source/ACE.Server/WorldObjects/Player_Move.cs:37–179` (`CreateMoveToChain`) and `Player_Inventory.cs:976–1106` (pickup chain).
 ---
 ## Session-specific morale note
 This was a long session — 43 user messages, ~12 hours wall-clock, 36 commits. The pattern was: implement, user tests against retail, user reports specific divergence, fix, repeat. The user pushed back hard on workarounds twice ("Why workarounds? Nothing wrong with ACE, our client is wrong" + "did you verify with retail?") and both times the right move was to drop the workaround and chase the root cause. The 10 Hz heartbeat (`301281d`) was the highest-leverage commit of the session — it closed #67 and tightened the firing distance for every other interaction. **Lesson: when a workaround starts feeling load-bearing, find the heartbeat-cadence-style root cause behind it before adding more layers.**
 The B.6 four-slice plan in the spec was the right shape — Slice 1 (diagnostic) revealed `mtRun=0.00 + no UP echo`, which directly informed Slice 2 (treat MovementType=0 InterpretedMotionState as a companion not a cancel signal, `f18de7c`). Slice 3 + 4 (walk vs run + turn-first) emerged from visual testing. **Lesson: diagnostic-first slicing pays off when you don't actually know what ACE will send.**
 — Session ended at user request to write this handoff before context compaction.
--- a/docs/research/2026-05-16-issue77-autowalk-handoff.md
+++ b/docs/research/2026-05-16-issue77-autowalk-handoff.md
@ -1,284 +0,0 @@
 # Issue #77 — close-range auto-walk + pickup overshoot — investigation handoff
 **Filed:** 2026-05-16 (in `docs/ISSUES.md` as the active issue at the top)
 **Severity:** MEDIUM (M1-deferred polish; visible during normal play, doesn't block any phase)
 **Component:** physics / auto-walk / `PlayerMovementController.DriveServerAutoWalk`
 **Branch state when handed off:** main at `f8829b3` (post-merge of `claude/hungry-tharp-b4a27b`)
 ---
 ## What you're chasing
 Two related close-range bugs in the server-driven auto-walk path. Both are
 **pre-existing** — not caused by the LiveSessionController extraction
 (0b25df5) — they were surfaced during that refactor's visual verification.
 ### Bug A — NPC at walking range never auto-walks
 - User clicks an NPC (e.g. Royal Guard at `0x7A9B46AE`) when the player
  is at "walking range" — far enough that retail would walk a short
  distance to reach the NPC's `useRadius`, not close enough to fire
  Use immediately.
 - The client's `WorldPicker` returns `WithinUseRadius=false`, so
  `OnInputAction.UseSelected` defers the Use and would expect ACE's
  inbound `MoveToObject` motion update to drive the player to the NPC.
 - **The local player does not visibly move.** Repeated clicks (the trace
  below shows seq 81 → 87 → 90 → 96 → 105 → 141 → 146 → 159 → 163 →
  169 → 173 → 177 against the same Royal Guard) produce the same
  response every time without any movement.
 ### Bug B — Pickup at walking range runs/overshoots/snaps back
 - User presses F on a ground item while in "walking range" of it.
 - Player **runs** (not walks) toward the target.
 - Overshoots the item, then **blips back** to the correct position
  before the pickup actually fires.
 - The pickup completes (item ends up in inventory), but the visual is
  jarring.
 The "blips back" almost certainly means ACE's server-side position
 correction snaps the player back after the client overshot. The
 client's run-not-walk choice is the proximal cause.
 ---
 ## What we know already (don't re-discover this)
 ### Trace evidence captured during merge
 From `launch.log` of the Step 2 verification run (task `b01zkw68w`,
 2026-05-16, with `ACDREAM_DEVTOOLS=1` + my temporary
 `OnLiveMotionUpdated` diagnostic):
 ```
 [B.4b] use guid=0x7A9B46AE seq=159                                ← outbound Use packet sent
 OnLiveMotionUpdated: guid=0x5000000A stance=61 cmd=0x speed=      ← player → NonCombat
 OnLiveMotionUpdated: guid=0x7A9B46AE stance=61 cmd=0x0003 speed=  ← NPC turns to face
 OnLiveMotionUpdated: guid=0x7A9B46AE stance=61 cmd=0x speed=
 OnLiveMotionUpdated: guid=0x5000000A stance=0 cmd=0x0005 speed=-1.84   ← ACE sends MoveToObject for player
 OnLiveMotionUpdated: guid=0x5000000A stance=0 cmd=0x speed=
 ```
 The pattern repeats identically for every retry — ACE *is* sending the
 auto-walk command, but the client isn't engaging it.
 **The negative speed (-1.84) is suspicious.** Speed is parsed as a raw
 IEEE 754 float by `UpdateMotion.cs:193`. Either retail encodes a sign
 that we're misinterpreting, or this is a legitimate "move backward"
 instruction (ACE sometimes positions the move-to point behind the
 player). The auto-walk engagement condition may be filtering negative
 speeds out without our intent.
 ### What was already established BEFORE this issue
 `PlayerMovementController` got significant retail-faithful refactor work
 in Phase B.6 (closed-issue #75 territory, commit `f035ea3`). That work
 established:
 - **Walk/run threshold = 1.0m** of remaining-distance-to-useRadius
  (not ACE's wire-supplied 15m default — that's overridden).
 - **One-shot walk/run decision** at `BeginServerAutoWalk` time, held
  for the rest of the chain.
 - **Direct body-velocity drive** — auto-walk does NOT synthesize
  `MovementInput`. It steps `Yaw`, sets `_body.set_local_velocity`
  from `runRate`, and calls `_motion.DoMotion(WalkForward, speed)`
  directly.
 The auto-walk diagnostic infrastructure already exists:
 ```
 PhysicsDiagnostics.ProbeAutoWalkEnabled   ← runtime-toggleable
 ACDREAM_PROBE_AUTOWALK=1                  ← env-var enable
 [autowalk-out]   on every SendUse / SendPickUp
 [autowalk-mt]    on every inbound UpdateMotion for the local player
 [autowalk-up]    on every inbound UpdatePosition for the local player
 [autowalk-begin] when BeginServerAutoWalk fires
 [autowalk-end]   when EndServerAutoWalk fires
 ```
 **You should turn this on first.** The `[autowalk-begin]` line will tell
 you whether `BeginServerAutoWalk` is even being invoked for the
 walking-range case.
 ### Where to start reading code
 | File | Why |
 |---|---|
 | `src/AcDream.App/Input/PlayerMovementController.cs` | The auto-walk driver lives here. Key functions: `BeginServerAutoWalk` (line ~428), `DriveServerAutoWalk` (line ~550), `EndServerAutoWalk` (line ~478). |
 | `src/AcDream.App/Rendering/GameWindow.cs` line ~3360 | The `OnLiveMotionUpdated` site that detects MoveToObject pattern and calls `BeginServerAutoWalk`. The `[autowalk-mt]` and `[autowalk-begin]` traces fire here. |
 | `src/AcDream.Core.Net/Messages/UpdateMotion.cs` line ~193 | The inbound parser. `ForwardSpeed` is a raw float — investigate whether negative is legitimate or a sign-misinterpretation. |
 | `docs/superpowers/specs/2026-05-14-phase-b6-design.md` | The Phase B.6 design spec. Read this first to understand the existing auto-walk contract. |
 | `references/holtburger/crates/holtburger-core/src/client/simulation.rs` | The Rust client's equivalent — has `ServerControlledProjection` + `approximate_move_to_object_projection_target`. Holtburger handles this case correctly, so cross-checking is valuable. |
 | `docs/research/named-retail/acclient_2013_pseudo_c.txt` | Grep for `MoveToManager::HandleMoveToPosition`, `MoveToManager::HandleAutonomyLevelChange`, `CMotionInterp::apply_interpreted_movement`. Retail's truth. |
 ### What was checked and ruled out during the Step 2 session
 - The bugs exist on the **pre-Step-2 branch** (eda936d / 32423c2 / main).
  This was confirmed by diff scope: `PlayerMovementController.cs`,
  `PhysicsEngine.cs`, `UpdateMotion.cs` were not touched by Step 2.
 - The Step 2 refactor (`0b25df5`) does not affect the auto-walk path.
 - Subscriptions are wired correctly — `OnLiveMotionUpdated` IS firing
  for every motion update (verified via `[step2-diag]` traces that have
  since been stripped).
 ---
 ## Hypotheses to test, in order
 ### H1 (most likely) — `BeginServerAutoWalk` never fires for the walking-range MoveToObject
 The walking-range MoveToObject from ACE may not match the pattern that
 `OnLiveMotionUpdated` checks before calling `BeginServerAutoWalk`. The
 condition probably checks for one of: `IsServerControlledMoveTo`,
 non-zero ForwardSpeed magnitude, specific `MovementType`, or specific
 `ForwardCommand` values. Walking-range UpdateMotion may differ from
 running-range in one of those fields.
 **Test:** Enable `ACDREAM_PROBE_AUTOWALK=1`, click the NPC at walking
 range. Look for `[autowalk-mt]` (inbound parse) WITHOUT a following
 `[autowalk-begin]`. That confirms H1 and points to GameWindow.cs:3360.
 ### H2 — `BeginServerAutoWalk` fires but `_autoWalkInitiallyRunning` decision misclassifies
 The walk/run decision uses:
 ```csharp
 remainingAtStart = initialDist - distanceToObject
 _autoWalkInitiallyRunning = remainingAtStart >= 1.0m
 ```
 If ACE sends a `distanceToObject` (useRadius) much smaller than the
 NPC's actual useRadius — or if `initialDist` is computed against the
 wrong target position — `remainingAtStart` could land just above 1m
 even at user-perceived walking range, causing run-not-walk. That
 matches **Bug B**'s "runs and overshoots" pattern.
 **Test:** Compare `[autowalk-begin] dest=(...) minDist=... objDist=... walkRunThresh=...`
 values between a walking-range click and a running-range click. The
 `objDist` should be the wire-supplied useRadius. If it's wrong (too
 small), retail's value disagrees and we have a parser bug elsewhere.
 ### H3 — Negative `ForwardSpeed` is filtered or misinterpreted
 `speed=-1.84` is the literal IEEE 754 float on the wire. Retail's
 `CMotionInterp::handle_action_walkforward` (or whichever code consumes
 ForwardSpeed) may use it for direction relative to the auto-walk
 heading; a sign-extension bug in our parse would matter.
 **Test:** Grep `references/holtburger` and named-retail decomp for how
 `ForwardSpeed` is consumed. If retail/holtburger interpret the sign
 specially and we don't, that's the gap.
 ### H4 — Arrival predicate fires too early
 `DriveServerAutoWalk` line ~601:
 ```csharp
 withinArrival = dist <= arrivalThreshold
 ```
 where `arrivalThreshold = _autoWalkDistanceToObject` (use-radius).
 If `distanceToObject` is 0 or near-zero (a parser bug, see H2), the
 arrival predicate fires on the first frame and `EndServerAutoWalk("arrived")`
 is called immediately, so the player never visibly moves. That matches
 **Bug A** exactly.
 **Test:** Look for `[autowalk-end] reason=arrived` immediately after
 `[autowalk-begin]` with zero or one frame between. That confirms H4.
 ---
 ## Reproduction recipe (~3 minutes)
 1. **Launch with autowalk probe enabled:**
   ```powershell
   $env:ACDREAM_DAT_DIR    = "$env:USERPROFILE\Documents\Asheron's Call"
   $env:ACDREAM_LIVE       = "1"
   $env:ACDREAM_TEST_HOST  = "127.0.0.1"
   $env:ACDREAM_TEST_PORT  = "9000"
   $env:ACDREAM_TEST_USER  = "testaccount"
   $env:ACDREAM_TEST_PASS  = "testpassword"
   $env:ACDREAM_DEVTOOLS   = "1"
   $env:ACDREAM_PROBE_AUTOWALK = "1"
   dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug | Tee-Object -FilePath launch.log
   ```
 2. **Reproduce Bug A:**
   - Walk toward the inn area in Holtburg until you're ~3-5 meters from
     an NPC (e.g. Royal Guard near the inn). Estimate by eye — the goal
     is "you can see the NPC clearly but you'd need to take a few steps
     to reach them."
   - Double-click the NPC.
   - Observe: player doesn't move. Click again — same result.
 3. **Reproduce Bug B:**
   - Find a ground item (Holtburg has scattered spell components — the
     coloured Tapers are obvious). Stand ~3-5 meters away.
   - Press F (or whatever your `SelectionPickUp` key is bound to).
   - Observe: player runs, overshoots, snaps back, item picked up.
 4. **Stop the client gracefully** (window close, not Stop-Process — see
   CLAUDE.md "Logout-before-reconnect"). ACE clears stale sessions in
   3–5 seconds on graceful close.
 5. **Grep the log:**
   ```bash
   tr -d '\000' < launch.log | grep -E "\[autowalk-(out|mt|begin|up|end)\]"
   ```
   This should give you a complete frame-by-frame trace of every
   auto-walk decision the client made.
 ---
 ## Acceptance criteria
 When the fix lands:
 - ✅ Click NPC at walking range → player **walks** (not runs) directly to NPC,
  Use fires on arrival, NPC dialogue appears.
 - ✅ Press F on ground item at walking range → player **walks** the short
  distance, no overshoot, no blip-back, item enters inventory.
 - ✅ Far-range click still **runs** to target (don't regress the working case).
 - ✅ Out-of-walking-but-very-close-range case (right at the edge of useRadius)
  still arrives without infinite spin or stuttering.
 - ✅ All existing tests pass (8 pre-existing Core failures are baseline,
  do NOT count against the fix).
 - ✅ Visual verification at Holtburg, all three M1 demo targets still work
  (door, NPC, pickup).
 ---
 ## What NOT to do
 - **Don't add a workaround**, per CLAUDE.md's "no workarounds" rule.
  No grace-period band-aid, no "if speed is negative, force walk" hack,
  no "always walk when within 5m" override. Fix the root cause.
 - **Don't rewrite the auto-walk path** — Phase B.6 was a heavy retail
  decomp port. The fix is almost certainly a one-condition or one-formula
  adjustment, not a new design.
 - **Don't change `Step 2`'s extracted code**. `LiveSessionController` and
  the wireup are clean — `OnLiveMotionUpdated` is wired and firing per
  the previous session's verification traces.
 ---
 ## Time estimate
 - 30 min: read the spec + reproduce + capture trace
 - 30 min: identify root-cause hypothesis from the trace
 - 30 min – 2 hr: implement the fix (depends on which hypothesis lands)
 - 30 min: visual verification + write commit message
 - **Total:** 2–3 hours focused work
 ---
 ## When done
 1. Commit message format: `fix(physics): close #77 — <root cause summary>`
 2. Move `#77` to the "Recently closed" section of `docs/ISSUES.md`
   with closed-date + commit SHA (matches the project convention).
 3. If the fix uncovered a durable lesson (e.g. "ACE sends negative
   ForwardSpeed for MoveToObject; we were filtering"), add a
   `feedback_*.md` memory entry per `memory/MEMORY.md` conventions.
 4. The next pre-M2 cleanup items in queue: root `.editorconfig` + Step 3
   (`LiveEntityRuntime`). See `docs/architecture/code-structure.md` §4.
--- a/docs/research/2026-05-16-session-handoff.md
+++ b/docs/research/2026-05-16-session-handoff.md
@ -1,90 +0,0 @@
 # Session handoff — 2026-05-16
 ## What landed this session
 **M1 — "Walkable + clickable world" — ✅ LANDED on main at `fb92122`.**
 All four M1 demo targets work end-to-end retail-faithfully:
 1. Walk through Holtburg without getting stuck (L.2 collision) — outdoor only verified
 2. Open the inn door (B.4c)
 3. Click an NPC and see dialogue (B.4b + Phase B.6)
 4. Pick up an item from the ground (B.5 + Phase B.6)
 **Important caveat:** the M1 demo specifically did NOT test:
 - Walking around inside the inn (just the doorway)
 - Going up stairs
 - Indoor-to-indoor transitions
 - Indoor lighting correctness
 These were assumed to "probably work" because outdoor walking does. They likely don't.
 ## Main branch history (newest first)
 | SHA | Title |
 |---|---|
 | `5d79dd3` | docs: session handoff 2026-05-16 (this doc; will be overwritten when you read this) |
 | `fb92122` | milestone: M1 landed; flip "currently working toward" to M2 |
 | `d640ed7` | feat(retail): Phase B.6 — server-driven auto-walk done right |
 | `b5da17d` | feat(retail): Commit B — retail-faithful AP cadence + screen-rect picker |
 | `e2bc3a9` | (base — docs(CLAUDE.md): document Ghidra MCP + WireMCP availability) |
 ## Phase B.6 (today's big landing) — what it actually did
 Replaced the chain of Commit-B workarounds that compensated for ACE's `MoveToChain` getting cancelled by a leaked user-MoveToState packet during inbound auto-walk. The fix was architectural:
 - **`ApplyAutoWalkOverlay → DriveServerAutoWalk`** — auto-walk drives the body's velocity + motion state + animation cycle DIRECTLY from the wire-supplied path data. No player-input synthesis. Mirrors retail's `MovementManager::PerformMovement` case 6 (decomp `0x00524440`) which never touches the user-input pipeline during server-controlled auto-walk.
 - **Wire-layer guard retained** at `GameWindow.cs:6419` as a semantic statement (user-MoveToState packets are for user-driven motion intent), NOT as the band-aid the deleted 500ms grace period was.
 - **Walk/run threshold = 1.0m** (matches user-observed retail behaviour; ACE's wire-default 15.0f is ignored — overridden in `BeginServerAutoWalk` via const `RetailWalkRunThresholdMeters`). Formula from decomp `0x0052aa00 MovementParameters::get_command`: `running = (initialDist - distance_to_object) >= threshold`, one-shot at chain start.
 - **Animation cycle plumbed** for moving-forward (RunForward/WalkForward) AND turn-first phase (TurnLeft/TurnRight via `_autoWalkTurnDirectionThisFrame`).
 - **Pickup gate** corrected to check `BF_STUCK` (`acclient.h:6435`, bit `0x4`) — signs (`pwd=0x14`) blocked; spell components (`pwd=0x10`) allowed.
 - **R-key dispatches by target type** — creature → SendUse, pickupable → SendPickUp, useable → SendUse, else toast.
 - **AP cadence reverted** to retail's two-branch `ShouldSendPositionEvent` gate (`acclient_2013_pseudo_c.txt:700233-700285`). Effective rates: 0 Hz idle, ~1 Hz smooth motion, per-event on cell/plane changes, 0 Hz airborne. `ApproxPlaneEqual` helper added.
 Issues closed: **#63, #69, #74, #75**.
 ## New rules / preferences captured this session
 1. **No workarounds without explicit approval.** CLAUDE.md "How to operate" + `memory/feedback_no_workarounds.md`. Band-aids, grace periods, suppression flags, retry loops forbidden unless the user explicitly approves or it's a deliberate new-feature design.
 2. **No milestone demo videos.** CLAUDE.md "milestone discipline" rule #3 + `memory/feedback_no_demo_videos.md`. Milestones land via text-only artifacts.
 3. **Graceful client shutdown via `CloseMainWindow`.** CLAUDE.md "Logout-before-reconnect" section. `Stop-Process` is a hard kill — leaves ACE's session marked logged-in for ~3+ min before timeout.
 ## Direction redirect at session end
 The originally-planned **M2 — "Kill a drudge"** is being **deferred** in favor of fundamentals-first work. User's stated reasoning: indoor walking, physics correctness, and lighting are all untested or broken, and building combat on top of an unverified-indoor foundation would compound problems.
 **New M2 candidate — "Indoor walkability."** Demo scenario candidate: walk into the Holtburg inn, climb to the second floor, look around, walk back out — all with sensible camera + correct indoor lighting + collision-clean. Three sub-phases proposed:
 | Phase | Scope | Estimate |
 |---|---|---|
 | Camera correctness | Sphere-cast from player to camera position; snap to first wall hit; lerp recovery when clear. Prevent camera from dipping below ground. Indoor-specific but applies everywhere. | ~1 day |
 | Indoor collision audit | Walk every floor of the Holtburg inn (and a nearby small dungeon if time). Document each off-feeling spot — stairs, narrow halls, EnvCell-to-EnvCell transitions, EnvCell-to-outdoor seams. Fix scoped per finding. | ~1 week |
 | Indoor lighting basics | Tightly scoped: torch-light pools + proper indoor ambient (dim). Defer fire/lamp/glow particles + dynamic-light count optimization to M5. Touches shader pipeline (modern bindless path) + per-object light selection. | ~1-2 weeks |
 Order matters: camera fix first (you can't honestly audit collision while the camera fights you), then collision audit (find the bugs), then lighting (the visual unlock).
 **This milestone has not been formally renamed in `docs/plans/2026-05-12-milestones.md` yet.** The doc still says "M2 — Kill a drudge." The next session should brainstorm the new milestone (using `superpowers:brainstorming`), agree on the demo scenario, scope the sub-phases, then update the milestones doc + CLAUDE.md to reflect the reorder. Combat slides to M3.
 ## Test baseline
 - Core.Net: 294/294 ✅
 - Core: 1073/1081 (8 pre-existing Physics failures — BSPStepUp + MotionInterpreter; unchanged baseline)
 ## Environment reminders
 - ACE running locally on `127.0.0.1:9000` (testaccount / testpassword / `+Acdream` at `0x5000000A`).
 - DAT directory: `%USERPROFILE%\Documents\Asheron's Call`.
 - Worktree branch `claude/vigilant-golick-9433e1` has the full 20-commit Phase B.6 history; main has one squashed commit (`d640ed7`).
 - WorldBuilder submodule needs `git submodule update --init references/WorldBuilder` in fresh worktrees.
 ## Open issues worth tracking
 - **#61** — AnimationSequencer link→cycle frame-0 flash on door swing. LOW.
 - **#64** — Local-player pickup animation does not render. LOW.
 - **#70** — Triangle apex/size DAT sprite. LOW.
 - **#71** — WorldPicker Stage B polygon refine. LOW.
 - **#72** — cdb probe to confirm `omega.z = π/2` base rate. LOW.
 - **#73** — Retail-message centralization. Per-feature, ongoing.
 None block the new indoor milestone. All M7 polish.
--- a/docs/research/2026-05-19-cluster-a-shipped-handoff.md
+++ b/docs/research/2026-05-19-cluster-a-shipped-handoff.md
@ -1,256 +0,0 @@
 # Indoor walking Phase 1 — BSP cluster (Cluster A) — handoff (2026-05-19)
 **Date:** 2026-05-19.
 **Branch:** `claude/competent-robinson-dec1f4` (commits land here; merge to main handled by controller).
 **Predecessor:** Indoor lighting + rendering Phase 2 (fix) — floors now render in Holtburg Inn. Nine pre-existing indoor bugs surfaced the moment floors were visible; this cluster addresses the collision/interaction subset (#84, #85, #86) and adds diagnostic infrastructure for the follow-up portal-traversal phase.
 **Plan:** [`docs/superpowers/plans/2026-05-19-indoor-walking-phase1-bsp-cluster.md`](../superpowers/plans/2026-05-19-indoor-walking-phase1-bsp-cluster.md).
 ---
 ## TL;DR
 Cluster A shipped **partially**. Three of the five planned phases (A, B, D)
 produced real behavior changes; two (C — obstacle audit — and E — cell-cache
 diagnostics) are diagnostic/research phases. The cluster's investigation
 confirmed that the wall-collision failures (#84, #85) all root in one cause:
 the player's `CellId` is never promoted to an indoor cell during normal
 walking, so the indoor-BSP collision branch in `TransitionTypes.FindEnvCollisions`
 never fires. Phase D implemented an AABB-containment shortcut that resolves
 the specific "spawn inside a building and be stuck above the floor" case but
 proved too tight to keep `CellId` promoted through threshold/doorway cells
 during normal outdoor→indoor entry.
 **#86** (click selection penetrates walls) is **fully closed** — a clean,
 self-contained fix in `WorldPicker`.
 **#84** is **partially closed** — the spawn-in-building symptom is gone; the
 remaining wall-collision symptom during normal walking is tracked under the
 new **#87**.
 **#85** remains **open**; its root cause is confirmed identical to #84's
 remaining symptom and is also tracked under #87.
 **#87** (indoor portal-based cell tracking) is **filed** and ready for the
 follow-up phase.
 ---
 ## Commits
 | # | SHA | Subject | Phase |
 |---|---|---|---|
 | 1 | `18a2e28` | `docs(plan): implementation plan written` | Plan doc |
 | 2 | `27d7de1` | `feat(physics): Cluster A — indoor BSP collision probe` | Phase A |
 | 3 | `3764867` | `fix(picker): Cluster A #86 — cell-BSP ray occlusion in WorldPicker` | Phase B |
 | 4 | `4e308d5` | `test(picker): Cluster A #86 — screen-rect cell-occlusion tests` | Phase B follow-up |
 | 5 | `c19d6fb` | `fix(physics): Cluster A #84 + #85 — indoor cell tracking` | Phase D |
 | 6 | `fda6af7` | `feat(physics): Cluster A — cell-cache diagnostic` | Phase E (1st) |
 | 7 | `1f11ba9` | `feat(diag): Cluster A — extend [cell-cache] with AABB + bsphere + recursive poly count` | Phase E (2nd) |
 **Build:** clean on all commits.
 **Tests:** `dotnet test` shows the same 8 pre-existing failures in
 `AcDream.Core.Tests` (MotionInterpreter / BSPStepUp / etc., unchanged across
 the entire cluster). All targeted test projects green. Phase B follow-up
 adds screen-rect occlusion tests; Phase D adds `RegisterCellStructForTest`
 helper used by caller-side tests.
 ---
 ## What shipped
 ### Phase A — `[indoor-bsp]` probe
 New `PhysicsDiagnostics.ProbeIndoorBspEnabled` toggle (env var
 `ACDREAM_PROBE_INDOOR_BSP` + DebugPanel checkbox under
 `ACDREAM_DEVTOOLS=1`). When enabled, logs one `[indoor-bsp]` line each time
 `TransitionTypes.FindEnvCollisions` takes the indoor-cell branch —
 i.e., when `CellId` is an EnvCell id and the BSP contains physics polys. The
 probe serves as a presence detector: if `[indoor-bsp]` never fires during
 indoor walking, the BSP is not being consulted at all.
 ### Phase B — WorldPicker cell-BSP ray occlusion (closes #86)
 New `CellBspRayOccluder` class (in `src/AcDream.App/Rendering/`) computes
 `NearestWallT`: the smallest ray parameter at which the pick ray intersects
 any cached EnvCell BSP polygon. Both `WorldPicker.Pick` overloads now accept
 an optional `cellOccluder` callback and filter out any hit candidate whose
 ray T exceeds `NearestWallT`. The occluder is wired from `GameWindow` using
 the `PhysicsDataCache` cell structs that Phase D also extends.
 Before Phase B: clicking through a wall from the outside selected NPCs/items
 inside the building — `WorldPicker.BuildRay + Pick` (Phase B.4b) tested only
 entity AABBs and scenery BSPs, not EnvCell BSP geometry.
 After Phase B: entities behind the nearest wall from the camera's perspective
 are filtered out of the candidate set. Screen-rect unit tests verify the
 filter across hit/miss/occlusion scenarios.
 ### Phase D — AABB containment for indoor CellId (partial #84 fix)
 `PhysicsEngine.ResolveOutdoorCellId` is extended with an indoor
 cell-containment scan. After resolving the outdoor cell, the method checks
 whether the player's world position falls inside any cached `CellPhysics`
 AABB; if so, `CellId` is promoted to that EnvCell. This enables the
 `FindEnvCollisions` indoor-BSP branch.
 New `PhysicsDataCache.TryFindContainingCell(worldPos)` does the AABB scan.
 New `CellPhysics.WorldAabb` caches the cell-local AABB in world space on
 first call (transforms the BSP bounding sphere's local AABB by the cell
 origin). New `RegisterCellStructForTest` helper allows unit test callers to
 populate the cache directly.
 Also fixes the L.2e bare-low-byte preservation bug: `ResolveOutdoorCellId`
 was silently truncating the player CellId to the low 16 bits; the fix
 preserves the full 32-bit value.
 **What this solved:** player spawning inside a building (e.g., logging in
 from a position inside Holtburg cottage) no longer sees `walkable=False` for
 hundreds of resolves with world Z=94.000. Phase D promotes CellId to the
 indoor cell, the floor's BSP polys are found, the player can move.
 **What this did NOT solve:** the `[indoor-bsp]` probe fires only 6 times
 during an entire indoor walking session (all mid-jump, when the body happens
 to be at a height that falls inside a room AABB). During normal walking on
 the floor, the player's world Z is at the AABB floor level or lower —
 outside the AABB for threshold/doorway cells that have only a 0.2 m Z range.
 See Phase E evidence below.
 ### Phase E — Cell-cache diagnostic infrastructure
 Two commits add `[cell-cache]` log output (env var
 `ACDREAM_PROBE_CELL_CACHE`, also DebugPanel). For each EnvCell in the
 physics cache, the probe logs:
 ```
 [cell-cache] id=0xA9B40143 physicsPolyCount=14 bspTotalLeafPolys=14
  bspUnmatchedIds=0 aabbMin=(-11.60,-1.60,0.00) aabbMax=(-6.20,7.60,2.80)
  bspOrigin=(0.00,0.00,0.00) bspRadius=9.97
 ```
 The extended second commit adds `bspTotalLeafPolys`, `bspUnmatchedIds`,
 `bspOrigin`, and `bspRadius` fields to give a complete picture of cell
 geometry from the physics cache perspective. This infrastructure stays in
 place as scaffolding for the portal-traversal phase.
 ---
 ## Issue status after Cluster A
 | Issue | Status | Notes |
 |---|---|---|
 | #84 Blocked by air indoors | OPEN (partial) | Spawn-in-building variant resolved by Phase D. Threshold/doorway wall-blocking remains open under #87. |
 | #85 Pass through walls outside→in | OPEN | Root cause confirmed as same as #84 remaining symptom. See #87. |
 | #86 Click selection penetrates walls | **CLOSED** | Phase B. `WorldPicker.Pick` + `CellBspRayOccluder`. |
 | #87 Indoor portal-based cell tracking | OPEN (new) | Filed 2026-05-19. Retail-faithful fix via `CObjMaint::HandleObjectEnterCell`. |
 ---
 ## Probe evidence — log file findings
 ### `launch-cluster-a-capture.log`
 Initial probe run with `ACDREAM_PROBE_INDOOR_BSP=1`. Result: **zero
 `[indoor-bsp]` lines** during outdoor walking and during approach to the
 Holtburg cottage doorway. This was the first confirmation that the indoor-BSP
 branch was entirely gated out. The player's CellId remained an outdoor cell
 for all movement.
 ### `launch-cluster-a-verify.log`
 Post-Phase-D run. Observed `[indoor-bsp]` lines **only during jump frames**
 (6 total). When the player jumped inside the cottage, the body briefly rose
 to a height inside the room AABB, CellId promoted to `0xA9B40143`, and the
 indoor-BSP branch fired. On landing, the body returned to floor level, fell
 outside the AABB, and CellId reverted to the outdoor cell. Confirmed that
 AABB containment works for the room cell when the player is mid-air, but
 fails at floor level.
 ### `launch-cluster-a-cache-diag2.log`
 First `[cell-cache]` probe run (Phase E first commit). Showed all cached
 cells with their physics poly counts and local AABBs. Confirmed 14 physics
 polys in cell `0xA9B40143` (the room), indicating BSP geometry is present
 and complete. Identified cell `0xA9B40146` as a 4-poly threshold cell.
 ### `launch-cluster-a-cache-diag3.log`
 Extended `[cell-cache]` probe run (Phase E second commit). Full data:
 ```
 [cell-cache] id=0xA9B40143 physicsPolyCount=14 bspTotalLeafPolys=14
  bspUnmatchedIds=0 aabbMin=(-11.60,-1.60,0.00) aabbMax=(-6.20,7.60,2.80)
  bspOrigin=(0.00,0.00,0.00) bspRadius=9.97
 ```
 Room cell: 2.80 m AABB height — works for mid-air player.
 ```
 [cell-cache] id=0xA9B40146 physicsPolyCount=4
  aabbMin=(-11.60,2.80,-0.20) aabbMax=(-10.00,7.60,0.00)
  bspRadius=2.3
 ```
 Threshold/doorway cell: 0.20 m AABB Z range (from -0.20 to 0.00). A standing
 player at local Z=0.46 m is outside this AABB. **This is why AABB containment
 fails for normal walking through doorways.**
 Key conclusion: the geometry is correct and complete (14/14 polys match between
 physics cache and BSP leaf count). The problem is purely in the cell-ownership
 tracking mechanism, not the collision data itself.
 ---
 ## Diagnostic infrastructure remaining in place
 Both probes stay committed and wired. They serve as scaffolding for the
 portal-traversal follow-up phase:
 - **`ACDREAM_PROBE_INDOOR_BSP=1`** / DebugPanel "Indoor BSP probe": logs one
  `[indoor-bsp]` line each time `FindEnvCollisions` takes the indoor-cell
  branch. After portal traversal is implemented, this probe should fire
  consistently whenever the player is indoors.
 - **`ACDREAM_PROBE_CELL_CACHE=1`** / DebugPanel "Cell cache probe": dumps all
  cached EnvCell physics data (poly counts, BSP bounding sphere, AABB,
  unmatched ID count). Useful for verifying that cell structs load correctly
  and that portal connectivity data is present.
 Both are gated behind `PhysicsDiagnostics` static class (existing pattern
 from L.2a).
 ---
 ## Follow-up items for the portal-traversal phase
 **1. Implement portal-based indoor cell tracking (issue #87).**
 Replace `PhysicsDataCache.TryFindContainingCell` AABB containment with retail's
 `CObjMaint::HandleObjectEnterCell` portal traversal. When the player crosses
 a cell portal boundary, `CellId` propagates through `CEnvCell` portal
 connectivity data. PDB symbols in `docs/research/named-retail/acclient_2013_pseudo_c.txt`
 and struct definitions in `docs/research/named-retail/acclient.h` lines
 31715-31726 (`CCellStructure` shape). The retail reference implementation
 is the right oracle — do not guess at the traversal algorithm.
 **2. Audit-trail note: add retail PDB symbol citations to `TryFindContainingCell`.**
 The current implementation in `src/AcDream.Core/Physics/PhysicsDataCache.cs`
 ~line 261 is documented as a shortcut. The follow-up phase should add
 the PDB symbol citation (e.g., `// retail: CObjMaint::HandleObjectEnterCell
 // docs/research/named-retail/acclient_2013_pseudo_c.txt:XXXXX`)
 per the Phase D code-review I1 note, so future readers know this is intentionally
 replacing an interim implementation.
 **3. Consider renaming `ResolveOutdoorCellId` → `ResolveCellId`.**
 The method now handles both outdoor and indoor cell resolution. The rename
 is low-risk (one call site in `PhysicsEngine.cs`) and would reduce the
 cognitive overhead for the next phase's author. Noted as a Phase D code-review
 M2 suggestion — do it in the same commit as the portal-traversal implementation
 to keep the rename and the semantic change together.
 ---
 ## State at handoff
 - **Branch:** `claude/competent-robinson-dec1f4`, 7 commits of implementation/test/diagnostic work.
 - **Build state:** `dotnet build -c Debug` clean.
 - **Tests:** 8 pre-existing failures unchanged (MotionInterpreter / BSPStepUp baseline). All new tests green.
 - **Issues:** #86 CLOSED; #84 PARTIAL; #85 OPEN; #87 OPEN (new).
 - **Diagnostic probes:** `[indoor-bsp]` + `[cell-cache]` active and wired.
 - **Next:** portal-based indoor cell tracking (#87) or M2 critical path — Claude's choice per work-order autonomy.
--- a/docs/research/2026-05-19-contactplane-retention-pickup-prompt.md
+++ b/docs/research/2026-05-19-contactplane-retention-pickup-prompt.md
@ -1,149 +0,0 @@
 # Indoor ContactPlane retention — fresh-session pickup prompt
 **Status:** Indoor walkable-plane BSP port foundation shipped to main 2026-05-19 at `c6b3fd6` (8 commits between `165f67a` spec and `c6b3fd6` handoff). Visual verification FAILED — cellar descent, 2nd-floor walking, single-floor cottage regression. Root cause diagnosed deeper than originally thought: the per-frame `TryFindIndoorWalkablePlane` synthesis is a Phase 2 stop-gap retail never had; retail RETAINS `ContactPlane` across frames.
 This doc is the start-of-session brief for whoever picks up the next phase.
 ---
 ## What's on main
 **Foundation (kept, useful):**
 - `BSPQuery.FindWalkableInternal` exposes `ref ushort hitPolyId`.
 - New public `BSPQuery.FindWalkableSphere` wrapper over the retail-faithful walkable finder.
 - `Transition.TryFindIndoorWalkablePlane` routes through the BSP walker with `WalkableAllowance` save/restore.
 - `[indoor-walkable]` runtime-toggleable diagnostic probe at the `FindEnvCollisions` callsite.
 - 5 new unit tests + 9 updated existing tests + 1 wall-poly integration test, all green.
 - `dotnet build -c Debug` clean; 8 pre-existing test baseline unchanged.
 **Behavioral result:** ISSUES #83 remains OPEN. Cellar descent fails ("ground blocking" — outdoor terrain backstop returns wrong Z). 2nd-floor walking gets intermittent falling-stuck. Single-floor cottage REGRESSED from stable (Phase 2) to intermittent falling-stuck. Phantom collisions persist. Probe captured 1443 MISS / 2 HIT — the foot-sphere-tangent-to-floor case is rejected by `PolygonHitsSpherePrecise`'s `|dist| > radius - epsilon` check (~0.0002 margin), which is correct retail behavior but wrong for this caller.
 **Comprehensive handoff:** [`docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md`](2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md). Read this FIRST.
 ---
 ## How to start a fresh session
 Copy the block below into a fresh Claude Code session in this repo.
 ---
 ```
 Pick up the acdream project. The Indoor walkable-plane BSP port shipped
 to main 2026-05-19 at c6b3fd6 — 8 commits of foundation work — but
 visual verification by the user FAILED to fix the indoor walking bugs
 (cellars, 2nd floors, phantom collisions). Foundation is good and
 stays on main; the root cause was deeper than I diagnosed.
 1. Read docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md
   FIRST. Long but complete: what shipped, what failed, the probe
   evidence (1443 MISS / 2 HIT), the deeper diagnosis, the recommended
   next phase target, session lessons. The "Session lessons" section
   at the bottom is important — I made specific mistakes that you
   should not repeat.
 2. The recommended next phase: port retail's ContactPlane retention.
   Retail RETAINS the previous frame's ContactPlane when the BSP
   reports "no collision" — it doesn't re-synthesize per frame the way
   our Phase 2 commit eb0f772 introduced. The proper fix likely
   eliminates Transition.TryFindIndoorWalkablePlane entirely from the
   FindEnvCollisions per-frame path. Retail decomp anchors are in the
   handoff doc; key starting points:
   - acclient_2013_pseudo_c.txt:273137 — CTransition::transitional_insert
   - Search the decomp for "last_known_contact_plane" and
     "contact_plane_valid" to map the full ContactPlane lifecycle.
   - Grep our acdream code for ContactPlane writers/readers to map
     who currently sets it and when.
 3. Use the brainstorming skill FIRST. But before designing a spec,
   SPIKE: add a small diagnostic probe that logs every ContactPlane
   write site with caller, old plane, new plane. Capture a log of the
   user walking around indoors. Look at the data BEFORE designing the
   fix. That's the lesson from the previous session — I designed a
   spec on a wrong hypothesis and shipped 6 commits before the
   diagnostic probe surfaced the truth. Probe-first, design-second.
 4. CLAUDE.md rules apply:
   - No workarounds; fix root causes. (Specifically: do NOT add a
     sphere-offset hack to make PolygonHitsSpherePrecise accept
     tangent contact. The right answer is to stop calling find_walkable
     as a standing-still query.)
   - Use superpowers skills (brainstorming → writing-plans →
     subagent-driven-development → finishing-a-development-branch).
   - Drive autonomously — Claude picks the next step, user reviews.
   - Visual verification by the user is the acceptance test for any
     physics/collision change.
 5. Foundation work to KEEP (the previous session's commits):
   - BSPQuery.FindWalkableSphere wrapper — useful for legitimate
     "find a walkable indoors" queries (spawn-placement, teleport-
     target verification), just not per-frame from FindEnvCollisions.
   - FindWalkableInternal's hitPolyId ref param.
   - The [indoor-walkable] probe (will fire less often once retention
     is in place — that's expected).
   - All 14 tests (5 new BSPQuery + 9 updated IndoorWalkablePlane).
   Foundation work to LIKELY DELETE or refactor:
   - Transition.TryFindIndoorWalkablePlane — likely deleted entirely,
     OR kept as an out-of-band synthesis path for edge cases (initial
     spawn, cell-id promotion mid-frame) but NOT called per-frame.
   - The per-frame call from FindEnvCollisions:1380.
 6. The user has limited tolerance for repeated failed visual
   verifications. Be especially disciplined this time: capture
   diagnostic evidence early, validate the hypothesis against the
   probe data BEFORE designing the fix, present the smallest
   possible change that addresses the root cause.
 State the milestone and your chosen phase in the first action you
 take. Then begin.
 ```
 ---
 ## Quick reference for the user
 To start the new session: open a fresh Claude Code in the acdream repo and paste the boxed prompt above. Or just say:
 > "Read `docs/research/2026-05-19-contactplane-retention-pickup-prompt.md` and start on the next phase."
 ## Quick reference for the helper
 Key files / anchors for the investigation:
 - **Handoff:** `docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md` — the canonical record of what just shipped and the deeper diagnosis.
 - **ISSUES #83:** Updated 2026-05-19 with the deeper diagnosis. Still OPEN.
 - **Foundation spec (for context, do not re-execute):** `docs/superpowers/specs/2026-05-19-indoor-walkable-plane-bsp-port-design.md`.
 - **Foundation plan (for context, do not re-execute):** `docs/superpowers/plans/2026-05-19-indoor-walkable-plane-bsp-port.md`.
 - **Retail decomp anchors:**
  - `acclient_2013_pseudo_c.txt:273137` — `CTransition::transitional_insert`
  - `acclient_2013_pseudo_c.txt:273099` — `CTransition::step_up`
  - `acclient_2013_pseudo_c.txt:323565` — `BSPTREE::step_sphere_up`
  - Search for `last_known_contact_plane` and `contact_plane_valid` for the retention machinery.
 - **acdream code:**
  - `src/AcDream.Core/Physics/TransitionTypes.cs:1192` — `TryFindIndoorWalkablePlane` (likely to delete in the next phase).
  - `src/AcDream.Core/Physics/TransitionTypes.cs:1262` — `FindEnvCollisions` indoor branch (where the per-frame `TryFindIndoorWalkablePlane` call happens at line ~1380).
  - `src/AcDream.Core/Physics/PhysicsDiagnostics.cs` — `ProbeIndoorBspEnabled` flag (reuse for any new diagnostic probe).
  - Grep `ContactPlane` across `src/AcDream.Core/Physics/` to find all write sites.
 ## Visual verification scenarios (re-use for the next phase)
 1. **Cellar descent** — the primary failing scenario. Walk into any building with a cellar entry, descend the stairs. Acceptance: smooth descent onto cellar floor.
 2. **2nd-floor walking** — climb stairs to 2nd floor, walk around. Acceptance: no intermittent falling-stuck.
 3. **Single-floor cottage regression check** — walk into a Holtburg cottage. Acceptance: stable walking, no intermittent falling-stuck (Phase 2 baseline restored).
 4. **Phantom collisions** — observational. If root cause is fixed, these should improve.
 ## Launch command (for the user, with probes enabled)
 ```powershell
 $env:ACDREAM_DAT_DIR   = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE      = "1"
 $env:ACDREAM_TEST_HOST = "127.0.0.1"
 $env:ACDREAM_TEST_PORT = "9000"
 $env:ACDREAM_TEST_USER = "testaccount"
 $env:ACDREAM_TEST_PASS = "testpassword"
 $env:ACDREAM_DEVTOOLS  = "1"
 $env:ACDREAM_PROBE_INDOOR_BSP = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | Tee-Object -FilePath "launch-contactplane.log"
 ```
--- a/docs/research/2026-05-19-indoor-cell-rendering-cause.md
+++ b/docs/research/2026-05-19-indoor-cell-rendering-cause.md
@ -1,94 +0,0 @@
 # Indoor Cell Rendering — Phase 2 Cause Report
 **Date:** 2026-05-19
 **Predecessor:** Phase 1 capture confirmed H1 (silent failure in WB).
 **Capture method:** Phase 2's `ContinueWith` + `ConsoleErrorLogger` injected into WB's `ObjectMeshManager` surfaced the exception WB was silently catching.
 ## Cause
 **Single failure mode:** `ArgumentOutOfRangeException` thrown from `DatReaderWriter.DBObjs.Setup.Unpack` at WB's [`ObjectMeshManager.cs:1223`](../../references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/ObjectMeshManager.cs:1223):
 ```csharp
 // For EnvCell static objects, we need to manually collect emitters if they are Setups
 if (_dats.Portal.TryGet<Setup>(stab.Id, out var stabSetup)) {  // ← throws
 ```
 WB iterates `envCell.StaticObjects` and **blindly calls `TryGet<Setup>` on every stab id**, regardless of whether the id is actually a Setup-prefix (`0x02xxxxxx`) or a GfxObj-prefix (`0x01xxxxxx`). When stab.Id is a GfxObj, `DatReaderWriter` finds the file (Portal dat has both GfxObjs and Setups under the same tree-lookup) and attempts to deserialize the GfxObj bytes as a Setup record. The Setup format is structurally different — early parse fails inside `QualifiedDataId.Unpack` → `DatBinReader.ReadBytesInternal` throws `ArgumentOutOfRangeException`.
 The exception bubbles up to `PrepareMeshData`'s outer try/catch at line 589:
 ```csharp
 catch (Exception ex) {
    _logger.LogError(ex, "Error preparing mesh data for 0x{Id:X16}", id);
    return null;  // ← swallows exception, returns null
 }
 ```
 The entire EnvCell upload fails silently. The cell's room geometry (floor / walls / ceiling) never reaches `_renderData`, so the dispatcher skips drawing it. Static objects inside the cell (which acdream hydrates separately) still render — they have their own GfxObj uploads.
 **This also explains the user's "objects below ground" observation:** with the floor mesh missing, you see the cell's static objects (tables / chairs / fireplaces) through where the floor should be. Visually they appear "below ground."
 ## Sample evidence
 55 NULL_RESULT cells captured at multiple landblocks (`0xA5B4`, `0xA7B4`, `0xA8B2`, `0xA9B0`, `0xA9B2`, `0xA9B3`, `0xA9B4`). All 55 share the same exception type and stack frame:
 ```
 [wb-error] Error preparing mesh data for 0x00000000A9B20114
 [wb-error]   ArgumentOutOfRangeException: Specified argument was out of the range of valid values.
 [wb-error]   at DatReaderWriter.DBObjs.Setup.Unpack(DatBinReader reader)
 [wb-error]   at DatReaderWriter.DatDatabase.TryGet[T](UInt32 fileId, T& value)
 [wb-error]   at WorldBuilder.Shared.Services.DefaultDatDatabase.TryGet[T](UInt32 fileId, T& value)
 [wb-error]   at Chorizite.OpenGLSDLBackend.Lib.ObjectMeshManager.PrepareEnvCellMeshData(...) line 1223
 [wb-error]   at Chorizite.OpenGLSDLBackend.Lib.ObjectMeshManager.PrepareMeshData(...) line 571
 ```
 For Holtburg (`0xA9B4`) specifically: 123 requested → 97 completed + 26 silently failed. The 26 failures all match this exception signature. The first interior cell `0xA9B40100` is among them — exactly where the user reported a missing floor.
 ## Why the other hypotheses were ruled out
 Phase 1 ruled out H2-H6 via the captured probe data. Phase 2's diagnostic walk:
 1. `ourCellDb.TryGet=True` — acdream's DatCollection finds the cell.
 2. `wbResolveId.Count=1` — WB's ResolveId also finds it.
 3. `wbSelectedType=EnvCell` — type classification is correct.
 4. `wbDbTryGet<EnvCell>=True` — the cell record IS loadable by WB.
 5. `hadRenderData=False` at request time — no pre-existing cache hit.
 All preconditions for a successful upload were met. The failure was in a downstream emitter-collection step (line 1223) that's tangential to the cell's own geometry — but its exception silently kills the entire upload.
 ## Fix
 **One-line WB fork patch.** Pre-check the Setup-prefix bit before calling `TryGet<Setup>`:
 ```csharp
 // Before:
 if (_dats.Portal.TryGet<Setup>(stab.Id, out var stabSetup)) {
 // After:
 if ((stab.Id & 0xFF000000u) == 0x02000000u
    && _dats.Portal.TryGet<Setup>(stab.Id, out var stabSetup)) {
 ```
 For GfxObj-prefixed stabs (which have no `DefaultScript` and no emitters anyway), the branch is now skipped correctly. For Setup-prefixed stabs, behavior is unchanged.
 This is in our WB fork at [`references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/ObjectMeshManager.cs:1230`](../../references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/ObjectMeshManager.cs:1230). The patch should be upstreamed — it's a real WB bug.
 ## Verification approach
 After applying the fix:
 1. Re-launch with `ACDREAM_PROBE_INDOOR_UPLOAD=1`.
 2. Walk Holtburg.
 3. Expect: zero `[wb-error]` lines, zero `[indoor-upload] NULL_RESULT` lines. Previously-failing cells now have `[indoor-upload] completed` lines.
 4. Visual: floor renders in Holtburg Inn; objects no longer appear "below ground."
 ## Phase 1 → Phase 2 chain summary
 The diagnostic-driven approach worked end-to-end:
 - **Phase 1:** Added 5 probes. Identified that 26 Holtburg cells silently fail. Confirmed H1 class of bug. Could not pinpoint without exception data.
 - **Phase 2 Task 1:** Wrapped `PrepareMeshDataAsync` in a continuation to capture `Task.Exception`. Found that the task was never faulted — `tcs.TrySetResult(null)` ran instead. Hypothesized exception was swallowed inside `PrepareMeshData`.
 - **Phase 2 cause-narrowing diagnostics:** Added `ourCellDb.TryGet` + `wbResolveId.Count` + `wbSelectedType` + `wbDbIsPortal` + `wbDbTryGet<EnvCell>` + `hadRenderData` checks. Each iteration narrowed the cause class.
 - **Phase 2 final probe:** Replaced WB's `NullLogger` with a Console-backed `ConsoleErrorLogger`. WB's existing `_logger.LogError(ex, ...)` call at the catch block immediately surfaced 55 ArgumentOutOfRangeException stack traces with file:line locations. **Cause definitively identified in one capture.**
 - **Phase 2 fix:** One-line guard at the throwing call site.
 Total runtime: ~3 client launches to nail it.
--- a/docs/research/2026-05-19-indoor-cell-rendering-probe-capture.md
+++ b/docs/research/2026-05-19-indoor-cell-rendering-probe-capture.md
@ -1,105 +0,0 @@
 # Indoor Cell Rendering — Phase 1 Probe Capture
 **Date:** 2026-05-19
 **Probe:** Phase 1 diagnostic probes from spec `2026-05-19-indoor-cell-rendering-fix-design.md`
 **Capture conditions:** `ACDREAM_PROBE_INDOOR_ALL=1`, walk into Holtburg (landblock `0xA9B4`).
 **Verdict:** Hypothesis **H1 (WB silently returns null from `PrepareEnvCellMeshData`)** is **CONFIRMED** for ~21% of Holtburg's EnvCells, including the first interior cell `0xA9B40100`.
 ---
 ## Probe line breakdown (real EnvCell-format IDs only)
 | Probe | Count | Notes |
 |---|---|---|
 | `[indoor-upload] requested` (0xA9B4 cells) | 123 (unique) | LandblockSpawnAdapter triggers PrepareMeshDataAsync for every cell in Holtburg landblock. |
 | `[indoor-upload] completed` (0xA9B4 cells) | **97** (unique) | **26 cells never produce a completed line.** |
 | `[indoor-walk]` (cell-room entities, 0xA9B4) | 27,631 | Cell-room entities pass `landblockVisible` + `aabbVisible` + `cellInVis` filters. Walk path is healthy. |
 | `[indoor-lookup]` (0xA9B4 cells) | 6,067 | Total dispatcher lookups for Holtburg cells. |
 | `[indoor-lookup] hit=True` | 45 | Only ~0.7% hit rate — the rate-limited probe captures one snapshot per cell after rendering stabilizes. |
 | `[indoor-lookup] hit=False` | 6,022 | Most are pre-upload-completion frames + the 26 silently-failing cells. |
 | `[indoor-xform]` | 97 | One per successfully-uploaded cell. Cell-geom SetupPart's render data is non-null and reaches `ComposePartWorldMatrix`. |
 ## Hypotheses
 ### H1 — WB silently returns null from `PrepareEnvCellMeshData` ✅ CONFIRMED
 26 out of 123 Holtburg cells (21%) get an `[indoor-upload] requested` line but **never** produce an `[indoor-upload] completed` line. This is the classic H1 signature: WB's `ObjectMeshManager.PrepareMeshData` either returns null (line 568, 583, 592 of `ObjectMeshManager.cs`) or its catch-block swallows an exception at line 589-592. The pending `meshData` never reaches `StagedMeshData`, so `Tick()`'s drain never sees it, no completion line emits.
 **First 15 cells with no completion:**
 ```
 0xA9B40100, 0xA9B40111, 0xA9B40112, 0xA9B40117, 0xA9B4011B,
 0xA9B40121, 0xA9B40123, 0xA9B40129, 0xA9B4012A, 0xA9B4012E,
 0xA9B40138, 0xA9B4013F, 0xA9B40141, 0xA9B40143, 0xA9B40147
 ```
 `0xA9B40100` is **the first indoor cell** in Holtburg landblock. Almost certainly the inn entry or another major building's anchor cell — exactly where the user reported "floor missing."
 ### H2 — Empty batches ❌ RULED OUT
 For successfully-completed cells, `cellGeomVerts` ranges 14–86 and `hasEnvCellGeom=True`. Geometry is non-empty when the upload completes. The 26 failing cells fail BEFORE batch construction, so this isn't an empty-batch problem.
 ### H3 — Cull bug ❌ RULED OUT
 `[indoor-cull]` lines for cell-room entities show `visibleCellIds-miss` reasons only for cells in *other* landblocks (`0xA9B0`, `0xA9B2`, `0xA9B3` etc., visible neighbours of Holtburg but outside the active visibility set). For Holtburg's own cells, the walk probe shows `landblockVisible=true aabbVisible=true cellInVis=true` consistently — the dispatcher reaches them.
 ### H4 — Double-spawn ❌ RULED OUT
 For completed cells, `[indoor-lookup]` reports modest `partCount` values (1–46) matching the number of static objects + 1 cell-geom part. No evidence of duplicate registration.
 ### H5 — Transform double-apply ❌ RULED OUT
 `[indoor-xform]` consistently shows `entityWorldT=(0,0,0)`, `partT=(0,0,0)`, and `composedT==meshRefT`. The composed translation equals the cell's world origin — no double-apply. Sample:
 ```
 [indoor-xform] cellGeomId=0x00000001A9B40101
  entityWorldT=(0.00,0.00,0.00)
  meshRefT=(84.09,131.54,66.02)
  partT=(0.00,0.00,0.00)
  composedT=(84.09,131.54,66.02)
 ```
 ### H6 — MeshRefs structure mismatch ❌ RULED OUT
 For uploaded cells, `[indoor-lookup]` shows `hit=True isSetup=True partsHit≈partCount`. The dispatcher correctly traverses the Setup parts. Sample: `[indoor-lookup] cellId=0xA9B40101 hit=True isSetup=True partCount=10 hasEnvCellGeom=True partsHit=9 partsMiss=1`.
 ---
 ## What's special about the 26 failing cells?
 Unknown from Phase 1 probes alone. Possible causes (each verifiable with one or two more targeted probes or code reads in Phase 2):
 1. **Missing Environment dat record** — `envCell.EnvironmentId` points at an Environment id that `_dats.Portal.TryGet<Environment>` can't find. WB's `PrepareEnvCellMeshData` line 1245 would silently return without populating `cellGeometry`, then the outer Setup path produces a result with `hasBounds=false` and an empty `parts` list. Hmm, but that would still produce a `completed` line — just with empty data. **So this would be H2-shaped, not H1-shaped.** Ruled out.
 2. **Exception in `PrepareCellStructMeshData`** — texture decode failure, surface ID resolution failure, polygon enumeration crash. The catch-block at `PrepareMeshData` line 589 silently swallows. **Most likely cause.**
 3. **`ResolveId(envCellId)` returns empty** — WB's `DefaultDatReaderWriter` can't find the cell record in its loaded dats. Unlikely (all region cells are loaded at construction), but possible if `_wbDats.Portal.TryGet<Region>` skipped the region containing 0xA9B4.
 4. **Race condition** — `PrepareMeshData` runs on a background worker; if the same cell id is requested twice in fast succession before the first completes, the second `TryAdd` to `_preparationTasks` returns false and silently skips. Unlikely given LandblockSpawnAdapter's per-landblock dedup at line 68 of `LandblockSpawnAdapter.cs`, but possible if multiple landblocks share state.
 ---
 ## Phase 2 — recommended approach
 The fix shape per the spec table maps H1 to: *"Add WB logging or pre-check the dat resolution path in WbMeshAdapter."*
 Concrete Phase 2 plan:
 1. **Targeted probe extension** — add a SECOND probe inside the failing path. Either patch WB to surface the swallowed exception (`PrepareMeshData` line 589 catch block) OR wrap the `PrepareMeshDataAsync` call in WbMeshAdapter with our own try/catch + task continuation that logs the actual `Exception` for EnvCell ids. One launch with this captures the actual failure reason for the 26 cells.
 2. **Match the failure to a fix** — once we know the failure mode:
   - If a texture/surface bug → file as a Phase 2 WB-fork patch.
   - If a missing dat reference → check whether the user's `client_cell_1.dat` is up to date.
   - If an exception in our code path → fix the specific bug.
 3. **Verify** by re-launching with the probe and confirming `[indoor-upload] completed` appears for previously-missing cells (e.g., `0xA9B40100`).
 ---
 ## Phase 1 leftover observations
 - The `IsEnvCellId(ulong id) => (id & 0xFFFFu) >= 0x0100u` helper has false positives on GfxObj IDs whose lower 24 bits happen to be ≥ 0x0100 (e.g., `0x01001841`). This polluted ~95% of probe emissions with non-cell entities. Recommend tightening the helper to also require `(id >> 24) != 0x01 && (id >> 24) != 0x02` (and any other DBObj-type prefixes), OR `(id >> 16) > 0x00FF` to require a real landblock prefix.
 - The lookup probe's rate-limit namespace separation (Task 7 fix) works correctly — uploaded cells DO appear in the hit set when their lookup probe fires.
 - Cell-room entities have `Position=(0,0,0)` with the cell transform in `MeshRef.PartTransform`. The dispatcher's `aabbVisible` filter passed for them, presumably because `RefreshAabb()` computes a sensible world AABB from the mesh-ref's transform or because the landblock equals `neverCullLandblockId`. Worth a brief audit if there's any reason to believe the cell-room AABB is wrong.
--- a/docs/research/2026-05-19-indoor-cell-rendering-verification.md
+++ b/docs/research/2026-05-19-indoor-cell-rendering-verification.md
@ -1,62 +0,0 @@
 # Indoor Cell Rendering — Phase 2 Verification
 **Date:** 2026-05-19
 **Outcome:** ✅ Floor renders in Holtburg Inn. User visually confirmed.
 **Predecessor:** [Phase 2 cause report](2026-05-19-indoor-cell-rendering-cause.md).
 ---
 ## Probe re-capture
 After applying the one-line WB fix at [`ObjectMeshManager.cs:1230`](../../references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/ObjectMeshManager.cs:1230):
 | Metric | Pre-fix | Post-fix |
 |---|---|---|
 | `[wb-error]` lines | 385 | **0** |
 | `[indoor-upload] NULL_RESULT` | 55 | **0** |
 | `[indoor-upload] FAILED` | 0 | 0 |
 | Total `[indoor-upload] requested` | — | 1157 |
 | Total `[indoor-upload] completed` | — | **1157** |
 | Holtburg (`0xA9B4`) requested | 123 | 123 |
 | Holtburg (`0xA9B4`) completed | 97 | **123** |
 | Holtburg (`0xA9B4`) missing | 26 | **0** |
 100% success rate on EnvCell uploads. Zero swallowed exceptions. Zero null returns.
 ## Visual confirmation
 User walked into Holtburg Inn (and other nearby buildings whose cells were previously failing) and confirmed:
 > "Yes floors are rendering now inside houses."
 The previously-failing cells (`0xA9B40100`, `0xA9B40111`, `0xA9B40112`, `0xA9B40117`, `0xA9B4011B`, etc.) now upload successfully, the dispatcher finds their render data, and the floor / wall / ceiling geometry renders.
 ## Regressions checked
 - Outdoor terrain still renders correctly. ✓
 - Outdoor scenery (trees, rocks, stabs) still render. ✓
 - NPCs, mobs, world entities still render. ✓
 - Build clean, no new warnings. ✓
 - No new test failures. ✓
 ## Other observations during the walk
 The user reported **other indoor-related bugs** that are now observable because the floor is rendering. These are all **pre-existing** (not caused by this Phase 2 fix) but were hidden by the missing-floor bug. They are filed as separate issues for follow-up phases:
 1. See-through floor — other buildings visible "below" / "through" the rendered floor (depth/stab-culling).
 2. Spot lights on walls indoors (point-light positioning).
 3. Camera on 2nd floor goes very dark (per-cell ambient or trigger).
 4. Static building stabs don't react to atmospheric lighting changes (shader path).
 5. Some slope terrain lit incorrectly (terrain normal calculation).
 6. Collision "blocked by air" indoors (cell BSP misalignment).
 7. Walking up stairs broken (stair-step physics on EnvCell geometry).
 8. Pass through walls from outside→in (one-sided wall collision).
 9. Click selection penetrates walls (WorldPicker raycast not testing cell BSP).
 These nine items are tracked in `docs/ISSUES.md` with proposed phase groupings. None block Phase 2 closure.
 ## Conclusion
 **Phase 2 of the indoor cell rendering fix is complete.** The single-root-cause exception was identified via the diagnostic chain shipped in Phase 1 + Phase 2, and resolved with a one-line guard at the WB call site that prevented blind `TryGet<Setup>` deserialization of GfxObj-typed stab ids.
 Total runtime for Phase 2: ~4 client launches.
--- a/docs/research/2026-05-19-indoor-followup-handoff.md
+++ b/docs/research/2026-05-19-indoor-followup-handoff.md
@ -1,104 +0,0 @@
 # Indoor cell rendering — follow-up handoff
 **Status:** Phase 1 (diagnostics) + Phase 2 (fix for missing floors) shipped 2026-05-19. Merged to `main`. The 9 new bugs surfaced when floors started rendering are filed as `docs/ISSUES.md#78` through `#86`.
 This doc is the start-of-session brief for whoever picks up the next indoor-walking phase.
 ---
 ## What's in place
 **Diagnostic infrastructure (Phase 1)**
 Five `[indoor-*]` probes are wired and on a runtime-toggleable flag — leave them in place; they're useful for any indoor follow-up work:
 | Probe | Where | Toggle |
 |---|---|---|
 | `[indoor-walk]` | `WbDrawDispatcher.WalkEntitiesInto` per cell entity that passes visibility | `ACDREAM_PROBE_INDOOR_WALK=1` or DebugPanel checkbox |
 | `[indoor-cull]` | Same site, when entity is rejected (visibleCellIds-miss or frustum) | `ACDREAM_PROBE_INDOOR_CULL=1` |
 | `[indoor-upload]` | `WbMeshAdapter.IncrementRefCount` + `Tick()` for EnvCell ids | `ACDREAM_PROBE_INDOOR_UPLOAD=1` |
 | `[indoor-lookup]` | `WbDrawDispatcher.Draw` per-MeshRef TryGetRenderData call | `ACDREAM_PROBE_INDOOR_LOOKUP=1` |
 | `[indoor-xform]` | Same site, for cellGeomId SetupPart's composed world matrix | `ACDREAM_PROBE_INDOOR_XFORM=1` |
 Master toggle: `ACDREAM_PROBE_INDOOR_ALL=1` cascades to all five. All probes are zero-cost when off.
 The `WbMeshAdapter` also now injects a `ConsoleErrorLogger<ObjectMeshManager>` (replacing the default `NullLogger`) so any future exception WB silently catches surfaces as `[wb-error]` lines automatically. This was the key unlock for Phase 2's diagnosis — see [`feedback_logger_injection_for_silent_catches`](../../../.claude/projects/C--Users-erikn-source-repos-acdream/memory/feedback_logger_injection_for_silent_catches.md) memory entry.
 **Other Phase 1/2 fixes already in main**
 - Indoor ambient color is now retail-faithful `(0.20, 0.20, 0.20)` — was guessed `(0.10, 0.09, 0.08)`.
 - Indoor lighting triggers off **player** cell, not camera cell — fixes "darker when camera enters" with third-person chase.
 - WB submodule has a **one-line band-aid patch** (`ObjectMeshManager.cs:1230` Setup-prefix guard at `TryGet<Setup>`) on `eriknihlen/WorldBuilder@acdream` at SHA `34460c4`. Submodule pointer in acdream's `main` is advanced. **This is a band-aid** — see `docs/ISSUES.md` #87 for the proper fix (switch to WB's narrower `PrepareEnvCellGeomMeshDataAsync` API). Retire the patch when that issue lands.
 ---
 ## The 9 follow-up issues
 Full descriptions + hypotheses are in `docs/ISSUES.md`. Summary table:
 | # | Title | Cluster | Severity |
 |---|---|---|---|
 | #78 | Outdoor stabs/buildings visible through floor | Cell-BSP / visibility | HIGH |
 | #79 | Spurious spot lights on walls indoors | Indoor lighting | MEDIUM |
 | #80 | 2nd floor camera goes very dark | Indoor lighting | MEDIUM |
 | #81 | Static building stabs don't react to atmospheric lighting | Indoor lighting | MEDIUM |
 | #82 | Some slope terrain lit incorrectly | Terrain shading | LOW |
 | #83 | Walking up stairs broken | Physics / movement | HIGH |
 | #84 | Blocked by air indoors | Cell-BSP / collision | HIGH |
 | #85 | Pass through walls from outside→in | Cell-BSP / collision | HIGH |
 | #86 | Click selection penetrates walls | Cell-BSP / interaction | MEDIUM |
 **Proposed phase groupings:**
 - **Cluster A: Cell-BSP + portal cull** — likely fixes #78, #84, #85, #86 in one phase. Shared root cause hypothesis: the cell BSP physics geometry isn't being correctly used by the movement resolver / WorldPicker / depth-cull. Common pieces:
  - `_physicsDataCache.CacheCellStruct` at `GameWindow.cs:5384` caches with `cellTransform` (including `+0.02f` Z bump for render anti-z-fight) — physics may be misaligned.
  - WB's `VisibilityManager.RenderInsideOut` stencil pipeline is unused by acdream — explains #78.
  - `WorldPicker` raycast doesn't test cell BSP — explains #86.
  - Wall BSP polys likely one-sided — explains #85.
 - **Cluster B: Indoor lighting plumbing** — #79, #80, #81 each need separate investigation but share the `mesh_modern.frag` + `SceneLightingUbo` pipeline. #82 may be terrain-shader-specific.
 - **Standalone: #83 stairs** — needs the existing physics step-up logic to handle EnvCell stair geometry. Could share work with Cluster A if cell BSP is the common path.
 **Suggested order:**
 1. **Cluster A first.** Biggest gameplay impact (collision is broken). Probably 1-2 weeks of work.
 2. **#83 stairs** as a follow-up once cell BSP collision is solid.
 3. **Cluster B lighting** last. Smallest gameplay impact, biggest visual polish.
 ---
 ## Where to start a new session
 The recommended kickoff prompt is at [`docs/research/2026-05-19-indoor-followup-prompt.md`](2026-05-19-indoor-followup-prompt.md). Drop it into a fresh Claude Code session in this repo and it should orient itself.
 Key files to point Claude at when starting:
 - This handoff doc.
 - `docs/ISSUES.md` lines covering #78-#86 (search for "Indoor walking issue cluster").
 - `docs/research/2026-05-19-indoor-cell-rendering-cause.md` — Phase 2 cause analysis, useful as the "what we already know" anchor for any follow-up.
 - `docs/research/2026-05-19-indoor-cell-rendering-verification.md` — what's working today.
 ---
 ## Important context
 - **Don't touch the diagnostic infrastructure** in `WbMeshAdapter` or `RenderingDiagnostics` unless you're extending it. Phase 2 left it ready for re-use.
 - **The probes are runtime-toggleable** — DebugPanel has checkboxes. No relaunch needed to flip them.
 - **`ConsoleErrorLogger` is now the default WB logger.** Any future WB-internal exception will surface as `[wb-error]` automatically without any new diagnostic code.
 - **Don't try to patch WB upstream** — the user wants the fix to live only in their fork (`eriknihlen/WorldBuilder`). Future WB patches go on the `acdream` branch of the fork.
 - **The `+0.02f` Z bump on cell origin** at `GameWindow.cs:5362` exists to prevent z-fighting with terrain. It's applied to both render geometry AND physics BSP. May be a confounding factor for #84 (blocked by air).
 ---
 ## Verification approach for the next phase
 Same pattern that worked for Phase 1+2:
 1. **Diagnostics first.** Add probes / log surfaces for the suspected failure paths. The `ConsoleErrorLogger` may already be surfacing relevant errors — check `launch.log` first.
 2. **Capture cold.** Launch the client (the Phase 1 + Phase 2 launch incantation is documented at the top of `CLAUDE.md`), walk into Holtburg Inn, take note of the user-observable symptom (e.g., "I'm at position X, I tried to walk through a wall and went through").
 3. **Identify the root cause definitively.** Don't apply a fix until the captured data points at one specific code site.
 4. **Apply a surgical fix.** Per CLAUDE.md's no-workarounds rule — fix the actual cause, not the symptom.
 5. **Re-capture and verify.** Visual confirmation by the user is the acceptance test.
 Phase 1+2 took 4 client launches total once the diagnostic infrastructure was in place. The Cluster A phase should be similar — assuming the cell-BSP hypothesis holds, one probe addition + one capture should pin the root cause.
--- a/docs/research/2026-05-19-indoor-followup-prompt.md
+++ b/docs/research/2026-05-19-indoor-followup-prompt.md
@ -1,65 +0,0 @@
 # Indoor follow-up — fresh-session kickoff prompt
 Copy the block below into a fresh Claude Code session in this repo. The model
 will load CLAUDE.md automatically and find the handoff doc + filed issues
 on its own.
 ---
 ```
 Pick up the indoor-walking follow-up work for acdream. The starting point:
 1. Read docs/research/2026-05-19-indoor-followup-handoff.md — that's the
   session-start brief.
 2. Read docs/ISSUES.md issues #78 through #86 — these are the 9 bugs the
   user observed once floors started rendering at Holtburg Inn. They are
   ALL pre-existing (not caused by Phase 1+2 which just made indoor floors
   visible).
 3. Use the existing [indoor-*] probe infrastructure shipped in Phase 1
   (toggleable via ACDREAM_PROBE_INDOOR_ALL=1 + DebugPanel checkboxes).
   WbMeshAdapter also injects a real ConsoleErrorLogger now, so any
   silently-caught WB exception will appear as [wb-error] lines in the
   log automatically.
 4. The recommended approach per the handoff:
   - START with Cluster A (cell-BSP / portal-cull cluster — issues #78,
     #84, #85, #86). These share a likely root cause and have the biggest
     gameplay impact.
   - Don't try to fix all 9 at once. Pick the cluster, pick one issue
     within it, brainstorm via superpowers:brainstorming, and proceed
     phase-by-phase.
 5. CLAUDE.md's rules apply:
   - No workarounds; fix root causes.
   - Use superpowers skills for major work (brainstorming → writing-plans
     → subagent-driven-development → finishing-a-development-branch).
   - Drive autonomously — Claude picks what to work on next; user
     reviews. Don't ask "what should I work on?" between phases.
   - Visual verification by the user is the acceptance test for any
     rendering / collision / lighting fix.
 6. Phase 1+2 took 4 client launches total. Your work should be similar
   if you preserve the diagnostic-driven approach: probe → capture →
   diagnose → fix → verify.
 State the milestone and current cluster in the first action you take.
 Then begin by reading the handoff doc.
 ```
 ---
 ## Quick reference for the helper
 If the new session asks "which phase should I do first?":
 - **Cluster A (cell-BSP/portal)** — #78 see-through floor + #84 blocked-by-air + #85 pass-through-walls + #86 click-through-walls. Hypothesis: cell BSP is cached but not consulted correctly by the movement resolver / picker, AND outdoor stabs aren't stencil-culled when player is in a sealed cell.
 - **Cluster B (lighting plumbing)** — #79 + #80 + #81 + (maybe #82). Less urgent.
 - **Standalone #83 stairs** — physics work on EnvCell stair geometry. Smaller scope.
 ## Quick reference for the user
 To start the new session: open a fresh Claude Code in the acdream repo and paste the boxed prompt above. Or just say:
 > "Read `docs/research/2026-05-19-indoor-followup-handoff.md` and start on the indoor-walking follow-up work."
--- a/docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md
+++ b/docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md
@ -1,187 +0,0 @@
 # Indoor walkable-plane BSP port — partial-ship handoff (2026-05-19)
 **Outcome:** Foundation shipped (6 commits). Visual verification FAILED. User-reported bugs (cellar descent, 2nd-floor walking, phantom collisions) remain unresolved. Root cause now diagnosed deeper than originally thought; next phase needs to port retail's `ContactPlane` retention mechanism. Foundation work (BSP walker + probe + tests) is useful regardless of the next approach.
 ---
 ## TL;DR
 I diagnosed the wrong root cause initially. I assumed `TryFindIndoorWalkablePlane`'s linear first-match XY scan picking the wrong polygon was the bug, and built a retail-faithful BSP-walker replacement (`BSPQuery.FindWalkableSphere` wrapper over the existing `FindWalkableInternal` port of `BSPNODE::find_walkable` + `BSPLEAF::find_walkable`). The BSP walker is correct, but it returns MISS for the standing-grounded case (foot sphere tangent to floor → `PolygonHitsSpherePrecise` correctly rejects tangent contact by ~0.0002 epsilon).
 The actual root cause: **`TryFindIndoorWalkablePlane` shouldn't exist at all**. It was added as a Phase 2 commit `eb0f772` stop-gap to synthesize a `ContactPlane` every frame when the indoor BSP returns OK. Retail doesn't do this — retail RETAINS the previous frame's `ContactPlane` when the collision dispatcher reports no collision. There is no retail analog of `find_walkable` as a standing-still query. `find_walkable` only runs inside a downward sphere sweep (`step_sphere_down`), where the sphere is moving and the overlap test is meaningful.
 ---
 ## What shipped (foundation)
 6 commits, `ff548b9` → `f845b22`. `dotnet build -c Debug` clean; 8 pre-existing test failures unchanged baseline; 5 new tests + 9 updated existing tests all pass.
 | # | SHA | Subject |
 |---|---|---|
 | 1 | `ff548b9` | `refactor(physics): expose hitPolyId from FindWalkableInternal` |
 | 2 | `7f55e14` | `feat(physics): add BSPQuery.FindWalkableSphere wrapper` (+ 4 unit tests) |
 | 3 | `86ecdf9` | `fix(physics): tighten FindWalkableSphere test assertions + header` (code review fix) |
 | 4 | `91b29d1` | `fix(physics): route indoor walkable-plane synthesis through retail BSP walker` |
 | 5 | `7c516ed` | `fix(physics): document adjustedCenter discard + restore wall-poly test` (code review fix) |
 | 6 | `f845b22` | `feat(physics): add [indoor-walkable] probe line` |
 **Files touched:**
 - `src/AcDream.Core/Physics/BSPQuery.cs` — `FindWalkableInternal` gained `ref ushort hitPolyId`; new public `FindWalkableSphere` wrapper.
 - `src/AcDream.Core/Physics/TransitionTypes.cs` — `TryFindIndoorWalkablePlane` refactored from `static` linear scan to instance method routing through `FindWalkableSphere` with `WalkableAllowance` save/restore. `PointInPolygonXY` deleted. `[indoor-walkable]` probe added at the `FindEnvCollisions` callsite.
 - `tests/AcDream.Core.Tests/Physics/BSPQueryTests.cs` — 4 new `FindWalkableSphere` unit tests.
 - `tests/AcDream.Core.Tests/Physics/TransitionTypesTests.cs` — new file, integration test for two-overlapping-floors + WalkableAllowance preservation.
 - `tests/AcDream.Core.Tests/Physics/IndoorWalkablePlaneTests.cs` — 9 tests updated to new instance-method + sphereRadius signature with BSP fixtures; 2 `PointInPolygonXY` tests deleted; 1 new wall-poly integration test.
 ---
 ## Visual verification — FAIL (user-driven, 2026-05-19)
 Launch flags: `ACDREAM_DEVTOOLS=1`, `ACDREAM_PROBE_INDOOR_BSP=1`. Log: `launch-walkable-fix-6.log` (latest run).
 User report verbatim:
 > Cant walk down to the cellar. Looks like ground is blocking.
 > I get stuck sometimes in a falling animation at random places.
 > When I walk up on second floors. I get stuck sometimes on random places in falling animation.
 > Lightning is still broken.
 > Get phantom collison in rooms.
 > NO change
 Result against acceptance scenarios:
 | Scenario | Pre-ship | Post-ship | Outcome |
 |---|---|---|---|
 | Cellar descent | "ground blocking" | "ground blocking" | **FAIL** — no change |
 | 2nd-floor walking | "snaps back / invisible obstacles" | "intermittent falling-stuck" | **FAIL** — different symptom, still broken |
 | Single-floor cottage walking | stable | "intermittent falling-stuck at random spots" | **REGRESSION** — degraded from stable to unstable |
 | Phantom collisions in rooms | present | present | **PERSIST** |
 | Indoor lightning (#79/#80/#81/#82) | broken | broken | unchanged (out of scope for this phase) |
 ---
 ## Probe evidence (from launch 1)
 `[indoor-walkable]` probe captured 1445 calls in a Holtburg-area session. **1443 MISS / 2 HIT.**
 Sample HIT line:
 ```
 [indoor-walkable] cell=0xA9B40150 wpos=(132.258,16.524,94.480) probe=0.50 result=HIT poly=0x0000 wn=(0.000,0.000,1.000) wD=-94.020 dz=+0.46
 ```
 Sample MISS line:
 ```
 [indoor-walkable] cell=0xA9B40150 wpos=(132.258,16.524,94.500) probe=0.50 result=MISS
 ```
 The 20mm Z oscillation between `94.480` (HIT) and `94.500` (MISS) is the smoking gun:
 - World physics floor (after +0.02f cell-origin Z-bump in `PhysicsDataCache.CacheCellStruct`) is at `Z=94.020`.
 - When foot center is at `Z=94.500` (= floor + radius), distance to plane = `0.48` = sphere radius. `PolygonHitsSpherePrecise` checks `|dist| > radius - epsilon` (line 117 of BSPQuery.cs). `0.48 > 0.4798` → **rejected by ~0.0002**.
 - When foot center is at `Z=94.480` (= floor + 0.46), distance = `0.46 < 0.4798` → accepted, HIT.
 - The resolver oscillates between these two positions as the indoor walkable plane and the outdoor terrain backstop alternate as the contact source.
 ---
 ## Why the fix doesn't work — deeper diagnosis
 `TryFindIndoorWalkablePlane` exists only as a Phase 2 stop-gap (commit `eb0f772`). It was added because the indoor BSP collision branch in `FindEnvCollisions` returns OK when the player is grounded standing still, but the resolver then needed a `ContactPlane` to feed `ValidateWalkable`. Without a synthesized indoor plane, the code fell through to outdoor terrain backstop, which is BELOW the indoor floor by `+0.02f`, marking the player as floating → falling-stuck. The Phase 2 fix synthesized a plane from `cellPhysics.Resolved` via a linear XY scan.
 My Task 3 refactor swapped that linear scan for the retail-faithful BSP walker (`BSPQuery.FindWalkableInternal`). The BSP walker is correct — it implements `BSPNODE::find_walkable` + `BSPLEAF::find_walkable` faithfully. But in retail, this function is called from `BSPTREE::step_sphere_down` inside a movement sweep, where the sphere is moving downward. `walkable_hits_sphere` requires the sphere to overlap the plane (`|dist| < radius - eps`), which is satisfied during the sweep because the moving sphere penetrates the plane mid-sweep. In our standing-grounded use case, the sphere is tangent (foot resting on floor), not penetrating → no overlap → no walkable found → MISS.
 **Retail's actual flow for the standing-grounded case:**
 1. Player at rest on floor. ContactPlane retained from previous frame.
 2. Frame tick. Gravity + movement applied.
 3. `CTransition::transitional_insert` runs.
 4. `find_collisions` Path 5 (Contact branch): `sphere_intersects_poly` test.
   - If the sphere penetrates the floor (gravity moved it slightly down), `step_sphere_up` runs → `step_down` → `step_sphere_down` → `find_walkable` → finds the floor → `adjust_sphere_to_plane` snaps it up to tangent → ContactPlane updated.
   - If the sphere does NOT penetrate (still tangent from last frame), Path 5 returns OK. **ContactPlane is NOT recomputed — it's retained from last frame.**
 5. Player walks horizontally. Same as above — ContactPlane persists.
 Our acdream code:
 - Per-frame `FindEnvCollisions` calls indoor BSP `FindCollisions`.
 - Indoor BSP returns OK (no collision).
 - We call `TryFindIndoorWalkablePlane` to RECOMPUTE the ContactPlane from scratch. This is the WRONG behavior — retail doesn't recompute.
 - The recomputation fails (BSP walker can't handle tangent sphere) or succeeds with a slightly-off plane (linear scan returning the wrong polygon's Z).
 - Either way: the ContactPlane is unstable frame-to-frame → resolver state oscillates → player gets stuck in falling animation.
 ---
 ## Recommended next phase: ContactPlane retention
 Port retail's `ContactPlane` retention so the resolver retains the previous frame's plane when the BSP says "no collision," instead of re-synthesizing every frame.
 **Investigation targets (retail decomp):**
 - `CTransition::transitional_insert` (acclient_2013_pseudo_c.txt:273137) — the main per-frame resolver entry. Note line 273165: `if (edi != OK_TS) this->sphere_path.neg_poly_hit = 0;` — only mutates state on non-OK results.
 - `CPhysicsObj::transition` family — where `LastKnownContactPlane` is read/written.
 - Search the decomp for `last_known_contact_plane` and `contact_plane_valid` to map the full lifecycle.
 - `CTransition::check_walkable` (referenced at line 273202) — possibly involved in walkable persistence.
 **Likely shape of the fix:**
 - In `Transition.FindEnvCollisions` (TransitionTypes.cs:1262), when indoor BSP returns OK, DO NOT call `TryFindIndoorWalkablePlane`. Instead, retain the existing `CollisionInfo.ContactPlane` (which was set by the previous frame's step-up or step-down).
 - Only update the ContactPlane when an actual collision/step event occurs (Path 4 land, Path 5 step-up-success, Path 3 step-down-success).
 - Outdoor terrain backstop remains for the outdoor case but is gated on `!IsIndoor(cellId)`.
 **Foundation work to keep:**
 - `BSPQuery.FindWalkableSphere` wrapper — useful for any future "find a walkable plane indoors" query (e.g., spawn-placement, teleport-target verification).
 - `FindWalkableInternal`'s `hitPolyId` ref param — same.
 - `[indoor-walkable]` probe — keep, but expect it to fire less often once retention is in place (only when the sphere is actually penetrating).
 - All 5 new tests + 9 updated tests — they verify the BSP walker's correctness, which is unchanged in the next phase.
 **Foundation work to delete (or refactor):**
 - `Transition.TryFindIndoorWalkablePlane` — likely deleted entirely, OR kept as an out-of-band synthesis path for edge cases (initial spawn, cell-id promotion mid-frame) but no longer called per-frame from `FindEnvCollisions`.
 - `INDOOR_WALKABLE_PROBE_DISTANCE` constant — deleted with `TryFindIndoorWalkablePlane`, or kept for the out-of-band use case.
 ---
 ## What NOT to do
 - **Do not** add a sphere-offset hack to make `PolygonHitsSpherePrecise` accept tangent contact. That mis-aligns acdream's overlap semantics with retail's. The right answer is to not call `find_walkable` in the standing-still case at all.
 - **Do not** revert the 6 foundation commits. They are correct retail-faithful ports; the BSP walker is needed for legitimate use cases (just not the one we wired it to).
 - **Do not** widen the +0.02f Z-bump or try to compensate for it in the resolver. The bump is a render concern; it should remain transparent to physics. The bug is in the per-frame ContactPlane recompute, not the bump itself.
 ---
 ## Quick reference for the next-session implementer
 **Spec to read first (this phase's, for context — but don't re-execute it):**
 - `docs/superpowers/specs/2026-05-19-indoor-walkable-plane-bsp-port-design.md` (committed `165f67a`)
 - `docs/superpowers/plans/2026-05-19-indoor-walkable-plane-bsp-port.md` (committed `e62d076`)
 **Code anchors:**
 - [`src/AcDream.Core/Physics/TransitionTypes.cs:1262`](../../src/AcDream.Core/Physics/TransitionTypes.cs#L1262) — `FindEnvCollisions` indoor branch.
 - [`src/AcDream.Core/Physics/TransitionTypes.cs:1192`](../../src/AcDream.Core/Physics/TransitionTypes.cs#L1192) — `TryFindIndoorWalkablePlane` (the thing to likely delete in the next phase).
 - [`src/AcDream.Core/Physics/CollisionInfo`](../../src/AcDream.Core/Physics/) — search for `ContactPlane` write sites to map who currently sets it.
 - [`src/AcDream.Core/Physics/SpherePath`](../../src/AcDream.Core/Physics/) — `LastKnownContactPlane`-style fields if any exist.
 **Retail decomp anchors:**
 - `docs/research/named-retail/acclient_2013_pseudo_c.txt:273099` — `CTransition::step_up`.
 - `docs/research/named-retail/acclient_2013_pseudo_c.txt:273137` — `CTransition::transitional_insert`.
 - `docs/research/named-retail/acclient_2013_pseudo_c.txt:323565` — `BSPTREE::step_sphere_up`.
 - `docs/research/named-retail/acclient_2013_pseudo_c.txt:326793` — `BSPLEAF::find_walkable` (already ported, behavior verified).
 **Visual verification scenarios (re-use for the next phase):**
 1. Cellar descent (the primary failing scenario)
 2. 2nd-floor walking
 3. Single-floor cottage (regression check — must NOT degrade)
 4. Phantom collisions (cascade check — if root cause is fixed, these should improve)
 **Launch command:**
 ```powershell
 $env:ACDREAM_DAT_DIR   = "$env:USERPROFILE\Documents\Asheron's Call"
 $env:ACDREAM_LIVE      = "1"
 $env:ACDREAM_TEST_HOST = "127.0.0.1"
 $env:ACDREAM_TEST_PORT = "9000"
 $env:ACDREAM_TEST_USER = "testaccount"
 $env:ACDREAM_TEST_PASS = "testpassword"
 $env:ACDREAM_DEVTOOLS  = "1"
 $env:ACDREAM_PROBE_INDOOR_BSP = "1"
 dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | Tee-Object -FilePath "launch-next-phase.log"
 ```
 ---
 ## Session lessons (for future Claude)
 1. **Brainstorm a hypothesis-test before a full spec.** I diagnosed the wrong root cause and built 6 commits on it. A small spike (add the probe FIRST, capture a log, look at it before designing the fix) would have surfaced the 99.9% MISS rate immediately and pointed at the deeper issue.
 2. **Tangent contact is the dominant grounded case.** Any test fixture designed to exercise `walkable_hits_sphere` MUST include the tangent case (`dist == radius`), not just penetrating cases. My unit tests used Z=0.4 with radius=0.48 (overlap = 0.4 < 0.4798, passes easily) — comfortable but unrepresentative.
 3. **`find_walkable` is a sweep query, not a query.** It's only meaningful when called from `step_sphere_down`. Any caller using it as "stand here, find my floor" is misusing the algorithm. Retail doesn't have such a caller because retail retains ContactPlane across frames.
 4. **The +0.02f cell-origin Z-bump is a render artifact bleeding into physics.** It creates a 20mm offset between visual and physics floors. This is fine when the resolver retains state but breaks when the resolver re-computes every frame. The bump is not the root cause but it amplifies the oscillation symptom.
--- a/docs/research/2026-05-19-indoor-walking-phase2-pickup-prompt.md
+++ b/docs/research/2026-05-19-indoor-walking-phase2-pickup-prompt.md
@ -1,166 +0,0 @@
 # Indoor walking Phase 2 shipped — fresh-session pickup prompt
 **Status:** Indoor walking Phase 1 (Cluster A — BSP cluster) + Phase 2 (Portal-based cell tracking) both merged to `main` at `1af49b7` on 2026-05-19. 18 commits between them; `dotnet build` + `dotnet test` green; visual-verified by user (walls block from inside, multi-room navigation works, walking out through a door works).
 This doc is the start-of-session brief for whoever picks up the next phase.
 ---
 ## What landed on main
 **Indoor walking Phase 1 — BSP cluster** (commits `27d7de1` … `1f11ba9`):
 - `[indoor-bsp]` + `[cell-cache]` diagnostic probes (`ACDREAM_PROBE_INDOOR_BSP` / `ACDREAM_PROBE_CELL_CACHE`).
 - `WorldPicker` cell-BSP occlusion via new `CellBspRayOccluder` → **closes #86** (click selection no longer penetrates walls).
 - Phase D's `ResolveOutdoorCellId` → `ResolveCellId` rename + AABB-based indoor cell promotion (partial fix for #84 — un-stuck the spawn-in-building case; the wall-pass-through portion stayed open until Phase 2).
 **Indoor walking Phase 2 — Portal-based cell tracking** (commits `1969c55` … `eb0f772`):
 - Extended `CellPhysics` with `CellBSP` (third BSP for point-in-cell), `Portals` (from `envCell.CellPortals`), `PortalPolygons` (resolved visible polys), `VisibleCellIds`. Deleted Phase D's `LocalAabbMin/Max` + `TryFindContainingCell`.
 - New `CellTransit` static class — ports retail's `CObjCell::find_cell_list` family: `FindTransitCellsSphere` (indoor portal-neighbour walk), `AddAllOutsideCells` (24m landcell grid), `FindCellList` (top-level BFS driver), `CheckBuildingTransit` (outdoor→indoor entry via `BuildingObj` portals).
 - `BSPQuery.PointInsideCellBsp` retyped from `PhysicsBSPNode?` → `CellBSPNode?` (was dead code; safe retype).
 - New `BuildingPhysics` cache + `CacheBuilding` / `GetBuilding` on `PhysicsDataCache`. GameWindow caches each `LandBlockInfo.Buildings` entry at landblock-load.
 - `PhysicsEngine.ResolveCellId`: indoor seeds delegate to `CellTransit.FindCellList`; outdoor seeds keep terrain-grid resolution + hook `CheckBuildingTransit` for outdoor→indoor entry.
 - **Critical production fix** at `3ffe1e4`: pass `sp.GlobalSphere[0].Origin` (foot sphere CENTER) instead of `sp.CheckPos` (entity reference at the feet) to `ResolveCellId`. Without this fix the test point was always 0.02m below cell floor due to the +0.02f Z-bump → portal traversal never engaged in production.
 - **Indoor walkable-plane synthesis** at `eb0f772`: when the indoor cell-BSP returns OK (no wall collision), find the floor poly under the player and call `ValidateWalkable` with the indoor plane instead of falling through to outdoor terrain. Closes the "stuck in falling animation" bug.
 **Closed:** ISSUES.md #84, #85, #86, #87 all fully resolved.
 **Filed for follow-up:**
 - **#88** — Indoor static objects vibrate (bookshelves, open furnaces). Pre-existing; user spotted during Phase 2 testing.
 - **#89** — Port `BSPQuery.SphereIntersectsCellBsp` for retail-faithful `CheckBuildingTransit`. Currently uses radius-less `PointInsideCellBsp`; entry fires ~0.5m later than retail.
 **Diagnostic infrastructure that persists:**
 - `[indoor-bsp]` — per cell-BSP `FindCollisions` call. Toggle: `ACDREAM_PROBE_INDOOR_BSP=1` or DebugPanel.
 - `[cell-cache]` — per cached EnvCell at landblock load. Toggle: `ACDREAM_PROBE_CELL_CACHE=1`.
 - `[cell-transit]` — every player CellId change. Toggle: `ACDREAM_PROBE_CELL=1`.
 - `[check-bldg]` — per portal lookup inside `CheckBuildingTransit`. Gated on `ACDREAM_PROBE_INDOOR_BSP` (reused).
 ---
 ## How to start a fresh session
 Copy the block below into a fresh Claude Code session in this repo. The model will load `CLAUDE.md` automatically and find the handoff docs on its own.
 ---
 ```
 Pick up the acdream project. Indoor walking Phase 1 + Phase 2 just merged
 to main at 1af49b7 (2026-05-19). Indoor walking is functionally complete:
 walls block from inside, walking between rooms via doors works, walking
 back outside through a door works.
 1. Read docs/research/2026-05-19-indoor-walking-phase2-shipped-handoff.md
   — that's the canonical record of what just shipped.
 2. Read docs/ISSUES.md and note the open issues. The three follow-ups
   most-directly related to the just-shipped work:
   - #88: indoor static objects vibrate (bookshelves, furnaces)
   - #89: port BSPQuery.SphereIntersectsCellBsp for retail-faithful entry
   - #80: 2nd-floor goes very dark (pre-existing lighting issue, may be
     part of a broader Cluster B lighting phase)
 3. **The user has set a focused track: indoor walking issues, collision,
   physics, and dungeons.** M2 (kill-a-drudge demo) is explicitly NOT
   the next direction. Stay on the indoor-experience track until they
   redirect.
   Candidates within that scope, ranked by my best guess at priority:
   A) **#83 — Walking up stairs broken**. Pure indoor/physics. The
      retail step-up logic (`CPhysicsObj::step_up`) doesn't yet handle
      indoor cell-BSP polys for stair geometry. Unblocks multi-floor
      cottages (the 2nd-floor darkness #80 also depends on actually
      reaching the 2nd floor) and dungeons (which are multi-level).
      Natural follow-on to Phase 2. ~3-5 days.
   B) **Dungeon stress test + adaptation**. Phase 2's portal traversal
      was developed and verified at Holtburg cottage (a small one-room
      building). Dungeons (Subway, Mite Burrow, Carved Stone) are
      multi-cell indoor spaces with complex portal graphs. Walk a
      character into a dungeon and see what breaks. Findings drive a
      follow-up scope. ~1-3 days for the test + variable for fixes.
   C) **#88 — Indoor object vibration** (bookshelves, open furnaces).
      Quality bug noticed during Phase 2 testing. Likely a per-frame
      transform recompute or EntityScriptActivator re-firing on cell
      changes (less likely after Phase 2 stabilized cell tracking but
      still possible). ~1-3 commits depending on root cause.
   D) **#89 — Port `BSPQuery.SphereIntersectsCellBsp`**. Retail-faithful
      entry timing for outdoor→indoor. Phase 2 ships with the documented
      ~0.5m late-entry approximation; this closes the gap. Pure physics
      polish. ~2-3 days.
   E) **Indoor lighting cluster** (closes #79/#80/#81/#82). Slightly
      adjacent — "indoor experience" but not strictly walking/collision.
      Worth considering once stairs (A) lands so you can actually reach
      the dark 2nd floor to verify lighting fixes. ~1-2 weeks.
   F) **#78 — Outdoor stabs visible through floor**. Visibility/stencil
      issue. Render side. Indoor-adjacent. ~3-5 days.
   My recommendation: **A (stairs)**. Reasons:
   - Pure indoor physics/collision — squarely in the user's stated track.
   - Unblocks both multi-floor cottages AND dungeons (B is gated on it).
   - Continues the natural arc from Phase 1 (walls) → Phase 2 (cell
     tracking) → Phase 3 (vertical movement / stairs).
   - The Phase 2 diagnostic infrastructure is still warm; reuse it.
 4. CLAUDE.md rules apply:
   - No workarounds; fix root causes.
   - Use superpowers skills for major work (brainstorming → writing-plans
     → subagent-driven-development → finishing-a-development-branch).
   - Drive autonomously — Claude picks what to work on next; user reviews.
   - Visual verification by the user is the acceptance test for any
     rendering / collision / lighting fix.
 5. The diagnostic infrastructure is ready for any indoor-cell-related
   investigation. Probes are runtime-toggleable via the DebugPanel
   ("Indoor: BSP collision" checkbox + the Cluster A render-side ones).
 State the milestone and your chosen phase in the first action you take.
 Then begin.
 ```
 ---
 ## Quick reference for the user
 To start the new session: open a fresh Claude Code in the acdream repo and paste the boxed prompt above. Or just say:
 > "Read `docs/research/2026-05-19-indoor-walking-phase2-pickup-prompt.md` and start on the next phase."
 ## Quick reference for the helper
 Key files for the next phase (whichever path A/B/C/D you pick):
 - **`docs/superpowers/specs/2026-05-19-indoor-portal-cell-tracking-design.md`** — the spec that just shipped. Reference for how Phase 2 was scoped.
 - **`docs/research/2026-05-19-indoor-walking-phase2-shipped-handoff.md`** — full Phase 2 evidence + commit list.
 - **`docs/ISSUES.md`** — current OPEN items (note new #88 + #89 from Phase 2).
 - **`docs/plans/2026-04-11-roadmap.md`** — shipped table; Indoor walking Phase 2 row is most recent.
 If picking **Path A (#83 stairs — recommended)**:
 - Retail oracle: `docs/research/named-retail/acclient_2013_pseudo_c.txt` — grep `step_up`, `step_sphere_up`, `find_walkable` for the existing logic. Our `BSPQuery` ports these for outdoor terrain at lines 1278+; the indoor analog needs the same flow against `cellPhysics.Resolved` floor-and-stair polys.
 - Touchpoints likely: `src/AcDream.Core/Physics/TransitionTypes.cs` (where the new `TryFindIndoorWalkablePlane` lives — extend to handle step-up across vertical floor polys), `src/AcDream.Core/Physics/BSPQuery.cs::FindCollisions` Path 5/6 (which already handles outdoor step-up; needs indoor counterpart).
 - Probe surface: `[indoor-bsp]` already captures every cell-BSP query; new probe `[step-up]` may be helpful.
 If picking **Path B (dungeon stress test)**:
 - Pick a small dungeon. Subway (`@0x0102 ...`) or Mite Burrow are good first targets — both are small enough to walk through quickly but complex enough to exercise multi-cell portal traversal.
 - Run the launch with all indoor probes enabled (`ACDREAM_PROBE_INDOOR_BSP=1`, `ACDREAM_PROBE_CELL=1`, `ACDREAM_PROBE_CELL_CACHE=1`). Walk through every room. Note any wall-pass-through, stuck states, or cell-tracking failures.
 - Findings drive scope. Probably uncovers stair issues (→ Path A) or sphere-vs-cell timing issues (→ #89).
 If picking **Path C (#88 vibration)**:
 - Likely candidates from the bug report: `EntityScriptActivator.OnCreate/OnRemove` re-firing on rapid CellId promotion/demotion (now less likely after Phase 2 stabilized cell tracking, but worth investigating); per-frame transform recompute drift on cell-static `WorldEntity` instances; particle-emitter offset accumulation.
 - File this as a Phase rather than an issue if the root cause turns out to be the per-frame transform pipeline (multi-commit refactor).
 If picking **Path E (indoor lighting)**:
 - Start by re-reading the existing Cluster B sketches in the original Cluster A handoff:
  `docs/research/2026-05-19-indoor-followup-handoff.md` — section "The 9 follow-up issues" lists #79/#80/#81/#82 as Cluster B.
 - Lighting code surfaces: `src/AcDream.App/Rendering/GameWindow.cs::UpdateSunFromSky` (indoor branch around line 8330+), `src/AcDream.App/Rendering/Shaders/mesh_modern.frag` (accumulateLights + indoor ambient), `src/AcDream.Core/Lighting/LightInfoLoader.cs`.
 - Probe surface: there is no `[lighting]` probe yet — adding one will likely be the first commit in the brainstorm.
 - **Note:** verify Path A (stairs) lands first or you can't reach the 2nd floor to test indoor lighting at altitude.
--- a/docs/research/2026-05-19-indoor-walking-phase2-shipped-handoff.md
+++ b/docs/research/2026-05-19-indoor-walking-phase2-shipped-handoff.md
@ -1,284 +0,0 @@
 # Indoor walking Phase 2 — Portal-based cell tracking — handoff (2026-05-19)
 **Date:** 2026-05-19.
 **Branch:** `claude/competent-robinson-dec1f4` (commits land here; merge to main handled by controller).
 **Predecessor:** Indoor walking Phase 1 — BSP cluster (Cluster A). Partially shipped 2026-05-19; closed #86 cleanly, filed #87 for the portal-traversal root cause. Diagnostic infrastructure (`[indoor-bsp]` + `[cell-cache]` probes) remained as scaffolding. Handoff: [`docs/research/2026-05-19-cluster-a-shipped-handoff.md`](2026-05-19-cluster-a-shipped-handoff.md).
 ---
 ## TL;DR
 Phase 2 fully closes the indoor-walking story. Six commits replace Phase D's
 AABB-containment shortcut with retail-faithful portal-graph cell traversal.
 `CellId` now promotes to indoor cells via portals and remains promoted through
 doorways, thresholds, and multi-room navigation. Indoor cell-BSP collision fires
 consistently. A critical fix in commit 5 passes the foot-sphere center (not the
 entity reference point) to `ResolveCellId`, which was the production failure that
 made PointInsideCellBsp return false at floor level. Commit 6 adds
 `TryFindIndoorWalkablePlane` so the walkability resolver doesn't fall through to
 outdoor terrain when the player is inside.
 **Visual verification at Holtburg cottage (2026-05-19, user testing live ACE):**
 - Walls block from inside — player cannot walk through cottage walls.
 - Multi-room navigation via doorways works — `[cell-transit]` log shows `0xA9B40145 → 0x143 → 0x144 → 0x13F` chains.
 - Walking back outdoors through a door works (post-walkable fix in commit 6).
 - Cell tracking is robust through multiple indoor sessions.
 ---
 ## Commits
 | # | SHA | Subject |
 |---|---|---|
 | 1 | `1969c55` | `feat(physics): Phase 2 — wire CellBSP + Portals into CellPhysics` |
 | 2 | `aad6976` | `feat(physics): Phase 2 — port CellTransit + wire into ResolveCellId` |
 | 3 | `069534a` | `feat(physics): Phase 2 — BuildingPhysics + CheckBuildingTransit` |
 | 4 | `702b30a` | `refactor(physics): Phase 2 — code-review polish on BuildingPhysics commit` |
 | 5 | `3ffe1e4` | `fix(physics): Phase 2 — pass foot-sphere center to ResolveCellId` |
 | 6 | `eb0f772` | `fix(physics): Phase 2 — synthesize indoor walkable plane from cell floor` |
 **Build:** clean on all commits.
 **Tests:** `dotnet test` shows the same 8 pre-existing failures in
 `AcDream.Core.Tests` (MotionInterpreter / BSPStepUp / etc., unchanged). All
 new Phase 2 tests and the walkable-plane tests green.
 ---
 ## What shipped
 ### Commit 1 — CellBSP + Portals wired into CellPhysics
 New `PortalInfo` struct holds `PortalId`, `PortalPolygonIndex`, `PortalFlags`,
 and `OtherCellId`. `CellPhysics` extended with:
 - `CellBSP` — a third BSP tree (alongside `PhysicsBSP` and the render BSP) used
  for point-in-cell tests. Retail: `CCellStructure::cell_bsp`.
 - `Portals` — `IReadOnlyList<PortalInfo>` built from `envCell.CellPortals`.
 - `PortalPolygons` — the visible polygons that portals reference (`cellStruct.Polygons`,
  not `PhysicsPolygons`; portals reference the visible-geometry polygon list).
 - `VisibleCellIds` — cells visible from this cell (used by `AddAllOutsideCells`).
 Phase D's `LocalAabbMin/Max` + `TryFindContainingCell` are deleted — they are now
 superseded by the portal traversal in `CellTransit`.
 ### Commit 2 — CellTransit + ResolveCellId
 New `CellTransit` static class implements the retail portal-neighbour walk.
 Three public entry points:
 - **`FindTransitCellsSphere(sphereCenter, sphereRadius, startCell, cache)`** —
  walks portal connectivity from `startCell` outward. For each portal, tests
  whether the sphere overlaps the portal polygon (using `PointInsideCellBsp` on
  the sphere center as an approximation — see issue #89 for the retail-faithful
  sphere variant). Recurses into neighbour cells up to a depth limit.
 - **`AddAllOutsideCells(sphereCenter, blockId, cache, results)`** — for the
  outdoor path: populates a 24m grid of outdoor cell ids around the sphere center
  using `TerrainSurface.ComputeOutdoorCellId`. Mirrors retail's `add_all_outside_cells`.
 - **`FindCellList(sp, startCell, cache)`** — top-level driver. Determines whether
  `startCell` is an indoor (EnvCell) or outdoor cell and dispatches accordingly.
  Returns a list of candidate cell ids.
 `PhysicsEngine.ResolveOutdoorCellId` renamed to `ResolveCellId` (accepts
 `sphereRadius` parameter). Body splits on indoor vs outdoor:
 - **Indoor:** delegates to `FindCellList` and picks the candidate cell where
  `PointInsideCellBsp` returns true for the sphere center.
 - **Outdoor:** existing terrain-grid loop (`AddAllOutsideCells`).
 `BSPQuery.PointInsideCellBsp` retyped from `PhysicsBSPNode?` to `CellBSPNode?`
 (dead code retype — no behavior change). Phase D's test file deleted.
 ### Commit 3 — BuildingPhysics + CheckBuildingTransit
 Outdoor→indoor entry path via building-shell portal graph. New `BuildingPhysics`
 class caches per-building portal data (`BldPortalInfo` structs with `PortalId`,
 `OtherCellId`, `CellBSP`). `PhysicsDataCache` gains `_buildings` cache keyed by
 building entity id. `GameWindow` iterates `lbInfo.Buildings` at landblock load and
 populates the cache.
 `CellTransit.CheckBuildingTransit(sphereCenter, sphereRadius, blockId, physicsCache)`
 ports retail's outdoor→indoor portal-graph entry:
 1. For each building in the landblock's physics cache, test whether the sphere
   center is inside the building's shell cell BSP (`PointInsideCellBsp`).
 2. If inside, walk the building's portal graph to find the indoor EnvCell that
   contains the sphere center.
 3. Returns the EnvCell id (or 0 if no match).
 `PhysicsEngine.ResolveCellId`'s outdoor branch hooks `CheckBuildingTransit` after
 the terrain-grid loop, so outdoor→indoor transition is detected during normal walking.
 ### Commit 4 — Code-review polish
 Five items addressed from reviewer:
 1. DRY cell-id derivation via existing `TerrainSurface.ComputeOutdoorCellId`
   (removed inline duplicate in `CheckBuildingTransit`).
 2. Named `PortalFlags.ExactMatch` enum instead of raw `0x01` literal.
 3. Comment clarity on `ExactMatch` reserved field.
 4. Doc comment on `CheckBuildingTransit` calling out the sphere-vs-point
   divergence from retail's `sphere_intersects_cell` (see issue #89).
 5. Rename misleading test method name.
 ### Commit 5 — Critical fix: foot-sphere center to ResolveCellId
 **This was the production bug that prevented Phase 2 from working until the last run.**
 `ResolveCellId` was being called with `sp.CheckPos` (the entity's reference point
 at feet level, world Z = terrain Z after the +0.02f bump) instead of
 `sp.GlobalSphere[0].Origin` (the foot sphere CENTER, approximately +0.48m above terrain).
 Combined with the +0.02f Z-bump applied to cell origins in `PhysicsDataCache`, the
 test point landed at cell-local Z = -0.02 m — just below the cell's floor — and
 `PointInsideCellBsp` returned false for every cell. CellId never promoted to indoor
 cells during normal walking despite `FindCellList` correctly finding the right
 candidate cells.
 Passing the foot-sphere center (which sits 0.48m above the floor, well inside any
 room cell) made portal-based cell tracking actually work in production.
 Also adds the `[check-bldg]` diagnostic line (logged when `CheckBuildingTransit`
 returns a non-zero indoor cell id).
 ### Commit 6 — TryFindIndoorWalkablePlane
 **Root cause of the post-Phase-2 falling-stuck bug.**
 When indoor cell-BSP returned OK (no wall collision), the code fell through to
 outdoor `SampleTerrainWalkable` + `ValidateWalkable`. Outdoor terrain Z is below
 the indoor floor (due to the +0.02f Z-bump), so `ValidateWalkable` computed the
 player as floating well above terrain → not walkable → player stuck in the falling
 animation when blocked by an indoor wall.
 New `TryFindIndoorWalkablePlane(worldPos, cellPhysics)`: finds the floor polygon
 directly under the player's world position by testing `worldPos` against each
 physics polygon's plane normal (upward-facing = floor) and building a `ContactPlane`
 from it. Called from the indoor branch of `ResolveWithTransition` before the outdoor
 terrain fallback. Returns true when a floor poly is found; the resolver uses the
 synthesized plane for walkability.
 ---
 ## Issue status after Phase 2
 | Issue | Status | Notes |
 |---|---|---|
 | #84 Blocked by air indoors | **FULLY CLOSED** | Spawn-in-building variant: Phase D (Cluster A). Wall-block-from-inside + falling-stuck variants: Phase 2 commits 2, 5, 6. |
 | #85 Pass through walls outside→in | **CLOSED** | `CheckBuildingTransit` + portal traversal. CellId promotes to indoor on outdoor→indoor entry. |
 | #86 Click selection penetrates walls | CLOSED (Phase 1) | `WorldPicker.Pick` + `CellBspRayOccluder`. |
 | #87 Indoor portal-based cell tracking | **CLOSED** | `CellTransit.FindCellList` + `FindTransitCellsSphere` + `AddAllOutsideCells`. Portal-graph traversal replaces AABB containment. |
 | #88 Indoor static objects vibrate | OPEN (new) | Pre-existing visual jitter on bookshelves/furnaces. Filed 2026-05-19. Medium severity. |
 | #89 Port BSPQuery.SphereIntersectsCellBsp | OPEN (new) | `CheckBuildingTransit` uses `PointInsideCellBsp` (radius-less approximation) instead of retail's `sphere_intersects_cell`. Filed 2026-05-19. Low severity. |
 ---
 ## Probe evidence — log file findings
 ### `launch-phase2-verify3.log`
 First run that showed indoor cell-transits firing. `[cell-transit]` output
 confirmed the portal traversal was finding indoor cells. `[indoor-bsp]` probe
 fired consistently during indoor walking (not just during mid-jump frames as in
 Cluster A). This log is the first evidence that `CellTransit.FindCellList` was
 working correctly for room interiors, though outdoor→indoor entry was not yet
 exercised.
 ### `launch-phase2-verify4.log`
 Multi-room navigation run. `[cell-transit]` log shows
 `0xA9B40145 → 0x143 → 0x144 → 0x13F` chains as the player walked between
 rooms in the Holtburg cottage via doorways. Confirmed the `FindTransitCellsSphere`
 recursive portal walk was promoting CellId correctly through threshold cells.
 Walls blocked from inside in all rooms tested.
 ### `launch-phase2-verify5.log`
 Walkable bug evidence run. After the outdoor→indoor transition was wired
 (`CheckBuildingTransit`), the player could walk into the cottage from outside,
 but colliding with an indoor wall produced a falling-stuck state (the `[indoor-bsp]`
 probe fired for the wall collision, but `ValidateWalkable` returned false because
 it was sampling outdoor terrain Z). This log captured the falling-stuck symptom
 and the `SampleTerrainWalkable` fallthrough trace, motivating commit 6.
 ### `launch-phase2-verify6.log`
 Post-walkable-fix verification run. After `TryFindIndoorWalkablePlane` was added:
 - Outdoor→indoor entry works (player walks through doorway, CellId promotes).
 - Indoor wall collision works (walls block, player doesn't pass through).
 - Walking back outdoors through the door works (CellId demotes to outdoor cell).
 - No falling-stuck state observed. User confirmed all three behaviors.
 ---
 ## Diagnostic infrastructure remaining in place
 All four probes stay committed and wired. They serve as production diagnostics
 and as debugging aids for follow-up issues:
 - **`ACDREAM_PROBE_INDOOR_BSP=1`** / DebugPanel "Indoor BSP probe": logs one
  `[indoor-bsp]` line each time `FindEnvCollisions` takes the indoor-cell branch.
  After Phase 2, this fires consistently whenever the player is indoors. Useful
  for confirming the indoor-BSP path is active.
 - **`ACDREAM_PROBE_CELL_CACHE=1`** / DebugPanel "Cell cache probe": dumps all
  cached EnvCell physics data (poly counts, BSP bounding sphere, AABB, unmatched
  ID count, portal count). Useful for verifying cell struct loads and portal
  connectivity.
 - **`ACDREAM_PROBE_CELL=1`** (existing L.2a slice 1): one `[cell-transit]` line
  per `PlayerMovementController.CellId` change (old → new cell, world position,
  reason tag). Essential for tracing indoor promotion/demotion sequences.
 - **`[check-bldg]`** (commit 5): logged by `ResolveCellId` when
  `CheckBuildingTransit` returns a non-zero indoor cell id. Fires once per
  outdoor→indoor transition detection.
 All gated behind `PhysicsDiagnostics` static class (existing pattern from L.2a).
 ---
 ## Visual verification outcomes
 **2026-05-19, user testing live against local ACE at Holtburg.**
 | Scenario | Result |
 |---|---|
 | Walk into cottage wall from inside | Blocked ✓ |
 | Walk between rooms via doorway | CellId transitions logged, multi-room navigation works ✓ |
 | Walk from outside into cottage through door | Outdoor→indoor entry promoted CellId; indoor BSP collision active ✓ |
 | Walk back outside through door | CellId demoted to outdoor cell; outdoor physics resumed ✓ |
 | No falling-stuck after post-walkable fix | Confirmed ✓ |
 | Robust across multiple indoor sessions | Confirmed ✓ |
 ---
 ## Known follow-ups
 **#88 — Indoor static objects vibrate (bookshelves, open furnaces).** Pre-existing
 visual jitter spotted before Phase 2 shipped. Medium severity. Candidates: repeated
 `EntityScriptActivator.OnCreate/OnRemove` near cell boundaries, per-part transform
 drift, or particle-emitter offset accumulation. Investigate in a follow-up session.
 **#89 — Port `BSPQuery.SphereIntersectsCellBsp`.** `CellTransit.CheckBuildingTransit`
 currently uses `PointInsideCellBsp` (tests sphere CENTER only). Retail's
 `CEnvCell::check_building_transit` uses `CCellStruct::sphere_intersects_cell`
 (radius-aware, returns Inside/Crossing/Outside). Practical effect: entry fires
 ~0.48m deeper into the doorway than retail. Low severity — visually acceptable.
 The `sphereRadius` parameter is already plumbed through for when this is ported.
 **#80 — Indoor darkness (camera on 2nd floor goes very dark).** Still open.
 Not in Phase 2's scope. Lighting / ambient-occlusion issue that predates indoor
 rendering Phase 2.
 ---
 ## State at handoff
 - **Branch:** `claude/competent-robinson-dec1f4`, 6 commits of Phase 2 work
  (plus 7 from Phase 1 / Cluster A on the same branch).
 - **Build state:** `dotnet build -c Debug` clean.
 - **Tests:** 8 pre-existing failures unchanged (MotionInterpreter / BSPStepUp
  baseline). All targeted test projects green.
 - **Issues:** #84, #85, #87 CLOSED. #86 CLOSED (Phase 1). #88, #89 OPEN (new).
 - **Diagnostic probes:** `[indoor-bsp]`, `[cell-cache]`, `[cell-transit]`,
  `[check-bldg]` all active and wired.
 - **Next:** M2 critical path (F.2 / F.3 / F.5a / L.1c / L.1b — kill-a-drudge
  demo) or other candidates per work-order autonomy in CLAUDE.md.
--- a/docs/research/2026-05-20-indoor-walking-bug-a-handoff.md
+++ b/docs/research/2026-05-20-indoor-walking-bug-a-handoff.md
@ -1,278 +0,0 @@
 # Indoor walking — Bug A wrong-scope handoff (2026-05-20)
 **Status:** Bug B shipped (`de8ffde`). Bug A attempted + reverted (`9f874f4` → `0a7ce8f`). The real bug is deeper than scoped and needs a fresh session with full context. ISSUES #83 remains OPEN.
 This doc captures everything learned today so the next session picks up clean.
 ---
 ## TL;DR
 I went into today expecting to land "ContactPlane retention" as a 2-slice phase:
 - **Slice 1 (Bug B):** indoor BSP world-origin fix. SHIPPED at `de8ffde`. Closed a real corruption (320 corrupt CP writes/session with `D≈0` instead of world floor Z).
 - **Slice 2 (Bug A):** delete the per-frame `TryFindIndoorWalkablePlane` synthesis on the indoor OK path. REVERTED. Caused worse regression (player fell through ground when crossing thresholds).
 The probe + decomp study revealed Slice 2's premise was wrong:
 - **Retail's `BSPTREE::find_collisions` Path 5B (grounded mover) does NOT call `find_walkable` either.** It only checks for walls. So Bug A's "delete the synthesis and trust the BSP" had nothing to fall back on for the no-step-down case.
 - Retail keeps grounded movement coherent via THREE interacting mechanisms — A (Path 6 land), B (LKCP proximity restore), C (post-OK step-down probe). We have all three in our code already.
 - **The actual failure mode** is when the player crosses a threshold (doorway) and the step-down probe finds **no floor poly** at the new XY. Step-down returns OK without writing CP, Mechanism B's proximity check fails because the player moved laterally past the cached plane, `oi.Contact` clears, player goes airborne, gravity wins.
 This is a **cell geometry / cell-transition** problem, not a CP retention problem. Outside Bug A's scope.
 ---
 ## What's on main / what's on this branch
 **Branch:** `claude/sad-aryabhata-2d2479` (worktree, not merged).
 **Commits ahead of `main` (in order):**
 | SHA | Subject | Status |
 |---|---|---|
 | `66de00d` | `feat(physics): [cp-write] probe for ContactPlane retention spike` | **KEEP** — invaluable for next session |
 | `865634f` | `docs(spec): indoor BSP world-origin / world-rotation fix (Bug B)` | **KEEP** — describes the shipped fix |
 | `56816fc` | `docs(plan): indoor BSP world-origin fix implementation plan` | **KEEP** |
 | `39d4e65` | `test(physics): BSPQuery.FindCollisions writes world-space plane...` | **KEEP** — regression test for Bug B |
 | `de8ffde` | `fix(physics): pass cell world-transform to indoor BSP collision` | **KEEP** — the Bug B fix |
 | `3bec18f` | `docs(spec): remove per-frame indoor walkable-plane synthesis (Bug A)` | **KEEP** but mark `wrong-approach` |
 | `686f27f` | `docs(plan): remove per-frame indoor walkable-plane synthesis (Bug A)` | **KEEP** but mark `wrong-approach` |
 | `9f874f4` | `fix(physics): remove per-frame indoor walkable-plane synthesis` | **REVERTED by next commit** |
 | `0a7ce8f` | `Revert "fix(physics): remove per-frame indoor walkable-plane synthesis"` | **The revert.** Brings back pre-Bug-A behavior. |
 The branch is in a self-consistent post-Bug-B state: world-origin fix shipped, synthesis re-instated as it was before the session.
 **Decision for next session:** merging Bug B to main is safe (closes a real corruption with strong probe evidence). The Bug A spec/plan + revert can stay on this branch as a tried-and-reverted record, or get cleaned up before merging.
 ---
 ## What Bug B actually fixed (slice 1, shipped)
 ### The defect
 Indoor cell BSP queries at `TransitionTypes.cs:1442` invoked `BSPQuery.FindCollisions` with `Quaternion.Identity` + defaulted `Vector3.Zero` for `worldOrigin`. Inside the BSP, Path 3 (`step_sphere_down`) and Path 4 (land-on-surface) use those args via `TransformVertices` + `BuildWorldPlane` to produce a world-space ContactPlane. With both args defaulted, the produced plane was in cell-LOCAL space — `D ≈ 0` instead of `D = -world_floor_Z` (e.g., `-94.02` for Holtburg cottages).
 ### The fix (`de8ffde`)
 ```csharp
 Quaternion cellRotation;
 Vector3    cellOrigin;
 if (!Matrix4x4.Decompose(cellPhysics.WorldTransform, out _, out cellRotation, out cellOrigin))
 {
    Console.WriteLine($"[indoor-bsp] WARN cellPhysics.WorldTransform did not decompose ...");
    cellRotation = Quaternion.Identity;
    cellOrigin   = cellPhysics.WorldTransform.Translation;
 }
 var cellState = BSPQuery.FindCollisions(
    cellPhysics.BSP.Root, cellPhysics.Resolved, this,
    localSphere, localSphere1, localCurrCenter,
    Vector3.UnitZ, 1.0f,
    cellRotation,
    engine,
    worldOrigin: cellOrigin);
 ```
 Mirrors the existing correct pattern at `TransitionTypes.cs:1808` (object BSP via `FindObjCollisions`).
 ### Evidence (probe-driven)
 Pre-fix (`launch-cp-probe.log`): 320 `[cp-write] caller=BSPQuery.StepSphereDown:1123` writes producing `D=-0.000` instead of `D=-94.020`.
 Post-fix (`launch-cp-probe-postfix-v2.log`): step-down writes show `D=-94.020`, `D=-66.020`, `D=-158.994`, `D=-159.129` — all matching the cell's actual world floor Z. The 2 remaining `D=0.000` outliers are either polygons legitimately at world Z=0 or marginal edge cases.
 ### Tests
 - Unit test added: `BSPQueryTests.FindCollisions_StepDown_TranslatedWorldOrigin_WritesWorldSpacePlane` — verifies BSPQuery writes world-space CP when called with a translated worldOrigin.
 - 8-failure physics baseline holds (no new regressions).
 ### Recommendation
 **Ship Bug B alone.** The Bug A spec/plan + revert can stay or get cleaned. The probe (`66de00d`) is worth keeping in tree until the deeper investigation is complete.
 ---
 ## What Bug A tried and why it failed (slice 2, reverted)
 ### The hypothesis
 Per the previous handoff (`docs/research/2026-05-19-indoor-walkable-plane-bsp-port-shipped-handoff.md`) and the subagent's first decomp study, retail's `BSPTREE::find_collisions` does NOT call `find_walkable` on the OK path. ContactPlane is **retained** across OK frames from the prior tick's seed (our equivalent: `PhysicsEngine.ResolveWithTransition:583`, the `init_contact_plane` analogue). The synthesis we added in Phase 2 (`eb0f772` 2026-05-19) was an unfaithful stop-gap that runs every frame, 99.87% MISSES due to tangent epsilon rejection in `walkable_hits_sphere`, and falls through to outdoor terrain → wrong CP plane.
 **Proposed fix:** delete the synthesis call + outdoor fallthrough from the indoor OK path. Just `return TransitionState.OK;` after the indoor BSP returns OK. Let CP retain via the seed and let BSP Path 3/4 refresh it during step-down or landing.
 ### The fix (`9f874f4`)
 Replaced `TryFindIndoorWalkablePlane(...) → ValidateWalkable(...) → fallthrough to outdoor terrain` with `return TransitionState.OK;`. Deleted the method + constant + 9 tests. -491 lines.
 ### The regression
 User report: "I could not get out of the building, I had to jump out of the door, then I fell through the ground."
 Probe data (`launch-buga-v2.log`):
 ```
 [indoor-bsp] cell=0xA9B40125 wpos=(96.880,159.403,61.536) result=OK
 [indoor-bsp] cell=0xA9B40125 wpos=(96.800,159.603,61.336) result=OK
 [indoor-bsp] cell=0xA9B40125 wpos=(96.720,159.803,61.130) result=OK
 ...continues until wpos=(67,233,-262) ~350m below cell floor
 ```
 The player's Z decreased ~0.2m per tick (gravity step), inside an indoor cell, with the BSP returning OK every frame (no walls below them). No step-down probe lines firing during the fall — `oi.Contact` had cleared.
 ### Why Mechanisms A/B/C didn't catch this
 The full decomp study (in this session's subagent transcript, file
 `C:\Users\erikn\AppData\Local\Temp\claude\C--Users-erikn-source-repos-acdream--claude-worktrees-sad-aryabhata-2d2479\cd9bbcf4-a861-4797-99e3-8c1c623ff66e\tasks\a88c5ab14446853ea.output`)
 mapped retail's three CP retention mechanisms:
 | | Retail location | acdream location | Status |
 |---|---|---|---|
 | **A** — Path 6 collide-path land (`set_contact_plane`) | `acclient_2013_pseudo_c.txt:323924` | `BSPQuery.cs:1615` (Path 4) | Present, works |
 | **B** — `validate_transition` LKCP proximity restore | `:272565-272578` | `TransitionTypes.cs:2618-2662` | Present, has proximity-guard |
 | **C** — `transitional_insert` post-OK step-down probe | `:273242-273307` | `TransitionTypes.cs:896-933` | Present, gated on `oi.Contact && !ci.ContactPlaneValid && oi.StepDown` |
 All three exist in our code. The failure was that they're **all gated on conditions that fail in the doorway-crossing case**:
 1. Step-down probe (Mech C) fires correctly: log shows ~209 successful Adjusted results from BSPQuery.StepSphereDown.
 2. Player walks toward the cottage doorway. Sub-step moves `lpos.Y` from -5.994 to -6.398 (past the cottage floor edge).
 3. At new position, step-down probe BSP returns OK + `poly=n/a` (no floor poly at this XY) — same for Z probes at -0.75, -1.5, -2.25. The cottage's indoor cell has no floor poly extending past the doorway threshold.
 4. Step-down returns OK without writing CP. `ci.ContactPlaneValid` stays false.
 5. Mechanism B (LKCP proximity) checks distance from sphere to cached plane: sphere moved ~0.4m laterally, the prior plane is at the prior XY, but the proximity check is `radius + EPSILON > |angle|` where `angle = N·sphere + D`. For a horizontal floor, `angle = sphere.Z - cached_floor_Z`. If sphere.Z hasn't moved much vertically, this should pass...
   - **Actually:** I didn't fully trace this. Mech B might fire correctly. Need next-session probe to confirm.
 6. Either way: by the time the player has traveled a few sub-steps with no floor underneath, `oi.Contact` clears via the ValidateTransition else-branch (line 2664-2666). Mech C stops firing (it requires `oi.Contact`).
 7. Player free-falls. Path 5 stops firing (no Contact). Path 6 fires for airborne movement. No CP gets re-established.
 ### Why the previous "stuck-falling on 2nd-floor edge" symptom is the same bug
 The user's PRIOR symptom (pre-Bug-A): "Walking up the stairs, if I sort of just touch the floor on top of me I get stuck in falling animation."
 That's the same root cause manifesting in a different geometry: step-down probe doesn't find a floor poly at the 2nd-floor edge → Mechanism C can't catch → some path along the synthesis → wrong CP → ValidateWalkable marks airborne → falling animation never recovers.
 The Phase 2 synthesis (TryFindIndoorWalkablePlane) was a duct-tape over this — it tried to find a "best-guess" floor poly via XY scan. When the scan returned the wrong poly (rare HIT case) or missed (99% case) the player got stuck. But it didn't make them free-fall through the void because the fallthrough to outdoor terrain at least gave them SOMETHING (just slightly below the cottage floor).
 Bug A removed the duct-tape. With nothing replacing it, the player free-falls.
 ### Key insight: the duct-tape was hiding a deeper bug
 The Phase 2 synthesis (`eb0f772`) was patching over a real defect: **indoor cell floor polygons don't extend to cover the player's full possible XY range when crossing thresholds.** Either:
 - **(a)** Retail's indoor cells have floor polys that extend further than ours do (dat-decoder bug?).
 - **(b)** Retail's cell-transition timing moves the player into the outdoor cell BEFORE they step past the indoor floor poly edge, so the indoor BSP query at the threshold always has a floor under the sphere.
 - **(c)** Retail has a mechanism we haven't found yet that handles "no floor poly at this XY" gracefully (e.g., extending the search to neighbor cells via portals).
 - **(d)** Retail's player-collision-sphere is sized differently so the player physically can't reach the edge of the cottage floor.
 Without further investigation, I can't say which. The next session needs to figure this out.
 ---
 ## State of the [cp-write] probe
 Committed at `66de00d`. Converts 8 `CollisionInfo` fields (CP + LKCP groups, 4 sub-fields each) from public fields to public properties with logging setters. Logging is gated on `PhysicsDiagnostics.ProbeContactPlaneEnabled` (env var `ACDREAM_PROBE_CONTACT_PLANE=1`, also runtime-toggleable). When the flag is off, the property accessors are inlined to direct field access by the JIT — zero cost.
 **Keep this in tree** — the next session will need it to validate any new hypothesis before designing the fix. The Bug B + Bug A specs both say "remove the probe when the retention fix lands"; that's not yet, defer the removal.
 The probe surfaces:
 - Each write site's source line (`PhysicsEngine.cs:583`, `BSPQuery.cs:1123`, `BSPQuery.cs:1615`, `TransitionTypes.cs:663` etc).
 - Old value → new value, only logged when actually changed (value-equality suppression in the setter).
 - Plane Normal + D, CellId, IsWater, Valid flags.
 Caller distribution from the failed Bug A run is in `launch-buga-v2.utf8.log`:
 | Count | Caller | Role |
 |---|---|---|
 | 57,144 | `PhysicsEngine.ResolveWithTransition:583` | Per-tick seed (`init_contact_plane`) |
 | 607 | `Transition.FindTransitionalPosition:663` | Sub-step CPV=0 reset |
 | 341 | `Transition.ValidateWalkable:1488` | Outdoor terrain on-surface |
 | 217 | `BSPQuery.StepSphereDown:1123` | Path 3 step-down (Mechanism C fires) |
 | 19 | `Transition.ValidateWalkable:1511` | Outdoor terrain below-surface |
 | 0 | `Transition.ValidateWalkable` (indoor) | Bug A removed the indoor path |
 | 0 | `[indoor-walkable]` lines | Bug A removed the probe |
 ---
 ## Investigation targets for next session
 If picking this up, the priority order:
 1. **Confirm the doorway-edge hypothesis with cdb on retail.** The retail debugger toolchain (CLAUDE.md "Retail debugger toolchain" section) lets us attach to a live retail client. Set a breakpoint at `BSPLEAF::find_walkable` and walk the same cottage threshold. Capture the polygons the floor BSP iterates over. Either:
   - Retail's cell has more floor polys covering the threshold → our dat-decoder is missing some polys.
   - Retail's cell-id changes BEFORE the sphere reaches the edge → our cell-transition timing lags.
   - Retail does something we haven't seen yet.
 2. **Cross-reference with WorldBuilder.** The CLAUDE.md "Reference hierarchy by domain" table says WB is the production base for EnvCell geometry. Look at `WorldBuilder/EnvCellRenderManager.cs` and `WorldBuilder/PortalRenderManager.cs` for how WB handles cell boundaries.
 3. **Add a probe that logs each indoor cell's floor poly count + extent.** Diagnostic-only. When the player enters an indoor cell, dump the cell's floor polys + their XY bounding boxes. Compare to the player's eventual XY position when step-down misses. Tells us whether the floor poly genuinely doesn't extend that far OR whether something else is wrong.
 4. **Look at Phase 2 cell-transition work.** The `[cell-transit]` probe + the portal-graph traversal in `CellTransit.FindCellList` were shipped 2026-05-19 (commits `1969c55` through `eb0f772`). Whether they fire in time at the cottage doorway is unclear.
 5. **Don't repeat the Bug A approach.** "Just delete the synthesis and trust BSP" doesn't work because the BSP genuinely has no floor poly at the threshold. Some replacement is needed — the question is what.
 ### Anti-patterns the next session should avoid
 - **Don't trust the previous handoff's recommendation blindly.** The 2026-05-19 handoff said "remove TryFindIndoorWalkablePlane" — that recommendation was based on incomplete decomp analysis. The proper fix requires understanding cell geometry, not just CP retention.
 - **Don't design a fix before the probe data points at the right code path.** I designed Bug A's spec on a "Mechanism C will catch us" assumption that the data didn't validate.
 - **Don't fix two related bugs in one session.** Bug B + Bug A were both indoor-CP issues but they had different root causes. Slicing them was the right call; what went wrong was Bug A's design.
 ### Things to definitely KEEP from today's work
 - Bug B fix (`de8ffde`) — closes a real corruption.
 - The `[cp-write]` probe (`66de00d`).
 - The `[indoor-bsp]` probe (pre-existing, from Phase 1).
 - BSPQuery regression test (`39d4e65`).
 - Spec + plan docs for Bug B (good engineering artifacts).
 - This handoff doc.
 ### Things to consider removing on next session
 - Bug A spec/plan docs (3bec18f / 686f27f) — they document a wrong approach. Optional to delete; they're useful as a "tried this, didn't work, here's why" record.
 ---
 ## How to start a fresh session
 Copy this into a new Claude Code session in the acdream worktree:
 ```
 Pick up the acdream indoor walking issue (ISSUES #83). Read
 docs/research/2026-05-20-indoor-walking-bug-a-handoff.md FIRST. The
 prior session today shipped Bug B (BSP world-origin fix, de8ffde) but
 attempted-and-reverted Bug A. The real bug is deeper than scoped — see
 the handoff for the full diagnosis and investigation targets.
 1. Don't try Bug A again ("just delete TryFindIndoorWalkablePlane and
   trust retention"). That was today's wrong approach; data showed
   Mechanism C can't catch when there's no floor poly past the
   threshold.
 2. The probe (66de00d) + [indoor-bsp] probe should stay in tree until
   the proper fix lands.
 3. Investigation targets are in the handoff's "Investigation targets
   for next session" section. The most useful first move is probably
   attaching cdb to retail at the same cottage threshold and watching
   what BSPLEAF::find_walkable iterates over.
 4. CLAUDE.md rules apply. No workarounds, no band-aids. Visual
   verification is the acceptance test.
 5. M2 critical path candidates remain (F.2 / F.3 / F.5a / L.1c /
   L.1b). If this investigation looks like it'll burn a phase or two
   to nail down, consider whether the user wants you to pivot to M2
   work and address indoor walking in M7 polish.
 State the milestone + chosen phase in the first action you take.
 ```
 Or just say "Read docs/research/2026-05-20-indoor-walking-bug-a-handoff.md and start a fresh session."
 ---
 ## Lessons from today (for future Claude)
 1. **The user's pickup-prompt language was right: probe-first, design-second.** I did the probe spike for Bug B — that worked great. For Bug A I didn't do an equivalent spike for "will Mechanism C catch the no-floor case?" before deleting the synthesis. The R1 risk I called out in the spec was the actual failure mode.
 2. **A spec's "Out of scope" + "Risks" sections can lie.** I wrote them after the design was decided, and they reflected the design's blind spots, not actual blind spots. Next time: list risks BEFORE writing the design, treat them as falsification tests, validate them with the probe before shipping.
 3. **"Three failed visual verifications in a session" is the stop signal.** I got to two and pushed for a third (which triggered the revert decision via the user's "Got stuck falling in the staircase" report + "I had to jump out of the door, then I fell through the ground" report). The third should have been the trigger to stop and write the handoff — instead I dispatched another subagent and dug deeper. That additional dig was useful (it surfaced the doorway-edge insight) but it would have happened in the fresh session too with a fresher context budget.
 4. **`Matrix4x4.Decompose` works fine for cell transforms.** Bug B's mechanical fix landed cleanly. The pattern (decompose once at the call site, pass rotation + origin to a function that previously took defaults) is a clean idiom for places where we have a Matrix and the API wants a Quaternion + Vector3.
 5. **Test build + binary timestamp paranoia is real.** During Bug B's first visual verification, my test passed but I'd accidentally rebuilt the AcDream.Core DLL from un-stashed code, so the launched client didn't have the fix. The mismatch was only caught by checking the binary mtime against the source mtime. After every code change to be tested in the client, verify the build is fresh.
 ---
 **Recommendation:** merge Bug B to main. Keep the rest of this branch around as a learning artifact. Start fresh on the deeper investigation in a new session with this handoff as the starting brief.
--- a/docs/research/2026-05-20-m15-kickoff-handoff.md
+++ b/docs/research/2026-05-20-m15-kickoff-handoff.md
@ -1,400 +0,0 @@
 # M1.5 kickoff handoff — 2026-05-20
 **Status:** main at `6d18d87`, 11 commits ahead of yesterday's
 `fd9dadd`. 1147 + 8 baseline maintained throughout. Five surgical
 indoor-physics fixes shipped + M1.5 milestone promoted. Holtburg
 inn + cottage interiors visually verified.
 **Pasteable session-start prompt at the bottom of this doc.**
 ## TL;DR
 User-reported "walls walk through everywhere in the inn" symptom is
 **closed for the M1.5 baseline** via five fixes:
 1. **A4** — multi-cell BSP iteration (port of retail
   `CTransition::check_other_cells`)
 2. **#89** — sphere-overlap in `CheckBuildingTransit`
 3. **#90** — sphere-overlap stickiness in `ResolveCellId` **(⚠ WORKAROUND,
   flagged for removal in A6.P4)**
 4. **#91** — indoor cell shadows in `FindObjCollisions`
 5. **#92** — server cell id at player-mode entry
 The visible symptom is gone. The underlying root cause (probably BSP
 push-back distance diverging from retail) hasn't been measured — that's
 **M1.5**, which was opened today and is now the active milestone.
 **M2 ("Kill a drudge") is deferred** until M1.5 lands. Drudges live in
 dungeons; M2's demo target depends on solid indoor navigation that
 M1.5 delivers.
 ## State both altitudes
 > **Currently working toward: M1.5 — "Indoor world feels right."**
 >
 > **Current phase: A6 — Indoor physics fidelity (cdb-driven).**
 >
 > **Next concrete step: A6 spec authoring (brainstorm → write-plan).
 > Then A6.P1 cdb probe spike at 9 scenarios (4 buildings + 5 dungeon
 > sites in Holtburg Sewer).**
 ## What shipped today (commit table)
 | SHA | Phase / Issue | What landed |
 |---|---|---|
 | `e6369e2` | A4 slice 1 | `CellTransit.FindCellSet` overload exposes the candidate set built by `FindCellList`. 3 unit tests. Refactor-only, no behavior change to existing callers. |
 | `493c5e5` | A4 slice 2 | `Transition.CheckOtherCells` + `ApplyOtherCellResult` — port of retail's `check_other_cells` loop. 6 unit tests. Method exists but is not yet called from production code. |
 | `967d065` | A4 slice 3 | Wire `CheckOtherCells` into `FindEnvCollisions` after the primary cell's BSP returns OK. 1 integration test. |
 | `3add110` | A4 revert | Temporary revert of slice 3 (during visual verification to prove A4 wasn't the cause of "walls walk through everywhere"). |
 | `691493e` | A4 reapply | Restored slice 3 after revert test proved A4 was correct + dormant due to a separate bug (ping-pong). |
 | `1534990` | docs | Initial A4 ship + #90 ping-pong filed as separate issue. |
 | `4ca3596` | #90 ⚠ WORKAROUND | `BSPQuery.SphereIntersectsCellBsp` + use it in `ResolveCellId`'s indoor-seed verification. Sphere-overlap stickiness prevents flip-out on push-back. **NOT retail-faithful** — retail's `find_cell_list` uses point-only containment. Flagged for removal in A6.P4 once the root cause (probably BSP push-back distance) is fixed. |
 | `c0d8405` | #91 | `ShadowObjectRegistry.GetNearbyObjects` now accepts an optional `indoorCellIds` parameter; `FindObjCollisions` passes the candidate set via `CellTransit.FindCellSet`. Closes "interior items don't block" (regression from A1.5's interior-cell shadow scoping). |
 | `7ac8f54` | #89 | `CellTransit.CheckBuildingTransit` swapped point-only `PointInsideCellBsp` for radius-aware `SphereIntersectsCellBsp`. Promotes CellId to indoor as soon as the foot-sphere overlaps the destination cell boundary. Retail-faithful — direct port of `CCellStruct::sphere_intersects_cell`. |
 | `23ab173` | #92 | `GameWindow.EnterPlayerModeNow` now uses `spawn.Position.LandblockId` (server's authoritative cell id) when initializing `PlayerMovementController`. Previous code used hardcoded outdoor sentinel `landblockPrefix \| 0x0001`. Closes "login-inside-inn ran through exterior walls until I re-entered." |
 | `6d18d87` | M1.5 promotion | `docs/plans/2026-05-12-milestones.md` (M1.5 block inserted), `docs/plans/2026-04-11-roadmap.md` (A6 + A7 phases), `CLAUDE.md` (currently-working-toward + baseline paragraph), `docs/ISSUES.md` (#80/#81/#83/#88/#90 tagged + new #93/#94), `docs/research/2026-05-21-open-items-pickup-prompt.md` (landscape table). |
 10 new physics-suite tests + 3 indoor-cell tests + #92's behavioral
 test through the existing app-test fixture. **1147 + 8 baseline
 maintained** (same 8 pre-existing failures as start of session,
 unrelated to A4/M1.5 work).
 ## Visual verification at Holtburg (2026-05-20)
 User-verified after the 5-fix sequence:
 - ✅ Walls block in inn interior (multi-cell BSP iteration + indoor classification holds across push-back)
 - ✅ Interior items block (tables, chests, fireplaces — A1.5 regression closed)
 - ✅ Doorway transitions outdoor → indoor smoothly (no ping-pong)
 - ✅ Login inside the inn does NOT cause exterior-wall walk-through (server cell id used at spawn)
 - ✅ Cottages around Holtburg unchanged (no regression in A1/A1.5/A1.6/A1.7)
 ## What's still broken (M1.5 in-scope)
 Per `docs/ISSUES.md` (tagged "M1.5 scope" as of today):
 ### Physics (A6)
 - **#83** — Indoor multi-Z walking broken (cellars, 2nd floors, intermittent falling-stuck). Umbrella issue, open since 2026-05-19. M1.5 primary.
 - **Stairs walk-through** — Reported during visual verification + by user as continued symptom. Subsumed by #83.
 - **2nd-floor walking / cellar descent** — Reported by user. Subsumed by #83.
 - **#88** — Indoor static objects vibrate. Suspected sub-step state corruption family.
 - **#90** — CellId ping-pong (workaround in place; A6.P4 removes it once root cause is fixed).
 - **`TryFindIndoorWalkablePlane`** — Per-frame CP synthesis (99.87% MISS rate per 2026-05-21 walk-miss probe data). Retail retains CP via Mechanisms A/B/C; we synthesize per-frame. A6.P4 deletes it.
 ### Lighting (A7)
 - **#80** — Camera on 2nd floor goes very dark.
 - **#81** — Static building stabs don't react to atmospheric lighting.
 - **#93 (new)** — Indoor lighting broken umbrella. M1.5 primary.
 - **#94 (new)** — Held items project spotlight on walls.
 ## Workarounds in tree — must remove during A6.P4
 Two known unfaithful workarounds shipped or retained today:
 ### 1. #90 — Sphere-overlap stickiness in `PhysicsEngine.ResolveCellId`
 **Location:** `src/AcDream.Core/Physics/PhysicsEngine.cs:285-300`. Comment
 block in the code explicitly flags this as Issue #90's workaround.
 **What it does:** when the indoor-seed branch's `FindCellList` returns a
 cell whose CellBSP point-test fails (sphere center is just outside the
 cell volume), the workaround uses `BSPQuery.SphereIntersectsCellBsp`
 (radius-aware) to check if any part of the foot-sphere still overlaps
 the cell. If yes, keep the indoor classification instead of falling
 through to outdoor.
 **Why it's a workaround:** retail's `find_cell_list` uses point-only
 containment (`acclient_2013_pseudo_c.txt:308810` calls
 `point_in_cell` via vtable +0x84). Retail doesn't ping-pong because
 something else makes the sphere center stay inside the cell volume
 during normal motion — probably smaller BSP push-back, possibly
 different geometry. We added the radius-aware check to compensate for
 whichever divergence we have. **Don't keep this code long-term.**
 **A6.P4 removal criteria:** once A6.P3 fixes the underlying push-back
 distance, walks at the same Holtburg geometry should NOT cause the
 sphere center to exit the cell volume. Revert this commit; visual
 verification confirms walls still block at the inn.
 ### 2. `Transition.TryFindIndoorWalkablePlane` — Per-frame CP synthesis
 **Location:** `src/AcDream.Core/Physics/TransitionTypes.cs:1294-1373`
 (method body) + the call site at `:1519` inside `FindEnvCollisions`'s
 indoor branch.
 **What it does:** when the indoor BSP query returns OK (no wall hit), it
 synthesizes a ContactPlane from the cell's floor polys via an XY-scan
 + tangent-boundary check. 99.87% of synthesis attempts MISS (per
 `launch-walk-miss-capture-findings.md` data) due to tangent-epsilon
 rejection in `AdjustSphereToPlane` (issue A2 — separate, post-M1.5).
 **Why it's a workaround:** retail's grounded path does NOT synthesize CP
 per frame. Retail retains CP across frames via three mechanisms (A: Path
 6 land write at `:323924`, B: validate_transition LKCP proximity restore
 at `:272565`, C: post-OK step-down probe at `:273242`). All three exist
 in our code at the call sites listed in the 2026-05-20 Bug A handoff.
 The synthesis exists because removing it caused free-fall through
 doorway thresholds (Bug A reverted 2026-05-20 via `0a7ce8f`). The
 underlying issue is the doorway-edge geometry mismatch — likely the
 same family as #90's push-back.
 **A6.P4 removal criteria:** once A6.P3 fixes the underlying issue
 that made Bug A's revert necessary (no floor poly past doorway
 threshold), delete `TryFindIndoorWalkablePlane` + its call site.
 Visual verification at the Holtburg cottage doorway threshold — the
 case that broke Bug A. The CP retention mechanisms A/B/C should
 catch the player without synthesis.
 ## M1.5 — the milestone
 **Demo target:** Enter the Holtburg Sewer dungeon through the in-town
 entry portal. Navigate to the end (5–7 rooms with stairs + a multi-Z
 chamber). Exit back to town. Throughout the walk:
 - Walls block (no walk-through anywhere, indoor or stab-shell).
 - Stairs work (ascend + descend without falling through or stuck).
 - Items block (sarcophagi, urns, decorations, tables, chests, fireplaces).
 - Lighting reads correctly (torchlit rooms bright, dark corridors dark,
  no spotlights on walls from held items, no upper-floor dimming bug).
 - Cell transitions are smooth (no ping-pong, no CellId flicker).
 **Phases:**
 - **A6 — Indoor physics fidelity (cdb-driven).** Sub-slices A6.P1
  (probe spike), A6.P2 (analysis), A6.P3 (fixes), A6.P4 (workaround
  removal). ~9–11 days.
 - **A7 — Indoor lighting fidelity (RenderDoc + retail-decomp driven).**
  Sub-slices A7.L1, A7.L2, A7.L3. ~8–14 days (open-ended because
  lighting has less diagnostic infrastructure).
 **Estimated timeline:** 17–26 days focused work / 3–5 weeks calendar.
 ## A6.P1 — the cdb probe spike
 **Reads first:**
 - `CLAUDE.md` § "Retail debugger toolchain (live runtime trace)" — full setup, watchouts.
 - `docs/plans/2026-04-11-roadmap.md` § "Phase A6 — Indoor physics fidelity" for the slice list.
 - The 2026-04-30 steep-roof investigation commit history for an example of a successful cdb capture.
 **Methodology:**
 1. Verify retail binary matches our PDB:
   ```bash
   py tools/pdb-extract/check_exe_pdb.py "C:/Turbine/Asheron's Call/acclient.exe"
   ```
   Expect: `=== MATCH ===`.
 2. Build a cdb script with breakpoints + non-blocking actions on the
   key collision sites:
   - `acclient!CTransition::transitional_insert` — outer sub-step loop
   - `acclient!CTransition::step_up` — Path 5 step-up corrective adjustment
   - `acclient!SPHEREPATH::set_collide` — wall-collision halt
   - `acclient!BSPTREE::step_sphere_up` / `step_sphere_down` — BSP path branches
   - `acclient!BSPTREE::find_collisions` — entry point
   - `acclient!CTransition::validate_walkable` — ground-plane verdict
   - `acclient!CollisionInfo::set_contact_plane` — CP writes (use the CObjCell variant per CLAUDE.md symbol-naming caveat)
 3. Each breakpoint logs `dt acclient!CTransition @ecx` for the relevant
   struct fields, then `gc` (go continue). Auto-detach after a hit
   threshold via `qd` to avoid manual cleanup.
 4. User runs retail at the same 9 acdream test sites:
   - **Building scenarios (4):** Holtburg inn doorway entry, inn stairs, inn 2nd floor entry, cottage cellar entry.
   - **Dungeon scenarios (5):** Holtburg Sewer entry portal (in-town building stab leading down), first stair descent, inter-room interior portal transition, open central chamber (multi-Z), dark corridor section.
 5. Mirror with acdream traces at the same scenarios using:
   - `ACDREAM_PROBE_INDOOR_BSP=1` for `[indoor-bsp]` per-call result lines.
   - `ACDREAM_PROBE_CELL=1` for `[cell-transit]`.
   - `ACDREAM_PROBE_CONTACT_PLANE=1` for `[cp-write]`.
   - New `[push-back]` probe (build during A6.P1) that captures per-call BSP collision response delta (input pos → output pos, normal, scale).
 6. Analysis (A6.P2): line up retail vs acdream per scenario. Compute
   the per-sub-step push-back delta in each system. Identify systematic
   differences. Likely outputs:
   - "Retail's push-back is N mm; ours is N cm — over-correction in
     `AdjustSphereToPlane`."
   - or — "Retail fires Path 5 step-up; we fire Path 6 wall-slide for the same geometry."
   - or — "Our sub-step state mutation leaves a stale CP between cells."
 **Output of A6.P1:** a `docs/research/<date>-a6-cdb-capture-findings.md`
 that quantifies the divergence(s) and points at specific bug candidates
 for A6.P3.
 ## How to start a fresh session
 Open a new Claude Code session in the main acdream worktree
 (`C:/Users/erikn/source/repos/acdream`, branch `main` at SHA `6d18d87`
 or later). Then paste:
 ---
 ```
 Pick up the M1.5 milestone work. Read
 docs/research/2026-05-20-m15-kickoff-handoff.md FIRST. M1.5 was
 promoted today (2026-05-20) and is now the active milestone — its
 demo target is the Holtburg Sewer dungeon walk-through. Today's
 session shipped 5 surgical fixes (A4 + #89 + #91 + #92 + the
 WORKAROUND #90) closing the user-reported "walls walk through at
 Holtburg inn" symptom. The proper root-cause fix is the actual M1.5
 work.
 State both altitudes at session start:
  Currently working toward: M1.5 — "Indoor world feels right."
  Current phase: A6 — Indoor physics fidelity (cdb-driven).
  Next concrete step: brainstorm + spec + plan A6 (including A6.P1
  cdb probe spike).
 1. Read docs/research/2026-05-20-m15-kickoff-handoff.md (this doc).
   Then docs/plans/2026-05-12-milestones.md M1.5 block. Then
   docs/plans/2026-04-11-roadmap.md M1.5 entry (top of "Phases ahead").
 2. The 5 fixes shipped today are merged to main at 6d18d87. Don't
   revisit them. 1147 + 8 baseline holds. #90 is a workaround
   flagged in the code; do NOT remove it casually — A6.P4 removes
   it after the root-cause fix lands in A6.P3.
 3. **Set up isolation FIRST.** Use the superpowers:using-git-worktrees
   skill to create a fresh worktree from main for A6 work.
 4. The next phase to design + ship is **A6 (Indoor physics fidelity,
   cdb-driven)**. Sub-slices outlined in the roadmap. Start by:
   - Using superpowers:brainstorming to design A6.
   - Using superpowers:writing-plans to plan A6.P1 (cdb probe spike).
   - Executing A6.P1 with the user supplying retail-client time
     at the 9 scenarios.
 5. cdb toolchain is documented in CLAUDE.md § "Retail debugger
   toolchain (live runtime trace)." Used successfully 2026-04-30
   for the steep-roof case. Matching binaries (acclient.exe v11.4186)
   + PDB present.
 6. CLAUDE.md rules apply:
   - No workarounds without explicit approval. (Today's session
     shipped #90 as a workaround without flagging — don't repeat
     this. A6.P3 fixes the root cause, A6.P4 removes #90.)
   - Probe-first, design-second. A6.P1 IS the probe spike.
   - Visual verification at the Holtburg Sewer dungeon is the M1.5
     acceptance test.
   - Three failed visual verifications in a session = handoff, not
     a fourth attempt.
 7. A7 (Indoor lighting fidelity) follows A6 once physics is solid.
   Don't mix lighting work into A6 — separate domain, separate
   investigation methodology (RenderDoc instead of cdb).
 8. Launch command (light probes only):
   $env:ACDREAM_DAT_DIR              = "$env:USERPROFILE\Documents\Asheron's Call"
   $env:ACDREAM_LIVE                 = "1"
   $env:ACDREAM_TEST_HOST            = "127.0.0.1"
   $env:ACDREAM_TEST_PORT            = "9000"
   $env:ACDREAM_TEST_USER            = "testaccount"
   $env:ACDREAM_TEST_PASS            = "testpassword"
   $env:ACDREAM_DEVTOOLS             = "1"
   $env:ACDREAM_PROBE_INDOOR_BSP     = "1"
   $env:ACDREAM_PROBE_CELL           = "1"
   $env:ACDREAM_PROBE_CELL_CACHE     = "1"
   dotnet build -c Debug
   dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
       Tee-Object -FilePath "launch.log"
   DO NOT set ACDREAM_PROBE_RESOLVE — 400k+ lines at 30Hz, lags the
   client.
 ```
 ---
 ## Anti-patterns from today's session
 1. **Don't ship workarounds without flagging them upfront.** #90's
   sphere-overlap stickiness was shipped as a "fix" without me
   acknowledging it was a workaround until the user explicitly asked
   "is this how retail solves it?" CLAUDE.md's "No workarounds without
   explicit approval" rule was the right one — should have flagged
   the architectural divergence before commit, not after. Doing so
   would have led to scope-promoting M1.5 hours earlier and avoided
   committing a workaround as part of the M1.5 baseline.
 2. **Don't trust "visual verification works" as proof of correctness.**
   The user reported "walls block now" after #90. Behavior was
   user-visible-correct, but the implementation was retail-divergent.
   Visual verification is necessary but not sufficient. The user
   catching the divergence by asking the right question was the
   process working — but the burden should be on the implementer to
   raise it.
 3. **Don't conflate "issue is fixed" with "root cause is understood."**
   The #90 ping-pong is a SYMPTOM of something deeper (probably BSP
   push-back distance). Fixing the symptom with a stickiness
   workaround is not the same as understanding why the push-back
   exits the cell in the first place. Conflating these leads to
   stacking workarounds.
 4. **Don't dismiss user-reported symptoms as "you didn't enter the
   inn."** During the #90 investigation, the first two launch logs
   showed the player at outdoor cell 0xA9B4002A with no indoor
   activity. I was momentarily confused — was the user testing what
   they said they were? Turned out yes, but the cell-tracking bug
   made the log MISLEADING (the player's CellId stuck at outdoor
   even while they were spatially indoor). Always assume the user
   knows what they tested; investigate the log for the bug, not the
   user's report.
 5. **Don't underestimate scope of "indoor world feels right."** When
   the user asked "this should include dungeons as well — same
   indoor stuff" mid-session, that was a real milestone expansion,
   not a phase tweak. Promoting to M1.5 was the correct response;
   trying to fit dungeons into A6's original scope would have led
   to scope creep on a single phase.
 ## Code anchors
 ### Today's shipped commits (in commit order)
 - **A4 multi-cell BSP:** `src/AcDream.Core/Physics/CellTransit.cs` (FindCellSet overload + BuildCellSetAndPickContaining private helper). `src/AcDream.Core/Physics/TransitionTypes.cs:1380-1486` (CheckOtherCells + ApplyOtherCellResult). `src/AcDream.Core/Physics/TransitionTypes.cs:1614-1631` (wire-up in FindEnvCollisions).
 - **#89 sphere-overlap CheckBuildingTransit:** `src/AcDream.Core/Physics/CellTransit.cs:179-218` (CheckBuildingTransit body) + `src/AcDream.Core/Physics/BSPQuery.cs:965-1003` (SphereIntersectsCellBsp).
 - **#90 WORKAROUND stickiness:** `src/AcDream.Core/Physics/PhysicsEngine.cs:285-300` (the comment block flagging the workaround) + `BSPQuery.SphereIntersectsCellBsp` (shared with #89).
 - **#91 indoor cell shadows:** `src/AcDream.Core/Physics/ShadowObjectRegistry.cs:251-269` (indoorCellIds branch in GetNearbyObjects) + `src/AcDream.Core/Physics/TransitionTypes.cs:1913-1935` (FindObjCollisions plumbs the candidate set).
 - **#92 server cell id:** `src/AcDream.App/Rendering/GameWindow.cs:10109-10135` (EnterPlayerModeNow uses spawn.Position.LandblockId).
 ### Tests added
 - `tests/AcDream.Core.Tests/Physics/CellTransitFindCellSetTests.cs` (3 tests).
 - `tests/AcDream.Core.Tests/Physics/TransitionCheckOtherCellsTests.cs` (6 tests).
 - `tests/AcDream.Core.Tests/Physics/FindEnvCollisionsMultiCellTests.cs` (1 integration test).
 - `tests/AcDream.Core.Tests/Physics/SphereIntersectsCellBspTests.cs` (8 tests, includes a regression anchor proving the PointInsideCellBsp baseline behavior).
 ### Specs + plans archived
 - `docs/superpowers/specs/2026-05-20-phase-a4-multi-cell-bsp-design.md` (spec)
 - `docs/superpowers/plans/2026-05-20-phase-a4-multi-cell-bsp.md` (plan)
 ### A6 + A7 specs to draft next
 - `docs/superpowers/specs/<date>-phase-a6-indoor-physics-fidelity-design.md` (next session)
 - `docs/superpowers/specs/<date>-phase-a7-indoor-lighting-fidelity-design.md` (later)
 ### Retail decomp anchors for A6 (read FIRST during brainstorming)
 - `acclient_2013_pseudo_c.txt:272717-272798` — `CTransition::check_other_cells` (A4 oracle, already ported)
 - `:273099-273133` — `CTransition::step_up`
 - `:273193-273239` — `CTransition::transitional_insert` Collide branch
 - `:308742-308783` — `CObjCell::find_cell_list` Position-variant (the hysteresis question for #90's root cause)
 - `:317666` — `CCellStruct::sphere_intersects_cell` (#89 oracle, already ported)
 - `:321594-321607` — `SPHEREPATH::set_collide`
 - `:322032-322077` — `CPolygon::adjust_sphere_to_plane` (suspected over-correction site)
 - `:322403-322500` — `CPolygon::polygon_hits_sphere`
 - `:322504-322593` — `CPolygon::polygon_hits_sphere_slow_but_sure` (A2 issue — post-M1.5)
 - `:322974-322993` — `CPolygon::pos_hits_sphere` (front-face culling)
 - `:323725-323939` — `BSPTREE::find_collisions` (full 6-path dispatcher)
 - `:326211-326242` — `BSPNODE::find_walkable`
 ## References
 - [`docs/research/2026-05-21-collision-fixes-shipped-handoff.md`](2026-05-21-collision-fixes-shipped-handoff.md) — yesterday's handoff (A1/A1.5/A1.6/A1.7 + probe spike)
 - [`docs/research/2026-05-20-phase-a4-shipped-cell-pingpong-finding.md`](2026-05-20-phase-a4-shipped-cell-pingpong-finding.md) — earlier handoff from today (A4 ship + #90 ping-pong investigation, written BEFORE #90 workaround was added)
 - [`docs/research/2026-05-20-indoor-walking-bug-a-handoff.md`](2026-05-20-indoor-walking-bug-a-handoff.md) — Bug A's tried-and-reverted story (the synthesis removal that A6.P4 will retry)
 - [`docs/research/2026-05-21-walk-miss-capture-findings.md`](2026-05-21-walk-miss-capture-findings.md) — the synthesis 99.87% MISS rate evidence
 - [`docs/plans/2026-05-12-milestones.md`](../plans/2026-05-12-milestones.md) — M1.5 block
 - [`docs/plans/2026-04-11-roadmap.md`](../plans/2026-04-11-roadmap.md) — A6 + A7 detailed phases
--- a/docs/research/2026-05-20-phase-a4-shipped-cell-pingpong-finding.md
+++ b/docs/research/2026-05-20-phase-a4-shipped-cell-pingpong-finding.md
@ -1,218 +0,0 @@
 # Phase A4 shipped + cell-tracking ping-pong finding — 2026-05-20
 **Status:** A4 (multi-cell BSP iteration) shipped in 3 commits + 1 revert + 1 reapply
 + 1 doc. Build green, 1139 + 8 baseline failures (same as pre-A4 baseline).
 A4 is **dormant in practice** because of a separate, pre-existing cell-tracking
 bug at the inn doorway that prevents the player from stably remaining in an
 indoor cell.
 ## TL;DR
 - A4 ports retail's `CTransition::check_other_cells` (`acclient_2013_pseudo_c.txt:272717-272798`).
  After the primary cell's BSP returns OK, every other cell the foot-sphere overlaps
  is queried via `BSPQuery.FindCollisions`. Halt on first
  Collided/Adjusted/Slid; Slid clears the contact-plane fields. Matches retail
  exactly.
 - 10 new unit tests pass; full test suite holds at the prior 8-failure baseline.
  Three commits land the slices (FindCellSet overload → CheckOtherCells helper →
  FindEnvCollisions wire-up).
 - **Visual verification surfaced a different bug**: walking into the Holtburg
  inn ping-pongs the player's CellId between indoor `0xA9B40164` and outdoor
  `0xA9B40022` rapidly. Indoor BSP DOES detect walls (Collided / Adjusted /
  Slid all fire on push-back), but the push-back moves the sphere outside the
  indoor CellBSP's volume → `ResolveCellId` reclassifies the player as outdoor
  → next tick bypasses indoor BSP entirely → player advances freely → re-enters
  → repeats.
 - Because the player never STAYS in an indoor cell, A4's multi-cell pass is
  rarely (if ever) actually exercised in production. The user's reported
  "walls walk through everywhere in the inn" reproduces fully with A4 wire-up
  reverted, confirming A4 is not the cause.
 ## What shipped
 | SHA | Phase | Description |
 |---|---|---|
 | `b100d54` | A4 spec | docs/superpowers/specs/2026-05-20-phase-a4-multi-cell-bsp-design.md |
 | `a8a0366` | A4 plan | docs/superpowers/plans/2026-05-20-phase-a4-multi-cell-bsp.md |
 | `e6369e2` | A4 slice 1 | `CellTransit.FindCellSet` overload + 3 unit tests |
 | `493c5e5` | A4 slice 2 | `Transition.CheckOtherCells` + `ApplyOtherCellResult` + 6 unit tests |
 | `967d065` | A4 slice 3 | Wire `CheckOtherCells` into `FindEnvCollisions` + 1 integration test |
 | `3add110` | A4 revert | Temporary revert of slice 3 to confirm A4 wasn't the cause |
 | `691493e` | A4 reapply | Restored slice 3 after revert test proved A4 not the cause |
 Total: ~380 LOC added (3 new test files + helper methods); 1139 + 8 baseline
 maintained throughout.
 ## Visual verification — what we tested
 Launched twice with the light-probe set (`ACDREAM_PROBE_INDOOR_BSP`,
 `ACDREAM_PROBE_CELL`, `ACDREAM_PROBE_CELL_CACHE`).
 ### Launch 1 — A4 wire-up active (`launch-a4.log`, 782 lines)
 User walked from spawn toward the Holtburg inn. Log captured:
 - Player CellId stayed at outdoor `0xA9B4002A` the entire session.
 - 0 indoor-bsp probes fired.
 - 0 other-cells probes fired (A4 wire-up only runs for indoor cells).
 - User reported "all interior walls in the inn can be walked through; going
  from indoor to outdoor broken."
 But — A4 wire-up only fires when `cellLow >= 0x0100`. The player never reached
 that state. So A4 couldn't possibly be the cause of the reported behavior.
 ### Launch 2 — A4 wire-up reverted (`launch-revert2.log`, 18490 lines)
 User walked into and out of the inn multiple times. Log captured:
 - 18 cell-transit events: outdoor cells `0xA9B40021` / `0xA9B40022` /
  `0xA9B4002A` ping-ponging with indoor cell `0xA9B40164` (vestibule).
 - 11 `[check-bldg] inside=True` events — player crossed the building threshold.
 - 61 indoor-bsp queries against `0xA9B40164` (58) and `0xA9B40162` (3).
 - Indoor BSP results: 40 OK + 7 Adjusted + 7 Collided + 7 Slid.
 - User confirmed: "walls still walked through (same bug)" with A4 reverted.
 **The bug reproduces with A4 reverted, proving A4 is not responsible.**
 ## The actual bug — cell-tracking ping-pong at doorway threshold
 The repeating cycle observed in the revert log:
 1. Player at outdoor cell `0xA9B40022`, walking toward inn door.
 2. `CheckBuildingTransit` returns `inside=True` for portal to `0xA9B40164`.
 3. ResolveCellId promotes CellId to `0xA9B40164`.
 4. Next tick: indoor branch of FindEnvCollisions fires. BSP query against
   `0xA9B40164`'s walls returns Adjusted/Collided/Slid. The sphere is pushed
   back (Adjusted/Slid) or halted (Collided).
 5. The push-back moves the sphere's world position BACK toward the outdoor
   side, beyond the indoor CellBSP's volume.
 6. ResolveCellId re-evaluates: indoor CellBSP no longer contains the sphere
   center → falls through to outdoor resolution → returns `0xA9B40022`.
 7. CellId flips back to outdoor. Next tick: indoor BSP not queried, player
   keeps advancing.
 8. Player re-crosses the building threshold → goto 2.
 Net effect: the player visually moves through the doorway zone, walls
 intermittently push them back, but most ticks classify them as OUTDOOR and
 those ticks bypass wall collision entirely. The aggregate behavior LOOKS LIKE
 "walls walk through" even though wall hits are firing.
 ### Why A4 doesn't help here
 A4 multi-cell iteration only runs when the primary cell BSP returns OK. In the
 ping-pong cycle, the primary cell BSP returns NON-OK (Collided/Adjusted/Slid)
 on most indoor frames — so A4 short-circuits early at the existing `if (cellState
 != TransitionState.OK) return cellState;` path. A4 would help if the player
 were STABLY indoor (cellLow >= 0x100) AND the primary cell's BSP had sparse
 geometry that missed walls in adjacent cells. The ping-pong prevents both
 conditions.
 ### Why this is a Bug A cousin
 The 2026-05-20 Bug A investigation
 ([docs/research/2026-05-20-indoor-walking-bug-a-handoff.md](2026-05-20-indoor-walking-bug-a-handoff.md))
 documented a similar doorway-edge problem: indoor cell floor polys don't
 extend past the doorway threshold, causing free-fall when stepping out.
 The current ping-pong is the same family of bug, different symptom: the
 indoor CellBSP volume doesn't extend past the doorway threshold either, so
 the push-back from a wall collision exits the cell's containment volume,
 and the cell-id resolver bounces the player back to outdoor.
 Hypothesis: the inn's vestibule cell `0xA9B40164` has a CellBSP that's tightly
 bounded to the room's interior volume. The doorway threshold is right at the
 boundary. Walking against an interior wall pushes the foot-sphere back toward
 the boundary → exits CellBSP → outdoor classification.
 ## Next steps (not blocking A4 ship)
 Two paths to investigate the ping-pong, both out of A4's scope:
 1. **CellBSP-volume retention.** Match retail's behaviour: once a player enters
   an indoor cell, don't flip back to outdoor until they cross the EXIT portal
   plane, not just because they exited the CellBSP volume on a push-back.
   Likely a `ResolveCellId` modification that prefers the previous indoor
   classification when sphere is "close enough" to the indoor CellBSP volume.
 2. **CellBSP-volume expansion.** Pad the indoor cell's CellBSP volume by the
   sphere radius (~0.48m) on all sides. The push-back stays within the
   padded volume. Risk: may incorrectly classify nearby outdoor positions as
   indoor.
 The retail oracle for cell-id stickiness is at
 `acclient_2013_pseudo_c.txt:308742-308783` (`CObjCell::find_cell_list` Position-
 variant) and the cell-array hysteresis logic around it. Not yet ported in
 detail.
 ## Why ship A4 anyway
 - **Correctness.** A4 matches retail's `check_other_cells` exactly. 10 unit
  tests pin the halt semantics + integration test verifies the wire-up. Pure
  port, no design improvisation.
 - **No regressions.** 1139-passing + 8-pre-existing-failing baseline holds.
  All A1 / A1.5 / A1.6 / A1.7 / Bug B fixes remain green.
 - **Foundation for A3.** A3 (synthesis removal) is unblocked by A4 being in
  place — it can rely on multi-cell BSP coverage for floor synthesis once the
  ping-pong is fixed and players stay indoor long enough.
 - **Reverting it would lose work.** A4 is correct and tested. The dormant
  state is caused by an unrelated bug. Reverting would just make the
  unrelated bug harder to investigate (no multi-cell foundation to build on).
 ## What this is NOT
 This is **NOT** a fix for the user's "walls walk through" report. That bug is
 pre-existing, caused by cell-tracking instability at doorway thresholds.
 This is **NOT** a regression introduced by A4. The bug reproduces fully with
 A4's wire-up reverted (verified by `launch-revert2.log`).
 This is **NOT** the same as Bug A (synthesis removal). Bug A's symptom was
 free-fall on doorway exit; this is wall walk-through due to CellId classification
 flipping back to outdoor on each push-back.
 ## Code anchors
 - Phase A4 wire-up: [src/AcDream.Core/Physics/TransitionTypes.cs:1614-1631](../../src/AcDream.Core/Physics/TransitionTypes.cs#L1614).
 - `CheckOtherCells` + `ApplyOtherCellResult`: TransitionTypes.cs (search `CheckOtherCells`).
 - `FindCellSet` overload: [src/AcDream.Core/Physics/CellTransit.cs](../../src/AcDream.Core/Physics/CellTransit.cs) (search `FindCellSet`).
 - ResolveCellId outdoor branch (where the ping-pong happens): [src/AcDream.Core/Physics/PhysicsEngine.cs:259-329](../../src/AcDream.Core/Physics/PhysicsEngine.cs#L259).
 ## Probe captures
 - `launch-a4.log` (782 lines) — A4 active, player stayed outdoor (didn't reach
  inn). Confirms A4's indoor branch never fired in that session.
 - `launch-revert.log` (1.2M lines) — A4 reverted, player parked at outdoor cell
  with 400K+ `[check-bldg]` probes all returning `inside=False`. Player never
  moved.
 - `launch-revert2.log` (18490 lines) — A4 reverted, player walked into inn
  multiple times. Captured the ping-pong cycle. Indoor BSP results breakdown:
  40 OK + 7 Adjusted + 7 Collided + 7 Slid. 11 `inside=True` building-transit
  events.
 ## How to start a fresh session
 Open a new Claude Code session, then:
 ```
 Pick up the cell-tracking ping-pong investigation that blocked Phase A4
 from being exercised in practice.
 1. Read docs/research/2026-05-20-phase-a4-shipped-cell-pingpong-finding.md
   FIRST. It documents A4 ship (correct, dormant) + the ping-pong bug it
   surfaced.
 2. A4 is shipped (3 commits at e6369e2, 493c5e5, 691493e). Don't touch it.
   1139 + 8 baseline holds.
 3. The real M2 blocker: at the Holtburg inn doorway, CellId ping-pongs
   between 0xA9B40022 (outdoor) and 0xA9B40164 (vestibule) every few ticks
   because indoor BSP push-back exits the indoor CellBSP volume → outdoor
   reclassification → walls bypassed on outdoor ticks.
 4. Investigate cell-id hysteresis. Retail oracle:
   acclient_2013_pseudo_c.txt:308742-308783 (CObjCell::find_cell_list
   Position-variant). Look for the cell-array stickiness logic that retail
   uses to prevent ping-pong.
 5. CLAUDE.md rules: no workarounds, retail-faithful, probe-first.
 State M2 as the milestone, "cell-tracking ping-pong fix" as the phase.
 ```
--- a/docs/research/2026-05-21-a6-captures/pdb-match-verification.txt
+++ b/docs/research/2026-05-21-a6-captures/pdb-match-verification.txt
--- a/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/.gitkeep
+++ b/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/.gitkeep
--- a/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail-v1-broken-offsets.log
+++ b/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail-v1-broken-offsets.log
--- a/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail-v2-zero-floats.log
+++ b/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail-v2-zero-floats.log
--- a/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail-v3-cpp-zero-floats.log
+++ b/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail-v3-cpp-zero-floats.log
--- a/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail.decoded.log
+++ b/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail.decoded.log
--- a/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail.log
+++ b/docs/research/2026-05-21-a6-captures/scen1_inn_doorway/retail.log
--- a/docs/research/2026-05-21-a6-captures/scen2_inn_stairs/.gitkeep
+++ b/docs/research/2026-05-21-a6-captures/scen2_inn_stairs/.gitkeep
--- a/docs/research/2026-05-21-a6-captures/scen2_inn_stairs/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen2_inn_stairs/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen2_inn_stairs/retail.decoded.log
+++ b/docs/research/2026-05-21-a6-captures/scen2_inn_stairs/retail.decoded.log
--- a/docs/research/2026-05-21-a6-captures/scen2_inn_stairs/retail.log
+++ b/docs/research/2026-05-21-a6-captures/scen2_inn_stairs/retail.log
--- a/docs/research/2026-05-21-a6-captures/scen2_inn_stairs_postfix/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen2_inn_stairs_postfix/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor/.gitkeep
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor/.gitkeep
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor/retail.decoded.log
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor/retail.decoded.log
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor/retail.log
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor/retail.log
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_postfix/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_postfix/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_postfix/retail.decoded.log
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_postfix/retail.decoded.log
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_postfix/retail.log
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_postfix/retail.log
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_slice2/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_slice2/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_slice2v2/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen3_inn_2nd_floor_slice2v2/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar/.gitkeep
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar/.gitkeep
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar/retail.decoded.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar/retail.decoded.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar/retail.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar/retail.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_place_fail/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_place_fail/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_place_fail/acdream_v2_with_obj_probe.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_place_fail/acdream_v2_with_obj_probe.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_retail_for_issue98/retail.decoded.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_retail_for_issue98/retail.decoded.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_retail_for_issue98/retail.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_retail_for_issue98/retail.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_slice3/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_slice3/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_slice3v2/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen4_cottage_cellar_slice3v2/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen5_sewer_entry/.gitkeep
+++ b/docs/research/2026-05-21-a6-captures/scen5_sewer_entry/.gitkeep
--- a/docs/research/2026-05-21-a6-captures/scen5_sewer_entry/acdream.log
+++ b/docs/research/2026-05-21-a6-captures/scen5_sewer_entry/acdream.log
--- a/docs/research/2026-05-21-a6-captures/scen5_sewer_entry/retail.decoded.log
+++ b/docs/research/2026-05-21-a6-captures/scen5_sewer_entry/retail.decoded.log
--- a/docs/research/2026-05-21-a6-captures/scen5_sewer_entry/retail.log
+++ b/docs/research/2026-05-21-a6-captures/scen5_sewer_entry/retail.log
--- a/docs/research/2026-05-21-a6-captures/scen6_sewer_first_stair/.gitkeep
+++ b/docs/research/2026-05-21-a6-captures/scen6_sewer_first_stair/.gitkeep
--- a/docs/research/2026-05-21-a6-captures/scen7_sewer_inter_room/.gitkeep
+++ b/docs/research/2026-05-21-a6-captures/scen7_sewer_inter_room/.gitkeep
--- a/Show more
+++ b/Show more
		`@ -1 +0,0 @@`
			`.github/workflows/*.lock.yml linguist-generated=true merge=ours`