llms.txt and Markdown exports
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 |
| 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
Available today
These endpoints are served by this site now. They export the docs, not a compiler.
| URL | Contents |
|---|---|
/llms.txt | An index of every docs page with title, description, and URL, grouped by sidebar section, following the llms.txt convention. |
/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. |
curl https://<this-site>/llms.txt
curl https://<this-site>/llms-full.txt
curl https://<this-site>/docs/tour/effects.mdEach 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
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, 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
sakura prompt --budget 8000sakura 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:
curl https://raw.githubusercontent.com/icantcodefyi/sakura-lang/master/docs/llms.txtSystem prompt snippet
A starting point for an agent that writes Sakura Lang. sakura prompt is available; consult its status section for planned interfaces.
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
MCP server: the compiler tools agents call directly.