Documentation Site

Site purpose

• capsem.org answers: “Why Capsem, what can I do, and how quickly can I get value?” Marketing owns benefits, use cases, and the short path to value; see /site-marketing.
• docs.capsem.org answers: “Exactly how does this work, how do I operate/integrate/administer it, and what is the contract?” Docs owns precise procedures, behavior, configuration, interfaces, limits, and guarantees.

Diátaxis is the authoring contract

All technical documentation must follow the principles and structure of the Diátaxis Framework. Before drafting or reviewing a page, identify its reader, the question it answers, and exactly one of the four document types below. Its structure and content must serve that type.

Guiding principles

1. Clarity: use simple, clear, unambiguous language. Explain necessary terms for the intended reader; remove internal jargon that adds no value.
2. Accuracy: check commands, code snippets, UI controls, defaults, limits, and guarantees against the current target contracts. Verify examples through the relevant project rails and record what was verified. Never invent output or present an untested example as tested.
3. User-centricity: identify a specific user and the task or need the page serves. That need may be learning a skill, solving a problem, looking up a fact, or understanding a topic; do not force all four into procedures.
4. Consistency: use consistent tone, terminology, names, units, and example conventions across the manual. Keep a stable structure within each type; do not impose the same structure on all four types.

The four document types

Tutorials: choose a reliable path for the learner and make success visible early and throughout. Explain only what they need for the next action; link to deeper explanation and reference. Avoid branches, optional advanced tasks, catalogues of alternatives, and exhaustive flags. A tutorial teaches through doing; it is not a collection of how-tos.

How-to guides: start from the user's problem, not a feature tour. Assume the reader knows the basics and wants a result. Include choices or branches when the real task requires them, with enough guidance to choose. Omit lessons, background discussions, and complete option lists; link to the other types.

Reference: describe accurately, neutrally, and completely within the declared scope. Use consistent fields for syntax, inputs, types, defaults, outputs, errors, constraints, and guarantees where applicable. Examples illustrate usage; they do not become a lesson or a procedural walkthrough. Link to guides for tasks and explanation for rationale.

Explanation: develop understanding of how and why things fit together. Discuss design decisions, trade-offs, boundaries, and alternatives when useful, distinguishing established facts from interpretation. Do not bury installation steps, recipes, or API/CLI inventories in the discussion; link to their owners.

Keep the types distinct. A short definition, illustrative example, or link can support a page's purpose without turning it into a second type. If substantial material belongs to another type, use an existing approved destination or wait for user direction; this framework does not authorize new pages or page splits.

Applying the types to our approved sections

• getting-started/: newcomer tutorials for learning by doing. An installation procedure can be a how-to; classify by reader need, not directory name.
• guides/: task-specific how-to guides, written last as agreed.
• architecture/: explanations of architecture and the security model.
• reference/: CLI, MCP, API, and configuration reference.
• sdk/: an integration subject area, not a fifth document type. Each SDK page must be a tutorial, how-to, reference, or explanation with a distinct purpose; link between those purposes instead of mixing them.

These are the approved section names. Applying Diátaxis does not authorize renaming them, creating more directories, filling TODOs, or adding pages.

Content budget and user direction

Write the minimum content on the minimum number of pages needed to answer those documentation questions completely. Prefer a section in an approved page and links to the canonical explanation over another page or duplicated prose. A feature, subsystem, troubleshooting case, or release does not automatically earn a page. Keep necessary prerequisites, defaults, failure behavior, and security limits; brevity must not make the contract ambiguous.

New pages require explicit user approval before creation. A general request to improve or rebuild docs is not approval for an agent-chosen page list. The user will tell us what to write. Do not proactively propose pages, page lists, outlines, or documentation topics. Follow the user's supplied scope and record page approval in the owning Sprinty item. New categories and page splits follow the same rule. Edit approved pages within their agreed scope without asking again.

Rebuild from scratch

The documentation rebuild starts from reader needs and current product contracts. The old manual is reference material, not the target information architecture or a backlog of stubs to fill.

Capsem 0.7 is the baseline. Architecture and security pages describe the agreed final architecture with the security refactoring complete; verify against those contracts rather than carrying over older behavior.

1. Wait for the user to specify what to write and which pages to create or edit.
2. Keep that requested content on the fewest approved pages, using related sections and canonical links instead of duplicating explanations.
3. Write the requested content afresh from current code, schemas, CLI/API contracts, and verified behavior. Reuse old text only after checking it against those sources; do not carry forward historical commands or claims by default.
4. Review for completeness, duplication, and removable prose. Verify commands, links, and examples with the relevant project skills and bounded rails.

