MetaMask · chaitanyapotti · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # MetaMask Agent CLI Skills
 
-SKILLs for the MetaMask Agent CLI (`@metamask/agentic-cli` v2.0.0). These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, and more using the MetaMask Agent CLI.
+SKILLs for the MetaMask Agent CLI (`@metamask/agentic-cli` v3.0.0). These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, and more using the MetaMask Agent CLI.
 
 ## Skills
 

diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md
@@ -4,8 +4,8 @@ description: Use when the user asks anything about blockchain wallets, transacti
 license: MIT
 metadata:
   author: metamask
-  version: "3.1.0"
-  cliVersion: "2.0.0"
+  version: "4.0.0"
+  cliVersion: "3.0.0"
 ---
 
 # MetaMask Agentic CLI Skill
@@ -25,8 +25,7 @@ Match the user's intent to a command and reference file, then read the reference
 | Choose a wallet mode and set up policies | `mm init` | [auth.md](references/auth.md) |
 | Show current init settings | `mm init show` | [auth.md](references/auth.md) |
 | Sign in via QR code with MetaMask Mobile | `mm login qr` | [auth.md](references/auth.md) |
-| Sign in via Google | `mm login google` | [auth.md](references/auth.md) |
-| Sign in via email OTP | `mm login email` | [auth.md](references/auth.md) |
+| Sign in via browser (Google or Email) | `mm login browser` | [auth.md](references/auth.md) |
 | Sign out | `mm logout` | [auth.md](references/auth.md) |
 | Reset CLI session | `mm reset` | [auth.md](references/auth.md) |
 | Show CLI configuration | `mm config get` | [auth.md](references/auth.md) |
@@ -154,7 +153,7 @@ Run these checks before the first CLI operation in a session, in order.
 
 ### 1. Version compatibility
 
-This skill is written for `@metamask/agentic-cli` **v2.0.0** (see `cliVersion` in the frontmatter). Check the installed version:
+This skill is written for `@metamask/agentic-cli` **v3.0.0** (see `cliVersion` in the frontmatter). Check the installed version:
 
 ```bash
 mm --version
@@ -168,7 +167,7 @@ npm view @metamask/agentic-cli version
 
 If the installed `major.minor` differs from the pinned `cliVersion`, or the installed version is behind the latest release, warn the user once and continue:
 
-> Version mismatch: installed CLI `<installed>`, this skill is pinned to `2.0.0`, latest release is `<latest>`. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agentic-cli@latest`, then re-install the skills with `npx skills add metaMask/agent-skills`.
+> Version mismatch: installed CLI `<installed>`, this skill is pinned to `3.0.0`, latest release is `<latest>`. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agentic-cli@latest`, then re-install the skills with `npx skills add metaMask/agent-skills`.
 
 Run this check once per session. Do not block operations on it.
 

diff --git a/skills/metamask-agent-wallet/references/auth.md b/skills/metamask-agent-wallet/references/auth.md
@@ -60,12 +60,12 @@ mm init show
 
 ## `login` Command
 
-Sign in to the CLI. On a TTY, bare `mm login` shows a method picker (MetaMask Mobile QR, Google, or email). QR is recommended but not auto-selected.
+Sign in to the CLI. On a TTY, bare `mm login` shows a method picker (MetaMask Mobile QR or browser). QR is recommended but not auto-selected. `mm login browser` covers both Google and Email — the user picks interactively in the browser.
 
 ### Syntax
 
 ```bash
-mm login [qr | google | email] [--token <token>] [--timeout <seconds>] [--no-wait]
+mm login [qr | browser] [--token <token>] [--timeout <seconds>] [--no-wait]
 ```
 
 ### Supported Flags
@@ -79,19 +79,18 @@ mm login [qr | google | email] [--token <token>] [--timeout <seconds>] [--no-wai
 ### Example
 
 ```bash
