Agentic Docs Architecture

Tiered documentation pattern designed so AI agents (and humans) can find rules, change code safely, and keep docs from rotting. The architecture is opinionated: every file has one place to live, every change has a known set of follow-ups, and the compiler enforces what it can.

The core idea (read this first)

Every boundary exists so that when something breaks, you find it in under 30 seconds.

Three forces shape the layout:

1. Failures must localize. Trait boundaries between crates act as firewalls — a bug in one crate doesn't cascade. If a tool fails inside an agent loop, you know it's the tool or the loop, not both. This is what makes the Tool<Ctx> trait, the LlmProvider trait, and friends non-negotiable: they're the seams along which problems get pinned.
2. Docs must not drift. Code changes constantly. Free-form docs can't keep up. Two mechanisms enforce freshness: (a) the Rust compiler (#![warn(missing_docs)], #![deny(rustdoc::broken_intra_doc_links)], doc tests) and (b) the change-impact table — a hand-written map of "if you change X, also update Y" that lives in every well-documented crate.
3. Agents need to know the rules. Every crate has an AGENTS.md (often symlinked or duplicated as CLAUDE.md) that states the invariants, the verify command, and the docs index. Without that file, agents invent conventions, misplace files, and ship code that compiles but doesn't fit. With it, they pick up any crate, follow the rules, and produce a PR that passes CI.

When you operate in this repo, you are participating in those three forces. Don't bypass them — extend them.

The doc tree (where things live)

Every well-documented crate (and the root) follows this layout. You don't get to invent a new tier — pick the right one.