diff --git a/build.zig b/build.zig
index ed98da3..fee0f82 100644
--- a/build.zig
+++ b/build.zig
@@ -102,7 +102,7 @@ pub fn build(b: *std.Build) void {
     // declares which one it speaks (no target is set, so each inherits the target of
     // whichever binary imports it). See docs/coding-standards.md.
     //   boot-handoff : loader <-> kernel (BootInformation, framebuffer, VM layout)
-    //   abi          : kernel <-> user, core (SystemCall, mmap prot flags, page_size)
+    //   abi          : kernel <-> runtime, core (SystemCall, mmap prot flags, page_size)
     //   device-abi   : kernel <-> user, devices (DeviceDescriptor, DeviceClass, ...)
     const boot_handoff_module = b.addModule("boot-handoff", .{
         .root_source_file = b.path("system/boot-handoff.zig"),
diff --git a/docs/README.md b/docs/README.md
index 3a52d27..808cd0b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -147,7 +147,7 @@ A sub-project's extra files are reached through the module, never as separate pa
 ```
 system/          → /system   danos's own internals (the self-representation)
   boot-handoff.zig             the loader↔kernel contract (the `boot-handoff` module)
-  abi.zig                      the core kernel↔user ABI (the `abi` module)
+  abi.zig                      the private kernel↔runtime syscall ABI (the `abi` module)
   parameters.zig  initial-ramdisk.zig  shared contracts
   kernel/                     IPC, memory, scheduling, the private syscall dispatch
     architecture/x86_64/      the `architecture` module (never named by generic code)
@@ -180,7 +180,7 @@ appears in the private-ABI path.
 | Boot methods (one per way of booting the kernel) | `boot/` — `efi.zig` (UEFI) → `BOOTX64.efi` |
 | Kernel entry, panic, bring-up | `system/kernel/kernel.zig` |
 | Loader↔kernel handoff (`BootInfo`, `Framebuffer`, `MemoryMap`, VM layout) | `system/boot-handoff.zig` |
-| Core kernel↔user ABI (`SystemCall`, mmap prot flags, `page_size`) | `system/abi.zig` |
+| Private kernel↔runtime syscall ABI (`SystemCall`, mmap prot flags, `page_size`) — the runtime speaks it, not apps | `system/abi.zig` |
 | Device wire types (`DeviceDescriptor`, `DeviceClass`, …) | `system/devices/device-abi.zig` |
 | Physical frame allocator | `system/kernel/pmm.zig` |
 | Kernel heap (`std.mem.Allocator`) | `system/kernel/heap.zig` |
diff --git a/system/abi.zig b/system/abi.zig
index 939a981..ac12c7d 100644
--- a/system/abi.zig
+++ b/system/abi.zig
@@ -1,16 +1,23 @@
-//! The **kernel ↔ user** ABI: the core contract every user program speaks to the
-//! kernel — the system_call numbers, `mmap` protection flags, the page size those
-//! calls work in, and the IPC name-registry ids and notification bit. Shared by the
-//! kernel dispatcher (system/kernel/process.zig) and the user runtime library
-//! (library/runtime/), so the two can never drift.
+//! The **private kernel ↔ runtime** ABI: the raw system_call contract — the call
+//! numbers, `mmap` protection flags, the page size those calls work in, and the IPC
+//! name-registry ids and notification bit. Shared by the kernel dispatcher
+//! (system/kernel/process.zig) and the user-space runtime library (library/runtime/),
+//! so the two can never drift.
 //!
-//! This is the *core* ABI; the device half — `DeviceDescriptor` and friends, which
+//! **Application code does not speak this.** danos programs call the `runtime` library —
+//! the stable, danos-native ABI — and the runtime is the one thing that issues the
+//! actual system calls (POSIX code layers over the runtime, never on this directly). It
+//! is the same split as libSystem on macOS or win32 over the NT syscalls: the numbers
+//! here are an implementation detail the runtime hides and may renumber, not a public
+//! interface. See docs/coding-standards.md and library/runtime/.
+//!
+//! This is the *core* contract; the device half — `DeviceDescriptor` and friends, which
 //! also cross this boundary — lives with the device sub-project as [[device-abi]]
 //! (system/devices/device-abi.zig). The loader↔kernel handoff is [[boot-handoff]].
 
 /// Page size every `mmap`/`munmap` grant and the boot memory map are measured in.
-/// 4 KiB on every architecture danos targets so far. Part of the ABI because user
-/// code aligns to it (grants are page-granular) and the kernel guarantees it.
+/// 4 KiB on every architecture danos targets so far. Part of the ABI because the
+/// runtime aligns to it (grants are page-granular) and the kernel guarantees it.
 pub const page_size = 4096;
 
 /// The kernel system_call numbers — the single source of truth shared by the kernel