[Japabu]

Draft for review. The ToyOS manual the owner approved on 2026-11-05: an mdBook in docs/, published to GitHub Pages from main.

How the manual is organised

What it must deliver — the requirements, four pages:

• Purpose and scope: release one (self-hosting development, browser and media, Bluetooth, passkeys, native Rust and C), performance bars, reproducibility, what is deferred.
• The desktop and its hardware: the two release laptops, the desktop's shape, apps in a session, more than one user.
• Installation and updates: installer, image contents, packages, updates.
• Access, privacy and data: permissions, storage encryption, login and recovery, diagnostics.

How it works — one page per area: overview (layer diagram, who does what, rules every boundary follows), trust, kernel, processes and authority, sessions and permissions, files and views, storage, memory, scheduling and power, devices and drivers, boot and updates, services and failure, logs and diagnostics, applications and portability.

Using it — closest to man pages: building and running, the program interface (kernel ABI families, SDK, std, libc, how a program starts), the system manifest, commands.

Pages are short, mostly lists, with plain-text diagrams. No preprocessor plugins.

The rules it lives by

• It names no code: no source paths, file names, functions, crate paths or snippets. User-facing command names (cargo run, pkg, launch) and the file-tree layout (/system, /home) appear, as a man page would show them.
• It states the intended design. Progress, status and measurements stay in issues/ and the evidence.
• Root CLAUDE.md now says, once: a PR that changes an architectural decision or a requirement updates the manual in the same PR, review checks it, and nothing cites the manual. CLAUDE.md's "Architecture and sources of truth" points at it. The reviewer file points at that rule; the implementer and orchestrator files apply it to their own steps.

What moved

• Root CLAUDE.md: the targets, self-hosting north star, userland first, explicit authority, existing Rust, the trust model, the loader/CPU/input/logging/POSIX placements and firmware loading. Engineering principles, testing, safety and dependency policy stay.
• system/CLAUDE.md: the "server never blocks on a client" doctrine; its code mechanics stay.
• Issue tracks: the design sections of the storage, file-isolation, file-layout, users, process-lifecycle, device-ownership, desktop, package, loader, scheduler, update, swap and GPU tracks. Their stages, exits and the dates of the rulings stay. issues/README.md now says a track does not restate the design.
• the-capability-end-state-is-twelve-answers is deleted: it existed "since the tree keeps no spec corpus", and its answers are now the authority page. Its remaining work is issues/the-handle-lifecycle-has-no-adversarial-suite.md.

Publishing

.github/workflows/manual.yml runs on pushes to main and on workflow_dispatch, never on pull requests. It builds mdBook 0.5.4 with cargo install --locked (no cache), uploads with actions/upload-pages-artifact v5.0.0 and deploys with actions/deploy-pages v5.0.1, both pinned by SHA. The build job holds contents: read and the deploy job pages: write and id-token: write; the deploy job also runs only on refs/heads/main. The owner enables Pages with GitHub Actions as its source; no repository settings were touched. build/ci.rs's workflow census counts the seventh workflow.

Checks

At 6566d58 (round 1), on macOS. Round 2 (9af4ef5) changes text only (four manual lines and one track line); mdbook build docs passes on it, and host CI was not rerun:

• cargo run -- --ci host: exit 0, "108 step(s), all green" (log). The run includes the workflow census, now 7, and the tracked-file identity gate over docs/.
• mdbook build docs with mdBook 0.5.4: exit 0 (log). A script checked that every relative link between pages resolves.
• Not run: the Pages workflow, which needs Pages enabled and runs only on main.

I did not add an mdbook build step to host CI. The owner's rule forbids any test from referencing the manual, and building mdBook in host CI would add a host tool to every run. The table of contents is checked by the build step on main.

Open decisions for the owner

Where sources disagree, the manual leaves the point out:

