docs: merge the legacy flat documents, add the CUDA deep-dive and link checks

* Merge and remove the pre-reboot flat documents, preserving their still-useful
  material in the structured tree: debugging workflows and the EPT-livelock
  case study (05-operations/02), performance microbenchmarks and A/B
  methodology (05-operations/01), the version-upgrade runbook
  (05-operations/02 section 4, with corrected host/guest framing), kernel-code
  pitfalls (07-developers) and the OpenRM build/load order
  (03-architecture/06 section 7). The remaining legacy files were verified
  redundant and removed.
* docs/README now records where each migrated topic lives.
* Portability: the config YAML files are called out as design targets that no
  code reads yet, with what adding support actually requires today.
* Getting started: the OpenRM step is marked optional (native vGPU-management
  workflows only; the emulated path uses the distro driver).
* tools docs: rmtool/rmtop marked as planned, pointing at the implemented
  tools/rmq subset.
* wiki: new CUDA-Userspace-Driver deep-dive page (public-safe, links the
  canonical userspace/cuda analysis) and index update.
* scripts/check-docs-links.py plus a CI step so relative links cannot rot.
* STATE.md references to removed documents repointed.

1 files changed, 38 insertions, 0 deletions

diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md
index 3d7ac78..b3ac1c5 100644
--- a/docs/07-developers/onboarding-and-standards.md
+++ b/docs/07-developers/onboarding-and-standards.md
@@ -85,6 +85,41 @@ open-iov/
   interface only.
 * Error paths: fail closed, log once with context, and give up the device
   cleanly.
+* **Guard every allocation** (`kmalloc`/`vzalloc`/`kzalloc`) and propagate
+  `-ENOMEM` with clean unwinding (`goto err_...` in reverse init order).
+
+The following rules each come from a real bug and are enforced in review:
+
+* **Never `virt_to_phys()` on vmalloc/ioremap memory.** Use
+  `is_vmalloc_addr() ? vmalloc_to_pfn() : virt_to_phys() >> PAGE_SHIFT`
+  (see `nv_vgpu_mmap_virt_to_pfn`). A bad PFN in a VFIO mmap puts a garbage
+  PFN in the guest's EPT and wedges the guest in an EPT-violation livelock —
+  case study in
+  [`../05-operations/02-debugging-and-maintenance-workflows.md`](../05-operations/02-debugging-and-maintenance-workflows.md) §5.3.
+* **`dma_addr_t` for every DMA address.** Never truncate it into `int`/`u32`:
+  IOMMU IOVAs can exceed 32 bits.
+* **Every `get` needs a `put`**: `pci_dev_get`/`pci_dev_put`,
+  `eventfd_ctx_fdget`/`eventfd_ctx_put`, `vfio_alloc_device`/`vfio_put_device`,
+  module references. Unbalanced gets become leaks that block unload.
+* **Remove paths must fully unwind init paths** (including `list_del` and
+  kthread stop); a remove that forgets one leaves the module unloadable.
+* **Fail fast in emulation mode**: never `gsp_rpc_submit_raw()` from the
+  emulation path — it writes into the same mailbox and rings the same
+  doorbell our own thread polls, a self-triggered RPC livelock. Return
+  `-ENOTSUPP` with `pr_warn_ratelimited` until a real handler exists.
+* **Log through the NULL-tolerant `nv_vgpu_*` wrappers and rate-limit**
+  anything a guest can spam.
+* `open-iov-vfio.ko` is **standalone**: no `MODULE_SOFTDEP`/dependency on
+  `nvidia` — `nvidia.ko` imports our symbols, not the other way around.
+* VM access in tooling goes through `scripts/vgpu_vm.py`; do not invoke
+  ``/QEMU directly.
+* Scripts never reboot or otherwise change system state without explicit
+  operator action (project hard rule).
+* Do not widen an API's hardware assumptions silently: if a function needs
+  `vgpu->pdev` (or similar), say so in the comment — unit tests cannot call
+  those paths.
+* The guest is stock: **no Open-IOV code in the guest, ever** — no guest
+  agent, no driver patch, no extra kernel parameters.
 
 ### 3.2 Userspace and tools (`userspace/`, `tools/`, `scripts/`)
 
@@ -98,6 +133,9 @@ open-iov/
 
 * Every behaviour change updates the doc that describes it. Docs are part of
   the definition of done.
+* Debugging discoveries go into the failure taxonomy in
+  [`../05-operations/02-debugging-and-maintenance-workflows.md`](../05-operations/02-debugging-and-maintenance-workflows.md)
+  so the next person does not rediscover them.
 * Prefer a table or a decision tree over prose for anything an operator will
   follow under pressure.
 * Protocol facts (IDs, offsets, structures) must cite their source (a live