# Overview

URL: /docs/agents
Markdown: /docs/agents.md

> How an AI agent is expected to work with Sakura Lang, from reading the docs to handing signature changes to a human.

> **Pre-alpha**
>
> The source-built compiler runs the core language and much of M3 on JavaScript: contracts, typed effects and failures, std handlers, permissions, LSP and MCP. M3 is still in progress; no release or stable compatibility contract exists. See the [roadmap](/docs/roadmap) for implemented features and remaining gates.

Sakura Lang is designed to be written by agents and reviewed by humans. The signature is the contract: parameter types with refinements, result type, effect row, error union, and `requires`/`ensures`. Agents write bodies against it; humans review signatures and the diff of signatures.

## Available today [#available-today]

| Resource | What it is |
| --- | --- |
| [`/llms.txt`](/llms.txt) | Index of every page on this site, with titles, descriptions, and URLs. |
| [`/llms-full.txt`](/llms-full.txt) | Every page on this site concatenated into one Markdown file. |
| `/docs/<page>.md` | Any page on this site as Markdown. Append `.md` to its URL; the docs root is `/docs.md`. |
| Copy as Markdown | A button at the top of every page, next to a menu with the `.md` link and the GitHub source. |
| [`docs/llms.txt`](https://github.com/icantcodefyi/sakura-lang/blob/master/docs/llms.txt) | The language reference for agents: the whole core language in one file of about 4,500 tokens. Lives in the repository. |
| [`docs/design.md`](https://github.com/icantcodefyi/sakura-lang/blob/master/docs/design.md) | The authoritative v0 design. When anything else disagrees with it, it wins. |

The two `llms.txt` files are different things. See [llms.txt](/docs/agents/llms-txt).

## Toolchain by milestone [#toolchain-by-milestone]

| Tool | Purpose | Design |
| --- | --- | --- |
| `sakura check --json` | Diagnostics, holes, and obligations as JSON Lines. | design §12.2, M0 |
| `?name` typed holes | Placeholders the checker reports with expected type, effects, locals, and candidates. | design §12.4, M2 |
| `sakura prompt` | Emits `docs/llms.txt` matched to the compiler's edition, plus requested library signatures. | design §12.1, M2 |
| `sakura fix`, `--frozen-specs` | Applies compiler fixes by impact class and rejects patches that touch frozen specs. | design §7.3, M3 |
| [`sakura audit`](/docs/agents/audit), [`sakura doc`](/docs/agents/doc) | Trust inventory and offline signature search. | design §17.78, M3 |
| [`sakura build --manifest`](/docs/agents/build-manifest) | Trusted components and runtime contract obligations. | design §17.76, M3 |
| [`sakura test --record`](/docs/agents/cassettes) | Opt-in cassette recording; ordinary tests replay offline. | design §17.73, M3 |
| `sakura mcp serve` | The compiler as Model Context Protocol tools. | design §12.6, M3 |

Milestones are defined in [design §14.3](https://github.com/icantcodefyi/sakura-lang/blob/master/docs/design.md). See also the [roadmap](/docs/roadmap).

## The intended loop [#the-intended-loop]

This is how an agent is expected to work with the full v0 toolchain. `sakura fix`, `--frozen-specs`, and the compiler MCP server are available.

### Load the language [#load-the-language]

Read `docs/llms.txt` once per session (or run `sakura prompt`). It is the entire core language. Look up library signatures with the MCP `symbol_query` tool instead of guessing; [`sakura doc --search`](/docs/agents/doc) is also available offline.
### Write signatures first, bodies as holes [#write-signatures-first-bodies-as-holes]

```sakura
fn clamp(x: Int, lo: Int, hi: Int) -> Int
  requires ordered: lo <= hi
  ensures bounded: lo <= result && result <= hi
{
  ?body
}
```

`sakura check` accepts holes. Signatures are what a human reviews, so get them right first.
### Check [#check]

Run `sakura check --json`, or call the MCP `check` tool. Each [typed hole](/docs/agents/typed-holes) comes back as a `hole` record with its expected type, allowed effects, locals, and ranked candidates.
### Fill holes and fix diagnostics [#fill-holes-and-fix-diagnostics]

Each problem is a `diagnostic` record with a stable code, byte spans, structured expected/actual, and fixes. See [Diagnostics](/docs/agents/diagnostics). `sakura explain V3001` gives the rationale for a code.
### Apply fixes by impact class [#apply-fixes-by-impact-class]

`local` fixes that are `machine_applicable` are safe to apply. `interface_change`, `contract_change`, and `authority_change` fixes are never `machine_applicable`; `sakura fix` never applies the last two. Run `sakura test --json`, then `sakura fmt`.
### Report signature changes [#report-signature-changes]

If the task really needs a new effect, error tag, permission, or a changed contract, make the change and list it for the reviewer. During repair, specs can be frozen (`--frozen-specs`), and any patch that touches them is rejected with `V8020`.

## What an agent should never do [#what-an-agent-should-never-do]

- Add an effect, error tag, or `[permissions]` entry without flagging it.
- Weaken or delete a `requires`, `ensures`, or `where` clause, or edit a `test` body, to make a check pass. Contract violations (`D020`, `D021`) mean the caller or callee is wrong, not the spec.
- Use `.trust(@trust("..."))`, `Secret.expose`, `.expect`, or `Email.from` outside trusted boundaries, or without a true reason.
- Leave a `?hole` in code meant to build. `sakura build` and `sakura run` reject it with `V2050`.
- Borrow syntax from other languages: call-site type arguments (`f<T>(x)`, `V0011`) and named arguments (`f(name: v)`, `V0014`) do not exist. Annotate the binding (`let rows: List<User> = Sql.query(q)`) and pass a record for options. Import every non-prelude name explicitly (`import std/http.{Http}` and `import std/request.{Request}`).

## Pages in this section [#pages-in-this-section]

- [llms.txt](/docs/agents/llms-txt): The site's Markdown exports and the language's `docs/llms.txt`.
- [MCP server](/docs/agents/mcp): The implemented `sakura mcp serve` compiler tools and `@tool` export.
- [Diagnostics](/docs/agents/diagnostics): The JSON Lines format, error codes, and fix impact classes.
- [Typed holes](/docs/agents/typed-holes): Writing programs incrementally with `?name`.
- [Trust audit](/docs/agents/audit): Inventory explicit trust, totality and refinement boundaries.
- [Offline API search](/docs/agents/doc): Query signatures, effect rows and contracts with sakura doc.
- [Build manifest](/docs/agents/build-manifest): Inspect trusted dependencies and runtime contract obligations.
- [Cassettes and recording](/docs/agents/cassettes): Replay HTTP and LLM exchanges offline; opt into recording.