docs: refresh status, supersede stale material, link the CUDA analysis

* Status now matches the live state: guest driver probe and nvidia-smi work;
  cuInit/device queries work; cuCtxCreate returns 999 because the emulated
  engine list is missing the async copy engine (COPY14). The userspace
  libcuda segfault is recorded as solved, with its mechanism (an RM
  allocation reply must echo request parameters; zeroing them corrupted the
  caller's saved frame pointer).
* Correct the emulation claims: only a subset of RM controls are
  special-cased; the rest return a success reply with zeroed parameters whose
  consumed fields are still being corrected; allocation replies are coherent
  but no server-side object model exists.
* Add the eight-point emulation checklist and reply-fidelity ladder as
  explicit gates, documented in userspace/cuda and linked from the
  architecture, implementation and operations docs.
* Fix operational errors: build/test commands, module load order, mdev type
  names, LFS references, debugfs claims, in-repo firmware claims, CI claims,
  portability matrix (guest status, config layout, userspace driver facts).
* Mark historical material: one superseded banner per legacy document with a
  pointer to its replacement; STATE.md marked as a 2026-09-21 snapshot.
* Wiki: fix the index, add status banners and in-place factual corrections
  (msgq transport vs legacy mailbox, BAR definitions, error statuses,
  migration, glossary), and note the archived 2023 imports.

1 files changed, 35 insertions, 13 deletions

diff --git a/docs/README.md b/docs/README.md
index fff4f82..cee435e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -97,24 +97,36 @@ and [`01-orientation/02-the-ai-edge-and-ecosystem.md`](01-orientation/02-the-ai-
 | Emulated vGPU device (PCI, BARs, MSI-X, VFIO mdev) | ✅ Working |
 | GSP boot emulation (FWSEC/booter/RISCV handshake) | ✅ Working |
 | GSP-RM message queue + RPC transport | ✅ Working |
-| GSP-RM controls: device/fb/bus tables, CE caps, vaspace, GMMU static info | ✅ Working |
+| GSP-RM controls: device/fb/bus tables, CE caps, vaspace, GMMU static info | 🟡 Mostly — values are coherent for the special-cased controls; engine inventory/class-list consistency is the current CUDA blocker (COPY14) |
 | Guest `nvidia.ko` probe, `nvidia-smi` | ✅ Working (TU104) |
-| Guest CUDA driver (`libcuda`) startup | 🟡 Partially — UVM advances through channel creation and page-tree init; see [`04-implementation/01-known-knowns-and-unknowns.md`](04-implementation/01-known-knowns-and-unknowns.md) |
-| CUDA kernel execution | 🔴 Not yet — requires GPU work forwarding |
+| Guest CUDA driver (`libcuda`) startup | 🟡 Partially — `cuInit`/device enumeration work; `cuCtxCreate` returns `999` (`CUDA_ERROR_UNKNOWN`) because the emulated engine list is missing the async copy engine (COPY14). See [`04-implementation/01-known-knowns-and-unknowns.md`](04-implementation/01-known-knowns-and-unknowns.md) and [`../userspace/cuda/READ-ME-FIRST.md`](../userspace/cuda/READ-ME-FIRST.md) |
+| CUDA kernel execution | 🔴 Not yet — context creation must succeed first; then GPU work forwarding (today only decoded memsets/copies/semaphore releases execute, in the host) |
 | OpenGL / Vulkan | 🔴 Not yet |
 | Windows guest | 🔴 Not yet |
 | Multi-tenant isolation (VFs, mdev-per-VM) | 🟡 Designed, partially implemented |
 
-We also know exactly *why* CUDA kernels do not run yet, and what the path is:
-see the known-knowns/known-unknowns document. The short version: the emulation
-is now faithful enough that the guest stack reaches UVM initialization; the
-missing piece is forwarding the guest's *work* (push buffers, page trees,
-execution) to the physical GPU under our control.
+We also know exactly where the CUDA bring-up stands and what the next step is:
+the userspace `libcuda` segfault was fixed (an RM allocation reply now echoes
+the request parameters instead of returning zeros), and the remaining blocker
+is data: the engine list the emulation reports must include the async copy
+engine and stay consistent with the class list, because `libcuda` filters
+engines against it. The full mechanism, with offsets and the decompiled call
+path, is in [`../userspace/cuda/docs/05-570.144-decompilation.md`](../userspace/cuda/docs/05-570.144-decompilation.md).
+Beyond that, the missing piece for kernel execution is forwarding the guest's
+*work* (push buffers, page trees, execution) to the physical GPU under our
+control; see [`04-implementation/02-practical-challenges-and-adversarial-interop.md`](04-implementation/02-practical-challenges-and-adversarial-interop.md).
 
 ## 4. How to read these docs (progressive disclosure)
 
 Read in order if you are new. Jump directly if you know what you need.
 
+> **Debugging the CUDA bring-up?** Start with
+> [`../userspace/cuda/READ-ME-FIRST.md`](../userspace/cuda/READ-ME-FIRST.md) —
+> a five-minute guide to the userspace driver analysis, the corrected crash
+> path, the current engine-topology blocker, and the lookup recipes for
+> `libcuda+0x...` offsets. It links back into this tree for the interface and
+> emulation contract.
+
 | # | Document | Audience | Time |
 |---|----------|----------|------|
 | 1 | [Purpose and scope](01-orientation/01-purpose-and-scope.md) | everyone | 10 min |
@@ -136,11 +148,21 @@ Read in order if you are new. Jump directly if you know what you need.
 | 17 | [HAAEEP and collaboration](08-ecosystem/haaeep-and-collaboration.md) | stakeholders, partners | 20 min |
 | 18 | [Glossary and FAQ](09-reference/glossary-and-faq.md) | everyone | reference |
 
-Existing deep-dive material (kept, still valid, being folded into this tree):
-the `wiki/` directory (firmware analysis, address reference, wire protocol,
-RPC message format) and the `docs/` reference documents
-(`GSP_EMULATION_ARCHITECTURE.md`, `DEBUGGING.md`, `PERFORMANCE.md`,
-`BUILD_NVIDIA_OPENRM.md`, `VERSION_UPGRADE.md`).
+Deep-dive material lives in [`../wiki/`](../wiki/README.md) (firmware
+decompilation record, address reference, historical protocol notes). Wiki
+pages that predate the current implementation carry a status banner naming
+the canonical document in this tree; use the banner, not the old body.
+
+Historical material is kept but must not be read as current state. The
+following carry a **superseded** banner and point at their replacements:
+`refactored-architecture.md`, `refactored-implementation-to-do.md`,
+`PORTABLE_ARCHITECTURE.md`, `GSP_EMULATION_ARCHITECTURE.md`, `ONBOARDING.md`,
+`DEVELOPMENT_WORKFLOW.md`, `PERFORMANCE.md`, `DEBUGGING.md` (sections 3–4
+remain useful case studies), `VERSION_UPGRADE.md`, `BUILD_NVIDIA_OPENRM.md`
+(historical build notes; its load order is corrected in place), and
+[`../STATE.md`](../STATE.md) (2026-09-21 snapshot). The current versions of
+those topics are `03-architecture/01`/`06`, `04-implementation/01`/`02`,
+`05-operations/01`/`02`, `06-portability`, and `07-developers`.
 
 ## 5. What makes Open-IOV different?