# Proposal: System Manual Capability

A built-in, system-served reference manual: capOS should be able to explain
itself from inside itself. The `Manual` capability serves Unix-style `man`
pages, schema-derived interface manuals, and a man-shaped reference corpus
through three surfaces -- the shell, the self-served web UI, and a typed capnp
API -- without any ambient file access.

**Status:** Phases 1-4 settled. Phase 1 landed
the `Manual` capnp interface, the boot-packaged `ManualCorpus` blob compiled by
`tools/manualc`, the kernel `Manual` cap (`kernel/src/cap/manual.rs`), and the
shell `man`/`apropos` builtins, proven by `make run-system-manual-smoke`. Phase 2
landed the self-served web-UI doc viewer. Phase 3 (schema-derived section-2
DESCRIPTION) was satisfied at Phase 1 and its already-landed contract is now
locked by proofs (see Phasing). Phase 4 (programmatic API + agent export) is
settled with deviation: the `describe @4`/`buildInfo @5`/`topics @2` runtime
support already shipped, so Phase 4 reduces to documenting that contract as
stable and locking the consistency invariants that genuinely hold -- byte
identity between the in-system manual navigation and the published-site
`llms.txt` is infeasible and undesirable (see Phasing). This
proposal promotes the documentation surface that the
[SystemInfo proposal](system-info-proposal.md) sketched as the
`# Future: helpTopics @2 / manPage @3` stubs into a dedicated capability, and
gives the [self-served web UI](remote-session-ui-security-proposal.md) an
in-system documentation source instead of relying on the externally hosted
[mdBook site](mdbook-docs-site-proposal.md).
**Last reviewed:** 2026-05-26 23:17 UTC.

### Phase 1 as-built notes

Two Phase-1 choices refine the original plan and are recorded here so the design
matches the code:

- **Section-2 DESCRIPTION is sourced from `.capnp` doc comments at build time.**
  The schema already carries per-interface doc comments, and `tools/manualc`
  parses the `.capnp` text directly (not the generated bindings), so section-2
  pages take their NAME-line title and DESCRIPTION from the interface doc
  comment and their SYNOPSIS from the parsed methods. This is a pragmatic
  improvement over the originally-planned curated-prose-keyed-by-id: it cannot
  drift from the schema and needs no per-interface prose file. The build check
  therefore requires every interface to carry a non-empty doc comment. Phase 3
  still adds doc-comment *preservation in the generated bindings* for live
  reflection (`describe`), which is a distinct mechanism from build-time text
  parsing.
- **`topics @2` returns a section-based index.** Pages are indexed by manual
  section (Commands, Capabilities, ...). The Phase 2 web-UI viewer renders this
  section-based index in its topic sidebar; replacing it with the curated
  front-matter `topics` taxonomy remains future corpus/build work.
- **`describe @4` is backed by a build-time interfaceId index.** `manualc`
  computes each interface's capnp type id (validated against the generated
  `*_INTERFACE_ID` constants) and emits an id->page-name index in the blob, so
  `describe` resolves an in-tree interface id to its section-2 page today.

## Problem

Today capOS has rich documentation, but none of it is reachable *from a running
capOS instance*. The corpus lives in `docs/` and is rendered by the host-side
mdBook pipeline (`tools/mdbook-doc-metadata/`); a booted system, a shell user,
or the in-guest web UI cannot answer "what does this capability do?" or "how do
I use this command?" without leaving the system. For a research OS whose whole
thesis is that *the typed interface is the contract*, the inability to read
those contracts in-system is a conspicuous gap.

Three concrete pressures motivate a dedicated capability:

- **A public explorer demo needs in-system docs.** The
  [cloud-deployment](cloud-deployment-proposal.md) and self-served web-UI work
  point toward a publicly explorable instance. An explorer who has never seen
  capOS needs to discover capabilities, commands, and concepts from inside the
  UI -- not by alt-tabbing to an external site that may drift from the running
  build.
