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, ROADMAP.md, WORKPLAN.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.

Status: Partially implemented. The book structure exists and is deployed; this proposal remains the editorial contract for keeping the site navigable and honest about current versus future behavior.

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 ROADMAP.md, WORKPLAN.md, or REVIEW_FINDINGS.md. Those files remain operational planning documents.
  • 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.
  • ROADMAP.md describes long-range stages and visible milestones.
  • WORKPLAN.md tracks the selected milestone and active implementation order.
  • REVIEW_FINDINGS.md tracks open remediation and verification history.
  • docs/capability-model.md is a real architecture reference.
  • docs/proposals/ contains accepted, future, exploratory, and rejected design material.
  • docs/research.md and docs/research/ contain prior-art analysis.
  • docs/*-design.md and inventory files capture targeted design/security decisions.

The weakness is not lack of content. The weakness is lack of a stable reader path and status model.

Site Shape

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

# Summary

[Introduction](index.md)

# Start Here
- [What capOS Is](overview.md)
- [Current Status](status.md)
- [Build, Boot, and Test](build-run-test.md)
- [Repository Map](repo-map.md)

# System Architecture
- [Boot Flow](architecture/boot-flow.md)
- [Process Model](architecture/process-model.md)
- [Capability Model](capability-model.md)
- [Capability Ring](architecture/capability-ring.md)
- [IPC and Endpoints](architecture/ipc-endpoints.md)
- [Userspace Runtime](architecture/userspace-runtime.md)
- [Manifest and Service Startup](architecture/manifest-startup.md)
- [Memory Management](architecture/memory.md)
- [Scheduling](architecture/scheduling.md)

# Security and Verification
- [Trust Boundaries](security/trust-boundaries.md)
- [Verification Workflow](security/verification-workflow.md)
- [Panic Surface Inventory](panic-surface-inventory.md)
- [Trusted Build Inputs](trusted-build-inputs.md)
- [DMA Isolation](dma-isolation-design.md)
- [Authority Accounting](authority-accounting-transfer-design.md)

# Design Proposals
- [Proposal Index](proposals/index.md)
- [Service Architecture](proposals/service-architecture-proposal.md)
- [Storage and Naming](proposals/storage-and-naming-proposal.md)
- [Networking](proposals/networking-proposal.md)
- [Error Handling](proposals/error-handling-proposal.md)
- [Userspace Binaries](proposals/userspace-binaries-proposal.md)
- [Shell](proposals/shell-proposal.md)
- [SMP](proposals/smp-proposal.md)
- [Other Proposals](proposals/other.md)
  - [Security and Verification](proposals/security-and-verification-proposal.md)
  - [mdBook Documentation Site](proposals/mdbook-docs-site-proposal.md)
  - [Go Runtime](proposals/go-runtime-proposal.md)
  - [User Identity and Policy](proposals/user-identity-and-policy-proposal.md)
  - [Cloud Metadata](proposals/cloud-metadata-proposal.md)
  - [Cloud Deployment](proposals/cloud-deployment-proposal.md)
  - [Live Upgrade](proposals/live-upgrade-proposal.md)
  - [GPU Capability](proposals/gpu-capability-proposal.md)
  - [Formal MAC/MIC](proposals/formal-mac-mic-proposal.md)
  - [Browser/WASM](proposals/browser-wasm-proposal.md)
  - [Rejected: Cap'n Proto SQE Envelope](proposals/rejected-capnp-ring-sqe-proposal.md)

# Research
- [Research Index](research.md)
- [seL4](research/sel4.md)
- [Zircon](research/zircon.md)
- [Genode](research/genode.md)
- [Plan 9 and Inferno](research/plan9-inferno.md)
- [EROS, CapROS, Coyotos](research/eros-capros-coyotos.md)
- [LLVM Target](research/llvm-target.md)
- [Cap'n Proto Error Handling](research/capnp-error-handling.md)
- [OS Error Handling](research/os-error-handling.md)
- [IX-on-capOS Hosting](research/ix-on-capos-hosting.md)
- [Out-of-Kernel Scheduling](research/out-of-kernel-scheduling.md)

The exact page list may change during implementation, but the hierarchy should stay stable:

  • Start Here: reader orientation and commands.
  • System Architecture: current implementation, with code maps and invariants.
  • Security and Verification: threat boundaries, validation workflow, and security inventories.
  • Design Proposals: accepted/future/rejected design documents.
  • Research: prior art and its consequences for capOS.

Page Standard

Every architecture page should use this shape:

# Page Title

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

**Status:** Implemented / Partially implemented / Proposal / Research note.

## 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 WORKPLAN or REVIEW_FINDINGS when relevant.

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

Status Vocabulary

Use explicit inline status labels near the top of proposal, research, and architecture pages when the label distinguishes current behavior from future or rejected design, after the lead paragraph:

  • 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.

Avoid status labels on orientation, index, command-reference, and workflow pages where the sidebar section or title already gives the page role. Avoid ambiguous language like “planned” without a stage, dependency, or status label. When a page mixes current and future behavior, split those sections.

Content Rules

  • 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 ROADMAP.md and WORKPLAN.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 first classification:

  • Active or near-term:
    • service architecture
    • storage and naming
    • error handling
    • security and verification
  • Future architecture:
    • networking
    • SMP
    • userspace binaries
    • shell
    • user identity and policy
    • 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.md should remain the top-level research index, but it should gain a short “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, REVIEW_FINDINGS.md, docs/trusted-build-inputs.md, and docs/panic-surface-inventory.md.

Phase 4: Proposal and Research Curation

  • Add docs/proposals/index.md.
  • Add docs/proposals/other.md only if the sidebar would otherwise become too noisy.
  • 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.

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 WORKPLAN.md 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 assumes mdBook because it matches the repo’s Rust toolchain and plain Markdown corpus. A minimal tooling follow-up should add:

  • book.toml
  • make docs
  • make docs-serve
  • optional link checking after the first site build is stable

Do not add a frontend package manager, theme framework, or generated site assets unless the content structure proves insufficient.

Open Questions

  • Should ROADMAP.md, WORKPLAN.md, and REVIEW_FINDINGS.md be included in the mdBook sidebar, or only linked from status.md?
  • 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?

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.