diff --git a/.cargo/config.toml.example b/.cargo/config.toml.example
deleted file mode 100644
index e703d9a4e2a..00000000000
--- a/.cargo/config.toml.example
+++ /dev/null
@@ -1,16 +0,0 @@
-# Local fork development — copy to .cargo/config.toml (gitignored).
-#
-# Committed builds fetch every fork from GitHub, so a fresh clone works with
-# no setup. When you need to *edit* a fork, clone it next to the monorepo and
-# list it here; cargo then uses your working copy instead of the git branch.
-#
-#   git clone https://github.com/ToyOSOrg/cpal ../forks/cpal
-#   cd ../forks/cpal && git checkout toyos-0.18.0
-#
-# Delete the entry (or the file) to go back to the pushed branch.
-
-paths = [
-    # "../forks/cpal",
-    # "../forks/socket2",
-    # "../forks/winit",
-]
diff --git a/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md b/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md
new file mode 100644
index 00000000000..dec3e860cbd
--- /dev/null
+++ b/issues/a-user-copy-demand-pages-under-whatever-its-caller-holds.md
@@ -0,0 +1,21 @@
+---
+status: open
+kind: finding
+opened: 2026-10-04
+---
+
+# A user copy demand-pages under whatever its caller holds
+
+`user_ptr::translate_user` (`kernel/src/user_ptr.rs`) calls
+`process::handle_page_fault` directly when a user address is not mapped, and
+every user copy faults its windows in through it (`fault_in`).
+`handle_page_fault` takes `PROCESS_TABLE`, the current process's
+`process_data` and its address-space lock, all three a `sync::Lock`. A syscall
+that copies user memory while holding any of the three re-enters that ticket
+lock on the first unmapped window: it spins, and the kernel panics
+"DEADLOCK at …" (`Lock::lock`, `kernel/src/sync.rs`). Nothing in the tree
+refuses that order: no lock-order check covers these locks.
+
+**Exit:** the order is refused by something that fails (a type or a
+checked lock level), or every caller is shown to hold none of the three and
+the invariant is one line in `user_ptr.rs`'s header.
diff --git a/issues/every-image-ships-a-hello-rs-nothing-reads.md b/issues/every-image-ships-a-hello-rs-nothing-reads.md
new file mode 100644
index 00000000000..3687c3b8655
--- /dev/null
+++ b/issues/every-image-ships-a-hello-rs-nothing-reads.md
@@ -0,0 +1,16 @@
+---
+status: open
+kind: defect
+opened: 2026-10-04
+---
+
+# Every image ships a hello.rs nothing reads
+
+`assets/hello.rs` is swept into ROOT with the rest of `assets/`: the image
+`cargo run -- --build-only` makes holds it as `share/hello.rs`, 55 bytes, by
+`cargo run --example imgstat -- target/bootable.img`. No source, test or
+manifest in the tree names it but its row in `src/licence.rs`, and that row
+says `tests/common/compile.rs` builds it, which that file does not.
+
+**Exit:** `assets/hello.rs` and its licence row are gone, or something that
+runs reads it and the row names that.
diff --git a/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md b/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md
new file mode 100644
index 00000000000..3d790b4ead6
--- /dev/null
+++ b/issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md
@@ -0,0 +1,33 @@
+---
+status: open
+kind: defect
+opened: 2026-10-04
+---
+
+# Five apps read the system font by a path only this tree has
+
+An app builds and runs on Linux, macOS and Windows from the same source as on
+ToyOS (root `CLAUDE.md`), and stage 7 of
+`issues/a-package-is-a-directory-under-apps-and-the-installer-is-a-program.md`
+builds each one outside this repository against published SDK crates alone.
+Five of the six apps cannot, because of how they find JetBrains Mono:
+
+- `editor` (`src/main.rs:1444`), `files` (`:60`) and `paint` (`:173`) read
+  `/system/share/fonts/JetBrainsMono-Regular-8x16.font` and `expect` it, so on
+  a host they build and then panic at start; `files` reads
+  `/system/share/icons/*.svg` the same way (`:63-64`).
+- `calc` (`build.rs:32`) and `snake` (`build.rs:7`) read
+  `../../assets/JetBrainsMono-Regular.ttf` in their build scripts, a path
+  into this tree.
+
+**The owner ruled the fix on 2026-10-04**, recorded verbatim in
+`issues/the-tree-says-who-uses-each-thing.md`: an SDK call answers the
+platform's monospace font, `/system/share/fonts` on ToyOS and the platform's
+own on Linux, macOS and Windows.
+
+The ruling covers the font alone. `files`' icons have no ruling yet, so
+`files` still panics at start on a host after this file closes.
+
+**Exit:** no app's source or build script names `/system/share/fonts` or a
+path outside its own directory, each of the five takes its font from that SDK
+call, and `calc`, `editor`, `paint` and `snake` start on a host.
diff --git a/issues/std-names-the-sdk-crates-by-path.md b/issues/std-names-the-sdk-crates-by-path.md
new file mode 100644
index 00000000000..b945a692ec1
--- /dev/null
+++ b/issues/std-names-the-sdk-crates-by-path.md
@@ -0,0 +1,21 @@
+---
+status: open
+kind: defect
+opened: 2026-10-04
+---
+
+# std names the SDK crates by path
+
+`rust/library/std/Cargo.toml` takes `toyos-abi` from `../../../toyos-abi`
+and `toyos` from `../../../toyos`, so the fork knows where this repository
+keeps them. `.claude/agents/implementer.md` ("A fork") says a fork depends on
+ToyOS crates by version, never by path; `vex-sdk`, three lines above in the
+same file, is named by version.
+
+It is stage 4 of `issues/the-tree-says-who-uses-each-thing.md`: while the
+path stands, moving either crate breaks every fork commit pinned before the
+move.
+
+**Exit:** std names both by version, the build supplies them by a `[patch]`,
+a clean toolchain build passes, and the sysroot key is unchanged by the
+switch.
diff --git a/issues/the-ssh-judge-runs-the-servers-own-russh.md b/issues/the-ssh-judge-runs-the-servers-own-russh.md
new file mode 100644
index 00000000000..1e0f080bfcd
--- /dev/null
+++ b/issues/the-ssh-judge-runs-the-servers-own-russh.md
@@ -0,0 +1,19 @@
+---
+status: open
+kind: defect
+opened: 2026-10-04
+---
+
+# The SSH judge runs the server's own russh
+
+`tests/ssh-client-host` is the harness's SSH client, and the root manifest
+keeps it out of the workspace as "a second implementation". It is not one:
+it takes `russh` from `https://github.com/ToyOSOrg/russh`, branch `toyos`,
+and its lock pins commit `389804d3b9908250282746c934c58c059b88fb7e`, the same
+commit `userland/Cargo.lock` pins for `sshserver` through userland's
+`[patch]`. A defect in the fork's protocol code is on both ends of every SSH
+test, and the two can agree on it.
+
+**Exit:** the judge's lock names no `ToyOSOrg` source, or the root
+manifest's exclusion comment stops calling it a second implementation and
+this file names what judges the server's protocol instead.
diff --git a/issues/the-tree-resolves-in-five-cargo-locks-not-one.md b/issues/the-tree-resolves-in-five-cargo-locks-not-one.md
index 2c7255852e8..1732054490e 100644
--- a/issues/the-tree-resolves-in-five-cargo-locks-not-one.md
+++ b/issues/the-tree-resolves-in-five-cargo-locks-not-one.md
@@ -27,7 +27,12 @@ its measurements, not the ruling.
 **Exit:** one workspace and one lock at the root replace the five. The step
 that merges them moves no version: its lock's name and version pairs are the
 union of the aligned locks, and the kernel and the loader, both arches, are
