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.

2 files changed, 44 insertions, 13 deletions

diff --git a/docs/09-reference/glossary-and-faq.md b/docs/09-reference/glossary-and-faq.md
index 255d1a6..2ec4faa 100644
--- a/docs/09-reference/glossary-and-faq.md
+++ b/docs/09-reference/glossary-and-faq.md
@@ -5,11 +5,15 @@
 | Term | Meaning |
 |---|---|
 | **AMAPlib** | NVIDIA's shared "address mapping" library: swizzling, bank/channel mapping, aperture rules. Studied for page-table and memory-layout semantics. |
+| **Async copy engine (COPY14)** | A copy-engine instance found in the host oracle's engine list but missing from the emulated list — engine descriptor `0x793ceb0e`, instance 14, client type `0x38`, class pair `0xc9b5`. Its absence is the current CUDA context-creation blocker. |
 | **BAR0 / BAR1 / BAR3** | PCI BAR windows of the GPU: register interface (16 MB), VRAM aperture (256 MB), instance/PRAMIN window. |
 | **CE** | Copy Engine: DMA engine; also used for UVM's internal work. |
+| **Class list (classDB)** | The set of RM classes reported as supported (`GPU_GET_CLASSLIST`); engine queries are filtered against it, so the class list, engine list and caps controls must agree. |
 | **CUDASW** | The family of NVIDIA user-space software that sits between applications and the driver: `libcuda`, `libcudart`, JIT compiler, fatbinary loader, and friends. |
 | **Doorbell** | A register/memory location a driver writes to signal "new work is available" for a channel or queue. |
 | **Engine type** | Numeric identifier for an execution engine (`GR = 0x1`, `COPY0 = 0x9`, ...). |
+| **Engine record / engine list** | The per-engine descriptors (kind, instance, class, client type) the driver walks after `GPU_GET_ENGINES`/`GET_ENGINES_V2`; each record must be self-consistent or the driver rewrites the following allocation. |
+| **File virtual address (`libcuda+0x...`)** | An address relative to the start of a shared object file (e.g. a `libcuda` offset), as distinct from a runtime mapping or a Ghidra program address; public docs cite these. |
 | **FWSEC** | Firmware security processor stage of the GSP boot sequence. |
 | **GNND / GB10** | NVIDIA "Grace-Blackwell" systems-on-chip used in DGX Spark and Surface-class laptops; explicit portability targets. |
 | **GPFIFO** | GPU FIFO: a ring of entries, each pointing to a push buffer for a channel. |
@@ -18,12 +22,15 @@
 | **GSP-RM** | The Resource Manager running on the GSP ("self-hosted RM"). |
 | **GMMU** | GPU Memory Management Unit: page tables, TLB, fault handling. |
 | **HAL** | Hardware Abstraction Layer: per-generation functions that program registers and formats. |
+| **Host oracle / A-B harness** | The same query or deterministic workload run against a bare-metal (host) driver and inside the guest, then diffed — our reference for what the guest should have seen. |
 | **mdev** | Mediated device: the kernel mechanism that turns a physical device into virtual instances (VFIO). |
 | **MSGQ** | The GSP message queue transport: shared-memory element rings with a page table, plus doorbells. |
 | **PBDMA** | Push-buffer DMA engine in the host scheduler that fetches and executes push buffers. |
 | **PDB** | Page Directory Base: root of a GPU page table. |
 | **PDE / PTE** | Page-directory entry / page-table entry. |
 | **Push buffer** | A stream of method calls (engine commands) submitted via a GPFIFO. |
+| **QMD** | Queue Meta Data: the per-launch descriptor a GR channel reads to execute a kernel grid. |
+| **Reply fidelity** | How completely an emulated reply matches what real hardware returns, as a ladder: status-only → coherent zeroed params → coherent values for consumed fields → exact values. |
 | **RMCore** | The RM's object system: classes, handles, parents, methods. |
 | **RM / RM API** | NVIDIA's Resource Manager and the API used to allocate objects and issue controls. |
 | **resserv / resource server** | The RM component that owns allocation authority, privileges and lifetimes. |
@@ -57,10 +64,14 @@ GPU and Open-IOV is an independent module. Building NVIDIA's OpenRM modules from
 source is only needed for the native-vGPU-management workflows.
 
 **Why is `nvidia-smi` working but CUDA not?**
