Language changes

Author: yashovardhan

.cursor/rules/product-agent-wallet.mdc

@@ -15,9 +15,9 @@ alwaysApply: false
 ## Wallet and trading modes
 
 - **server-wallet** — private keys are held securely in a TEE-backed environment.
-- **BYOK** (bring your own key) — user supplies a BIP-39 mnemonic.
-- **Guard Mode (Recommended)** — trading mode (`--mode guard`). Enforces spend limits and allowlists with 2-factor authentication on violations.
-- **Beast Mode** — trading mode (`--mode beast`). Skips routine policy checks; malicious or flagged transactions still require 2-factor authentication.
+- **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 security check, 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. Security check 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.
@@ -29,9 +29,19 @@ CLI flags use `server-wallet`, `byok`, `guard`, and `beast`.
 
 Use these terms consistently when describing the security stack:
 
-- **Transaction Shield** — threat scanning for malicious contracts and scams. Do not lead with vendor names.
-- **Smart Transactions** — MEV protection (externally branded name; do not use "Servo" in user-facing docs).
-- **Server wallet** / **TEE** — key custody in server-wallet mode. Do not lead with vendor names.
+- **Transaction Protection** — guarantee for transactions deemed safe (up to $10,000 loss coverage).
+  Frame as backing for "security by default," not as a standalone scanning feature. Link eligibility
+  and terms to
+  [Transaction Shield support](https://support.metamask.io/manage-crypto/transactions/transaction-shield/).
+- **Transaction Shield** — automated security checks for malicious contracts and scams. Link to
+  [Transaction Shield support](https://support.metamask.io/manage-crypto/transactions/transaction-shield/).
+  Do not lead with vendor names.
+- **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.
@@ -42,8 +52,7 @@ Do not add comparative security claims beyond approved product copy.
 | ---------------- | ------------------------------------------------- |
 | Root (`README.mdx`, `quickstart.md`, `use-the-cli-directly.md`) | Overview, quickstart, headless CLI |
 | `guides/`        | Task-oriented how-to guides                       |
-| `concepts/`      | Architecture, security                            |
-| `reference/`     | CLI commands, error codes, supported chains       |
+| `reference/`     | Architecture, CLI commands, error codes, supported chains |
 | `troubleshooting/` | Symptom-based fixes (single page in v1)         |
 
 Do not paste content from `.agents/skills/metamask-agent-wallet/` into documentation pages.

.cursor/rules/terminology.mdc

@@ -27,7 +27,7 @@ listed on the right unless they appear in code, URLs, or direct quotations from
 | Guard Mode                             | guard mode (capitalize Mode)                                                    |
 | Beast Mode                             | beast mode (capitalize Mode)                                                    |
 | server-wallet                          | server wallet, Server Wallet (except as product phrase "server-wallet mode")    |
-| BYOK                                   | byok (capitalize in prose when referring to the mode name)                      |
+| Bring your own wallet                  | BYOK, bring your own key, byok (except CLI flag `--wallet byok`)                |
 | `mm` (CLI binary)                      | MM, Mm (except at sentence start)                                               |
 
 ## Standards and specifications

agent-wallet-sidebar.js

@@ -31,17 +31,16 @@ const sidebar = {
         'guides/sign-messages-and-transactions',
       ],
     },
-    {
-      type: 'category',
-      label: 'Concepts',
-      collapsed: true,
-      items: ['concepts/architecture', 'concepts/security'],
-    },
     {
       type: 'category',
       label: 'Reference',
       collapsed: true,
-      items: ['reference/commands', 'reference/error-codes', 'reference/supported-chains'],
+      items: [
+        'reference/architecture',
+        'reference/commands',
+        'reference/error-codes',
+        'reference/supported-chains',
+      ],
     },
     {
       type: 'doc',

agent-wallet/README.mdx

@@ -7,18 +7,34 @@ keywords: [MetaMask, Agent Wallet, mm, AI agents, skills]
 
 import CardList from '@site/src/components/CardList'
 
-Give your AI agent a self-custody wallet with built-in security on every signing path.
-Custody depends on wallet mode: server-wallet uses TEE-backed key storage; BYOK keeps keys under your
-local control.
-You install the `mm` CLI and add agent skills once.
-After that, your agent handles authentication, transfers, swaps, bridges, perpetuals, and prediction
-markets from natural-language requests.
+A fully self-custodial agent wallet that lets AI agents trade autonomously without forcing users to give up control. Deploying an agent on a self-custody wallet can mean choosing between giving the agent freedom to act and keeping users’ funds safe. MetaMask Agent Wallet ends that trade-off. Your agent operates inside user-defined limits.
 
 :::info Early Access
 MetaMask Agent Wallet is available through the
 [Early Access Program](https://metamask.io/agent-wallet).
 :::
 
+## MetaMask safety-checks every transaction before it lands
+
+Security by default, not configuration.
+Supported EVM transactions pass through a mandatory 3-step security pipeline.
+Backed by Transaction Protection: transactions through Agent Wallet deemed safe are guaranteed
+against loss up to $10,000.\*
+
+1. **Transaction simulation**: what will this transaction actually do? Balance changes, approvals,
+   and gas are surfaced before signing.
+2. **[Transaction Shield](https://support.metamask.io/manage-crypto/transactions/transaction-shield/)**:
+   automated security checks flag malicious contracts and scams; flagged transactions require your
+   approval before they execute.
+3. **[Smart Transactions](https://support.metamask.io/manage-crypto/transactions/smart-transactions/)**:
+   smart transaction execution with built-in MEV protection, fewer fails, and better gas where
+   supported on the target chain.
+
+Learn more in [Architecture](reference/architecture.md).
+
+\* See [Transaction Shield](https://support.metamask.io/manage-crypto/transactions/transaction-shield/)
+for eligibility, coverage limits, and terms.
+
 ## What your agent can do
 
 After setup, prompt your agent in plain language:
@@ -35,11 +51,6 @@ After setup, prompt your agent in plain language:
 
 <!-- vale on -->
 
-## Works in your agent
-
-Install skills in any skills-compatible agent environment, including Claude Code, Codex, Cursor,
-OpenClaw, and Hermes Agent.
-
 ## Capabilities
 
 The `mm` CLI exposes a full command surface for wallet operations.
@@ -63,41 +74,6 @@ Your agent routes natural-language requests to these commands through installed
 
 See the [commands reference](reference/commands.md) for every flag and subcommand.
 
-## Security by default
-
-Signing and transaction requests pass through a built-in security pipeline before they complete.
-
-- **Transaction simulation**: transactions are simulated before signing to surface reverts and
-  unexpected state changes.
-- **Transaction Shield**: threat scanning flags malicious contracts and scams; flagged transactions
-  require your approval before they execute.
-- **Smart Transactions**: helps protect against sandwich and front-running attacks where supported on
-  the target chain.
-- **Server wallet**: in server-wallet mode, your private key is held securely in a trusted execution
-  environment (TEE).
-
-Learn more in [Security](concepts/security.md).
-
-## Operating modes
-
-During `mm init`, you choose a wallet mode and, for server-wallet, a trading mode.
-See [Use the CLI directly](use-the-cli-directly.md) for details.
-
-**Wallet mode** (choose one):
-
-- **server-wallet**: MetaMask holds your private key in a TEE-backed environment. Signing uses an
-  asynchronous model; long-running operations return a `pollingId` unless you pass `--wait`.
-- **BYOK (bring your own key)**: you supply a BIP-39 mnemonic. Keys stay under your local control
-  and operations return immediately.
-
-**Trading mode** (server-wallet only):
-
-- **Guard Mode (Recommended)**: enforces daily spend limits and protocol allowlists you set during
-  setup. Transactions that exceed those limits or target non-allowlisted protocols require
-  2-factor authentication before they execute.
-- **Beast Mode**: skips routine policy checks for faster scripted workflows. 2-factor authentication
-  still applies to malicious or flagged transactions.
-
 ## Supported chains
 
 MetaMask Agent Wallet supports multiple EVM chains.
@@ -115,9 +91,10 @@ See [Supported chains](reference/supported-chains.md) for typical networks.
         'Install the CLI, add skills to your agent, sign in, and send your first transfer.',
     },
     {
-      href: '/agent-wallet/concepts/security',
-      title: 'Security',
-      description: 'Transaction Shield, Smart Transactions, TEE key custody, and 2FA.',
+      href: '/agent-wallet/reference/architecture',
+      title: 'Architecture',
+      description:
+        'Wallet modes, Transaction Protection, Transaction Shield, Smart Transactions, and 2FA.',
     },
     {
       href: '/agent-wallet/guides/trade-perpetuals',

agent-wallet/concepts/architecture.md

@@ -66,7 +66,7 @@ mm wallet requests list
 mm wallet requests watch --polling-id <POLLING_ID>
 ```
 
-In BYOK mode, results return immediately when the mnemonic is unlocked.
+In bring your own wallet mode, results return immediately when the mnemonic is unlocked.
 
 ## Related commands