-mm login --no-wait
-mm login google --no-wait
-mm login email --no-wait
+mm login browser --no-wait
 mm login --token "cliToken:cliRefreshToken"
 ```
 
 ### Note
 
 - If already authenticated, the CLI returns `ALREADY_AUTHENTICATED`. Run `mm logout` first, then log in again.
-- `mm login qr` (scan with MetaMask Mobile) is available on non-production builds (dev/uat). On production it returns `COMING_SOON`; use Google or email sign-in instead.
+- `mm login qr` (scan with MetaMask Mobile) is available on non-production builds (dev/uat). On production it returns `COMING_SOON`; use browser sign-in instead.
 - Pairing codes tolerate `-` and whitespace separators (e.g. `608-225` is equivalent to `608225`).
-- Use `mm login google --no-wait` or `mm login email --no-wait` for non-interactive/CI flows. Bare `mm login --no-wait` fails without a TTY because no method is selected.
+- Use `mm login browser --no-wait` for non-interactive/CI flows. The command prints a sign-in URL; the user completes login in the browser (Google or Email). Bare `mm login --no-wait` fails without a TTY because no method is selected.
 - `--no-wait` is not supported with QR login. Complete authentication later with `mm login --token`.
+- After a successful login in server-wallet mode, the CLI automatically syncs existing wallets from the server. Run `mm wallet list` immediately — no need to re-run `mm init`. In BYOK mode, no sync occurs; run `mm init` to configure the wallet.
 
 ## `auth status` Command
 

diff --git a/skills/metamask-agent-wallet/workflows/login.md b/skills/metamask-agent-wallet/workflows/login.md
@@ -6,20 +6,19 @@ Reference command syntax in `references/auth.md`.
 
 ## Flow
 
-1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email.
+1. Ask the user which login method they want: MetaMask Mobile QR or browser (Google / Email).
 2. Execute login.
 3. Verify with token.
 
 ## Login
 
-For non-interactive/CI flows, use Google or email with `--no-wait`:
+For non-interactive/CI flows, use `mm login browser --no-wait`:
 
 ```bash
-mm login google --no-wait
-mm login email --no-wait
+mm login browser --no-wait
 ```
 
-The command prints a sign-in URL.
+The command prints a sign-in URL. The user opens it in a browser and chooses Google or Email to complete sign-in.
 
 `mm login qr` (scan with MetaMask Mobile) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`. QR login keeps the CLI attached to the relay, so it does not support `--no-wait`.
 
@@ -33,6 +32,8 @@ mm login --token "<TOKEN>"
 
 ## Confirm
 
+Run `mm doctor` to verify the session is ready. It reports `authenticated` and `initialized` booleans. Do not proceed until both are `true`. If `initialized` is `false`, follow `workflows/onboarding.md` to run `mm init`.
+
 ```bash
-mm auth status
+mm doctor
 ```
diff --git a/skills/metamask-agent-wallet/workflows/onboarding.md b/skills/metamask-agent-wallet/workflows/onboarding.md
@@ -24,16 +24,15 @@ Then run the version compatibility check from the skill `Preflight` section: com
 
 ## Login Flow
 
-Ask the user which login method they want to use: MetaMask Mobile QR, Google, or Email. QR (`mm login qr`) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`, so fall back to Google or email there.
+Ask the user which login method they want to use: MetaMask Mobile QR or browser (Google or Email). QR (`mm login qr`) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`, so fall back to browser login there.
 
 ### Login
 
 ```bash
-mm login google --no-wait
-mm login email --no-wait
+mm login browser --no-wait
 ```
 
-Use `--no-wait` for non-interactive environments. The command prints a sign-in URL.
+Use `--no-wait` for non-interactive environments. The command prints a sign-in URL; the user completes sign-in in the browser using Google or Email.
 
 ### Verify
 

diff --git a/skills/metamask-agent-workflows/SKILL.md b/skills/metamask-agent-workflows/SKILL.md
@@ -4,8 +4,8 @@ description: Use when the user needs to perform multi-step operations with the M
 license: MIT
 metadata:
   author: metamask
-  version: "3.0.0"
-  cliVersion: "2.0.0"
+  version: "4.0.0"
+  cliVersion: "3.0.0"
 ---
 
 # MetaMask Agent Workflows
@@ -47,7 +47,7 @@ Run these checks before the first CLI operation in a session, in order.
 
 ### 1. Version compatibility
 
-This skill is written for `@metamask/agentic-cli` **v2.0.0** (see `cliVersion` in the frontmatter). Check the installed version:
+This skill is written for `@metamask/agentic-cli` **v3.0.0** (see `cliVersion` in the frontmatter). Check the installed version:
 
 ```bash
 mm --version
@@ -61,17 +61,26 @@ npm view @metamask/agentic-cli version
 
 If the installed `major.minor` differs from the pinned `cliVersion`, or the installed version is behind the latest release, warn the user once and continue:
 
-> Version mismatch: installed CLI `<installed>`, this skill is pinned to `2.0.0`, latest release is `<latest>`. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agentic-cli@latest`, then re-install the skills with `npx skills add metaMask/agent-skills`.
+> Version mismatch: installed CLI `<installed>`, this skill is pinned to `3.0.0`, latest release is `<latest>`. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agentic-cli@latest`, then re-install the skills with `npx skills add metaMask/agent-skills`.
 
 Run this check once per session. Do not block operations on it.
 
-### 2. Authentication
+### 2. Readiness gate (authentication + initialization)
+
+`mm doctor` is the single readiness check. Run it before the first CLI operation in a session:
 
 ```bash
