# llms.txt and Markdown pages

> Page: https://docs.plotwork.dev/agents/machine-readable. Index of every page: https://docs.plotwork.dev/llms.txt

The files that let an agent read these docs without a browser: an index, the full text, a Markdown copy of every page, and the generated references as data.

## TL;DR

| Question | Answer |
|---|---|
| Where do I start? | `https://docs.plotwork.dev/llms.txt`. It lists every page with a line on what it holds and its size in tokens. |
| How do I get one page as Markdown? | Add `.md` to its address, for example `https://docs.plotwork.dev/quick-start.md`. |
| How do I load a whole subject? | Fetch the bundle of its tab, `https://docs.plotwork.dev/llms-<tab>.txt`. It is the recommended way, and `llms.txt` gives the size of each bundle in tokens. |
| How do I load all of it? | `https://docs.plotwork.dev/llms-full.txt` holds every page that is not optional. It is the largest file, meant for a search index and not for a task. |
| Where are the schemas? | `https://docs.plotwork.dev/reference/tools.json` for the tools and `https://docs.plotwork.dev/reference/openapi.json` for the HTTP API. |
| Can a crawler read the pages? | Yes. The robots file welcomes search engines and AI assistants by name, every page is also served as HTML with its text in the file, and a sitemap lists every address. |

## Files

Every file below is written when the docs are built, from the same pages a reader sees, so none can differ from them.

| File | Address | What it holds | Fetch it when |
|---|---|---|---|
| `llms.txt` | `https://docs.plotwork.dev/llms.txt` | An index of every page: its title, address, a line on what it holds, and its size in tokens. | You do not know which page you need. Read this first. |
| `llms-docs.txt` | `https://docs.plotwork.dev/llms-docs.txt` | The text of every page in the Documentation tab except the optional ones, in one file. | You need all of Documentation in one fetch. A tab bundle is the recommended way to load a whole subject. |
| `llms-agents.txt` | `https://docs.plotwork.dev/llms-agents.txt` | The text of every page in the AI agents tab except the optional ones, in one file. | You need all of AI agents in one fetch. A tab bundle is the recommended way to load a whole subject. |
| `llms-mcp.txt` | `https://docs.plotwork.dev/llms-mcp.txt` | The text of every page in the MCP tab except the optional ones, in one file. | You need all of MCP in one fetch. A tab bundle is the recommended way to load a whole subject. |
| `llms-cli.txt` | `https://docs.plotwork.dev/llms-cli.txt` | The text of every page in the CLI tab except the optional ones, in one file. | You need all of CLI in one fetch. A tab bundle is the recommended way to load a whole subject. |
| `llms-api.txt` | `https://docs.plotwork.dev/llms-api.txt` | The text of every page in the API reference tab except the optional ones, in one file. | You need all of API reference in one fetch. A tab bundle is the recommended way to load a whole subject. |
| `llms-reference.txt` | `https://docs.plotwork.dev/llms-reference.txt` | The text of every page in the Language tab except the optional ones, in one file. | You need all of Language in one fetch. A tab bundle is the recommended way to load a whole subject. |
| `llms-full.txt` | `https://docs.plotwork.dev/llms-full.txt` | The text of every page except the optional ones, in one file. It is the largest file here. | You are loading the whole documentation into a search index. For a task, read a tab bundle instead. |
| `tools.json` | `https://docs.plotwork.dev/reference/tools.json` | The name, description, behavior hints, and JSON Schema of every tool. | You build a client or a tool call and need the exact schema. |
| `openapi.json` | `https://docs.plotwork.dev/reference/openapi.json` | The OpenAPI 3.1 document of the HTTP API. | You call the HTTP API and want a generated client or the exact request and response shapes. |
| `sitemap.xml` | `https://docs.plotwork.dev/sitemap.xml` | The address of every page. | You crawl the site. |
| `robots.txt` | `https://docs.plotwork.dev/robots.txt` | What crawlers may fetch, and where the sitemap is. | You run a crawler. |

## One tab in one fetch

Each tab of the docs has a bundle that holds the text of its pages, except the pages marked optional, which are catalogues and policies. Each page starts with its own title and the address it is served at, so an agent can cite it.

| Bundle | Tab | Pages in it |
|---|---|---|
| `llms-docs.txt` | Documentation | 35 |
| `llms-agents.txt` | AI agents | 5 |
| `llms-mcp.txt` | MCP | 25 |
| `llms-cli.txt` | CLI | 20 |
| `llms-api.txt` | API reference | 132 |
| `llms-reference.txt` | Language | 10 |

## Markdown copies

A page copy is not the source file of the page. It is the page as an agent should read it.

- A link to another page of the docs is the full address of that page's Markdown copy, so an agent can follow it without a browser.
- A diagram keeps its source in a fenced block, and its picture is replaced by the one sentence that describes it, such as "Login request: 3 nodes, 3 connections."
- Icons that only decorate a table are left out, and the sync comments and collapsible wrappers of the page are gone.
- The first line under the title names the page and the index, because a copy fetched on its own has no sidebar around it.

## A good reading order

1. Fetch `llms.txt` and pick pages by title and size. A page of 2 thousand tokens costs less than guessing.
2. Fetch only those pages as Markdown.
3. Fetch a `llms-<tab>.txt` bundle when the task needs a whole subject, such as every tool or the whole language reference. Prefer it to `llms-full.txt`.
4. Read the optional pages last, and only when the task needs them: icon catalogues, the architecture pattern gallery, and the policies.

## See also

| Doc | Why |
|---|---|
| [Plotwork for AI agents](https://docs.plotwork.dev/agents/overview.md) | What an agent needs to know in one page |
| [Rules file for your agent](https://docs.plotwork.dev/agents/rules.md) | Guidance to paste into a project |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The tools whose schemas `tools.json` holds |
| [API reference](https://docs.plotwork.dev/api/reference.md) | The endpoints whose document `openapi.json` holds |