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/display.md

@@ -25,7 +25,7 @@ which one you're holding decides what you can do.
   exiting ([gop.md](gop.md)). Once the kernel runs, GOP is **gone** — no `set_mode`, no
   mode list, no EDID. What survives is the frozen snapshot in
   [`BootInformation.framebuffer`](../system/boot-handoff.zig): `{base, width, height,
-  pitch, format}`, and nothing more.
+  pitch, format, refresh_hz}`, and nothing more.
 
 - **The PCI class-0x03 device is the raw controller** — BARs, config space, registers,
   IO ports. It is what you actually *own* after boot. On QEMU's emulated adapter
@@ -69,28 +69,30 @@ rest of the system hasn't had to face:
    [syscall](syscall.md). A user-space display service needs a **new mechanism just to
    touch the pixels**. (See "The handoff" below — this is built.)
 
-2. **danos has no cross-process shared memory.** The memory syscalls are `mmap`
+2. **danos had no cross-process shared memory.** At v1 the memory syscalls were `mmap`
    (private, zeroed), `mmio_map` (a *claimed device's* MMIO), and `dma_alloc` (new
    pinned physical). The block driver's "pass a buffer by physical address" trick
    ([block/protocol.zig](../system/services/block/protocol.zig)) works *only because its
    consumer is DMA hardware*. A compositor that CPU-reads and blends client layers can't
-   use it — it would have to *map* another process's memory, which nothing allows. This
-   is deferred (see "What v1 does not do"), because v1 sidesteps it entirely.
+   use it — it would have to *map* another process's memory, which nothing allowed. v1
+   sidesteps it entirely (see "What v1 does not do"); v2 has since built the primitive
+   (`shared_memory_create` / `shared_memory_map` / `shared_memory_physical` —
+   [display-v2.md](display-v2.md)).
 
 ## Architecture
 
 ```
   kernel  ── owns the boot framebuffer; bootstrap console only
-     │   seeds a "display0" device node from BootInformation.framebuffer
+     │   seeds a display-class device node from BootInformation.framebuffer
      │   (ResourceKind.memory = [base, height*pitch], write-combining hint,
-     │    plus DisplayInfo{width, height, pitch, format})
+     │    plus DisplayInfo{width, height, pitch, format, refresh_hz})
      ▼
   display service   (system/services/display/, ServiceId.display)      ← the compositor
-     │   device.claim(display0) → mmio_map(WRITE-COMBINING) = FRONT buffer (the LFB)
+     │   device.claim(display node) → mmio_map(WRITE-COMBINING) = FRONT buffer (the LFB)
      │   mmap(cacheable) a BACK buffer of the same geometry
-     │   owns:  an ordered LAYER STACK  +  a per-frame DAMAGE list
+     │   owns:  an ordered LAYER STACK  +  a per-frame DAMAGE tracker (rect list or tile grid)
      │   loop:  composite dirty layers → back buffer → present dirty rects → front
-     │   backend is an INTERNAL interface: {gop-fb} today; {bochs-dispi, virtio-gpu} later
+     │   backend is an INTERNAL interface: {gop-fb} at boot; {virtio-gpu} on hot-attach (v2)
      ▼   reached by name (ipc_lookup); clients drive it over the display protocol
   ┌────────────────────────────────────┬──────────────────────────────────────┐
   drawing clients (v1)                  surface clients (deferred)
