# llms.txt and Markdown exports

URL: /docs/agents/llms-txt
Markdown: /docs/agents/llms-txt.md

> The two llms.txt files for Sakura Lang - this site's Markdown exports, and the language reference in docs/llms.txt that sakura prompt will emit.

There are two different `llms.txt` files in the Sakura Lang project. Do not confuse them.

| | Site exports | Language reference |
| --- | --- | --- |
| Where | This website: `/llms.txt`, `/llms-full.txt`, `/docs/<page>.md` | The repository: [`docs/llms.txt`](https://github.com/icantcodefyi/sakura-lang/blob/master/docs/llms.txt) |
| Contents | These docs pages, as Markdown | The whole core language in one file, written for a model's context |
| Status | Live today | Exists today as a file; `sakura prompt` emits it |
| Use it for | Explanations, the tour, agent tooling docs | Writing Sakura Lang code |

## Site exports [#site-exports]

> **Available today**
>
> These endpoints are served by this site now. They export the docs, not a compiler.

| URL | Contents |
| --- | --- |
| [`/llms.txt`](/llms.txt) | An index of every docs page with title, description, and URL, grouped by sidebar section, following the [llms.txt](https://llmstxt.org) convention. |
| [`/llms-full.txt`](/llms-full.txt) | Every docs page concatenated into one Markdown file. |
| `/docs.md` | The docs root as Markdown. |
| `/docs/<path>.md` | Any docs page as Markdown. Append `.md` to its URL. `.mdx` works too. |

```bash
curl https://<this-site>/llms.txt
curl https://<this-site>/llms-full.txt
curl https://<this-site>/docs/tour/effects.md
```

Each exported page starts with its title, its URL, its Markdown URL, and its description. Components are flattened to plain Markdown: callouts become blockquotes and card grids become link lists.

Every rendered page also has a **Copy as Markdown** button and a menu linking to its `.md` version and its source on GitHub.

Use `/llms.txt` to choose pages when context is tight. Use a per-page `.md` URL to refresh one topic. `/llms-full.txt` is the whole site, including design rationale and planned tooling, so it is larger than the language reference.

## The language reference: `docs/llms.txt` [#the-language-reference-docsllmstxt]

[`docs/llms.txt`](https://github.com/icantcodefyi/sakura-lang/blob/master/docs/llms.txt) is the one-file reference an agent needs to write correct Sakura Lang. It is about 16 KB, roughly 4,500 tokens, and covers:

- the toolchain loop (`sakura check --json`, `sakura test --json`, `sakura run`) and fix impact rules;
- the syntax on one screen, plus the rules agents get wrong (newlines, casing, no call-site type arguments, no named arguments, explicit imports, one lambda form);
- types, refinements, and the derived constraints `Eq`, `Ord`, `Hash`, `Show`, `Schema`;
- effects, `Fail<E>`, `try`/`catch`, defects, handlers, and authority;
- concurrency and memory;
- the most used standard library names;
- common diagnostics and their fixes.

It is kept in sync with [`docs/design.md`](https://github.com/icantcodefyi/sakura-lang/blob/master/docs/design.md), which is authoritative if they ever disagree. Library signatures are deliberately not in it; look them up with the implemented MCP `symbol_query` tool; `sakura doc --search` is planned.

### `sakura prompt` [#sakura-prompt]

```bash
sakura prompt
sakura prompt --budget 8000
```

`sakura prompt [--budget tokens]` will print `docs/llms.txt` for the edition the installed compiler implements, plus requested library signatures within the token budget (design §12.1). Until it exists, fetch the file from the repository:

```bash
curl https://raw.githubusercontent.com/icantcodefyi/sakura-lang/master/docs/llms.txt
```

## System prompt snippet [#system-prompt-snippet]

A starting point for an agent that writes Sakura Lang. `sakura prompt` is available; consult its status section for planned interfaces.

```text
You write code in Sakura Lang. Before writing code, read the Sakura Lang language reference
(docs/llms.txt, or the output of `sakura prompt`) and follow it exactly. Do not
borrow syntax from other languages.

- Write full signatures first: parameter types, `-> T`, the effect row after
  `!`, the `Fail<...>` error union, and `requires`/`ensures`. Leave bodies as
  typed holes (`?body`) and run `sakura check --json`.
- Fill holes using the `hole` records: expected_type, allowed_effects, locals,
  candidates, contracts_in_scope.
- Apply only fixes with "impact": "local". Never apply a fix whose impact is
  "contract_change" or "authority_change" unless asked. List every
  "interface_change" in your summary for human review.
- Never weaken or delete requires/ensures/where clauses or test bodies to pass
  a check. Never use .trust(@trust(...)) or Secret.expose without a true reason.
- No call-site type arguments and no named arguments: annotate the binding
  (`let rows: List<User> = Sql.query(q)`) and pass records for options.
  Import every non-prelude name explicitly (`import std/http.{Http, Request}`).
- Use `sakura explain <code>` before guessing at a fix.
```

## Next [#next]

[MCP server](/docs/agents/mcp): the compiler tools agents call directly.