docs: README, plan, guides and the site describe what is built now

README: rewritten around what runs (Linux software, Xorg, apk, Linux's drivers), the honest gaps, measured numbers.
plan/: 1.0.md is the finish line, where each clause of the acceptance test stands, and the register (one failing
clause: a root that survives a reboot); built plans (foundations, hybrid, alpine, xorg) and the decided-against one
(wayland) are gone, their content lives in architecture/; roadmap.md is only what is still open.
guides: building/layout/testing/adding-a-driver (Linux code may be used). history: four entries (ls -lR, TLB
shootdowns, MDIO 0x02460246, netlink MSG_TRUNC). Website: cards, stack, download page, docs index.
Code comments that pointed at deleted plan docs point at the architecture docs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EVRhxi9zpdW2uDUN4FVcao

kernel/dev/pciuser.c

@@ -302,7 +302,7 @@ pciuser_mmio_ok(uint64 phys, uint64 len)
       //
       // Nothing had noticed because the only consumer was virtio-gpu, whose
       // BARs are large. The first foreign driver found it in its first minute,
-      // which is the thing docs/plan/hybrid.md said a foreign driver would be
+      // which is the thing docs/architecture/devices.md said a foreign driver would be
       // good for.
       //
       // The widening is real and is worth naming: a sub-page BAR hands the
@@ -477,13 +477,13 @@ do_claim(uint64 argp)
   //
   // Two drivers on one device is not a subtle failure -- it is two writers of
   // the same registers, and what it looks like from outside is hardware that
-  // has started lying. The eviction path (docs/plan/hybrid.md) is for the
+  // has started lying. The eviction path (docs/architecture/devices.md) is for the
   // kernel to *hand over* a device deliberately; until a driver can be told to
   // let go, the honest answer to "may I have the one you are using" is no.
   if (d->driver) {
     // Ask it to let go. A driver with no release hook keeps its device, which
     // is always safe and, for anything on the path to a shell, correct: the
-    // rule in docs/plan/hybrid.md is that the kernel keeps a minimal driver
+    // rule in docs/architecture/devices.md is that the kernel keeps a minimal driver
     // for everything needed to reach a prompt and userspace owns the good one.
     if (!d->drv || !d->drv->release)
       return -EBUSY;

kernel/drivers/gpu/vga/vga_fb.c

@@ -272,7 +272,7 @@ const struct display_ops vga_display_ops = {
 // driver that leaves has to name its replacement rather than simply detaching;
 // detaching alone leaves gfx pointing at a device nobody is driving.
 //
-// This is the fallback rule from docs/plan/hybrid.md made real: the kernel
+// This is the fallback rule from docs/architecture/devices.md made real: the kernel
 // keeps a minimal driver for everything on the path to a shell, so a fancy
 // driver leaving degrades to a working screen instead of to no screen.
 int

kernel/drivers/gpu/virtio_gpu/virtio_gpu.c

@@ -557,7 +557,7 @@ static struct {
 
 // Hand the device to a userspace driver.
 //
-// docs/plan/hybrid.md's first eviction, and the reason it is this device: the
+// docs/architecture/devices.md's first eviction, and the reason it is this device: the
 // boundary already exists (struct display_ops), it has exactly one consumer,
 // and there is a working fallback underneath. So letting go is safe in a way
 // it would not be for the disk the root filesystem is on.
@@ -580,7 +580,7 @@ vgpu_release(struct pci_dev *d)
   if (!g)
     return -1;
 
-  // The rule from docs/plan/hybrid.md, enforced rather than described: **the
+  // The rule from docs/architecture/devices.md, enforced rather than described: **the
   // kernel keeps a minimal driver for everything on the path to a shell.** If
   // there is no framebuffer to fall back to, this device is the only screen the
   // machine has, and handing it to a process that might crash would make a
@@ -645,7 +645,7 @@ vgpu_release(struct pci_dev *d)
 
 // --- the crash screen, on a device this driver was told to let go ----------
 //
-// docs/plan/hybrid.md's bargain has a clause nobody wrote down: a device the
+// docs/architecture/devices.md's bargain has a clause nobody wrote down: a device the
 // kernel hands away is a device the kernel cannot use to tell you the machine
 // died. The second monitor sat there showing a shell prompt from before the
 // panic, which is the most misleading thing a screen can do.

kernel/drivers/net/e1000/e1000.c

@@ -423,7 +423,7 @@ e1000_link_up(struct device *dev)
 
 // Let go of the device, so a userspace driver can have it.
 //
-// The same hook virtio-gpu grew for H1, on a NIC. docs/plan/hybrid.md's rule
+// The same hook virtio-gpu grew for H1, on a NIC. docs/architecture/devices.md's rule
 // is that the kernel keeps a minimal driver for everything on the path to a
 // shell -- and a network interface is not on that path, so this one may leave.
 //

kernel/net/unix.c

@@ -339,7 +339,7 @@ sockname(struct socket *s)
 // ---------------------------------------------------------------------------
 // Descriptor passing
 //
-// docs/plan/hybrid.md mechanism 1, and item 1 of foundations.md. The kernel
+// docs/architecture/devices.md mechanism 1, and item 1 of the descriptor-passing work (kernel.md). The kernel
 // holds a reference on every descriptor in flight, which is what makes the
 // sender free to close its own copy the instant sendmsg returns -- and what
 // makes dropping a socket with descriptors still queued a thing that has to be

kernel/sys/sys_mem.c

@@ -686,7 +686,7 @@ shm_detach(int id)
 // or race to invent a key.
 //
 // It is the same segment machinery underneath, which is exactly what
-// docs/plan/foundations.md proposed: shmget()'s pages, refcounts, no_free
+// docs/architecture/kernel.md proposed: shmget()'s pages, refcounts, no_free
 // VMAs and the fork/exit accounting are all already right. What memfd adds is
 // a segment that starts empty and is sized by ftruncate(), and a file that
 // owns one reference to it.

kernel/sys/sys_net.c

@@ -812,7 +812,7 @@ SYSCALL_DEFINE(getsockopt)
 // programs that need it are not ours: libwayland and toybox's ping both call
 // recvmsg with Linux's structures and would not notice a friendlier door.
 //
-// docs/plan/foundations.md item 1, and docs/plan/hybrid.md mechanism 1.
+// docs/architecture/kernel.md item 1, and docs/architecture/devices.md mechanism 1.
 // ---------------------------------------------------------------------------
 
 // Linux caps an iovec at UIO_MAXIOV = 1024, and so does this. It was 32, and

kernel/sys/table.inc

@@ -141,11 +141,11 @@ SYSCALL(192,         55, getsockopt)
 // reads whatever it last left there and invents a flag out of stack litter.
 SYSCALL(198,        288, accept4)
 // sendmsg/recvmsg exist for the one thing only they can do: carry a descriptor
-// from one process to another (SCM_RIGHTS). docs/plan/foundations.md item 1.
+// from one process to another (SCM_RIGHTS). docs/architecture/kernel.md item 1.
 SYSCALL(199,         46, sendmsg)
 SYSCALL(200,         47, recvmsg)
 // memfd_create: an anonymous shared memory object reached by descriptor.
-// docs/plan/foundations.md item 2 -- the thing a Wayland buffer crosses on,
+// docs/architecture/kernel.md item 2 -- the thing a Wayland buffer crosses on,
 // and the reason the descriptor passing above had to exist first.
 SYSCALL(201,        319, memfd_create)