2 files changed, 56 insertions, 18 deletions
diff --git a/docs/05-operations/01-performance-correctness-security.md b/docs/05-operations/01-performance-correctness-security.md
index 2f10b35..1391426 100644
--- a/docs/05-operations/01-performance-correctness-security.md
+++ b/docs/05-operations/01-performance-correctness-security.md
@@ -17,26 +17,32 @@ Rung 4  SUSTAINED         workloads run for hours; faults/errors recoverable
 Rung 5  MULTI-TENANT      N VMs, isolation + fairness + no cross-talk
 ```
 
-**Current rung (2026-10-02):** Rungs 1–2 are green: the stock driver probes,
-`nvidia-smi` enumerates, and the full CUDA driver-API smoke passes
-(`ALL OK` 64/64, copies matched) — `cuInit`, device queries, context creation,
-allocation, copies, free and destroy complete, and the copies are verified
-byte-for-byte. **Rung 3 is partial:** CE-class copies execute on the physical
-copy engine (default off) with engine-authored releases and a fault relay; for
-GR kernel execution a forwarded guest launch now reaches the front-end but the
-inline launch-descriptor install has not been observed (no grid dispatched;
-context validity at dispatch is ruled out —
-[`../04-implementation/03-execution-frontier.md`](../04-implementation/03-execution-frontier.md)).
-Before Rung 3
-is claimed, the
-**reply-fidelity gate** applies: a control whose reply fields the driver
-consumes is not implemented until the reply is coherent (status-only →
-coherent zeroed params → coherent values for consumed fields → exact values) —
-see
-[`../../userspace/cuda/docs/04-virtualization-and-emulation.md` §6](../../userspace/cuda/docs/04-virtualization-and-emulation.md).
-New to CUDA analysis here: start at
+**Current rung (2026-10-30):** Rungs 1–3 are green for the verified CUDA
+clients: the stock driver probes, `nvidia-smi` enumerates, the full CUDA
+driver-API smoke passes (`ALL OK` 64/64), and guest kernels **execute on the
+physical engine** — vector-add, matrix-multiply and transformer clients verify
+on fresh boots with engine-authored completions relayed to the guest. What
+remains before Rung 3 is claimed outright: the staged-transfer class (some
+large multi-chunk clients still mis-verify; failure modes proven) and the
+every-boot acceptance campaign — plus the **reply-fidelity gate** below. Rung 4
+(sustained) has partial evidence (a 100-launch loop, long soak pending); rung 5
+(multi-tenant) is partial: two mediated devices and two guests coexist, and
+per-guest execution isolation plus fairness measurement are in progress. On the
+graphics side, the X server/GLX run on the emulated vGPU, the engine executes
+GL method streams, and the guest Vulkan pipeline runs end to end; rendered
+(non-black) frames are the frontier
+([`../04-implementation/05-graphics-execution-plan.md`](../04-implementation/05-graphics-execution-plan.md)).
+**No performance numbers are published yet**; the A/B programme in §3 is the
+next measurement step, and the first scheduled public measurement is the
+graphics 60 fps target (no forcing). New to CUDA analysis here: start at
 [`../../userspace/cuda/READ-ME-FIRST.md`](../../userspace/cuda/READ-ME-FIRST.md).
 
+The **reply-fidelity gate** applies to every emulated control: a control whose
+reply fields the driver consumes is not implemented until the reply is
+coherent (status-only → coherent zeroed params → coherent values for consumed
+fields → exact values) — see
+[`../../userspace/cuda/docs/04-virtualization-and-emulation.md` §6](../../userspace/cuda/docs/04-virtualization-and-emulation.md).
+
 ## 2. Correctness
 
 ### 2.1 Test corpus
diff --git a/docs/05-operations/02-debugging-and-maintenance-workflows.md b/docs/05-operations/02-debugging-and-maintenance-workflows.md
index cb3ea28..972e9b6 100644
--- a/docs/05-operations/02-debugging-and-maintenance-workflows.md
+++ b/docs/05-operations/02-debugging-and-maintenance-workflows.md
@@ -422,6 +422,38 @@ anything that is not lowmem; the module rule is recorded in
 and the shadow mapping is described in
 [`../03-architecture/06-host-module-and-hybrid-model.md`](../03-architecture/06-host-module-and-hybrid-model.md).
 
+### 5.4 Case study: vGPU guest bring-up — three size/state traps
+
+Three independent values can make a stock guest driver fail long before the
+GPU work starts.  They are worth checking in this order.
+
+1. **FB info size units.**  The framebuffer-info ABI documents the RAM,
+   total/usable/heap, mappable-heap, BAR1 and BAR1-avail size indices in
+   **kilobytes**; compression and L2-cache sizes are in bytes.  Returning
+   bytes for the kilobyte indices over-reports the emulated framebuffer by
+   1024x, which the X driver turns into a huge surface allocation.  The
+   fix is a per-index unit conversion, not a clamp.
+2. **GPU GART size.**  A multi-gigabyte GART reply makes the guest RM
+   allocate that much system memory for the GART at GL init.  On a 12 GiB
+   guest a 4 GiB GART is a fatal allocation: it appears as a
+   `nv_alloc_pages` burst with a page count in the hundreds of thousands.
+   The emulated GART should be small (hundreds of MiB at most), matched to
+   the guest RAM budget.
+3. **Shared nvClip mode-number parity.**  The first X server start after a
+   guest boot can leave the shared `screens[0].modeNum` odd.  The GL client
+   reads bit 0 as "mode switch in progress" and clears its init bits, so
+   every buffer allocation/map fails (typically `GL_OUT_OF_MEMORY`) and a
+   client that trusts a non-NULL map pointer crashes later.  A second X
+   start normally leaves the value even and the same client proceeds.
+   Treat this as a guest X-driver state issue; do not chase it as a host
+   VAS/page-table problem.
+
+Diagnosis pattern: separate *allocation size* problems (values in the
+hundreds of MiB/GiB, no host channel activity) from *buffer mapping*
+problems (GL errors with no ioctl traffic, i.e. a userspace init gate) from
+*host translation* problems (ring/USERD walks failing with `rc=-2`).  The
+three have different fixes and should not be conflated.
+
 ## 6. Release engineering
 
 * Versions are tagged; each tag carries the rung/matrix table and the