diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md
index 80c1824..b4fa409 100644
--- a/skills/metamask-agent-wallet/SKILL.md
+++ b/skills/metamask-agent-wallet/SKILL.md
@@ -4,7 +4,7 @@ description: Use when the user asks anything about blockchain wallets, transacti
 license: MIT
 metadata:
   author: metamask
-  version: "3.0.0"
+  version: "3.1.0"
   cliVersion: "2.0.0"
 ---
 
@@ -172,13 +172,22 @@ If the installed `major.minor` differs from the pinned `cliVersion`, or the inst
 
 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).
 
 ## Safety Rules
 
diff --git a/skills/metamask-agent-wallet/workflows/onboarding.md b/skills/metamask-agent-wallet/workflows/onboarding.md
index e479be5..cb04073 100644
--- a/skills/metamask-agent-wallet/workflows/onboarding.md
+++ b/skills/metamask-agent-wallet/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
@@ -45,13 +45,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 +94,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