-byte-identical to the build of the last alignment before it. The alignments
+byte-identical to the build of the last alignment before it. The root
+`.cargo/config.toml` is tracked, which `.gitignore` ignores today and where
+`.claude/agents/implementer.md` has agents list fork clones, so the merge
+moves that instruction; no `rust-toolchain.toml` is tracked outside `rust/`,
+since step 1 of the rule in `issues/the-tree-says-who-uses-each-thing.md`
+names none. The alignments
 land first, each in today's workspace; pull request #724, the root and
 kernel locks, is the first.
 
diff --git a/issues/the-tree-says-who-uses-each-thing.md b/issues/the-tree-says-who-uses-each-thing.md
new file mode 100644
index 00000000000..5304d6bfacf
--- /dev/null
+++ b/issues/the-tree-says-who-uses-each-thing.md
@@ -0,0 +1,226 @@
+---
+status: assigned
+kind: track
+opened: 2026-10-04
+---
+
+# The tree says who uses each thing
+
+The repository's top level is shaped by cargo's per-directory `build.target`,
+not by what each thing is or who uses it. The owner adopted a layout on
+2026-10-04; this file records it and the migration to it.
+
+**Owner:** the orchestrator. The rule, the rulings and the tree are the
+owner's, the tree changed only where a later ruling or `main` moved it (listed
+under it); the stages and their exits are the orchestrator's plan.
+
+## The rule
+
+> **A path says who uses a thing. A thing lives inside the one thing that uses
+> it. A thing that several things use lives under the top level named for what
+> they share. A top level exists for a boundary, or because a tool outside this
+> repository looks there, and the rule names every one of those.**
+
+**Uses** is the only relation the rule reads, and it is defined once:
+
+- **X uses Y** when X links Y, or when X's code or build script reads Y's bytes
+  by name.
+- **A shipped file is used by whoever reads its installed form.**
+- **Assembling is not a use.** Assembling is the build reading a thing to
+  compile, copy, link, convert or sign it into an image or a toolchain.
+- **Starting a program is not a use, and neither is running a tool.**
+
+None of these facts depends on which machine builds the tree, ToyOS included.
+
+**Decision procedure.** Apply the steps in order; the first that fits wins.
+
+1. **Does a tool outside this repository look for it at a fixed place?** Then it
+   goes there, and nothing else does. The complete list:
+   - **cargo:** `Cargo.toml`, `Cargo.lock`, `.cargo/config.toml`, `clippy.toml`.
+   - **git:** `.gitignore`, `.gitmodules`.
+   - **the forge, which renders the root:** `README.md`, `LICENSE-*`, `NOTICE`.
+   - **GitHub:** `.github/`, which holds the workflows, the PR template, and the
+     pictures only the README shows.
+   - **Claude Code:** `.claude/`, plus each `CLAUDE.md`, which sits at the top of
+     the subtree whose caveats it holds.
+
+   A file our own code reads is never here, whatever its subject. That is why
+   `qemu-version` leaves `.github/`.
+2. **Does nothing use it?** Then it is a root, placed by what it is:
+   - **`kernel/`:** what the loader boots.
+   - **`loader/`:** what firmware boots.
+   - **`system/<name>/`:** a program the image is; one directory per
+     `/system/bin` name.
+   - **`apps/<name>/`:** a program built on `sdk/` and registries alone, which
+     the image does not need in order to be itself. It leaves this repository at
+     stage 7.
+   - **`images/`:** an image definition.
+   - **`build/`:** the build system, meaning the root package's library and
+     binaries.
+   - **`tests/`:** anything that exists to judge. That covers the root package's
+     test targets, guest test programs, test images, machine descriptors and the
+     loops that drive them, second implementations, and corpora. One exception:
+     a test that judges a single thing with nothing else present is part of that
+     thing (step 4). **Shipping in an image does not change this.**
+   - **`ports/<name>/`:** a third-party program packaged by a recipe, with its
+     archive pinned by hash and its patch files (owner ruling, 2026-10-02).
+   - **`rust/`:** the toolchain the tree is built with, a submodule. LLVM lives
+     inside it.
+   - **`issues/`:** the record, flat.
+
+   A crate fork is not a path at all. It is a ToyOSOrg branch, named once in the
+   root `[patch]`.
+3. **Does something outside this repository use it?** Then `sdk/`. That covers
+   crates.io's crates, libc as the C face, and what std links.
+4. **Does exactly one thing use it?** Then it lives inside that thing. This
+   covers a crate, data, a firmware blob, vendored upstream source compiled into
+   that thing, a licence text, a host test, and a `CLAUDE.md`. The root package
+   counts as one thing: what its library uses lives in `build/`, and what its
+   test targets use lives in `tests/`.
+5. **Do several things use it?** Then:
+   - code goes to `lib/`, and is held to the bar of its strictest user;
+   - shipped data goes to `share/`, which mirrors `/system/share`.
+6. **Does nothing use it yet?** This is staged code. It goes where its track
+   names its first user.
+
+"Stage 7" above is stage 7 of
+`issues/a-package-is-a-directory-under-apps-and-the-installer-is-a-program.md`.
+
+## The owner's rulings, 2026-10-04
+
+Each is the option he chose, then its text, verbatim.
+
+- **Rule and top level:** "Take it as proposed (Recommended)": "The rule and
+  the 16-folder tree above; src/ becomes build/, bootloader/ becomes loader/,
+  userland/ splits into system/, apps/ and tests/guest/."
+- **One workspace:** "Yes, one workspace (Recommended)": "One lockfile, one
+  profile, shared crates tested as shipped; about 35 version alignments land
+  first."
+- **Tracker:** "Flatten it (Recommended)": "Cheapest step, done first; 574
+  citations in 284 files updated."
+- **Apps:** "calc, doom, editor, files, paint, snake (Recommended)": "The six
+  user apps; toyfetch joins them when built. Everything else is system/."
+- **filepicker:** "Publish it (Recommended)": "It becomes a public SDK crate
+  that apps may use; editor and paint keep using it."
+- **sprite:** "Files drops sprite (Recommended)": "One fewer public crate to
+  commit to; files draws what it needs itself."
+- **App fonts:** "SDK call for the font (Recommended)": "An SDK call answers
+  the platform's monospace font: /system/share/fonts on ToyOS, the platform's
+  own on Linux, macOS, Windows. Also fixes the three apps that can't start on
+  a host."
+- **toyos-ld** has no place in the tree: the owner ruled it deleted ("Just get
+  rid of toyos ld"), and pull request #726 deletes it.
+
+## The tree
+
+```
+README.md CLAUDE.md NOTICE LICENSE-APACHE LICENSE-MIT            rule step 1
+Cargo.toml Cargo.lock clippy.toml .cargo/config.toml             rule step 1: one workspace, one lock,
+                                                                 one [target.<triple>] table per guest triple
+.github/ .claude/ .gitignore .gitmodules                         rule step 1
+loader/   the UEFI loader (today bootloader/)
+kernel/   CLAUDE.md; src/ pure/ loom/ sim/ pci/ gicv3/ ps2/ dma/ cpuvuln/ microcode/ (+ intel-ucode, licence)
+system/   CLAUDE.md (the server doctrine); one directory per /system/bin name:
+          supervisor compositor (desktop/ sprite/ wallpaper.jpg)
+          netstack (mdns/ dns/ and the net family) soundserver (mixer/) console diskserver
+          fileserver logkeeper filepicker pkg update swap sshserver shell terminal toybox inspect host
+apps/     CLAUDE.md (sdk/ and registries only; Linux under Wayland, macOS, Windows)
+          calc editor files paint snake doom/ (doomgeneric/ DOOM1.WAD soundfont licences);
+          toyfetch when built
+sdk/      CLAUDE.md (identity, sysroot, publication; std links abi and toyos)
+          abi/ toyos/ keymap/ font/ window/ filepicker/ libc/ (arch/)
+lib/      acpi bcachefs blackbox blockhold blockring bootmap elf elide fat32 gpt hda i219 inspect
+          logstream manifest osrelease quiesce rootimage swap symbols tco tmpdir tsc untrusted
+          update userbound wallclock xhci
+share/    mirrors /system/share: fonts/ (+ OFL) icons/ (+ MIT)
+images/   system.toml console.toml diag.toml
+build/    CLAUDE.md; the root package's library and binaries (today src/); ci/qemu-version
+tests/    CLAUDE.md; toyos.rs checks.rs common/ checks/ (the root package's test targets)
+          guest/ (proctest kernelprobe metalprobe test-runner rust-tests/) images/ (one .toml per boot case)
+          machines/t14/ (package toyos-metal: the loop, the descriptor, the Linux timings)
+          judges/ssh/ corpus/tinycc/
+ports/    <name>/recipe.toml and patches/, empty until the first
+issues/   <slug>.md
+rust/     the submodule
+```
+
+A directory drops `toyos-` and its package keeps it (`lib/gpt` is package
+`toyos-gpt`). `system.toml` resolves a program key in `system/`, `apps/` and
+`tests/guest/` and refuses a name found in two.
+
+Where this differs from the tree the owner adopted:
+
+- `system/toyos-ld` is gone, by his toyos-ld ruling.
+- `filepicker-api` is `sdk/filepicker/`, by the filepicker ruling.
+- `sprite` is inside the compositor rather than in `lib/` or `sdk/`: by the sprite
+  ruling `files` stops using it, which leaves the compositor its one user
+  (rule step 4).
+- `apps/` names toyfetch, by the Apps ruling.
+- `lib/osrelease` is `toyos-osrelease`, which #722 added after the design;
+  the build, `libc` and the supervisor use it (rule step 5).
+- `lib/tsc` is `toyos-tsc`, which #721 added after the design; the kernel
+  and the loader use it (rule step 5).
+
+## Stages
+
+Each stage updates, in its own diff, every prompt and `CLAUDE.md` pointer that
+names a path it moves.
+
+**Exit of the track:** `git ls-tree --name-only HEAD` prints exactly the
+tree's top level: `.cargo`, `.claude`, `.github`, `.gitignore`,
+`.gitmodules`, `CLAUDE.md`, `Cargo.lock`, `Cargo.toml`, `LICENSE-APACHE`,
+`LICENSE-MIT`, `NOTICE`, `README.md`, `apps`, `build`, `clippy.toml`,
+`images`, `issues`, `kernel`, `lib`, `loader`, `rust`, `sdk`, `share`,
+`system`, `tests`, and `ports` once it holds a recipe.
+
+0. **Hygiene, no moves.** Landed with the commit that filed this track:
+   every package manifest has a `description`, and
+   `.cargo/config.toml.example`, `kernel/README.md` and
+   `kernel/TECHNICAL_DEBT.md` are gone. **Exit:** every tracked
+   `[package]` outside `rust/` has a `description` line.
+1. **A flat tracker.** Landed in #723.
+2. **Version alignment** in today's workspaces:
+   `issues/the-tree-resolves-in-five-cargo-locks-not-one.md`.
+3. **One workspace:** `issues/the-tree-resolves-in-five-cargo-locks-not-one.md`.
+   **Exit:** that file's.
+4. **std off repository paths:** `issues/std-names-the-sdk-crates-by-path.md`.
+   **Exit:** that file's.
+5. **`sdk/`:** abi, toyos, keymap, font, window, filepicker and libc (with
+   `tests/libc-arch` as `sdk/libc/arch/`); `src/sysroot.rs`,
+   `src/sdkversion.rs` and `src/release.rs` read the directory instead of a
+   list. A branch that bumps the `rust` gitlink merges the fork change with
+   it. **Exit:** `PUBLISHED` and `SYSROOT_SOURCES` are gone or derived from
+   `sdk/`; a release dry run, a clean toolchain build and the guest suite
+   green.
+6. **`lib/`, and what one thing uses into that thing:** `kernel/cpuvuln`,
+   `kernel/microcode`, the net family and `toyos-dns` into
+   `system/netstack/`. **Exit:** no `toyos-*` or `bcachefs` directory is left
+   at the root; `git diff -M` reports every change a
+   rename; `--ci host` and the guest suite green.
+7. **`userland/` splits into `system/`, `apps/` and `tests/guest/`;**
+   programs resolve by name; `userland/CLAUDE.md` becomes `system/CLAUDE.md`;
+   `files` drops `sprite` and `sprite` moves into the compositor. **Exit:**
+   `userland/` is gone; no `apps/` package depends on a path outside `sdk/`;
+   `--build-only` and the guest suite green.
+8. **Tests and images:** `images/`, `tests/images/`, `tests/machines/t14/`
+   (`src/metal*.rs`, `tests/metal/` and `tests/t14-linux/` as package
+   `toyos-metal`), `tests/judges/ssh/`, `tests/corpus/tinycc/`, and
+   `.github/qemu-version` as `build/ci/qemu-version`. Image names stay
+   `bootable-<stem>.img`. Blocked on
+   `issues/the-owners-flash-script-runs-diskutil.md`, which owns
+   `diag/flash.sh`. **Exit:** no `tests/*case/`, `console/` or `diag/`
+   directory and no root `system.toml` remains, and `--diag-boot`,
+   `--console-boot` and a `--metal-readback` build green.
+9. **`src/` becomes `build/`, `bootloader/` becomes `loader/`,** and
+   `examples/imgstat.rs` becomes a binary of the root package in `build/`
+   (rule step 2). **Exit:** `src/`, `bootloader/` and `examples/` are gone;
+   `--ci host` and `--build-only` green.
+10. **`assets/` into `share/`, `apps/doom/` and `system/compositor/`**;
+    each licence text beside what it covers; `OPENED_BY` goes; `doom.jpg`
+    and `first-boot.jpg`, which only the README shows, into `.github/`
+    (rule step 1). Needs
+    `issues/five-apps-read-the-system-font-by-a-path-only-this-tree-has.md`
+    first, since `calc` and `snake` read `../../assets` at build time.
+    **Exit:** `assets/`, `licenses/` and both photos are gone from the root;
+    the image's file list is identical before and after; the licence gate is
+    green.
diff --git a/kernel/README.md b/kernel/README.md
deleted file mode 100644
index ecd8211d823..00000000000
--- a/kernel/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# kernel
-
-The ToyOS kernel for x86-64.
-
-Depends on tyfs for filesystem support and toyos-abi for the userland ABI.
diff --git a/kernel/TECHNICAL_DEBT.md b/kernel/TECHNICAL_DEBT.md
deleted file mode 100644
index da503538fc0..00000000000
--- a/kernel/TECHNICAL_DEBT.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Kernel Technical Debt
-
-Tracked issues to address, roughly ordered by impact.
-
-## ~~1. Identity map~~ DONE
-
-Removed. Kernel PML4 has no PML4[0..255] entries. Process page tables start
-empty and build user mappings on demand. SMP trampoline uses the bootloader's
-PML4 for AP transition, then switches to kernel PML4 in ap_entry.
-
-## ~~3. No DmaAddr newtype~~ DONE
-
-Added `DmaAddr` newtype in addr.rs. `DmaPool::page_phys()` returns `DmaAddr`.
-All drivers use `DmaAddr` for device-visible addresses. `Virtqueue::base_phys`
-is `DmaAddr`. Every site that writes to hardware uses `.raw()` explicitly.
-
-## ~~4. PhysAddr::from_ptr is unchecked~~ DONE
-
-Added `debug_assert!` in `from_ptr()` that validates the pointer is in the
-high-half direct map.
-
-## ~~5. No compile-time enforcement of user pointer safety~~ VERIFIED OK
-
-Audited all `UserAddr::raw()` call sites — no kernel code outside `user_ptr.rs`
-and `paging.rs` creates raw pointers from user addresses. The convention is
-already clean. `UserAddr::raw()` is needed for page table walks and address
-arithmetic, but no code dereferences the raw value.
-
-## 6. Large NVMe reads for demand paging
-
-The demand pager maps 2MB pages but populates them by issuing up to 512
-individual 4KB page cache lookups (each potentially a separate NVMe read).
-This works but is suboptimal — a single NVMe command can transfer 2MB in
-roughly the same time as a 4KB read (command overhead dominates, not transfer
-size).
-
-**Fix:** Add a bulk read path: when demand-paging a 2MB region, issue one
-NVMe read for the entire 2MB range and populate 512 page cache entries at
-once. The page cache stays at 4KB granularity (important for fine-grained
-eviction of cold blocks), but the I/O path batches reads.
-
-**Not urgent:** Current startup times are fine. This is a throughput
-optimization for large binaries.
-
-## 7. Demand paging called from user_ptr translate()
-
-When `virt_to_phys` returns None, `user_ptr::translate()` calls
-`process::handle_page_fault()` directly. This works but is fragile — if
-`handle_page_fault` ever needs locks that are held by the caller, it deadlocks.
-The old approach (kernel dereferences user pointer, CPU faults, fault handler
-maps page, instruction retries) was more robust.
-
-**Fix:** Either (a) ensure all user pages are faulted in before syscall entry
-(a "prefault" pass), or (b) accept the current approach but audit
-`handle_page_fault` to ensure it never takes locks that syscall handlers hold.
-Option (a) is cleaner but slower for large buffers.
diff --git a/tests/toyos-rust-tests/tls-cranelift/Cargo.toml b/tests/toyos-rust-tests/tls-cranelift/Cargo.toml
index 1f8bd074aa6..788bc39a1e0 100644
--- a/tests/toyos-rust-tests/tls-cranelift/Cargo.toml
+++ b/tests/toyos-rust-tests/tls-cranelift/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "tls-cranelift"
+description = "A guest test fixture: a cdylib that runs cranelift's code generator, loaded with dlopen to test thread-local storage in a shared object."
 version = "0.1.0"
 edition = "2021"
 
diff --git a/tests/toyos-rust-tests/tls-dlopen-lib/Cargo.toml b/tests/toyos-rust-tests/tls-dlopen-lib/Cargo.toml
index 51f682b83b4..ff7d317b4f2 100644
--- a/tests/toyos-rust-tests/tls-dlopen-lib/Cargo.toml
+++ b/tests/toyos-rust-tests/tls-dlopen-lib/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "tls-dlopen-lib"
+description = "A guest test fixture: a cdylib of thread-locals at several offsets, loaded with dlopen by the TLS and unwinding tests."
 version = "0.1.0"
 edition = "2021"
 
diff --git a/tests/toyos-rust-tests/tls-lib/Cargo.toml b/tests/toyos-rust-tests/tls-lib/Cargo.toml
index abe1c365bea..4c997ab80bb 100644
--- a/tests/toyos-rust-tests/tls-lib/Cargo.toml
+++ b/tests/toyos-rust-tests/tls-lib/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "tls-lib"
+description = "A guest test fixture: a cdylib of thread-locals that std_tls links through DT_NEEDED."
 version = "0.1.0"
 edition = "2021"
 
diff --git a/tests/toyos-rust-tests/tls-multi-crate/Cargo.toml b/tests/toyos-rust-tests/tls-multi-crate/Cargo.toml
index e5f8f362fd5..7c0783a571a 100644
--- a/tests/toyos-rust-tests/tls-multi-crate/Cargo.toml
+++ b/tests/toyos-rust-tests/tls-multi-crate/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "tls-multi-crate"
+description = "A guest test fixture: a cdylib whose thread-locals and its dependency's sit beside ordinary statics, loaded with dlopen."
 version = "0.1.0"
 edition = "2021"
 
diff --git a/tests/toyos-rust-tests/tls-multi-crate/dep/Cargo.toml b/tests/toyos-rust-tests/tls-multi-crate/dep/Cargo.toml
index b6b11534cc1..70086dc1375 100644
--- a/tests/toyos-rust-tests/tls-multi-crate/dep/Cargo.toml
+++ b/tests/toyos-rust-tests/tls-multi-crate/dep/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "tls-dep"
+description = "tls-multi-crate's dependency: an ordinary static and a thread-local the linker must keep apart."
 version = "0.1.0"
 edition = "2021"
 
diff --git a/userland/calc/Cargo.toml b/userland/calc/Cargo.toml
index b58ee1d6d0d..368f805a2cc 100644
--- a/userland/calc/Cargo.toml
+++ b/userland/calc/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "calc"
+description = "A calculator: exact rationals in Calc, 64-bit two's-complement integers in Prog; the engine is a library tested on the host, and the window is winit and softbuffer."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/compositor/Cargo.toml b/userland/compositor/Cargo.toml
index 1860841e17f..fe0fe765765 100644
--- a/userland/compositor/Cargo.toml
+++ b/userland/compositor/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "compositor"
+description = "The desktop's display server: it claims the framebuffer, keyboard and mouse, composes its clients' windows and hands finished rectangles to the panel."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/console/Cargo.toml b/userland/console/Cargo.toml
index 4e35113d4fc..1d79c14de09 100644
--- a/userland/console/Cargo.toml
+++ b/userland/console/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "console"
+description = "The machine's console: /system/bin/shell on the raw framebuffer below this boot's log, for a machine with no serial port and no compositor."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/diskserver/Cargo.toml b/userland/diskserver/Cargo.toml
index 7e823426bc2..47079cf42e5 100644
--- a/userland/diskserver/Cargo.toml
+++ b/userland/diskserver/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "diskserver"
+description = "One NVMe controller driven from userland, its partitions served as toyos-blockring sessions; the library is what a client of a block service links."
 edition = "2024"
 license = "MIT OR Apache-2.0"
 
diff --git a/userland/doom/Cargo.toml b/userland/doom/Cargo.toml
index d605d606009..49a54583d97 100644
--- a/userland/doom/Cargo.toml
+++ b/userland/doom/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "doom"
+description = "DOOM: doomgeneric's C engine in a winit and softbuffer window, its music played through rustysynth and cpal."
 version = "0.1.0"
 edition = "2021"
 license = "GPL-2.0-only"
diff --git a/userland/editor/Cargo.toml b/userland/editor/Cargo.toml
index 275bcff9fb0..69a07d1d87a 100644
--- a/userland/editor/Cargo.toml
+++ b/userland/editor/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "editor"
+description = "A text editor with syntax highlighting, opening and saving through the file picker."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/filepicker-api/Cargo.toml b/userland/filepicker-api/Cargo.toml
index 593b781862d..92fab86aa0b 100644
--- a/userland/filepicker-api/Cargo.toml
+++ b/userland/filepicker-api/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "filepicker-api"
+description = "The file picker's protocol: the request a program sends /system/bin/filepicker on its port, and the path that answers it."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/filepicker/Cargo.toml b/userland/filepicker/Cargo.toml
index e340b33eb01..3ded9fefbd7 100644
--- a/userland/filepicker/Cargo.toml
+++ b/userland/filepicker/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "filepicker"
+description = "The file picker: a window that answers one program's open or save request with a path, served on the filepicker port."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/files/Cargo.toml b/userland/files/Cargo.toml
index 9e5c04dffd7..22ce10d550c 100644
--- a/userland/files/Cargo.toml
+++ b/userland/files/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "files"
+description = "A graphical file browser."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/host/Cargo.toml b/userland/host/Cargo.toml
index 0ac2a9ba936..c7ebc0aa222 100644
--- a/userland/host/Cargo.toml
+++ b/userland/host/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "host"
+description = "host <name>...: each name's IPv4 addresses, asked through std::net and so through netstack's resolver."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/inspect/Cargo.toml b/userland/inspect/Cargo.toml
index 7e794328448..01d50e06608 100644
--- a/userland/inspect/Cargo.toml
+++ b/userland/inspect/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "inspect"
+description = "/system/bin/inspect: what each owner of a device or service, and the kernel's inventory and counters, say about themselves now."
 version = "0.1.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
diff --git a/userland/libc/Cargo.toml b/userland/libc/Cargo.toml
index 99af4f6ddc4..b566182da94 100644
--- a/userland/libc/Cargo.toml
+++ b/userland/libc/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "toyos-libc"
+description = "ToyOS's C library, ours and not a fork: the POSIX layer a C program links, over toyos-abi and toyos, built into the sysroot."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/logkeeper/Cargo.toml b/userland/logkeeper/Cargo.toml
index b6aba0055b2..69e94720b0c 100644
--- a/userland/logkeeper/Cargo.toml
+++ b/userland/logkeeper/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "logkeeper"
+description = "The machine's log: the kernel's records and every program's, written to /log by a process that can die without taking the kernel with it."
 version = "0.1.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
diff --git a/userland/metalprobe/Cargo.toml b/userland/metalprobe/Cargo.toml
index c35e0ca43ac..85c86d81aa0 100644
--- a/userland/metalprobe/Cargo.toml
+++ b/userland/metalprobe/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "metalprobe"
+description = "Test-only multi-call binary: the device measurements a metal boot takes of itself, each command exiting with its number."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/netstack/Cargo.toml b/userland/netstack/Cargo.toml
index 04c8770a26d..0c28c27b7ef 100644
--- a/userland/netstack/Cargo.toml
+++ b/userland/netstack/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "netstack"
+description = "The network server: one Ethernet device claimed from the kernel, smoltcp over it, DHCP, the DNS resolver and mDNS, served to programs over IPC."
 edition = "2024"
 license = "MIT OR Apache-2.0"
 
diff --git a/userland/paint/Cargo.toml b/userland/paint/Cargo.toml
index 5d9f7bd1ee6..f70d1318cd8 100644
--- a/userland/paint/Cargo.toml
+++ b/userland/paint/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "paint"
+description = "A paint program, opening and saving through the file picker."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/pkg/Cargo.toml b/userland/pkg/Cargo.toml
index 54eab7c0880..b9ba188f5af 100644
--- a/userland/pkg/Cargo.toml
+++ b/userland/pkg/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "pkg"
+description = "The installer: an archive checked against its release's SHA256SUMS and unpacked as one directory under /apps; the decoders are a library tested on the host."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/proctest/Cargo.toml b/userland/proctest/Cargo.toml
index 9293011ac39..794beee24d0 100644
--- a/userland/proctest/Cargo.toml
+++ b/userland/proctest/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "proctest"
+description = "Test-only: subprocess creation, piped I/O and an interactive child, checked from inside a ToyOS guest."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/shell/Cargo.toml b/userland/shell/Cargo.toml
index 9c40b9f2173..3a20bcf1050 100644
--- a/userland/shell/Cargo.toml
+++ b/userland/shell/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "shell"
+description = "ToyOS's command-line shell."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/snake/Cargo.toml b/userland/snake/Cargo.toml
index a4fc958ba2e..f11cd60ec37 100644
--- a/userland/snake/Cargo.toml
+++ b/userland/snake/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "snake"
+description = "Snake, in a winit and softbuffer window."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/soundserver/Cargo.toml b/userland/soundserver/Cargo.toml
index 5d2a71fcbe4..13fc21e9b8c 100644
--- a/userland/soundserver/Cargo.toml
+++ b/userland/soundserver/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "soundserver"
+description = "The audio server: ToyOS's audio devices claimed from the kernel, and every client's stream mixed onto them."
 edition = "2024"
 license = "MIT OR Apache-2.0"
 
diff --git a/userland/sprite/Cargo.toml b/userland/sprite/Cargo.toml
index 9aaf69cefbf..0856af22ce9 100644
--- a/userland/sprite/Cargo.toml
+++ b/userland/sprite/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "sprite"
+description = "An SVG rasterized through resvg into an RGBA pixel buffer, optionally in one colour."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/sshserver/Cargo.toml b/userland/sshserver/Cargo.toml
index 819d1067d67..b096f364780 100644
--- a/userland/sshserver/Cargo.toml
+++ b/userland/sshserver/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "sshserver"
+description = "The machine's SSH server: a shell, a command, and files both ways over SFTP."
 edition = "2024"
 license = "MIT OR Apache-2.0"
 
diff --git a/userland/supervisor/Cargo.toml b/userland/supervisor/Cargo.toml
index 78c241eab8d..710f43ca183 100644
--- a/userland/supervisor/Cargo.toml
+++ b/userland/supervisor/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "supervisor"
+description = "The one program the kernel starts: it builds every program's namespace and device claims from /system/etc/system.manifest and starts it."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/swap/Cargo.toml b/userland/swap/Cargo.toml
index bd418c4a41c..32567895173 100644
--- a/userland/swap/Cargo.toml
+++ b/userland/swap/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "swap"
+description = "swap <service> <sha256> <length>: a running service's binary replaced by the one on standard input, asked of the supervisor."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/terminal/Cargo.toml b/userland/terminal/Cargo.toml
index 67ecc407e38..490ef000981 100644
--- a/userland/terminal/Cargo.toml
+++ b/userland/terminal/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "terminal"
+description = "A shell in a window: the terminal emulator, a library the console shares, and the program that runs it under the compositor."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/test-runner/Cargo.toml b/userland/test-runner/Cargo.toml
index 638278ace1d..eb6d1fe92de 100644
--- a/userland/test-runner/Cargo.toml
+++ b/userland/test-runner/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "test-runner"
+description = "Test-only: the job runner a test image starts, which runs the harness's in-guest jobs under a deadline and announces the boot to the harness."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/toybox/Cargo.toml b/userland/toybox/Cargo.toml
index 9ac87978bff..81020051a34 100644
--- a/userland/toybox/Cargo.toml
+++ b/userland/toybox/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "toybox"
+description = "A multi-call binary of command-line utilities (cat, ls, grep, ps and the rest), each run by the name it is invoked under."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/userland/update/Cargo.toml b/userland/update/Cargo.toml
index ff43e1e3fe3..f03341a6c06 100644
--- a/userland/update/Cargo.toml
+++ b/userland/update/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "update"
+description = "update: a signed image on standard input, verified and installed into the slot this machine is not running, and marked to boot next."
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"