Update agent wallet docs

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

@@ -56,7 +56,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                       |
-| `reference/`     | Architecture, CLI commands, error codes, supported chains |
+| `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 `.agents/skills/metamask-agent-wallet/` into documentation pages.

agent-wallet-sidebar.js

@@ -34,9 +34,11 @@ const sidebar = {
     {
       type: 'category',
       label: 'Reference',
-      collapsed: true,
+      collapsed: false,
       items: [
         'reference/architecture',
+        'reference/trading-modes',
+        'reference/outflow-policy',
         'reference/commands',
         'reference/error-codes',
         'reference/supported-chains',

agent-wallet/quickstart.md

@@ -57,20 +57,21 @@ commands.
 
 ### Sign in
 
-During `mm login`, choose QR code, Google, or email.
+During `mm login`, choose Google or email.
+QR code sign-in with MetaMask Mobile is coming soon.
 Your sign-in method also determines how you receive 2-factor authentication approvals when a
 transaction needs your confirmation.
 
-| Sign-in method  | 2FA delivery                        |
-| --------------- | ----------------------------------- |
-| QR code         | MetaMask Mobile push notification   |
-| Google or email | Email link with transaction details |
+| Sign-in method        | 2FA delivery                        |
+| --------------------- | ----------------------------------- |
+| Google or email       | Email link with transaction details |
+| QR code (coming soon) | MetaMask Mobile push notification   |
 
-:::info QR code sign-in
+:::note QR code sign-in (coming soon)
 
 Sign in with MetaMask Mobile by scanning the QR code the CLI displays.
-The CLI and your agent can access only the dedicated Agent Wallet created for this setup, not your
-main MetaMask wallet or its accounts.
+When available, the CLI and your agent can access only the dedicated Agent Wallet created for this
+setup, not your main MetaMask wallet or its accounts.
 When a transaction needs approval, you receive a 2-factor authentication prompt in MetaMask Mobile.
 
 :::
@@ -95,7 +96,7 @@ During `mm init`, choose a wallet mode and, for server-wallet, a trading mode.
 - **Beast Mode**: designed for power users. Keeps the threat scanning guardrail only. Malicious
   transactions and risky contracts are blocked and surfaced for 2-factor authentication approval.
 
-See [Trading modes](reference/architecture.md#trading-modes) for guardrails and approval conditions.
+See [Trading modes](reference/trading-modes.md) for guardrails and approval conditions.
 
 Confirm your choices with `mm init show`.
 

agent-wallet/reference/architecture.md

@@ -87,63 +87,9 @@ where supported on the target chain.
 ## Trading modes
 
 Trading modes apply to server-wallet only.
-During `mm init`, you set outflow limits and allowlists, then choose a trading mode that defines how
-those policies are enforced.
-Choose during `mm init` with `--mode` or at the interactive prompt.
-
-| Mode                     | CLI flag       | Summary                                                                                                               |
-| ------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------- |
-| Guard Mode (Recommended) | `--mode guard` | Designed for everyday traders. Transactions outside your policy limits require 2-factor authentication approval.      |
-| Beast Mode               | `--mode beast` | Designed for power users. Malicious transactions are still blocked and surfaced for 2-factor authentication approval. |
-
-### Guard Mode (Recommended)
-
-Designed for everyday traders.
-Transactions outside your policy limits require 2-factor authentication approval.
-
-**Guardrails**
-
-- Threat scanning
-- Network allowlist
-- Token recipient allowlist
-- Address allowlist
-- Outflow limit (rolling 24h)
-
-**Approval required for**
-
-- Malicious transactions
-- Addresses or contracts not in allowlist
-- Networks not in allowlist
-- Recipients not in allowlist
-- Raising outflow limit
-
-### Beast Mode
-
-Designed for power users.
-Malicious transactions are still blocked and surfaced for 2-factor authentication approval.
-
-**Guardrails**
-
-- Threat scanning
-
-**Approval required for**
-
-- Malicious transactions
-- Risky contracts
-
-When 2-factor authentication is required, the CLI pauses the job until you approve or reject it.
-Your sign-in method during `mm login` determines which channel the CLI uses:
-
-| Sign-in method  | Approval channel                    |
-| --------------- | ----------------------------------- |
-| QR code         | MetaMask Mobile push notification   |
-| Google or email | Email link with transaction details |
-
-The agent cannot proceed without your approval on flagged or policy-violating transactions.
-
-Switch modes by re-running `mm init` with a different `--mode` value.
-Confirm the active configuration with `mm init show`.
-See [Trading modes](../use-the-cli-directly.md#trading-modes-server-wallet-only).
+During `mm init`, you set allowlists and choose Guard Mode or Beast Mode to define how those policies
+are enforced.
+See [Trading modes](trading-modes.md) for the full guardrail and approval comparison.
 
 ## Server-wallet async model
 

agent-wallet/reference/commands.md

@@ -38,16 +38,17 @@ Environment variables: `MM_MNEMONIC`, `MM_PASSWORD` (bring your own wallet encry
 Sign in to MetaMask Agent Wallet.
 
 ```bash
-mm login [qr | google | email] [--token <token>] [--no-wait]
-mm login qr
+mm login [google | email] [--token <token>] [--no-wait]
 mm login google [--no-wait]
 mm login email [--no-wait]
 ```
 
+QR code sign-in (`mm login qr`) is coming soon.
+
 | Flag        | Required | Description                                                                          |
 | ----------- | -------- | ------------------------------------------------------------------------------------ |
 | `--token`   | No       | Pre-minted token as `cliToken:cliRefreshToken`. Environment variable: `MM_CLI_TOKEN` |
-| `--no-wait` | No       | Print sign-in URL and exit (not supported for QR)                                    |
+| `--no-wait` | No       | Print sign-in URL and exit                                                           |
 
 ## `mm auth status`
 

agent-wallet/reference/outflow-policy.md

@@ -0,0 +1,54 @@
+---
+description: How Agent Wallet enforces rolling 24-hour outflow limits on server-wallet transactions.
+keywords: [MetaMask, Agent Wallet, outflow policy, outflow limit, server-wallet, Guard Mode, 2FA]
+---
+
+# Outflow policy
+
+Your outflow limit caps the total value that can leave the server-wallet in a rolling 24-hour window.
+MetaMask tracks outflows automatically and requests 2-factor authentication approval when a transaction
+would exceed the limit.
+
+Outflow limits apply in **Guard Mode (Recommended)** when using server-wallet.
+See [Trading modes](trading-modes.md) for how Guard Mode enforces this policy alongside other
+guardrails.
+
+## Setting your outflow limit
+
+You're prompted to set your outflow limit on your first transaction, or whenever a transaction would
+exceed your current limit.
+When you set your 24-hour outflow limit, it counts the transaction you're approving now plus all
+subsequent transactions in the rolling window.
+
+## How outflow is calculated
+
+Before signing, MetaMask simulates the transaction value and adds that value to your 24-hour total once
+the transaction is confirmed (submitted successfully).
+
+For example, if you swap 10 USDC to ETH and later swap the ETH to DAI, this counts as a \$10 outflow for
+USDC to ETH and another \$10 for ETH to DAI.
+
+You'll receive a 2-factor authentication request when the transaction exceeds your 24-hour outflow
+limit.
+
+## What's included
+
+The following transaction types count toward your outflow limit:
+
+- Swaps and liquidity deposits (like on Uniswap).
+- Polymarket USDC deposits to deposit addresses and collateral onramp contracts.
+- Hyperliquid deposits to bridge and deposit contracts.
+
+## Limitations
+
+Outflow tracking can be imprecise if transactions are not submitted through our backend.
+
+When an outflow can't be tracked reliably, such as when a transaction can't be simulated, fall back on
+your allowlists.
+
+Signatures (for example, Permit2) are not included in the outflow calculation as of now.
+
+## Related
+
+- [Trading modes](trading-modes.md)
+- [Architecture](architecture.md)

agent-wallet/reference/trading-modes.md

@@ -0,0 +1,111 @@
+---
+description: Guard Mode and Beast Mode trading policies for server-wallet, including guardrails and 2FA approval.
+keywords:
+  [
+    MetaMask,
+    Agent Wallet,
+    trading modes,
+    Guard Mode,
+    Beast Mode,
+    server-wallet,
+    2FA,
+    allowlist,
+    outflow limit,
+  ]
+---
+
+# Trading modes
+
+Trading modes apply to server-wallet only.
+During `mm init`, you are prompted to choose a trading mode.
+
+## Guard Mode vs Beast Mode
+
+Guard Mode enforces all of your policies and asks for approval on anything outside them.
+
+Beast Mode is for power users who want fewer interruptions.
+It still blocks and surfaces dangerous transactions.
+
+:::info
+
+We recommend **Guard Mode** for most users.
+
+:::
+
+## Comparison
+
+### Guardrails
+
+Policies enforced automatically before a transaction can proceed.
+
+| Guardrail                       | Guard Mode | Beast Mode |
+| ------------------------------- | ---------- | ---------- |
+| Threat scanning                 | ✓          | ✓          |
+| Network allowlist               | ✓          | —          |
+| Address allowlist               | ✓          | —          |
+| Token recipient allowlist       | ✓          | —          |
+| Rolling 24-hour outflow limit\* | ✓          | —          |
+
+In Guard Mode, untrusted contracts, networks, and recipients are caught by your allowlists.
+In Beast Mode there are no allowlists.
+
+### Requires 2FA approval
+
+Transactions that pause the job until you approve or reject them.
+
+| Condition                        | Guard Mode | Beast Mode |
+| -------------------------------- | ---------- | ---------- |
+| Malicious transactions           | ✓          | ✓          |
+| Risky contracts                  | ✓          | ✓          |
+| Anything outside your allowlists | ✓          | —          |
+| Raising your outflow limit       | ✓          | —          |
+
+In Beast Mode, only malicious and risky transactions trigger approval.
+
+:::note
+
+See [Outflow policy](outflow-policy.md) for how outflows are tracked.
+
+:::
+
+## Set your trading mode
+
+Set the mode with the `--mode` flag, or pick it at the interactive prompt:
+
+```bash
+mm init --mode guard   # or --mode beast
+```
+
+## How 2FA approval works
+
+When a transaction needs approval, the CLI pauses the job until you approve or reject it.
+The agent cannot proceed on a flagged or policy-violating transaction without your response.
+
+Your sign-in method during `mm login` determines where the approval request is sent:
+
+| Sign-in method                | Approval channel                  |
+| ----------------------------- | --------------------------------- |
+| MetaMask Mobile (QR code)\*\* | MetaMask Mobile push notification |
+| Google or email               | Email link                        |
+
+\*\* QR code sign-in (`mm login qr`) is coming soon.
+
+## Switch modes
+
+Re-run `mm init` with a different `--mode` value to change modes.
+Confirm your active configuration with:
+
+```bash
+mm init show
+```
+
+## Outflow policy
+
+Guard Mode enforces a rolling 24-hour outflow limit on server-wallet outgoing transfers.
+You're prompted to set the limit on your first transaction, or when a transaction would exceed your
+current limit.
+If a transaction would exceed the limit, or you request a higher limit, the CLI requires
+2-factor authentication approval before the transaction proceeds.
+
+See [Outflow policy](outflow-policy.md) for how outflows are calculated, what counts toward the
+limit, and known limitations.

agent-wallet/use-the-cli-directly.md

@@ -26,14 +26,15 @@ mm login
 mm auth status
 ```
 