-Because CUDA requires *execution*: kernels must run on real hardware. The
-current state runs the entire initialization path (including UVM's start-up)
-but stops short of executing engine work. See the known-knowns document for
-the exact status and plan.
+CUDA startup reaches `cuInit` / `cuDeviceGet`, but context creation is blocked:
+the emulated engine list lacks the async copy engine (`COPY14`), so
+`cuCtxCreate` returns `rc=999` (`CUDA_ERROR_UNKNOWN`) and memory allocation
+never runs. (The earlier `libcuda` segfault on this path was fixed by echoing
+the request params back in the alloc reply.) Once context creation is green,
+CUDA still needs *execution*: kernels must run on real hardware. See the
+known-knowns document for the exact status and plan; start at
+[`../../userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md).
 
 **How is this legal / license-clean?**
 Open-IOV is BSD-3-Clause (GPL-2.0 for kernel modules that link GPL-only kernel
@@ -85,9 +96,11 @@ MIG is a hardware partitioning mechanism; Open-IOV's scheduling policy can use
 it where available. It is part of the multi-tenancy work.
 
 **How fast is it?**
-Initialization currently completes in the same order of magnitude as native;
-execution forwarding is not implemented yet. Performance claims follow the
-published methodology in the operations docs.
+No published numbers yet: execution forwarding is not implemented, and even
+the initialization path has not been measured under the project's methodology.
+Any performance claim will come with the methodology and the measurements
+together (see
+[`../05-operations/01-performance-correctness-security.md`](../05-operations/01-performance-correctness-security.md)).
 
 **Where do I report bugs or ask for help?**
 Open an issue with the standard captures listed in the debugging document. A
diff --git a/docs/09-reference/legal-and-licensing.md b/docs/09-reference/legal-and-licensing.md
index 74f1363..57aad43 100644
--- a/docs/09-reference/legal-and-licensing.md
+++ b/docs/09-reference/legal-and-licensing.md
@@ -30,9 +30,12 @@ In this repository you will find:
 
 * **GSP firmware images** (`firmware/**/*.fwimage.bin`) — fetched from public
   distribution channels (e.g. `linux-firmware`); used to understand and
-  emulate the firmware interface.
-* **Decompiled firmware artifacts** (`firmware/**/decompiled/`) — our own
-  analysis output; kept for study and cited in the wiki.
+  emulate the firmware interface. They are **not distributed in this
+  repository**: like all firmware blobs they are gitignored and kept only as
+  local study material.
+* **Decompiled/disassembled artifacts** (`firmware/**/decompiled/`) — our own
+  analysis output, kept locally for study and cited in the wiki. They are
+  gitignored and never committed.
 * **Reformatted interface tables** — IDs, structures and message layouts that
   we derived, published in `wiki/` and in this documentation tree.
 
@@ -42,13 +45,28 @@ do not point readers at material we cannot redistribute, and do not
 redistribute third-party binaries as project content beyond what their terms
 allow.
 
+**CUDA-userspace (`libcuda`) analysis rules:**
+
+* Decompiled or disassembled output is never committed; it is gitignored study
+  material.
+* Cite userspace locations as `libcuda+0x...` *file virtual addresses*. Note
+  the Ghidra image-base caveat: that library is loaded at **`0x100000`**, so a
+  decompilation produced without translating the offset refers to the wrong
+  function.
+* Tracked docs state facts and evidence; conclusions cite numeric IDs, code
+  offsets and recorded observations, never source locations.
+* Name maps and indexes (`userspace/cuda/*/annotations/`) are our own work
+  product and may be tracked.
+
 ## 3. Adversarial interoperability and the law
 
 We implement the *interface contract* so that unmodified NVIDIA software can
 talk to our device. We do not:
 
 * copy NVIDIA driver code into our kernel module,
-* patch NVIDIA drivers or firmware,
+* patch the guest, runtime or host driver at run time. The only patch series
+  we carry is build glue for the optional OpenRM submodule (`install.sh`); the
+  deployment path uses the distribution's NVIDIA driver as shipped,
 * defeat licensing for NVIDIA's own products (our device is our device; no
   impersonation of a licensed product identity).
 
@@ -68,8 +86,8 @@ open an issue: we would rather over-comply than argue.
   contribution does not contain third-party material under incompatible terms.
 * Write original code. Describe behaviour, cite the evidence, and reimplement
   interfaces from observation rather than copying anyone's source.
-* Do not commit firmware or ISO images unless they are explicitly permitted and
-  listed in `.gitattributes`/LFS policy.
+* Do not commit firmware or ISO images: they are local study/deployment
+  material and are gitignored (see §2).
 
 ## 5. Export, safety and platform notes