@curdx/flow 3.2.0 → 3.3.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to `@curdx/flow` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/) and the project follows [Semantic Versioning](https://semver.org/).
 
+## 3.3.1 — 2026-04-27
+
+### Fixed
+
+- **Silent stalls between phases** — added spinners to the previously-silent windows where flow shells out to `claude plugin list --json` and `claude mcp list` (the latter performs an MCP server health check and can take 5-15 seconds). Affected sites: `install` (state-derivation between marketplace refresh and the multiselect), `update` and `uninstall` (state-derivation at flow entry), and the post-flow CLAUDE.md sync (after install/update/uninstall busts the cache, sync re-queries state). Each now shows `Checking installed state… (claude plugin list / mcp list)` with a result line so the run no longer feels frozen.
+- **CLAUDE.md sync feedback** — replaced the post-hoc `p.log.info` line with a live spinner that converts to a final status line on completion, matching the marketplace-refresh and per-item install UX.
+
+## 3.3.0 — 2026-04-27
+
+### Added
+
+- **CLAUDE.md sync** — every successful `install` / `update` / `uninstall` now rewrites a small managed block in `~/.claude/CLAUDE.md` so Claude Code has session-start knowledge of which tools are installed and when to use each. The block lives between `<!-- BEGIN @curdx/flow v1 -->` / `<!-- END @curdx/flow v1 -->` markers; everything outside is preserved verbatim. Uninstalling all managed items removes the block entirely.
+- **`Pkg.whenToUse` and `Pkg.slashNamespace`** — two new optional registry fields. `whenToUse` is the English trigger fragment shown in the CLAUDE.md "Available tools/plugins" list (e.g. "auto-fires on 2+ failures..."). `slashNamespace` is the slash invocation pattern (e.g. `/pua:*`) — only set on plugins that expose one. Both populated for the six bundled items, sourced from each upstream's own documentation.
+- **Conditional Rules section** — the block's `Rules:` lines are emitted only for currently-installed tools, so the block never advises Claude to use a tool that isn't there. The "plan first" rule names whichever planners (`sequential-thinking`, `claude-mem`) are installed.
+- **`--no-claude-md` flag and `CURDX_FLOW_NO_CLAUDE_MD` env var** — opt out of the CLAUDE.md sync (CI, locked-down filesystems, or users who prefer to manage CLAUDE.md by hand).
+
+### Notes
+
+- Sync is **safe by default**: writes are atomic (tmp + `fs.rename`), partial CLAUDE.md changes are impossible, and a failed sync prints a warning but never aborts a successful install.
+- Forward-compatible: the BEGIN/END regex matches any `v\d+` suffix, so a future `v2` block format will silently replace any pre-existing `v1` block.
+- Block content is always English regardless of `--lang`. CLAUDE.md's audience is Claude itself; English keeps instructions stable and avoids diff churn from alternating language runs.
+
 ## 3.2.0 — 2026-04-26
 
 ### Added

package/README.md

@@ -34,6 +34,28 @@ npx @curdx/flow --lang en    # override language
 | `sequential-thinking` | mcp | `@modelcontextprotocol/server-sequential-thinking` |
 | `context7` | mcp | HTTP — `https://mcp.context7.com/mcp` (optional API key) |
 
+## What it writes to your filesystem
+
+After every successful `install` / `update` / `uninstall`, flow keeps a short managed block in your global `~/.claude/CLAUDE.md` so Claude Code knows at session start which tools are installed and when to use them. The block looks like:
+
+```
+<!-- BEGIN @curdx/flow v1 -->
+## Tool Usage
+
+Available tools/plugins:
+- pua (v3.0.0) — `/pua:*` — auto-fires on 2+ failures or user frustration; ...
+- ...
+
+Rules:
+- Do not call every tool by default; ...
+- ...
+
+Run `npx @curdx/flow` to install / update / uninstall.
+<!-- END @curdx/flow v1 -->
+```
+
+Anything outside the BEGIN/END markers is preserved verbatim — flow only ever rewrites or removes the block itself. Uninstalling all managed items removes the block entirely. Pass `--no-claude-md` (or set `CURDX_FLOW_NO_CLAUDE_MD=1`) to opt out.
+
 ## Requirements
 
 - Node.js >= 20.12

package/dist/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import * as p8 from "@clack/prompts";
+import * as p9 from "@clack/prompts";
 import { defineCommand, runMain } from "citty";
 
 // src/ui/language.ts
@@ -66,7 +66,15 @@ var messages = {
   "chrome.prereqNode": "\u9700\u8981 Node.js >= 20.19\uFF0C\u5F53\u524D\u7248\u672C {current}",
   "chrome.prereqChrome": "\u9700\u8981\u672C\u673A\u5DF2\u5B89\u88C5 Chrome\uFF08chrome-devtools-mcp \u4F1A\u8C03\u7528\u672C\u5730\u6D4F\u89C8\u5668\uFF09",
   "reinstall.uninstalling": "\u5148\u5378\u8F7D\u65E7\u7248\u672C\u2026",
-  "reinstall.installing": "\u5B89\u88C5\u65B0\u7248\u672C\u2026"
+  "reinstall.installing": "\u5B89\u88C5\u65B0\u7248\u672C\u2026",
+  "state.checking": "\u68C0\u67E5\u5DF2\u5B89\u88C5\u72B6\u6001\u2026\uFF08claude plugin list / mcp list\uFF09",
+  "state.checked": "\u5DF2\u68C0\u67E5 {count} \u9879",
+  "claudeMd.syncing": "\u540C\u6B65 ~/.claude/CLAUDE.md \u2026",
+  "claudeMd.synced": "CLAUDE.md \u5DF2\u66F4\u65B0\uFF08{path}\uFF09",
+  "claudeMd.unchanged": "CLAUDE.md \u5DF2\u662F\u6700\u65B0",
+  "claudeMd.removed": "\u5DF2\u4ECE CLAUDE.md \u79FB\u9664 @curdx/flow \u533A\u5757",
+  "claudeMd.skipped": "\u5DF2\u8DF3\u8FC7 CLAUDE.md \u540C\u6B65\uFF08--no-claude-md\uFF09",
+  "claudeMd.failed": "CLAUDE.md \u540C\u6B65\u5931\u8D25\uFF1A{error}"
 };
 var zh_default = messages;
 
@@ -129,7 +137,15 @@ var messages2 = {
   "chrome.prereqNode": "Requires Node.js >= 20.19 (current: {current})",
   "chrome.prereqChrome": "Requires Chrome installed locally (chrome-devtools-mcp drives the local browser)",
   "reinstall.uninstalling": "Uninstalling old version\u2026",
-  "reinstall.installing": "Installing new version\u2026"
+  "reinstall.installing": "Installing new version\u2026",
+  "state.checking": "Checking installed state\u2026 (claude plugin list / mcp list)",
+  "state.checked": "Checked {count} item(s)",
+  "claudeMd.syncing": "Syncing ~/.claude/CLAUDE.md\u2026",
+  "claudeMd.synced": "CLAUDE.md updated ({path})",
+  "claudeMd.unchanged": "CLAUDE.md already up to date",
+  "claudeMd.removed": "Removed @curdx/flow block from CLAUDE.md",
+  "claudeMd.skipped": "Skipped CLAUDE.md sync (--no-claude-md)",
+  "claudeMd.failed": "CLAUDE.md sync failed: {error}"
 };
 var en_default = messages2;
 
@@ -178,10 +194,10 @@ async function initLanguage(override) {
 }
 
 // src/ui/menu.ts
-import * as p7 from "@clack/prompts";
+import * as p8 from "@clack/prompts";
 
 // src/flows/install.ts
-import * as p3 from "@clack/prompts";
+import * as p4 from "@clack/prompts";
 import pc from "picocolors";
 
 // src/runner/state.ts
@@ -200,15 +216,15 @@ async function run(cmd, args) {
     stderr: result.stderr
   };
 }
