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 sketched as the # Future: helpTopics @2 / manPage @3 stubs into a dedicated capability, and gives the self-served web UI an in-system documentation source instead of relying on the externally hosted mdBook site. 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 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:

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

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 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 PageRefs, 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.
• Prior interface sketch and the scope tension this resolves: SystemInfo proposal.

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.