- **SystemInfo is the wrong home.** The SystemInfo proposal already foresaw
  this and stubbed `helpTopics`/`manPage` methods, while noting the tension:
  documentation would "either squat on `ShellConfig` (wrong scope) or get its
  own one-method cap (proliferation)." SystemInfo is for small system-wide
  *scalars* (MOTD, hostname). Documentation is a *queryable corpus* with
  search, sectioning, and cross-links. Bolting a content/query service onto a
  scalar-info cap is the wrong shape.
- **Schema-as-manual is a capability-native idea worth capturing.** Because
  every capability is a typed Cap'n Proto interface, a capability's reference
  page can be *generated from its own schema*. "The interface IS the permission"
  extends naturally to "the interface IS its own reference page." No other OS
  doc system gets this for free; capOS should not throw it away.

## Design Principle: Ground On `man`, Modernize Navigation

The design is deliberately conservative at its core and ambitious at its edges.

- **The core is `man`.** The proven Unix model -- ordered sections
  (`NAME`, `SYNOPSIS`, `DESCRIPTION`, `OPTIONS`, `ERRORS`, `SEE ALSO`, ...),
  numbered manual *sections by kind*, and `apropos`/`man -k` keyword search --
  is the contract every page honors. The mechanics (`man <name>`,
  `man <section> <name>`, `man -k`) are immediately familiar to anyone who
  knows `man`.
- **The navigation is modern.** On top of the `man` core we layer the
  discovery affordances that make documentation *pleasant*: a topic index
  (reusing the existing front-matter `topics` taxonomy), `tldr`-style
  example-first quick views, hyperlinked `SEE ALSO` cross-references, and an
  agent-readable export. Plan 9's "follow the documentation pointers on demand"
  philosophy -- navigate by need, not by linear reading -- is the model for the
  cross-link graph.

The two are layered, not in tension: the modern surface is a *renderer and
index* over `man`-shaped content, never a replacement for it.

## Manual Sections (the capOS analog of man 1-8)

Classic `man` numbers sections by *kind of thing documented*. Plan 9 keeps the
same idea but splits "devices / file servers / protocol / formats" -- a split
that maps cleanly onto a capability OS, where devices and services *are*
capabilities. The proposed capOS sections:

| Section | Name | Contents |
| --- | --- | --- |
| `1` | Commands | Shell builtins and userspace command binaries (`spawn`, `caps`, `login`, ...). |
| `2` | Capabilities | One page per typed capability interface (`Console`, `Timer`, `ProcessSpawner`, `DMAPool`, ...); SYNOPSIS schema-generated. |
| `3` | Runtime & SDK | `capos-rt` / `libcapos` / `capos-service` APIs available to userspace programs. |
| `5` | Manifests & Schemas | Boot-manifest fields, CUE config, `schema/capos.capnp` structures and their wire contracts. |
| `7` | Concepts | Prose: the capability model, the ring protocol, threading contract, session-bound invocation context. |
| `8` | Operations | Operator/admin surfaces: boot, run targets, remote-session gateway, cloud deployment. |

The section *numbers* diverge from Unix deliberately: Unix `2` is syscalls, but
capOS's whole point is that it has essentially no syscall surface, so `2` is
Capabilities instead. The numbering is capOS-specific and documented in
`intro(7)`; the *mechanics* are unchanged, so the muscle memory transfers.
Section `2` is the capability-native centerpiece -- the part no conventional OS
can auto-generate, because conventional OSes have no machine-readable interface
contract for every resource.

## Interface

