From 2f3da9f87b167275147ec848f06f7117bae3d7c5 Mon Sep 17 00:00:00 2001
From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com>
Date: Wed, 10 Jun 2026 21:15:48 +0530
Subject: [PATCH 1/7] Update agent wallet docs

---
 .cursor/rules/product-agent-wallet.mdc        |   2 +-
 agent-wallet-sidebar.js                       |   4 +-
 agent-wallet/quickstart.md                    |  19 +--
 agent-wallet/reference/architecture.md        |  60 +---------
 agent-wallet/reference/commands.md            |   7 +-
 agent-wallet/reference/outflow-policy.md      |  54 +++++++++
 agent-wallet/reference/trading-modes.md       | 111 ++++++++++++++++++
 agent-wallet/use-the-cli-directly.md          |  14 +--
 .../SidebarSectionDropdown/configs.ts         |   5 +
 src/theme/DocSidebar/Desktop/index.tsx        |  16 +++
 src/theme/DocSidebar/Mobile/index.tsx         |   7 ++
 11 files changed, 221 insertions(+), 78 deletions(-)
 create mode 100644 agent-wallet/reference/outflow-policy.md
 create mode 100644 agent-wallet/reference/trading-modes.md

diff --git a/.cursor/rules/product-agent-wallet.mdc b/.cursor/rules/product-agent-wallet.mdc
index 216526ab338..27ca11b4184 100644
--- a/.cursor/rules/product-agent-wallet.mdc
+++ b/.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.
diff --git a/agent-wallet-sidebar.js b/agent-wallet-sidebar.js
index a7663f35979..d7540fb5d77 100644
--- a/agent-wallet-sidebar.js
+++ b/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',
diff --git a/agent-wallet/quickstart.md b/agent-wallet/quickstart.md
index fd83183151c..4de58361769 100644
--- a/agent-wallet/quickstart.md
+++ b/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`.
 
diff --git a/agent-wallet/reference/architecture.md b/agent-wallet/reference/architecture.md
index 94f87ca3ba3..e5575b3eb65 100644
--- a/agent-wallet/reference/architecture.md
+++ b/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
 
diff --git a/agent-wallet/reference/commands.md b/agent-wallet/reference/commands.md
index 18ff9c0ab94..7201adc3370 100644
--- a/agent-wallet/reference/commands.md
+++ b/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`
 
diff --git a/agent-wallet/reference/outflow-policy.md b/agent-wallet/reference/outflow-policy.md
new file mode 100644
index 00000000000..ec13e885dde
--- /dev/null
+++ b/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)
diff --git a/agent-wallet/reference/trading-modes.md b/agent-wallet/reference/trading-modes.md
new file mode 100644
index 00000000000..260f7c01ba1
--- /dev/null
+++ b/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.
diff --git a/agent-wallet/use-the-cli-directly.md b/agent-wallet/use-the-cli-directly.md
index c71cda5b675..c2e196c12dd 100644
--- a/agent-wallet/use-the-cli-directly.md
+++ b/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.
 
