# For agents

Point your coding agent here before it touches Tally. Every page of these
docs is also plain Markdown, and `/llms.txt` is the index: what Tally is, the
rules a safe adapter follows, and where each page lives.

## Give this to your agent

Paste this into Claude Code, or your agent's instructions:

```
Before writing or changing anything that talks to Tally, read
https://tallyprotocol.dev/llms.txt and follow its rules. Fetch the .md pages it links to
as you need them. Test only in a sandbox grouping (docs/sandbox.sh).
```

## Every page as Markdown

Swap a page's address for `.md`: `/concepts.md`, `/sidecar-api.md`. Same
content, no layout. [llms.txt](llms.txt) lists them all and is short on
purpose: an agent reads it first, then follows the links it needs.

## The MCP tools are already there

`gromit local install` registered them in Claude Code as `<you>/claude`,
under the default mandate: `tally_status`, `tally_state`, `tally_inbox` and
`tally_do`. See [Get started](get-started.md#what-claude-code-gets).

## The rules, and why

1. **Talk only to your person's sidecar.** It holds the key and judges every
   event. Nothing else on the machine can publish, and nothing needs to.
2. **Read `outcome` on every `POST /do`.** The sidecar answers 200 even when
   it rejects. A rejected event is never stored or sent, and sending it again
   gets the same answer.
3. **Compare with `/state` every pass.** It's the fold of everything everyone
   did. Your own memory of what you sent isn't, so trusting it publishes
   things twice.
4. **Put your tool's id on `created`.** One `ext.<tool>` key on the creating
   event means a crash can never leave an item you won't recognise next pass.
5. **Move state with its own verb.** `edited` with a `state` is rejected. Use
   `state_changed`, and claim an item before marking it done.
6. **Leave change sets to the bridge.** The GitLab bridge opens one per MR,
   so one from an adapter would be a duplicate. Link your planning to the
   bridge's with `change-set@0 linked`.
7. **Never test on the team's grouping.** Events can't be deleted. A sandbox
   grouping takes one command and is gone with another.
8. **Assume the whole team reads it.** Every event goes to everyone in the
   grouping. Publish only what the tool marks as shared.

## When the docs and the code disagree

The code wins. Say so in your answer, name the file and line, and carry on
with what the code does. Then tell your person, so the page gets fixed.

## For people: checking your agent's adapter

- Ask for the manifest and run `gromit conformance <manifest> --in sandbox`.
  Only `compliant` is ready.
- Run it once with `--dry-run` against the team's grouping and read every
  line it would publish.
- After the first real pass, check `gromit fold all` for anything
  `rejected:` and ask why.

See [Writing an adapter](writing-an-adapter.md) for the whole procedure.