Approval of content or page structure does not itself authorize publication. The replacement manual and its publication were explicitly approved on October 15, 2026.

Publication and development

The user approved publishing the 33-page Capsem 0.7 manual on October 15, 2026. Production astro.config.mjs re-exports astro.preview.config.mjs; both use the approved inventory in approved-docs.mjs. Legacy manual sources remain checked in but are excluded from the collection. The former holding surface is archival.

Use pnpm --dir web/docs run dev for local review and pnpm --dir web/docs run build for the production build and link checks, through the bounded command wrapper. Verify root navigation and changed routes after restarting the server.

ci.yaml owns the merge-blocking docs-build job. Pushes to main run .github/workflows/docs.yaml, build the manual, deploy it to Cloudflare Pages capsem-docs, and smoke the introduction, SDK, installation, and security pages. Verify the deployed content before reporting publication. This deployment is independent from binary and runtime releases; use /release-process for channel publication at release.capsem.org.

Writing and review

Write for the intended reader with the structure of the chosen document type. Start every page with a short introductory paragraph explaining what the page covers and which reader question it answers. Give the reader the overall idea before definitions, implementation details, diagrams, tables, code, or language tabs. This applies to reference and generated pages too. A page title or frontmatter description does not replace the visible introduction.

Use BLUF as a writing principle, not a mandatory format: explain the main idea before supporting detail. Do not add a BLUF heading, a canned summary, or force every opening into the same wording. A concrete sentence such as “This page provides an overview of Capsem's security architecture and how it mitigates risks” is useful orientation; follow it with the specific scope of that page.

Check logical progression across the whole page: introduce the topic before its parts, explain a concept before using it, and put prerequisites and choices before dependent actions. In procedures, show the result before moving to the next step; in reference, order entries by the interface rather than imposing a tutorial. Avoid abstract framing and paragraphs that repeat a diagram or table. Architecture pages use concrete component relationships and a process/role/sandboxing table. Keep one canonical explanation or contract and link to it instead of repeating it. No filler, marketing pitches, or speculative features. Use tables for comparable facts and JointJS diagrams when they clarify relationships.

In tutorials and how-tos, explain necessary options when first used, identify sample names and replaceable values, and say whether commands run on the reader's computer or inside the VM. Complete the requested task: launching a VM must lead to accessing it when the goal is to work in it. Explain capsem suspend as pausing work, capsem resume as returning to it, and capsem fork as duplicating a prepared setup for another use. Keep explanations proportional to the chosen type, with detailed mechanics and rationale in their reference and explanation destinations.

When introducing an interface, explain what it lets the user manage, describe the visible layout, and provide the controls needed to navigate it. For a TUI, include switching between VMs, checking status, opening help, and exiting without stopping the VMs. Do not reduce a multi-VM manager to “an interactive terminal.”

Every single paragraph serves a user action

Every single paragraph must answer a user's question and help the user do something concrete. This applies to every page and document type, including introductions, architecture explanations, reference, transitions, and endings. There is no exemption for background, general explanation, or “useful context.”

For each paragraph, identify both:

1. What question is the user asking here?
2. What can the user do with this answer?

If either answer is missing, delete or rewrite the paragraph. Do not write prose merely to repeat a topic, diagram, or heading, or fill space. An opening that explains scope helps readers decide whether the page answers their question; it is not filler. Explanations must support a concrete user action or decision; reference must help the user configure, call, inspect, or diagnose something. The questions are an editing check, not mandatory question-shaped headings.

Links must state what the user can accomplish at the destination and appear where that task arises. Generic endings such as “For component relationships, read System architecture” or “For exact interfaces, use Reference” fail this rule. Review every single paragraph on the affected page after a correction.

One thing, one name

Use the names exposed by the public command line for its concepts, commands, and options. One thing has one name throughout prose, headings, links, and examples; do not invent synonyms for variety. Write image as in --image and capsem images, then explain what it lets the user do in simple language. When referring to a command, include the executable and format the full name as inline code so it stands out: capsem fork, capsem suspend, capsem resume, capsem create, and capsem shell. Do not shorten command references to bare subcommands such as fork or create.

VM is the environment the user creates, accesses, suspends, resumes, or forks. Do not rename it a project, workspace, container, session, or setup. An image supplies its software; a container image and a VM are distinct things. Use TUI for the terminal interface and Capsem UI for the graphical interface, not “UI app.” Define these interface terms at first use. Keep exact command names and actual control labels when quoting them.

Simplicity, links, and sequence

Keep first-use explanations short and specific to what the reader can do. For example, explain that a name keeps a VM for stop/resume and reuse, then link to the sections on pausing work and duplicating a setup. Explain that --image selects a prebuilt or administrator-authorized custom image, then link to image selection. Preserve these useful capabilities instead of replacing them with vague wording such as “come back later.”