1. Scheduling: the manual follows J1 and J2 and the code. issues/cpu-time-is-a-band-and-not-a-reservation.md still plans reservations, and issues/the-fair-band-orders-by-share-alone-and-a-woken-editor-waits.md waits on them. Should both tracks be closed or rejected?
2. RAM wipe after an unexpected reset: the planning notes request it; the 2026-10-03 ruling "Keep crash records" declines it.
3. Machines without an IOMMU: one image-wide policy, or a per-program manifest grant? The manual states only the 2026-09-29 ruling: a shipped driver may claim, and no other.
4. App rights: the package's request intersected with the user's grant and the image's ceiling (2026-09-24), or runtime requests with no permission list (planning notes)? The manual states only the ceiling.
5. Who writes /apps: issues/whether-pkg-alone-writes-apps.md, against the requirement that installed versions are protected.
6. Waits in general: CLAUDE.md's "a wait has a failure timeout" against the planning notes' general report-and-preserve rule. The manual states no general rule. It does carry the specific no-timeout rules that were already recorded design: swap's waits (2026-10-28 swap design), "no timer ends a process" (process-lifecycle track) and no restart because time passed.
7. The desktop as a login session once a greeter exists.
8. Rollback: the loader falls back to the other slot today, and the loader track's stage 5 plans tries and a good flag. That conflicts with the fix-forward policy and the 2026-10-20 decision against automatic fallback. The manual describes refusing an image that fails verification, and neither fallback nor its absence.

🤖 Generated with Claude Code

[Japabu]

Review of #1191 at e42627a (round 1)

Architecture and fit

The structure is right. The requirements are in one part and the design in another, a page per area, built by a small workflow that only publishes from main. The rule that one fact has one home is well placed in root CLAUDE.md. I found no source paths, :: paths, code identifiers, snippets or links into the tree in docs/. Backticks are used only for file-tree names, environment names and command names. book.toml's git-repository-url only adds the repository icon to each page. Net change: +1679/−771. Roughly 1,400 of the added lines are the manual. The deletions are design moved out of CLAUDE.md and eight tracks, plus the 343-line capability record.

The branch has three main problems:

• It copies design out of tracks that still state it, including one track it edits. That breaks rule 4.
• Some pages contradict later owner rulings.
• One deleted track section takes an owner ruling with it and leaves a dangling reference.

Required

1. Rule 4: design is copied, not moved. The manual repeats text from tracks this PR leaves unchanged:

   • docs/src/architecture/boot.md:17-27,62-67 repeats every one of "The owner's bounds" in issues/the-loader-does-only-what-must-precede-the-handover.md:9-19. This PR edits that track (it removes one citation) and still leaves the copy.
   • docs/src/architecture/scheduling.md:11-15 is J1 almost word for word from issues/the-scheduler-and-the-clocks-never-talk.md:56-62.
   • boot.md:29-35,69-76 is the "verified system" list and signed-header design in issues/the-machine-updates-itself-without-ubuntu.md.
   • memory.md's Swap section repeats issues/anonymous-memory-swaps-to-an-encrypted-partition.md:28-35.

   The handoff lists these and others as "trim when next touched". The owner's rule says the design moves rather than being copied. Trim each track that a page now states to its stages, exits and ruling dates, as was done for the eight tracks. The alternative is to leave that area out of the manual for now. In the same way, issues/toyos-supports-thunderbolt-and-usb4.md:15 now restates trust design inside a track, which the new issues/README.md rule forbids. Delete it. It cannot point at the manual.

2. Lost owner ruling and dangling references in trimmed tracks.

   • issues/where-everything-lives.md deleted the 2026-09-26 font ruling: sans-serif and system-ui are Open Sans, monospace is JetBrains Mono, and serif stays empty until a licence-clean face is chosen. docs/src/architecture/files.md keeps only where fonts live. Stage 7 (where-everything-lives.md:56) still says "fontique maps the families above", which now points at nothing.
   • issues/every-program-sees-only-the-files-it-was-given.md:50 "Left of the design above" points at a section that was deleted.

   Put the family assignment in files.md and fix both references.