@@ -121,12 +123,15 @@ release-on-death, and re-claim-on-restart for free (the [resilience](resilience.
 story: a crashed display service returns the LFB to the kernel, and its restart
 re-claims it).
 
-- The kernel seeds a synthetic **`display0`** node into the
-  [devices-broker](../system/kernel/devices-broker.zig) at init, from
+- The kernel seeds a synthetic **display-class** node into the
+  [devices-broker](../system/kernel/devices-broker.zig) at init (`seedDisplay`), from
   `BootInformation.framebuffer`: one `ResourceKind.memory` resource spanning
   `[base, height*pitch]`, tagged **write-combining**, plus a small
-  `DisplayInfo{width, height, pitch, format}` (the memory resource says *where* and *how
-  big*; `DisplayInfo` says how to *interpret* the bytes).
+  `DisplayInfo{width, height, pitch, format, refresh_hz}` (the memory resource says *where*
+  and *how big*; `DisplayInfo` says how to *interpret* the bytes — and `refresh_hz`, the
+  panel refresh the loader computed from EDID before `ExitBootServices`, seeds the
+  compositor's frame clock). The node carries no name or index; it is identified purely by
+  its `display` device class.
 - The service `device.claim`s it and `mmio_map`s the resource. The map is
   **write-combining**, not the strong-uncacheable that `mmio_map` uses for register
   MMIO. The kernel already programs a WC PAT slot for its own console
@@ -138,8 +143,8 @@ re-claims it).
   panic on screen wins.
 
 The display service is a **named boot service**: `init` spawns it by name alongside
-`vfs`/`input`/`device-manager` ([init.zig](../system/services/init/init.zig)), and it
-self-discovers `display0` with `device.enumerate`. The [device manager](device-manager.md)
+`input`/`device-manager`/`fat` ([init.zig](../system/services/init/init.zig)), and it
+self-discovers the display node with `device.enumerate` (matching on `DeviceClass.display`). The [device manager](device-manager.md)
 matching path (PCI class 0x03 → a driver) is reserved for the future *native* backend, not
 this singleton synthetic node.
 
@@ -182,6 +187,12 @@ discovered.
 The compositor holds an **ordered stack of layers**. Each layer has a rectangle, a
 z-order, a visibility flag, and a surface. Presenting walks the stack bottom-to-top,
 painting each dirty layer into the back buffer, then flushes the damage to the front.
+Damage is tracked by one of two interchangeable trackers behind a compile-time
+`damage_mode` A/B switch ([display.zig](../system/services/display/display.zig)): a
+free-form dirty-rectangle **list** (tight bounds, heuristic merging) or a fixed 64-px
+**tile grid** (exact O(1) merging, tile-quantized repaints) — the grid is the default;
+[compositor.zig](../system/services/display/compositor.zig) has both, with the trade-off
+discussion.
 
 In v1 the surfaces are **server-owned**, and clients draw into them with a small
 immediate-mode command protocol — essentially the model early X used, and enough for a
@@ -258,15 +269,16 @@ both are clean additions behind the interfaces v1 establishes.
 
 - **Client-rendered surfaces (shared memory).** The fast path for a bitmap-heavy app is
   to render into its *own* buffer and hand the compositor a *reference*, not a stream of
-  commands. That needs the missing cross-process shared-memory primitive — best built as
-  the natural generalization of the existing M13 [capability passing](driver-model.md)
+  commands. That needs a cross-process shared-memory primitive — the natural
+  generalization of the existing M13 [capability passing](driver-model.md)
   from *endpoints* to *memory objects* (`shared_memory_create(len) → {cap, virtual_address}`, pass `cap` on
   an `ipc_call`, receiver `shared_memory_map(cap) → virtual_address`). v1 avoids it because server-owned
-  surfaces already prove the whole pipeline.
+  surfaces already prove the whole pipeline; v2 has since built exactly that primitive
+  ([display-v2.md](display-v2.md)) — the client-surface path on top of it is still open.
 
 - **Runtime mode-setting (a native backend).** Detecting the EDID mode list and changing
-  resolution / bpp at runtime needs the raw PCI device. The first native backend is
-  Bochs DISPI — the register interface QEMU's `-device VGA` exposes — behind the same
+  resolution / bpp at runtime needs the raw PCI device. The first native backend — since
+  built by v2 ([display-v2.md](display-v2.md)) — is virtio-gpu, behind the same
   internal backend interface the dumb framebuffer sits behind. Refresh-rate and colour
   management (a gamma LUT) are real-GPU-KMS territory, far beyond this.