-During `mm login`, choose QR code, Google, or email.
+During `mm login`, choose Google or email.
+QR code sign-in with MetaMask Mobile is coming soon.
 Your sign-in method also determines how you receive 2FA approvals when a transaction needs your
 confirmation:
 
-| Sign-in method  | 2FA delivery                        |
-| --------------- | ----------------------------------- |
-| QR code         | MetaMask Mobile push notification   |
-| Google or email | Email link with transaction details |
+| Sign-in method        | 2FA delivery                        |
+| --------------------- | ----------------------------------- |
+| Google or email       | Email link with transaction details |
+| QR code (coming soon) | MetaMask Mobile push notification   |
 
 For headless or CI environments:
 
@@ -85,8 +86,7 @@ rolling 24-hour outflow limit.
 Beast Mode keeps only the threat scanning guardrail.
 2FA is required for malicious transactions and risky contracts.
 
-See [Trading modes](reference/architecture.md#trading-modes) for the full guardrail and approval
-lists.
+See [Trading modes](reference/trading-modes.md) for the full guardrail and approval lists.
 
 Switch modes by re-running `mm init` with a different `--mode` value.
 

src/components/SidebarSectionDropdown/configs.ts

@@ -33,6 +33,11 @@ export const SMART_ACCOUNTS_KIT_CONFIG: SidebarStaticTitleProps = {
   pathPattern: '/smart-accounts-kit',
 }
 
+export const AGENT_WALLET_CONFIG: SidebarStaticTitleProps = {
+  title: 'Agent Wallet',
+  pathPattern: '/agent-wallet',
+}
+
 export function isPathInSections(
   pathname: string,
   sections: SidebarSectionDropdownProps['sections']