3. The manual contradicts later owner rulings.

   • Display scope. docs/src/product/desktop.md:10-14 ("one monitor … Multiple monitors, high and variable refresh rates are later goals") and purpose.md:51 ("multiple monitors" deferred) contradict the owner's 2026-10-31 rulings in issues/each-gpu-drives-its-displays-from-a-userland-driver.md:9-15. Those put the display engine in release 1 on both benches, with several outputs, extended or mirrored, high refresh and VRR. The manual follows the 2026-10-18 planning note those rulings replaced.
   • GPU drivers. docs/src/architecture/devices.md:72-76 says "GPU support reuses maintained vendor and upstream components through ToyOS adapters". The same rulings say Intel's driver is ToyOS's own Rust code written from Intel's PRMs, and only AMD adapts AMD's Display Core. Root CLAUDE.md also allows the vendor-component exception only for one device at a time, by owner ruling. The sentence states the exception as a general policy.
   • Rollback. docs/src/architecture/boot.md:37-52 describes automatic fallback to the other slot when the new image "fails to start", with tries and a good flag. docs/src/product/installation.md:44 says "no downgrade or rollback: fixes ship forward". The record on main says "the update policy is fix-forward" (issues/the-block-service-does-not-refuse-the-running-root.md:14-17). The 2026-10-20 owner decision the planning notes record rules out "automatic fallback to an older OS after an activated update fails to boot". So the manual contradicts itself, and this conflict is not among the seven listed. Either state the fix-forward design in boot.md, with refusing a bad signature as verification rather than rollback, or add it to the owner's list and word both pages neutrally.

4. Not neutral where the PR says it is. The description says the manual "leaves the point out or words it neutrally".

   • Waits. overview.md:63-66 states the planning notes' expiry rule as design. Root CLAUDE.md keeps "a wait has a failure timeout". The rule is now split across two homes, and the stricter version has not been ruled. Remove it until the owner rules, or record the ruling and keep one wording, in one place.
   • No-IOMMU machines. trust.md:25-28 lists "DMA on a machine without an IOMMU" among privileges "granted only by the signed image's system manifest, to a program". That is the old per-program-grant side of open decision 3. The owner's 2026-09-29 ruling in issues/a-machine-without-an-iommu-refuses-every-claim.md and trust.md:30-37 describe it per shipped driver. Drop that example from the list.
   • App rights. privacy.md:10 says "There is no mandatory list of permission categories". That takes the planning notes' 2026-10-16 side of open decision 4. Cut it or list it as the owner's choice.

   Scheduling does follow owner decisions J1 and J2, so it is backed. The cpu-time track still contradicts it, which is the owner's item 1.

5. Rule 2: status and transitional facts stated as design.

   • using/building.md:33 "Secure Boot must be off until the verified boot chain exists" is current status, and it contradicts boot.md's verified chain.
   • files.md:61 "per-user overrides come with users" is staging.
   • trust.md:42-44 "until external-device isolation is designed … whose design is open" is status. The ruling is "refuse external, record reflash". State the refusal.
   • storage.md:48 turns LOG as FAT32 into permanent design ("readable on any computer"). The source said "while a Mac has to read the dev stick", and the storage track (:62-64) records folding LOG into DATA in the installed product as deferred by ruling.

