@curdx/flow 2.0.0-beta.9 → 2.0.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-    "version": "2.0.0-beta.9"
+    "version": "2.0.0-beta.18"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.0-beta.9",
+  "version": "2.0.0-beta.18",
   "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
   "author": {
     "name": "wdx",
     "email": "bydongxin@gmail.com"
   },
-  "homepage": "https://github.com/wdx/curdx-flow",
-  "repository": "https://github.com/wdx/curdx-flow",
+  "homepage": "https://github.com/curdx/curdx-flow",
+  "repository": "https://github.com/curdx/curdx-flow",
   "license": "MIT",
   "keywords": [
     "workflow",
@@ -16,21 +16,5 @@
     "orchestration",
     "karpathy",
     "claude-code"
-  ],
-  "mcpServers": {
-    "context7": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@upstash/context7-mcp@latest"
-      ]
-    },
-    "sequential-thinking": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-sequential-thinking"
-      ]
-    }
-  }
+  ]
 }

package/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to CurDX-Flow will be documented here.
 
 ## [Unreleased]
 
+### Fixed
+
+- `hooks/hooks.json` + `hooks/scripts/inject-karpathy.sh` — migrated the L1 baseline injector from the `InstructionsLoaded` event to `SessionStart` with `matcher: "startup|clear|compact"`. Per the Claude Code hooks docs (code.claude.com/docs/en/hooks), `InstructionsLoaded` is an observability-only event: its hook schema has no `hookSpecificOutput` field, so the injector's `{"hookSpecificOutput":{"hookEventName":"InstructionsLoaded","additionalContext":…}}` payload was rejected at session boot with `Hook JSON output validation failed — (root): Invalid input`, producing the `SessionStart:startup hook error` banner on every Claude Code launch. The `startup|clear|compact` matcher preserves the original "baseline survives compaction" intent. Also updated `docs/architecture.md` and `README.zh.md` hook-event inventories.
+
+### BREAKING
+
+- **`context7` and `sequential-thinking` moved from plugin-bundled MCPs to user-level MCPs.** Previously `.claude-plugin/plugin.json` declared both in `mcpServers`, so Claude Code auto-registered them as `plugin:curdx-flow:context7` and `plugin:curdx-flow:sequential-thinking` when the plugin installed. This is no longer the case — the `mcpServers` block is gone. Instead, `curdx-flow install` now runs `claude mcp add context7 …` + `claude mcp add sequential-thinking …` against the user's `~/.claude.json`, which keeps them as standard user-level registrations named `context7` and `sequential-thinking`.
+
+  **Why**: every early adopter who ran `claude mcp add context7 -- npx -y @upstash/context7-mcp --api-key ctx7sk-…` before installing curdx-flow ended up with *both* entries side-by-side — doubling MCP processes, making API-key routing unpredictable (random between free-tier plugin copy and paid user copy), and forcing an awkward env-var migration path. User-level registration matches the way every other MCP in the ecosystem is installed, keeps tool names standard (`mcp__context7__*` instead of `mcp__plugin_curdx-flow_context7__*`), and lets users put an `--api-key` directly in their own entry without any env-var indirection. Every agent / knowledge doc / command in the repo already calls the standard tool-name form, so this is a **zero-change-for-callers** migration.
+
+  **Migration for existing users**:
+
+  ```bash
+  # Upgrade the plugin — this removes the plugin-bundled MCPs and
+  # registers them at user-level (preserving any existing user-level entry
+  # with a custom --api-key).
+  npx @curdx/flow@latest upgrade
+
+  # Restart Claude Code so the plugin manifest reloads.
+  ```
+
+  After upgrade, `claude mcp list` will show `context7` and
+  `sequential-thinking` (user-level) but NOT `plugin:curdx-flow:context7` etc.
+  `npx @curdx/flow doctor` confirms with "user-level (standard)" in the
+  "MCP Servers" section.
+
+### Added
+
+- `cli/registry.js` exports a new `BUNDLED_MCPS` constant — the source-of-truth list of MCPs that `install` registers at user-level and `uninstall` optionally removes.
+- `cli/install.js` Step 3.5 — registers the required MCPs via `claude mcp add`. Detects pre-existing user-level entries (e.g. your hand-configured context7 with an API key) and preserves them instead of overwriting.
+- `cli/uninstall.js` Step 4.5 — asks whether to `claude mcp remove` the registered MCPs (default: no, because other tools may depend on them).
+- `cli/doctor.js` — now reports "user-level (standard)" for each required MCP when it's registered the right way, and "(legacy)" with a migration hint when the old plugin-bundled form is still active.
+
+### Changed
+
+- The "Duplicate MCP" warning in `doctor` (added in beta.11) is now framed as "Legacy plugin-bundled MCPs still present" with a concrete migration command, since the new architecture reserves duplication strictly for the upgrade-transition window.
+- `docs/getting-started.md` "Optional: use your paid context7 API key" section rewritten around the user-level path (add `--api-key` to your `claude mcp add` command) since env-var indirection is no longer the only way to route a key to the plugin copy.
+
+## [2.0.0-beta.11] - 2026-04-22
+
+### Added
+
+- `cli/doctor.js` detects when a user-level MCP in `~/.claude.json` (typically `context7` added via `claude mcp add …`) duplicates a plugin-bundled MCP from `plugin.json` (`plugin:curdx-flow:context7`). Backed by `cli/utils.js:readUserMcpConfig()` + `findDuplicateMcps()` and 3 new tests in `test/utils.test.js`.
+- `docs/getting-started.md` "Optional: use your paid context7 API key" section documenting the env-var path.
+
+## [2.0.0-beta.10] - 2026-04-21
+
+### Fixed
+
+- `cli/utils.js` — `listMcps` rewritten to handle the actual `claude mcp list` format captured from claude 2.1.117. The previous regex matched only a single kebab-case token before the first colon, so `plugin:curdx-flow:context7: npx ...` parsed as name=`plugin` and silently dropped the rest. New parser exports `{ name, plugin, fullName, status, command }` and is fixture-tested in `test/utils.test.js`.
+- `cli/doctor.js` — MCP presence check now accepts both standalone (`context7`) and plugin-bundled (`plugin:curdx-flow:context7`) registrations, with source in the status line. Fixes the same class of false-positive that bit `chrome-devtools` in beta.7. Also gated `--verbose` raw-plugin dump behind `claude` being on PATH, so it no longer runs a meaningless empty child when the CLI is absent.
+- `cli/install.js` — step counter was `1/4`..`4/4` but there are five steps; `Step 5: inject global protocols` was emitted via bare `console.log` so the progress display lied. All five steps now use `log.step(N, 5, ...)`. Also switched `⏳ Installing` and `✅ Install complete` glyphs to the `▸` / `✓` symbols used elsewhere in the project's `log.*` helpers.
+- `cli/uninstall.js` — same `⏳` → `▸` glyph normalisation.
+- `cli/protocols.js` + `cli/utils.js` + `cli/uninstall.js` — switched from `process.env.HOME || ""` to `os.homedir()`. `$HOME` is only guaranteed in interactive login shells; CI containers, some `docker exec` invocations, and non-login spawns can leave it empty, which resolved `GLOBAL_CLAUDE_MD` to `/.claude/CLAUDE.md` and broke `ensureRuntimeInPath` runtime candidate lookup.
+- `bin/curdx-flow.js` — `main()` was called unconditionally at module scope, so `import()` from a test would spawn the CLI, parse the test runner's argv, and `exit(1)`. Now guarded by the ESM direct-invocation idiom (`import.meta.url === pathToFileURL(process.argv[1]).href`). Added one real-import test.
+- `.claude-plugin/plugin.json` — `homepage` and `repository` pointed at `github.com/wdx/curdx-flow` but the authoritative remote is `github.com/curdx/curdx-flow`. Plugin-marketplace UI clicks previously 404'd. Aligned to the real owner.
+- `.github/workflows/npm-publish.yml` — bumped `actions/setup-node` from Node 20 to Node 22 LTS ahead of the 2026-06-02 Node 20 removal.
+- `scripts/release.sh` — lockstep bump of `plugin.json` + `marketplace.json` now parses both files in memory before writing either, with `git checkout -- package.json` auto-revert on failure. Previously the second file could fail to write while the first was already disk-committed.
+
+### Changed
+
+- `commands/start.md` — replaced the brittle `xargs`/`awk`/`sed` flag-parsing block with a model-directed parse that tolerates quoted strings in `$ARGUMENTS` (e.g. `my-feature "Fix user's login bug"` no longer hits `xargs: unmatched quote`).
+- `commands/init.md` — Step 5 used to say "Run `npx @curdx/flow doctor`" but the slash command runs inside Claude Code where a spawned CLI's output doesn't render cleanly. Reframed as "verify inline + suggest the user run the CLI in a separate terminal if they want the full report."
+- `commands/implement.md` — replaced `❌` emoji with `✗` to match the project's own `log.err` helper.
+- `docs/architecture.md` — Hook System section and CLI layout were **entirely fabricated** (listed non-existent hooks `pre-spec.sh` / `post-implement.sh` / `pre-verify.sh` / `post-review.sh` / `on-gate-fail.sh` and bogus paths `cli/bin/flow` / `cli/commands/install.js` / `cli/lib/…`). Rewritten to match the real `hooks/scripts/` layout (4 hooks: session-start / inject-karpathy / quick-mode-guard / stop-watcher) and real `bin/` + `cli/` paths including `cli/registry.js` and the `test/` directory.
+
+### Added
+
+- `test/utils.test.js` grew 5 fixture tests for the new `parseMcpList` against a captured `claude mcp list` output.
+- `test/cli-entrypoints.test.js` — 5 smoke tests that each dynamically-import `cli/doctor.js` / `cli/install.js` / `cli/upgrade.js` / `cli/uninstall.js` and assert the expected top-level function exports. Guards against the "deleted an import but forgot the consumer" class of regression at CI time. Plus one test that imports `bin/curdx-flow.js` now that it no longer runs `main()` at module load.
+
+### Removed (docs compliance)
+
+- Chinese trigger phrases from `skills/*/SKILL.md` descriptions (5 files). Keeping bilingual triggers violated the project's own language-separation rule (`CLAUDE.md`: "Documentation layer = English"). Semantic matching on the English phrases plus the model's own bilingual understanding covers the same invocation surface.
+
+## [2.0.0-beta.9] - 2026-04-21
+
 ### Fixed (P0)
 
 - `cli/utils.js` — `findRuntime()` referenced `existsSync` without importing it; any user whose `bun`/`uv` was not on PATH hit `ReferenceError` during install or doctor.
@@ -18,6 +95,10 @@ All notable changes to CurDX-Flow will be documented here.
 - `commands/start.md` and `commands/spec.md` now produce `.state.json` files that match `schemas/spec-state.schema.json` (field names: `spec_name` / `created` / `updated` / `version`; initial phase is `research`, not the undefined `created`).
 - All python heredocs inside hook scripts use quoted delimiters (`<<'PY'`) and read `STATE_FILE` via `os.environ`, closing a shell→python code-injection surface triggered by unusual spec names.
 
+### Added
+
+- First real test suite — `node --test`-based, 18 regression tests covering `cli/protocols.js`, `cli/registry.js`, and `cli/utils.js`. Wired into `package.json` `scripts.test` and the CI `publish` job so a failing test blocks `npm publish`.
+
 ### Removed
 
 - `hooks/scripts/fail-tracker.sh` and its `PostToolUseFailure` registration — the counter was written but never read by any consumer (the intended pua escalation was never implemented). Can be reintroduced when the consumer exists.

package/README.md

@@ -28,7 +28,9 @@ Not a framework. Not a methodology library. A discipline layer.
 npx @curdx/flow install --all
 ```
 
-This installs the Claude Code plugin (fully offline from the npm package — no GitHub fetch), the 3 auto-registered MCP servers, and three recommended companion plugins (pua, claude-mem, frontend-design).
+This installs the Claude Code plugin (fully offline from the npm package — no GitHub fetch), the official Context7 plugin, the required sequential-thinking MCP server, and four recommended companion plugins (pua, claude-mem, frontend-design, chrome-devtools-mcp).
+
+**Note:** If you're running this command inside the `curdx-flow` project directory itself, use `npx --ignore-existing @curdx/flow install --all` to avoid npx trying to use the local package without dependencies installed.
 
 ## 9 slash commands, that's it
 
@@ -97,7 +99,8 @@ npm i -g @curdx/flow@^1.1
 - **8 composable gates** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 execution strategies** for `/curdx-flow:implement` (linear / subagent / stop-hook / wave, auto-routed)
 - **5 hook events** that enforce the discipline without user action
-- **3 auto-installed MCPs** — context7 (latest docs), sequential-thinking (structured reasoning), chrome-devtools (browser automation)
+- **Required docs/reasoning tools** — Context7 official plugin (MCP + skill + docs agent) and sequential-thinking MCP
+- **4 recommended companion plugins** — pua, claude-mem, frontend-design, chrome-devtools-mcp
 - **Offline-capable install** — the npm package ships the full plugin body; zero GitHub round-trips during install
 
 ## Documentation
@@ -123,7 +126,7 @@ CurDX-Flow v2 is a distillation, not an invention. Ideas we depend on:
 - [**superpowers**](https://github.com/obra/superpowers) — subagent discipline + TDD + two-stage review
 - [**pua**](https://github.com/tanweai/pua) — the three red lines
 - [**claude-mem**](https://github.com/thedotmack/claude-mem) — cross-session memory
-- **Anthropic official** — context7 (Upstash), sequential-thinking, chrome-devtools-mcp, frontend-design skill
+- **MCP / plugin ecosystem** — context7 (Upstash), sequential-thinking, chrome-devtools-mcp (Chrome DevTools team), frontend-design skill
 
 ## License
 

package/README.zh.md

@@ -3,7 +3,7 @@
 > **Claude Code 的 AI 工程工作流元框架**
 > 把 Claude Code 变成有工程纪律的 AI 团队 — 编排 MCP 和插件，强制 Karpathy 4 原则，用规格驱动工作流交付高质量软件。
 
-[![Version](https://img.shields.io/badge/version-1.1.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/npm/v/@curdx/flow.svg)](https://www.npmjs.com/package/@curdx/flow)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Plugin](https://img.shields.io/badge/claude--code-plugin-purple)](https://code.claude.com)
 [![English](https://img.shields.io/badge/doc-English-red)](./README.md)
@@ -16,15 +16,15 @@ CurDX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作
 
 **不重造轮子。编排好轮子。**
 
-## 一览（v1.1.0）
+## 一览（v2）
 
-- **31 个命令** — 初始化 / 研究 / 设计 / 执行 / 验证 / 审查 / 调试 / QA / 安全 / ...
-- **24 个代理** — 15 职能 + 9 人格（Mary / John / Winston / Amelia / Rachel / David / Oliver / Serena / Emma）
+- **9 个命令** — 初始化 / 启动规格 / 规格 / 执行 / 验证 / 审查 / 调试 / fast / 帮助
+- **15 个内部代理** — 由命令调度，不再暴露 v1 的人格角色
 - **8 个可组合 Gate** — Karpathy / Verification / TDD / Coverage / Adversarial / Edge-Case / Security / DevEx
 - **4 种执行策略** — linear / subagent / stop-hook / wave（自动路由）
 - **10 个知识文档** — 规格驱动 / POC-First / 原子提交 / 执行策略 / ...
-- **4 个 hook 事件** — SessionStart / InstructionsLoaded / Stop / PreToolUse
-- **2 个自动安装的 MCP + 1 个推荐插件** — context7 / sequential-thinking（plugin.json 内置）+ chrome-devtools-mcp（recommended，beta.8 解耦）
+- **5 个 hook 事件** — SessionStart / InstructionsLoaded / PostToolUseFailure / Stop / PreToolUse
+- **必需文档/推理工具 + 4 个推荐插件** — Context7 官方插件 / sequential-thinking MCP + pua / claude-mem / frontend-design / chrome-devtools-mcp
 - **优雅降级** — 依赖缺失时进入 fallback 模式并清晰告知
 
 ## 为什么用
@@ -41,23 +41,23 @@ CurDX-Flow 是一个 Claude Code 插件，把 6 个验证过的 AI 工程工作
 
 ## 安装
 
-### 从 marketplace（发布后）
-```
-/plugin marketplace add wdx/curdx-flow
-/plugin install curdx-flow
+```bash
+npx @curdx/flow install --all
 ```
 
+这会用 `claude plugin ...` 非交互 CLI 安装 CurDX-Flow 插件、Context7 官方插件、必需 MCP，并安装推荐插件。
+
+**注意：** 如果你在 `curdx-flow` 项目目录内运行此命令，请使用 `npx --ignore-existing @curdx/flow install --all` 避免 npx 尝试使用本地未安装依赖的包。
+
 ### 本地 dev
 ```bash
-git clone https://github.com/wdx/curdx-flow
+git clone https://github.com/curdx/curdx-flow
 claude --plugin-dir ./curdx-flow
 ```
 
-3 个 MCP 自动装。然后运行：
+安装后在 Claude Code 内运行：
 
 ```
-/curdx-flow:install-deps    # 交互式安装 pua / claude-mem / frontend-design
-/curdx-flow:doctor          # 验证健康
 /curdx-flow:init            # 初始化你的项目
 ```
 
@@ -102,8 +102,8 @@ claude --plugin-dir ./curdx-flow
 | 文档 | 何时读 |
 |-----|------|
 | [`docs/getting-started.md`](./docs/getting-started.md) | 首次使用，5 分钟上手 |
-| [`docs/command-reference.md`](./docs/command-reference.md) | 31 个命令完整参考 |
-| [`docs/agent-reference.md`](./docs/agent-reference.md) | 24 个代理 + 人格 |
+| [`docs/command-reference.md`](./docs/command-reference.md) | 9 个命令完整参考 |
+| [`docs/agent-reference.md`](./docs/agent-reference.md) | 15 个内部代理 |
 | [`docs/workflows.md`](./docs/workflows.md) | 5 种典型场景（greenfield/brownfield/epic/fast/UI） |
 | [`docs/architecture.md`](./docs/architecture.md) | 内部设计（给扩展者） |
 | [`docs/ethos.md`](./docs/ethos.md) | 设计决策的理由 |
@@ -132,7 +132,7 @@ CurDX-Flow 是蒸馏，不是原创。深深致谢：
 - [**pua**](https://github.com/tanweai/pua) — 持续性 + 三条红线
 - [**claude-mem**](https://github.com/thedotmack/claude-mem) — 自动跨会话记忆
 - [**frontend-design skill**](https://claude.ai/skills/frontend-design) — distinctive UI（Anthropic 官方）
-- **context7**（Upstash）+ **sequential-thinking**（Anthropic）+ **chrome-devtools-mcp**（Chrome 团队）
+- **Context7**（Upstash）+ **sequential-thinking**（Anthropic）+ **chrome-devtools-mcp**（Chrome 团队）
 
 ## 许可
 
@@ -140,7 +140,7 @@ MIT。见 [`LICENSE`](./LICENSE)。
 
 ## 贡献
 
-- Issues: https://github.com/wdx/curdx-flow/issues
+- Issues: https://github.com/curdx/curdx-flow/issues
 - 欢迎 PR，但请先用 `/curdx-flow:spec` 自己走一遍（吃自己的狗粮）
 - 社区准则：友善 + 具体 + 不对着 LLM 发火
 

package/bin/curdx-flow.js

@@ -20,6 +20,9 @@
  *                 for the full command/workflow reference)
  */
 
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+
 import { install } from "../cli/install.js";
 import { doctor } from "../cli/doctor.js";
 import { upgrade } from "../cli/upgrade.js";
@@ -128,4 +131,30 @@ async function main() {
   }
 }
 
-main();
+// Only execute main() when invoked directly (`node bin/curdx-flow.js ...`
+// or via the npm bin shim at node_modules/.bin/<name>). When the file is
+// imported by tests or tooling, we want the module graph to load without
+// side-effects.
+//
+// CRITICAL: compare RESOLVED real paths. npm installs the bin as a symlink
+// (node_modules/.bin/curdx-flow → ../@curdx/flow/bin/curdx-flow.js), so
+// process.argv[1] is the symlink path while import.meta.url resolves to
+// the real file. Comparing them directly (the pre-beta.13 behavior)
+// silently skipped main() for every single npx / global-install user,
+// producing a completely broken CLI that exited with no output. Regression
+// caught by user report + reproduced in CI via test/cli-entrypoints.test.js.
+function isInvokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    // argv[1] is not a real filesystem path (e.g. `node -e` eval forms or
+    // a worker pipe). Treat as "not invoked directly" — the caller is
+    // doing something non-standard.
+    return false;
+  }
+}
+
+if (isInvokedDirectly()) {
+  main();
+}

package/cli/README.md

@@ -24,9 +24,11 @@ npx @curdx/flow upgrade
 
 Steps:
 1. Verify the `claude` CLI is installed
-2. `claude plugin marketplace add curdx/curdx-flow`
-3. `claude plugin install curdx-flow@curdx-flow-marketplace` (auto-installs 3 MCPs)
-4. Interactively (or automatically) install recommended plugins: **pua**, **claude-mem**, **frontend-design**
+2. `claude plugin marketplace add --scope user curdx/curdx-flow`
+3. `claude plugin install --scope user curdx-flow@curdx-flow-marketplace`
+4. Install required companion plugin: **context7-plugin@context7-marketplace**
+5. Register required user-level MCP: **sequential-thinking**
+6. Interactively (or automatically) install recommended plugins: **pua**, **claude-mem**, **frontend-design**, **chrome-devtools-mcp**
 
 | Flag | Purpose |
 |------|---------|
@@ -35,7 +37,7 @@ Steps:
 
 ### `doctor [--verbose]`
 
-External diagnostics: claude CLI / curdx-flow / 3 MCPs / 3 recommended plugins / current directory `.flow/` state.
+External diagnostics: claude CLI / curdx-flow / required MCPs / recommended plugins / current directory `.flow/` state.
 
 ### Project initialization (not a CLI command)
 
