llms.txt
What's in /llms.txt and /llms-full.txt, and how every docs page has a plain markdown twin.
These docs ship in two forms: the pages you're reading, and plain markdown for agents. Both are built from the same source on every build, so they can't drift.
The three files
| URL | What it is |
|---|---|
/llms.txt | The agent brief. Safety contract first, setup by situation, how to report back, the loop for every change, then an index of every docs page. |
/llms-full.txt | Every docs page as markdown in one file, in nav order. |
/docs/<page>.md | A markdown twin of each page, for example /docs/keys.md. The docs root is /docs/index.md. |
Every page has a Copy Markdown button and a View .md link at the top. Use them to hand one page to an agent.
What /llms.txt says, in order
- Who it's for. "You are an agent. A human gave you this file to set up metro on their machine."
- Safety contract. Ten rules: read-only by default, sandbox first, always name the tenant, never ask for a key in chat, preview before every write, apply only with the approved hash, production needs a typed yes for that change, report the readback, what each exit code means, and never retry a failed apply blindly.
- Setup, by situation. A: a local coding agent with a terminal runs the install and
metro init --agent. B: a hosted chat assistant without a terminal says so and stops. C: a sandboxed agent with a blocked network names the blocked host and stops. - Learn the tenant.
metro status --json,metro catalog bind --sandbox --write,metro tenant snapshot show --sandbox --markdown,metro ops who. - Report a doorway. One line, then exactly three next actions.
- The loop for every change. Preview, confirm, apply, readback, with a real
metro ledger-adjustmentexample. - Key pages. The sandbox and production token pages.
- Docs index. One line per page:
- [Title](…/docs/page.md): description.
How the twins are made
scripts/gen-llms.mjs runs before every build. It walks the docs page tree in meta.json order and, for each page:
- writes the page as markdown with a title, its description, and a source link back to the HTML page;
- turns MDX components into plain markdown: callouts become quotes, tabs become labelled sections, cards become link lists, the object diagram becomes a table;
- drops MDX comments, which is where these docs keep source notes.
Code blocks pass through unchanged, so every command in a twin is the same command as on the page.
For people building on it
The twins are static files. Static hosting can't vary a response by Accept header, so link the .md URL directly. Fetch /llms.txt first; it lists every twin.