docs: vdso + vfs-protocol — the public ABI boundary, linked from the index

docs/README.md

@@ -39,37 +39,42 @@ rather than restate it. Roughly in the order things happen at runtime:
     endpoints — the backbone the microkernel's isolated servers talk over.
 12. **[syscall.md](syscall.md) — system calls.** How ring 3 asks the kernel for
     something: the `syscall`/`sysret` fast path, the trap frame, and why the table is
-    deliberately tiny.
-13. **[drivers.md](drivers.md) — writing a driver.** The payoff: a driver is an
+    deliberately tiny. The numbers are a **private** ABI — [vdso.md](vdso.md) designs
+    the public boundary that will hide them.
+13. **[vfs-protocol.md](vfs-protocol.md) — the VFS wire protocol.** The language-neutral
+    byte-level spec of the file protocol spoken over IPC: request/reply headers,
+    the operation table, mount routing, and the append-only evolution rules — the
+    first IPC protocol documented as public ABI.
+14. **[drivers.md](drivers.md) — writing a driver.** The payoff: a driver is an
     ordinary ring-3 process that claims a device, maps its registers, and **sleeps
     until its hardware interrupts it**. The claim is the capability; `irq_ack` is the
     unmask.
-14. **[driver-model.md](driver-model.md) — buses, classes and host controllers.** How
+15. **[driver-model.md](driver-model.md) — buses, classes and host controllers.** How
     real driver stacks factor into three shapes and how families share code. The
     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).
-15. **[process-management.md](process-management.md) — process management.** The
+16. **[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.
-16. **[process-lifecycle.md](process-lifecycle.md) — the process lifecycle.** Built
+17. **[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).
-17. **[device-manager.md](device-manager.md) — the device manager.** Built (M18,
+18. **[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.
-18. **[input.md](input.md) — the input module.** Broadcasting input events (keyboard,
+19. **[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.
-19. **[display.md](display.md) — the display service.** The display half of the GUI
+20. **[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
@@ -80,7 +85,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).
-20. **[halting.md](halting.md) — halting.** Why a kernel can't just "exit", and
+21. **[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:
@@ -99,6 +104,12 @@ Start with the north star:
   port to **one seam** (`std.os.danos`), so we build `runtime.os` (→ that seam) plus a
   thin `runtime.fs`, retire the `posix` shim, and follow a phased path to
   `zig build-exe hello.zig` running on danos — **not** Linux-ABI emulation.
+- **[vdso.md](vdso.md) — the vDSO, the public system-call boundary.** A design note
+  (not built yet) on keeping `abi.zig` genuinely private: a kernel-supplied, C-ABI
+  entry blob mapped into every process as the *only* way into the kernel — so the
+  syscall numbers can be renumbered or randomised at will, and Rust/C binaries get a
+  stable boundary without danos growing a dynamic linker. danos's public ABI = the
+  vDSO + the documented IPC wire protocols ([vfs-protocol.md](vfs-protocol.md) first).
 
 Cutting across all of these: