metamask-docs / rules

---
description: Product-specific guidance for MetaMask Agent Wallet documentation, including terminology, CLI conventions, and content organization.
globs: agent-wallet/**/*.md,agent-wallet/**/*.mdx
alwaysApply: false
---

# Agent Wallet

## Product naming

- The product name is **MetaMask Agent Wallet**. Use **Agent Wallet** as short form in prose.
- The CLI binary is `mm` (lowercase, monospace). Do not document `mm-dev` or `mm-uat` in user-facing docs.
- The npm package is `@metamask/agent-wallet`.

## Wallet and trading modes

- **server-wallet** — private keys are held securely in a TEE-backed environment.
- **Bring your own wallet** — user supplies a BIP-39 mnemonic. CLI flag: `byok`.
- **Guard Mode (Recommended)** — trading mode (`--mode guard`). Designed for everyday traders. Enforces threat scanning, network allowlist, token recipient allowlist, address allowlist, and rolling 24h outflow limit. 2-factor authentication on policy violations, malicious transactions, and raising outflow limit.
- **Beast Mode** — trading mode (`--mode beast`). Designed for power users. Threat scanning guardrail only. 2-factor authentication on malicious transactions and risky contracts.

Users choose wallet and trading modes during interactive `mm init` or by prompting their agent.
Mark Guard Mode as **Recommended**; do not describe modes as opt-in, default, or preferred in other ways.
Sign-in method determines the 2FA approval channel: Google or email passwordless (browser dashboard) → email link; MetaMask Mobile QR (`mm login qr`) → Mobile push.

**Google**, **email passwordless**, and **MetaMask Mobile QR** are three separate sign-in methods.
Each loads a different server-wallet address, even when the same email is used across methods.
Do not document `mm login google` or `mm login email` (removed in CLI v3).

CLI flags use `server-wallet`, `byok`, `guard`, and `beast`.

## Security terms

Use these terms consistently when describing the security stack:

- **Threat scanning** — powered by Blockaid; production-tested across millions of MetaMask
  transactions. Malicious transactions get auto-bounced. Do not conflate with Transaction Shield.
- **Transaction Protection** — guarantee for eligible transactions deemed safe (up to $10,000/month
  loss coverage). Frame as optional coverage backing, not as a scanning feature. Link eligibility
  and terms to
  [Transaction Shield support](https://support.metamask.io/manage-crypto/transactions/transaction-shield/).
- **Transaction Shield** — MetaMask subscription pairing Transaction Protection with priority support.
  Link to
  [Transaction Shield support](https://support.metamask.io/manage-crypto/transactions/transaction-shield/)
  for subscription details, eligibility, and terms. Do not describe Transaction Shield as a security
  or threat-scanning feature.
- **Smart Transactions** — optimizes how trades land onchain (fewer fails, better gas, built-in MEV
  protection). Link to
  [Smart Transactions support](https://support.metamask.io/manage-crypto/transactions/smart-transactions/).
  Do not use "Servo" in user-facing docs.
- **Server wallet** / **TEE** — keys managed and secured server-side; agents can't access the user's
  main wallet. Do not lead with vendor names.
- **2FA** or **2-factor authentication** — human approval for flagged or policy-violating transactions. Do not use "MFA" in prose (CLI state `AWAITING_MFA` is acceptable in code references).

Do not add comparative security claims beyond approved product copy.

## Content organization

| Folder           | Content type                                      |
| ---------------- | ------------------------------------------------- |
| Root (`README.mdx`, `quickstart.md`, `cli-setup.md`) | Overview, quickstart, CLI setup |
| Root (`agent-rules.md`, `switch-modes-and-wallets.md`, `approve-requests.md`) | Agent operating rules, switching, and 2FA approvals |
| `guides/`        | Task-oriented how-to guides                       |
| `reference/`     | Architecture, trading modes, outflow policy, CLI commands, error codes, supported chains |
| `troubleshooting/` | Symptom-based fixes (single page in v1)         |

Do not paste content from the `metamask-agent-wallet` skill into documentation pages verbatim.
`agent-rules.md` deliberately mirrors the skill's operating rules (preflight, confirmations,
credential safety, 2FA pauses, output rules) in documentation voice, because many agents read the
docs without loading the skill. When the skill's rules change, update `agent-rules.md` in the same
release. When the docs and the skill disagree about CLI behavior, check the CLI source or
`mm <command> --help` and fix whichever is wrong.

## Writing for AI agents

AI agents are a primary reader of these pages, often without the skill and often a non-Claude model.
They quote the docs back to users and act on them literally.

- **State deterministic behavior as fact.** Don't write "may", "might", or "probably" when the CLI
  always does the same thing. Where behavior genuinely varies, say what decides it.
- **Pair every interactive prompt with its non-interactive equivalent.** Name the flag (`--mode`,
  `--wallet`, a positional address, `--yes`) and what happens when it is omitted in a
  non-interactive session.
- **Write literal tokens exactly, in backticks.** Error codes, `AWAITING_MFA`, `pending_approval`,
  and status values must match CLI output character for character so agents can string-match them.
- **Make sections self-contained.** Retrieval splits pages by heading, so repeat scoping such as
  "server-wallet only" in each section where it applies.
- **Give each fact one canonical home.** Approval channels live in `approve-requests.md`; switching
  behavior lives in `switch-modes-and-wallets.md`. Link to them instead of restating.
- **Say where, not just what.** For anything the user must do outside the terminal, name the exact
  surface (for example, the MetaMask Mobile notifications menu).
- **End task pages with a "Guidance for AI agents that …" section** (complete it with the task, so each
  heading is unique) when the task has choices the agent
  must leave to the user or states it must not misreport. Don't reuse the heading
  "Rules for AI agents"; that is the title of `agent-rules.md`, and duplicate headings confuse
  retrieval in the concatenated `llms-agent-wallet-full.txt`.
- **Bump `version` in `src/plugins/llms-html-injector/options.js`** after checking the docs
  against a new CLI release.

## Reference conventions

- Command headings use backtick-wrapped names (for example, `## \`mm transfer\``).
- Parameters use tables with columns: Flag, Required, Description.
- Use `bash` fences for CLI examples.
- Global flags: `--format`, `--json`, `--toon`, `--verbose`.

## Sidebar

The sidebar configuration is in [agent-wallet-sidebar.js](agent-wallet-sidebar.js).

## Images

Place product images in `static/img/agent-wallet/`.