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, 15 insertions, 3 deletions

diff --git a/docs/02-getting-started/01-install-and-first-run.md b/docs/02-getting-started/01-install-and-first-run.md
index f323dbb..d1c57c3 100644
--- a/docs/02-getting-started/01-install-and-first-run.md
+++ b/docs/02-getting-started/01-install-and-first-run.md
@@ -30,7 +30,7 @@
 git clone https://git.vgpu.io/open-iov.git
 cd open-iov
 ./install.sh deps        # build/runtime dependencies
-./install.sh nvidia      # NVIDIA open kernel modules (submodule) + patches
+./install.sh nvidia      # optional: NVIDIA open kernel modules (submodule) + patches
 ./install.sh firmware    # GSP firmware image (verified)
 ./install.sh build       # kernel module + userspace
 ```
@@ -45,7 +45,8 @@ short and comments the order.
 # 1. Kernel module first: it generates Module.symvers used by the next step.
 make kernel
 
-# 2. NVIDIA OpenRM modules (must see our symbols):
+# 2. Optional: NVIDIA OpenRM modules (needed only for native vGPU-management
+#    workflows; see section 3). They must see our symbols:
 #    KBUILD_EXTRA_SYMBOLS=<repo>/kernel/Module.symvers
 ./scripts/build_nvidia_openrm.sh
 
@@ -62,11 +63,22 @@ make userspace
 
 ```bash
 ./scripts/stack_manager.sh status        # check what is currently loaded
-./scripts/stack_manager.sh load-stack    # vfio/mdev prereqs -> open-iov -> nvidia (if used)
+./scripts/stack_manager.sh load-stack    # vfio/mdev prereqs -> open-iov -> nvidia (optional)
 ./scripts/stack_manager.sh mdev-create   # create a vGPU mediated device
 ./scripts/stack_manager.sh mdev-list     # inspect /sys/bus/mdev/devices/
 ```
 
+**The `nvidia` (OpenRM) stage is optional.** It is needed only when the host
+must run NVIDIA's OpenRM modules built against the symbols `open-iov-vfio.ko`
+exports — that is, the native vGPU-management/RM-callback workflows. The
+QEMU/emulated path uses the distribution driver that already manages the
+physical GPU; `load-stack` skips the OpenRM submodule when a distribution
+driver is present, and the build steps for it (`./install.sh nvidia`,
+`./scripts/build_nvidia_openrm.sh`) can be skipped. When the OpenRM path *is*
+used, the build and load order in
+[`../03-architecture/06-host-module-and-hybrid-model.md`](../03-architecture/06-host-module-and-hybrid-model.md)
+§7 applies.
+
 The mdev device is the virtual GPU. Everything after this point treats it like
 any other VFIO device.