docs: the tree moved and the documentation did not

The site and several documents still described the system as it was before
virtual terminals, the new schinit, the hybrid work and descriptor passing.

docs/architecture/init.md described the wrong program. It documented a single
schinit that parses manifests and supervises jobs, which has not been true since
PID 1 was split: PID 1 forks a supervisor, spawns jobs on its behalf and reaps;
the job table lives in /proc/schinit; a heartbeat runs both ways; and
proc_reincarnate() re-execs PID 1 in place rather than panicking. Rewritten
around what exists, keeping the reasoning that is still load-bearing -- the five
failures of the sibling-init scheme, the escalation ladder, and the three bugs in
the reincarnation path that each had to happen before they were obvious.

docs/plan/init.md is deleted, which is the tree's own rule for finished work and
had not been applied. Fourteen source comments referenced it by part number, so
they are repointed at the architecture doc by section name rather than left
dangling -- a deleted document nobody notices is worse than a stale one.

docs/architecture/devices.md gained the section it has been missing since
/dev/pci existed: what a driver needs from a kernel, why mmap is checked against
the caller's claims, why DMA is a call and not a mapping, and why the write back
after an interrupt is not optional. Also that a released device does not come
back by itself, which is true and was nowhere.

docs/architecture/networking.md gained a descriptor-passing section, and
docs/architecture/README.md's stack diagram gained the two layers and the third
seam it was missing. "Two seams hold the whole thing together" has not been true
since /dev/pci.

docs/plan/README.md said the hybrid work was deliberately last, on the argument
that an interface with no consumer is wrong in ways nobody can see. The argument
was right; the conclusion was not, and the document now says why it changed --
the alternative to a driver compatibility layer is writing a driver for every
device that exists, and the original objection is answered rather than ignored
because SchOS's own drivers are the consumers.

The site: a Hybrid section with the eviction transcript, cards for virtual
terminals, schinit and drivers outside the kernel, and the numbers remeasured
rather than estimated -- 46,961 lines, 207 syscalls. The boot log in app.js is
from a boot taken today, and the lines are trimmed to what the console can show
without clipping, each still a verbatim prefix of real output.

Two small rendering fixes found by looking at the pages rather than assuming:
.console pre's min-height is now scoped to the hero, so a static transcript sizes
to its content instead of reserving eight lines it does not have; and the docs
reader's contents panel strips inline marks from headings, so a heading written
`proc_reincarnate()` no longer carries its backticks into the sidebar.

Every intra-doc link checked; none broken.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2

docs/architecture/devices.md

@@ -57,6 +57,75 @@ can read beats a list assembled by side effects.
 
 ---
 
+## Drivers that are not in the kernel
+
+`/dev/pci` (major 9) hands a PCI device to a process. It is deliberately about
+*PCI devices* and not about any driver model, and its first users are SchOS's
+own drivers, evicted one at a time — which is the ordering that keeps it a
+general mechanism rather than a hole shaped like something foreign.
+
+What a driver needs from a kernel, and all it needs:
+
+| | |
+|---|---|
+| find its device, and read what the bus says | `PCIIOC_INFO`, `PCIIOC_CFG` |
+| be given it, exclusively | `PCIIOC_CLAIM` |
+| reach its registers | `mmap`, where the offset is a BAR's physical address |
+| memory it can hand to the device | `PCIIOC_DMA` |
+| be told when the device wants attention | `PCIIOC_IRQ`, then `read()` |
+
+Three of those are worth expanding on, because each encodes a decision:
+
+**`mmap` is checked against the caller's claims.** An offset that is not inside
+a BAR of a device this process holds is refused. That is the whole difference
+between this and `/dev/mem` with extra steps.
+
+**DMA is a call, not a mapping.** The process is told the *physical* address,
+which is precisely what it cannot work out for itself, and the memory comes from
+an arena reserved at boot before the general allocator gets anything.
+
+**Interrupts arrive by `read()`**, the way Linux's uio does it and for the same
+reason: a descriptor composes with `poll`, and a driver that stops reading falls
+behind rather than losing events. The kernel masks the line when the interrupt
+arrives and leaves it masked until the driver `write()`s back. **That write is
+not optional.** A PCI interrupt is level-triggered — it stays asserted until the
+cause is cleared *at the device*, which is a different register on every chip and
+therefore something only the driver can do. Signal EOI on a line that is still
+asserted and it re-fires immediately, for ever. That is not hypothetical: it
+happened here at 72,000 interrupts a second, and what it looked like from
+userspace was a clock running seven times slow. See §13 of
+[../history/kernel.md](../history/kernel.md).
+
+### Handing a device over
+
+`struct pci_driver` has a `release` hook. A driver that does not define one keeps
+its device — always safe, and for anything on the path to a shell also correct.
+A driver that does define one has to give back everything, not just the device:
+the first eviction found this the hard way, because releasing the GPU while
+keeping its 4 MB framebuffer meant the incoming driver was told there was no DMA
+memory left.
+
+`cmd/vgpud` is the virtio-gpu driver as an ordinary process. It does the whole
+virtio 1.0 bring-up from outside — reset, feature negotiation, a virtqueue in DMA
+memory, `SET_SCANOUT`, transfer and flush — and while it owns the GPU the kernel
+console falls back to the VBE framebuffer.
+
+**No syscall on that path knows it is talking about a GPU.** The kernel hands
+over a PCI device; the process decides what it is.
+
+### What this is not
+
+**It is not a security boundary.** There is no IOMMU, so a process holding a DMA
+buffer can point the device at any physical address. This isolates a driver
+against its own *bugs* and not against its own *intent* — a crashed driver that
+restarts instead of taking the machine down is the entire benefit, and it is
+worth having on those terms. [../plan/hybrid.md](../plan/hybrid.md) says so at
+length.
+
+**One device per process.** A driver drives one thing; if you need two, run two.
+
+---
+
 ## Linux drivers
 
 **Decided 2026-08-08.** Linux drivers are not shipped with SchOS and never
@@ -96,9 +165,14 @@ existing mechanisms for keeping that true mechanically rather than by intention.
   `in_use` flag is the hook a hot-unplug path would need, and nothing sets it
   for that purpose.
 - **`NDEVICE` is 32**, compile-time, like every other table in the kernel.
-- **Drivers are fixed at link time.** There is no module loader, and nothing can
-  be installed after the build — the class vtable is the attachment point a
-  loader would use, and it is the only part that exists.
+- **In-kernel drivers are fixed at link time.** There is no module loader, and
+  nothing can be added to the kernel after the build. A driver *outside* the
+  kernel is an ordinary program and can be started whenever — but it reaches its
+  device through `/dev/pci` and publishes nothing to the class vtables, so the
+  console cannot be handed to one yet.
+- **A released device does not come back by itself.** `PCIIOC_RELEASE`, or the
+  process exiting, leaves the interrupt line masked and the in-kernel driver
+  unbound. Something has to start a replacement; nothing watches for one.
 - **Only two class vtables are defined**: `display_ops` and `netdev_ops`.
   Storage and input devices appear in the list with `ops = 0` and are reached
   through their own subsystems instead.