llms.txt and AGENTS.md

Language models read this documentation, some of them helping somebody build a host and some making a change in the repository itself. This page names a different file for each.

Reading the documentation

Three files on the published site are written for machines. They are plain Markdown, with no navigation and no styling around the text, and they follow the llms.txt proposal:

File	Contents	Fetch
/llms.txt	The index: what the project is, the two files below it, and the pages a model can read on their own, each with a sentence describing it	curl -sS https://codemode-executor.supolka.dev/llms.txt
/llms-full.txt	The whole book in one file, in the book’s own reading order	curl -sS https://codemode-executor.supolka.dev/llms-full.txt
/llms-small.txt	The same text with the whitespace squeezed out, because no page here writes a presentational block for the abridgement to drop	curl -sS https://codemode-executor.supolka.dev/llms-small.txt

Entries in /llms.txt link straight to the page each one names, so a model can fetch one page instead of the whole book. /llms-full.txt follows the sidebar and not the filenames: the landing page, then the page saying what this is, the two quickstarts, the guides, the contract, and this repository’s own conventions at the end.

starlight-llms-txt generates all three at build time out of the same pages a person reads, so none of them can drift from the site. Every page is also plain Markdown in the repository under docs/, the same text the site renders from, so a model with the repository checked out needs no fetch at all.

The executor composes its failure texts for a model to read, and the failure grammar quotes every one of them as the code builds it.

Working inside the repository

AGENTS.md at the root is the entry point for anything making a change: pnpm verify, 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. That file governs every change, so it stays general, and it names the three directories below:

Path	Contents
.github/instructions/	Rules narrowed by path, through the instructions files convention
.agents/skills/	Agent Skills for the procedures here that recur and are easy to get wrong, such as adding a case to the corpus that attacks the sandbox from the inside
.github/prompts/	Prompt files for the tasks worth starting from a written brief

Editing a spec file hands over the testing rules, editing Markdown hands over the prose rules, and neither agent reads the other’s. All three directories are versioned with the code they govern, so a rule and the tree it applies to move together.