# AGENTS.md

> The operating manual metro ships for agents, section by section, with what each part makes your agent do.

Source: https://metrocli.com/docs/agents/agents-md/ · Docs index: https://metrocli.com/llms.txt

`AGENTS.md` is the operating manual for agents. It lives at the root of the [metro repo](https://github.com/metrocli/metro/blob/main/AGENTS.md), and `metro init` copies it to `~/.metro/AGENTS.md` with a header line: `<!-- Managed by metro init. Re-running metro init replaces this file. -->`.

Point any agent at it with one sentence: "read ~/.metro/AGENTS.md and run metro status". The manual tells the agent to read all of it before any command that talks to Metronome.

Below is each section, what it says, and why it's there.

## 1. What metro is

What it says: metro reads your billing setup, previews changes as local files, validates them against known Metronome gotchas, and applies them only through gates. It gives the package name `@metrocli/metro`, Node 18, and the exit codes.

Why: the agent needs to know that `0`, `1` and `2` mean different things. Prefer `--json`; success goes to stdout, refusals and progress to stderr.

> **Exit code 3.** The manual lists codes `0`, `1` and `2`. The provisioning and ops commands add `3` for a readback mismatch. Treat `3` as "the write landed, but the object differs": read it fresh, don't re-run the plan.

## 2. Metronome in two minutes

What it says: a table of every object, in data-flow order: usage events, billable metrics, products and rate cards, contracts, invoices. It ends with "Source of truth: docs.metronome.com. When a doc and this table disagree, the doc wins."

Why: an agent that knows a package can't be edited won't try to edit one. The same model is in [Concepts](/docs/concepts/architecture).

## 3. Set up (agent steps)

What it says: install, run `metro init --agent`, ask the human to paste the sandbox key into `~/.metro/.env` in their editor, run `metro init --check --json`, and continue only when `keys.sandbox.status` is `working`. Production comes last, and only the human adds it.

Why: this is the one place the agent must stop and wait for you. It's the same flow as [Copy-paste setup](/docs/agents/copy-paste-setup).

## 4. The safety contract

What it says: six rules. Read-only by default. Sandbox first. Always name the tenant. Preview, confirm, apply, read back. Production needs your explicit typed yes for that specific change. Never print keys.

Why: most of these are enforced in code; the rest are behavior the agent must follow. The full version, including the typed tokens, is on [Safety contract](/docs/agents/safety-contract).

## 5. Learn the tenant before you act

What it says: run these before proposing anything, and reuse the bound IDs instead of guessing.

```bash
metro status --json
metro catalog bind --sandbox --write
metro tenant snapshot show --sandbox --markdown
metro ops who "Acme" --sandbox
```

Why: the snapshot's `accountPattern` decides which shape fits a pricing change. "If something is missing, say so; do not invent IDs."

## 6. Provisioning workflow

What it says: a table from goal to command. Every write is a `preflight` then an `apply`:

| Goal | Command |
|---|---|
| Create a customer with ingest aliases | `metro customer create` |
| Create a rate card | `metro ratecard create` |
| Create a package | `metro package create` |
| Create a contract | `metro contract create` |
| Add a subscription | `metro subscription add` |
| Change quantity or seats | `metro subscription set-quantity`, `metro subscription seats` |
| Move a customer to another package | `metro contract move-plan` |
| Extend a trial, or end a contract | `metro contract extend-trial`, `metro contract expire` |
| Adjust a credit or commit balance | `metro ledger-adjustment` |
| Archive a contract created by mistake | `metro contract repair-accidental` |
| Replace a Stripe billing-provider config | `metro billing-provider cutover` |

Why: if a command reports `Unknown command`, the installed metro is older than the manual. The agent updates metro, or falls back to `metro plan` and `metro api preview`.

## 7. Which docs and skills to load

What it says: load `skills/metro/SKILL.md` for any metro task, the cookbook for workflows, and the gotchas before any write. `metro docs explain <topic> --markdown` gives focused explanations, and `metro schema --json` lists every command.

Why: these are the same pages as [Reference](/docs/reference/commands), in the form an agent loads best.

## 8. Report a doorway

What it says: after setup, or after any task, end with three concrete next actions the human can say yes to, based on this tenant.

Why: you get a choice, not an install log.

## Keep it current

Re-running `metro init` (or `metro init --agent`) replaces `~/.metro/AGENTS.md` with the copy from your installed metro. It never touches `~/.metro/.env`.