@curdx/flow 2.0.0-beta.9 → 2.0.0

package/cli/install.js

@@ -15,9 +15,20 @@ import {
   listPlugins,
   multiSelect,
   ensureClaudeMemRuntimes,
+  select,
+  intro,
+  outro,
+  readConfig,
+  writeConfig,
+  text,
+  note,
+  multiselectClack,
+  runSync,
+  VERSION,
 } from "./utils.js";
 import { injectGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
-import { RECOMMENDED_PLUGINS } from "./registry.js";
+import { REQUIRED_PLUGINS, RECOMMENDED_PLUGINS, BUNDLED_MCPS } from "./registry.js";
+import { readUserMcpConfig } from "./utils.js";
 
 // When installed via npm, this CLI file lives at <pkg-root>/cli/install.js.
 // The npm package bundles the full plugin body (.claude-plugin/, agents/,
@@ -39,6 +50,25 @@ export async function install(args = []) {
   const all = args.includes("--all");
   const noDeps = args.includes("--no-deps");
   const forceOnline = args.includes("--online") || args.includes("--from-github");
+  const yes = args.includes("--yes") || args.includes("-y");
+  const skipSelfUpdate = args.includes("--skip-self-update");
+
+  // ---------- Step 0: Self-update check ----------
+  if (!skipSelfUpdate) {
+    const updateResult = await checkAndUpdateSelf();
+    if (updateResult.updated) {
+      // CLI was updated, re-exec with same args
+      log.info("Restarting with updated version...");
+      const { spawn } = await import("node:child_process");
+      const child = spawn("curdx-flow", ["install", ...args, "--skip-self-update"], {
+        stdio: "inherit",
+        shell: false,
+      });
+      return new Promise((resolve) => {
+        child.on("close", (code) => process.exit(code || 0));
+      });
+    }
+  }
 
   // Default to offline install when the npm package includes the full plugin
   // body (since 1.1.5). Fall back to GitHub only if the local manifest is
@@ -46,10 +76,48 @@ export async function install(args = []) {
   // or the user explicitly passes --online.
   const useOffline = !forceOnline && existsSync(LOCAL_MARKETPLACE_MANIFEST);
 
-  log.title("🚀 CurDX-Flow Installer");
+  // Use @clack intro only in interactive TTY mode
+  if (process.stdout.isTTY && !yes) {
+    await intro("🚀 CurDX-Flow Installer");
+  } else {
+    log.title("🚀 CurDX-Flow Installer");
+  }
+
+  // ---------- Step 0: Language selection ----------
+  const config = readConfig();
+  let language = config.language;
+
+  if (!language && !yes) {
+    log.blank();
+    language = await select({
+      message: "Choose your preferred language / 选择语言",
+      options: [
+        {
+          value: "en",
+          label: "English",
+          hint: "CLI output and documentation in English"
+        },
+        {
+          value: "zh",
+          label: "简体中文",
+          hint: "CLI 输出和文档使用简体中文"
+        },
+      ],
+      initialValue: "en",
+    });
+    config.language = language;
+    writeConfig(config);
+    log.ok(`Language set to ${language === "zh" ? "简体中文" : "English"}`);
+  } else if (!language) {
+    // --yes mode, default to English
+    language = "en";
+    config.language = language;
+    writeConfig(config);
+  }
 
   // ---------- Step 1: Check claude CLI ----------
-  log.step(1, 4, "Checking claude CLI...");
+  log.blank();
+  log.step(1, 5, "Checking claude CLI...");
   const ver = claudeVersion();
   if (!ver) {
     log.err("claude CLI not found. Install Claude Code from https://code.claude.com first.");
@@ -57,13 +125,66 @@ export async function install(args = []) {
   }
   log.ok(`claude CLI found (${ver})`);
 
+  // Snapshot curdx-flow's pre-install version BEFORE Step 2 touches the
+  // marketplace. Step 2 does `claude plugin marketplace remove` + `add` to
+  // rebind to the current source, and the remove side-effect also drops
+  // any plugins installed from that marketplace. If we only call
+  // listPlugins() in Step 3, curdx-flow is already gone from the list and
+  // we can't tell a fresh install apart from an upgrade — the Step 3
+  // output then incorrectly says "installed" for both cases.
+  const prevCurdxFlow = listPlugins().find((p) => p.name === "curdx-flow");
+
+  // ---------- Step 1.5: Existing installation action menu ----------
+  if (prevCurdxFlow && !yes) {
+    log.blank();
+    const action = await select({
+      message: language === "zh"
+        ? "检测到已安装的版本。如何继续？"
+        : "Existing installation detected. How would you like to proceed?",
+      options: [
+        {
+          value: "upgrade",
+          label: language === "zh" ? "升级到最新版本" : "Upgrade to latest version",
+          hint: language === "zh"
+            ? `当前: v${prevCurdxFlow.version}`
+            : `Current: v${prevCurdxFlow.version}`
+        },
+        {
+          value: "reinstall",
+          label: language === "zh" ? "重新安装（保留配置）" : "Reinstall (preserve config)",
+        },
+        {
+          value: "reconfigure",
+          label: language === "zh" ? "重新配置插件" : "Reconfigure plugins",
+        },
+        {
+          value: "cancel",
+          label: language === "zh" ? "取消" : "Cancel",
+        },
+      ],
+      initialValue: "upgrade",
+    });
+
+    if (action === "cancel") {
+      log.info(language === "zh" ? "安装已取消" : "Installation cancelled");
+      process.exit(0);
+    }
+
+    if (action === "reconfigure") {
+      log.info(language === "zh"
+        ? "重新配置模式：将重新提示插件选择和 API key 配置"
+        : "Reconfigure mode: will re-prompt for plugin selection and API key configuration");
+      // Continue with normal flow but force prompts
+    }
+  }
+
   // ---------- Step 2: Add marketplace ----------
   log.blank();
   const marketplaceSource = useOffline ? PKG_ROOT : "curdx/curdx-flow";
   const marketplaceLabel = useOffline
     ? `local npm package (${PKG_ROOT})`
     : "GitHub curdx/curdx-flow";
-  log.step(2, 4, `Adding curdx-flow marketplace from ${marketplaceLabel}...`);
+  log.step(2, 5, `Adding curdx-flow marketplace from ${marketplaceLabel}...`);
 
   // Remove any existing marketplace with the same name so we get a clean
   // rebind to the chosen source. Errors are non-fatal (marketplace may
@@ -76,7 +197,7 @@ export async function install(args = []) {
 
   const addRes = await run(
     "claude",
-    ["plugin", "marketplace", "add", marketplaceSource],
+    ["plugin", "marketplace", "add", "--scope", "user", marketplaceSource],
     { silent: true }
   );
   if (addRes.code !== 0 && !addRes.stderr.includes("already")) {
@@ -90,7 +211,7 @@ export async function install(args = []) {
 
   // ---------- Step 3: Install curdx-flow plugin ----------
   log.blank();
-  log.step(3, 4, "Installing curdx-flow plugin (2 MCPs will auto-start)...");
+  log.step(3, 5, "Installing curdx-flow plugin...");
   // Read the version the marketplace is shipping so we can decide whether an
   // already-installed plugin needs an update (same name but stale version
   // previously silently skipped the upgrade — caused the beta.1 → beta.7 drift).
@@ -104,41 +225,157 @@ export async function install(args = []) {
     // marketplace not local (online install) or unreadable — fall through
   }
 
-  const installed = listPlugins();
-  const already = installed.find((p) => p.name === "curdx-flow");
-  if (already && shippedVersion && already.version !== shippedVersion) {
+  // Use the pre-Step-2 snapshot — by this point `claude plugin marketplace
+  // remove` has already evicted the plugin, so listPlugins() here would
+  // always return undefined for curdx-flow and we'd mis-report "installed"
+  // when we actually upgraded (the bug reported by @wdx's beta.14 log).
+  const already = prevCurdxFlow;
+
+  if (already && shippedVersion && already.version === shippedVersion) {
+    // Step 2 removes and re-adds the marketplace to rebind it to the current
+    // source. Claude Code removes plugins installed from that marketplace as
+    // part of `marketplace remove`, so even a same-version install must be
+    // re-registered here.
     log.info(
-      `curdx-flow installed at v${already.version}, marketplace ships v${shippedVersion} — updating...`
+      `curdx-flow already at v${already.version}, re-registering...`
     );
     const r = await run(
       "claude",
-      ["plugin", "update", "curdx-flow@curdx-flow-marketplace"],
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
       { silent: true }
     );
     if (r.code !== 0) {
-      log.warn(`Update returned non-zero: ${r.stderr.trim() || r.stdout.trim()}`);
-      log.info(`If the version stays on v${already.version}, run: claude plugin uninstall curdx-flow@curdx-flow-marketplace && retry`);
-    } else {
-      log.ok(`curdx-flow updated to v${shippedVersion}`);
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
     }
+    log.ok(`curdx-flow re-registered at v${shippedVersion}`);
+  } else if (already && shippedVersion) {
+    // Existing install, different version — frame as an upgrade.
+    log.info(
+      `curdx-flow v${already.version} → v${shippedVersion}, installing...`
+    );
+    const r = await run(
+      "claude",
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
+    }
+    log.ok(`curdx-flow upgraded to v${shippedVersion}`);
   } else if (already) {
-    log.ok(`curdx-flow already installed (v${already.version}, ${already.status})`);
+    // shippedVersion unknown (e.g. online install) — best we can do is report
+    // the previous version and let `claude plugin install` idempotently
+    // re-register.
+    log.info(
+      `curdx-flow v${already.version} detected, re-registering...`
+    );
+    const r = await run(
+      "claude",
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
+    }
+    log.ok(`curdx-flow re-registered`);
   } else {
     const r = await run(
       "claude",
-      ["plugin", "install", "curdx-flow@curdx-flow-marketplace"],
+      ["plugin", "install", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
       { silent: true }
     );
     if (r.code !== 0) {
       log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
       process.exit(1);
     }
-    log.ok("curdx-flow installed");
+    if (shippedVersion) {
+      log.ok(`curdx-flow v${shippedVersion} installed`);
+    } else {
+      log.ok("curdx-flow installed");
+    }
+  }
+
+  // ---------- Step 3.5: Install required plugins + register user-level MCPs ----------
+  log.blank();
+  log.info("Installing required Claude Code plugins...");
+  for (const plugin of REQUIRED_PLUGINS) {
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(plugin.name)}...`);
+    const ma = await run(
+      "claude",
+      ["plugin", "marketplace", "add", "--scope", plugin.scope, plugin.marketplaceSource],
+      { silent: true }
+    );
+    if (ma.code !== 0 && !ma.stderr.includes("already")) {
+      log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+    }
+
+    const ir = await run(
+      "claude",
+      ["plugin", "install", "--scope", plugin.scope, plugin.installSpec],
+      { silent: true }
+    );
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${plugin.name} installed`);
+
+      // Post-install: API key configuration
+      if (plugin.requiresConfig && plugin.configType === "apiKey" && !yes) {
+        await promptPluginConfig(plugin, language, config);
+      }
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${plugin.name} install failed: ${ir.stderr.trim().split("\n").pop()}`
+      );
+      console.log(
+        color.dim(
+          `     Run manually: claude plugin marketplace add --scope ${plugin.scope} ${plugin.marketplaceSource}`
+        )
+      );
+      console.log(
+        color.dim(
+          `     Then: claude plugin install --scope ${plugin.scope} ${plugin.installSpec}`
+        )
+      );
+    }
+  }
+
+  // Beta.12: direct MCPs migrated from plugin.json bundling. See cli/registry.js
+  // for the rationale. Context7 now uses Upstash's official plugin instead.
+  log.blank();
+  log.info("Registering required MCP servers (user-level)...");
+  const existingUserMcps = readUserMcpConfig();
+  for (const mcp of BUNDLED_MCPS) {
+    if (mcp.preserveExisting && existingUserMcps.has(mcp.name)) {
+      const existing = existingUserMcps.get(mcp.name);
+      log.info(
+        `  ${mcp.name.padEnd(22)} ${color.dim(`already registered (${(existing.args || []).join(" ")}) — preserving`)}`
+      );
+      continue;
+    }
+    const r = await run(
+      "claude",
+      ["mcp", "add", "--scope", "user", mcp.name, "--", mcp.command, ...mcp.args],
+      { silent: true }
+    );
+    if (r.code === 0) {
+      log.ok(`  ${mcp.name.padEnd(22)} ${color.dim("registered")}`);
+    } else if (r.stderr.includes("already exists")) {
+      log.info(`  ${mcp.name.padEnd(22)} ${color.dim("already exists — skipped")}`);
+    } else {
+      log.warn(
+        `  ${mcp.name.padEnd(22)} registration failed: ${r.stderr.trim().split("\n").pop()}`
+      );
+      log.info(
+        `     Run manually: claude mcp add --scope user ${mcp.name} -- ${mcp.command} ${mcp.args.join(" ")}`
+      );
+    }
   }
 
   // ---------- Step 4: Recommended plugins ----------
   log.blank();
-  log.step(4, 4, "Recommended plugins");
+  log.step(4, 5, "Recommended plugins");
 
   if (noDeps) {
     log.info("Skipping recommended plugins (--no-deps)");
@@ -150,18 +387,32 @@ export async function install(args = []) {
   if (all) {
     toInstall = RECOMMENDED.map((r) => r.name);
     log.info("--all mode: installing all recommended");
+  } else if (yes) {
+    // --yes mode: install all not-yet-installed plugins
+    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
+    toInstall = RECOMMENDED
+      .filter((r) => !currentlyInstalled.has(r.name))
+      .map((r) => r.name);
+    log.info(`--yes mode: installing ${toInstall.length} recommended plugins`);
   } else {
     const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
-    const choices = RECOMMENDED.map((r) => ({
-      label: `${color.bold(r.name)}${currentlyInstalled.has(r.name) ? color.green(" (installed)") : ""}`,
+    const options = RECOMMENDED.map((r) => ({
       value: r.name,
+      label: `${r.name}${currentlyInstalled.has(r.name) ? " (installed)" : ""}`,
       hint: r.hint,
     }));
-    const defaults = RECOMMENDED
-      .map((r, i) => (currentlyInstalled.has(r.name) ? -1 : i))
-      .filter((i) => i >= 0);
+    const initialValues = RECOMMENDED
+      .filter((r) => !currentlyInstalled.has(r.name))
+      .map((r) => r.name);
 
-    toInstall = await multiSelect("Which recommended plugins to install?", choices, defaults);
+    toInstall = await multiselectClack({
+      message: language === "zh"
+        ? "选择要安装的推荐插件（空格切换，回车确认）"
+        : "Select recommended plugins to install (space to toggle, enter to confirm)",
+      options,
+      initialValues,
+      required: false,
+    });
   }
 
   if (!toInstall || toInstall.length === 0) {
@@ -174,13 +425,13 @@ export async function install(args = []) {
   for (const pluginName of toInstall) {
     const rec = RECOMMENDED.find((r) => r.name === pluginName);
     log.blank();
-    console.log(`  ${color.cyan("⏳")} Installing ${color.bold(rec.name)}...`);
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
 
     // 1. Add marketplace (if needed)
-    if (rec.marketplace) {
+    if (rec.marketplaceSource) {
       const ma = await run(
         "claude",
-        ["plugin", "marketplace", "add", rec.marketplace],
+        ["plugin", "marketplace", "add", "--scope", rec.scope, rec.marketplaceSource],
         { silent: true }
       );
       if (ma.code !== 0 && !ma.stderr.includes("already")) {
@@ -190,7 +441,7 @@ export async function install(args = []) {
     }
 
     // 2. Install
-    const ir = await run("claude", ["plugin", "install", rec.installSpec], {
+    const ir = await run("claude", ["plugin", "install", "--scope", rec.scope, rec.installSpec], {
       silent: true,
     });
     if (ir.code === 0) {
@@ -224,7 +475,7 @@ export async function install(args = []) {
       );
       console.log(
         color.dim(
-          `     Run manually: claude plugin install ${rec.installSpec}`
+          `     Run manually: claude plugin install --scope ${rec.scope} ${rec.installSpec}`
         )
       );
     }
@@ -232,7 +483,7 @@ export async function install(args = []) {
 
   // ---------- Step 5: inject global protocols ----------
   log.blank();
-  console.log(color.dim("Injecting global protocols into ~/.claude/CLAUDE.md..."));
+  log.step(5, 5, "Injecting global protocols into ~/.claude/CLAUDE.md...");
   try {
     const r = injectGlobalProtocols();
     if (r.action === "created") {
@@ -251,13 +502,155 @@ export async function install(args = []) {
   printNextSteps();
 }
 
+/**
+ * Check for CLI updates and auto-update if available
+ * Returns { updated: boolean, version?: string }
+ */
+async function checkAndUpdateSelf() {
+  try {
+    // Check if globally installed
+    const globalPath = runSync("npm", ["root", "-g"]).stdout.trim();
+    const installedPath = join(globalPath, "@curdx/flow");
+
+    if (!existsSync(installedPath)) {
+      // Not globally installed, skip update
+      return { updated: false };
+    }
+
+    // Check npm registry for latest version
+    log.info("Checking for CLI updates...");
+    const res = runSync("npm", ["view", "@curdx/flow", "version"]);
+
+    if (res.code !== 0) {
+      // Registry check failed, continue with current version
+      return { updated: false };
+    }
+
+    const latestVersion = res.stdout.trim();
+    const currentVersion = VERSION;
+
+    if (latestVersion === currentVersion) {
+      log.ok(`CLI is up to date (v${currentVersion})`);
+      return { updated: false };
+    }
+
+    // Compare versions (simple string comparison works for semver)
+    if (latestVersion > currentVersion) {
+      log.info(`New version available: v${currentVersion} → v${latestVersion}`);
+      log.info("Updating CLI...");
+
+      const updateRes = await run("npm", ["install", "-g", "@curdx/flow@latest"], {
+        silent: false,
+      });
+
+      if (updateRes.code === 0) {
+        log.ok(`CLI updated to v${latestVersion}`);
+        return { updated: true, version: latestVersion };
+      } else {
+        log.warn("CLI update failed, continuing with current version");
+        return { updated: false };
+      }
+    }
+
+    return { updated: false };
+  } catch (err) {
+    // Update check failed, continue silently
+    return { updated: false };
+  }
+}
+
+/**
+ * Prompt for plugin-specific configuration (e.g., API keys)
+ */
+async function promptPluginConfig(plugin, language, config) {
+  if (plugin.name === "context7-plugin") {
+    log.blank();
+    await note(
+      language === "zh"
+        ? "Context7 需要 API key 才能使用。\n获取 API key: https://console.upstash.com/context7"
+        : "Context7 requires an API key to function.\nGet your API key at: https://console.upstash.com/context7",
+      language === "zh" ? "配置 Context7" : "Configure Context7"
+    );
+
+    const apiKey = await text({
+      message: language === "zh"
+        ? "输入你的 Context7 API key（或按 Enter 跳过）"
+        : "Enter your Context7 API key (or press Enter to skip)",
+      placeholder: "ctx7_...",
+      validate: (value) => {
+        if (!value) return; // Allow skip
+        if (!value.startsWith("ctx7_")) {
+          return language === "zh"
+            ? "API key 应该以 ctx7_ 开头"
+            : "API key should start with ctx7_";
+        }
+      },
+    });
+
+    if (apiKey) {
+      // Save to config for future reference
+      config.context7ApiKey = apiKey;
+      writeConfig(config);
+
+      // Add to MCP config with environment variable
+      const r = await run(
+        "claude",
+        ["mcp", "add", "--scope", "user", "context7", "--env", `CONTEXT7_API_KEY=${apiKey}`, "--", "npx", "-y", "@upstash/context7-mcp"],
+        { silent: true }
+      );
+
+      if (r.code === 0) {
+        log.ok(
+          language === "zh"
+            ? "  Context7 API key 已配置"
+            : "  Context7 API key configured"
+        );
+      } else if (r.stderr.includes("already exists")) {
+        // Update existing MCP server
+        await run("claude", ["mcp", "remove", "--scope", "user", "context7"], { silent: true });
+        const r2 = await run(
+          "claude",
+          ["mcp", "add", "--scope", "user", "context7", "--env", `CONTEXT7_API_KEY=${apiKey}`, "--", "npx", "-y", "@upstash/context7-mcp"],
+          { silent: true }
+        );
+        if (r2.code === 0) {
+          log.ok(
+            language === "zh"
+              ? "  Context7 API key 已更新"
+              : "  Context7 API key updated"
+          );
+        }
+      } else {
+        log.warn(
+          language === "zh"
+            ? `  Context7 MCP 配置失败: ${r.stderr.trim().split("\n").pop()}`
+            : `  Context7 MCP configuration failed: ${r.stderr.trim().split("\n").pop()}`
+        );
+        log.info(
+          color.dim(
+            language === "zh"
+              ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- npx -y @upstash/context7-mcp`
+              : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- npx -y @upstash/context7-mcp`
+          )
+        );
+      }
+    } else {
+      log.info(
+        language === "zh"
+          ? "  跳过 Context7 配置（稍后可运行 curdx-flow install 重新配置）"
+          : "  Skipped Context7 configuration (run curdx-flow install later to reconfigure)"
+      );
+    }
+  }
+}
+
 function printNextSteps() {
   // Detect whether the CLI is globally installed (curdx-flow on PATH) or
   // the user ran us via npx. Tell them the right invocation each time.
   const cliOnPath = has("curdx-flow");
   const cliCmd = cliOnPath ? "curdx-flow" : "npx @curdx/flow";
 
-  console.log(`\n${color.bold("✅ Install complete")}\n`);
+  console.log(`\n${color.bold(`${color.green("✓")} Install complete`)}\n`);
   console.log(`${color.bold("Restart Claude Code")} so the plugin registers all its commands and hooks.\n`);
   console.log(`${color.bold("Next steps")}:\n`);
   console.log(`  ${color.dim("# Verify health")}`);

package/cli/protocols-body.md

@@ -0,0 +1,21 @@
+## Global Protocols (curdx-flow)
+
+All operations MUST strictly follow these system constraints:
+
+### Language separation
+- **Tool / persistence layer = English**: commit messages, code, comments, file names, function names, PR descriptions, CLI log output, error messages thrown by code, and any artifact persisted to the repository or shown in a developer terminal.
+- **Conversational layer = Simplified Chinese**: chat replies, explanations and reasoning shown directly to the human in a conversation interface (e.g. Claude Code chat).
+
+Rationale: English in the persistence/tool layer aligns with developer-tool industry norms (npm/git/cargo are all English) and keeps the codebase internationally collaborable. Chinese in the conversational layer matches the user's language preference. Mixing the two (e.g. Chinese commit messages, Chinese CLI log output) is a violation.
+
+### Discovery & reasoning
+- **Library / framework / API questions**: query `context7` MCP first. Do not rely on training memory.
+- **Planning / design / architecture review / epic decomposition**: use `sequential-thinking` MCP with at least 5 thoughts.
+- **Cross-session memory**: query `claude-mem` MCP at task start when available.
+
+### Three red lines (inherited from pua)
+1. **Closed loop**: claiming "done"? Provide evidence (build output / passing tests / curl result).
+2. **Fact-driven**: before saying "probably an env issue", verify it. Unverified attribution = blame-shifting.
+3. **Exhaust everything**: before saying "I cannot", complete the systematic 4-stage debugging.
+
+> Source: curdx-flow CLI installer (`curdx-flow install`). Remove with: `curdx-flow uninstall --purge`.

package/cli/protocols.js

@@ -14,41 +14,32 @@ import {
   unlinkSync,
 } from "node:fs";
 import { join, dirname } from "node:path";
-
-const HOME = process.env.HOME || "";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+// Use os.homedir() instead of process.env.HOME — HOME can be empty inside
+// non-login shells (CI containers, some spawned child envs), which would
+// resolve GLOBAL_CLAUDE_MD to "/.claude/CLAUDE.md" (filesystem root) and
+// cause mkdir/writeFileSync to fail with EACCES. homedir() falls back to
+// the effective user's passwd entry on POSIX and USERPROFILE on Windows.
+const HOME = homedir();
 export const GLOBAL_CLAUDE_MD = join(HOME, ".claude", "CLAUDE.md");
 
 const SENTINEL_BEGIN =
   "<!-- BEGIN curdx-flow protocols (auto-managed; do not edit between sentinels) -->";
 const SENTINEL_END = "<!-- END curdx-flow protocols -->";
 
-// Protocol block is itself in English — it's instructions for the model,
-// not user-facing prose. User chat output is still Chinese per the rule below.
-const PROTOCOL_BODY = `
-## Global Protocols (curdx-flow)
-
-All operations MUST strictly follow these system constraints:
-
-### Language separation
-- **Tool / persistence layer = English**: commit messages, code, comments, file names, function names, PR descriptions, CLI log output, error messages thrown by code, and any artifact persisted to the repository or shown in a developer terminal.
-- **Conversational layer = Simplified Chinese**: chat replies, explanations and reasoning shown directly to the human in a conversation interface (e.g. Claude Code chat).
-
-Rationale: English in the persistence/tool layer aligns with developer-tool industry norms (npm/git/cargo are all English) and keeps the codebase internationally collaborable. Chinese in the conversational layer matches the user's language preference. Mixing the two (e.g. Chinese commit messages, Chinese CLI log output) is a violation.
-
-### Discovery & reasoning
-- **Library / framework / API questions**: query \`context7\` MCP first. Do not rely on training memory.
-- **Planning / design / architecture review / epic decomposition**: use \`sequential-thinking\` MCP with at least 5 thoughts.
-- **Cross-session memory**: query \`claude-mem\` MCP at task start when available.
-
-### Three red lines (inherited from pua)
-1. **Closed loop**: claiming "done"? Provide evidence (build output / passing tests / curl result).
-2. **Fact-driven**: before saying "probably an env issue", verify it. Unverified attribution = blame-shifting.
-3. **Exhaust everything**: before saying "I cannot", complete the systematic 4-stage debugging.
-
-> Source: curdx-flow CLI installer (\`curdx-flow install\`). Remove with: \`curdx-flow uninstall --purge\`.
-`;
-
-const FULL_BLOCK = `${SENTINEL_BEGIN}\n${PROTOCOL_BODY.trim()}\n${SENTINEL_END}`;
+// Protocol body lives in a sibling markdown file so it keeps markdown tooling
+// (preview, lint, prettier) and avoids backtick-escaping noise inside a JS
+// template literal. The body itself is English — it's instructions for the
+// model, not user-facing prose.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROTOCOL_BODY = readFileSync(
+  join(__dirname, "protocols-body.md"),
+  "utf-8"
+).trim();
+
+const FULL_BLOCK = `${SENTINEL_BEGIN}\n${PROTOCOL_BODY}\n${SENTINEL_END}`;
 
 /**
  * Read existing CLAUDE.md content; return "" if missing.