```capnp
struct ManPage {
    name       @0 :Text;            # "console", "spawn", "capability-model"
    section    @1 :UInt8;           # 1,2,3,5,7,8 (see section table)
    title      @2 :Text;            # short NAME-line abstract
    body       @3 :Text;            # rendered page text (man-shaped sections)
    seeAlso    @4 :List(PageRef);   # cross-links -> SEE ALSO graph
    examples   @5 :List(Text);      # tldr-style example-first snippets
    source     @6 :Source;          # schemaReflection | prose | runtime
    lastReviewed @7 :Text;          # provenance from doc front matter
    buildId    @8 :Text;            # build/commit id this page was rendered from
}

struct PageRef   { name @0 :Text; section @1 :UInt8; siteOnly @2 :Bool; }
struct Topic     { key @0 :Text; title @1 :Text; pages @2 :List(PageRef); }
struct Apropos   { query @0 :Text; matches @1 :List(PageRef); }

enum Source { schemaReflection @0; prose @1; runtime @2; }

interface Manual {
    # man <name> [section]: fetch a single page.
    page      @0 (name :Text, section :UInt8) -> (page :ManPage);
    # man -k / apropos: keyword search over the prebuilt index.
    apropos   @1 (query :Text) -> (result :Apropos);
    # the modern topic index, reusing the docs front-matter taxonomy.
    topics    @2 () -> (topics :List(Topic));
    # enumerate a section (man -s 2: list all capabilities).
    section   @3 (section :UInt8) -> (pages :List(PageRef));
    # interfaceId -> section-2 page lookup (see note below).
    describe  @4 (interfaceId :UInt64) -> (page :ManPage);
    # the build/commit this manual blob was produced from.
    buildInfo @5 () -> (commit :Text, builtAt :Text);
}
```

`Manual` is **read-only** and holds no authority beyond serving text. Adding
methods later is a Cap'n Proto-compatible change, matching the additive
discipline the SystemInfo and DDF work already follow.

`describe @4` is an `interfaceId -> section-2 page` lookup. It does **not** take
or verify a live capability: the caller passes an interface id it already knows
(capabilities expose `interface_id()` today, see `capos-lib/src/cap_table.rs`),
and the Manual returns that interface's manual page, or not-found for an id it
does not document (it covers only in-tree interfaces). It is the programmatic
complement to section-`2` browsing -- convenient for an SDK or agent that holds
a cap and wants its reference page -- not reflection on the live object.

## Content Model: Man-Shaped Pages, Not Raw Markdown

A `ManPage` is structured text with the conventional ordered sections
(`NAME`/`SYNOPSIS`/`DESCRIPTION`/`SEE ALSO`/...), **not** free-form Markdown.
This is a deliberate, load-bearing choice. The published `docs/` tree is
long-form Markdown -- proposals, architecture prose, mermaid diagrams, mdBook
preprocessor directives -- and is not a man-shaped corpus. The Manual therefore
serves a *purpose-authored, man-shaped corpus* built at `make` time; it is a
distinct artifact, not a verbatim mirror of `docs/*.md`. The guest renders the
fixed section set (terminal pager / web pane) and needs no full Markdown engine.

What this corpus does and does not share with the published mdBook site:

- **Shared:** the taxonomy *provenance* and the schema-derived section-2
  interface membership. The man corpus and the published site are tagged from
  the same front-matter/`topics` vocabulary, so neither invents a category the
  other does not recognize. They do **not** share top-level navigation keys:
  `topics @2` navigates by manual section (Commands, Capabilities, ...), while
  the site's `llms.txt` navigates the full `docs/` tree by `docs/SUMMARY.md`
  section. The in-system index is a curated subset and deliberately diverges
  from the site's navigation (see the Phase 4 settlement under Phasing).
- **Not shared:** the long-form prose body. The manual is concise reference;
  the site is the depth. Concept pages (section `7`) are short man-shaped
  summaries whose `SEE ALSO` points at the fuller site/`docs/` page. The manual
  does not claim to reproduce that long-form content.

This removes the conflation between "reuse the corpus" and "serve man-shaped
sections": the *taxonomy* is reused; the man pages are curated.

### Page provenance (the three sources)

`ManPage.source` records how each page's body was produced:

1. **`schemaReflection` -- interface manuals (section 2/5).** The page
   *structure* is derived from the schema at build time: capnp reflection makes
   method/field *names and signatures* recoverable, so the `SYNOPSIS` (method
   list with ordinals and parameter/return shapes) is generated directly from
   `schema/capos.capnp` from day one and cannot drift from the live interface.
   The `DESCRIPTION` prose comes from `.capnp` **doc comments**. Two
   prerequisites are *not done today* and are tracked as their own tasks (see
   Sequencing): (a) the schema carries almost no doc comments, and (b) the
   no_std generated bindings under `tools/generated/` do not preserve schema
   doc text. Until (a)/(b) land, the generated SYNOPSIS is real but the
   DESCRIPTION falls back to curated prose keyed by interface id. So the
   Phase-1 drift surface is the prose body only -- not the method list -- and a
   build check (below) forbids a missing page.
2. **`prose` -- authored reference (section 1/3/7/8).** Man pages authored in
   the manual corpus for commands, the runtime/SDK, concepts, and operations.
   Curated, man-shaped, taxonomy-tagged.
3. **`runtime` -- live facts (section 8).** A small set of pages interpolate
   live state (current run target, the caller's granted capabilities for
   `caps`/`inspect`), sourced from existing caps such as `SystemInfo`, and are
   marked `Source.runtime` so they are never cached as static.

### Subset rule (what is and isn't in the manual)

The in-system manual ships sections `1`/`2`/`3`/`5` in full plus curated
section-`7`/`8` summaries. It deliberately does **not** carry the long-form
research, proposal, and design corpus -- that stays on the published site. To
keep the boundary legible to an explorer rather than surprising:

- `PageRef.siteOnly` marks topics that exist on the published site but have no
  in-manual page, so `apropos` results distinguish them visibly.
- A concept page whose depth lives on the site ends with an explicit `SEE ALSO`
  link to the fuller site page.
- The subset rule is itself documented in `intro(7)`, and a build check
  classifies every `docs/` page as in-manual, summarized, or site-only so the
  boundary stays explicit as the docs grow.

### Delivery and freshness

The man corpus and generated interface manuals are compiled to a compact,
read-only blob and delivered like the boot manifest -- a boot-packaged payload
read through an offset/length method, mirroring `BootPackageCap`
(`kernel/src/cap/boot_package.rs`). The blob is built at `make` time, so a
given ISO's manuals match that build. **Every page carries the build/commit id
that produced it** (`ManPage.buildId` plus `Manual.buildInfo @5`), so an
explorer of a possibly-drifting public build can always tell which capOS
version they are reading about. A build check fails the build if any in-tree
capability interface lacks a section-`2` page. A future storage-backed `Manual`
service (once persistence exists) can serve a mutable corpus without changing
the capability shape.

## Three Surfaces

All three surfaces are *clients of the same `Manual` capability*. None of them
re-implement documentation; they render `ManPage` values.

### 1. Shell `man` / `apropos`

A `man` builtin (and `apropos` alias for `man -k`) joins the shell's existing
command dispatch (`shell/src/main.rs`, the `match command { ... }` block that
already handles `help`, `caps`, `inspect`, `motd`). It calls `Manual.page` /
`Manual.apropos` on a `Manual` cap held in shell state and paginates the body
to the terminal.

`help`, `man`, and `inspect` stay distinct and complementary:

- `help` remains the terse, cap-free built-in command list for first
  orientation; `help <command>` becomes a shortcut to `man 1 <command>`.
- `man <name>` is the full reference served by the `Manual` cap.
- `man <capability>` complements the existing `inspect <cap>` command:
  `inspect` shows *this instance*, `man` shows *the interface*.

### 2. Self-served web-UI doc viewer (Implemented)

