Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Proposal: mdBook Documentation Site

Turn the existing Markdown documentation into a navigable mdBook site that explains capOS as a working system, while keeping proposals and research as deep reference material.

The current docs are useful for agents and maintainers who already know what they are looking for. They are weaker as a reader path: a new contributor has to jump between README.md, docs/roadmap.md, docs/tasks/README.md, proposal files, research reports, and source code before they can form an accurate model of the system. The mdBook site should fix that by adding a concise, current system manual above the existing archive.

Goals

  • Make the first reading path obvious: what capOS is, how to build it, what works today, and where the important subsystems live.
  • Separate implemented behavior from future design, rejected ideas, and research background.
  • Preserve existing long-form proposal and research documents instead of rewriting them prematurely.
  • Give architecture pages a repeatable structure so future edits do not turn into ad hoc status notes.
  • Make validation visible: each architecture page should name the host tests, QEMU smokes, fuzz targets, Kani proofs, Loom models, or manual checks that support its claims.
  • Keep the docs useful from a local clone, without requiring hosted services, databases, or custom frontend code.

Non-Goals

  • Replacing docs/tasks/README.md. Task records remain operational planning documents; REVIEW_FINDINGS.md is only a tombstone for older links, and docs/roadmap.md is now part of the book while still owning long-range planning.
  • Turning proposals into user manuals by bulk editing every existing document. Long proposal files stay as references until a subsystem needs a targeted refresh.
  • Building a marketing site, blog, changelog, or public product page.
  • Adding MDX, React, Vue, custom components, or a JavaScript application layer.
  • Automatically generating API reference documentation from Rust or Cap’n Proto. That can be evaluated later as a separate documentation track.

Audience

The site should serve three readers:

  • New contributor: wants to build the ISO, boot QEMU, understand the current architecture, and find the right files to edit.
  • Reviewer: wants to verify whether a change preserves the intended ownership, authority, lifecycle, and validation rules.
  • Future agent: wants current project context without having to infer the system from stale proposals or source code alone.

The primary audience is maintainers and agents, not end users. This matters: accuracy, status labels, and code maps are more important than a polished external landing page.

Current State