-async function runStreaming(cmd, args, log4) {
-  log4.message(`$ ${cmd} ${args.join(" ")}`);
+async function runStreaming(cmd, args, log5) {
+  log5.message(`$ ${cmd} ${args.join(" ")}`);
   const proc = x(cmd, args, { throwOnError: false });
   let stdout = "";
   for await (const line of proc) {
     const trimmed = line.replace(/\r?\n$/, "");
     if (trimmed.length > 0) {
       stdout += trimmed + "\n";
-      log4.message(trimmed);
+      log5.message(trimmed);
     }
   }
   const finished = await proc;
@@ -251,15 +267,15 @@ async function listPlugins(force = false) {
   }
   try {
     const arr = JSON.parse(res.stdout);
-    pluginCache = arr.map((p9) => {
-      const [name = p9.id, marketplace = ""] = p9.id.split("@");
+    pluginCache = arr.map((p10) => {
+      const [name = p10.id, marketplace = ""] = p10.id.split("@");
       return {
-        id: p9.id,
+        id: p10.id,
         name,
         marketplace,
-        version: p9.version,
-        scope: p9.scope,
-        enabled: p9.enabled
+        version: p10.version,
+        scope: p10.scope,
+        enabled: p10.enabled
       };
     });
   } catch {
@@ -305,7 +321,7 @@ async function listMcp(force = false) {
 }
 async function isPluginInstalled(id) {
   const list = await listPlugins();
-  return list.some((p9) => p9.id === id);
+  return list.some((p10) => p10.id === id);
 }
 async function isMarketplaceAdded(name) {
   const list = await listMarketplaces();
@@ -317,7 +333,7 @@ async function isMcpInstalled(name) {
 }
 async function findPlugin(id) {
   const list = await listPlugins();
-  return list.find((p9) => p9.id === id);
+  return list.find((p10) => p10.id === id);
 }
 var marketplaceJsonCache = /* @__PURE__ */ new Map();
 function marketplaceDir(name) {
@@ -339,7 +355,7 @@ async function readMarketplaceJson(name) {
 async function getMarketplacePluginVersion(marketplaceName, pluginName) {
   const m = await readMarketplaceJson(marketplaceName);
   if (!m?.plugins) return null;
-  const entry = m.plugins.find((p9) => p9.name === pluginName);
+  const entry = m.plugins.find((p10) => p10.name === pluginName);
   return entry?.version ?? null;
 }
 var REFRESH_TTL_MS = 60 * 60 * 1e3;
@@ -399,11 +415,13 @@ var pua = {
   name: "pua",
   description: "tanweai/pua \u2014 Chinese Claude Code skills bundle",
   type: "plugin",
+  slashNamespace: "/pua:*",
+  whenToUse: "auto-fires on 2+ failures or user frustration; sub-modes p7 / p9 / pro / loop. Skip on first-attempt failures or when a known fix is executing.",
   marketplaces: () => [MARKETPLACE_NAME],
   isInstalled: () => isPluginInstalled(PLUGIN_ID),
   installedVersion: async () => {
-    const p9 = await findPlugin(PLUGIN_ID);
-    const v = p9?.version;
+    const p10 = await findPlugin(PLUGIN_ID);
+    const v = p10?.version;
     return v && v !== "unknown" ? v : null;
   },
   latestVersion: () => getMarketplacePluginVersion(MARKETPLACE_NAME, PLUGIN_NAME),
@@ -426,11 +444,13 @@ var claudeMem = {
   name: "claude-mem",
   description: "thedotmack/claude-mem \u2014 persistent cross-session memory for Claude Code",
   type: "plugin",
+  slashNamespace: "/claude-mem:*",
+  whenToUse: 'for cross-session memory search ("did we solve this before?"), phased planning (`make-plan`), or phased execution (`do`).',
   marketplaces: () => [MARKETPLACE_NAME2],
   isInstalled: () => isPluginInstalled(PLUGIN_ID2),
   installedVersion: async () => {
-    const p9 = await findPlugin(PLUGIN_ID2);
-    const v = p9?.version;
+    const p10 = await findPlugin(PLUGIN_ID2);
+    const v = p10?.version;
     return v && v !== "unknown" ? v : null;
   },
   latestVersion: () => getMarketplacePluginVersion(MARKETPLACE_NAME2, PLUGIN_NAME2),
@@ -461,6 +481,7 @@ var chromeDevtoolsMcp = {
   name: "chrome-devtools-mcp",
   description: "ChromeDevTools/chrome-devtools-mcp \u2014 drive a real Chrome from Claude Code",
   type: "plugin",
+  whenToUse: "when debugging code that runs in a browser: perf traces, network / console inspection, DOM / CSS issues. Prefer snapshot over screenshot.",
   prereqCheck: async (t2) => {
     const major = Number(process.versions.node.split(".")[0] ?? "0");
     const minor = Number(process.versions.node.split(".")[1] ?? "0");
@@ -489,6 +510,7 @@ var frontendDesign = {
   name: "frontend-design",
   description: "Anthropic official \u2014 UI/frontend design helpers",
   type: "plugin",
+  whenToUse: "auto-fires when building UI / web components / pages. Best where visual personality matters (landing, marketing, portfolio).",
   isInstalled: () => isPluginInstalled(PLUGIN_ID4),
   install: (ctx) => installPluginById(PLUGIN_ID4, ctx),
   uninstall: (ctx) => uninstallPluginById(PLUGIN_ID4, ctx),
@@ -503,6 +525,7 @@ var sequentialThinking = {
   name: "sequential-thinking",
   description: "modelcontextprotocol/server-sequential-thinking \u2014 structured reasoning helper",
   type: "mcp",
+  whenToUse: "for complex multi-step problems where assumptions may shift (architecture comparison, risk-assessed migrations, prod-only debugging). Skip for simple queries.",
   isInstalled: () => isMcpInstalled(MCP_NAME),
   install: async (ctx) => {
     const r = await runStreaming(
@@ -543,6 +566,7 @@ var context7 = {
   name: "context7",
   description: "upstash/context7 \u2014 up-to-date docs from any library (HTTP MCP, optional API key)",
   type: "mcp",
+  whenToUse: "for any library / SDK / framework / API / Claude Code docs lookup. Use instead of web search.",
   isInstalled: () => isMcpInstalled(MCP_NAME2),
   configPrompts: async ({ t: t2 }) => {
     p2.note(`${t2("context7.dashboardHint")}
@@ -595,7 +619,187 @@ var PKGS = [
   context7_default
 ];
 function findPkg(id) {
-  return PKGS.find((p9) => p9.id === id);
+  return PKGS.find((p10) => p10.id === id);
+}
+
+// src/runner/claudeMd.ts
+import { promises as fs2 } from "fs";
+import path2 from "path";
+import os2 from "os";
+import * as p3 from "@clack/prompts";
+var BEGIN_MARKER = "<!-- BEGIN @curdx/flow v1 -->";
+var END_MARKER = "<!-- END @curdx/flow v1 -->";
+var BLOCK_RE = /<!-- BEGIN @curdx\/flow v\d+[^>]*-->[\s\S]*?<!-- END @curdx\/flow v\d+ -->/;
+function claudeMdPath() {
+  return path2.join(os2.homedir(), ".claude", "CLAUDE.md");
+}
+function renderItemLine(item) {
+  let line = `- ${item.name}`;
+  if (item.version) line += ` (v${item.version})`;
+  if (item.slashNamespace) line += ` \u2014 \`${item.slashNamespace}\``;
+  if (item.whenToUse) line += ` \u2014 ${item.whenToUse}`;
+  return line;
+}
+var ALWAYS_ON_RULES = [
+  "Do not call every tool by default; pick by the trigger condition above.",
+  "For first-attempt failures or simple edits, skip extra tools."
+];
+function buildConditionalRules(installedIds) {
+  const out = [];
+  const planners = [];
+  if (installedIds.has("sequential-thinking")) planners.push("sequential-thinking");
+  if (installedIds.has("claude-mem")) planners.push("claude-mem `make-plan`");
+  if (planners.length > 0) {
+    out.push(`For complex / risky changes, plan first (${planners.join(" or ")}).`);
+  }
+  if (installedIds.has("context7")) {
+    out.push("For library / SDK lookups, prefer context7 over web search.");
+  }
+  if (installedIds.has("chrome-devtools-mcp")) {
+    out.push("For browser-rendered behavior, verify in chrome-devtools-mcp instead of guessing.");
+  }
+  return out;
+}
+function renderBlock(items) {
+  const installedIds = new Set(items.map((i) => i.id));
+  const rules = [...ALWAYS_ON_RULES, ...buildConditionalRules(installedIds)];
+  return [
+    BEGIN_MARKER,
+    "## Tool Usage",
+    "",
+    "Available tools/plugins:",
+    ...items.map(renderItemLine),
+    "",
+    "Rules:",
+    ...rules.map((r) => `- ${r}`),
+    "",
+    "Run `npx @curdx/flow` to install / update / uninstall.",
+    END_MARKER
+  ].join("\n");
+}
+function withEol(s, eol) {
+  return eol === "\n" ? s : s.split("\n").join(eol);
+}
+function ensureSingleTrailingNewline(s, eol) {
+  if (s.length === 0) return s;
+  return s.replace(/[\r\n]+$/, "") + eol;
+}
+function upsertBlock(existing, blockBody, eol) {
+  const block = withEol(blockBody, eol);
+  if (BLOCK_RE.test(existing)) {
+    return existing.replace(BLOCK_RE, block);
+  }
+  if (existing.length === 0) {
+    return block + eol;
+  }
+  const trimmed = existing.replace(/[\r\n\s]+$/, "");
+  return trimmed + eol + eol + block + eol;
+}
+function removeBlock(existing, eol) {
+  if (!BLOCK_RE.test(existing)) return existing;
+  let next = existing.replace(BLOCK_RE, "");
+  const tripleEol = new RegExp(`(?:\\r?\\n){3,}`, "g");
+  next = next.replace(tripleEol, eol + eol);
+  if (next.replace(/[\s\r\n]/g, "").length === 0) return "";
+  return ensureSingleTrailingNewline(next, eol);
+}
+async function pkgToItem(pkg) {
+  let version;
+  if (pkg.installedVersion) {
+    const v = await pkg.installedVersion();
+    if (v) version = v;
+  }
+  return {
+    id: pkg.id,
+    name: pkg.name,
+    type: pkg.type,
+    version,
+    whenToUse: pkg.whenToUse,
+    slashNamespace: pkg.slashNamespace
+  };
+}
+async function collectInstalledItems() {
+  await Promise.all([listPlugins(true), listMcp(true)]);
+  const items = [];
+  for (const pkg of PKGS) {
+    if (await pkg.isInstalled()) {
+      items.push(await pkgToItem(pkg));
+    }
+  }
+  items.sort((a, b) => {
+    if (a.type !== b.type) return a.type === "plugin" ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  return items;
+}
+async function syncClaudeMd(opts) {
+  const file = claudeMdPath();
+  if (opts?.skip) return { status: "skipped", path: file };
+  try {
+    const items = await collectInstalledItems();
+    let existing = "";
+    let existed = true;
+    try {
+      existing = await fs2.readFile(file, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        existed = false;
+      } else {
+        throw err;
+      }
+    }
+    const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+    const hadBlock = BLOCK_RE.test(existing);
+    let next;
+    if (items.length === 0) {
+      if (!hadBlock) {
+        return { status: "unchanged", path: file };
+      }
+      next = removeBlock(existing, eol);
+    } else {
+      next = upsertBlock(existing, renderBlock(items), eol);
+    }
+    if (next === existing) {
+      return { status: "unchanged", path: file };
+    }
+    await fs2.mkdir(path2.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp.${process.pid}`;
+    await fs2.writeFile(tmp, next, "utf8");
+    await fs2.rename(tmp, file);
+    if (!existed) return { status: "created", path: file };
+    if (hadBlock && items.length === 0) return { status: "removed", path: file };
+    return { status: "updated", path: file };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { status: "failed", path: file, error: msg };
+  }
+}
+async function syncFromState(opts) {
+  if (opts?.skip) {
+    p3.log.info(t("claudeMd.skipped"));
+    return;
+  }
+  const sp = p3.spinner();
+  sp.start(t("claudeMd.syncing"));
+  const r = await syncClaudeMd();
+  switch (r.status) {
+    case "skipped":
+      sp.stop(t("claudeMd.skipped"));
+      return;
+    case "unchanged":
+      sp.stop(t("claudeMd.unchanged"));
+      return;
+    case "created":
+    case "updated":
+      sp.stop(t("claudeMd.synced", { path: r.path }));
+      return;
+    case "removed":
+      sp.stop(t("claudeMd.removed"));
+      return;
+    case "failed":
+      sp.stop(t("claudeMd.failed", { error: r.error ?? "unknown" }));
+      return;
+  }
 }
 
 // src/flows/install.ts
@@ -634,13 +838,13 @@ async function selectInteractive(states) {
     const s = states.get(pkg.id);
     return s.kind === "not_installed" || s.kind === "update_available";
   }).map((pkg) => pkg.id);
-  const picked = await p3.multiselect({
+  const picked = await p4.multiselect({
     message: t("install.selectPrompt"),
     options,
     initialValues,
     required: false
   });
-  if (p3.isCancel(picked)) return null;
+  if (p4.isCancel(picked)) return null;
   return picked.map((id) => findPkg(id)).filter((x2) => Boolean(x2));
 }
 function selectFromIds(opts) {
@@ -650,7 +854,7 @@ function selectFromIds(opts) {
   for (const id of opts.ids) {
     const pkg = findPkg(id);
     if (pkg) found.push(pkg);
-    else p3.log.warn(`Unknown id: ${id}`);
+    else p4.log.warn(`Unknown id: ${id}`);
   }
   return found;
 }
@@ -662,11 +866,11 @@ async function runOne(pkg, state, opts) {
     mode = "update";
   } else {
     if (!opts.yes) {
-      const ans = await p3.confirm({
+      const ans = await p4.confirm({
         message: t("install.confirmReinstall", { name: pkg.name }),
         initialValue: false
       });
-      if (p3.isCancel(ans) || ans === false) {
+      if (p4.isCancel(ans) || ans === false) {
         return { id: pkg.id, status: "skip", message: t("install.skippedReinstall", { name: pkg.name }) };
       }
     }
@@ -675,7 +879,7 @@ async function runOne(pkg, state, opts) {
   if (pkg.prereqCheck) {
     const r = await pkg.prereqCheck(t);
     if (!r.ok) {
-      p3.log.warn(t("install.prereqFail", { name: pkg.name, reason: r.reason }));
+      p4.log.warn(t("install.prereqFail", { name: pkg.name, reason: r.reason }));
       return { id: pkg.id, status: "skip", message: r.reason };
     }
   }
@@ -690,30 +894,30 @@ async function runOne(pkg, state, opts) {
   if (mode === "update" && state.kind === "update_available") {
     titleVars["version"] = state.latest;
   }
-  const log4 = p3.taskLog({ title: t(titleKey, titleVars) });
+  const log5 = p4.taskLog({ title: t(titleKey, titleVars) });
   try {
     if (mode === "reinstall") {
-      log4.message(t("reinstall.uninstalling"));
-      await pkg.uninstall({ log: log4, config, t });
-      log4.message(t("reinstall.installing"));
-      await pkg.install({ log: log4, config, t });
+      log5.message(t("reinstall.uninstalling"));
+      await pkg.uninstall({ log: log5, config, t });
+      log5.message(t("reinstall.installing"));
+      await pkg.install({ log: log5, config, t });
     } else if (mode === "update") {
       if (pkg.update) {
-        await pkg.update({ log: log4, config, t });
+        await pkg.update({ log: log5, config, t });
       } else {
-        log4.message(t("reinstall.uninstalling"));
-        await pkg.uninstall({ log: log4, config, t });
-        log4.message(t("reinstall.installing"));
-        await pkg.install({ log: log4, config, t });
+        log5.message(t("reinstall.uninstalling"));
+        await pkg.uninstall({ log: log5, config, t });
+        log5.message(t("reinstall.installing"));
+        await pkg.install({ log: log5, config, t });
       }
     } else {
-      await pkg.install({ log: log4, config, t });
+      await pkg.install({ log: log5, config, t });
     }
-    log4.success(t("install.success", { name: pkg.name }));
+    log5.success(t("install.success", { name: pkg.name }));
     return { id: pkg.id, status: "ok" };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    log4.error(`${t("install.failed", { name: pkg.name })}
+    log5.error(`${t("install.failed", { name: pkg.name })}
 ${msg}`);
     return { id: pkg.id, status: "fail", message: msg };
   }
@@ -731,7 +935,7 @@ function summarize(results) {
     ...skip.map((r) => `  ${pc.yellow("-")} ${r.id}${r.message ? pc.dim(` (${r.message})`) : ""}`),
     ...fail.map((r) => `  ${pc.red("\u2717")} ${r.id}${r.message ? pc.dim(` (${r.message.split("\n")[0]})`) : ""}`)
   ];
-  p3.note(lines.join("\n"), t("install.summaryTitle"));
+  p4.note(lines.join("\n"), t("install.summaryTitle"));
 }
 async function maybeRefreshMarketplaces(opts) {
   if (opts.noRefresh) return;
@@ -740,7 +944,7 @@ async function maybeRefreshMarketplaces(opts) {
     if (pkg.marketplaces) for (const n of pkg.marketplaces()) names.add(n);
   }
   if (names.size === 0) return;
-  const sp = p3.spinner();
+  const sp = p4.spinner();
   sp.start(t("marketplace.refreshing"));
   const refreshed = await refreshMarketplaces([...names]);
   sp.stop(
@@ -752,28 +956,35 @@ async function installFlow(opts = {}) {
   const explicit = opts.all || opts.ids && opts.ids.length > 0;
   const candidates = explicit ? selectFromIds(opts) : [...PKGS];
   if (candidates.length === 0) {
-    p3.log.info(t("install.nothingSelected"));
+    p4.log.info(t("install.nothingSelected"));
     return;
   }
   const stateMap = /* @__PURE__ */ new Map();
-  await Promise.all(
-    candidates.map(async (pkg) => {
-      stateMap.set(pkg.id, await deriveState(pkg));
-    })
-  );
+  const sp = p4.spinner();
+  sp.start(t("state.checking"));
+  try {
+    await Promise.all([listPlugins(), listMcp()]);
+    await Promise.all(
+      candidates.map(async (pkg) => {
+        stateMap.set(pkg.id, await deriveState(pkg));
+      })
+    );
+  } finally {
+    sp.stop(t("state.checked", { count: candidates.length }));
+  }
   let targets;
   if (explicit) {
     targets = candidates;
   } else {
     const picked = await selectInteractive(stateMap);
     if (picked === null) {
-      p3.cancel(t("app.cancelled"));
+      p4.cancel(t("app.cancelled"));
       return;
     }
     targets = picked;
   }
   if (targets.length === 0) {
-    p3.log.info(t("install.nothingSelected"));
+    p4.log.info(t("install.nothingSelected"));
     return;
   }
   const results = [];
@@ -782,38 +993,52 @@ async function installFlow(opts = {}) {
     results.push(await runOne(pkg, state, opts));
   }
   summarize(results);
+  await syncFromState({ skip: opts.noClaudeMd });
 }
 
 // src/flows/uninstall.ts
-import * as p4 from "@clack/prompts";
+import * as p5 from "@clack/prompts";
 import pc2 from "picocolors";
 async function getInstalled() {
   const states = await Promise.all(PKGS.map(async (pkg) => ({ pkg, installed: await pkg.isInstalled() })));
   return states.filter((s) => s.installed).map((s) => s.pkg);
 }
+async function probeInstalled() {
+  const sp = p5.spinner();
+  sp.start(t("state.checking"));
+  try {
+    await Promise.all([listPlugins(), listMcp()]);
+    const installed = await getInstalled();
+    sp.stop(t("state.checked", { count: installed.length }));
+    return installed;
+  } catch (err) {
+    sp.stop(t("state.checked", { count: 0 }));
+    throw err;
+  }
+}
 async function uninstallFlow(opts = {}) {
-  const installed = await getInstalled();
+  const installed = await probeInstalled();
   let targets;
   if (opts.ids && opts.ids.length > 0) {
     targets = [];
     for (const id of opts.ids) {
       const pkg = findPkg(id);
       if (!pkg) {
-        p4.log.warn(`Unknown id: ${id}`);
+        p5.log.warn(`Unknown id: ${id}`);
         continue;
       }
       if (!installed.some((x2) => x2.id === pkg.id)) {
-        p4.log.warn(`${pkg.name}: ${t("pkg.notInstalled")}`);
+        p5.log.warn(`${pkg.name}: ${t("pkg.notInstalled")}`);
         continue;
       }
       targets.push(pkg);
     }
   } else {
     if (installed.length === 0) {
-      p4.log.info(t("uninstall.noneInstalled"));
+      p5.log.info(t("uninstall.noneInstalled"));
       return;
     }
-    const picked = await p4.multiselect({
+    const picked = await p5.multiselect({
       message: t("uninstall.selectPrompt"),
       options: installed.map((pkg) => ({
         value: pkg.id,
@@ -822,62 +1047,76 @@ async function uninstallFlow(opts = {}) {
       })),
       required: false
     });
-    if (p4.isCancel(picked)) {
-      p4.cancel(t("app.cancelled"));
+    if (p5.isCancel(picked)) {
+      p5.cancel(t("app.cancelled"));
       return;
     }
     targets = picked.map((id) => findPkg(id)).filter((x2) => Boolean(x2));
   }
   if (targets.length === 0) {
-    p4.log.info(t("install.nothingSelected"));
+    p5.log.info(t("install.nothingSelected"));
     return;
   }
   if (!opts.yes) {
-    const ok2 = await p4.confirm({
+    const ok2 = await p5.confirm({
       message: t("uninstall.confirm", { count: targets.length }),
       initialValue: false
     });
-    if (p4.isCancel(ok2) || ok2 === false) {
-      p4.cancel(t("app.cancelled"));
+    if (p5.isCancel(ok2) || ok2 === false) {
+      p5.cancel(t("app.cancelled"));
       return;
     }
   }
   const results = [];
   for (const pkg of targets) {
-    const log4 = p4.taskLog({ title: t("uninstall.starting", { name: pkg.name }) });
+    const log5 = p5.taskLog({ title: t("uninstall.starting", { name: pkg.name }) });
     try {
-      await pkg.uninstall({ log: log4, config: {}, t });
-      log4.success(t("uninstall.success", { name: pkg.name }));
+      await pkg.uninstall({ log: log5, config: {}, t });
+      log5.success(t("uninstall.success", { name: pkg.name }));
       results.push({ id: pkg.id, status: "ok" });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      log4.error(`${t("uninstall.failed", { name: pkg.name })}
+      log5.error(`${t("uninstall.failed", { name: pkg.name })}
 ${msg}`);
       results.push({ id: pkg.id, status: "fail", message: msg });
     }
   }
   const ok = results.filter((r) => r.status === "ok").length;
   const fail = results.filter((r) => r.status === "fail").length;
-  p4.note(
+  p5.note(
     [
       pc2.green(t("install.summaryOk", { count: ok })),
       pc2.red(t("install.summaryFail", { count: fail }))
     ].join("\n"),
     t("install.summaryTitle")
   );
+  await syncFromState({ skip: opts.noClaudeMd });
 }
 
 // src/flows/update.ts
-import * as p5 from "@clack/prompts";
+import * as p6 from "@clack/prompts";
 import pc3 from "picocolors";
 async function getInstalled2() {
   const states = await Promise.all(PKGS.map(async (pkg) => ({ pkg, installed: await pkg.isInstalled() })));
   return states.filter((s) => s.installed).map((s) => s.pkg);
 }
+async function probeInstalled2() {
+  const sp = p6.spinner();
+  sp.start(t("state.checking"));
+  try {
+    await Promise.all([listPlugins(), listMcp()]);
+    const installed = await getInstalled2();
+    sp.stop(t("state.checked", { count: installed.length }));
+    return installed;
+  } catch (err) {
+    sp.stop(t("state.checked", { count: 0 }));
+    throw err;
+  }
+}
 async function updateFlow(opts = {}) {
-  const installed = await getInstalled2();
+  const installed = await probeInstalled2();
   if (installed.length === 0) {
-    p5.log.info(t("update.noneInstalled"));
+    p6.log.info(t("update.noneInstalled"));
     return;
   }
   let targets;
@@ -888,17 +1127,17 @@ async function updateFlow(opts = {}) {
     for (const id of opts.ids) {
       const pkg = findPkg(id);
       if (!pkg) {
-        p5.log.warn(`Unknown id: ${id}`);
+        p6.log.warn(`Unknown id: ${id}`);
         continue;
       }
       if (!installed.some((x2) => x2.id === pkg.id)) {
-        p5.log.warn(`${pkg.name}: ${t("pkg.notInstalled")}`);
+        p6.log.warn(`${pkg.name}: ${t("pkg.notInstalled")}`);
         continue;
       }
       targets.push(pkg);
     }
   } else {
-    const picked = await p5.multiselect({
+    const picked = await p6.multiselect({
       message: t("update.selectPrompt"),
       options: installed.map((pkg) => ({
         value: pkg.id,
@@ -907,41 +1146,41 @@ async function updateFlow(opts = {}) {
       })),
       required: false
     });
-    if (p5.isCancel(picked)) {
-      p5.cancel(t("app.cancelled"));
+    if (p6.isCancel(picked)) {
+      p6.cancel(t("app.cancelled"));
       return;
     }
     targets = picked.map((id) => findPkg(id)).filter((x2) => Boolean(x2));
   }
   if (targets.length === 0) {
-    p5.log.info(t("install.nothingSelected"));
+    p6.log.info(t("install.nothingSelected"));
     return;
   }
   const results = [];
   for (const pkg of targets) {
     if (pkg.id === "sequential-thinking") {
-      p5.log.info(t("update.mcpAutoNote", { name: pkg.name }));
+      p6.log.info(t("update.mcpAutoNote", { name: pkg.name }));
       results.push({ id: pkg.id, status: "noop" });
       continue;
     }
     if (pkg.id === "context7") {
-      p5.log.info(t("update.context7Note"));
+      p6.log.info(t("update.context7Note"));
       results.push({ id: pkg.id, status: "noop" });
       continue;
     }
-    const log4 = p5.taskLog({ title: t("update.starting", { name: pkg.name }) });
+    const log5 = p6.taskLog({ title: t("update.starting", { name: pkg.name }) });
     try {
       if (pkg.update) {
-        await pkg.update({ log: log4, config: {}, t });
+        await pkg.update({ log: log5, config: {}, t });
       } else {
-        await pkg.uninstall({ log: log4, config: {}, t });
-        await pkg.install({ log: log4, config: {}, t });
+        await pkg.uninstall({ log: log5, config: {}, t });
+        await pkg.install({ log: log5, config: {}, t });
       }
-      log4.success(t("update.success", { name: pkg.name }));
+      log5.success(t("update.success", { name: pkg.name }));
       results.push({ id: pkg.id, status: "ok" });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      log4.error(`${t("update.failed", { name: pkg.name })}
+      log5.error(`${t("update.failed", { name: pkg.name })}
 ${msg}`);
       results.push({ id: pkg.id, status: "fail", message: msg });
     }
@@ -949,7 +1188,7 @@ ${msg}`);
   const ok = results.filter((r) => r.status === "ok").length;
   const fail = results.filter((r) => r.status === "fail").length;
   const noop = results.filter((r) => r.status === "noop").length;
-  p5.note(
+  p6.note(
     [
       pc3.green(t("install.summaryOk", { count: ok })),
       pc3.red(t("install.summaryFail", { count: fail })),
@@ -957,10 +1196,11 @@ ${msg}`);
     ].join("\n"),
     t("install.summaryTitle")
   );
+  await syncFromState({ skip: opts.noClaudeMd });
 }
 
 // src/flows/status.ts
-import * as p6 from "@clack/prompts";
+import * as p7 from "@clack/prompts";
 import pc4 from "picocolors";
 async function statusFlow(opts = {}) {
   const states = await Promise.all(
@@ -993,12 +1233,12 @@ async function statusFlow(opts = {}) {
   const rows = states.map(
     (s) => `${s.name.padEnd(nameW)}  ${s.type.padEnd(typeW)}  ${s.installed ? pc4.green(`\u2713 ${t("pkg.installed")}`) : pc4.yellow(`\u2717 ${t("pkg.notInstalled")}`)}`
   );
-  p6.note([header, sep, ...rows].join("\n"), t("status.title"));
+  p7.note([header, sep, ...rows].join("\n"), t("status.title"));
 }
 
 // src/ui/menu.ts
 async function mainMenu() {
-  const action = await p7.select({
+  const action = await p8.select({
     message: t("menu.title"),
     options: [
       { value: "install", label: t("menu.install") },
@@ -1008,8 +1248,8 @@ async function mainMenu() {
       { value: "exit", label: t("menu.exit") }
     ]
   });
-  if (p7.isCancel(action) || action === "exit") {
-    p7.cancel(t("app.cancelled"));
+  if (p8.isCancel(action) || action === "exit") {
+    p8.cancel(t("app.cancelled"));
     return;
   }
   switch (action) {
@@ -1032,8 +1272,16 @@ async function mainMenu() {
 function parseLang(v) {
   return v === "zh" || v === "en" ? v : void 0;
 }
+function noClaudeMdFromArgs(args) {
+  if (args["no-claude-md"]) return true;
+  return Boolean(process.env["CURDX_FLOW_NO_CLAUDE_MD"]);
+}
 var sharedArgs = {
-  lang: { type: "string", description: "Override language: zh or en" }
+  lang: { type: "string", description: "Override language: zh or en" },
+  "no-claude-md": {
+    type: "boolean",
+    description: "Skip syncing the @curdx/flow block in ~/.claude/CLAUDE.md"
+  }
 };
 var installCmd = defineCommand({
   meta: { name: "install", description: "Install, reinstall, or update plugins / MCP servers" },
@@ -1046,15 +1294,16 @@ var installCmd = defineCommand({
   },
   async run({ args }) {
     await initLanguage(parseLang(args.lang));
-    p8.intro(t("app.intro"));
+    p9.intro(t("app.intro"));
     const ids = collectPositional(args);
     await installFlow({
       ids,
       all: Boolean(args.all),
       yes: Boolean(args.yes),
-      noRefresh: Boolean(args["no-refresh"])
+      noRefresh: Boolean(args["no-refresh"]),
+      noClaudeMd: noClaudeMdFromArgs(args)
     });
-    p8.outro(t("app.outro"));
+    p9.outro(t("app.outro"));
   }
 });
 var uninstallCmd = defineCommand({
@@ -1066,10 +1315,14 @@ var uninstallCmd = defineCommand({
   },
   async run({ args }) {
     await initLanguage(parseLang(args.lang));
-    p8.intro(t("app.intro"));
+    p9.intro(t("app.intro"));
     const ids = collectPositional(args);
-    await uninstallFlow({ ids, yes: Boolean(args.yes) });
-    p8.outro(t("app.outro"));
+    await uninstallFlow({
+      ids,
+      yes: Boolean(args.yes),
+      noClaudeMd: noClaudeMdFromArgs(args)
+    });
+    p9.outro(t("app.outro"));
   }
 });
 var updateCmd = defineCommand({
@@ -1081,10 +1334,14 @@ var updateCmd = defineCommand({
   },
   async run({ args }) {
     await initLanguage(parseLang(args.lang));
-    p8.intro(t("app.intro"));
+    p9.intro(t("app.intro"));
     const ids = collectPositional(args);
-    await updateFlow({ ids, all: Boolean(args.all) });
-    p8.outro(t("app.outro"));
+    await updateFlow({
+      ids,
+      all: Boolean(args.all),
+      noClaudeMd: noClaudeMdFromArgs(args)
+    });
+    p9.outro(t("app.outro"));
   }
 });
 var statusCmd = defineCommand({
@@ -1095,16 +1352,16 @@ var statusCmd = defineCommand({
   },
   async run({ args }) {
     await initLanguage(parseLang(args.lang));
-    if (!args.json) p8.intro(t("app.intro"));
+    if (!args.json) p9.intro(t("app.intro"));
     await statusFlow({ json: Boolean(args.json) });
-    if (!args.json) p8.outro(t("app.outro"));
+    if (!args.json) p9.outro(t("app.outro"));
   }
 });
 var SUBCOMMANDS = /* @__PURE__ */ new Set(["install", "uninstall", "update", "status"]);
 var root = defineCommand({
   meta: {
     name: "@curdx/flow",
-    version: "3.2.0",
+    version: "3.3.1",
     description: "Interactive installer for Claude Code plugins and MCP servers"
   },
   args: sharedArgs,
@@ -1139,9 +1396,9 @@ async function runInteractive(argv2) {
     else if (argv2[i]?.startsWith("--lang=")) lang = parseLang(argv2[i].slice("--lang=".length));
   }
   await initLanguage(lang);
-  p8.intro(t("app.intro"));
+  p9.intro(t("app.intro"));
   await mainMenu();
-  p8.outro(t("app.outro"));
+  p9.outro(t("app.outro"));
 }
 var argv = process.argv.slice(2);
 var first = firstNonFlag(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "description": "Interactive installer for Claude Code plugins and MCP servers",
   "type": "module",
   "bin": "./dist/index.mjs",