Using this with an assistant

Language models read this documentation, some of them helping somebody build a host and some making a change in the repository itself. Those two want different things. Both are served on purpose.

Reading the documentation

Three files on the published site are written for machines. They are plain Markdown with no navigation, no styling and nothing to parse around, and they follow the llms.txt proposal. /llms.txt is the index. It names what the project is, then the two files below it, then the pages that answer a question on their own, each with a sentence saying what it holds. Fetching it is cheap, and a model that already knows what it is looking for often needs no second fetch, because the entries link straight to the page.

/llms-full.txt is the entire book in one file. Its order is the book’s reading order and not its filenames. The landing page comes first, then the page that says what this is, the two quickstarts, the guides, the contract, and this repository’s own conventions at the end. It is the file to fetch where a model should hold the whole book at once. /llms-small.txt is the abridged form of the same file. It drops the presentational blocks a page can carry, then squeezes the whitespace out of the prose. But this book writes no such block, so the abridged form saves the line breaks.

All three come out of the same pages a person reads, generated by starlight-llms-txt at build time, so they cannot drift from what the site shows. Every page is also plain Markdown in the repository under docs/, the same text the site renders from. So a model reading the repository and a model reading the site are reading one source.

Working inside the repository

AGENTS.md at the root is the entry point for anything making a change: the gate, the conventions, the workspace, and what a change has to survive before it counts as done. It follows the AGENTS.md format, so a tool looking for such a file finds it there with no configuration.

Because that file governs every change, it stays general. But the rules for one kind of file live where they can be handed over on demand. .github/instructions/ narrows them by path, through the instructions files convention. Editing a spec file hands over the testing rules, editing Markdown hands over the prose rules, and neither agent reads the other’s. .agents/skills/ is for procedure, not for rules. It holds Agent Skills for the work here that recurs and is easy to get wrong, such as adding a case to the corpus that attacks the sandbox from the inside. .github/prompts/ sits beside it with prompt files for the tasks worth starting from a written brief.

Failure texts written for the model

The executor writes its failure texts for the model that reads them, not for a log. A run that outlasted its bound is told to do less per run, a run that filled its heap is told to work in smaller pieces, and a run that called fetch under a disabled outbound setting is told to ask for what it wanted through a tool call. Where this runtime declares a surface absent, reaching for it answers a sentence saying why and what remains possible. Without that sentence, a bare undefined would send a model hunting for a bug it did not write. Those texts are the failure grammar, and they are the part of this project most worth copying into something built for the same job.