diff --git a/src/components/SidebarSectionDropdown/configs.ts b/src/components/SidebarSectionDropdown/configs.ts
index 80dba45e6c4..83e4d61054a 100644
--- a/src/components/SidebarSectionDropdown/configs.ts
+++ b/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']
diff --git a/src/theme/DocSidebar/Desktop/index.tsx b/src/theme/DocSidebar/Desktop/index.tsx
index 6de40837ca1..ba98671d99f 100644
--- a/src/theme/DocSidebar/Desktop/index.tsx
+++ b/src/theme/DocSidebar/Desktop/index.tsx
@@ -10,6 +10,7 @@ import SidebarSectionDropdown, {
   SidebarStaticTitle,
 } from '@site/src/components/SidebarSectionDropdown/SidebarSectionDropdown'
 import {
+  AGENT_WALLET_CONFIG,
   SERVICES_DASHBOARD_CONFIG,
   SNAPS_CONFIG,
   SMART_ACCOUNTS_KIT_CONFIG,
@@ -40,6 +41,7 @@ function DocSidebarDesktop({ path, sidebar, onCollapse, isHidden }: Props) {
     SERVICES_DASHBOARD_CONFIG.sections
   )
   const isSnaps = location.pathname.startsWith('/snaps')
+  const isAgentWallet = location.pathname.startsWith('/agent-wallet')
 
   let smartAccountsKitTitle = null
   let versionDropdown = null
@@ -86,6 +88,19 @@ function DocSidebarDesktop({ path, sidebar, onCollapse, isHidden }: Props) {
     console.error('Failed to render Snaps title:', e)
   }
 
+  let agentWalletTitle = null
+  try {
+    if (isAgentWallet) {
+      agentWalletTitle = (
+        <div className={styles.versionDropdownContainer}>
+          <SidebarStaticTitle title={AGENT_WALLET_CONFIG.title} />
+        </div>
+      )
+    }
+  } catch (e) {
+    console.error('Failed to render Agent Wallet title:', e)
+  }
+
   return (
     <div
       className={clsx(
@@ -98,6 +113,7 @@ function DocSidebarDesktop({ path, sidebar, onCollapse, isHidden }: Props) {
       {versionDropdown}
       {servicesDropdown}
       {snapsTitle}
+      {agentWalletTitle}
       <Content path={path} sidebar={sidebar} />
       {hideable && <CollapseButton onClick={onCollapse} />}
     </div>
diff --git a/src/theme/DocSidebar/Mobile/index.tsx b/src/theme/DocSidebar/Mobile/index.tsx
index d822629097d..9e46da61267 100644
--- a/src/theme/DocSidebar/Mobile/index.tsx
+++ b/src/theme/DocSidebar/Mobile/index.tsx
@@ -13,6 +13,7 @@ import SidebarSectionDropdown, {
   SidebarStaticTitle,
 } from '@site/src/components/SidebarSectionDropdown/SidebarSectionDropdown'
 import {
+  AGENT_WALLET_CONFIG,
   SERVICES_DASHBOARD_CONFIG,
   SNAPS_CONFIG,
   SMART_ACCOUNTS_KIT_CONFIG,
@@ -31,6 +32,7 @@ const DocSidebarMobileSecondaryMenu: NavbarSecondaryMenuComponent<Props> = ({ si
     SERVICES_DASHBOARD_CONFIG.sections
   )
   const isSnaps = location.pathname.startsWith('/snaps')
+  const isAgentWallet = location.pathname.startsWith('/agent-wallet')
 
   return (
     <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
@@ -54,6 +56,11 @@ const DocSidebarMobileSecondaryMenu: NavbarSecondaryMenuComponent<Props> = ({ si
           <SidebarStaticTitle title={SNAPS_CONFIG.title} />
         </li>
       )}
+      {isAgentWallet && (
+        <li className={styles.versionDropdownContainer}>
+          <SidebarStaticTitle title={AGENT_WALLET_CONFIG.title} />
+        </li>
+      )}
       <DocSidebarItems
         items={sidebar}
         activePath={path}

From 67ecb896de38e9a62f28c8ede6efc00a39db499c Mon Sep 17 00:00:00 2001
From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com>
Date: Wed, 17 Jun 2026 17:51:35 +0530
Subject: [PATCH 2/7] Update vercel.json

---
 vercel.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/vercel.json b/vercel.json
index f850a1ea4d5..8b96d13ce42 100644
--- a/vercel.json
+++ b/vercel.json
@@ -721,7 +721,7 @@
     },
     {
       "source": "/embedded-wallets/connect-blockchain/xrpl/",
-      "destination": "/embedded-wallets/connect-blockchain/"
+      "destination": "/embedded-wallets/connect-blockchain/other/xrpl/"
     },
     {
       "source": "/embedded-wallets/dashboard/whitelist/",
@@ -729,7 +729,7 @@
     },
     {
       "source": "/embedded-wallets/how-it-works/",
-      "destination": "/embedded-wallets/"
+      "destination": "/embedded-wallets/architecture/"
     },
     {
       "source": "/guide/",

From b0509b31eb56fe5e00cd9c798af0381fe8c13f42 Mon Sep 17 00:00:00 2001
From: Yashovardhan Agrawal <yashovardhan.agrawal@gmail.com>
Date: Wed, 24 Jun 2026 17:15:11 +0530
Subject: [PATCH 3/7] Update agent-wallet/reference/outflow-policy.md

Co-authored-by: matthiasgeihs <62935430+matthiasgeihs@users.noreply.github.com>
---
 agent-wallet/reference/outflow-policy.md | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/agent-wallet/reference/outflow-policy.md b/agent-wallet/reference/outflow-policy.md
index ec13e885dde..a7f179f10d6 100644
--- a/agent-wallet/reference/outflow-policy.md
+++ b/agent-wallet/reference/outflow-policy.md
@@ -33,11 +33,7 @@ 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.
+Our transaction simulation engine analyzes token outflow from your account and estimates the volume in USD. This includes token transfers, swaps, and deposits (e.g., to Uniswap, Polymarket, or Hyperliquid).
 
 ## Limitations
 

From f0bb39a2acd5d5b0e41707e043786305c4179262 Mon Sep 17 00:00:00 2001
From: Yashovardhan Agrawal <yashovardhan.agrawal@gmail.com>
Date: Wed, 24 Jun 2026 17:15:24 +0530
Subject: [PATCH 4/7] Update agent-wallet/reference/outflow-policy.md

Co-authored-by: matthiasgeihs <62935430+matthiasgeihs@users.noreply.github.com>
---
 agent-wallet/reference/outflow-policy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agent-wallet/reference/outflow-policy.md b/agent-wallet/reference/outflow-policy.md
index a7f179f10d6..0af6d608bfb 100644
--- a/agent-wallet/reference/outflow-policy.md
+++ b/agent-wallet/reference/outflow-policy.md
@@ -18,7 +18,7 @@ guardrails.
 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.
+transactions in the rolling window.
 
 ## How outflow is calculated
 

From 683f15a506247564113f11153b6a06b84a1ff265 Mon Sep 17 00:00:00 2001
From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com>
Date: Wed, 24 Jun 2026 17:32:40 +0530
Subject: [PATCH 5/7] Updates for v3

---
 .cursor/rules/product-agent-wallet.mdc        |   2 +-
 agent-wallet-sidebar.js                       |   1 +
 agent-wallet/README.mdx                       |   7 +-
 .../guides/check-balances-and-prices.md       |  10 +
 agent-wallet/guides/lend-and-borrow-aave.md   | 171 ++++++++++++++++
 agent-wallet/guides/swap-and-bridge.md        |  23 +++
 .../guides/trade-prediction-markets.md        |  28 +++
 agent-wallet/quickstart.md                    |  60 ++++--
 agent-wallet/reference/architecture.md        |  11 +-
 agent-wallet/reference/commands.md            | 189 +++++++++++++++---
 agent-wallet/reference/error-codes.md         |  71 ++++---
 agent-wallet/reference/trading-modes.md       |  36 +++-
 agent-wallet/troubleshooting.md               |  59 +++++-
 agent-wallet/use-the-cli-directly.md          |  40 ++--
 14 files changed, 592 insertions(+), 116 deletions(-)
 create mode 100644 agent-wallet/guides/lend-and-borrow-aave.md

diff --git a/.cursor/rules/product-agent-wallet.mdc b/.cursor/rules/product-agent-wallet.mdc
index 27ca11b4184..507b6e724cb 100644
--- a/.cursor/rules/product-agent-wallet.mdc
+++ b/.cursor/rules/product-agent-wallet.mdc
@@ -21,7 +21,7 @@ alwaysApply: false
 
 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 (QR, Google, or email) determines the 2FA approval channel (Mobile push vs email link).
+Sign-in method determines the 2FA approval channel: browser sign-in (Google or email in the MetaMask dashboard) → email link; QR code (MetaMask Mobile) → Mobile push. QR sign-in (`mm login qr`) is not available in production (`COMING_SOON`); document browser sign-in (`mm login browser`) as the production path. Do not document `mm login google` or `mm login email` (removed in CLI v3).
 
 CLI flags use `server-wallet`, `byok`, `guard`, and `beast`.
 
diff --git a/agent-wallet-sidebar.js b/agent-wallet-sidebar.js
index d7540fb5d77..fc882f4be4a 100644
--- a/agent-wallet-sidebar.js
+++ b/agent-wallet-sidebar.js
@@ -27,6 +27,7 @@ const sidebar = {
         'guides/swap-and-bridge',
         'guides/trade-perpetuals',
         'guides/trade-prediction-markets',
+        'guides/lend-and-borrow-aave',
         'guides/check-balances-and-prices',
         'guides/sign-messages-and-transactions',
       ],
diff --git a/agent-wallet/README.mdx b/agent-wallet/README.mdx
index b6feb11edc7..ac55bdbde12 100644
--- a/agent-wallet/README.mdx
+++ b/agent-wallet/README.mdx
@@ -65,14 +65,15 @@ Your agent routes natural-language requests to these commands through installed
 
 | Area                                                                | What your agent can do                                  |
 | ------------------------------------------------------------------- | ------------------------------------------------------- |
-| [Authentication](quickstart.md)                                     | Sign in, check session, sign out                        |
-| [Wallet](guides/check-balances-and-prices.md)                       | Create wallet, show address, check balances             |
+| [Authentication](quickstart.md)                                     | Sign in, verify with `mm doctor`, sign out              |
+| [Wallet](guides/check-balances-and-prices.md)                       | Create wallet, show address, check balances, tx history |
 | [Send](guides/send-tokens.md)                                       | Transfer native tokens and ERC-20s                      |
 | [Sign / raw transactions](guides/sign-messages-and-transactions.md) | Sign messages, typed data, and raw EVM transactions     |
 | [Decode calldata](guides/sign-messages-and-transactions.md)         | Inspect unfamiliar EVM calldata before signing          |
 | [Swap / bridge](guides/swap-and-bridge.md)                          | Quote, execute, and track swaps and cross-chain bridges |
 | [Perpetuals](guides/trade-perpetuals.md)                            | Trade on Hyperliquid (deposit, open, modify, close)     |
-| [Prediction markets](guides/trade-prediction-markets.md)            | Search, quote, and trade on Polymarket                  |
+| [Prediction markets](guides/trade-prediction-markets.md)            | Search, quote, trade, and redeem on Polymarket          |
+| [Aave V3](guides/lend-and-borrow-aave.md)                           | Supply, borrow, repay, and manage lending positions     |
 | [Market data](guides/check-balances-and-prices.md)                  | Spot prices, token discovery, supported chains          |
 
 <!-- vale on -->
diff --git a/agent-wallet/guides/check-balances-and-prices.md b/agent-wallet/guides/check-balances-and-prices.md
index b6f0cd35af7..7c868735722 100644
--- a/agent-wallet/guides/check-balances-and-prices.md
+++ b/agent-wallet/guides/check-balances-and-prices.md
@@ -69,6 +69,16 @@ mm token networks
 mm chains list
 ```
 
+## Transaction history
+
+List recent transactions for your wallets:
+
+```bash
+mm tx history
+mm tx history --chain 1,8453 --limit 20
+mm tx history --type out
+```
+
 ## Related commands
 
 See [Commands reference](../reference/commands.md) for `mm wallet balance`, `mm price`, and
diff --git a/agent-wallet/guides/lend-and-borrow-aave.md b/agent-wallet/guides/lend-and-borrow-aave.md
new file mode 100644
index 00000000000..2c5a00ebed5
--- /dev/null
+++ b/agent-wallet/guides/lend-and-borrow-aave.md
@@ -0,0 +1,171 @@
+---
+description: Supply, borrow, and manage Aave V3 positions using mm wallet commands and the Aave GraphQL API.
+keywords: [MetaMask, Agent Wallet, Aave, DeFi, lending, borrowing, mm]
+---
+
+# Lend and borrow with Aave V3
+
+Supply assets, borrow against collateral, and manage Aave V3 positions through your agent.
+There is no dedicated `mm aave` command.
+Your agent uses `mm wallet` commands together with the [Aave V3 GraphQL API](https://api.v3.aave.com/graphql)
+to build and submit transactions.
+
+Install the `metamask-agent-workflows` skill for multi-step Aave workflow templates.
+
+## Ask your agent
+
+```text
+You (to your agent): "Supply 100 USDC to Aave on Base"
+```
+
+```text
+You (to your agent): "What's my Aave health factor on Ethereum?"
+```
+
+```text
+You (to your agent): "Borrow 0.5 ETH against my USDC collateral on Arbitrum"
+```
+
+Your agent resolves chain and token addresses, queries the Aave API for transaction payloads,
+confirms with you, then submits transactions with `mm wallet send-transaction`.
+
+## Prerequisites
+
+- [Quickstart](../quickstart.md) completed
+- Sufficient token and native-gas balances on the target chain
+- For borrows: supplied collateral with collateral enabled on at least one asset
+
+## Supported chains
+
+| Chain     | Chain ID | Pool address                                 |
+| --------- | -------- | -------------------------------------------- |
+| Ethereum  | 1        | `0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2` |
+| Polygon   | 137      | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Arbitrum  | 42161    | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Optimism  | 10       | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Avalanche | 43114    | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+| Base      | 8453     | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` |
+
+Resolve token contract addresses with `mm token list search --query <SYMBOL> --chain <CHAIN_ID>`.
+
+## Common pattern
+
+Each Aave operation follows the same steps:
+
+1. Get your wallet address: `mm wallet address`
+2. Check balances or positions on the target chain
+3. Query the Aave V3 GraphQL API for the operation (supply, withdraw, borrow, repay, or collateral
+   toggle)
+4. Handle the response:
+   - **`TransactionRequest`**: confirm with the user, then send with `mm wallet send-transaction`
+   - **`ApprovalRequired`**: send the approval transaction first, then retry the original operation
+   - **`InsufficientBalanceError`**: fund the wallet or bridge tokens to the target chain
+5. Use `--wait` on server-wallet mode and include a descriptive `--intent` when supported
+
+Example transaction submission:
+
+```bash
+mm wallet send-transaction --chain-id <CHAIN_ID> --payload '{"to":"<TO>","value":"0x0","data":"<DATA>"}' --wait
+```
+
+For ERC-20 operations, the transaction `value` is typically `"0x0"`.
+For native token supplies, convert the amount to hex wei in the payload.
+
+Before signing unfamiliar calldata, run `mm decode --payload <0x-calldata>` and confirm the decoded
+intent.
+
+## Supply assets
+
+1. Confirm you hold enough of the supply token and native gas on the chain:
+
+   ```bash
+   mm wallet balance --chain <CHAIN_ID>
+   ```
+
+2. Query the Aave API for a supply execution plan (replace placeholders with your values):
+
+   ```bash
+   curl -s -X POST https://api.v3.aave.com/graphql \
+     -H 'Content-Type: application/json' \
+     -d '{
+       "query": "{ supply(request: { market: \"<POOL_ADDRESS>\", amount: { erc20: { currency: \"<ASSET_ADDRESS>\", value: \"<AMOUNT>\" } }, sender: \"<WALLET_ADDRESS>\", chainId: <CHAIN_ID> }) { __typename ... on TransactionRequest { to from data value chainId } ... on ApprovalRequired { approval { to from data value chainId } originalTransaction { to from data value chainId } } } }"
+     }'
+   ```
+
+3. If the response is `ApprovalRequired`, send the approval transaction, then retry supply.
+4. Confirm recipient, amount, token, and chain before executing.
+
+## Withdraw assets
+
+1. Query your positions (see [Check positions](#check-positions)).
+2. Before a full withdrawal, confirm no outstanding debt remains.
+   Full collateral withdrawal reverts if any debt exists.
+3. Query the Aave API for a withdraw execution plan and submit the transaction after confirmation.
+
+For partial withdrawals with outstanding borrows, preview the health factor impact through the Aave
+API `healthFactorPreview` query before proceeding.
+
+## Borrow assets
+
+1. Confirm supplied collateral with collateral enabled.
+2. Check available borrow capacity and that `borrowCapReached` is not `true` for the target asset.
+3. Preview health factor impact with the Aave `healthFactorPreview` query.
+4. Query the borrow execution plan and submit after confirmation.
+
+## Repay debt
+
+1. Query outstanding borrows from your positions.
+2. Query the Aave API for a repay execution plan.
+3. Handle `ApprovalRequired` if the debt asset is an ERC-20, then submit the repay transaction.
+
+## Toggle collateral
+
+Enable or disable an asset as collateral for borrowing.
+When disabling collateral with outstanding borrows, preview the health factor impact.
+Do not disable collateral if the health factor would drop below 1.0.
+
+## Check positions
+
+Query supply and borrow positions in one request:
+
+```bash
+curl -s -X POST https://api.v3.aave.com/graphql \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": "{ userSupplies(request: { markets: [{ address: \"<POOL_ADDRESS>\", chainId: <CHAIN_ID> }], user: \"<WALLET_ADDRESS>\" }) { currency { symbol decimals } balance { amount { value } usd } apy { formatted } isCollateral } userBorrows(request: { markets: [{ address: \"<POOL_ADDRESS>\", chainId: <CHAIN_ID> }], user: \"<WALLET_ADDRESS>\" }) { currency { symbol decimals } debt { amount { value } usd } apy { formatted } } }"
+  }'
+```
+
+Present supply balances, borrow balances, collateral status, and APY rates to the user.
+
+## Discover markets
+
+List available reserves, supply APY, borrow APY, and liquidity on a chain:
+
+```bash
+curl -s -X POST https://api.v3.aave.com/graphql \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": "{ markets(request: { chainIds: [<CHAIN_ID>] }) { reserves { underlyingToken { symbol decimals } supplyInfo { apy { formatted } } borrowInfo { apy { formatted } availableLiquidity { amount { value } usd } borrowCapReached } isFrozen isPaused } } }"
+  }'
+```
+
+Skip reserves where `isFrozen` or `isPaused` is `true`.
+
+## Common pitfalls
+
+:::caution Confirm before submitting
+Always confirm operation type, token, amount, chain, and health factor impact (for borrows and
+collateral changes) before calling `mm wallet send-transaction`.
+:::
+
+:::caution Guard Mode allowlists
+Aave pool contracts must be permitted by your server-wallet policy in Guard Mode.
+Transactions to untrusted contracts require 2-factor authentication approval.
+:::
+
+## Related commands
+
+- [`mm wallet send-transaction`](../reference/commands.md#mm-wallet-send-transaction)
+- [`mm decode`](../reference/commands.md#mm-decode)
+- [Check balances and prices](check-balances-and-prices.md)
diff --git a/agent-wallet/guides/swap-and-bridge.md b/agent-wallet/guides/swap-and-bridge.md
index a5be9767cc3..18e2b4ea549 100644
--- a/agent-wallet/guides/swap-and-bridge.md
+++ b/agent-wallet/guides/swap-and-bridge.md
@@ -57,6 +57,29 @@ mm swap quote --from USDC --to USDC --amount 10 --from-chain 8453 --to-chain 421
 mm swap execute --quote-id <QUOTE_ID>
 ```
 
+### Send bridged tokens to another address
+
+Add `--to-address` to send output tokens to a recipient other than your wallet.
+Only valid for cross-chain bridges (`--to-chain` differs from `--from-chain`):
+
+```bash
+mm swap quote --from USDC --to USDC --amount 10 --from-chain 8453 --to-chain 42161 --to-address 0x742d35Cc6634C0532925a3b844Bc454e4438f08e
+```
+
+### Top up destination gas (refuel)
+
+When bridging to a chain where you hold no native gas token, add `--refuel` to bundle a small
+destination native-gas top-up into the quote:
+
+```bash
+mm swap quote --from USDC --to USDC --amount 50 --from-chain 1 --to-chain 42161 --refuel
+```
+
+Refuel is opt-in and cross-chain only.
+Do not use `--refuel` when the destination token is the destination chain's native gas asset (for
+example, bridging ETH to Arbitrum ETH).
+The backend returns `NO_QUOTES` in that case.
+
 ## Common pitfalls
 
 :::caution Verify the quote step succeeded
diff --git a/agent-wallet/guides/trade-prediction-markets.md b/agent-wallet/guides/trade-prediction-markets.md
index 3731c81da62..d8ef303f51a 100644
--- a/agent-wallet/guides/trade-prediction-markets.md
+++ b/agent-wallet/guides/trade-prediction-markets.md
@@ -20,6 +20,10 @@ You (to your agent): "Bet 10 USDT on YES for BTC 5-min price up"
 You (to your agent): "Show my open prediction market positions"
 ```
 
+```text
+You (to your agent): "Redeem my winning Polymarket positions"
+```
+
 Your agent runs one-time setup if needed, shows current odds, confirms your bet, then places the
 order.
 
@@ -60,6 +64,14 @@ order.
    mm predict markets search "<QUERY>" --limit 5
    ```
 
+   Browse by event, series, or tag:
+
+   ```bash
+   mm predict events list --tag-slug politics --active
+   mm predict series list --recurrence weekly
+   mm predict tags list
+   ```
+
 2. Preview a quote:
 
    ```bash
@@ -86,8 +98,24 @@ order.
    ```bash
    mm predict orders
    mm predict positions
+   mm predict portfolio
    ```
 
+## Redeem winnings
+
+List redeemable winning positions:
+
+```bash
+mm predict redeem list
+```
+
+Redeem one condition or all winning positions:
+
+```bash
+mm predict redeem <CONDITION_ID> --wait
+mm predict redeem --all --wait
+```
+
 ## Common pitfalls
 
 :::caution One-time setup is required
diff --git a/agent-wallet/quickstart.md b/agent-wallet/quickstart.md
index 4de58361769..ace9747a3e8 100644
--- a/agent-wallet/quickstart.md
+++ b/agent-wallet/quickstart.md
@@ -19,9 +19,11 @@ After setup, use natural language for day-to-day wallet operations.
 ## 1. Install the CLI
 
 ```bash npm2yarn
-npm install -g @metamask/agentic-cli
+npm install -g @metamask/agentic-cli@3
 ```
 
+Run `mm doctor` after install to confirm the CLI version and skill compatibility.
+
 ## 2. Add skills to your agent
 
 Skills teach your agent how to route natural-language requests to `mm` commands and follow safety
@@ -32,7 +34,11 @@ npx skills add MetaMask/agent-skills
 ```
 
 When prompted, install `metamask-agent-wallet` for full command routing.
-Add `metamask-agent-workflows` if you want multi-step workflow templates.
+Add `metamask-agent-workflows` if you want multi-step workflow templates for swaps, bridges,
+perpetuals, prediction markets, and Aave V3 lending.
+
+Reinstall skills if you previously installed an older version (for example, v2.x).
+The current skills target CLI v3.0.0.
 
 ## 3. Complete setup
 
@@ -41,9 +47,10 @@ Use the interactive CLI or ask your agent to walk you through onboarding.
 **Interactive CLI**: run `mm` with no arguments for the REPL, or step through setup:
 
 ```bash
+mm doctor
 mm login
 mm init
-mm auth status
+mm doctor
 ```
 
 **Through your agent**: prompt in natural language:
@@ -55,30 +62,49 @@ Set up MetaMask Agent Wallet: sign me in, help me pick a wallet mode and trading
 Your agent asks which sign-in method, wallet mode, and trading mode you want before running
 commands.
 
+### Verify readiness
+
+Run `mm doctor` before your first wallet operation.
+Do not send transactions until the output shows `authenticated: true` and `initialized: true`.
+
+If either flag is false, follow the hints in the output (sign in, run `mm init`, or reinstall
+skills), then run `mm doctor` again.
+
 ### Sign in
 
-During `mm login`, choose Google or email.
-QR code sign-in with MetaMask Mobile is coming soon.
+During `mm login`, choose **Dashboard (browser)** or **QR code (MetaMask Mobile)**.
+
+- **Browser** (`mm login browser`): sign in through the MetaMask dashboard with Google or email.
+  Use this method in production.
+- **QR code** (`mm login qr`): scan the QR code with MetaMask Mobile.
+  QR sign-in is not available in production; the CLI returns `COMING_SOON` and you should use browser
+  sign-in instead.
+
 Your sign-in method also determines how you receive 2-factor authentication approvals when a
 transaction needs your confirmation.
 
-| Sign-in method        | 2FA delivery                        |
-| --------------------- | ----------------------------------- |
-| Google or email       | Email link with transaction details |
-| QR code (coming soon) | MetaMask Mobile push notification   |
+| Sign-in method            | 2FA delivery                        |
+| ------------------------- | ----------------------------------- |
+| Browser (Google or email) | Email link with transaction details |
+| QR code (MetaMask Mobile) | MetaMask Mobile push notification   |
 
-:::note QR code sign-in (coming soon)
+:::note QR code sign-in
 
-Sign in with MetaMask Mobile by scanning the QR code the CLI displays.
-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 you sign in with MetaMask Mobile, 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.
 
 :::
 
+After a successful sign-in in server-wallet mode, the CLI syncs existing remote wallets from the
+server.
+Run `mm wallet list` to see synced wallets.
+You may not need to run `mm init` if you already have a remote wallet.
+
 ### Initialize wallet
 
-During `mm init`, choose a wallet mode and, for server-wallet, a trading mode.
+If `mm doctor` reports `initialized: false`, run `mm init` and choose a wallet mode and, for
+server-wallet, a trading mode.
 
 #### Wallet mode (choose one)
 
@@ -99,12 +125,14 @@ During `mm init`, choose a wallet mode and, for server-wallet, a trading mode.
 See [Trading modes](reference/trading-modes.md) for guardrails and approval conditions.
 
 Confirm your choices with `mm init show`.
+View wallet policy YAML with `mm wallet policy get`.
 
 For headless or CI environments, see [Use the CLI directly](use-the-cli-directly.md).
 
 ## 4. Transfer funds and verify
 
-Fund the address shown by your agent or by `mm wallet address`.
+Fund the address shown by your agent, by `mm wallet address`, or with `mm wallet add-fund` to display
+a QR code and address.
 
 Verify with a natural-language prompt:
 
@@ -112,7 +140,7 @@ Verify with a natural-language prompt:
 What's my wallet address and balance?
 ```
 
-Your agent checks auth and queries balances before you send transactions.
+Your agent runs `mm doctor` and queries balances before you send transactions.
 
 ## Next steps
 
diff --git a/agent-wallet/reference/architecture.md b/agent-wallet/reference/architecture.md
index e5575b3eb65..0c2c9589ab7 100644
--- a/agent-wallet/reference/architecture.md
+++ b/agent-wallet/reference/architecture.md
@@ -22,13 +22,15 @@ MetaMask Agent Wallet exposes wallet operations through the `mm` CLI, backed by
 Security is applied by default on every signing and transaction path, backed by Transaction
 Protection.
 
-Transactions through Agent Wallet deemed safe are guaranteed against loss up to $10,000.\*
+Transactions through Agent Wallet deemed safe are guaranteed against loss up to $10,000/month.\*
 See [Transaction Shield](https://support.metamask.io/manage-crypto/transactions/transaction-shield/)
 for eligibility, coverage limits, and terms.
 
 ## CLI and session
 
 - Install `@metamask/agentic-cli` to get the `mm` binary.
+- Run `mm doctor` to verify CLI version, skill compatibility, authentication, and initialization
+  before wallet operations.
 - Session data is stored at `~/.metamask/session.json` with restricted file permissions.
 - Wallet metadata is stored at `~/.metamask/wallets.json`. Predict state is stored at
   `~/.metamask/predict.json`.
@@ -87,8 +89,8 @@ where supported on the target chain.
 ## Trading modes
 
 Trading modes apply to server-wallet only.
-During `mm init`, you set allowlists and choose Guard Mode or Beast Mode to define how those policies
-are enforced.
+During `mm init`, you choose Guard Mode or Beast Mode to define how policies are enforced.
+View and update policy YAML with `mm wallet policy get` and `mm wallet policy set`.
 See [Trading modes](trading-modes.md) for the full guardrail and approval comparison.
 
 ## Server-wallet async model
@@ -98,7 +100,8 @@ When you submit a signing or transaction request in server-wallet mode:
 1. The CLI submits the request to the wallet service.
 2. The service may simulate the transaction, run threat scanning, and evaluate policies.
 3. If policy requires 2-factor authentication or threat scanning flags the transaction, the job
-   enters an `AWAITING_MFA` state until you approve via MetaMask Mobile or email.
+   enters an `AWAITING_MFA` state until you approve via MetaMask Mobile (QR sign-in) or email
+   (browser sign-in).
 4. The CLI returns a `pollingId` unless you pass `--wait`.
 
 Track pending work:
diff --git a/agent-wallet/reference/commands.md b/agent-wallet/reference/commands.md
index 7201adc3370..f832d79dd9c 100644
--- a/agent-wallet/reference/commands.md
+++ b/agent-wallet/reference/commands.md
@@ -16,6 +16,26 @@ All `mm` commands accept global flags unless noted.
 | `--toon`    |       | Shorthand for `--format=toon`                            |
 | `--verbose` | `-v`  | Show debug logs on standard error                        |
 
+## `mm doctor`
+
+Inspect CLI version, installed skills, environment, and session health.
+Does not require authentication or initialization.
+
+```bash
+mm doctor
+```
+
+| Field               | Description                                                                |
+| ------------------- | -------------------------------------------------------------------------- |
+| `authenticated`     | Whether the CLI session is valid                                           |
+| `initialized`       | Whether wallet mode and trading mode are set                               |
+| `recommendedSkills` | Status of `metamask-agent-wallet` and `metamask-agent-workflows`           |
+| `compatible`        | Whether installed skills match the CLI version (`null` if no skills found) |
+| `hints`             | Actionable guidance for missing skills, auth, init, or version mismatch    |
+
+Run before the first wallet operation in a session.
+Do not run wallet commands until both `authenticated` and `initialized` are `true`.
+
 ## `mm init`
 
 Initialize wallet mode and trading mode.
@@ -33,22 +53,31 @@ mm init show
 
 Environment variables: `MM_MNEMONIC`, `MM_PASSWORD` (bring your own wallet encryption).
 
+Use `mm wallet policy get` to view wallet policy YAML.
+Policy is not included in `mm init show` output.
+
 ## `mm login`
 
 Sign in to MetaMask Agent Wallet.
 
 ```bash
-mm login [google | email] [--token <token>] [--no-wait]
-mm login google [--no-wait]
-mm login email [--no-wait]
+mm login [qr | browser] [--token <token>] [--timeout <seconds>] [--no-wait]
+mm login browser [--no-wait]
+mm login qr [--timeout <seconds>]
 ```
 
-QR code sign-in (`mm login qr`) is coming soon.
+On a TTY, bare `mm login` shows a method picker (Dashboard and QR).
+Use `mm login browser` for Google or email sign-in through the MetaMask dashboard.
+QR sign-in (`mm login qr`) is not available in production (`COMING_SOON`).
+
+| Flag        | Required | Description                                                                            |
+| ----------- | -------- | -------------------------------------------------------------------------------------- |
+| `--token`   | No       | Pre-minted token as `cliToken:cliRefreshToken`. Environment variable: `MM_CLI_TOKEN`   |
+| `--timeout` | No       | Seconds to wait for QR or browser callback                                             |
+| `--no-wait` | No       | Print sign-in URL and exit. Use with `browser` in headless mode. Not supported with QR |
 
-| 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                                                           |
+After a successful login in server-wallet mode, the CLI syncs existing remote wallets from the
+server.
 
 ## `mm auth status`
 
@@ -73,9 +102,11 @@ Wallet lifecycle and signing commands.
 ### `mm wallet create`
 
 ```bash
-mm wallet create [--chain-namespace <namespace>] [--name <name>]
+mm wallet create [--chain-namespace <namespace>] [--name <name>] [--trading-mode guard|beast]
 ```
 
+Returns `policyYaml: string | null` in structured output.
+
 ### `mm wallet list`
 
 ```bash
@@ -94,18 +125,74 @@ mm wallet select [--chain-namespace <namespace>] [--id <id>] [--address <address
 mm wallet show [--chain-namespace <namespace>] [--id <id>] [--address <address>] [--name <name>]
 ```
 
+Returns `policyYaml: string | null` in structured output.
+
 ### `mm wallet address`
 
 ```bash
 mm wallet address [--chain-namespace <namespace>]
 ```
 
+### `mm wallet add-fund`
+
+Show a QR code and address to fund the active wallet.
+In headless mode (`--json`), outputs the address only.
+
+```bash
+mm wallet add-fund [--chain-namespace <namespace>]
+```
+
 ### `mm wallet balance`
 
 ```bash
 mm wallet balance [--currency <code>] [--chain <chains>] [--token <token>] [--address <address>]
 ```
 
+### `mm wallet trading-mode get`
+
+Show the current trading mode and active server-wallet address.
+Server-wallet mode only.
+
+```bash
+mm wallet trading-mode get
+```
+
+### `mm wallet trading-mode set`
+
+Set the trading mode for the active server wallet.
+Prompts for confirmation when switching to Beast mode.
+
+```bash
+mm wallet trading-mode set <guard|beast>
+```
+
+### `mm wallet policy get`
+
+Show the policy YAML for the active server wallet.
+Server-wallet mode only.
+
+```bash
+mm wallet policy get
+```
+
+### `mm wallet policy set`
+
+Set the policy YAML for the active server wallet.
+Server-wallet mode only.
+
+```bash
+mm wallet policy set --policy <yaml>
+```
+
+### `mm wallet policy template`
+
+Show the project policy template.
+Server-wallet mode only.
+
+```bash
+mm wallet policy template
+```
+
 ### `mm wallet sign-message`
 
 ```bash
@@ -163,22 +250,51 @@ mm transfer --to <address> --amount <value> --chain-id <id> --token <symbol-or-a
 ### `mm swap quote`
 
 ```bash
-mm swap quote --from <token> --to <token> --amount <amount> --from-chain <chain-id> [--to-chain <chain-id>] [--slippage <percent>]
+mm swap quote --from <token> --to <token> --amount <amount> --from-chain <chain-id> [--to-chain <chain-id>] [--to-address <address>] [--slippage <percent>] [--refuel]
 ```
 
+| Flag           | Required | Description                                                                     |
+| -------------- | -------- | ------------------------------------------------------------------------------- |
+| `--to-chain`   | No       | Destination chain ID. Defaults to `--from-chain` for same-chain swaps           |
+| `--to-address` | No       | Recipient for bridged output tokens. Cross-chain only. Defaults to signer       |
+| `--slippage`   | No       | Maximum slippage as a percentage, 0–100 (default 0.5)                           |
+| `--refuel`     | No       | Bundle destination native-gas top-up into a cross-chain quote. Cross-chain only |
+
+`--refuel` is opt-in and cross-chain only.
+Do not use it when the destination token is the destination chain's native gas asset; the backend
+returns `NO_QUOTES`.
+
 ### `mm swap execute`
 
 ```bash
 mm swap execute --quote-id <id>
-mm swap execute --from <token> --to <token> --amount <amount> --from-chain <chain-id> [--to-chain <chain-id>] [--slippage <percent>]
+mm swap execute --from <token> --to <token> --amount <amount> --from-chain <chain-id> [--to-chain <chain-id>] [--to-address <address>] [--slippage <percent>] [--refuel]
 ```
 
+When executing by `--quote-id`, the persisted quote retains `--to-address` and `--refuel` settings
+from the quote step.
+
 ### `mm swap status`
 
 ```bash
 mm swap status --quote-id <id> [--tx-hash <hash>]
 ```
 
+## `mm tx history`
+
+List recent transactions for the active wallet or specific addresses.
+
+```bash
+mm tx history [--addresses <addrs>] [--chain <chains>] [--type <filter>] [--limit <n>]
+```
+
+| Flag          | Required | Description                                                            |
+| ------------- | -------- | ---------------------------------------------------------------------- |
+| `--addresses` | No       | Comma-separated EVM addresses. Defaults to all EVM wallets for account |
+| `--chain`     | No       | Comma-separated chain filters (for example, `1,137`)                   |
+| `--type`      | No       | Filter by direction (`in`, `out`, `self`) or transaction category      |
+| `--limit`     | No       | Maximum transactions to return (1–500, default 50)                     |
+
 ## `mm perps`
 
 <!-- vale off -->
@@ -210,27 +326,36 @@ Hyperliquid perpetuals commands. Most commands require `--venue hyperliquid`.
 
 Polymarket prediction market commands.
 
-| Command                     | Description                                  |
-| --------------------------- | -------------------------------------------- |
-| `mm predict setup`          | One-time predict setup                       |
-| `mm predict deposit`        | Fund predict deposit wallet                  |
-| `mm predict balance`        | Check predict balance                        |
-| `mm predict mode`           | Set `mainnet` or `testnet`                   |
-| `mm predict auth`           | Refresh predict credentials                  |
-| `mm predict approve`        | Repair approvals                             |
-| `mm predict status`         | Backend status                               |
-| `mm predict markets search` | Search markets                               |
-| `mm predict markets list`   | List markets with filters                    |
-| `mm predict markets get`    | Inspect a market (slug, ID, or condition ID) |
-| `mm predict quote`          | Preview order cost                           |
-| `mm predict place`          | Place an order                               |
-| `mm predict cancel`         | Cancel orders                                |
-| `mm predict orders`         | List open orders                             |
-| `mm predict positions`      | View positions                               |
-| `mm predict withdraw`       | Withdraw pUSD from deposit wallet            |
-| `mm predict book`           | Order book for a token                       |
-| `mm predict watch`          | Watch a predict job                          |
-| `mm predict geoblock`       | Check Polymarket geoblock for your IP        |
+| Command                     | Description                                              |
+| --------------------------- | -------------------------------------------------------- |
+| `mm predict setup`          | One-time predict setup                                   |
+| `mm predict deposit`        | Fund predict deposit wallet                              |
+| `mm predict balance`        | Check predict balance                                    |
+| `mm predict mode`           | Set `mainnet` or `testnet`                               |
+| `mm predict auth`           | Refresh predict credentials                              |
+| `mm predict approve`        | Repair approvals                                         |
+| `mm predict status`         | Backend status                                           |
+| `mm predict portfolio`      | Snapshot of pUSD balance, positions, redeemable winnings |
+| `mm predict redeem list`    | List redeemable winning positions                        |
+| `mm predict redeem`         | Redeem one or all winning positions                      |
+| `mm predict markets search` | Search markets                                           |
+| `mm predict markets list`   | List markets with filters                                |
+| `mm predict markets get`    | Inspect a market (slug, ID, or condition ID)             |
+| `mm predict events list`    | List Polymarket events with filters                      |
+| `mm predict events get`     | Retrieve a single event by ID or slug                    |
+| `mm predict series list`    | List event series                                        |
+| `mm predict series get`     | Retrieve a single event series                           |
+| `mm predict tags list`      | List Polymarket tags                                     |
+| `mm predict tags get`       | Retrieve a tag by ID or slug                             |
+| `mm predict quote`          | Preview order cost                                       |
+| `mm predict place`          | Place an order                                           |
+| `mm predict cancel`         | Cancel orders                                            |
+| `mm predict orders`         | List open orders                                         |
+| `mm predict positions`      | View positions                                           |
+| `mm predict withdraw`       | Withdraw pUSD from deposit wallet                        |
+| `mm predict book`           | Order book for a token                                   |
+| `mm predict watch`          | Watch a predict job                                      |
+| `mm predict geoblock`       | Check Polymarket geoblock for your IP                    |
 
 <!-- vale on -->
 
diff --git a/agent-wallet/reference/error-codes.md b/agent-wallet/reference/error-codes.md
index 34e2ea5844e..af0a60a80f8 100644
--- a/agent-wallet/reference/error-codes.md
+++ b/agent-wallet/reference/error-codes.md
@@ -12,45 +12,50 @@ Run `mm <command> --help` for command-specific validation rules.
 
 ## Authentication errors (`AuthError`)
 
-| Code                   | Meaning                                                    |
-| ---------------------- | ---------------------------------------------------------- |
-| `AUTH_FAILED`          | Authentication failed (includes missing refresh token)     |
-| `AUTH_ERROR`           | Generic authentication error                               |
-| `TOKEN_INVALID`        | Invalid CLI token, token pair, or project ID               |
-| `TOKEN_REFRESH_FAILED` | Failed to refresh token                                    |
-| `PAIRING_EXPIRED`      | Pairing session expired                                    |
-| `INVALID_OTP`          | Invalid one-time password                                  |
-| `MWP_TIMEOUT`          | Mobile Wallet Protocol timeout                             |
-| `MWP_CANCELLED`        | Mobile Wallet Protocol cancelled (pairing aborted)         |
-| `LOGOUT_FAILED`        | Sign-out operation failed (includes token revoke failures) |
+| Code                    | Meaning                                                          |
+| ----------------------- | ---------------------------------------------------------------- |
+| `AUTH_FAILED`           | Authentication failed (includes missing refresh token)           |
+| `AUTH_ERROR`            | Generic authentication error                                     |
+| `ALREADY_AUTHENTICATED` | Valid session already exists; run `mm logout` before login       |
+| `COMING_SOON`           | Feature not available (for example, `mm login qr` in production) |
+| `TOKEN_INVALID`         | Invalid CLI token, token pair, or project ID                     |
+| `TOKEN_REFRESH_FAILED`  | Failed to refresh token                                          |
+| `PAIRING_EXPIRED`       | Pairing session expired                                          |
+| `INVALID_OTP`           | Invalid one-time password                                        |
+| `MWP_TIMEOUT`           | Mobile Wallet Protocol timeout                                   |
+| `MWP_CANCELLED`         | Mobile Wallet Protocol cancelled (pairing aborted)               |
+| `LOGOUT_FAILED`         | Sign-out operation failed (includes token revoke failures)       |
 
 ## Validation errors (`ValidationError`)
 
-| Code                          | Meaning                                              |
-| ----------------------------- | ---------------------------------------------------- |
-| `MISSING_FLAG`                | Required flag missing in headless mode               |
-| `MISSING_INPUT`               | Required input is missing                            |
-| `MISSING_CHAIN`               | Chain value is missing                               |
-| `MISSING_CHAIN_ID`            | `--chain-id` is missing                              |
-| `INVALID_CHAIN`               | Chain value is invalid                               |
-| `INVALID_INPUT`               | Invalid user input                                   |
-| `INVALID_TO`                  | Recipient address is invalid                         |
-| `INVALID_TYPED_DATA`          | EIP-712 payload is invalid                           |
-| `INVALID_TRANSACTION_PAYLOAD` | Transaction payload is invalid                       |
-| `CHAIN_ID_MISMATCH`           | Typed-data domain chain ID differs from `--chain-id` |
-| `INVALID_MNEMONIC`            | Bring your own wallet mnemonic is invalid            |
+| Code                          | Meaning                                                     |
+| ----------------------------- | ----------------------------------------------------------- |
+| `MISSING_FLAG`                | Required flag missing in headless mode                      |
+| `MISSING_INPUT`               | Required input is missing                                   |
+| `MISSING_CHAIN`               | Chain value is missing                                      |
+| `MISSING_CHAIN_ID`            | `--chain-id` is missing                                     |
+| `INVALID_CHAIN`               | Chain value is invalid                                      |
+| `INVALID_INPUT`               | Invalid user input                                          |
+| `INVALID_TO`                  | Recipient address is invalid                                |
+| `INVALID_TYPED_DATA`          | EIP-712 payload is invalid                                  |
+| `INVALID_TRANSACTION_PAYLOAD` | Transaction payload is invalid                              |
+| `CHAIN_ID_MISMATCH`           | Typed-data domain chain ID differs from `--chain-id`        |
+| `INVALID_MNEMONIC`            | Bring your own wallet mnemonic is invalid                   |
+| `NOT_INITIALIZED`             | Project not initialized; run `mm init`                      |
+| `INVALID_LIMIT`               | Invalid `--limit` value for `mm tx history` (must be 1–500) |
 
 ## Wallet errors (`WalletError`)
 
-| Code               | Meaning                                          |
-| ------------------ | ------------------------------------------------ |
-| `MISSING_MNEMONIC` | Bring your own wallet mode is missing a mnemonic |
-| `MNEMONIC_LOCKED`  | Mnemonic is password-protected                   |
-| `WRONG_PASSWORD`   | Mnemonic password is incorrect                   |
-| `WALLET_NOT_FOUND` | Wallet not found                                 |
-| `WALLET_ERROR`     | Wallet operation failed                          |
-| `NO_AUTH_TOKEN`    | Missing authentication token                     |
-| `NO_PROJECT_ID`    | Project ID not configured                        |
+| Code                 | Meaning                                          |
+| -------------------- | ------------------------------------------------ |
+| `MISSING_MNEMONIC`   | Bring your own wallet mode is missing a mnemonic |
+| `MNEMONIC_LOCKED`    | Mnemonic is password-protected                   |
+| `WRONG_PASSWORD`     | Mnemonic password is incorrect                   |
+| `WALLET_NOT_FOUND`   | Wallet not found                                 |
+| `WALLET_ERROR`       | Wallet operation failed                          |
+| `NO_AUTH_TOKEN`      | Missing authentication token                     |
+| `NO_PROJECT_ID`      | Project ID not configured                        |
+| `NO_HISTORY_WALLETS` | No EVM wallets found for `mm tx history`         |
 
 ## Swap errors (`SwapCommandError`)
 
diff --git a/agent-wallet/reference/trading-modes.md b/agent-wallet/reference/trading-modes.md
index 260f7c01ba1..a9e05e16f15 100644
--- a/agent-wallet/reference/trading-modes.md
+++ b/agent-wallet/reference/trading-modes.md
@@ -70,7 +70,7 @@ 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:
+Set the mode with the `--mode` flag during `mm init`, or pick it at the interactive prompt:
 
 ```bash
 mm init --mode guard   # or --mode beast
@@ -83,20 +83,36 @@ The agent cannot proceed on a flagged or policy-violating transaction without yo
 
 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.
+| Sign-in method            | Approval channel                  |
+| ------------------------- | --------------------------------- |
+| QR code (MetaMask Mobile) | MetaMask Mobile push notification |
+| Browser (Google or email) | Email link                        |
 
 ## Switch modes
 
-Re-run `mm init` with a different `--mode` value to change modes.
-Confirm your active configuration with:
+Change the active trading mode without re-running `mm init`:
+
+```bash
+mm wallet trading-mode set guard
+mm wallet trading-mode set beast
+```
+
+Switching to Beast Mode prompts for confirmation.
+View the current mode with:
+
+```bash
+mm wallet trading-mode get
+```
+
+## Wallet policy
+
+Guard Mode allowlists and outflow limits are stored as policy YAML on the server wallet.
+View, update, or inspect the template with:
 
 ```bash
-mm init show
+mm wallet policy get
+mm wallet policy set --policy "<yaml>"
+mm wallet policy template
 ```
 
 ## Outflow policy
diff --git a/agent-wallet/troubleshooting.md b/agent-wallet/troubleshooting.md
index bd8575f6447..822da4c3447 100644
--- a/agent-wallet/troubleshooting.md
+++ b/agent-wallet/troubleshooting.md
@@ -7,6 +7,22 @@ keywords: [MetaMask, Agent Wallet, troubleshooting, mm]
 
 Symptom-first fixes for common `mm` CLI issues.
 
+## Start with `mm doctor`
+
+Run `mm doctor` first to inspect CLI version, skill compatibility, authentication, and
+initialization:
+
+```bash
+mm doctor
+```
+
+The output includes `authenticated`, `initialized`, `compatible`, and actionable `hints`.
+Fix each hint, then re-run `mm doctor` until both `authenticated` and `initialized` are `true`.
+
+Authentication and initialization are independent.
+A session can be authenticated but not initialized, which causes `NOT_INITIALIZED` on wallet
+commands.
+
 ## Authentication and access
 
 ### `AUTH_FAILED`, `TOKEN_INVALID`, or `TOKEN_REFRESH_FAILED`
@@ -14,11 +30,39 @@ Symptom-first fixes for common `mm` CLI issues.
 Sign in again:
 
 ```bash
-mm login
+mm login browser
 mm auth status
 ```
 
-For CI or headless agents, use `mm login --token "<cliToken:cliRefreshToken>"`.
+For CI or headless agents:
+
+```bash
+mm login browser --no-wait
+mm login --token "<cliToken:cliRefreshToken>"
+```
+
+### `ALREADY_AUTHENTICATED`
+
+You already have a valid session.
+Run `mm logout` before signing in again.
+
+### `COMING_SOON` on `mm login qr`
+
+QR sign-in is not available in production.
+Use browser sign-in instead:
+
+```bash
+mm login browser
+```
+
+### `NOT_INITIALIZED`
+
+Run setup before wallet commands:
+
+```bash
+mm init
+mm doctor
+```
 
 ### Early Access required
 
@@ -29,8 +73,9 @@ If commands fail with authorization errors after sign-in, confirm your account h
 
 ```bash
 mm reset
-mm login
+mm login browser
 mm init --wallet server-wallet --mode guard
+mm doctor
 ```
 
 ## Perpetuals
@@ -66,6 +111,10 @@ See [Trade prediction markets](guides/trade-prediction-markets.md).
 Liquidity may be unavailable for the token pair or chain. Do not call `mm swap execute` without a
 valid `quoteId` from a successful quote step.
 
+When bridging with `--refuel`, do not use the flag if the destination token is the destination
+chain's native gas asset (for example, bridging ETH to Arbitrum ETH).
+The backend returns no quotes in that case.
+
 ### Swap execute fails after a quote
 
 Re-run `mm swap quote` and execute immediately. Quotes can expire.
@@ -95,8 +144,8 @@ See [Architecture](reference/architecture.md).
 
 ## 2FA approval pending
 
-If a job status is `AWAITING_MFA`, approve or reject the transaction in MetaMask Mobile or through
-the email approval link.
+If a job status is `AWAITING_MFA`, approve or reject the transaction through the channel for your
+sign-in method: MetaMask Mobile push (QR sign-in) or the email approval link (browser sign-in).
 
 ## Related pages
 
diff --git a/agent-wallet/use-the-cli-directly.md b/agent-wallet/use-the-cli-directly.md
index c2e196c12dd..39b459ebd6e 100644
--- a/agent-wallet/use-the-cli-directly.md
+++ b/agent-wallet/use-the-cli-directly.md
@@ -16,37 +16,44 @@ For day-to-day use, prefer [Quickstart](quickstart.md) and prompt your agent in
 ## 1. Install the CLI
 
 ```bash npm2yarn
-npm install -g @metamask/agentic-cli
+npm install -g @metamask/agentic-cli@3
 ```
 
 ## 2. Sign in
 
 ```bash
-mm login
+mm doctor
+mm login browser --no-wait
 mm auth status
 ```
 
-During `mm login`, choose Google or email.
-QR code sign-in with MetaMask Mobile is coming soon.
+During interactive `mm login`, choose **Dashboard (browser)** or **QR code (MetaMask Mobile)**.
 Your sign-in method also determines how you receive 2FA approvals when a transaction needs your
 confirmation:
 
-| Sign-in method        | 2FA delivery                        |
-| --------------------- | ----------------------------------- |
-| Google or email       | Email link with transaction details |
-| QR code (coming soon) | MetaMask Mobile push notification   |
+| Sign-in method            | 2FA delivery                        |
+| ------------------------- | ----------------------------------- |
+| Browser (Google or email) | Email link with transaction details |
+| QR code (MetaMask Mobile) | MetaMask Mobile push notification   |
 
 For headless or CI environments:
 
 ```bash
-mm login google --no-wait
+mm login browser --no-wait
 mm login --token "<cliToken:cliRefreshToken>"
 ```
 
+Bare `mm login --no-wait` fails without a TTY because no sign-in method is selected.
+Use `mm login browser --no-wait` to print a dashboard sign-in URL.
+
 ## 3. Initialize wallet
 
-Run `mm init` and follow the prompts to choose wallet mode and trading mode, or pass flags
-explicitly.
+Run `mm doctor` to check whether `mm init` is required.
+If `initialized` is false, run `mm init` and follow the prompts to choose wallet mode and trading
+mode, or pass flags explicitly.
+
+In server-wallet mode, a successful login may sync existing remote wallets.
+Run `mm wallet list` before `mm init` if you are returning to an existing account.
 
 ### Wallet modes
 
@@ -88,12 +95,19 @@ Beast Mode keeps only the threat scanning guardrail.
 
 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.
+Switch modes with `mm wallet trading-mode set`:
+
+```bash
+mm wallet trading-mode set guard
+mm wallet trading-mode set beast
+```
 
 ### View current settings
 
 ```bash
 mm init show
+mm wallet trading-mode get
+mm wallet policy get
 ```
 
 ## 4. Transfer funds and verify
@@ -102,6 +116,7 @@ Get your Agent Wallet address:
 
 ```bash
 mm wallet address
+mm wallet add-fund
 ```
 
 Transfer funds to this address on the chain you plan to use (from another wallet or exchange).
@@ -127,6 +142,7 @@ Pass `--format json` or `--json` for scripts and automation:
 ```bash
 mm wallet balance --chain 8453 --json
 mm auth status --json
+mm doctor --json
 ```
 
 ## Next steps

From 3ede935dfda5c9a63ae1fe1df3a39f0354166e6f Mon Sep 17 00:00:00 2001
From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com>
Date: Wed, 24 Jun 2026 17:52:35 +0530
Subject: [PATCH 6/7] Fix vale and style guide issues

---
 agent-wallet/README.mdx                        | 17 +++++++++++++++++
 .../guides/check-balances-and-prices.md        |  8 ++++----
 agent-wallet/guides/lend-and-borrow-aave.md    |  2 +-
 agent-wallet/quickstart.md                     |  4 ++--
 agent-wallet/reference/architecture.md         | 10 ++++++++--
 agent-wallet/reference/commands.md             | 18 +++++++++---------
 agent-wallet/reference/error-codes.md          |  2 +-
 agent-wallet/reference/outflow-policy.md       |  9 ++++++++-
 agent-wallet/reference/trading-modes.md        | 12 ++++++------
 agent-wallet/troubleshooting.md                |  4 ++--
 agent-wallet/use-the-cli-directly.md           |  2 +-
 11 files changed, 59 insertions(+), 29 deletions(-)

diff --git a/agent-wallet/README.mdx b/agent-wallet/README.mdx
index ac55bdbde12..818de3ad9b0 100644
--- a/agent-wallet/README.mdx
+++ b/agent-wallet/README.mdx
@@ -37,9 +37,15 @@ Supported EVM transactions pass through a mandatory 3-step pipeline before they
 
 1. **Transaction simulation**: What will this transaction actually do? Balance changes, approvals,
    and gas are surfaced before signing.
+
+<!-- vale off -->
+
 2. **Threat scanning**: Powered by Blockaid and production-tested across millions of MetaMask
    transactions. Malicious transactions get auto-bounced. Flagged transactions require your approval
    before they execute.
+
+<!-- vale on -->
+
 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.
@@ -107,5 +113,16 @@ See [Supported chains](reference/supported-chains.md) for typical networks.
       title: 'Trade perpetuals',
       description: 'Deposit, open, modify, and close Hyperliquid positions.',
     },
+    {
+      href: '/agent-wallet/guides/lend-and-borrow-aave',
+      title: 'Lend and borrow with Aave V3',
+      description: 'Supply, borrow, repay, and manage Aave V3 positions through your agent.',
+    },
+    {
+      href: '/agent-wallet/reference/trading-modes',
+      title: 'Trading modes',
+      description:
+        'Compare Guard Mode and Beast Mode guardrails, 2FA approval, and outflow limits.',
+    },
   ]}
 />
diff --git a/agent-wallet/guides/check-balances-and-prices.md b/agent-wallet/guides/check-balances-and-prices.md
index 7c868735722..224d696ce14 100644
--- a/agent-wallet/guides/check-balances-and-prices.md
+++ b/agent-wallet/guides/check-balances-and-prices.md
@@ -1,6 +1,6 @@
 ---
-description: Check wallet balances, token prices, and discover tokens with mm.
-keywords: [MetaMask, Agent Wallet, balance, price, market data, mm]
+description: Check wallet balances, spot prices, token metadata, and transaction history with mm.
+keywords: [MetaMask, Agent Wallet, balance, price, transaction history, market data, mm]
 ---
 
 # Check balances and prices
@@ -81,5 +81,5 @@ mm tx history --type out
 
 ## Related commands
 
-See [Commands reference](../reference/commands.md) for `mm wallet balance`, `mm price`, and
-`mm token`.
+See [Commands reference](../reference/commands.md) for `mm wallet balance`, `mm price`, `mm token`,
+and [`mm tx history`](../reference/commands.md#mm-tx-history).
diff --git a/agent-wallet/guides/lend-and-borrow-aave.md b/agent-wallet/guides/lend-and-borrow-aave.md
index 2c5a00ebed5..30533401c3f 100644
--- a/agent-wallet/guides/lend-and-borrow-aave.md
+++ b/agent-wallet/guides/lend-and-borrow-aave.md
@@ -6,7 +6,7 @@ keywords: [MetaMask, Agent Wallet, Aave, DeFi, lending, borrowing, mm]
 # Lend and borrow with Aave V3
 
 Supply assets, borrow against collateral, and manage Aave V3 positions through your agent.
-There is no dedicated `mm aave` command.
+Agent Wallet has no dedicated `mm aave` command.
 Your agent uses `mm wallet` commands together with the [Aave V3 GraphQL API](https://api.v3.aave.com/graphql)
 to build and submit transactions.
 
diff --git a/agent-wallet/quickstart.md b/agent-wallet/quickstart.md
index ace9747a3e8..7ce0587a69b 100644
--- a/agent-wallet/quickstart.md
+++ b/agent-wallet/quickstart.md
@@ -1,6 +1,6 @@
 ---
-description: Install the mm CLI, add agent skills, and complete one-time setup through the interactive CLI or your AI agent.
-keywords: [MetaMask, Agent Wallet, quickstart, mm, skills, server-wallet]
+description: Install CLI v3, add agent skills, verify readiness with mm doctor, and complete browser sign-in and wallet setup.
+keywords: [MetaMask, Agent Wallet, quickstart, mm, mm doctor, skills, server-wallet]
 ---
 
 # Quickstart
diff --git a/agent-wallet/reference/architecture.md b/agent-wallet/reference/architecture.md
index 0c2c9589ab7..575e1d07a27 100644
--- a/agent-wallet/reference/architecture.md
+++ b/agent-wallet/reference/architecture.md
@@ -65,12 +65,16 @@ and other failures early.
 
 ## Threat scanning
 
+<!-- vale off -->
+
 Threat scanning is powered by Blockaid and production-tested across millions of MetaMask
 transactions.
 Malicious transactions get auto-bounced.
 When a transaction is flagged, it requires your approval before it executes.
 You receive details in the CLI output and through the approval flow.
 
+<!-- vale on -->
+
 ## Transaction Protection
 
 Eligible transactions deemed safe are backed by Transaction Protection coverage up to
@@ -90,8 +94,10 @@ where supported on the target chain.
 
 Trading modes apply to server-wallet only.
 During `mm init`, you choose Guard Mode or Beast Mode to define how policies are enforced.
-View and update policy YAML with `mm wallet policy get` and `mm wallet policy set`.
-See [Trading modes](trading-modes.md) for the full guardrail and approval comparison.
+Guardrail tables, 2FA approval conditions, mode switching, and outflow limits moved to dedicated
+reference pages.
+See [Trading modes](trading-modes.md) for the full guardrail and approval comparison and
+[Outflow policy](outflow-policy.md) for rolling 24-hour limit details.
 
 ## Server-wallet async model
 
diff --git a/agent-wallet/reference/commands.md b/agent-wallet/reference/commands.md
index f832d79dd9c..8f69755cf31 100644
--- a/agent-wallet/reference/commands.md
+++ b/agent-wallet/reference/commands.md
@@ -76,7 +76,7 @@ QR sign-in (`mm login qr`) is not available in production (`COMING_SOON`).
 | `--timeout` | No       | Seconds to wait for QR or browser callback                                             |
 | `--no-wait` | No       | Print sign-in URL and exit. Use with `browser` in headless mode. Not supported with QR |
 
-After a successful login in server-wallet mode, the CLI syncs existing remote wallets from the
+After you sign in successfully in server-wallet mode, the CLI syncs existing remote wallets from the
 server.
 
 ## `mm auth status`
@@ -255,8 +255,8 @@ mm swap quote --from <token> --to <token> --amount <amount> --from-chain <chain-
 
 | Flag           | Required | Description                                                                     |
 | -------------- | -------- | ------------------------------------------------------------------------------- |
-| `--to-chain`   | No       | Destination chain ID. Defaults to `--from-chain` for same-chain swaps           |
-| `--to-address` | No       | Recipient for bridged output tokens. Cross-chain only. Defaults to signer       |
+| `--to-chain`   | No       | Destination chain ID. The default is `--from-chain` for same-chain swaps        |
+| `--to-address` | No       | Recipient for bridged output tokens. Cross-chain only. The default is signer    |
 | `--slippage`   | No       | Maximum slippage as a percentage, 0–100 (default 0.5)                           |
 | `--refuel`     | No       | Bundle destination native-gas top-up into a cross-chain quote. Cross-chain only |
 
@@ -288,12 +288,12 @@ List recent transactions for the active wallet or specific addresses.
 mm tx history [--addresses <addrs>] [--chain <chains>] [--type <filter>] [--limit <n>]
 ```
 
-| Flag          | Required | Description                                                            |
-| ------------- | -------- | ---------------------------------------------------------------------- |
-| `--addresses` | No       | Comma-separated EVM addresses. Defaults to all EVM wallets for account |
-| `--chain`     | No       | Comma-separated chain filters (for example, `1,137`)                   |
-| `--type`      | No       | Filter by direction (`in`, `out`, `self`) or transaction category      |
-| `--limit`     | No       | Maximum transactions to return (1–500, default 50)                     |
+| Flag          | Required | Description                                                               |
+| ------------- | -------- | ------------------------------------------------------------------------- |
+| `--addresses` | No       | Comma-separated EVM addresses. The default is all EVM wallets for account |
+| `--chain`     | No       | Comma-separated chain filters (for example, `1,137`)                      |
+| `--type`      | No       | Filter by direction (`in`, `out`, `self`) or transaction category         |
+| `--limit`     | No       | Maximum transactions to return (1–500, default 50)                        |
 
 ## `mm perps`
 
diff --git a/agent-wallet/reference/error-codes.md b/agent-wallet/reference/error-codes.md
index af0a60a80f8..9ff69684956 100644
--- a/agent-wallet/reference/error-codes.md
+++ b/agent-wallet/reference/error-codes.md
@@ -16,7 +16,7 @@ Run `mm <command> --help` for command-specific validation rules.
 | ----------------------- | ---------------------------------------------------------------- |
 | `AUTH_FAILED`           | Authentication failed (includes missing refresh token)           |
 | `AUTH_ERROR`            | Generic authentication error                                     |
-| `ALREADY_AUTHENTICATED` | Valid session already exists; run `mm logout` before login       |
+| `ALREADY_AUTHENTICATED` | Valid session already exists; run `mm logout` before signing in  |
 | `COMING_SOON`           | Feature not available (for example, `mm login qr` in production) |
 | `TOKEN_INVALID`         | Invalid CLI token, token pair, or project ID                     |
 | `TOKEN_REFRESH_FAILED`  | Failed to refresh token                                          |
diff --git a/agent-wallet/reference/outflow-policy.md b/agent-wallet/reference/outflow-policy.md
index 0af6d608bfb..a10837659bb 100644
--- a/agent-wallet/reference/outflow-policy.md
+++ b/agent-wallet/reference/outflow-policy.md
@@ -33,7 +33,14 @@ limit.
 
 ## What's included
 
-Our transaction simulation engine analyzes token outflow from your account and estimates the volume in USD. This includes token transfers, swaps, and deposits (e.g., to Uniswap, Polymarket, or Hyperliquid).
+<!-- vale off -->
+
+Our transaction simulation engine analyzes token outflow from your account and estimates the volume
+in USD.
+This includes token transfers, swaps, and deposits (for example, to Uniswap, Polymarket, or
+Hyperliquid).
+
+<!-- vale on -->
 
 ## Limitations
 
diff --git a/agent-wallet/reference/trading-modes.md b/agent-wallet/reference/trading-modes.md
index a9e05e16f15..5f0cc432d4b 100644
--- a/agent-wallet/reference/trading-modes.md
+++ b/agent-wallet/reference/trading-modes.md
@@ -41,10 +41,10 @@ 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\* | ✓          | —          |
+| Network allowlist               | ✓          | No         |
+| Address allowlist               | ✓          | No         |
+| Token recipient allowlist       | ✓          | No         |
+| Rolling 24-hour outflow limit\* | ✓          | No         |
 
 In Guard Mode, untrusted contracts, networks, and recipients are caught by your allowlists.
 In Beast Mode there are no allowlists.
@@ -57,8 +57,8 @@ Transactions that pause the job until you approve or reject them.
 | -------------------------------- | ---------- | ---------- |
 | Malicious transactions           | ✓          | ✓          |
 | Risky contracts                  | ✓          | ✓          |
-| Anything outside your allowlists | ✓          | —          |
-| Raising your outflow limit       | ✓          | —          |
+| Anything outside your allowlists | ✓          | No         |
+| Raising your outflow limit       | ✓          | No         |
 
 In Beast Mode, only malicious and risky transactions trigger approval.
 
diff --git a/agent-wallet/troubleshooting.md b/agent-wallet/troubleshooting.md
index 822da4c3447..037bcb0c0c6 100644
--- a/agent-wallet/troubleshooting.md
+++ b/agent-wallet/troubleshooting.md
@@ -1,6 +1,6 @@
 ---
-description: Diagnose and fix common mm CLI issues.
-keywords: [MetaMask, Agent Wallet, troubleshooting, mm]
+description: Start with mm doctor, then fix authentication, initialization, and common mm CLI errors.
+keywords: [MetaMask, Agent Wallet, troubleshooting, mm doctor, mm]
 ---
 
 # Troubleshooting
diff --git a/agent-wallet/use-the-cli-directly.md b/agent-wallet/use-the-cli-directly.md
index 39b459ebd6e..a778e0b177f 100644
--- a/agent-wallet/use-the-cli-directly.md
+++ b/agent-wallet/use-the-cli-directly.md
@@ -52,7 +52,7 @@ Run `mm doctor` to check whether `mm init` is required.
 If `initialized` is false, run `mm init` and follow the prompts to choose wallet mode and trading
 mode, or pass flags explicitly.
 
-In server-wallet mode, a successful login may sync existing remote wallets.
+In server-wallet mode, a successful sign-in may sync existing remote wallets.
 Run `mm wallet list` before `mm init` if you are returning to an existing account.
 
 ### Wallet modes

From 405e364692c68b8a75091029d75dd7f89f5d81f7 Mon Sep 17 00:00:00 2001
From: Yashovardhan Agrawal <21066442+yashovardhan@users.noreply.github.com>
Date: Wed, 24 Jun 2026 17:57:28 +0530
Subject: [PATCH 7/7] Remove MM agent workflows skill

---
 agent-wallet/guides/lend-and-borrow-aave.md | 2 +-
 agent-wallet/quickstart.md                  | 4 +---
 agent-wallet/reference/commands.md          | 4 ++--
 3 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/agent-wallet/guides/lend-and-borrow-aave.md b/agent-wallet/guides/lend-and-borrow-aave.md
index 30533401c3f..17ff1137004 100644
--- a/agent-wallet/guides/lend-and-borrow-aave.md
+++ b/agent-wallet/guides/lend-and-borrow-aave.md
@@ -10,7 +10,7 @@ Agent Wallet has no dedicated `mm aave` command.
 Your agent uses `mm wallet` commands together with the [Aave V3 GraphQL API](https://api.v3.aave.com/graphql)
 to build and submit transactions.
 
-Install the `metamask-agent-workflows` skill for multi-step Aave workflow templates.
+Install the `metamask-agent-wallet` skill for multi-step Aave workflow templates.
 
 ## Ask your agent
 
diff --git a/agent-wallet/quickstart.md b/agent-wallet/quickstart.md
index 7ce0587a69b..808101db672 100644
--- a/agent-wallet/quickstart.md
+++ b/agent-wallet/quickstart.md
@@ -33,9 +33,7 @@ patterns (confirm before transfers, quote before swaps, and similar rules).
 npx skills add MetaMask/agent-skills
 ```
 
-When prompted, install `metamask-agent-wallet` for full command routing.
-Add `metamask-agent-workflows` if you want multi-step workflow templates for swaps, bridges,
-perpetuals, prediction markets, and Aave V3 lending.
+When prompted, install `metamask-agent-wallet`.
 
 Reinstall skills if you previously installed an older version (for example, v2.x).
 The current skills target CLI v3.0.0.
diff --git a/agent-wallet/reference/commands.md b/agent-wallet/reference/commands.md
index 8f69755cf31..1d465e07c76 100644
--- a/agent-wallet/reference/commands.md
+++ b/agent-wallet/reference/commands.md
@@ -29,7 +29,7 @@ mm doctor
 | ------------------- | -------------------------------------------------------------------------- |
 | `authenticated`     | Whether the CLI session is valid                                           |
 | `initialized`       | Whether wallet mode and trading mode are set                               |
-| `recommendedSkills` | Status of `metamask-agent-wallet` and `metamask-agent-workflows`           |
+| `recommendedSkills` | Status of `metamask-agent-wallet`                                          |
 | `compatible`        | Whether installed skills match the CLI version (`null` if no skills found) |
 | `hints`             | Actionable guidance for missing skills, auth, init, or version mismatch    |
 
@@ -177,7 +177,7 @@ mm wallet policy get
 
 ### `mm wallet policy set`
 
-Set the policy YAML for the active server wallet.
+Set the policy for the active server wallet.
 Server-wallet mode only.
 
 ```bash