Link at the point where the reader may need more detail: to the relevant section for the next action, to reference for exact options, or to explanation for deeper understanding. Use descriptive link text, verify the destination, and avoid repeating the destination's full content. Do not create a page to supply a link without approval.

For tutorials and how-tos, make the temporal relationship between sections explicit. State the prerequisite or trigger before an action: “Once your VM is created…”, “When you are ready to pause…”, or “After preparing a setup…”. Order dependent actions by when they become possible; identify choices and optional branches as such. Distinguish work on the current VM from decisions made before creating another VM. A heading alone does not communicate this. Do not impose chronological steps on reference or explanation.

Improve the skill with every documentation change

Whenever documentation changes, propose a concise, reusable improvement to this skill based on what the change or user correction taught us. State the proposed rule to the user alongside the work; a generic promise to improve is not a proposal. Apply improvements the user requests or accepts and record them in the owning Sprinty item. Keep proposals about writing rules separate from page/topic proposals, which remain user-directed.

Generalize the lesson rather than accumulating instructions for one sentence. If an existing rule already captures it, propose a clearer rule or a specific review check rather than adding a duplicate. After incorporating a correction, review the whole affected page for the same pattern, not only the cited line.

Review before delivery:

• Every page: does its opening explain the topic and scope before details? Does the main idea come before supporting material, and does each section follow logically from what the reader already knows? Does it answer its description question, use consistent terms, and stay within one type?
• Tutorial: can a newcomer follow the chosen path without guessing and see the promised result at each meaningful step? Are prerequisites, transitions, and links for further detail clear throughout?
• How-to: can the intended user solve the stated problem, including any necessary decisions, without being taken through an unrelated lesson? Is it clear when each action or branch applies and where to find deeper detail?
• Reference: can someone quickly find exact, complete facts for the stated interface or contract without searching through a narrative?
• Explanation: does the reader understand the topic, its relationships and rationale without being diverted into a recipe or interface inventory?

Fix editorial and task gaps before treating a passing build as completion.

Frontmatter

Every doc page must include title and description. Starlight handles lastUpdated from git history automatically. No layout: field -- Starlight provides its own.

The description is always the reader's question that the page answers, phrased as a direct question ending in ?. Keep it specific to the page's scope; do not use a summary, slogan, or imperative. Apply this rule to every new page and whenever an existing page is rewritten.

---
title: Page Title
description: How do I install Capsem on my computer?
sidebar:
  order: 10
---

Approved pages and navigation

After approval, create the agreed Markdown/MDX path under web/docs/src/content/docs/ with the frontmatter above. When Starlight is restored, configure its sidebar in web/docs/astro.config.mjs to match the approved page list; sidebar.order controls order within a section. Do not turn every source directory into a navigation category.

A minor release does not authorize a new release page. Use CHANGELOG.md for release history and update the approved manual where behavior changed. Create a separate release page only when the user requests and approves it.

SDK package documentation

Keep each package's hand-written getting-started document as its README.md, with About, Installation, and Usage sections. State what the reader can do, required versions and service access, then give a small complete example and explain its result. Link to guides for tasks and reference for exact API details using absolute documentation URLs that also work on npm and PyPI.

Use one SDK getting-started page for the shared task, with Python, TypeScript, and Rust examples in language tabs. Symlink package READMEs into the docs source and render them in those tabs rather than copying prose or creating a page per language. Keep real README files inside packages so packaging includes them; site-only title and question-description metadata belong on the shared page. Verify both docs rendering and registry/package Markdown requirements.

Keep first-use examples linear with direct await statements. Avoid async function wrappers, runner boilerplate, and try/finally scaffolding in the lesson; state the execution context and retain necessary lifecycle actions. Detailed error handling and cleanup belong in reference or a task-specific guide. Local onboarding should not ask users to find gateway URLs or copy tokens. Track missing SDK ergonomics as bugs; flag dependent examples as drafts rather than claiming they work before those bugs are fixed. Documentation work does not authorize implementing those SDK fixes. Keep basic examples free of connection setup; use an existing bug or file one for a missing default. Keep explicit remote connection details in reference and integration guides, where the reader needs them.

Link application integration to guides/developers/integrate-the-sdk/, VM configuration to guides/enterprise/configure-a-vm/, and investigation to guides/enterprise/investigate-a-vm/. Keep language API references under sdk/. Inspect AI and the future UI security workflow remain explicit TODOs until their implementations are available. Document only actual export contracts; a body archive export is not a complete telemetry export. Generate API reference separately from public SDK interfaces, types, and docstrings/comments, including hand-written facades as well as generated operations. Do not generate or overwrite the getting-started README, and do not claim a reference exists before it is generated and accessible.