-mm auth status
+mm doctor
 ```
 
-If the user is not authenticated, follow `workflows/onboarding.md` for first time setup, or `workflows/login.md` for login.
+It reports an `authenticated` boolean, an `initialized` boolean, and a list of `hints`. **Do not run any other command until `mm doctor` reports both `authenticated: true` and `initialized: true`.** Authentication and initialization are independent gates: a session can be authenticated while the project has no wallet mode selected, in which case any command that needs a wallet aborts before running with `NOT_INITIALIZED` — "Project not initialized." (hint: Run `mm init` to set up wallet and trading modes.).
+
+A project counts as initialized only when a wallet mode is set — and, for `server-wallet`, a trading mode is set as well (`byok` needs only the wallet mode). Do not use `mm init show` as the check: it requires an initialized project and throws `NOT_INITIALIZED` on an uninitialized one rather than reporting state.
+
+Remediate, then **re-run `mm doctor` and confirm a clean result before doing anything else**:
+
+- `authenticated: false` → follow `workflows/login.md` (or `workflows/onboarding.md` for first-time setup) to run `mm login`.
+- `authenticated: true` and `initialized: false` → follow `workflows/onboarding.md` to run `mm init` and select a wallet mode (and a trading mode for server-wallet).
 
 ## Command Discovery
 

diff --git a/skills/metamask-agent-workflows/workflows/login.md b/skills/metamask-agent-workflows/workflows/login.md
@@ -6,20 +6,19 @@ Reference command syntax in `references/auth.md`.
 
 ## Flow
 
-1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email.
+1. Ask the user which login method they want: MetaMask Mobile QR or browser (Google / Email).
 2. Execute login.
 3. Verify with token.
 
 ## Login
 
-For non-interactive/CI flows, use Google or email with `--no-wait`:
+For non-interactive/CI flows, use `mm login browser --no-wait`:
 
 ```bash
-mm login google --no-wait
-mm login email --no-wait
+mm login browser --no-wait
 ```
 
-The command prints a sign-in URL.
+The command prints a sign-in URL. The user opens it in a browser and chooses Google or Email to complete sign-in.
 
 `mm login qr` (scan with MetaMask Mobile) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`. QR login keeps the CLI attached to the relay, so it does not support `--no-wait`.
 
@@ -36,3 +35,7 @@ mm login --token "<TOKEN>"
 ```bash
 mm auth status
 ```
+
+## After Login
+
+In server-wallet mode, wallets are automatically synced after a successful login. Run `mm wallet list` to see them — no need to run `mm init` if wallets already exist. If no wallets are synced, run `mm init` to create one.
diff --git a/skills/metamask-agent-workflows/workflows/onboarding.md b/skills/metamask-agent-workflows/workflows/onboarding.md
@@ -9,7 +9,7 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`.
 1. Check CLI installation.
 2. Login.
 3. Initialize wallet mode.
-4. Verify auth status.
+4. Verify readiness.
 5. Show wallet address.
 
 ## Check CLI Installation
@@ -24,16 +24,15 @@ Then run the version compatibility check from the skill `Preflight` section: com
 
 ## Login Flow
 
-Ask the user which login method they want to use: MetaMask Mobile QR, Google, or Email. QR (`mm login qr`) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`, so fall back to Google or email there.
+Ask the user which login method they want to use: MetaMask Mobile QR or browser (Google or Email). QR (`mm login qr`) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`, so fall back to browser login there.
 
 ### Login
 
 ```bash
-mm login google --no-wait
-mm login email --no-wait
+mm login browser --no-wait
 ```
 
-Use `--no-wait` for non-interactive environments. The command prints a sign-in URL.
+Use `--no-wait` for non-interactive environments. The command prints a sign-in URL; the user completes sign-in in the browser using Google or Email.
 
 ### Verify
 
@@ -45,13 +44,13 @@ mm login --token "<TOKEN>"
 
 ## Initialize Project
 
-First check if the project is already initialized:
+First check whether the project is already initialized with `mm doctor` (read its `initialized` boolean):
 
 ```bash
-mm init show
+mm doctor
 ```
 
-If already initialized, skip this step.
+If `initialized` is `true`, skip this step.
 
 For server-wallet mode, if the account already has a remote wallet, `mm init` syncs it and reuses the existing trading mode — no trading-mode prompt.
 
@@ -94,13 +93,13 @@ mm wallet password set
 
 Once the mnemonic is encrypted, all subsequent operations that need the private key require the `MM_PASSWORD` environment variable to be set. Never instruct the user to pass `--password` inline.
 
-## Verify Auth Status
+## Verify Readiness
 
 ```bash
-mm auth status
+mm doctor
 ```
 
-Confirm the session is authenticated, the wallet mode is correct, and the token is valid.
+Confirm `mm doctor` reports both `authenticated: true` and `initialized: true` with no blocking hints before proceeding. (`mm auth status` reports only authentication and does not reflect initialization, so it cannot confirm readiness on its own.)
 
 ## Show Wallet Address