6. Rule 3 and rule 4: repetition inside the manual and with CLAUDE.md. Each of these facts has two to four homes:

   • The testing ladder and reproducibility. building.md:38-55 repeats root CLAUDE.md's Testing section ("QEMU establishes order, completion, contents and counts") and purpose.md's Reproducibility, word for word.
   • Prerequisites. "Rust and QEMU are the development prerequisites" now appears in both root CLAUDE.md and building.md:8. The host-tool list belongs to issues/the-build-runs-host-tools-outside-rust-and-qemu.md.
   • Component tables. introduction.md:17-25 "In one paragraph" and services.md's service table repeat the overview's layer diagram and "Who does what" table.
   • The supervisor. That the kernel starts only the supervisor, and that every port exists before any server runs, is said in authority.md, sessions.md, services.md, boot.md and manifest.md.
   • Timers. That no timer ends a process is said in overview.md, sessions.md and services.md.
   • Failure. That a session owner's failure ends at most its own session, and that a contained device may stay unavailable, is said in both sessions.md and services.md, and in devices.md.
   • The page cache. The one page cache is described in both storage.md:80-85 and memory.md.
   • The ABI boundary. The kernel ABI and error boundary are in both kernel.md:55-61 and interface.md.
   • libc and POSIX. Covered in kernel.md, applications.md and interface.md.
   • Desktop toolkit and rendering. iced and CPU rendering are covered in desktop.md, devices.md and applications.md.
   • Boot handover. boot.md:19-27 repeats its own diagram, and storage.md repeats it again.
   • Image-only privileges. manifest.md:40-44 repeats trust.md.

   Give each fact one page and link from the others. That cuts something like 1,000–1,500 of the ~11,500 words, an estimate.

Suggestions

• docs/src/using/commands.md is an inventory of images/system.toml and toybox's applets. Root CLAUDE.md says not to duplicate those inventories, and this list goes stale with every rename. Keep only commands that embody design (launch, pkg, update, swap, logout), or drop the page. The same applies to the toybox and shell-builtin lists. manifest.md's row table mirrors the manifest's keys and will drift with them.
• authority.md, sessions.md, trust.md and boot.md are still mostly paragraphs. The owner asked for lists and small diagrams.
• sessions.md:44 "numeric user ids are deliberately absent" reads against the 2026-10-21 libc identity ruling (issues/libc-answers-uid-0-for-every-process.md). Something like "no numeric id is authority; libc maps the authenticated identity to ids" would fit it.
• boot.md:62-67 presents the firmware-variable floor as the design, while issues/the-anti-rollback-floor-is-a-firmware-variable.md records why it does not meet the same page's "holds against someone with the machine in hand".
• The storage track's dual-boot lines were deleted without a home: ToyOS never writes EFI/Microsoft, and the installer adds one boot entry. Consider one line in installation.md.
• manual.yml: the comment says "from main and nothing else". For a workflow_dispatch on another ref, that rests entirely on the github-pages environment's branch policy. if: github.ref == 'refs/heads/main' on deploy, as nightly.yml does, would put the guarantee in the file.
• reviewer.md:49 restates the CLAUDE.md rule, although the description says the role files only apply it. The text is fine; the description's claim about it is not accurate.
• No PR-time check builds the book, so a broken SUMMARY.md shows up only after merge on main.

Checked and fine

• The workflow. Its triggers are push to main and workflow_dispatch only. There is no pull_request or pull_request_target trigger, so nothing runs for outside PRs or forks. The build job holds only contents: read. The deploy job holds only pages: write and id-token: write. All three actions are pinned by full SHA (checkout is the same SHA as the other workflows). It uses no cache, runs on GitHub-hosted ubuntu-24.04, and installs cargo install mdbook --version 0.5.4 --locked. There is no continue-on-error. The census in build/ci.rs:2034 correctly counts 7.
• Evidence. It is at e42627a. host-ci.log ends "108 step(s), all green", exit=0, including only_a_dispatch_reaches_a_self_hosted_runner. The mdBook install and build both end exit=0. Nothing after the evidence commit changes what it covers.
• The capability record. Its open question 12 is still held by the cpu-time track. The rulings in questions 1–11 are in authority.md. Its two standing rules and the claim-rights inconsistency moved to issues/the-handle-lifecycle-has-no-adversarial-suite.md. I checked that inconsistency against the code: kernel/src/syscall/device.rs:31 (NONE), :62 and :190 (WRITE). abuse_handle_table and handle_lifetime exist. No reference to the deleted record remains.
• Root CLAUDE.md. Nothing points at a removed section. The remaining code pointers (toyos-abi, sdk/toyos, sdk/libc, exempt) are the parts the manual cannot name. The rule-1 references in system/CLAUDE.md and issues/README.md are in instruction files, not code, tests or issue records.