@@ -50,11 +52,11 @@ This keeps the CLI scoped to install-time and lifecycle operations only — anyt
 
 ### `upgrade`
 
-`claude plugin marketplace update` + `claude plugin update` for every installed curdx-flow-related plugin.
+`claude plugin marketplace update` + `claude plugin update --scope user` for every installed curdx-flow-related plugin.
 
 ### `uninstall [-y] [--keep-recommended] [--purge]`
 
-Inverse of `install`. By default removes only the curdx-flow plugin. With `--purge`, also removes the `~/.local/bin/bun` and `~/.local/bin/uv` symlinks created by install.
+Inverse of `install`. By default removes only the curdx-flow plugin. Recommended plugins are kept unless selected interactively. With `--purge`, also removes third-party marketplaces and the `~/.local/bin/bun` / `~/.local/bin/uv` symlinks created by install.
 
 ## Why a CLI?
 

package/cli/doctor.js

@@ -10,10 +10,13 @@ import {
   runSync,
   claudeVersion,
   listPlugins,
+  listPluginMarketplaces,
   listMcps,
   ensureClaudeMemRuntimes,
+  readUserMcpConfig,
+  findDuplicateMcps,
 } from "./utils.js";
-import { RECOMMENDED_PLUGINS } from "./registry.js";
+import { BUNDLED_MCPS, REQUIRED_PLUGINS, RECOMMENDED_PLUGINS } from "./registry.js";
 
 export async function doctor(args = []) {
   const verbose = args.includes("--verbose") || args.includes("-v");
@@ -50,21 +53,58 @@ export async function doctor(args = []) {
     warnings++;
   }
 
+  const marketplaces = cv ? listPluginMarketplaces() : [];
+  const marketplaceNames = new Set(marketplaces.map((m) => m.name));
+
+  // ---------- Required plugins ----------
+  console.log(`\n${color.bold("Required plugins:")}`);
+  for (const r of REQUIRED_PLUGINS) {
+    const p = plugins.find((x) => x.id === r.id || x.name === r.name);
+    if (r.marketplaceSource && !marketplaceNames.has(r.marketplaceId)) {
+      log.warn(
+        `${r.marketplaceId.padEnd(22)} marketplace missing ${color.dim(`(run: claude plugin marketplace add --scope ${r.scope} ${r.marketplaceSource})`)}`
+      );
+      warnings++;
+    }
+    if (p && p.status === "enabled") {
+      log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version || "unknown"}`)}`);
+    } else if (p && p.status === "failed") {
+      log.err(`${r.name.padEnd(22)} load failed`);
+      errors++;
+    } else {
+      log.warn(
+        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install --scope ${r.scope} ${r.installSpec})`)}`
+      );
+      warnings++;
+    }
+  }
+
   // ---------- MCPs ----------
-  // Bundled by curdx-flow plugin via .claude-plugin/plugin.json mcpServers.
-  // chrome-devtools is NOT here anymore — it was extracted into its own
-  // recommended plugin (see below) to align with the "each MCP owned by one
-  // plugin" model and avoid double-spawning the chrome-devtools-mcp process.
-  console.log(`\n${color.bold("MCP Servers:")}`);
+  console.log(`\n${color.bold("MCP Servers (required by L2 mandatory tools):")}`);
   const mcps = cv ? listMcps() : [];
-  const expectedMcps = ["context7", "sequential-thinking"];
-  for (const m of expectedMcps) {
-    const found = mcps.find((x) => x.name === m);
-    if (found) {
-      log.ok(`${m.padEnd(22)} ${color.dim("auto-loaded")}`);
+  for (const expected of BUNDLED_MCPS) {
+    const m = expected.name;
+    // Beta.12 onward: the required MCPs are registered at user-level
+    // (via `claude mcp add`), NOT plugin-bundled. Both still show up in
+    // `claude mcp list`. Accept a standalone user-level registration
+    // as the primary form, and warn if only a plugin-bundled copy exists
+    // (because that's the legacy layout that beta.11 had).
+    const userLevel = mcps.find((x) => x.name === m && x.plugin === null);
+    const pluginLevel = mcps.find((x) => x.name === m && x.plugin !== null);
+
+    if (userLevel) {
+      log.ok(`${m.padEnd(22)} ${color.dim("user-level (standard)")}`);
+    } else if (pluginLevel) {
+      log.warn(
+        `${m.padEnd(22)} registered via plugin:${pluginLevel.plugin} (legacy). ` +
+          `Run ${color.cyan("npx @curdx/flow install --all")} to migrate to user-level.`
+      );
+      warnings++;
     } else {
       if (curdx) {
-        log.warn(`${m.padEnd(22)} not shown in claude mcp list (restart Claude Code may fix)`);
+        log.warn(
+          `${m.padEnd(22)} missing. Run: ${color.cyan(`claude mcp add --scope user ${m} -- ${expected.command} ${expected.args.join(" ")}`)}`
+        );
         warnings++;
       } else {
         log.info(`${m.padEnd(22)} waiting for curdx-flow install`);
@@ -76,7 +116,13 @@ export async function doctor(args = []) {
   console.log(`\n${color.bold("Recommended plugins:")}`);
   let claudeMemEnabled = false;
   for (const r of RECOMMENDED_PLUGINS) {
-    const p = plugins.find((x) => x.name === r.name);
+    const p = plugins.find((x) => x.id === r.id || x.name === r.name);
+    if (r.marketplaceSource && !marketplaceNames.has(r.marketplaceId)) {
+      log.warn(
+        `${r.marketplaceId.padEnd(22)} marketplace missing ${color.dim(`(run: claude plugin marketplace add --scope ${r.scope} ${r.marketplaceSource})`)}`
+      );
+      warnings++;
+    }
     if (p && p.status === "enabled") {
       log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version}`)}`);
       if (r.postInstall === "claude-mem-runtimes") claudeMemEnabled = true;
@@ -85,12 +131,39 @@ export async function doctor(args = []) {
       errors++;
     } else {
       log.warn(
-        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install ${r.installSpec})`)}`
+        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install --scope ${r.scope} ${r.installSpec})`)}`
       );
       warnings++;
     }
   }
 
+  // ---------- Legacy plugin-bundled MCP residue (beta.11 and earlier) ----------
+  // Beta.12 moved context7 + sequential-thinking to user-level registration.
+  // If both a user-level and a plugin-bundled copy are visible, the user
+  // was likely installed from an older beta.7-beta.11 that still had
+  // mcpServers in plugin.json and a `claude mcp update` hasn't refreshed
+  // the plugin cache yet. Point them at the migration command.
+  if (cv) {
+    const userCfg = readUserMcpConfig();
+    const duplicates = findDuplicateMcps(mcps, userCfg);
+    if (duplicates.length > 0) {
+      console.log(`\n${color.bold("Legacy plugin-bundled MCPs still present:")}`);
+      for (const d of duplicates) {
+        log.warn(
+          `${d.name.padEnd(22)} both user-level AND plugin:${d.pluginEntry.plugin} active`
+        );
+        console.log(
+          color.dim(
+            `     → Migration: ${color.cyan(`claude plugin update curdx-flow@curdx-flow-marketplace`)}\n` +
+              `                  then restart Claude Code. Beta.12+ removes plugin-bundled\n` +
+              `                  versions in favor of the user-level entry you already have.`
+          )
+        );
+        warnings++;
+      }
+    }
+  }
+
   // ---------- Runtime PATH guards (only if claude-mem is installed) ----------
   if (claudeMemEnabled) {
     console.log(`\n${color.bold("Runtime (claude-mem dependencies):")}`);
@@ -149,7 +222,9 @@ export async function doctor(args = []) {
     console.log(color.green("Summary: all healthy ✓"));
   }
 
-  if (verbose) {
+  if (verbose && cv) {
+    // Only call claude when it is actually on PATH; otherwise we spawn a
+    // child that fails silently and print a blank block.
     console.log(`\n${color.bold("Details:")}`);
     console.log(color.dim(`  Plugins raw:`));
     console.log(runSync("claude", ["plugin", "list"]).stdout);