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
| Option | Why not |
|---|---|
One llms-full.txt | Over 2,700 lines; an agent asking about one prop reads all of it. |
| Hand-written reference for agents | Drifts 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.