# llms.txt

> What's in /llms.txt and /llms-full.txt, and how every docs page has a plain markdown twin.

Source: https://metrocli.com/docs/agents/llms-txt/ · Docs index: https://metrocli.com/llms.txt

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`](/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`](/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`](/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

1. **Who it's for.** "You are an agent. A human gave you this file to set up metro on their machine."
2. **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.
3. **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.
4. **Learn the tenant.** `metro status --json`, `metro catalog bind --sandbox --write`, `metro tenant snapshot show --sandbox --markdown`, `metro ops who`.
5. **Report a doorway.** One line, then exactly three next actions.
6. **The loop for every change.** Preview, confirm, apply, readback, with a real `metro ledger-adjustment` example.
7. **Key pages.** The sandbox and production token pages.
8. **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.