SEND BACK

[Japabu]

Review of #1191 at 6566d58 (round 2, e42627a9f..6566d5895)

Architecture and fit

The round does what round 1 asked for. Design was moved out of the tracks rather than copied, the later owner rulings are followed, and the manual is noticeably tighter. The round changes +566/−789 lines. Against main the branch is +1549/−864. The manual drops from about 11,500 words to 10,057 (wc -w). A scan of every backticked term in docs/src finds only file-tree names, HOME, the home folder names and the command names. There are no :: paths, .rs files, issues/ links or snippets. One new line turns an interim owner refusal into permanent design and contradicts a standing owner requirement. My own round-1 wording invited it.

Round-1 findings

1. Moved, not copied: resolved.

   • Loader track: the bounds list is replaced by a pointer to the 2026-09-28 bounds and the UEFI-bindings ruling. All five bounds are in boot.md:15-22,51-52.
   • Scheduler track: the J1 and J2 statements are gone. scheduling.md:5-31 holds them. The model figures, the stage-4 abuse-rule debt and the remaining stage-3 work stay in the track.
   • Update track: the verified-system list and the header design are gone. Stage 1 now says the loader falls back "today" and that whether this stays is before the owner. That is the right home for the status.
   • Swap track: "What a program sees" is gone, and memory.md:57-83 carries it.
   • GPU track: the rulings are now in desktop.md:11-22 and devices.md:68-75, including the scope, several outputs, high refresh and VRR, the Intel/AMD split, the panic surface and that video and render acceleration are out.
   • Thunderbolt: the "Constraint" line is deleted.

   I found no lost stage, exit or ruling date. Two small details from the trims have no home now; both are under Suggestions.

2. Font ruling and dangling references: resolved. files.md:59-61 carries the 2026-09-26 family assignment. where-everything-lives.md:56 names that ruling, and every-program-sees-only-the-files-it-was-given.md:50 now says "Left of this stage".

3. Later rulings followed: resolved. The display scope matches the 2026-10-31 rulings. purpose.md's deferred list now says "GPU rendering and video acceleration" instead of "multiple monitors". devices.md:72-74 gives the per-vendor ruling instead of a general vendor-component policy. On rollback, boot.md describes refusing an image that fails verification and says nothing about fallback. The fix-forward sentence in installation.md is gone; see the suggestion on "no downgrade".

4. Neutrality: resolved. The general wait-expiry rule is gone from overview.md. trust.md:23-26 no longer lists no-IOMMU DMA as an image grant, and the no-IOMMU section states only the 2026-09-29 ruling. privacy.md:9-10 drops "no mandatory list", and sessions.md:70-71 states only the ceiling, which both sides of item 4 share.

5. Status: resolved. The Secure Boot line in building.md, "come with users" in files.md and the "until … designed" wording in trust.md are gone. storage.md:51-52 now treats LOG as FAT32 on the development stick only, and leaves undecided whether LOG folds into DATA on an installed machine.

6. Repetition: resolved.

   • The introduction's paragraph and the service table are gone.
   • The testing ladder and the prerequisites are gone from building.md.
   • The supervisor's description now lives in services.md, and other pages only name it in diagrams or links.
   • The page cache is in memory.md alone, and storage.md:69 links to it.
   • The ABI and its errors are in interface.md, with a link from kernel.md.
   • POSIX is in applications.md, and interface.md:55 points there.
   • iced is in desktop.md alone.
   • Image-only privileges are in trust.md alone, and manifest.md links to it.

   The overlap that remains is either a one-line pointer or a different fact. For example, sessions.md:49 says no timer ends a process, and services.md:41 says no restart happens because time passed.

Required

