docs: full docs-vs-code audit — fix every stale claim across 40 docs

Every doc verified claim-by-claim against the code by parallel audit agents,
then fixed and adversarially re-verified. Two waves of staleness corrected:
the originally audited findings (higher-half boot handoff, kernel VFS
takeover, fault isolation + claim release + driver restart, AML/S5 moving to
ring 3, threading's shipped design, USB+FAT landing) and a second pass of
adjacent claims the verifiers caught (smp.md 'not built yet' intro,
system-requirements' PS/2-only and no-storage claims, halting.md's red-panic
and no-IDT text, testing.md's serial mirroring, router-era vfs-protocol
wording, capsule-first boot loading).

threading.md now documents the shared-fate gap explicitly: the design says a
process dies whole, the kernel today kills only the offending thread.

Also fixes three stale code comments (isr.s exceptionHandler, acpi.zig
sleepValue, build.zig boot-volume) — comments only, no behavior change.

docs/README.md

@@ -54,27 +54,32 @@ rather than restate it. Roughly in the order things happen at runtime:
     three primitives it proposed are long since built (M13 capability passing,
     M14 DMA + barriers, M15 MSI), and the driver *contract* on top of them —
     hello, supervision, restart — is built too (device-manager.md, M18).
-16. **[process-management.md](process-management.md) — process management.** The
+16. **[usb-hub.md](usb-hub.md) — USB hubs.** Built (M22): why hub topology is handled
+    *inside* the `usb-xhci-bus` driver rather than a separate hub class driver — a
+    device behind a hub is reached by the **controller**, programmed with a route
+    string in its slot context — plus the compound-hub reality (a USB 3.0 hub is
+    physically two hubs) and detection via the hub's status-change interrupt endpoint.
+17. **[process-management.md](process-management.md) — process management.** The
     microkernel's `ps`/`kill`/SIGCHLD: enumerate as a table snapshot, the
     supervision link as the kill authority, and child-exit notifications over the
     same endpoints IRQs arrive on.
-17. **[process-lifecycle.md](process-lifecycle.md) — the process lifecycle.** Built
+18. **[process-lifecycle.md](process-lifecycle.md) — the process lifecycle.** Built
     (M17): signals over IPC as the one lifecycle vocabulary every process speaks — the
     POSIX.1-1990 words with message delivery instead of stack hijack, the stable
     `runtime.process` interface, exit reasons, published exit events any stateful
     service can subscribe to (the VFS releasing dead clients' handles), and the two
     iron rules (cleanup is the kernel's job; kill is not a signal).
-18. **[device-manager.md](device-manager.md) — the device manager.** Built (M18,
+19. **[device-manager.md](device-manager.md) — the device manager.** Built (M18,
     through the app surface): the
     tree, the matcher, and the supervisor. Tree structure lives in the manager,
     authority stays in the kernel; bus drivers report what they see; drivers are
     restarted through the lifecycle vocabulary — the plan that turns
     [resilience.md](resilience.md)'s restart goal into increments.
-19. **[input.md](input.md) — the input module.** Broadcasting input events (keyboard,
+20. **[input.md](input.md) — the input module.** Broadcasting input events (keyboard,
     mouse, joystick): why a synchronous rendezvous can't fan out to many listeners, the
     asynchronous `ipc_send` primitive built to fix it, and the per-device subscribe/publish
     service layered on top.
-20. **[display.md](display.md) — the display service.** The display half of the GUI
+21. **[display.md](display.md) — the display service.** The display half of the GUI
     track: a user-space compositor that owns the framebuffer, composes a layer stack into
     a double buffer, and presents it. Why GOP and the PCI display device are two views of
     one controller, the device-node + write-combining handoff, and what flicker-free buys
@@ -85,7 +90,7 @@ rather than restate it. Roughly in the order things happen at runtime:
     further out, two research snapshots survey what a *native* driver for real GPU silicon
     would take as another `.scanout` backend: [nvidia-gpus.md](nvidia-gpus.md) (RTX 3060 /
     Ampere) and [intel-igpu.md](intel-igpu.md) (Intel iGPU).
-21. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
+22. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
     how `while (true) hlt` parks the CPU safely once there's nothing left to do.
 
 Start with the north star:
@@ -139,7 +144,7 @@ Cutting across all of these:
   hardware exists via ACPI (x86) or device tree (ARM) behind one neutral device model —
   when to build it, and how to keep it architecture-agnostic.
 - **[acpi.md](acpi.md) — finding the ACPI tables.** The concrete x86 locator chain:
-  how the loader captures the **RSDP**, hands its physical address across in `BootInfo`,
+  how the loader captures the **RSDP**, hands its physical address across in `BootInformation`,
   and how the platform derives the **RSDT/XSDT** from it and walks the SDTs — plus the
   live event side (the SCI, the power button, GPE/Notify) the ring-3 acpi service runs.
 - **[power.md](power.md) — the power service.** System power as a domain-named
@@ -210,7 +215,7 @@ addressed as **`system/services/init`** — the repeated leaf resolves away:
 | `library/runtime/runtime.zig`          | `library/runtime` (the `runtime` module)         |
 
 In **source**, a sub-project is a directory so it can hold many files — the entry is
-`init/init.zig`, beside it `vfs/vfs-test.zig`, `vfs/protocol.zig`, and so on. When
+`fat/fat.zig`, beside it `fat/engine.zig`, `fat/on-disk.zig`, and so on. When
 **addressed or installed**, that collapses to the single canonical path: the `init`
 binary installs to `/system/services/init` (a file at that path), not
 `/system/services/init/init`. The repeated leaf exists only in source; the directory is
@@ -222,24 +227,28 @@ A sub-project's extra files are reached through the module, never as separate pa
 system/          → /system   danos's own internals (the self-representation)
   boot-handoff.zig             the loader↔kernel contract (the `boot-handoff` module)
   abi.zig                      the private kernel↔runtime syscall ABI (the `abi` module)
-  parameters.zig  initial-ramdisk.zig  shared contracts
-  kernel/                     IPC, memory, scheduling, the private syscall dispatch
+  parameters.zig  initial-ramdisk.zig  vfs-protocol.zig  shared contracts
+  kernel/                     IPC, memory, scheduling, the VFS root, the private syscall dispatch
     architecture/x86_64/      the `architecture` module (never named by generic code)
   devices/                    the device model /system/devices reflects (+ aml/)
     device-abi.zig            the device wire types (the `device-abi` module)
-  drivers/     hpet/ bus/   one sub-project per driver → /system/drivers
-  services/    init/ vfs/ device-manager/   system servers → /system/services (vfs/ holds
-                              vfs.zig, vfs-test.zig, protocol.zig)
+  drivers/     pci-bus/ ps2-bus/ usb-xhci-bus/   one sub-project per driver → /system/drivers
+  services/    init/ fat/ device-manager/   system servers → /system/services (fat/ holds
+                              fat.zig, engine.zig, on-disk.zig)
 library/         → /lib       libraries, one sub-directory each
   runtime/                    the danos-native runtime + file API (fs) — the stable application ABI
 boot/            → /boot      the loaders
 tools/  test/                 host-side build + QEMU test harness
 ```
 
-A sub-project exposes its **public interface as a module**: `system/services/vfs/` owns
-the VFS wire protocol (`protocol.zig`, the `vfs-protocol` module), which the runtime's
-file API (`runtime.fs`) imports by name. `usb`/`block` drivers expose their protocols the
-same way.
+A sub-project exposes its **public interface as a module**: the `usb-xhci-bus` driver
+owns the USB transfer protocol (`usb-transfer-protocol.zig`, the `usb-transfer-protocol`
+module), which `runtime.usb` imports by name — the USB class drivers reach the
+protocol through that wrapper; `block` exposes its protocol (`block-protocol`) the
+same way. The VFS wire protocol is the one that outgrew its
+sub-project: the VFS root moved into the kernel (`system/kernel/vfs.zig`), so the
+protocol lives as a shared contract at `system/vfs-protocol.zig` (the `vfs-protocol`
+module), which the runtime's file API (`runtime.fs`) imports by name.
 
 There is **no POSIX/C compatibility layer today**: danos programs do file I/O through the
 danos-native `runtime.fs` (open/read/write/list over the VFS). A hand-rolled POSIX shim
@@ -254,7 +263,7 @@ exception in [coding-standards.md](coding-standards.md) applies to that seam.
 |------|------|
 | Boot methods (one per way of booting the kernel) | `boot/` — `efi.zig` (UEFI) → `BOOTX64.efi` |
 | Kernel entry, panic, bring-up | `system/kernel/kernel.zig` |
-| Loader↔kernel handoff (`BootInfo`, `Framebuffer`, `MemoryMap`, VM layout) | `system/boot-handoff.zig` |
+| Loader↔kernel handoff (`BootInformation`, `Framebuffer`, `MemoryMap`, VM layout) | `system/boot-handoff.zig` |
 | Private kernel↔runtime syscall ABI (`SystemCall`, mmap prot flags, `page_size`) — the runtime speaks it, not apps | `system/abi.zig` |
 | Device wire types (`DeviceDescriptor`, `DeviceClass`, …) | `system/devices/device-abi.zig` |
 | Physical frame allocator | `system/kernel/pmm.zig` |
@@ -264,6 +273,7 @@ exception in [coding-standards.md](coding-standards.md) applies to that seam.
 | IPC channels between kernel threads (message passing) | `system/kernel/ipc.zig` |
 | IPC endpoints: cross-address-space call/reply, handles, notifications | `system/kernel/ipc-synchronous.zig` |
 | User processes: ELF loading, address spaces, the syscall table | `system/kernel/process.zig` |
+| VFS root: mount table + kernel-served nodes (`fs_resolve`/`fs_node`); wire protocol in `system/vfs-protocol.zig` | `system/kernel/vfs.zig` |
 | Device tree + claim capability + `device_register` containment | `system/kernel/devices-broker.zig` |
 | IRQ-as-IPC: routing a device interrupt to a driver's endpoint | `system/kernel/irq.zig` |
 | Hardware discovery (ACPI/device tree) behind one neutral device model | `system/devices/` |
@@ -271,7 +281,7 @@ exception in [coding-standards.md](coding-standards.md) applies to that seam.
 | In-kernel test cases | `system/kernel/tests.zig` |
 | Arch-specific kernel code (`halt`, GDT/IDT/TSS, exception + interrupt stubs, page tables, APIC/IO-APIC/timer, serial, linker script) | `system/kernel/architecture/x86_64/` |
 | danos-native runtime (`runtime`): syscall wrappers, heap, IPC, device access, the file API (`fs`) — the stable application ABI | `library/runtime/` |
-| System services (init, the VFS server + `protocol`, the device-manager) | `system/services/` |
+| System services (init, the `fat` filesystem, the device-manager) | `system/services/` |
 | Device drivers, one sub-project each (`pci-bus`, `ps2-bus`, `usb-xhci-bus` bus drivers) | `system/drivers/` |
 | Build + `run-x86-64` (QEMU/OVMF) + `release-x86-64` (the flashable ISO) | `build.zig` |
 | QEMU integration test harness | `test/qemu_test.py` |