From 9461b54b72a964c073c5aa30284bf9dccc79ade7 Mon Sep 17 00:00:00 2001 From: Sam Walker Date: Sun, 21 Jun 2026 19:33:05 -0400 Subject: [PATCH 1/4] Gate preflight on mm doctor for auth + init readiness Make `mm doctor` the single readiness gate before any CLI operation, requiring both `authenticated: true` and `initialized: true` before proceeding. Previously the preflight only checked authentication (`mm auth status`), so an authenticated-but-uninitialized session would pass and then fail at runtime with `NOT_INITIALIZED`. Because doctor's hints are sequential (the init hint is gated on being authenticated), call out that fixing login is not a green light and the agent must re-run `mm doctor` after each remediation until clean. Also align onboarding.md to use `mm doctor` for the init check and readiness verification instead of `mm init show` (which itself throws `NOT_INITIALIZED` when uninitialized) and `mm auth status` (which does not reflect initialization). Co-authored-by: Cursor --- skills/metamask-agent-wallet/SKILL.md | 17 ++++++++++++++--- .../workflows/onboarding.md | 14 +++++++------- 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md index 80c1824..18775c4 100644 --- a/skills/metamask-agent-wallet/SKILL.md +++ b/skills/metamask-agent-wallet/SKILL.md @@ -172,13 +172,24 @@ 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). + +**Critical — the hints are sequential, not simultaneous.** When the session is not authenticated, `mm doctor` shows only the login hint and stays silent about initialization (the init hint is gated on being authenticated). So fixing login is **not** a green light: a freshly logged-in session is still uninitialized. Never chain from a remediation straight into operations — always re-run `mm doctor` after each fix and loop until it reports `authenticated: true` and `initialized: true` with no blocking hints. Only then proceed to any wallet, transfer, swap, perps, or predict operation. ## Safety Rules diff --git a/skills/metamask-agent-wallet/workflows/onboarding.md b/skills/metamask-agent-wallet/workflows/onboarding.md index e479be5..587bad3 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 "" ## 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. Do not use `mm init show` to check — it requires an initialized project and throws `NOT_INITIALIZED` on an uninitialized one rather than reporting state. 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 From 3974932492cbad5d2eee70b8bbcbae2912b05ab8 Mon Sep 17 00:00:00 2001 From: Sam Walker Date: Sun, 21 Jun 2026 19:58:08 -0400 Subject: [PATCH 2/4] Trim redundant sequential-hints paragraph from readiness gate The closing paragraph restated the hard gate and re-run-after-remediation instructions already stated above it. Remove it to keep the gate concise. Co-authored-by: Cursor --- skills/metamask-agent-wallet/SKILL.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md index 18775c4..1ebb52a 100644 --- a/skills/metamask-agent-wallet/SKILL.md +++ b/skills/metamask-agent-wallet/SKILL.md @@ -189,8 +189,6 @@ Remediate, then **re-run `mm doctor` and confirm a clean result before doing any - `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). -**Critical — the hints are sequential, not simultaneous.** When the session is not authenticated, `mm doctor` shows only the login hint and stays silent about initialization (the init hint is gated on being authenticated). So fixing login is **not** a green light: a freshly logged-in session is still uninitialized. Never chain from a remediation straight into operations — always re-run `mm doctor` after each fix and loop until it reports `authenticated: true` and `initialized: true` with no blocking hints. Only then proceed to any wallet, transfer, swap, perps, or predict operation. - ## Safety Rules These rules apply to every operation, regardless of which reference or workflow is active. From 2d4cb92dc030f3be07442fa935dda91d02e8a549 Mon Sep 17 00:00:00 2001 From: Sam Walker Date: Sun, 21 Jun 2026 20:05:46 -0400 Subject: [PATCH 3/4] Drop mm init show caveat from onboarding init check The mm doctor instruction is sufficient; the extra mm init show warning was unnecessary detail for the onboarding step. Co-authored-by: Cursor --- skills/metamask-agent-wallet/workflows/onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/metamask-agent-wallet/workflows/onboarding.md b/skills/metamask-agent-wallet/workflows/onboarding.md index 587bad3..cb04073 100644 --- a/skills/metamask-agent-wallet/workflows/onboarding.md +++ b/skills/metamask-agent-wallet/workflows/onboarding.md @@ -51,7 +51,7 @@ First check whether the project is already initialized with `mm doctor` (read it mm doctor ``` -If `initialized` is `true`, skip this step. Do not use `mm init show` to check — it requires an initialized project and throws `NOT_INITIALIZED` on an uninitialized one rather than reporting state. +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. From 1915bb8ce0c344e8f56fbf6e68fbf102f61d888a Mon Sep 17 00:00:00 2001 From: Sam Walker Date: Sun, 21 Jun 2026 20:26:44 -0400 Subject: [PATCH 4/4] Bump metamask-agent-wallet skill to 3.1.0 Minor version bump for the mm doctor readiness gate change. cliVersion stays 2.0.0 (no CLI change); per repo convention, skill content changes within the same CLI major get a minor bump. Co-authored-by: Cursor --- skills/metamask-agent-wallet/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md index 1ebb52a..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" ---