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 — 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