Skip to content

rtb-docs

Ships a tool's documentation inside the binary and makes it readable without a network connection. One markdown tree, carried by rtb-assets, presented three ways: a terminal browser, a local HTTP server, and plain text on stdout.

Registers the docs command into BUILTIN_COMMANDS, gated on Feature::Docs.

Why documentation lives in the binary

A support tool is most needed where the network is least available: a locked-down build agent, an air-gapped environment, a laptop on a plane. Documentation behind a URL is documentation that is missing exactly then.

Embedding it also pins it: the pages a binary carries are the pages that describe that binary. A published site describes whatever was released most recently, which is not necessarily what the user is running.

What it is made of

Piece Role
Index / IndexEntry The navigation model, from _index.yaml or a filesystem scan
DocsBrowser Two-pane ratatui widget: index left, rendered page right
DocsServer axum HTTP server rendering the same tree as HTML
SearchIndex tantivy full-text search over page bodies, plus fuzzy title matching
AiAnswerStream The trait docs ask calls, behind the ai Cargo feature
DocsError thiserror + miette::Diagnostic error enum

Why the index is optional

load_docs looks for <root>/_index.yaml. When it is there it defines the navigation exactly; when it is not, an index is synthesised from the tree, with the first # Heading as the title, top-level directory as the section.

The scan means a tool can embed a docs/ directory and get something usable with no extra file. The explicit index exists for when scan order and heading text are not the presentation you want.

The trade-off is worth knowing: once _index.yaml exists it is the whole navigation, and an unlisted page becomes invisible to docs list, to the browser and to search, even though it is still loaded and still servable by path.

Why the AI seam is a trait, not a configuration surface

docs ask calls AiAnswerStream::ask(context, question). The bundled implementation, behind the ai feature, hard-codes Anthropic, a model, and ANTHROPIC_API_KEY.

That looks like an under-configured feature and is really a deliberate refusal to become a provider-configuration layer. Credential resolution, provider selection, model choice and endpoint validation are all things a tool already has opinions about; duplicating them here would mean two places to configure the same thing. A tool with requirements implements the trait. A tool without gets a default that works if you export one variable.

What it does not excuse is the retrieval strategy: the whole doc tree goes into every prompt, with no ranking. That is a scale limit, not a design position.

Where to go next