AGENTS.md
The operating manual metro ships for agents, section by section, with what each part makes your agent do.
AGENTS.md is the operating manual for agents. It lives at the root of the metro repo, 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.
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.
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.
5. Learn the tenant before you act
What it says: run these before proposing anything, and reuse the bound IDs instead of guessing.
metro status --json
metro catalog bind --sandbox --write
metro tenant snapshot show --sandbox --markdown
metro ops who "Acme" --sandboxWhy: 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, 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.