The [self-served web UI](remote-session-ui-security-proposal.md) service
(`demos/remote-session-web-ui/`) already holds capabilities in session state
and exposes them over HTTP routes that return JSON view-models -- raw caps
never reach the browser. A `Manual` cap added to that service backs the routes
`/api/man?name=&section=`, `/api/apropos?q=`, and `/api/topics`, and a viewer
page renders pages with a topic sidebar, a search box (`apropos`), and clickable
`SEE ALSO` links. This is the surface that makes a public explorer demo
self-explanatory: a viewer can browse the capability catalog and
concept pages with no shell and no external site.

As-built notes:

- The `Manual` cap is granted to the web-UI service via the manifest
  (`{kernel: "manual"}`), looked up from the service CapSet alongside
  `console`/`sessions`/`broker`, and never crosses to the browser; only the
  rendered JSON view-models do. The doc routes are read-only and require no
  login, since `Manual` confers no authority beyond documentation access.
- The viewer is served as a separate `/manual` page, distinct from the
  login-proof page on `/`, so the session-proof leak assertions on `/` stay
  whole-body while the manual page may legitimately display capability
  interface names as documentation text.
- `SEE ALSO` and topic refs are rendered from the structured `seeAlso`/`pages`
  `PageRef` lists (not by re-parsing body text). `siteOnly` refs link out to
  the published site in a new tab; in-manual refs navigate in-system. The
  Phase 1 corpus builder currently emits only in-manual refs (`siteOnly` is
  always false); the viewer's `siteOnly` path is proven against the shipped
  ref-classifier, and wiring real `siteOnly` refs is follow-on corpus authoring.
- The topic sidebar lists the section-based `topics @2` index (Commands,
  Capabilities, ...); the front-matter taxonomy-backed index remains future work.
- Proof: `make run-remote-session-self-served-web-ui` drives a headless browser
  that logs in, renders `console(2)` with its `source`/`buildId` provenance,
  searches `apropos timer`, and asserts the `siteOnly`-vs-in-manual link
  classifier -- without leaking any raw cap or session internals to the browser.

### 3. Programmatic capnp API

