docs: reconcile project status and navigation

Add a canonical documentation map, modernize the public README, and align milestone, roadmap, architecture, issue, divergence, and session guidance with the July 20 baseline. Correct the far-teleport residual to issue #153, close visually accepted indicator and terrain-tiling work, record the remaining detail-overlay and build-warning debt, and deprecate the duplicate legacy bug ledger.

Co-authored-by: OpenAI Codex <codex@openai.com>

docs/README.md

@@ -0,0 +1,98 @@
+# acdream documentation map
+
+This page is the entry point for project documentation. It distinguishes
+current sources of truth from implementation history so an old plan or issue
+banner cannot silently override the current program state.
+
+## Current snapshot — 2026-07-20
+
+- **Active milestone:** M3, “Cast a spell.” The automated implementation and
+  connected single-client magic/portal presentation gates are complete.
+- **Next visual gates:** the R6 locomotion/collision/projectile/teleport retail
+  comparison, then the final two-client portal-out/materialization observer
+  comparison (`#218`).
+- **Separate visual verification:** the shared-alpha lifestone/particle result
+  in `#225`; its connected resource-lifetime and performance routes pass.
+- **Carried behavior debt:** `#153` (far teleport onto an unstreamed edge),
+  `#116` (two narrowed slide-response cases), and divergence rows TS-50/TS-51.
+- **Deferred engineering tracks:** Modern Pipeline MP1b+ and Linux/headless
+  automation (Track LH). Neither is part of the active M3 gate.
+- **Divergence audit:** 178 active rows — IA 17, AD 37, AP 85, TS 34,
+  and UN 5 — plus the retained retired TS-37 history note.
+- **Latest automated baseline:** Release build succeeds with 17 known
+  test-project warnings (`#228`); 6,452 tests passed and 5 intentionally
+  skipped. The unattended connected R6 route
+  completed seven portal materializations, production input exercises, and a
+  graceful close. See
+  [`research/2026-07-20-connected-r6-soak.md`](research/2026-07-20-connected-r6-soak.md).
+
+## Sources of truth
+
+Read these in this order when deciding what to do next:
+
+1. [`plans/2026-05-12-milestones.md`](plans/2026-05-12-milestones.md) — the
+   active playable outcome, freeze boundaries, and visual gates.
+2. [`plans/2026-04-11-roadmap.md`](plans/2026-04-11-roadmap.md) — strategic
+   phase ledger: shipped, active, deferred, and future work.
+3. [`ISSUES.md`](ISSUES.md) — tactical defects and small follow-ups. The status
+   inside an issue is authoritative; physical order is not.
+4. [`architecture/retail-divergence-register.md`](architecture/retail-divergence-register.md)
+   — every known place runtime behavior can differ from retail.
+5. [`architecture/acdream-architecture.md`](architecture/acdream-architecture.md)
+   and [`architecture/code-structure.md`](architecture/code-structure.md) —
+   ownership, dependency, update-thread, and extraction rules.
+6. [`architecture/worldbuilder-inventory.md`](architecture/worldbuilder-inventory.md)
+   — rendering/DAT code already owned in-tree versus mechanisms still ours to
+   port.
+
+If these disagree, milestones control the current outcome, the roadmap controls
+work ordering, the issue status controls the individual defect, and the
+architecture documents control implementation shape. Reconcile the stale
+document in the same change; do not leave both claims standing.
+
+## Research and implementation records
+
+- [`research/named-retail/`](research/named-retail/) is the primary retail
+  oracle: named pseudo-C, headers, symbols, and types from the Sept 2013 build.
+- [`research/decompiled/`](research/decompiled/) is the older Ghidra fallback.
+- [`research/`](research/) contains focused pseudocode, traces, fixtures, and
+  gate reports. A dated research note records evidence; it does not become a
+  new roadmap.
+- [`superpowers/specs/`](superpowers/specs/) and
+  [`superpowers/plans/`](superpowers/plans/) are per-slice design and execution
+  records. Completed plans remain historical.
+- [`audit/`](audit/) contains completion and conformance audits.
+
+## Durable memory
+
+- [`../claude-memory/MEMORY.md`](../claude-memory/MEMORY.md) indexes the live
+  subsystem memories and the render/physics digests. Read a domain digest
+  before changing that subsystem, especially its DO-NOT-RETRY table.
+- [`../memory/`](../memory/) contains stable engineering references such as the
+  modern rendering pipeline, two-tier streaming, and toolchain notes.
+
+Memory accelerates recall; it does not outrank the canonical documents above.
+When current truth changes, update the relevant canonical document and distill
+only the durable lesson into memory.
+
+## Historical and deprecated documents
+
+- [`bugs.md`](bugs.md) is the April 2026 bug snapshot. It is preserved for
+  archaeology and is not an active ledger.
+- Dated plans and specs describe the decision at that time. Their completion
+  wording is historical unless the current milestone/roadmap explicitly links
+  the item as active.
+- Old `R1→R8` architecture sequencing is superseded. Current execution comes
+  from the milestones and strategic roadmap.
+
+## Documentation maintenance rules
+
+- Update milestone, roadmap, issue, divergence, architecture, and memory claims
+  in the same commit when a shipped change affects them.
+- Keep one issue ID per defect. Narrow an issue in place; do not reuse another
+  issue's number as a shorthand.
+- Mark automated, connected, and visual gates separately. An automated pass is
+  not a visual acceptance, and an RDP throughput sample is not a local-display
+  visual comparison.
+- Preserve research history, but remove stale “current/next” claims from living
+  documents once the state advances.