Status: agreed 2026-09-24; steps 1-5 of the migration are implemented.
Supersedes the OSS side of dekit-web/design/docs-system.md (draft of
2026-08-30); the website side of that draft still applies except where
"Website" below says otherwise.
One documentation tree in this repo covers everything a user or an agent
can touch: the CLI, dekit.yaml and the user config, the JS API, the
target grammar, runners and kernels, and (hidden for now) the RPC
protocol. The same sources reach four surfaces:
dekit help [topic]in the binary: rendered for a terminal, plain markdown when piped (agents), JSON with--json.- dekit.run/docs, rendered by dekit-web from JSON the binary exports.
- later, a help pager inside the console TUI.
- later, MCP tools, once dekit has an agent-control feature to host them.
Design notes at the repo root (PLAN.md, PROTOCOL.md, TARGETS.md, ...) stay design notes. User docs are written for users; they are not copies of the design notes.
- Sources live here, under
src/docs/, in DekitDoc (the dialect from the website draft, with the changes listed under "Dialect"). The package root issrc/(src/Cargo.toml), so a tree at the repo root would never reach crates.io. - One parser, in Rust, in this crate (
src/help/). The website's TypeScript compiler is retired; dekit-web keeps only the IR types and the React renderer and consumesdocs.jsonproduced bydekit help --json. One interpretation, no generated blob committed here, no cross-repo CI step. - The binary embeds the markdown sources (a dependency-free
build.rs), not compiled JSON, and parses on demand. Sources are about
half the size of the IR and are what agents want to read. Validation
runs in
cargo test; export fails on any error. - Agents get the CLI.
dekit help <topic>on a non-TTY prints markdown. Nothing to install or configure, and every agent has a shell. MCP is deferred until dekit exposes runner control to agents; the docs tools then wrap the same functions. - What code knows, code generates; what needs prose, docs own. Clap
owns the command tree (names, arguments, flags, one-line abouts) and
the
:::usageblock pulls it in at render and export time. Docs own everything else. Tests enforce coverage in both directions. - Identity is the path.
docs/cli/up.mdis topiccli/up, URL/docs/cli/up,dekit help cli/up. Directories are sections. Aliases come fromtagsand, for CLI topics, from the command itself (dekit help up,dekit help runner stop). dekit helptakes over clap's implicithelpsubcommand.dekit up --helpanddekit --helpstay clap and are a subset of the topic.- The website vendors
docs.jsonandschemas/dekit.jsonper release;yarn docs:pullrefreshes them. Website builds are hermetic and the diff shows documentation changes.
src/docs/**/*.md ─src/build.rs─▶ embedded sources ─parse─▶ IR (in memory)
├─▶ terminal renderer dekit help up (TTY)
├─▶ markdown renderer dekit help up | cat (agents)
├─▶ JSON via serde dekit help --json ─▶ dekit-web src/gen/docs.json ─▶ React
└─▶ later: TUI pager (same layout code), MCP tools
src/docs/
index.yaml sections in nav order, with titles
index.md home topic
README.md pointer for GitHub readers; skipped by the parser
start/ cli/ config/ js/ rpc/ one directory per section
src/help/
mod.rs embedded table (from build.rs), load()
ir.rs IR types, serde Serialize, export()
error.rs DocError (path:line[:column]: message)
patterns.rs the identifier and tag matchers
parse.rs block parser inline.rs inline scanner
compile.rs frontmatter, identity, tags, nav, catalogs, validation
generate.rs :::usage from clap; later :::keymap, :::js-api
layout.rs IR -> lines of styled spans at a width; shared with the TUI later
term.rs lines -> ANSI through src/term/vt/emit.rs::sgr
markdown.rs IR -> markdown
help.rs the subcommand: resolution, search, pager
tests.rs the parser corpus (in-memory sources) and coverage tests
src/build.rs walks src/docs/, emits a static table of (path, include_str!)
src/build.rs has no dependencies and does no parsing: it only makes the
tree available to the crate, with cargo:rerun-if-changed. Slugs use /
on every platform. The clap tree lives in dekit::main::cli() so
generate.rs and the tests can walk it.
README.md files anywhere under src/docs/ are skipped; every other
.md there is a topic.
DekitDoc as specified in the website draft: a CommonMark subset, YAML
frontmatter, ::: containers, |tag| links. The block and inline
grammar, the forbidden constructs, and the validation table carry over
unchanged unless listed here.
- Topic id = slug = path under
docs/without.md.<dir>/index.mdis<dir>;docs/index.mdisindex, the home. Onlyindex.mdmay sit at the top level; every other topic lives in a section directory. Nested directories nest (cli/runner/stop); the website nav already nests by path. docs/index.yamlissections: [{dir, title}]in nav order. A section directory absent from the manifest, or an entry without a directory, fails validation. A section whose topics are all hidden is hidden.- Frontmatter keys; anything else fails:
| key | rule |
|---|---|
title |
required |
summary |
one sentence for nav, the index, and the page description; required unless cli is set, forbidden when it is |
cli |
dekit, dekit up, dekit runner stop: binds the topic to a clap command; the summary is that command's about |
tags |
aliases, ^[a-z][a-z0-9-]*$, globally unique across ids, tags, and record tags |
related |
topic ids |
order |
within the section; filename breaks ties |
hidden |
reachable by exact name in dekit help; absent from the index, nav, search, and the export |
Dropped from the draft: id, slug, section, draft, and home: in
the manifest.
As in the draft: ##/### headings with optional {#id}, paragraphs,
fenced code, flat lists, :::callout note|tip|warning [title=...],
:::commands (YAML {cmd, desc, tag?}), :::fields kind=config|js|cli-flag
(YAML records, required keys per kind as in the draft), :::footnote
(one, last), image ( or :::image, web-only).
Void containers are one line with no closer: :::usage,
:::image src=... alt=.... The draft required a closer for :::image;
the corpus is adjusted when ported.
Generated blocks expand at parse time from the running binary and are ordinary blocks in the IR, so no renderer learns a new type:
:::usagerequirescli. It expands to acodeblock with clap's usage line, afields kind=cli-flagblock with the command's own arguments and options (global flags excluded; they are documented once on theclitopic), and, for a group command, acommandsblock of its subcommands with their abouts. Everyclitopic must contain it (validation), so every command page shows its synopsis and the CLI overview's command list can never go stale.- Reserved, same mechanism, added with their topics:
:::keymap(default console bindings fromKeymapandAction::name) and:::js-api <module>(from the binding registry once the JSVM.md macro exists).
Unknown container types fail validation; the block set is closed.
Unchanged: `code`, **strong**, _em_ with flanking, |tag|,
[label](https://...). The tag charset gains / so |cli/up| and
|cli/up#semantics| resolve.
cli names a real clap path; every cli topic has :::usage;
summary and cli are exclusive; manifest and directories agree; a file
is at most 64 KiB; hidden topics may be linked only from other hidden
topics (a visible page must not dangle on the website).
Rust types in src/docs/ir.rs with Serialize. dekit-web/src/lib/docs/ir.ts
mirrors them and is the only contract the website has. The shape is the
draft's DocsIR v1 with:
- root gains
dekit: "<CARGO_PKG_VERSION>". Still no timestamp: the same sources and binary produce identical bytes; keys serialize in declaration order. Topickeepsid,slug, andsectionfor the renderer:id == slug,sectionis the first path segment and""for the home.- hidden topics are not in the export at all.
- the deduped
commands[]andfields[]catalogs stay, for search and MCP later.
dekit help: the index. Sections withslug summaryper topic, thenRun dekit help <topic>. dekit <command> --help shows flags only.dekit help <words...>: the words are joined with spaces and resolved in this order:dekit <words>matches aclitopic; exact id; tag; unique last path segment (upresolves tocli/up); title, case-insensitively;id#heading. No match: search titles, tags, headings, and record keys, print the candidates, exit 1.- TTY output: layout at
min(terminal width, 100)columns. Headings bold, inline code colored, callouts as a left bar with a colored label, commands and fields as definition lists (bold key, dim type and default on the same line, wrapped description indented), code indented, related topics asdekit help xlines at the end.NO_COLORandTERM=dumbturn styling off. The text goes through$PAGER(defaultless, withLESS=FRXwhen unset, so a short topic never waits forq); an unusable pager falls back to plain printing. - Not a TTY: markdown re-rendered from the IR. Generated blocks are
expanded, callouts become
> **Note:**quotes, records become GFM tables,|tag|becomes`tag`plus a trailing "Related" list ofdekit helpcommands so an agent knows how to follow a link. --jsonis the existing global flag. With no topic it exports the whole IR (the website's input); with a topic, that topic. Hidden topics are exported only when named explicitly.- Never contacts the runner; the docs are those of the invoking binary.
- Clap:
disable_help_subcommand(true)and an ownhelpsubcommand with trailing words.after_helpshrinks to a pointer atdekit help targetsanddekit help; the TARGETS and BRINGING TASKS DOWN prose moves tostart/targets.
Direction rules:
- clap to docs: command tree, abouts, argument and flag help, through
:::usage. Nothing inmain.rsdescribes a command beyond its one-liner and its arguments. - docs generate nothing back into code.
schemas/dekit.jsonandsrc/js/lib/std.d.tsstay hand-written; tests keep the sets equal.
Coverage tests in src/docs/tests.rs:
- every clap subcommand path has exactly one
clitopic, and vice versa; ROOT_KEYS,TASK_KEYS, andTASK_SETTING_KEYSequal the keys of thefields kind=configrecords (prefix stripped) and the properties inschemas/dekit.json, per object. This already catchesstopandlogmissing from the schema today;- every function reachable from the
stdglobal in a test VM has afields kind=jsrecord; - every fixture parses to its golden IR; every forbidden fixture fails with the expected message.
CI needs nothing new: cargo test already runs on three platforms.
Keep ir.ts, load.ts, nav-tree.ts, components/docs/*, and the
routes. Remove lib/docs/compiler/*, scripts/docs-compile.ts, the
docs/ tree, and the yaml devDependency. Change:
vite-plugin-dekit-docs.tsstops compiling. It servessrc/gen/docs.json(path overridable withDEKIT_DOCS_JSON) asvirtual:dekit-docsand watches the file.yarn docs:pull [--from <binary>]runsdekit help --jsonintosrc/gen/docs.jsonand copiesschemas/dekit.jsontopublic/schemas/dekit.json(its$idalready names that URL). Images arehttps://URLs only. Default source iscargo run --manifest-path ../mprocs/src/Cargo.toml -- help --json; for a release, the installed binary ofSITE.version.src/gen/is committed. The docs footer showsdocs for dekit <ir.dekit>.- The six starter pages move to
mprocs/docswith corrections: host runner wording per PLAN.md, the fullrunnersubcommand list, and the "dekit help(later)" notes. design/docs-system.mdgets a status line pointing here.
dekit help is the agent surface: markdown when piped, --json when
structure is wanted. A start/agents topic explains driving dekit from
an agent: --json shapes for ls and why, targets, screen to read a
task's output, run for one-offs, exit codes, and a snippet for a
CLAUDE.md. MCP later: docs_get and docs_search over the same
functions, inside the agent-control feature, plus the runner-control
tools that feature is actually about.
layout.rs is the seam: fn layout(topic, width) -> Vec<Line> where a
Line is spans of (String, Attrs) using src/term/attrs.rs. stdout
converts with emit::sgr; the console draws the same lines into its
grid. Pager behavior (j/k, gg/G, / search, tag jump with history) as in
the draft's TUI section, opened by a console action OpenHelp { topic }.
| section | topics |
|---|---|
index |
home |
start |
getting-started, targets, runners (project and host, records, runner verbs), agents, from-mprocs |
cli |
index (global flags, .js files, exit codes, --json) and one topic per subcommand, with runner/ and kernel/ nested |
config |
index (dekit.yaml, fragments, user config.yaml), tasks (every task key), hooks, kernel, load, user (tui and keymap), schema (link) |
js |
index (running scripts), std, fs, path, env, process, tui, dekit |
rpc (hidden) |
protocol, framing, requests, attach; written from PROTOCOL.md |
Each step ships on its own.
- Parser, IR, validation, fixtures, build.rs embed;
docs/seeded from the six starter pages;cargo testgates. No CLI change yet. dekit help: resolution, terminal and markdown output,--json, the clap takeover,after_helptrimmed.- Coverage tests and the full CLI and config topic set,
:::usagein every command topic. - dekit-web: retire the compiler,
docs:pull, vendored JSON and schema, deploy. jsandrpcsections; the JS coverage test.- Later:
:::keymap, the TUI pager, MCP.
- Long topics on a TTY go through
$PAGER, as git does. summarycannot override clap's about on aclitopic: one source.- Terminal width is capped at 100 columns.