Product entry pages and architecture explanations

Keep the product intro brief: explain what Capsem runs (container images inside isolated Linux VMs), its service model, and the main interactive and SDK-driven uses. Lead next to installation, then task links for those uses. Do not turn an entry page into a component tour or duplicate its architecture diagram.

An intro may include one compact conceptual diagram showing how the reader uses Capsem and what runs inside its isolation boundary. Keep detailed component relationships and process diagrams in the canonical architecture explanation; do not reproduce that tour in the product intro.

Explain the major components, where they run, and how control, requests, and records move between them. Name each component and state its concrete job. Keep detailed permission and sandbox inventories in the security architecture. Put shared prerequisites such as installation before workflow choices. Explain each interface when first introduced, including how the web UI and desktop app relate. Do not present a prerequisite as a parallel alternative to tasks that depend on it. Use top-to-bottom overview diagrams that fit the reading column; do not require horizontal scrolling to understand the overview. Verify the rendered layout, since a vertical arrangement alone does not guarantee a narrow diagram.

Diagrams

Use JointJS Community for new and migrated diagrams, starting with the security architecture. The shared web/diagrams/ package owns the viewer and visual tokens for both sites; documentation definitions live in web/docs/src/lib/. Import the component from an MDX page and pass a diagram definition. Keep the approved route unchanged when converting a Markdown source to MDX, and update approved-docs.mjs to its new source extension.

Preserve all connections, directionality, permission levels, and boundaries when migrating. Give diagrams deliberate layouts, zoom/pan/fit controls, and server-rendered connection tables so the information remains available without JavaScript. Verify label readability and controls on desktop and mobile. Every color used in a diagram must appear in its Legend. Use the shared semantic meanings in web/diagrams/semantics.ts, backed by Tailwind palette tokens; SVG fills and legend swatches must come from those same definitions. Distinct meanings in one diagram use distinct color families, not different shades of one hue. Keep permission levels separate from process and VM boundaries, and verify the expanded Legend after changing a diagram. All published diagrams use this component; archived manual sources retain their old Mermaid text but are excluded from the build. Do not add another renderer or a JointJS+ dependency for a new diagram. Keep external services outside per-VM and processing boundaries, and run tools/test-diagrams.mjs when changing diagram definitions; the docs build includes these boundary checks.

Astro reference

Read references/astro.md for Astro framework patterns (components, content collections, SSR, CLI). From the official Astro team.

Theme

Custom CSS in web/docs/src/styles/custom.css. Accent colors and fonts. Logo at web/docs/src/assets/logo.svg.

Graphics and icons

Source of truth for all icons: web/graphics/.

web/graphics/
  icon/                        Brand icon in multiple sizes and variants
    icon-mainfile.ai           Illustrator source file
    22w/                       22px (menu bar)
    1x/                        726px (standard)
    2x/                        1450px (retina)
    3x/                        2176px
    4x/                        2900px
    1024w/                     1024px (app store, high-res)
    Variants: capsem-logo-{black,color,grey,white}.png
  tauri/                       Pre-built Tauri app icon set
    32x32.png, 128x128.png, 128x128@2x.png
    icon.icns, icon.ico, icon.svg

Site favicons in web/docs/public/ are generated from web/graphics/icon/1024w/capsem-logo-color.png. To regenerate:

sips -z 16 16 web/graphics/icon/1024w/capsem-logo-color.png --out web/docs/public/favicon-16x16.png
sips -z 32 32 web/graphics/icon/1024w/capsem-logo-color.png --out web/docs/public/favicon-32x32.png
sips -z 180 180 web/graphics/icon/1024w/capsem-logo-color.png --out web/docs/public/apple-touch-icon.png
sips -z 192 192 web/graphics/icon/1024w/capsem-logo-color.png --out web/docs/public/android-chrome-192x192.png
sips -z 512 512 web/graphics/icon/1024w/capsem-logo-color.png --out web/docs/public/android-chrome-512x512.png

Keep docs in sync

For rule authoring, put task steps and a few practical examples in a how-to guide; put the complete supported syntax and limits in its reference. Link the architecture explanation to both. Document the product's implemented language subset, not every feature of the upstream CEL or Sigma specification. Separate detection severity from enforcement action, including defaults that affect access.

For requested documentation updates, edit the corresponding approved page and verify it against the owning source contract. Consolidate overlapping explanations and remove obsolete claims within the requested scope. Do not create pages or stubs automatically; the user directs what to write and approves any new page.