Duolith docs

0060. The agent reference is generated from spec/ and docs/, and split by topic

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP14 (agent layer)

Context

Agents writing Duolith apps, or working on Duolith, need the elements, kit parts, utilities, diagnostics, data API and commands in one place they can read cheaply. A hand-written summary drifts from the spec within a week. One file with everything is too long to read for a single question.

Decision

llms.txt at the repository root is an index in the llms.txt format: a summary, then one link and one line for each topic. Each topic is a full file in llms/ (language, elements, kit, diagnostics, styling, data, navigation, production, cli, lint, agents), rendered by tools/generate/llms/ from spec/ (elements, kit parts, diagnostics, glossary) or taken as it is from a guide in docs/ (styling, data, navigation, production, lint, agents, and the CLI reference that tools/generate/reference makes from spec/). They are generated outputs: pnpm generate writes them and check-generated fails when one is stale. packages/create copies llms.txt and llms/ into every new app, so a skill can say "llms/kit.md" and mean the same thing in the repository and in an app.

Alternatives considered

OptionWhy not
One llms-full.txtOver 2,700 lines; an agent asking about one prop reads all of it.
Hand-written reference for agentsDrifts from the spec; nothing fails when it does.
Generate only from spec/The guides hold the how-to that agents most need (data, navigation); duplicating them would drift.

Consequences

Changing a spec file or one of the source guides means running pnpm generate. A new guide that agents need is one entry in tools/generate/llms/topics.ts. OWNERS.yaml gives llms/** to the Agent surface context beside llms.txt.