Skip to content

Concepts

Concept pages map the framework's mental model to the shipped code. Each page matches what's actually in the crates rather than an aspirational design — if a concept page and the code disagree, the code is authoritative and the page is a bug.

Pages in this section

  • App context — the App struct, Arc-shared services, cancellation flow, why there's no App<C> yet.
  • Configuration — typed layered config via figment, precedence rules, atomic reload.
  • Error diagnostics — thiserror + miette, tool-specific footer, the edge-rendering pipeline.
  • MCP exposure — how Command::mcp_exposed surfaces a CLI command as an MCP tool.
  • Flags vs settings — the scaffolder's two input verbs (flag = transient CLI arg, setting = persistent typed config), when to use each, and why RTB keeps them distinct.

Concepts that are not written yet

These are known gaps, not oversights. Until each is written, the behaviour is covered — thinly — by the reference pages and the module microsites linked from Components.

Missing page Would explain
Assets overlay How the embedded, on-disk and in-memory asset layers compose, and which one wins
Command authoring The registration model end to end, including the macro when it lands
Telemetry events What an event carries, what the salted machine id is for, and why consent is a hard gate
Credentials resolution The order the resolver tries sources in, and what "resolved" means when several could answer
AI providers The multi-provider layout, and the streaming and structured-output paths

Why these pages do not point at a spec

A specification is a point-in-time design record. It says what was decided and why at the time it was written, and nothing keeps it in step with the code afterwards. Documentation has the opposite obligation: it describes what is true now.

So the reasoning belongs here, in prose, in its own words — not behind a spec number. A page in this section that still says "see spec NNNN" for its reasoning has not had that pass yet, and should be treated as unexplained rather than explained elsewhere.

  • Reference — the same subjects at lookup level: keys, flags, defaults.
  • Engineering standards — requirements that span crates: security rules, testing discipline, documentation expectations.