1. docs/src/architecture/trust.md:42 — "A device behind an external port is never claimed by a userland driver." The 2026-10-04 "Refuse external, record reflash" ruling holds only until the external-device design is ruled (issues/toyos-supports-thunderbolt-and-usb4.md:9-13). This line states it as the target design. That contradicts the owner's 2026-10-13 requirement that ToyOS supports Thunderbolt and USB4. That track's exit is a tunnelled PCIe function "claimed by a userland driver and its DMA into its grants completes". It also conflicts with the same page's lines 18-19, where external devices are isolated behind the IOMMU, and line 35, "External DMA-capable devices always need isolation", which assumes they are claimed. My round-1 advice to "state the refusal" was wrong: the refusal is status. Delete line 42. Line 35 is the design, and line 43 keeps the reflash limit.

Suggestions

• docs/src/product/installation.md:48-49, "and no downgrade". If this means the user cannot install an older release, it is fine. A reader could also take it as ruling out falling back to the other slot, which is open item 8. The PR body says the manual states "neither fallback nor its absence". Either drop the phrase or have item 8 mention it. (The PR description belongs to the orchestrator.)

• PR body, item 6, "The manual says nothing about it". That is true of the general rule. Still, memory.md:64-66 (a swap wait is reported overdue, and a timeout never turns it into an error), services.md:41 and sessions.md:49 state report-and-preserve for specific waits. Each moved from a track that already stated it: the swap track's 2026-10-28 design and the process-lifecycle track's "No timer ends a process". The owner question would be more accurate if it said those specific rules are already recorded design.

• docs/src/product/desktop.md:42, "for now iced is the one toolkit the platform supports". "For now" is status wording. "In release one" would state the scope.

• Two details from the trims now have no home:

  • The swap track's "O_NONBLOCK does not cover the caller's own buffer".
  • The update track's "a writable ESP is the gap". Only the Secure Boot clause in issues/the-anti-rollback-floor-is-a-firmware-variable.md:19 and "a verified boot chain" as a later stage still record it.

  Neither is a blocker.

On mdbook build in host CI (asked for)

I think the cited rule does not apply: "no code, comment, test or issue record cites" the manual is about coupling to its content, and building the book does not cite anything. mdBook is a Rust host tool, so it raises no host-tool question either. Declining is still reasonable on cost. Every host-CI run would cargo install mdBook with no cache, which takes about a minute (an estimate). Meanwhile a broken SUMMARY.md costs one failed Pages deploy on main and a one-line fix. A cheaper middle ground would be a pull_request trigger with paths: [docs/**] on manual.yml's build job only. deploy is already gated on refs/heads/main, and build holds contents: read and no cache, so this meets the CI security rules. Optional either way.

Checked and fine

• manual.yml now has if: github.ref == 'refs/heads/main' on deploy, and nothing else changed. reviewer.md:49 now points at the root rule instead of restating it.
• Evidence: the evidence README at b881f07 names 6566d58. host-ci-r1.log ends "108 step(s), all green" with exit=0. mdbook-build.log ends with exit=0. The round's changes are docs, issues, one instruction line and one workflow condition, all covered by that run.
• Nothing in docs/ cites code, and no code, test or issue record cites the manual. The pointers in issues/README.md and system/CLAUDE.md are instruction files, as settled in round 1.

SEND BACK

[Japabu]

Orchestrator verification of round 2 (6566d58..9af4ef5), which changes text only:

• The diff touches only five files (+9/-7): four manual pages and one issue record. No code or workflow changes.
• The required finding from The ToyOS manual: the design in docs/, published by GitHub Pages #1191 (comment) is resolved: trust.md no longer says external-port devices are never claimed by a userland driver.
• The suggestions were taken: the downgrade wording, "for now", the homes for the non-blocking-descriptor note and the writable-ESP gap, and the PR body's owner question 6.
• Host CI at 6566d58 still applies, since only text changed after it.

This PR waits for the owner's own review before it is queued.

[Japabu]

The owner approved landing the manual on 2026-11-05: "Land it, I'll read it live." Changes will come as follow-up PRs.