The repository already has a substantial Markdown corpus:

  • README.md explains the project and core commands.
  • docs/roadmap.md describes long-range stages and visible milestones.
  • docs/tasks/state.toml tracks the selected milestone.
  • docs/tasks/state.toml tracks the selected milestone; task records under docs/tasks/ track active implementation order.
  • docs/tasks/** tracks open remediation, review-finding work, and verification history.
  • docs/capability-model.md is a real architecture reference.
  • docs/proposals/ contains accepted, future, exploratory, and rejected design material.
  • docs/research/ contains prior-art analysis (the capability-systems-survey.md synthesis plus per-system deep-dive reports).
  • docs/*-design.md and inventory files capture targeted design/security decisions.

The weakness is not lack of content. The weakness is keeping the current manual visibly separate from archival planning, proposal, and research material.

Site Shape

The mdBook site should be structured as a book, not as a mirror of the file tree. The current hierarchy is:

  • Start Here: reader orientation and commands.
  • Runnable Demos: current user-visible proofs.
  • System Architecture: current implementation, with code maps and invariants.
  • Security and Verification: threat boundaries, validation workflow, and security inventories.
  • Planning: roadmap, changelog, and backlog links.
  • Design Archive: proposal index plus nested active, future, and rejected long-form design documents.
  • Research Archive: research index plus nested prior-art reports.

All proposal and research files should remain reachable through the sidebar so mdBook builds them, but they should be nested under their indexes rather than listed as peer pages beside the current system manual. Sidebar folding should be enabled so the default reader path stays compact.

Page Standard

Every architecture page should use this shape:

---
status: "Partially implemented."
last_reviewed: "2026-04-27 10:00 UTC"
description: "Page description."
topics:
  - { key: "capabilities-ipc-and-authority", reason: "Explains authority or invocation behavior." }
---

# Page Title

What problem this subsystem solves and why a reader should care.

The preprocessor strips front matter from rendered page content and uses the metadata to regenerate docs/topics.md. A post-build agent asset pass patches final rendered HTML so status, description, and last_reviewed appear as page-head metadata without adding visible status blocks to each page. The same pass adds HTML head discovery links for llms.txt and each page’s Markdown mirror.

The docs build also emits agent-facing static assets in target/docs-site: llms.txt, Markdown source mirrors for pages listed in docs/SUMMARY.md, sitemap.xml, robots.txt, and a Cloudflare Pages _headers file with discovery links. robots.txt includes a comment pointing agents to llms.txt; crawler rules stay in standard User-agent, Allow, Disallow, Sitemap, and Content-Signal fields.

Current Behavior

What exists in the repo today.

Design

How it works, with concrete data flow.

Invariants

Security, lifetime, ownership, ordering, or failure rules.

Code Map

Important files and entry points.

Validation

Relevant host tests, QEMU smokes, fuzz/Kani/Loom checks.

Open Work

Concrete known gaps, linked to task ledger records when relevant.


Architecture pages should normally stay between 100 and 300 lines. Longer
background belongs in proposals or research reports.

## Status Vocabulary

Use explicit status labels only where a reader could reasonably confuse
implemented behavior, accepted design, future design, or rejected material.
Status belongs on the page itself only when the page role is not already
obvious from the page type or nearby index. Put this information in YAML front
matter (`status`, `last_reviewed`, `topics`) as the first block in the file.

Canonical page-level form:

```md
---
status: "Partially implemented."
last_reviewed: "2026-04-25 11:36 UTC"
description: "Canonical page-level metadata layout."
topics:
  - { key: "capabilities-ipc-and-authority", reason: "Describes authority and invocation behavior." }
---

last_reviewed is hand-maintained and uses the same minute-precision, timezone-aware format as status updates in docs/tasks/README.md, docs/roadmap.md, and task records. Get it from date '+%Y-%m-%d %H:%M %Z'; do not infer or round from memory. Use this field for substantial content edits that should reset a reader’s trust.

Use one of these labels:

  • Implemented: behavior exists in the mainline code and has validation.
  • Partially implemented: some behavior exists, but the page also describes missing work.
  • Accepted design: intended direction, not fully implemented.
  • Future design: plausible direction, not selected for near-term work.
  • Rejected: explicitly not the chosen direction.
  • Research note: background used to inform design, not a direct plan.

Add a page-level status label to:

  • proposal pages whose content could be mistaken for current behavior
  • architecture or design pages that mix implemented facts with future or partial behavior
  • design-gate documents whose role is to define an accepted implementation contract before the implementation is complete
  • research pages that would otherwise read like selected design rather than background

Do not add a page-level status label to:

  • orientation, index, command-reference, and workflow pages where the page type already makes the role obvious
  • reader-orientation overview pages whose role is to explain why the design looks the way it does (design bets, project framing) rather than catalogue what is implemented. These pages must point at status.md or the relevant architecture page for implementation state; a mixed “Partially implemented” label on them is misleading because each bullet it covers has its own, different status
  • status summary pages that already classify other documents
  • pages whose content is purely operational and only describes current, validated behavior

When only one section differs from the rest of the page, keep the page-level status for the dominant role of the document and add a local sentence in that section such as Current implementation status: or Current status:. Do not replace the page-level label with timestamped prose unless the timestamp itself is the point.

Avoid ambiguous language like “planned” without a stage, dependency, or status label. When a page mixes current and future behavior heavily, split those sections instead of relying on status text alone.

Content Rules

The docs-scoped authoring contract lives in docs/AGENTS.md; the rules below extend it with site-shape conventions specific to the mdBook manual. Apply the AGENTS.md rules first when editing any file under docs/, then layer the site-shape rules from this proposal.

  • Start with operational facts, not motivation.
  • Prefer concrete nouns: process, cap table, ring, endpoint, manifest, init, QEMU smoke.
  • Name source files when a claim depends on implementation.
  • State authority and ownership rules explicitly.
  • State failure behavior explicitly.
  • Link to proposals and research instead of duplicating long rationale.
  • Keep docs/roadmap.md and docs/tasks/README.md as planning sources, not as content to paste into the book.
  • Do not describe behavior as implemented unless validation exists or the code map makes the claim directly checkable.
  • Do not bury current limitations at the bottom of a long proposal.

Proposal Index

docs/proposals/index.md should classify proposal files instead of listing them alphabetically. A useful classification:

  • Active or near-term:
    • service architecture
    • service object capabilities
    • storage and naming
    • error handling
    • security and verification
    • SMP
    • Ring v2 for full SMP
  • Future architecture:
    • networking
    • userspace binaries
    • shell
    • SSH shell gateway
    • boot to shell
    • user identity and policy
    • cryptography and key management
    • certificates and TLS
    • OIDC and OAuth2
    • volume encryption
    • cloud metadata
    • cloud deployment
    • live upgrade
    • GPU capability
    • formal MAC/MIC
    • browser/WASM
  • Rejected or superseded:
    • rejected Cap’n Proto ring SQE envelope

Each proposal entry should have a one-sentence purpose and a status label.

Research Index

docs/research/index.md is the top-level research index, and the capability/microkernel survey lives at docs/research/capability-systems-survey.md with a “Design consequences for capOS” section near the top. Readers should not need to read every long report to learn which ideas were accepted.

Each long research report should eventually end with:

## Used By

- Architecture or proposal page that relies on this research.
- Concrete design decision influenced by this report.

Diagrams

Use Mermaid only where it clarifies flow or authority:

  • boot flow: firmware, Limine, kernel, manifest, init
  • capability ring: SQE submission, cap_enter, CQE completion
  • endpoint IPC: client CALL, server RECV, server RETURN
  • manifest startup: boot package, init, ProcessSpawner, child caps

Avoid diagrams that duplicate file layout or become stale when a function is renamed. Every diagram should have nearby text that states the same key invariant in prose.

Migration Plan

Phase 1: Skeleton and Reader Path

  • Add book.toml with docs as the source directory and output under target/docs-site.
  • Add docs/SUMMARY.md.
  • Add docs/index.md.
  • Add docs/overview.md.
  • Add docs/status.md.
  • Add docs/build-run-test.md.
  • Add docs/repo-map.md.

Acceptance criteria:

  • mdbook build succeeds.
  • The first section explains what capOS is, how to build it, how to boot it, and where to find the major code areas.
  • Existing proposal and research files are reachable through the sidebar.

Phase 2: Current Architecture Pages

  • Add the first architecture pages:
    • boot flow
    • process model
    • capability ring
    • IPC and endpoints
    • userspace runtime
    • manifest and service startup
    • memory management
    • scheduling
  • Keep docs/capability-model.md as a first-class architecture page.

Acceptance criteria:

  • Each architecture page has status, current behavior, invariants, code map, validation, and open work.
  • Each page distinguishes implemented behavior from future design.
  • At least boot flow, capability ring, IPC, and manifest startup include a concise Mermaid diagram.

Phase 3: Security and Verification Pages

  • Add docs/security/trust-boundaries.md.
  • Add docs/security/verification-workflow.md.
  • Link existing inventories and designs from the security section.
  • Make each security page name the relevant validation commands and review documents.

Acceptance criteria:

  • A reviewer can find the hostile-input boundaries, trusted inputs, and verification workflow without reading all proposals.
  • The security section links to REVIEW.md, docs/tasks/README.md, docs/trusted-build-inputs.md, and docs/panic-surface-inventory.md.

Phase 4: Proposal and Research Curation

  • Add docs/proposals/index.md.
  • Keep proposal and research documents reachable through SUMMARY.md, but nest them under archive groups so they do not dominate the default sidebar.
  • Add status labels to proposal files as they are touched.
  • Add “Used By” sections to research files incrementally.

Acceptance criteria:

  • Proposal status is visible before a reader opens a long document.
  • Rejected and future proposals are not confused with implemented behavior.
  • Research pages point back to the architecture or proposal pages they influence.
  • The default sidebar presents the current manual before backlog, proposal, and research archives.

Maintenance Rules

  • When implementation changes a subsystem, update the corresponding architecture page in the same change when the page would otherwise become misleading.
  • When a proposal is accepted, rejected, or partially implemented, update its status and the proposal index.
  • When docs/tasks/state.toml changes the selected milestone, update docs/status.md only if the public current-system summary changes. Do not mirror every operational task into the docs site.
  • When validation commands change, update docs/build-run-test.md and the affected architecture page.

Tooling Follow-Up

The content proposal continues to assume mdBook because it matches the repo’s Rust toolchain and plain Markdown corpus. The current tooling baseline is:

  • book.toml
  • make docs
  • make docs-serve
  • make cloudflare-pages-build
  • pinned mdbook and mdbook-mermaid downloads in Makefile, with version and SHA-256 inputs catalogued in docs/trusted-build-inputs.md under the mdBook documentation tools row. make docs and make cloudflare-pages-build verify those checksums and the executable versions before rendering the book, and mdbook-mermaid supplies the pinned mermaid.min.js browser bundle used by both mdBook HTML rendering and docs-PDF Mermaid rasterization
  • a small local stylesheet for readability and sidebar spacing

Do not add a frontend package manager, theme framework, or generated site assets unless the content structure proves insufficient. If mdBook becomes too limited after the sidebar, index, metadata, and styling cleanup, the preferred replacement candidate is Astro Starlight because it supports Markdown/MDX, content collections, structured sidebars, built-in docs components, and static Cloudflare Pages output. Docusaurus is better only if versioned public docs, blogging, and a larger external project site become requirements. VitePress is reasonable only if the project wants Vue-oriented customization.

Open Questions

  • Should docs/tasks/README.md remain outside the book and linked from status.md, or should redacted public summaries be generated later?
  • Should long proposal files keep their current filenames, or should accepted designs eventually move from docs/proposals/ into docs/architecture/?
  • Should docs/status.md be manually maintained, or generated from a smaller checked-in status data file later?
  • Should Cap’n Proto schema documentation be generated into the book once the interface surface stabilizes?
  • Should proposal and research indexes eventually be generated from structured frontmatter instead of hand-maintained Markdown tables?

The first implementation commit should be deliberately small:

  1. Add mdBook config.
  2. Add SUMMARY.md.
  3. Add the Start Here pages.
  4. Link existing proposal and research files without rewriting them.
  5. Verify mdbook build.

That gives the project a usable docs site quickly, without blocking on a full architecture rewrite.