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

cmd/memfdtest/main.c

@@ -2,7 +2,7 @@
 //
 // memfdtest -- two processes map the same memfd, one writes, the other sees it.
 //
-// That sentence is docs/plan/foundations.md's own acceptance criterion for
+// That sentence is docs/architecture/kernel.md's own acceptance criterion for
 // item 2, and it is the check a permissive implementation cannot pass: an
 // mmap that quietly returns private zeroed pages satisfies every return code
 // here and fails the one assertion that matters, because the reader is a

cmd/pcitest/main.c

@@ -2,7 +2,7 @@
 //
 // pcitest -- prove that a driver could live out here.
 //
-// docs/plan/hybrid.md mechanisms 2 and 4, exercised end to end from a process:
+// docs/architecture/devices.md mechanisms 2 and 4, exercised end to end from a process:
 // enumerate the bus, claim a device, map its registers, read them, and get
 // memory the device could be pointed at.
 //

cmd/ping/main.c

@@ -6,7 +6,7 @@
 // worth recording because it is not "ours is better". toybox's ping reads its
 // replies with recvmsg(2) and asks for the TTL through an IP_RECVTTL control
 // message, and SchOS has neither: no recvmsg, no ancillary data. Both are owed
-// -- recvmsg is item 1 of docs/plan/foundations.md, where it is wanted for
+// -- recvmsg is item 1 of docs/architecture/kernel.md, where it is wanted for
 // SCM_RIGHTS -- and neither should be rushed to make one applet run.
 //
 // So this uses sendto/recvfrom, which the kernel does have, and proves the ICMP

cmd/schmode/main.c

@@ -2,7 +2,7 @@
 //
 // schmode -- change the display mode.
 //
-// docs/plan/hybrid.md milestone H3. The interesting thing about this program
+// docs/architecture/devices.md milestone H3. The interesting thing about this program
 // is how little it is: it opens a socket to `vgpud` and writes a line. No
 // syscall it makes has heard of a GPU, no kernel code runs that knows what a
 // scanout is, and if the driver on the other end gets the sequence wrong the

cmd/socktest/main.c

@@ -447,7 +447,7 @@ strneq_(const char *a, const char *b, int n)
 // ---------------------------------------------------------------------------
 // 8. SCM_RIGHTS: a descriptor crossing between processes.
 //
-// docs/plan/foundations.md item 1, docs/plan/hybrid.md mechanism 1. The thing
+// docs/architecture/kernel.md item 1, docs/architecture/devices.md mechanism 1. The thing
 // being proved is not that recvmsg returns a number -- it is that the number
 // names the *same open file* the other process had, which is why every check
 // below moves data through the descriptor rather than inspecting it.
@@ -763,7 +763,7 @@ test_fdpass_nodata(void)
 // ---------------------------------------------------------------------------
 // 15. A bound socket is a file.
 //
-// docs/plan/foundations.md item 3, in its own words: bind() a socket, then
+// docs/architecture/kernel.md item 3, in its own words: bind() a socket, then
 // stat() and `ls -l` the path and see an `s`, then unlink() it.
 //
 // The reason it matters is not tidiness. A Wayland client finds its compositor

cmd/vgpud/main.c

@@ -2,7 +2,7 @@
 //
 // vgpud -- the virtio-gpu driver, outside the kernel.
 //
-// docs/plan/hybrid.md's first eviction. The same device the kernel drives in
+// docs/architecture/devices.md's first eviction. The same device the kernel drives in
 // kernel/drivers/gpu/virtio_gpu/, driven instead by a process that asks the
 // kernel for four things and nothing else:
 //
@@ -648,7 +648,7 @@ present(void)
 //
 // This used to be a test card: three colour bands, four gradients, a
 // checkerboard, and this instance's pid in binary along the bottom edge. That
-// was scaffolding for hybrid.md's H2 and H3 -- a screenshot had to answer "did
+// was scaffolding for the out-of-kernel driver work -- a screenshot had to answer "did
 // a *userspace process* put this here", and "did the driver come back" needed
 // a second run to look different from a first that never stopped. Both
 // milestones are closed, and what was left was a garish test pattern on a
@@ -866,7 +866,7 @@ register_panic_fb(void)
 
 // --- the modeset --------------------------------------------------------------
 //
-// docs/plan/hybrid.md milestone H3: *"a modeset API, which is the thing an
+// docs/architecture/devices.md milestone H3: *"a modeset API, which is the thing an
 // out-of-kernel GPU driver makes affordable and an in-kernel one never got."*
 //
 // The claim is worth testing rather than repeating, so here is the whole of
@@ -944,7 +944,7 @@ set_mode(int w, int h)
 //
 // The name is a *name*, not a path. AF_UNIX sockets in this kernel live in a
 // table keyed by string and never touch the filesystem -- that is item 3 of
-// docs/plan/foundations.md and it is not built. Nothing here depends on which
+// docs/architecture/kernel.md and it is not built. Nothing here depends on which
 // it is, and the day it becomes a real path this keeps working.
 #define VGPUD_SOCKET "/run/vgpud"