Because `Manual` is an ordinary capability, any process or agent granted it can
fetch documentation programmatically -- an SDK can surface inline help, and an
in-system agent can ground itself on the real interface contracts. `describe @4`
resolves a held interface id to its section-2 page, `topics @2` returns the
navigation taxonomy, and `buildInfo @5` (plus each page's `buildId`) tells an
agent exactly which capOS build it is reading about. Agents get one
machine-readable index of everything *the running system* documents: the
man-shaped subset, navigated by manual section. That subset is a curated
projection of the published site rather than a byte-identical copy of its
`llms.txt` navigation -- the in-system manual and the published full-tree index
deliberately differ in scope (see the Phase 4 settlement under Phasing), and the
invariant that holds is shared *taxonomy provenance*, not identical keys.

## Navigation and Discovery (making it great)

The features that lift this above a flat page dump, all riding on the `man`
core:

- **Topic index over `apropos`.** `topics @2` exposes the curated front-matter
  taxonomy; `apropos @1` does free-text keyword fallback against a keyword
  index built into the blob at `make` time (NAME lines + tagged keywords), not
  a linear scan of page bodies. A reader navigates by topic when they know the
  area and by keyword when they do not.
- **`SEE ALSO` as a real graph.** `ManPage.seeAlso` is structured `PageRef`s,
  not prose, so every surface renders them as links and an explorer can walk
  the concept graph -- the Plan 9 "pointers on demand" model. `siteOnly` refs
  link out to the published site.
- **Example-first quick views.** `ManPage.examples` carries `tldr`-style
  snippets so the common case ("how do I actually use `spawn`?") is answered in
  five lines before the full DESCRIPTION.
- **Provenance is visible.** `source`, `lastReviewed`, and `buildId` travel
  with every page, so a reader can tell an auto-generated interface manual from
  curated prose and see which build it describes.

## Authority and Security Model

- **Read-only, no ambient authority.** `Manual` only returns text. Holding it
  grants nothing but the ability to read documentation; it cannot mutate state
  or widen any other authority. Documentation access is itself a capability,
  consistent with Principle 1 (no ambient authority).
- **Scoped distribution.** The web-UI service and operator shells receive
  `Manual` via manifest cap grants or the `AuthorityBroker` bundle, exactly as
  `SystemInfo` is distributed today. A public/anonymous web session can be
  granted a `Manual` with no risk, because it confers no authority.
- **Browser boundary unchanged.** As with all web-UI routes, the browser
  receives only rendered `ManPage` JSON view-models; the `Manual` cap never
  crosses into browser JavaScript.
- **No code execution.** Pages are structured text rendered by the viewer. The
  Manual never serves executable content, so an explorable public instance does
  not gain a new code path from documentation serving.

## Phasing

1. **Phase 1 -- capability + shell `man`. (Implemented.)** Defined the `Manual`
   interface, authored the man-shaped corpus, delivered the boot-packaged blob,
   implemented `page`/`apropos`/`topics`/`section`/`describe`/`buildInfo`,
   stamped every page with the build/commit id, added the build check that
   forbids a missing section-`2` page, and added the shell `man`/`apropos`
   builtins. Section-`2` SYNOPSIS is schema-generated; section-`2` DESCRIPTION
   is sourced from `.capnp` doc comments at build time (see Phase 1 as-built
   notes); sections `1`/`7` ship authored prose. Proof:
   `make run-system-manual-smoke`.
2. **Phase 2 -- web-UI viewer. (Implemented.)** Added `Manual` to the
   self-served web-UI service and shipped the viewer page (topic sidebar,
   `apropos` search, page provenance, and clickable `SEE ALSO` links with
   `siteOnly` external linking). This is the public-explorer-facing milestone.
   Proof: `make run-remote-session-self-served-web-ui`.
3. **Phase 3 -- schema-derived section-2 DESCRIPTION. (Satisfied at Phase 1;
   proofs hardened.)** The Phase-1 corpus builder already auto-generates the
   section-`2` DESCRIPTION (and the per-method SYNOPSIS docs) from `.capnp` doc
   comments and backs `describe @4` with a build-time interfaceId->page index,
   so the prose-drift window the original Phase-3 plan targeted is already
   closed. Phase 3 therefore reduces to locking and proving that already-landed
   contract, with two deliberate deviations from the original plan:
   - **Fail-closed over warn-and-fallback.** The build check *fails* when an
     interface lacks a doc comment (`manualc` `enforce_coverage`), rather than
     falling back to curated prose with a warning. Fail-closed keeps the served
     pages provably schema-sourced and is the reviewed Phase-1 choice; it is
     kept, not regressed.
   - **No live runtime reflection.** The prerequisite binding-preservation task
     emits doc text as Rust `///` attributes, which are not runtime-accessible
     data, and the kernel cannot introspect interface docs at call time. Live
     reflection in `describe` is neither feasible at the current `capnp` version
     nor necessary: `manualc` reparses the live schema each build and
     `make generated-code-check` enforces schema<->binding parity, so the served
     signatures and DESCRIPTION cannot drift from `schema/capos.capnp`.

   Proofs: a `manualc` host test
   (`describe_index_resolves_to_schema_derived_section2_pages`) asserts that for
   every shipped interface the `describe @4` descriptor resolves to the same
   schema-derived section-`2` page `page @0` serves, with the doc comment in the
   DESCRIPTION body; `make run-system-manual-smoke` asserts the served Console
   DESCRIPTION body and a method-doc line both originate from doc-comment text.
   Open follow-up: `describe @4` has no userspace client today (the shell `man`
   builtin and `ManualClient` use `page @0`), so a runtime `describe` exerciser
   would need a `ManualClient::describe_wait` plus a caller (out of this slice's
   `tools/` + `kernel/src/cap/manual.rs` scope).
4. **Phase 4 -- programmatic API + agent export. (Settled with deviation.)**
   The programmatic surface this phase set out to stabilize -- `describe @4`
   (interfaceId -> section-2 page), `buildInfo @5` (build/commit provenance),
   and `topics @2` (navigation taxonomy) -- already shipped at Phase 1 with
   kernel dispatch (`kernel/src/cap/manual.rs`) and `ManualClient` methods
   (`capos-rt/src/client.rs`). Phase 4 therefore reduces to declaring that
   contract stable for SDK/agent consumers and locking the consistency
   invariants that genuinely hold, with one deliberate deviation from the
   original "unify ... so they share one source" framing:

   - **`describe @4`/`buildInfo @5` are stable programmatic API.** `describe @4`
     is the id-keyed complement to section-2 browsing (it takes an interface id
     the caller already holds; it does not reflect on a live object) and
     resolves through the build-time descriptor index `manualc` emits.
     `buildInfo @5` returns the corpus commit, and every page carries that same
     commit as its `buildId`, so an agent grounding itself on a possibly-drifting
     public build can always resolve which capOS build any page describes. These
     are additive, read-only methods; widening them later stays Cap'n
     Proto-compatible.
   - **Deviation: byte-identical navigation keys / a single source pass are
     infeasible and undesirable.** The original plan called for the in-system
     `topics @2` list to be *identical* to the published `llms.txt` navigation
     keys, emitted from one source pass. That contradicts the reviewed subset
     rule: the in-system manual is the man-shaped *subset* navigated by manual
     section (`topics @2` keys `commands`/`capabilities`/`runtime-sdk`/
     `manifests-schemas`/`concepts`/`operations`), while the published
     `llms.txt` indexes the *full* `docs/` tree navigated by `docs/SUMMARY.md`
     site sections (`Start Here`/`Runnable Demos`/`System Architecture`/...).
     The two key sets are deliberately disjoint and cover different content
     scopes; forcing identity would either shrink the published agent index to
     the man subset or replace the manual's section navigation, regressing a
     shipped, asserted artifact. The two artifacts are also produced by separate
     compilers in separate languages with separate inputs (`tools/manualc`, a
     Rust capnp-blob compiler reading `schema/capos.capnp` + `docs/manual/`; and
     `tools/mdbook-doc-metadata/generate-llms-txt.js`, a Node site generator
     reading `docs/SUMMARY.md` + page front matter), so a literal single pass is
     a re-architecture, not a documentation slice.
   - **What is delivered instead: the shared invariants that cannot diverge are
     locked.** The genuinely shared dimension is the front-matter/`topics`
     taxonomy *provenance* and the schema-derived section-2 interface membership,
     not the top-level navigation keys. A `manualc` host test
     (`topics_taxonomy_is_canonical_and_stable`) pins the served `topics @2`
     taxonomy to its canonical key/title/section/order projection so the
     navigation cannot silently drift, and `build_info_commit_grounds_every_page`
     proves the `buildInfo @5` round-trip stamps every page with the corpus
     commit.

   Proofs: the two `manualc` host tests above; `make run-system-manual-smoke`
   asserts `buildInfo @5` grounds pages of *both* provenance kinds (the
   schema-derived `console(2)` and the authored `spawn(1)`) with one consistent,
   non-placeholder build id. Open follow-up: a true single-source agent export
   shared with the published `llms.txt` would require reconciling the subset rule
   (a documented man-subset projection of the site taxonomy) plus schema,
   Makefile, corpus, and kernel scope beyond this slice's `tools/` + proposal
   surface; and `describe @4`/`topics @2` still have no shell exerciser (the
   shell `man`/`apropos` builtins use `page @0`/`apropos @1`), carried from the
   Phase 3 follow-up.

## Sequencing and Priority

Recording this design now is cheap and the public-explorer angle is real, but
Phase 1 *implementation* competes with foundational work. capOS does not yet
have persistence, a userspace network stack, or the DDF Task-5 userspace device
authority gate closed. Phase 1 (capability + boot-packaged corpus + shell
`man`) is buildable on current infrastructure and does not depend on those
gates; Phase 2 depends only on the already-implemented self-served web UI.
Unless a public demo is imminent, sequence Phase 1 behind the foundational
milestones on the priority ladder rather than ahead of them. The schema
doc-comment authoring and binding-preservation prerequisites (Phase 3) can
proceed independently and are worth doing regardless, because they also improve
review and the published interface docs.

## Relationship to Existing Proposals

- **SystemInfo proposal:** retire the `# Future: helpTopics @2 / manPage @3`
  stubs there in favor of this capability; SystemInfo stays scalar
  (MOTD/hostname/host metadata). That proposal's front matter and interface
  comment should be updated to point here when this lands.
- **mdBook documentation-site proposal:** complementary, not competing. mdBook
  remains the *host-rendered public site* (the long-form depth); `Manual` is the
  *in-system* concise reference. They share the front-matter/topics taxonomy
  provenance, so navigation cannot drift on the *taxonomy* it is drawn from. They
  do **not** share top-level navigation keys: the site's `llms.txt` indexes the
  full `docs/` tree by `docs/SUMMARY.md` section, while `topics @2` indexes the
  man-shaped subset by manual section. The Phase-4 agent export is the in-system
  manual's own machine-readable index of that subset, not a copy of the site's
  `llms.txt` (see the Phase 4 settlement under Phasing).
- **Remote-session UI security proposal:** the web-UI viewer inherits its
  view-model and browser-boundary rules; this proposal adds no new
  authority-bearing route.
- **Interactive command surfaces proposal:** a future typed `CommandSession`
  could host a richer in-shell pager for `man`, but Phase 1 uses the existing
  line-based terminal write path.
- **Cloud deployment / public-release boundaries:** in-system docs are a
  prerequisite for a self-explanatory public explorer demo; this proposal is
  the documentation half of that story.

## Open Questions

- **Subset boundary precision.** The subset rule (sections `1/2/3/5` full,
  `7/8` summaries, long-form on the site) needs a concrete inclusion list, and
  the build check that classifies each `docs/` page as in-manual / summarized /
  site-only must be authored so the boundary stays legible as docs grow.
- **Schema doc-comment authoring.** Section-`2` DESCRIPTION quality (Phase 3)
  depends on writing real doc comments across `schema/capos.capnp`; that
  authoring is its own tracked work and gates the auto-generated path. A
  REVIEW.md rule now requires doc comments on new/changed interfaces so the gap
  does not regrow.
- **Structured page schema.** Whether man sections are a fixed set of typed
  fields or a single tagged-text body; leaning toward a small fixed set so both
  renderers stay trivial.

## Design Grounding

- Capability dispatch and `interface_id()`: `capos-lib/src/cap_table.rs`;
  boot-packaged read-only blob pattern: `kernel/src/cap/boot_package.rs`.
- Shell command dispatch for the `man` builtin: `shell/src/main.rs`.
- Web-UI cap-holding + view-model boundary: `demos/remote-session-web-ui/`.
- Front-matter / topics taxonomy reused for `topics`:
  `tools/mdbook-doc-metadata/` and [mdBook proposal](mdbook-docs-site-proposal.md).
- Prior interface sketch and the scope tension this resolves:
  [SystemInfo proposal](system-info-proposal.md).

## Relevant Research

- Unix manual conventions and section ordering -- `man-pages(7)`.
- Plan 9's section split (commands / devices / file servers / protocol /
  formats) and "follow the documentation pointers on demand" navigation model,
  which motivate the capability-section mapping and the `SEE ALSO` graph
  (`docs/research/` Plan 9 report).
- Cap'n Proto runtime reflection (`RawStructSchema` / dynamic schema), the basis
  for schema-derived section-`2` SYNOPSIS and DESCRIPTION.
- Modern discovery affordances -- `tldr`/`apropos`/topic indexes -- adopted as a
  navigation layer over, not a replacement for, the `man` core.