@nick848/fet 1.0.7 → 1.0.9

package/dist/cli/index.js

@@ -179,7 +179,12 @@ function toGitNexusState(detection, previous) {
     setupHandoffPath: previous?.setupHandoffPath ?? null,
     setupHandoffUpdatedAt: previous?.setupHandoffUpdatedAt ?? null,
     handoffPath: previous?.handoffPath ?? null,
-    handoffUpdatedAt: previous?.handoffUpdatedAt ?? null
+    handoffUpdatedAt: previous?.handoffUpdatedAt ?? null,
+    projectContextPath: previous?.projectContextPath ?? null,
+    projectContextUpdatedAt: previous?.projectContextUpdatedAt ?? null,
+    workflowContextPath: previous?.workflowContextPath ?? null,
+    workflowContextUpdatedAt: previous?.workflowContextUpdatedAt ?? null,
+    lastWorkflowGraphQuery: previous?.lastWorkflowGraphQuery ?? null
   };
 }
 async function inspectGitNexusGraph(projectRoot, env = process.env) {
@@ -248,7 +253,8 @@ function resolveGitNexusCommand(env) {
   const raw = env.FET_GITNEXUS_COMMAND?.trim() || env.FET_GITNEXUS_EXECUTABLE?.trim() || "gitnexus";
   const parts = splitCommand(raw);
   const [file = "gitnexus", ...args] = parts;
-  return { file, args, label: raw };
+  const resolvedFile = process.platform === "win32" && raw === "gitnexus" ? "gitnexus.cmd" : file;
+  return { file: resolvedFile, args, label: raw };
 }
 function splitCommand(value) {
   const matches = value.match(/"[^"]+"|'[^']+'|\S+/g);
@@ -262,7 +268,7 @@ async function doctorCommand(ctx, options = {}) {
   checks.push(await checkState(ctx));
   checks.push(await checkFile("agents", join6(ctx.projectRoot, "AGENTS.md"), "AGENTS.md \u7F3A\u5931", "fet update-context"));
   checks.push(await checkFile("config", join6(ctx.projectRoot, "openspec", "config.yaml"), "openspec/config.yaml \u7F3A\u5931", "fet init"));
-  checks.push(await checkPlaceholders(ctx.projectRoot));
+  checks.push(await checkPlaceholders(ctx));
   checks.push(await checkGitNexus(ctx));
   for (const adapter of ctx.toolAdapters) {
     checks.push(...await adapter.doctor(ctx.projectRoot));
@@ -299,12 +305,12 @@ async function checkGitNexus(ctx) {
   return state.installed ? {
     id: "gitnexus",
     status: "pass",
-    message: `GitNexus detected: ${state.executablePath ?? "gitnexus"} (${state.version ?? "unknown"}), graph ${state.graphExists ? "found" : "not found"}`
+    message: ctx.language === "en" ? `GitNexus detected: ${state.executablePath ?? "gitnexus"} (${state.version ?? "unknown"}), graph ${state.graphExists ? "found" : "not found"}` : `\u68C0\u6D4B\u5230 GitNexus\uFF1A${state.executablePath ?? "gitnexus"}\uFF08${state.version ?? "unknown"}\uFF09\uFF0C\u4EE3\u7801\u56FE${state.graphExists ? "\u5DF2\u627E\u5230" : "\u672A\u627E\u5230"}`
   } : {
     id: "gitnexus",
     status: "warn",
-    message: "Optional GitNexus code graph support is not installed",
-    suggestedCommand: "Install GitNexus later if you want OpenSpec artifacts to prefer a repository graph"
+    message: ctx.language === "en" ? "Optional GitNexus code graph support is not installed" : "\u5C1A\u672A\u5B89\u88C5\u53EF\u9009\u7684 GitNexus \u4EE3\u7801\u56FE\u652F\u6301",
+    suggestedCommand: ctx.language === "en" ? "Install GitNexus later if you want OpenSpec artifacts to prefer a repository graph" : "\u5982\u679C\u5E0C\u671B OpenSpec \u4EA7\u7269\u4F18\u5148\u53C2\u8003\u4ED3\u5E93\u4EE3\u7801\u56FE\uFF0C\u53EF\u4EE5\u7A0D\u540E\u5B89\u88C5 GitNexus"
   };
 }
 async function checkOpenSpec(ctx) {
@@ -326,18 +332,27 @@ async function checkState(ctx) {
 async function checkFile(id, path, missing, suggestedCommand) {
   return await exists(path) ? { id, status: "pass", message: `${id} \u5B58\u5728` } : { id, status: "warn", message: missing, suggestedCommand };
 }
-async function checkPlaceholders(projectRoot) {
+async function checkPlaceholders(ctx) {
   try {
-    await readFile4(join6(projectRoot, "AGENTS.md"), "utf8");
-    const count2 = await countAgentsLlmPlaceholders(projectRoot);
+    await readFile4(join6(ctx.projectRoot, "AGENTS.md"), "utf8");
+    const count2 = await countAgentsLlmPlaceholders(ctx.projectRoot);
     return count2 ? {
       id: "context-placeholders",
       status: "warn",
-      message: `AGENTS.md has ${count2} LLM placeholder(s)`,
+      message: ctx.language === "en" ? `AGENTS.md has ${count2} LLM placeholder(s)` : `AGENTS.md \u4ECD\u6709 ${count2} \u4E2A LLM \u5360\u4F4D\u7B26`,
       suggestedCommand: "fet fill-context"
-    } : { id: "context-placeholders", status: "pass", message: "AGENTS.md placeholders resolved" };
+    } : {
+      id: "context-placeholders",
+      status: "pass",
+      message: ctx.language === "en" ? "AGENTS.md placeholders resolved" : "AGENTS.md \u5360\u4F4D\u7B26\u5DF2\u5904\u7406"
+    };
   } catch {
-    return { id: "context-placeholders", status: "warn", message: "AGENTS.md missing", suggestedCommand: "fet update-context" };
+    return {
+      id: "context-placeholders",
+      status: "warn",
+      message: ctx.language === "en" ? "AGENTS.md missing" : "AGENTS.md \u7F3A\u5931",
+      suggestedCommand: "fet update-context"
+    };
   }
 }
 async function exists(path) {
@@ -433,8 +448,313 @@ FET:END -->
 }
 
 // src/commands/graph.ts
-import { mkdir as mkdir4 } from "fs/promises";
+import { mkdir as mkdir5 } from "fs/promises";
+import { dirname as dirname6, join as join9 } from "path";
+
+// src/graph-context.ts
+import { mkdir as mkdir4, readdir, readFile as readFile5 } from "fs/promises";
 import { dirname as dirname5, join as join8 } from "path";
+var MAX_SOURCE_CONTEXT = 8e3;
+var MAX_GRAPH_OUTPUT = 2e4;
+async function buildProjectGraphContext(ctx, state, trigger) {
+  if (!isGraphReadable(state)) {
+    return {
+      generated: false,
+      path: null,
+      query: null,
+      warnings: ["GitNexus graph exists check did not pass; project graph context was not generated."]
+    };
+  }
+  const query = "FET OpenSpec workflow architecture commands adapters graph integration project structure";
+  const goal = "Summarize the repository modules, workflow entry points, and likely insertion points for future FET/OpenSpec work.";
+  const graphQuery = await runGitNexus(["query", query, "--goal", goal, "--limit", "8"], { cwd: ctx.projectRoot });
+  const status = await runGitNexus(["status"], { cwd: ctx.projectRoot });
+  const warnings = commandWarnings([["gitnexus query", graphQuery], ["gitnexus status", status]]);
+  const relativePath = ".fet/graph-context/project.md";
+  await writeGraphContext(
+    join8(ctx.projectRoot, relativePath),
+    renderProjectContext({
+      trigger,
+      state,
+      query,
+      goal,
+      status: commandText(status),
+      graphOutput: commandText(graphQuery),
+      warnings
+    })
+  );
+  return {
+    generated: true,
+    path: relativePath,
+    query,
+    warnings
+  };
+}
+async function buildWorkflowGraphContext(ctx, options) {
+  const existing = await ctx.stateStore.getOrCreateGlobal();
+  if (!existing.graph?.gitnexus?.graphExists) {
+    return {
+      generated: false,
+      path: null,
+      query: null,
+      warnings: []
+    };
+  }
+  const state = await refreshGitNexusState(ctx);
+  if (!isGraphReadable(state)) {
+    return {
+      generated: false,
+      path: null,
+      query: null,
+      warnings: []
+    };
+  }
+  const sourceContext = await collectOpenSpecContext(ctx.projectRoot, options.changeId);
+  const query = buildWorkflowQuery(options, sourceContext);
+  const goal = workflowGoal(options.command);
+  const graphQuery = await runGitNexus(["query", query, "--goal", goal, "--limit", "8"], { cwd: ctx.projectRoot });
+  const detectChanges = shouldDetectChanges(options.command) ? await runGitNexus(["detect-changes", "--scope", "all"], { cwd: ctx.projectRoot }) : null;
+  const warnings = commandWarnings([
+    ["gitnexus query", graphQuery],
+    ...detectChanges ? [["gitnexus detect-changes", detectChanges]] : []
+  ]);
+  const relativePath = `.fet/graph-context/${sanitizePathPart(options.changeId ?? options.command)}.md`;
+  await writeGraphContext(
+    join8(ctx.projectRoot, relativePath),
+    renderWorkflowContext({
+      state,
+      command: options.command,
+      args: options.args,
+      changeId: options.changeId,
+      query,
+      goal,
+      sourceContext,
+      graphOutput: commandText(graphQuery),
+      detectChanges: detectChanges ? commandText(detectChanges) : null,
+      warnings
+    })
+  );
+  const global = await ctx.stateStore.getOrCreateGlobal();
+  global.graph ??= {};
+  global.graph.gitnexus = {
+    ...state,
+    workflowContextPath: relativePath,
+    workflowContextUpdatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastWorkflowGraphQuery: query
+  };
+  await ctx.stateStore.writeGlobal(global);
+  return {
+    generated: true,
+    path: relativePath,
+    query,
+    warnings
+  };
+}
+async function refreshGitNexusState(ctx) {
+  const global = await ctx.stateStore.getOrCreateGlobal();
+  global.graph ??= {};
+  const detection = await detectGitNexus();
+  const graph2 = await inspectGitNexusGraph(ctx.projectRoot);
+  const state = mergeGitNexusGraphInfo(toGitNexusState(detection, global.graph.gitnexus), graph2);
+  global.graph.gitnexus = state;
+  await ctx.stateStore.writeGlobal(global);
+  return state;
+}
+function isGraphReadable(state) {
+  return Boolean(state.installed && state.graphExists);
+}
+async function writeGraphContext(path, content) {
+  await mkdir4(dirname5(path), { recursive: true });
+  await atomicWrite(path, content);
+}
+function renderProjectContext(options) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-context
+scope: project
+FET:END -->
+
+# FET GitNexus Project Graph Context
+
+Generated at: ${(/* @__PURE__ */ new Date()).toISOString()}
+Trigger: ${options.trigger}
+
+Use this file before broad repository scans in FET/OpenSpec work. Treat it as graph-derived context: confirm concrete behavior by reading the source files it points to.
+
+## Graph State
+
+- Provider: GitNexus
+- Installed: ${options.state.installed ? "yes" : "no"}
+- Version: ${options.state.version ?? "unknown"}
+- Graph path: ${options.state.graphPath ?? ".gitnexus"}
+- Graph exists: ${options.state.graphExists ? "yes" : "no"}
+- Last indexed at: ${options.state.lastIndexedAt ?? "unknown"}
+
+## GitNexus Status
+
+\`\`\`text
+${clip(options.status, MAX_GRAPH_OUTPUT)}
+\`\`\`
+
+## Project Query
+
+- Query: ${options.query}
+- Goal: ${options.goal}
+
+\`\`\`text
+${clip(options.graphOutput, MAX_GRAPH_OUTPUT)}
+\`\`\`
+${renderWarnings(options.warnings)}
+`;
+}
+function renderWorkflowContext(options) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-context
+scope: workflow
+FET:END -->
+
+# FET GitNexus Workflow Graph Context
+
+Generated at: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+Read this before editing or generating OpenSpec artifacts for this workflow. Use the graph output to narrow likely files, symbols, dependencies, and impact areas. If it conflicts with OpenSpec artifacts or source code, OpenSpec artifacts and source code win.
+
+## Workflow
+
+- FET command: ${options.command}
+- Args: ${options.args.length ? options.args.join(" ") : "(none)"}
+- Change: ${options.changeId ?? "(none)"}
+- Graph path: ${options.state.graphPath ?? ".gitnexus"}
+- Last indexed at: ${options.state.lastIndexedAt ?? "unknown"}
+
+## OpenSpec Context Used For Query
+
+\`\`\`text
+${clip(options.sourceContext || "(no change artifacts found yet)", MAX_SOURCE_CONTEXT)}
+\`\`\`
+
+## GitNexus Query
+
+- Query: ${options.query}
+- Goal: ${options.goal}
+
+\`\`\`text
+${clip(options.graphOutput, MAX_GRAPH_OUTPUT)}
+\`\`\`
+${options.detectChanges ? `
+## GitNexus Change Impact
+
+\`\`\`text
+${clip(options.detectChanges, MAX_GRAPH_OUTPUT)}
+\`\`\`
+` : ""}
+${renderWarnings(options.warnings)}
+`;
+}
+function renderWarnings(warnings) {
+  if (!warnings.length) {
+    return "";
+  }
+  return `
+## Warnings
+
+${warnings.map((warning) => `- ${warning}`).join("\n")}
+`;
+}
+async function collectOpenSpecContext(projectRoot, changeId) {
+  if (!changeId) {
+    return "";
+  }
+  const changeRoot = join8(projectRoot, "openspec", "changes", changeId);
+  const chunks = [];
+  for (const file of ["proposal.md", "design.md", "tasks.md", "README.md"]) {
+    const content = await readOptional(join8(changeRoot, file));
+    if (content) {
+      chunks.push(`## ${file}
+${content}`);
+    }
+  }
+  const specsRoot = join8(changeRoot, "specs");
+  for (const spec of await listSpecFiles(specsRoot)) {
+    const content = await readOptional(spec.path);
+    if (content) {
+      chunks.push(`## ${spec.label}
+${content}`);
+    }
+  }
+  return clip(chunks.join("\n\n"), MAX_SOURCE_CONTEXT);
+}
+async function listSpecFiles(specsRoot) {
+  try {
+    const capabilities = await readdir(specsRoot, { withFileTypes: true });
+    return capabilities.filter((entry) => entry.isDirectory()).map((entry) => ({
+      path: join8(specsRoot, entry.name, "spec.md"),
+      label: `specs/${entry.name}/spec.md`
+    }));
+  } catch {
+    return [];
+  }
+}
+async function readOptional(path) {
+  try {
+    return await readFile5(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function buildWorkflowQuery(options, sourceContext) {
+  const artifactTerms = normalizeWhitespace(sourceContext).slice(0, 1200);
+  return normalizeWhitespace(
+    [
+      `FET OpenSpec ${options.command}`,
+      options.changeId ? `change ${options.changeId}` : "",
+      options.args.join(" "),
+      artifactTerms
+    ].join(" ")
+  );
+}
+function workflowGoal(command) {
+  if (command === "apply") {
+    return "Find implementation files, symbols, dependencies, and likely blast radius for the current OpenSpec tasks.";
+  }
+  if (command === "verify") {
+    return "Find affected flows and source areas that should be checked while verifying this OpenSpec change.";
+  }
+  if (["explore", "propose", "new", "continue", "ff"].includes(command)) {
+    return "Find relevant modules, entry points, and existing behavior to make OpenSpec artifacts precise.";
+  }
+  return "Find relevant repository context for this FET/OpenSpec workflow command.";
+}
+function shouldDetectChanges(command) {
+  return ["apply", "verify", "sync"].includes(command);
+}
+function commandText(result) {
+  const output = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+  return output || `exit ${result.exitCode}`;
+}
+function commandWarnings(results) {
+  return results.filter(([, result]) => result.exitCode !== 0).map(([label, result]) => `${label} exited with ${result.exitCode}: ${firstLine(commandText(result))}`);
+}
+function firstLine(value) {
+  return value.trim().split(/\r?\n/)[0]?.trim() || "no output";
+}
+function clip(value, max) {
+  if (value.length <= max) {
+    return value;
+  }
+  return `${value.slice(0, max)}
+
+[truncated ${value.length - max} characters]`;
+}
+function normalizeWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function sanitizePathPart(value) {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "workflow";
+}
+
+// src/commands/graph.ts
 async function graphCommand(ctx, action, args = []) {
   switch (action) {
     case "status":
@@ -459,38 +779,41 @@ async function graphCommand(ctx, action, args = []) {
 }
 async function graphStatusCommand(ctx) {
   const result = await refreshGraphState(ctx, { runStatus: true });
-  const warnings = result.state.installed ? [] : ["GitNexus is not installed. Run fet graph setup for installation handoff instructions."];
+  const warnings = result.state.installed ? [] : [
+    ctx.language === "en" ? "GitNexus is not installed. Run fet graph setup for installation handoff instructions." : "\u5C1A\u672A\u5B89\u88C5 GitNexus\u3002\u8FD0\u884C fet graph setup \u83B7\u53D6\u5B89\u88C5\u4EA4\u63A5\u8BF4\u660E\u3002"
+  ];
   ctx.output.result({
     ok: true,
     command: "graph status",
-    summary: result.state.installed ? `GitNexus graph status checked. Graph ${result.state.graphExists ? "exists" : "does not exist"} at ${result.state.graphPath ?? ".gitnexus"}.` : "GitNexus is not installed. Graph support remains optional.",
+    summary: ctx.language === "en" ? result.state.installed ? `GitNexus graph status checked. Graph ${result.state.graphExists ? "exists" : "does not exist"} at ${result.state.graphPath ?? ".gitnexus"}.` : "GitNexus is not installed. Graph support remains optional." : result.state.installed ? `\u5DF2\u68C0\u67E5 GitNexus \u4EE3\u7801\u56FE\u72B6\u6001\u3002\u4EE3\u7801\u56FE${result.state.graphExists ? "\u5B58\u5728" : "\u4E0D\u5B58\u5728"}\uFF0C\u8DEF\u5F84\u4E3A ${result.state.graphPath ?? ".gitnexus"}\u3002` : "\u5C1A\u672A\u5B89\u88C5 GitNexus\u3002\u4EE3\u7801\u56FE\u80FD\u529B\u4FDD\u6301\u53EF\u9009\u3002",
     warnings,
-    nextSteps: result.state.installed && !result.state.graphExists ? ["Run fet graph init to build the first GitNexus graph"] : void 0,
+    nextSteps: result.state.installed && !result.state.graphExists ? [ctx.language === "en" ? "Run fet graph init to build the first GitNexus graph" : "\u8FD0\u884C fet graph init \u751F\u6210\u7B2C\u4E00\u4EFD GitNexus \u4EE3\u7801\u56FE"] : void 0,
     data: result
   });
 }
 async function graphDoctorCommand(ctx) {
   const result = await refreshGraphState(ctx, { runStatus: true });
   const warnings = [
-    ...!result.state.installed ? ["GitNexus is not installed."] : [],
-    ...result.state.installed && !result.state.graphExists ? ["GitNexus is installed but no graph directory was found."] : [],
-    ...!result.state.handoffPath ? ["Graph handoff instructions have not been generated."] : []
+    ...!result.state.installed ? [ctx.language === "en" ? "GitNexus is not installed." : "\u5C1A\u672A\u5B89\u88C5 GitNexus\u3002"] : [],
+    ...result.state.installed && !result.state.graphExists ? [ctx.language === "en" ? "GitNexus is installed but no graph directory was found." : "\u5DF2\u5B89\u88C5 GitNexus\uFF0C\u4F46\u672A\u53D1\u73B0\u4EE3\u7801\u56FE\u76EE\u5F55\u3002"] : [],
+    ...!result.state.handoffPath ? [ctx.language === "en" ? "Graph handoff instructions have not been generated." : "\u5C1A\u672A\u751F\u6210\u4EE3\u7801\u56FE\u4F7F\u7528\u4EA4\u63A5\u8BF4\u660E\u3002"] : []
   ];
   ctx.output.result({
     ok: true,
     command: "graph doctor",
-    summary: warnings.length ? `Graph doctor completed with ${warnings.length} warning(s).` : "Graph doctor completed without warnings.",
+    summary: ctx.language === "en" ? warnings.length ? `Graph doctor completed with ${warnings.length} warning(s).` : "Graph doctor completed without warnings." : warnings.length ? `\u4EE3\u7801\u56FE\u8BCA\u65AD\u5B8C\u6210\uFF0C\u53D1\u73B0 ${warnings.length} \u4E2A\u8B66\u544A\u3002` : "\u4EE3\u7801\u56FE\u8BCA\u65AD\u5B8C\u6210\uFF0C\u672A\u53D1\u73B0\u8B66\u544A\u3002",
     warnings,
-    nextSteps: warnings.length ? ["Run fet graph setup", "Run fet graph handoff", "Run fet graph init when GitNexus is installed"] : void 0,
+    nextSteps: warnings.length ? ctx.language === "en" ? ["Run fet graph setup", "Run fet graph handoff", "Run fet graph init when GitNexus is installed"] : ["\u8FD0\u884C fet graph setup", "\u8FD0\u884C fet graph handoff", "\u5B89\u88C5 GitNexus \u540E\u8FD0\u884C fet graph init"] : void 0,
     data: result
   });
 }
 async function graphSetupCommand(ctx) {
   let result;
-  const handoffPath = join8(ctx.projectRoot, ".fet", "graph-setup.md");
+  const handoffPath = join9(ctx.projectRoot, ".fet", "graph-setup.md");
+  const installCommand = process.env.FET_GITNEXUS_INSTALL_COMMAND?.trim() || null;
   await withProjectLock(ctx.projectRoot, { command: "graph setup", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
     result = await refreshGraphState(ctx, { write: false });
-    await writeHandoffFile(handoffPath, renderGraphSetupHandoff(result.state));
+    await writeHandoffFile(handoffPath, renderGraphSetupHandoff(result.state, { installCommand, language: ctx.language }));
     const global = await ctx.stateStore.getOrCreateGlobal();
     global.graph ??= {};
     global.graph.gitnexus = {
@@ -503,21 +826,29 @@ async function graphSetupCommand(ctx) {
   ctx.output.result({
     ok: true,
     command: "graph setup",
-    summary: "GitNexus setup handoff generated.",
-    warnings: result.state.installed ? [] : ["GitNexus is not installed. The handoff explains installation and IDE-assisted setup options."],
-    nextSteps: result.state.installed ? ["Run gitnexus setup if you want to configure IDE/MCP integrations", "Run fet graph init"] : ["Open .fet/graph-setup.md in your IDE AI"],
+    summary: ctx.language === "en" ? "GitNexus IDE-assisted setup playbook generated." : "\u5DF2\u751F\u6210 GitNexus IDE LLM \u8F85\u52A9\u5B89\u88C5\u4EFB\u52A1\u4E66\u3002",
+    warnings: result.state.installed ? [] : [
+      ctx.language === "en" ? "GitNexus is not installed. The playbook lets the current IDE LLM guide installation with user confirmation before risky commands." : "\u5C1A\u672A\u5B89\u88C5 GitNexus\u3002\u4EFB\u52A1\u4E66\u4F1A\u6307\u5BFC\u5F53\u524D IDE LLM \u63A8\u8FDB\u5B89\u88C5\uFF0C\u5E76\u5728\u9AD8\u98CE\u9669\u547D\u4EE4\u524D\u8BF7\u6C42\u7528\u6237\u786E\u8BA4\u3002"
+    ],
+    nextSteps: result.state.installed ? [
+      ctx.language === "en" ? "Ask your IDE AI to read .fet/graph-setup.md and run the optional gitnexus setup flow if you want IDE/MCP integration" : "\u8BA9\u5F53\u524D IDE AI \u9605\u8BFB .fet/graph-setup.md\uFF0C\u5E76\u5728\u9700\u8981 IDE/MCP \u96C6\u6210\u65F6\u6309\u786E\u8BA4\u6D41\u7A0B\u8FD0\u884C gitnexus setup",
+      "fet graph init"
+    ] : [
+      ctx.language === "en" ? "Ask your current IDE AI to read .fet/graph-setup.md and follow the installation playbook" : "\u8BA9\u5F53\u524D IDE AI \u9605\u8BFB .fet/graph-setup.md\uFF0C\u5E76\u6309\u5B89\u88C5\u4EFB\u52A1\u4E66\u63A8\u8FDB"
+    ],
     data: {
       path: ".fet/graph-setup.md",
+      installCommandConfigured: Boolean(installCommand),
       gitnexus: result.state
     }
   });
 }
 async function graphHandoffCommand(ctx) {
   let result;
-  const handoffPath = join8(ctx.projectRoot, ".fet", "graph-handoff.md");
+  const handoffPath = join9(ctx.projectRoot, ".fet", "graph-handoff.md");
   await withProjectLock(ctx.projectRoot, { command: "graph handoff", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
     result = await refreshGraphState(ctx, { runStatus: true, write: false });
-    await writeHandoffFile(handoffPath, renderGraphUsageHandoff(result.state));
+    await writeHandoffFile(handoffPath, renderGraphUsageHandoff(result.state, ctx.language));
     const global = await ctx.stateStore.getOrCreateGlobal();
     global.graph ??= {};
     global.graph.gitnexus = {
@@ -530,9 +861,11 @@ async function graphHandoffCommand(ctx) {
   ctx.output.result({
     ok: true,
     command: "graph handoff",
-    summary: "GitNexus graph usage handoff generated.",
-    warnings: result.state.installed ? [] : ["GitNexus is not installed. The handoff still documents the fallback behavior."],
-    nextSteps: ["Cursor/Codex/OpenCode: read .fet/graph-handoff.md before broad repository scans"],
+    summary: ctx.language === "en" ? "GitNexus graph usage handoff generated." : "\u5DF2\u751F\u6210 GitNexus \u4EE3\u7801\u56FE\u4F7F\u7528\u4EA4\u63A5\u8BF4\u660E\u3002",
+    warnings: result.state.installed ? [] : [
+      ctx.language === "en" ? "GitNexus is not installed. The handoff still documents the fallback behavior." : "\u5C1A\u672A\u5B89\u88C5 GitNexus\u3002\u4EA4\u63A5\u8BF4\u660E\u4ECD\u4F1A\u8BB0\u5F55\u56DE\u9000\u884C\u4E3A\u3002"
+    ],
+    nextSteps: ctx.language === "en" ? ["Cursor/Codex/OpenCode: read .fet/graph-handoff.md before broad repository scans"] : ["Cursor/Codex/OpenCode\uFF1A\u5927\u8303\u56F4\u626B\u63CF\u4ED3\u5E93\u524D\u5148\u9605\u8BFB .fet/graph-handoff.md"],
     data: {
       path: ".fet/graph-handoff.md",
       gitnexus: result.state
@@ -544,7 +877,7 @@ async function graphAnalyzeCommand(ctx, mode, args) {
   if (!detection.installed) {
     throw new FetError({
       code: "GRAPH_PROVIDER_NOT_FOUND" /* GraphProviderNotFound */,
-      message: "GitNexus is not installed or is not available on PATH.",
+      message: ctx.language === "en" ? "GitNexus is not installed or is not available on PATH." : "\u5C1A\u672A\u5B89\u88C5 GitNexus\uFF0C\u6216 GitNexus \u4E0D\u5728 PATH \u4E2D\u3002",
       details: { executable: detection.executablePath, error: detection.error },
       suggestedCommand: "fet graph setup"
     });
@@ -553,27 +886,33 @@ async function graphAnalyzeCommand(ctx, mode, args) {
   if (run.exitCode !== 0) {
     throw new FetError({
       code: "GRAPH_COMMAND_FAILED" /* GraphCommandFailed */,
-      message: "GitNexus analyze failed.",
+      message: ctx.language === "en" ? "GitNexus analyze failed." : "GitNexus analyze \u6267\u884C\u5931\u8D25\u3002",
       details: { command: run.command.join(" "), exitCode: run.exitCode, stdout: run.stdout, stderr: run.stderr },
       suggestedCommand: "fet graph doctor"
     });
   }
   const result = await refreshGraphState(ctx, { write: false });
+  const graphContext = await buildProjectGraphContext(ctx, result.state, `fet graph ${mode}`);
   const global = await ctx.stateStore.getOrCreateGlobal();
   global.graph ??= {};
   global.graph.gitnexus = {
     ...result.state,
-    lastRefreshAt: (/* @__PURE__ */ new Date()).toISOString()
+    lastRefreshAt: (/* @__PURE__ */ new Date()).toISOString(),
+    projectContextPath: graphContext.path,
+    projectContextUpdatedAt: graphContext.generated ? (/* @__PURE__ */ new Date()).toISOString() : result.state.projectContextUpdatedAt ?? null
   };
   await ctx.stateStore.writeGlobal(global);
   ctx.output.result({
     ok: true,
     command: `graph ${mode}`,
-    summary: mode === "init" ? "GitNexus graph initialized." : "GitNexus graph refreshed.",
-    warnings: result.state.graphExists ? [] : ["GitNexus analyze completed, but the configured graph directory was not found."],
-    nextSteps: ["Run fet graph status", "Use .fet/graph-handoff.md or generated IDE prompts to prefer graph context"],
+    summary: ctx.language === "en" ? mode === "init" ? "GitNexus graph initialized." : "GitNexus graph refreshed." : mode === "init" ? "\u5DF2\u521D\u59CB\u5316 GitNexus \u4EE3\u7801\u56FE\u3002" : "\u5DF2\u5237\u65B0 GitNexus \u4EE3\u7801\u56FE\u3002",
+    warnings: result.state.graphExists ? [] : [
+      ctx.language === "en" ? "GitNexus analyze completed, but the configured graph directory was not found." : "GitNexus analyze \u5DF2\u5B8C\u6210\uFF0C\u4F46\u672A\u53D1\u73B0\u914D\u7F6E\u7684\u4EE3\u7801\u56FE\u76EE\u5F55\u3002"
+    ],
+    nextSteps: ctx.language === "en" ? ["Run fet graph status", "Read .fet/graph-context/project.md before broad scans", "Use .fet/graph-handoff.md or generated IDE prompts to prefer graph context"] : ["\u8FD0\u884C fet graph status", "\u4F7F\u7528 .fet/graph-handoff.md \u6216\u751F\u6210\u7684 IDE \u63D0\u793A\uFF0C\u4F18\u5148\u53C2\u8003\u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587"],
     data: {
       gitnexus: global.graph.gitnexus,
+      graphContext,
       run: {
         command: run.command,
         stdout: run.stdout.trim(),
@@ -593,7 +932,7 @@ async function refreshGraphState(ctx, options = {}) {
     gitnexusStatus = await runGitNexus(["status"], { cwd: ctx.projectRoot });
     state = {
       ...state,
-      lastStatus: firstLine(gitnexusStatus.stdout) || firstLine(gitnexusStatus.stderr) || `exit ${gitnexusStatus.exitCode}`
+      lastStatus: firstLine2(gitnexusStatus.stdout) || firstLine2(gitnexusStatus.stderr) || `exit ${gitnexusStatus.exitCode}`
     };
   }
   if (options.write ?? true) {
@@ -611,18 +950,19 @@ async function refreshGraphState(ctx, options = {}) {
   };
 }
 async function writeHandoffFile(path, content) {
-  await mkdir4(dirname5(path), { recursive: true });
+  await mkdir5(dirname6(path), { recursive: true });
   await atomicWrite(path, content);
 }
-function renderGraphSetupHandoff(state) {
-  return `<!-- FET:MANAGED
+function renderGraphSetupHandoff(state, options) {
+  if (options.language === "en") {
+    return `<!-- FET:MANAGED
 schemaVersion: 1
 generator: graph-setup
 FET:END -->
 
-# FET Graph Setup
+# FET GitNexus IDE Setup Playbook
 
-GitNexus graph support is optional. FET does not install GitNexus automatically and does not require graph support for OpenSpec workflows.
+This file is written for the current IDE LLM. Use it to help the user install and verify optional GitNexus graph support. GitNexus is optional; FET/OpenSpec workflows must continue to work when it is unavailable.
 
 Current status:
 
@@ -631,24 +971,70 @@ Current status:
 - Version: ${state.version ?? "unknown"}
 - Graph path: ${state.graphPath ?? ".gitnexus"}
 - Graph exists: ${state.graphExists ? "yes" : "no"}
+- Configured install command: ${options.installCommand ?? "none"}
 
-Suggested setup flow:
+IDE LLM setup flow:
 
-1. If GitNexus is not installed, install it using the method recommended by the GitNexus project.
-2. If you want GitNexus MCP or IDE integration, run \`gitnexus setup\` yourself after reviewing what it changes.
-3. Return to this project and run \`fet graph init\` to build the first graph.
-4. Run \`fet graph handoff\` so IDE AI can prefer graph context before broad repository scans.
+1. Check the shell, operating system, package managers, and PATH. Run only read-only detection commands at first.
+2. Run \`gitnexus --version\` or the executable shown above. If it succeeds, skip installation and continue to verification.
+3. If GitNexus is missing and \`FET_GITNEXUS_INSTALL_COMMAND\` is configured, explain that command to the user and ask for approval before running it.
+4. If no install command is configured, find the official GitNexus installation instructions or ask the user for the preferred install method. Do not invent an installer.
+5. Before running any command that downloads software, installs globally, changes PATH, modifies user home files, or changes IDE/MCP configuration, show the exact command and wait for user approval.
+6. After installation, verify with \`gitnexus --version\`.
+7. If the user wants IDE/MCP integration, run \`gitnexus setup\` only after explaining what it may change and receiving approval.
+8. Return to this project and run \`fet graph init\` to build the first graph.
+9. Run \`fet graph handoff\` so future IDE AI work can prefer graph context before broad repository scans.
 
 Guardrails:
 
 - Do not block FET/OpenSpec commands when GitNexus is unavailable.
 - Do not generate or modify application code during setup.
-- Do not run global IDE configuration commands unless the user explicitly approves them.
+- Do not silently install software or modify global/user-level configuration.
+- If installation fails, summarize the failing command, stderr, and the next manual step.
 `;
-}
-function renderGraphUsageHandoff(state) {
+  }
   return `<!-- FET:MANAGED
 schemaVersion: 1
+generator: graph-setup
+FET:END -->
+
+# FET GitNexus IDE \u5B89\u88C5\u4EFB\u52A1\u4E66
+
+\u672C\u6587\u6863\u5199\u7ED9\u5F53\u524D IDE LLM\u3002\u8BF7\u7528\u5B83\u5E2E\u52A9\u7528\u6237\u5B89\u88C5\u5E76\u9A8C\u8BC1\u53EF\u9009\u7684 GitNexus \u4EE3\u7801\u56FE\u80FD\u529B\u3002GitNexus \u662F\u53EF\u9009\u80FD\u529B\uFF1B\u5373\u4F7F\u4E0D\u53EF\u7528\uFF0CFET/OpenSpec \u4E3B\u6D41\u7A0B\u4E5F\u5FC5\u987B\u7EE7\u7EED\u53EF\u7528\u3002
+
+\u5F53\u524D\u72B6\u6001\uFF1A
+
+- \u5DF2\u5B89\u88C5\uFF1A${state.installed ? "\u662F" : "\u5426"}
+- \u53EF\u6267\u884C\u6587\u4EF6\uFF1A${state.executablePath ?? "gitnexus"}
+- \u7248\u672C\uFF1A${state.version ?? "unknown"}
+- \u56FE\u8DEF\u5F84\uFF1A${state.graphPath ?? ".gitnexus"}
+- \u56FE\u5DF2\u5B58\u5728\uFF1A${state.graphExists ? "\u662F" : "\u5426"}
+- \u5DF2\u914D\u7F6E\u5B89\u88C5\u547D\u4EE4\uFF1A${options.installCommand ?? "\u65E0"}
+
+IDE LLM \u5B89\u88C5\u6D41\u7A0B\uFF1A
+
+1. \u5148\u68C0\u6D4B shell\u3001\u64CD\u4F5C\u7CFB\u7EDF\u3001\u5305\u7BA1\u7406\u5668\u548C PATH\u3002\u8D77\u6B65\u9636\u6BB5\u53EA\u8FD0\u884C\u53EA\u8BFB\u68C0\u6D4B\u547D\u4EE4\u3002
+2. \u8FD0\u884C \`gitnexus --version\` \u6216\u4E0A\u65B9\u663E\u793A\u7684\u53EF\u6267\u884C\u6587\u4EF6\u3002\u5982\u679C\u6210\u529F\uFF0C\u8DF3\u8FC7\u5B89\u88C5\u5E76\u8FDB\u5165\u9A8C\u8BC1\u3002
+3. \u5982\u679C GitNexus \u7F3A\u5931\u4E14\u5DF2\u914D\u7F6E \`FET_GITNEXUS_INSTALL_COMMAND\`\uFF0C\u5148\u5411\u7528\u6237\u89E3\u91CA\u8BE5\u547D\u4EE4\uFF0C\u518D\u7B49\u5F85\u7528\u6237\u6279\u51C6\u540E\u6267\u884C\u3002
+4. \u5982\u679C\u6CA1\u6709\u914D\u7F6E\u5B89\u88C5\u547D\u4EE4\uFF0C\u67E5\u627E GitNexus \u5B98\u65B9\u5B89\u88C5\u8BF4\u660E\uFF0C\u6216\u8BE2\u95EE\u7528\u6237\u5E0C\u671B\u4F7F\u7528\u7684\u5B89\u88C5\u65B9\u5F0F\u3002\u4E0D\u8981\u81C6\u9020\u5B89\u88C5\u547D\u4EE4\u3002
+5. \u4EFB\u4F55\u4F1A\u4E0B\u8F7D\u8F6F\u4EF6\u3001\u5168\u5C40\u5B89\u88C5\u3001\u4FEE\u6539 PATH\u3001\u5199\u5165\u7528\u6237\u76EE\u5F55\u6216\u4FEE\u6539 IDE/MCP \u914D\u7F6E\u7684\u547D\u4EE4\uFF0C\u6267\u884C\u524D\u90FD\u8981\u5C55\u793A\u5B8C\u6574\u547D\u4EE4\u5E76\u7B49\u5F85\u7528\u6237\u786E\u8BA4\u3002
+6. \u5B89\u88C5\u540E\u8FD0\u884C \`gitnexus --version\` \u9A8C\u8BC1\u3002
+7. \u5982\u679C\u7528\u6237\u9700\u8981 IDE/MCP \u96C6\u6210\uFF0C\u5148\u8BF4\u660E \`gitnexus setup\` \u53EF\u80FD\u4FEE\u6539\u7684\u5185\u5BB9\uFF0C\u83B7\u5F97\u786E\u8BA4\u540E\u518D\u8FD0\u884C\u3002
+8. \u56DE\u5230\u672C\u9879\u76EE\u8FD0\u884C \`fet graph init\`\uFF0C\u751F\u6210\u7B2C\u4E00\u4EFD\u4EE3\u7801\u56FE\u3002
+9. \u8FD0\u884C \`fet graph handoff\`\uFF0C\u8BA9\u540E\u7EED IDE AI \u5728\u5927\u8303\u56F4\u626B\u63CF\u524D\u4F18\u5148\u4F7F\u7528\u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587\u3002
+
+\u7EA6\u675F\uFF1A
+
+- GitNexus \u4E0D\u53EF\u7528\u65F6\uFF0C\u4E0D\u8981\u963B\u585E FET/OpenSpec \u547D\u4EE4\u3002
+- \u5B89\u88C5\u8FC7\u7A0B\u4E2D\u4E0D\u8981\u751F\u6210\u6216\u4FEE\u6539\u4E1A\u52A1\u4EE3\u7801\u3002
+- \u4E0D\u8981\u9759\u9ED8\u5B89\u88C5\u8F6F\u4EF6\uFF0C\u4E5F\u4E0D\u8981\u9759\u9ED8\u4FEE\u6539\u5168\u5C40\u6216\u7528\u6237\u7EA7\u914D\u7F6E\u3002
+- \u5982\u679C\u5B89\u88C5\u5931\u8D25\uFF0C\u6C47\u603B\u5931\u8D25\u547D\u4EE4\u3001stderr \u548C\u4E0B\u4E00\u6B65\u4EBA\u5DE5\u5904\u7406\u5EFA\u8BAE\u3002
+`;
+}
+function renderGraphUsageHandoff(state, language) {
+  if (language === "en") {
+    return `<!-- FET:MANAGED
+schemaVersion: 1
 generator: graph-handoff
 FET:END -->
 
@@ -676,26 +1062,57 @@ When producing OpenSpec artifacts:
 - Use graph context to make proposal, design, specs, and tasks more precise.
 - Avoid large repository scans when the graph already narrows the relevant area.
 - Keep all generated artifacts in the normal OpenSpec change directory.
+`;
+  }
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-handoff
+FET:END -->
+
+# FET \u4EE3\u7801\u56FE\u4EA4\u63A5\u8BF4\u660E
+
+\u5728\u5927\u8303\u56F4\u626B\u63CF\u4ED3\u5E93\u524D\uFF0C\u4F18\u5148\u628A GitNexus \u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587\u4F5C\u4E3A\u53EF\u9009\u7684\u7B2C\u4E00\u8F6E\u7EBF\u7D22\u3002
+
+\u5F53\u524D\u72B6\u6001\uFF1A
+
+- \u5DF2\u5B89\u88C5\uFF1A${state.installed ? "\u662F" : "\u5426"}
+- \u56FE\u8DEF\u5F84\uFF1A${state.graphPath ?? ".gitnexus"}
+- \u56FE\u5DF2\u5B58\u5728\uFF1A${state.graphExists ? "\u662F" : "\u5426"}
+- \u6700\u540E\u7D22\u5F15\u65F6\u95F4\uFF1A${state.lastIndexedAt ?? "unknown"}
+- \u6700\u540E\u72B6\u6001\uFF1A${state.lastStatus ?? "unknown"}
+
+\u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587\u53EF\u7528\u65F6\uFF1A
+
+1. \u7528\u4EE3\u7801\u56FE\u8BC6\u522B\u53EF\u80FD\u76F8\u5173\u7684\u6A21\u5757\u3001\u4F9D\u8D56\u548C\u63D2\u5165\u70B9\u3002
+2. \u53EA\u8BFB\u53D6\u9700\u8981\u786E\u8BA4\u884C\u4E3A\u7684\u5177\u4F53\u6E90\u7801\u6587\u4EF6\u3002
+3. \u5F53\u4EE3\u7801\u56FE\u63A8\u65AD\u4E0E OpenSpec \u4EA7\u7269\u6216 AGENTS.md \u51B2\u7A81\u65F6\uFF0C\u4F18\u5148\u76F8\u4FE1 OpenSpec \u4EA7\u7269\u548C AGENTS.md\u3002
+4. \u5982\u679C\u4EE3\u7801\u56FE\u7F3A\u5931\u3001\u8FC7\u671F\u6216\u4E0D\u5B8C\u6574\uFF0C\u56DE\u9000\u5230\u666E\u901A\u4ED3\u5E93\u68C0\u67E5\u3002
+
+\u751F\u6210 OpenSpec \u4EA7\u7269\u65F6\uFF1A
+
+- \u7528\u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587\u8BA9 proposal\u3001design\u3001specs \u548C tasks \u66F4\u7CBE\u786E\u3002
+- \u5F53\u4EE3\u7801\u56FE\u5DF2\u7ECF\u7F29\u5C0F\u76F8\u5173\u8303\u56F4\u65F6\uFF0C\u907F\u514D\u5927\u8303\u56F4\u4ED3\u5E93\u626B\u63CF\u3002
+- \u6240\u6709\u751F\u6210\u4EA7\u7269\u4ECD\u5199\u5165\u6B63\u5E38\u7684 OpenSpec change \u76EE\u5F55\u3002
 `;
 }
-function firstLine(value) {
+function firstLine2(value) {
   return value.trim().split(/\r?\n/)[0]?.trim() || null;
 }
 
 // src/commands/init.ts
-import { readFile as readFile7, stat as stat4 } from "fs/promises";
-import { join as join11 } from "path";
+import { readFile as readFile8, stat as stat4 } from "fs/promises";
+import { join as join12 } from "path";
 
 // src/version.ts
 import { existsSync, readFileSync } from "fs";
-import { dirname as dirname6, join as join9, parse } from "path";
+import { dirname as dirname7, join as join10, parse } from "path";
 import { fileURLToPath } from "url";
 var FET_VERSION = readPackageVersion();
 function readPackageVersion() {
-  let currentDir = dirname6(fileURLToPath(import.meta.url));
+  let currentDir = dirname7(fileURLToPath(import.meta.url));
   const root = parse(currentDir).root;
   while (true) {
-    const packageJsonPath = join9(currentDir, "package.json");
+    const packageJsonPath = join10(currentDir, "package.json");
     if (existsSync(packageJsonPath)) {
       const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
       if (typeof packageJson.version === "string" && packageJson.version.length > 0) {
@@ -706,7 +1123,7 @@ function readPackageVersion() {
     if (currentDir === root) {
       throw new Error("\u65E0\u6CD5\u5B9A\u4F4D FET package.json");
     }
-    currentDir = dirname6(currentDir);
+    currentDir = dirname7(currentDir);
   }
 }
 
@@ -975,8 +1392,8 @@ function renderFetConfig(scan, language = "zh-CN") {
 var KARPATHY_SKILLS_SOURCE = "https://github.com/forrestchang/andrej-karpathy-skills";
 var BEGIN = "<!-- FET:BEGIN ANDREJ-KARPATHY-SKILLS -->";
 var END = "<!-- FET:END ANDREJ-KARPATHY-SKILLS -->";
-function mergeKarpathyClaudeMd(existing) {
-  const block = renderManagedBlock(renderKarpathyClaudeGuidelines());
+function mergeKarpathyClaudeMd(existing, language = "zh-CN") {
+  const block = renderManagedBlock(renderKarpathyClaudeGuidelines(language));
   if (!existing || !existing.trim()) {
     return `${block}
 `;
@@ -1021,10 +1438,10 @@ function renderManagedBlock(content) {
 ${content}
 ${END}`;
 }
-function renderKarpathyClaudeGuidelines() {
-  return `# Andrej Karpathy Inspired Coding Guidelines
+function renderKarpathyClaudeGuidelines(language) {
+  return `# ${language === "en" ? "Andrej Karpathy Inspired Coding Guidelines" : "\u53D7 Andrej Karpathy \u542F\u53D1\u7684\u7F16\u7801\u6307\u5357"}
 
-${renderKarpathyGuidelinesBody()}`;
+${renderKarpathyGuidelinesBody(language)}`;
 }
 function renderKarpathyGuidelinesBody(language = "zh-CN") {
   if (language === "en") {
@@ -1157,18 +1574,18 @@ ${block}
 }
 
 // src/commands/update-context.ts
-import { readFile as readFile6 } from "fs/promises";
-import { join as join10 } from "path";
+import { readFile as readFile7 } from "fs/promises";
+import { join as join11 } from "path";
 
 // src/config/yaml.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import { parseDocument } from "yaml";
 async function mergeFetConfig(configPath, renderedFetYaml) {
   const fetDoc = parseDocument(renderedFetYaml);
   const nextFet = fetDoc.get("fet", true);
   let existing = "";
   try {
-    existing = await readFile5(configPath, "utf8");
+    existing = await readFile6(configPath, "utf8");
   } catch {
     return renderedFetYaml;
   }
@@ -1192,14 +1609,14 @@ async function updateContextCommand(ctx) {
 }
 async function updateContextFiles(ctx) {
   const scan = await ctx.scanner.scan(ctx.projectRoot, {});
-  const agentsPath = join10(ctx.projectRoot, "AGENTS.md");
-  const configPath = join10(ctx.projectRoot, "openspec", "config.yaml");
-  const claudePath = join10(ctx.projectRoot, "CLAUDE.md");
-  const karpathyHandoffPath = join10(ctx.projectRoot, ".fet", "karpathy-guidelines.md");
-  const karpathyCursorPath = join10(ctx.projectRoot, ".cursor", "rules", "karpathy-guidelines.mdc");
-  const existingAgents = await readOptional(agentsPath);
-  const existingClaude = await readOptional(claudePath);
-  const existingKarpathyCursor = await readOptional(karpathyCursorPath);
+  const agentsPath = join11(ctx.projectRoot, "AGENTS.md");
+  const configPath = join11(ctx.projectRoot, "openspec", "config.yaml");
+  const claudePath = join11(ctx.projectRoot, "CLAUDE.md");
+  const karpathyHandoffPath = join11(ctx.projectRoot, ".fet", "karpathy-guidelines.md");
+  const karpathyCursorPath = join11(ctx.projectRoot, ".cursor", "rules", "karpathy-guidelines.mdc");
+  const existingAgents = await readOptional2(agentsPath);
+  const existingClaude = await readOptional2(claudePath);
+  const existingKarpathyCursor = await readOptional2(karpathyCursorPath);
   const warnings = [...scan.warnings];
   if (existingAgents && hasInvalidManagedAutoRegion(existingAgents)) {
     throw new FetError({
@@ -1225,7 +1642,7 @@ async function updateContextFiles(ctx) {
   }
   await atomicWrite(agentsPath, replaceManagedRegion(existingAgents, renderAgentsMd(scan, ctx.language)));
   await atomicWrite(configPath, await mergeFetConfig(configPath, renderFetConfig(scan, ctx.language)));
-  await atomicWrite(claudePath, mergeKarpathyClaudeMd(existingClaude));
+  await atomicWrite(claudePath, mergeKarpathyClaudeMd(existingClaude, ctx.language));
   await atomicWrite(karpathyHandoffPath, renderKarpathyFetHandoff(ctx.language));
   if (!existingKarpathyCursor || existingKarpathyCursor.includes("FET:MANAGED")) {
     await atomicWrite(karpathyCursorPath, renderKarpathyCursorRule(ctx.language));
@@ -1247,9 +1664,9 @@ async function updateContextFiles(ctx) {
   await ctx.stateStore.writeGlobal(state);
   return { warnings };
 }
-async function readOptional(path) {
+async function readOptional2(path) {
   try {
-    return await readFile6(path, "utf8");
+    return await readFile7(path, "utf8");
   } catch {
     return null;
   }
@@ -1257,7 +1674,7 @@ async function readOptional(path) {
 
 // src/commands/init.ts
 async function initCommand(ctx) {
-  const alreadyInitialized = await exists2(join11(ctx.projectRoot, "openspec", "config.yaml"));
+  const alreadyInitialized = await exists2(join12(ctx.projectRoot, "openspec", "config.yaml"));
   let warnings = [];
   await withProjectLock(ctx.projectRoot, { command: "init", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
     const journal = createInitJournal(ctx.fetVersion);
@@ -1309,13 +1726,13 @@ async function initCommand(ctx) {
   });
 }
 async function ensureGitignore(ctx) {
-  const gitignorePath = join11(ctx.projectRoot, ".gitignore");
-  const existing = await readOptional2(gitignorePath);
+  const gitignorePath = join12(ctx.projectRoot, ".gitignore");
+  const existing = await readOptional3(gitignorePath);
   await atomicWrite(gitignorePath, mergeGitignore(existing));
 }
-async function readOptional2(path) {
+async function readOptional3(path) {
   try {
-    return await readFile7(path, "utf8");
+    return await readFile8(path, "utf8");
   } catch {
     return null;
   }
@@ -1330,8 +1747,8 @@ async function exists2(path) {
 }
 
 // src/commands/proxy.ts
-import { readFile as readFile10 } from "fs/promises";
-import { join as join13 } from "path";
+import { readFile as readFile11 } from "fs/promises";
+import { join as join14 } from "path";
 
 // src/state/project.ts
 import { execFile as execFile2 } from "child_process";
@@ -1360,8 +1777,8 @@ async function git(cwd, args) {
 }
 
 // src/state/store.ts
-import { mkdir as mkdir5, readFile as readFile8 } from "fs/promises";
-import { join as join12 } from "path";
+import { mkdir as mkdir6, readFile as readFile9 } from "fs/promises";
+import { join as join13 } from "path";
 
 // src/language.ts
 var DEFAULT_LANGUAGE = "zh-CN";
@@ -1479,7 +1896,7 @@ var StateStore = class {
   project;
   async readGlobal() {
     try {
-      const value = JSON.parse(await readFile8(this.globalPath(), "utf8"));
+      const value = JSON.parse(await readFile9(this.globalPath(), "utf8"));
       assertGlobalState(value);
       return value;
     } catch (error) {
@@ -1494,13 +1911,13 @@ var StateStore = class {
   }
   async writeGlobal(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir5(join12(this.projectRoot, "openspec"), { recursive: true });
+    await mkdir6(join13(this.projectRoot, "openspec"), { recursive: true });
     await atomicWrite(this.globalPath(), `${JSON.stringify(state, null, 2)}
 `);
   }
   async readChange(changeId) {
     try {
-      const value = JSON.parse(await readFile8(this.changePath(changeId), "utf8"));
+      const value = JSON.parse(await readFile9(this.changePath(changeId), "utf8"));
       assertChangeState(value);
       return value;
     } catch (error) {
@@ -1515,15 +1932,15 @@ var StateStore = class {
   }
   async writeChange(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir5(join12(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
+    await mkdir6(join13(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
     await atomicWrite(this.changePath(state.changeId), `${JSON.stringify(state, null, 2)}
 `);
   }
   globalPath() {
-    return join12(this.projectRoot, "openspec", "fet-state.json");
+    return join13(this.projectRoot, "openspec", "fet-state.json");
   }
   changePath(changeId) {
-    return join12(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
+    return join13(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
   }
 };
 function isNotFound(error) {
@@ -1531,11 +1948,11 @@ function isNotFound(error) {
 }
 
 // src/state/tasks.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 async function readCompletedTaskIds(tasksPath) {
   let content;
   try {
-    content = await readFile9(tasksPath, "utf8");
+    content = await readFile10(tasksPath, "utf8");
   } catch {
     return [];
   }
@@ -1566,71 +1983,76 @@ var phaseByCommand = {
 };
 async function proxyCommand(ctx, command, args) {
   const openSpecArgs = stripFetOptions(args);
-  await withProjectLock(
-    ctx.projectRoot,
-    { command, cwd: ctx.cwd, fetVersion: ctx.fetVersion },
-    async () => {
-      if (["sync", "archive", "bulk-archive"].includes(command)) {
-        await assertVerified(ctx);
-      }
-      const mapped = await mapOpenSpecCommand(ctx, command, openSpecArgs);
-      const targetChangeId = command === "archive" ? mapped.args[0] ?? ctx.changeId ?? null : ctx.changeId ?? null;
-      const changelogEntry = command === "archive" && targetChangeId ? await createChangelogEntry(ctx.projectRoot, targetChangeId) : null;
-      const result = await ctx.openSpec.run(mapped.command, mapped.args, { cwd: ctx.projectRoot, stdio: ctx.json ? "pipe" : "inherit" });
-      if (result.exitCode !== 0) {
-        throw new FetError({
-          code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
-          message: `OpenSpec ${command} \u6267\u884C\u5931\u8D25`,
-          details: result,
-          recoverable: true
-        });
-      }
-      if (changelogEntry) {
-        await appendChangelog(ctx.projectRoot, changelogEntry);
-      }
-      const inspection = await ctx.openSpec.inspectProject(ctx.projectRoot);
-      const state = await ctx.stateStore.getOrCreateGlobal();
-      state.openChangeIds = inspection.changes;
-      if (command === "archive") {
-        if (!state.activeChangeId || state.activeChangeId === targetChangeId || !inspection.changes.includes(state.activeChangeId)) {
-          state.activeChangeId = null;
-        }
-        state.verifyAuthorization = null;
-      } else {
-        if (ctx.changeId && inspection.changes.includes(ctx.changeId)) {
-          state.activeChangeId = ctx.changeId;
-        } else if (state.activeChangeId && !inspection.changes.includes(state.activeChangeId)) {
-          state.activeChangeId = inspection.changes.length === 1 ? inspection.changes[0] ?? null : null;
-        } else if (!state.activeChangeId && inspection.changes.length === 1) {
-          state.activeChangeId = inspection.changes[0] ?? null;
-        }
-      }
-      await ctx.stateStore.writeGlobal(state);
-      const changeId = ctx.changeId ?? state.activeChangeId;
-      if (changeId && inspection.changes.includes(changeId)) {
-        const changeInspection = await ctx.openSpec.inspectChange(ctx.projectRoot, changeId);
-        const changeState = await ctx.stateStore.getOrCreateChange(changeId, phaseByCommand[command] ?? "propose");
-        changeState.currentPhase = phaseByCommand[command] ?? changeState.currentPhase;
-        changeState.phases[changeState.currentPhase] = {
-          status: "done",
-          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-        };
-        changeState.lastOpenSpecCommand = {
-          command: mapped.command,
-          args: mapped.args,
-          exitCode: result.exitCode,
-          ranAt: (/* @__PURE__ */ new Date()).toISOString()
-        };
-        changeState.tasks.completedIds = await readCompletedTaskIds(changeInspection.tasksPath);
-        changeState.tasks.lastSyncedAt = (/* @__PURE__ */ new Date()).toISOString();
-        await ctx.stateStore.writeChange(changeState);
+  const runState = {};
+  await withProjectLock(ctx.projectRoot, { command, cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    if (["sync", "archive", "bulk-archive"].includes(command)) {
+      await assertVerified(ctx);
+    }
+    const mapped = await mapOpenSpecCommand(ctx, command, openSpecArgs);
+    const mappedChangeId = extractChangeId(mapped.args);
+    const targetChangeId = command === "archive" ? mapped.args[0] ?? ctx.changeId ?? mappedChangeId : ctx.changeId ?? mappedChangeId;
+    runState.graphContext = await buildWorkflowGraphContext(ctx, {
+      command,
+      args: mapped.args,
+      changeId: targetChangeId
+    });
+    const changelogEntry = command === "archive" && targetChangeId ? await createChangelogEntry(ctx.projectRoot, targetChangeId) : null;
+    const result = await ctx.openSpec.run(mapped.command, mapped.args, { cwd: ctx.projectRoot, stdio: ctx.json ? "pipe" : "inherit" });
+    if (result.exitCode !== 0) {
+      throw new FetError({
+        code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+        message: `OpenSpec ${command} failed.`,
+        details: result,
+        recoverable: true
+      });
+    }
+    if (changelogEntry) {
+      await appendChangelog(ctx.projectRoot, changelogEntry);
+    }
+    const inspection = await ctx.openSpec.inspectProject(ctx.projectRoot);
+    const state = await ctx.stateStore.getOrCreateGlobal();
+    state.openChangeIds = inspection.changes;
+    if (command === "archive") {
+      if (!state.activeChangeId || state.activeChangeId === targetChangeId || !inspection.changes.includes(state.activeChangeId)) {
+        state.activeChangeId = null;
       }
+      state.verifyAuthorization = null;
+    } else if (ctx.changeId && inspection.changes.includes(ctx.changeId)) {
+      state.activeChangeId = ctx.changeId;
+    } else if (state.activeChangeId && !inspection.changes.includes(state.activeChangeId)) {
+      state.activeChangeId = inspection.changes.length === 1 ? inspection.changes[0] ?? null : null;
+    } else if (!state.activeChangeId && inspection.changes.length === 1) {
+      state.activeChangeId = inspection.changes[0] ?? null;
     }
-  );
+    await ctx.stateStore.writeGlobal(state);
+    const changeId = ctx.changeId ?? state.activeChangeId;
+    if (changeId && inspection.changes.includes(changeId)) {
+      const changeInspection = await ctx.openSpec.inspectChange(ctx.projectRoot, changeId);
+      const changeState = await ctx.stateStore.getOrCreateChange(changeId, phaseByCommand[command] ?? "propose");
+      changeState.currentPhase = phaseByCommand[command] ?? changeState.currentPhase;
+      changeState.phases[changeState.currentPhase] = {
+        status: "done",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      changeState.lastOpenSpecCommand = {
+        command: mapped.command,
+        args: mapped.args,
+        exitCode: result.exitCode,
+        ranAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      changeState.tasks.completedIds = await readCompletedTaskIds(changeInspection.tasksPath);
+      changeState.tasks.lastSyncedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await ctx.stateStore.writeChange(changeState);
+    }
+  });
+  const graphContext = runState.graphContext;
   ctx.output.result({
     ok: true,
     command,
-    summary: `fet ${command} \u5B8C\u6210\u3002`
+    summary: `fet ${command} completed.`,
+    warnings: graphContext?.warnings,
+    nextSteps: graphContext?.generated && graphContext.path ? [`Read ${graphContext.path} before broad source scans or implementation decisions.`] : void 0,
+    data: graphContext ? { graphContext } : void 0
   });
 }
 async function createChangelogEntry(projectRoot, changeId) {
@@ -1640,10 +2062,12 @@ async function createChangelogEntry(projectRoot, changeId) {
   };
 }
 async function appendChangelog(projectRoot, entry) {
-  const changelogPath = join13(projectRoot, "CHANGELOG.md");
-  const existing = await readOptional3(changelogPath);
+  const changelogPath = join14(projectRoot, "CHANGELOG.md");
+  const existing = await readOptional4(changelogPath);
+  const legacyContentLabel = "\u66F4\u65B0\u5185\u5BB9";
   const block = `updateTime: ${entry.updateTime}
-\u66F4\u65B0\u5185\u5BB9:${entry.content}
+changeRequirement:${entry.content}
+${legacyContentLabel}:${entry.content}
 `;
   const next = existing?.trimEnd() ? `${existing.trimEnd()}
 
@@ -1651,12 +2075,12 @@ ${block}` : block;
   await atomicWrite(changelogPath, next);
 }
 async function readChangeRequirement(projectRoot, changeId) {
-  const changeRoot = join13(projectRoot, "openspec", "changes", changeId);
-  const proposal = await readOptional3(join13(changeRoot, "proposal.md"));
+  const changeRoot = join14(projectRoot, "openspec", "changes", changeId);
+  const proposal = await readOptional4(join14(changeRoot, "proposal.md"));
   if (proposal) {
     return summarizeMarkdown(proposal);
   }
-  const readme = await readOptional3(join13(changeRoot, "README.md"));
+  const readme = await readOptional4(join14(changeRoot, "README.md"));
   if (readme) {
     return summarizeMarkdown(readme);
   }
@@ -1664,11 +2088,11 @@ async function readChangeRequirement(projectRoot, changeId) {
 }
 function summarizeMarkdown(content) {
   const normalized = content.replace(/\r\n/g, "\n").split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("<!--") && !line.startsWith("---")).join(" ");
-  return normalized || "\u672A\u63D0\u4F9B\u53D8\u66F4\u9700\u6C42";
+  return normalized || "No change requirement found.";
 }
-async function readOptional3(path) {
+async function readOptional4(path) {
   try {
-    return await readFile10(path, "utf8");
+    return await readFile11(path, "utf8");
   } catch {
     return null;
   }
@@ -1690,7 +2114,7 @@ async function passthroughCommand(ctx, command, args) {
   if (result.exitCode !== 0) {
     throw new FetError({
       code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
-      message: `OpenSpec ${command} \u6267\u884C\u5931\u8D25`,
+      message: `OpenSpec ${command} failed.`,
       details: result
     });
   }
@@ -1732,18 +2156,6 @@ async function mapOpenSpecCommand(ctx, command, args) {
       return { command: "new", args: args[0] === "change" ? args : ["change", ...args] };
     case "archive":
       return { command: "archive", args: [ctx.changeId ?? args[0] ?? await requireChangeId(ctx), ...args.slice(ctx.changeId ? 0 : 1)] };
-    /*
-    case "bulk-archive":
-      throw new FetError({
-        code: ErrorCode.InvalidArguments,
-        message: "OpenSpec 1.2.0 不提供 bulk-archive 顶层命令",
-        suggestedCommand: "逐个执行 fet archive --change <change-id>"
-      });
-    case "explore":
-      return { command: "explore", args: ctx.changeId ? ["--change", ctx.changeId, ...args] : args };
-    case "onboard":
-      return { command: "instructions", args: [] };
-    */
     default:
       return { command, args };
   }
@@ -1763,6 +2175,18 @@ async function withDefaultChange(ctx, args, allowWithArgs = false) {
   }
   return ["--change", await requireChangeId(ctx), ...args];
 }
+function extractChangeId(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--change") {
+      return args[index + 1] ?? null;
+    }
+    if (arg?.startsWith("--change=")) {
+      return arg.slice("--change=".length) || null;
+    }
+  }
+  return null;
+}
 async function requireChangeId(ctx) {
   if (ctx.changeId) {
     return ctx.changeId;
@@ -1777,9 +2201,9 @@ async function requireChangeId(ctx) {
   }
   throw new FetError({
     code: "INVALID_ARGUMENTS" /* InvalidArguments */,
-    message: "\u8BE5\u547D\u4EE4\u9700\u8981\u660E\u786E\u7684 change",
+    message: "No unambiguous OpenSpec change id was found.",
     details: { openChangeIds: inspection.changes },
-    suggestedCommand: "\u6DFB\u52A0 --change <change-id>"
+    suggestedCommand: "Pass --change <change-id>."
   });
 }
 async function assertVerified(ctx) {
@@ -1788,7 +2212,7 @@ async function assertVerified(ctx) {
   if (!changeId) {
     throw new FetError({
       code: "INVALID_ARGUMENTS" /* InvalidArguments */,
-      message: "\u672A\u6307\u5B9A change\uFF0C\u65E0\u6CD5\u68C0\u67E5 verify \u72B6\u6001",
+      message: "A change id is required before this command can check FET verification.",
       suggestedCommand: "fet verify --done --change <change-id>"
     });
   }
@@ -1797,7 +2221,7 @@ async function assertVerified(ctx) {
   if (!inspection.changes.includes(changeId)) {
     throw new FetError({
       code: "INVALID_ARGUMENTS" /* InvalidArguments */,
-      message: "\u6307\u5B9A\u7684 change \u4E0D\u5B58\u5728\u6216\u5DF2\u5F52\u6863",
+      message: "The selected change does not exist in openspec/changes.",
       details: { changeId, openChangeIds: inspection.changes },
       suggestedCommand: "fet doctor"
     });
@@ -1805,7 +2229,7 @@ async function assertVerified(ctx) {
   if (change?.manualVerify?.status !== "declared_done") {
     throw new FetError({
       code: "STATE_CORRUPTED" /* StateCorrupted */,
-      message: "\u5F53\u524D change \u5C1A\u672A\u901A\u8FC7 FET verify",
+      message: "This change has not been marked verified by FET.",
       details: { changeId },
       suggestedCommand: `fet verify --change ${changeId}`
     });
@@ -1814,8 +2238,8 @@ async function assertVerified(ctx) {
 
 // src/commands/verify.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir6, readFile as readFile11, stat as stat5 } from "fs/promises";
-import { join as join14 } from "path";
+import { mkdir as mkdir7, readFile as readFile12, stat as stat5 } from "fs/promises";
+import { join as join15 } from "path";
 async function verifyCommand(ctx, options) {
   if (options.auto) {
     const scan = await ctx.scanner.scan(ctx.projectRoot, {});
@@ -1882,9 +2306,9 @@ async function verifyCommand(ctx, options) {
 async function writeInstructions(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join14(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join14(dir, "verify-instructions.md");
-  await mkdir6(dir, { recursive: true });
+  const dir = join15(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  const instructionsPath = join15(dir, "verify-instructions.md");
+  await mkdir7(dir, { recursive: true });
   await atomicWrite(instructionsPath, renderVerifyInstructions(changeId, generatedAt));
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
   state.currentPhase = "verify";
@@ -1900,7 +2324,7 @@ async function writeInstructions(ctx, changeId) {
 async function markDone(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const declaredAt = (/* @__PURE__ */ new Date()).toISOString();
-  const instructionsPath = join14(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
+  const instructionsPath = join15(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
   const instructions = await readInstructions(instructionsPath, changeId);
   const instructionsGeneratedAt = readFrontMatterValue(instructions, "generatedAt") ?? declaredAt;
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
@@ -1936,7 +2360,7 @@ async function assertChangeExists(ctx, changeId) {
 async function readInstructions(path, changeId) {
   try {
     await stat5(path);
-    const content = await readFile11(path, "utf8");
+    const content = await readFile12(path, "utf8");
     const fileChangeId = readFrontMatterValue(content, "changeId");
     if (fileChangeId !== changeId) {
       throw new FetError({
@@ -2013,10 +2437,10 @@ function getModelPolicyMode(env = process.env) {
   if (value === "off" || env.FET_SKIP_MODEL_POLICY === "1") {
     return "off";
   }
-  if (value === "confirm") {
-    return "confirm";
+  if (value === "warn") {
+    return "warn";
   }
-  return "warn";
+  return "confirm";
 }
 function getCommandModelPolicyMismatch(command, env = process.env) {
   if (getModelPolicyMode(env) === "off") {
@@ -2060,23 +2484,23 @@ function formatModelPolicyMismatch(mismatch, language = "zh-CN") {
 function renderIdeModelPolicy(command, language = "zh-CN") {
   if (language === "en") {
     if (command === "apply") {
-      return "Model policy: this command is recommended to run with a high-capability/high-cost model such as GPT-5.5, GLM-5.1, GLM-5, Claude Opus, or Claude Sonnet. Treat this as advisory: do not interrupt the workflow solely to ask about switching models. Run the FET command unless the user explicitly asks to pause for a model switch, and report any FET model warning in the summary.";
+      return "Model policy: this command is recommended to run with a high-capability/high-cost model such as GPT-5.5, GLM-5.1, GLM-5, Claude Opus, or Claude Sonnet. If the current IDE model is lower-cost, tell the user and ask whether to stop for a model switch or continue anyway. Continue only after the user chooses.";
     }
-    return "Model policy: this command is recommended to run with a low-cost model. If the current IDE model is GPT-5.5, GLM-5.1, GLM-5, Claude Opus, Claude Sonnet, or another high-cost model, treat it as an advisory warning: do not interrupt the workflow solely to ask about switching models. Run the FET command unless the user explicitly asks to pause for a model switch, and report any FET model warning in the summary.";
+    return "Model policy: this command is recommended to run with a low-cost model. If the current IDE model is GPT-5.5, GLM-5.1, GLM-5, Claude Opus, Claude Sonnet, or another high-cost model, tell the user and ask whether to stop for a model switch or continue anyway. Continue only after the user chooses.";
   }
   if (command === "apply") {
-    return "\u6A21\u578B\u7B56\u7565\uFF1A\u8BE5\u547D\u4EE4\u5EFA\u8BAE\u4F7F\u7528\u9AD8\u80FD\u529B/\u9AD8\u6210\u672C\u6A21\u578B\u8FD0\u884C\uFF0C\u4F8B\u5982 GPT-5.5\u3001GLM-5.1\u3001GLM-5\u3001Claude Opus \u6216 Claude Sonnet\u3002\u6B64\u63D0\u793A\u4EC5\u4F5C\u4E3A\u5EFA\u8BAE\uFF0C\u4E0D\u8981\u4EC5\u56E0\u6A21\u578B\u7B56\u7565\u800C\u6253\u65AD\u6D41\u7A0B\u8BE2\u95EE\u662F\u5426\u5207\u6362\u6A21\u578B\uFF1B\u9664\u975E\u7528\u6237\u660E\u786E\u8981\u6C42\u5148\u5207\u6362\u6A21\u578B\uFF0C\u5426\u5219\u7EE7\u7EED\u8FD0\u884C FET \u547D\u4EE4\uFF0C\u5E76\u5728\u603B\u7ED3\u4E2D\u8BF4\u660E FET \u8F93\u51FA\u7684\u6A21\u578B\u63D0\u9192\u3002";
+    return "\u6A21\u578B\u7B56\u7565\uFF1A\u8BE5\u547D\u4EE4\u5EFA\u8BAE\u4F7F\u7528\u9AD8\u80FD\u529B/\u9AD8\u6210\u672C\u6A21\u578B\u8FD0\u884C\uFF0C\u4F8B\u5982 GPT-5.5\u3001GLM-5.1\u3001GLM-5\u3001Claude Opus \u6216 Claude Sonnet\u3002\u82E5\u5F53\u524D IDE \u6A21\u578B\u80FD\u529B\u8F83\u4F4E\uFF0C\u8BF7\u544A\u77E5\u7528\u6237\u5E76\u8BE2\u95EE\u662F\u505C\u6B62\u540E\u5207\u6362\u6A21\u578B\uFF0C\u8FD8\u662F\u7EE7\u7EED\u6267\u884C\u5F53\u524D\u547D\u4EE4\uFF1B\u53EA\u6709\u5728\u7528\u6237\u9009\u62E9\u540E\u624D\u7EE7\u7EED\u3002";
   }
-  return "\u6A21\u578B\u7B56\u7565\uFF1A\u8BE5\u547D\u4EE4\u5EFA\u8BAE\u4F7F\u7528\u4F4E\u6210\u672C\u6A21\u578B\u8FD0\u884C\u3002\u82E5\u5F53\u524D IDE \u6A21\u578B\u662F GPT-5.5\u3001GLM-5.1\u3001GLM-5\u3001Claude Opus\u3001Claude Sonnet \u6216\u5176\u4ED6\u9AD8\u6210\u672C\u6A21\u578B\uFF0C\u6B64\u63D0\u793A\u4EC5\u4F5C\u4E3A\u5EFA\u8BAE\uFF1B\u4E0D\u8981\u4EC5\u56E0\u6A21\u578B\u7B56\u7565\u800C\u6253\u65AD\u6D41\u7A0B\u8BE2\u95EE\u662F\u5426\u5207\u6362\u6A21\u578B\u3002\u9664\u975E\u7528\u6237\u660E\u786E\u8981\u6C42\u5148\u5207\u6362\u6A21\u578B\uFF0C\u5426\u5219\u7EE7\u7EED\u8FD0\u884C FET \u547D\u4EE4\uFF0C\u5E76\u5728\u603B\u7ED3\u4E2D\u8BF4\u660E FET \u8F93\u51FA\u7684\u6A21\u578B\u63D0\u9192\u3002";
+  return "\u6A21\u578B\u7B56\u7565\uFF1A\u8BE5\u547D\u4EE4\u5EFA\u8BAE\u4F7F\u7528\u4F4E\u6210\u672C\u6A21\u578B\u8FD0\u884C\u3002\u82E5\u5F53\u524D IDE \u6A21\u578B\u662F GPT-5.5\u3001GLM-5.1\u3001GLM-5\u3001Claude Opus\u3001Claude Sonnet \u6216\u5176\u4ED6\u9AD8\u6210\u672C\u6A21\u578B\uFF0C\u8BF7\u544A\u77E5\u7528\u6237\u5E76\u8BE2\u95EE\u662F\u505C\u6B62\u540E\u5207\u6362\u6A21\u578B\uFF0C\u8FD8\u662F\u7EE7\u7EED\u6267\u884C\u5F53\u524D\u547D\u4EE4\uFF1B\u53EA\u6709\u5728\u7528\u6237\u9009\u62E9\u540E\u624D\u7EE7\u7EED\u3002";
 }
 
 // src/cli/context.ts
 import { resolve } from "path";
 
 // src/adapters/codex/index.ts
-import { mkdir as mkdir7, readFile as readFile12, stat as stat6 } from "fs/promises";
+import { mkdir as mkdir8, readFile as readFile13, stat as stat6 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname7, join as join15 } from "path";
+import { dirname as dirname8, join as join16 } from "path";
 
 // src/adapters/commands.ts
 var FET_WORKFLOW_COMMANDS = [
@@ -2107,18 +2531,9 @@ function renderFetAdapterUsage(command, args = "[...args]") {
 
 // src/adapters/codex/templates.ts
 function codexGuideFile(language = DEFAULT_LANGUAGE) {
-  return {
-    path: ".codex/fet/context.md",
-    content: `<!-- FET:MANAGED
-schemaVersion: 1
-fetVersion: ${FET_VERSION}
-generator: codex-adapter
-adapterVersion: 1
-FET:END -->
+  const body = language === "en" ? `# FET For Codex
 
-# FET For Codex
-
-## \u8BED\u8A00
+## Language
 
 ${languageInstruction(language)}
 
@@ -2134,7 +2549,35 @@ If GitNexus code graph context is available in the IDE or MCP tools, prefer it b
 Use the terminal command \`fet <command>\` as the source of truth for workflow transitions. These files are Codex-readable guidance; they do not register native slash commands.
 
 Command guides live in .codex/fet/commands/.
-`
+` : `# Codex \u7684 FET \u4F7F\u7528\u6307\u5357
+
+## \u8BED\u8A00
+
+${languageInstruction(language)}
+
+\u5728 Codex \u4E2D\u6267\u884C FET \u6216 OpenSpec \u5DE5\u4F5C\u524D\uFF0C\u5148\u9605\u8BFB\uFF1A
+
+- AGENTS.md
+- openspec/config.yaml
+- .codex/fet/karpathy-guidelines.md
+- \u5982\u679C\u5DF2\u9009\u62E9 change\uFF0C\u9605\u8BFB openspec/changes/<change-id>/ \u4E0B\u7684\u5F53\u524D\u4EA7\u7269
+
+\u5982\u679C IDE \u6216 MCP \u5DE5\u5177\u4E2D\u53EF\u7528 GitNexus \u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587\uFF0C\u5148\u7528\u5B83\u7F29\u5C0F\u4ED3\u5E93\u626B\u63CF\u8303\u56F4\uFF1B\u7528\u56FE\u8BC6\u522B\u76F8\u5173\u6A21\u5757\u3001\u4F9D\u8D56\u548C\u63D2\u5165\u70B9\uFF0C\u518D\u53EA\u8BFB\u53D6\u9700\u8981\u786E\u8BA4\u884C\u4E3A\u7684\u5177\u4F53\u6E90\u7801\u6587\u4EF6\u3002GitNexus \u4E0D\u53EF\u7528\u65F6\uFF0C\u6309\u666E\u901A FET/OpenSpec \u5DE5\u4F5C\u6D41\u7EE7\u7EED\u3002
+
+\u5DE5\u4F5C\u6D41\u6D41\u8F6C\u4EE5\u7EC8\u7AEF\u547D\u4EE4 \`fet <command>\` \u4E3A\u51C6\u3002\u8FD9\u4E9B\u6587\u4EF6\u662F\u7ED9 Codex \u9605\u8BFB\u7684\u6307\u5BFC\uFF0C\u4E0D\u6CE8\u518C\u539F\u751F slash command\u3002
+
+\u547D\u4EE4\u6307\u5357\u4F4D\u4E8E .codex/fet/commands/\u3002
+`;
+  return {
+    path: ".codex/fet/context.md",
+    content: `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+FET:END -->
+
+${body}`
   };
 }
 function codexCommandFiles(language = DEFAULT_LANGUAGE) {
@@ -2162,7 +2605,7 @@ generator: codex-adapter
 adapterVersion: 1
 FET:END -->
 
-# Andrej Karpathy Inspired Coding Guidelines
+# ${language === "en" ? "Andrej Karpathy Inspired Coding Guidelines" : "\u53D7 Andrej Karpathy \u542F\u53D1\u7684\u7F16\u7801\u6307\u5357"}
 
 ${renderKarpathyGuidelinesBody(language)}
 `
@@ -2216,6 +2659,34 @@ After the command completes, report the important next steps from the FET output
 function renderCommandZh(command) {
   const usage = renderFetAdapterUsage(command, command === "fill-context" ? "" : command === "passthrough" ? "<openspec-command> [...args]" : "");
   const title = commandTitleZh(command);
+  if (command === "graph-setup") {
+    return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+command: ${usage}
+FET:END -->
+
+# ${usage}
+
+${renderIdeModelPolicy(command, "zh-CN")}
+
+${languageInstruction("zh-CN")}
+
+\u7528\u4E8E\u6307\u5BFC\u5F53\u524D IDE LLM \u5728\u7528\u6237\u786E\u8BA4\u4E0B\u5B89\u88C5 GitNexus\u3002
+
+\u5148\u8FD0\u884C\uFF1A
+
+\`\`\`sh
+${usage}
+\`\`\`
+
+\u7136\u540E\u9605\u8BFB .fet/graph-setup.md\uFF0C\u5E76\u4EE5\u5B83\u4F5C\u4E3A\u5B89\u88C5\u4EFB\u52A1\u4E66\u3002\u53EA\u8BFB\u68C0\u6D4B\u547D\u4EE4\u53EF\u4EE5\u76F4\u63A5\u8FD0\u884C\uFF1B\u4EFB\u4F55\u4F1A\u4E0B\u8F7D\u8F6F\u4EF6\u3001\u5168\u5C40\u5B89\u88C5\u3001\u4FEE\u6539 PATH\u3001\u5199\u5165\u7528\u6237\u7EA7\u6587\u4EF6\u6216\u4FEE\u6539 IDE/MCP \u914D\u7F6E\u7684\u547D\u4EE4\uFF0C\u6267\u884C\u524D\u90FD\u8981\u5C55\u793A\u5B8C\u6574\u547D\u4EE4\u5E76\u7B49\u5F85\u7528\u6237\u786E\u8BA4\u3002
+
+\u5B89\u88C5\u540E\u7528 \`gitnexus --version\` \u9A8C\u8BC1\u3002\u5408\u9002\u65F6\u7EE7\u7EED\u8FD0\u884C \`fet graph init\` \u548C \`fet graph handoff\`\u3002\u5982\u679C\u5B89\u88C5\u5931\u8D25\uFF0C\u62A5\u544A\u5931\u8D25\u547D\u4EE4\u3001stderr \u548C\u4E0B\u4E00\u6B65\u4EBA\u5DE5\u5904\u7406\u5EFA\u8BAE\u3002
+`;
+  }
   return `<!-- FET:MANAGED
 schemaVersion: 1
 fetVersion: ${FET_VERSION}
@@ -2279,6 +2750,34 @@ This preserves the FET entry point while allowing access to unmanaged or newly a
 }
 function renderGraphCommand(command, language) {
   const usage = renderFetAdapterUsage(command, "");
+  if (command === "graph-setup") {
+    return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+command: ${usage}
+FET:END -->
+
+# ${usage}
+
+${renderIdeModelPolicy(command, language)}
+
+${languageInstruction(language)}
+
+Use this command to guide IDE-assisted GitNexus installation with user approval.
+
+Run:
+
+\`\`\`sh
+${usage}
+\`\`\`
+
+Then read .fet/graph-setup.md and follow it as the source of truth. You may run read-only detection commands directly. Before downloading software, installing globally, changing PATH, writing user-level files, or modifying IDE/MCP configuration, show the exact command and wait for user approval.
+
+After installation, verify \`gitnexus --version\`. If appropriate, continue with \`fet graph init\` and \`fet graph handoff\`. If installation fails, report the failing command, stderr, and next manual step.
+`;
+  }
   const subcommand = command.slice("graph-".length);
   return `<!-- FET:MANAGED
 schemaVersion: 1
@@ -2351,6 +2850,9 @@ function renderSlashPrompt(command, language) {
   if (command === "passthrough") {
     return renderPassthroughSlashPrompt(language);
   }
+  if (command === "graph-setup") {
+    return renderGraphSetupSlashPrompt(language);
+  }
   const usage = renderFetAdapterUsage(command);
   const isGraph = command.startsWith("graph-");
   const shellCommand = isGraph ? `${renderFetAdapterUsage(command, "")} $ARGUMENTS` : `fet ${command} $ARGUMENTS`;
@@ -2385,6 +2887,9 @@ After it completes, summarize the important FET output and next steps.
 `;
 }
 function renderSlashPromptZh(command) {
+  if (command === "graph-setup") {
+    return renderGraphSetupSlashPrompt("zh-CN");
+  }
   const usage = renderFetAdapterUsage(command, command === "fill-context" ? "" : command === "passthrough" ? "<openspec-command> [...args]" : "[...args]");
   const argumentHint = command === "passthrough" ? "openspec-command [...args]" : void 0;
   const argumentHintLine = argumentHint ? `argument-hint: ${argumentHint}
@@ -2778,6 +3283,62 @@ Guardrails:
     language
   );
 }
+function renderGraphSetupSlashPrompt(language) {
+  if (language === "en") {
+    return renderManagedSlashPrompt(
+      "fet graph setup",
+      "Guide IDE-assisted GitNexus installation with user approval",
+      `Guide optional GitNexus installation for this project.
+
+Steps:
+
+1. Run:
+   \`\`\`sh
+   fet graph setup
+   \`\`\`
+2. Read .fet/graph-setup.md and follow it as the source of truth.
+3. Run read-only detection commands as needed, such as checking the shell, PATH, package managers, and \`gitnexus --version\`.
+4. If GitNexus is missing, use the configured \`FET_GITNEXUS_INSTALL_COMMAND\` when present; otherwise find the official GitNexus installation instructions or ask the user for the preferred method.
+5. Before any command that downloads software, installs globally, changes PATH, writes user-level files, or modifies IDE/MCP settings, show the exact command and wait for user approval.
+6. Verify installation with \`gitnexus --version\`.
+7. If the user wants IDE/MCP integration, explain \`gitnexus setup\` and run it only after approval.
+8. Run \`fet graph init\` and then \`fet graph handoff\` when GitNexus is available.
+
+Guardrails:
+- GitNexus is optional; do not block FET/OpenSpec workflows if installation fails.
+- Do not modify application code during setup.
+- Report the failing command, stderr, and next manual step if blocked.`,
+      void 0,
+      language
+    );
+  }
+  return renderManagedSlashPrompt(
+    "fet graph setup",
+    "\u6307\u5BFC IDE LLM \u5728\u7528\u6237\u786E\u8BA4\u4E0B\u5B89\u88C5 GitNexus",
+    `\u4E3A\u5F53\u524D\u9879\u76EE\u5F15\u5BFC\u53EF\u9009\u7684 GitNexus \u5B89\u88C5\u3002
+
+\u6B65\u9AA4\uFF1A
+
+1. \u8FD0\u884C\uFF1A
+   \`\`\`sh
+   fet graph setup
+   \`\`\`
+2. \u9605\u8BFB .fet/graph-setup.md\uFF0C\u5E76\u4EE5\u5B83\u4F5C\u4E3A\u5B89\u88C5\u4EFB\u52A1\u4E66\u3002
+3. \u6309\u9700\u8FD0\u884C\u53EA\u8BFB\u68C0\u6D4B\u547D\u4EE4\uFF0C\u4F8B\u5982\u68C0\u67E5 shell\u3001PATH\u3001\u5305\u7BA1\u7406\u5668\u548C \`gitnexus --version\`\u3002
+4. \u5982\u679C GitNexus \u7F3A\u5931\uFF0C\u4F18\u5148\u4F7F\u7528\u5DF2\u914D\u7F6E\u7684 \`FET_GITNEXUS_INSTALL_COMMAND\`\uFF1B\u6CA1\u6709\u914D\u7F6E\u65F6\uFF0C\u67E5\u627E GitNexus \u5B98\u65B9\u5B89\u88C5\u8BF4\u660E\uFF0C\u6216\u8BE2\u95EE\u7528\u6237\u5E0C\u671B\u4F7F\u7528\u7684\u5B89\u88C5\u65B9\u5F0F\u3002
+5. \u4EFB\u4F55\u4F1A\u4E0B\u8F7D\u8F6F\u4EF6\u3001\u5168\u5C40\u5B89\u88C5\u3001\u4FEE\u6539 PATH\u3001\u5199\u5165\u7528\u6237\u7EA7\u6587\u4EF6\u6216\u4FEE\u6539 IDE/MCP \u8BBE\u7F6E\u7684\u547D\u4EE4\uFF0C\u6267\u884C\u524D\u90FD\u8981\u5C55\u793A\u5B8C\u6574\u547D\u4EE4\u5E76\u7B49\u5F85\u7528\u6237\u786E\u8BA4\u3002
+6. \u7528 \`gitnexus --version\` \u9A8C\u8BC1\u5B89\u88C5\u3002
+7. \u5982\u679C\u7528\u6237\u9700\u8981 IDE/MCP \u96C6\u6210\uFF0C\u5148\u8BF4\u660E \`gitnexus setup\`\uFF0C\u83B7\u5F97\u786E\u8BA4\u540E\u518D\u8FD0\u884C\u3002
+8. GitNexus \u53EF\u7528\u540E\u8FD0\u884C \`fet graph init\`\uFF0C\u518D\u8FD0\u884C \`fet graph handoff\`\u3002
+
+\u7EA6\u675F\uFF1A
+- GitNexus \u662F\u53EF\u9009\u80FD\u529B\uFF1B\u5B89\u88C5\u5931\u8D25\u65F6\u4E0D\u8981\u963B\u585E FET/OpenSpec \u4E3B\u6D41\u7A0B\u3002
+- \u5B89\u88C5\u8FC7\u7A0B\u4E2D\u4E0D\u8981\u4FEE\u6539\u4E1A\u52A1\u4EE3\u7801\u3002
+- \u5982\u679C\u53D7\u963B\uFF0C\u62A5\u544A\u5931\u8D25\u547D\u4EE4\u3001stderr \u548C\u4E0B\u4E00\u6B65\u4EBA\u5DE5\u5904\u7406\u5EFA\u8BAE\u3002`,
+    void 0,
+    language
+  );
+}
 function renderExploreSlashPrompt(language) {
   return renderManagedSlashPrompt(
     "fet explore [...args]",
@@ -2897,6 +3458,7 @@ function renderManagedSlashPrompt(command, description, body, argumentHint, lang
   const policyCommand = command.split(/\s+/)[1] ?? command;
   const argumentHintLine = argumentHint ? `argument-hint: ${argumentHint}
 ` : "";
+  const graphContextInstruction = language === "en" ? "If GitNexus graph context is available, consult it before broad source scans and use it to narrow the files you read. If it is unavailable, continue normally." : "\u5982\u679C GitNexus \u4EE3\u7801\u56FE\u4E0A\u4E0B\u6587\u53EF\u7528\uFF0C\u5148\u7528\u5B83\u7F29\u5C0F\u6E90\u7801\u626B\u63CF\u8303\u56F4\uFF1B\u4E0D\u53EF\u7528\u65F6\u6309\u666E\u901A\u6D41\u7A0B\u7EE7\u7EED\u3002";
   return `<!-- FET:MANAGED
 schemaVersion: 1
 fetVersion: ${FET_VERSION}
@@ -2913,7 +3475,7 @@ ${renderIdeModelPolicy(policyCommand, language)}
 
 ${languageInstruction(language)}
 
-If GitNexus graph context is available, consult it before broad source scans and use it to narrow the files you read. If it is unavailable, continue normally.
+${graphContextInstruction}
 
 ${body}
 `;
@@ -2925,7 +3487,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists3(join15(projectRoot, ".codex")) || await exists3(join15(projectRoot, "AGENTS.md")),
+      detected: await exists3(join16(projectRoot, ".codex")) || await exists3(join16(projectRoot, "AGENTS.md")),
       reason: "Codex adapter is available for projects that use AGENTS.md"
     };
   }
@@ -2964,7 +3526,7 @@ var CodexAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir7(dirname7(target), { recursive: true });
+      await mkdir8(dirname8(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(displayPath);
     }
@@ -2991,9 +3553,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join15(resolveCodexHome(), file.path);
+    return join16(resolveCodexHome(), file.path);
   }
-  return join15(projectRoot, file.path);
+  return join16(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -3002,11 +3564,11 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join15(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join16(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
-    return await readFile12(path, "utf8");
+    return await readFile13(path, "utf8");
   } catch {
     return null;
   }
@@ -3021,8 +3583,8 @@ async function exists3(path) {
 }
 
 // src/adapters/cursor/index.ts
-import { mkdir as mkdir8, readFile as readFile13, stat as stat7 } from "fs/promises";
-import { dirname as dirname8, join as join16 } from "path";
+import { mkdir as mkdir9, readFile as readFile14, stat as stat7 } from "fs/promises";
+import { dirname as dirname9, join as join17 } from "path";
 
 // src/adapters/cursor/templates.ts
 function cursorSkillFiles(language = DEFAULT_LANGUAGE) {
@@ -3088,6 +3650,36 @@ ${languageInstruction(language)}
 - openspec/config.yaml
 
 \u68C0\u67E5 README\u3001package scripts\u3001\u8DEF\u7531\u3001\u6D4B\u8BD5\u3001\u6E90\u7801\u7ED3\u6784\u548C\u73B0\u6709\u7EA6\u5B9A\u540E\uFF0C\u628A AGENTS.md \u4E2D\u6BCF\u4E2A \`[NEEDS LLM INPUT]\` \u6216 \`[NEED LLM INPUT]\` \u5360\u4F4D\u7B26\u66FF\u6362\u4E3A\u5177\u4F53\u3001\u7B80\u6D01\u3001\u9879\u76EE\u76F8\u5173\u7684\u5185\u5BB9\u3002\u4FDD\u7559 FET \u6258\u7BA1\u6807\u8BB0\uFF0C\u4E0D\u8981\u4FEE\u6539\u4E1A\u52A1\u4EE3\u7801\u3002
+`;
+  }
+  if (command === "graph-setup") {
+    return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: cursor-adapter
+adapterVersion: 1
+command: fet graph setup
+FET:END -->
+
+---
+name: fet-graph-setup
+description: ${language === "en" ? "Guide IDE-assisted GitNexus installation with user approval" : "\u6307\u5BFC IDE LLM \u5728\u7528\u6237\u786E\u8BA4\u4E0B\u5B89\u88C5 GitNexus"}
+disable-model-invocation: false
+---
+
+${renderIdeModelPolicy(command, language)}
+
+${languageInstruction(language)}
+
+${language === "en" ? `Run \`fet graph setup\`, then read .fet/graph-setup.md and follow it as an installation playbook.
+
+You may run read-only detection commands without extra confirmation. Before any command that downloads software, installs globally, changes PATH, writes user-level config, or modifies IDE/MCP settings, show the exact command and wait for user approval.
+
+After installation, verify with \`gitnexus --version\`, then run \`fet graph init\` and \`fet graph handoff\` when appropriate. If installation fails, summarize the failing command and next manual step.` : `\u5148\u8FD0\u884C \`fet graph setup\`\uFF0C\u518D\u9605\u8BFB .fet/graph-setup.md\uFF0C\u5E76\u628A\u5B83\u4F5C\u4E3A\u5B89\u88C5\u4EFB\u52A1\u4E66\u6267\u884C\u3002
+
+\u53EA\u8BFB\u68C0\u6D4B\u547D\u4EE4\u53EF\u4EE5\u76F4\u63A5\u8FD0\u884C\u3002\u4EFB\u4F55\u4F1A\u4E0B\u8F7D\u8F6F\u4EF6\u3001\u5168\u5C40\u5B89\u88C5\u3001\u4FEE\u6539 PATH\u3001\u5199\u5165\u7528\u6237\u7EA7\u914D\u7F6E\u6216\u4FEE\u6539 IDE/MCP \u8BBE\u7F6E\u7684\u547D\u4EE4\uFF0C\u6267\u884C\u524D\u90FD\u8981\u5C55\u793A\u5B8C\u6574\u547D\u4EE4\u5E76\u7B49\u5F85\u7528\u6237\u786E\u8BA4\u3002
+
+\u5B89\u88C5\u540E\u7528 \`gitnexus --version\` \u9A8C\u8BC1\uFF1B\u5408\u9002\u65F6\u7EE7\u7EED\u8FD0\u884C \`fet graph init\` \u548C \`fet graph handoff\`\u3002\u5982\u679C\u5B89\u88C5\u5931\u8D25\uFF0C\u6C47\u603B\u5931\u8D25\u547D\u4EE4\u548C\u4E0B\u4E00\u6B65\u4EBA\u5DE5\u5904\u7406\u5EFA\u8BAE\u3002`}
 `;
   }
   return `<!-- FET:MANAGED
@@ -3126,7 +3718,7 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists4(join16(projectRoot, ".cursor")),
+      detected: await exists4(join17(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
@@ -3143,7 +3735,7 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join16(projectRoot, file.path);
+      const target = join17(projectRoot, file.path);
       const existing = await readExisting2(target);
       if (existing && !existing.includes("FET:MANAGED") && !force) {
         throw new FetError({
@@ -3156,7 +3748,7 @@ var CursorAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir8(dirname8(target), { recursive: true });
+      await mkdir9(dirname9(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(file.path);
     }
@@ -3166,7 +3758,7 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join16(projectRoot, file.path);
+      const target = join17(projectRoot, file.path);
       const content = await readExisting2(target);
       const managed = Boolean(content?.includes("FET:MANAGED"));
       const versionMatches = Boolean(content?.includes(`adapterVersion: ${this.adapterVersion}`));
@@ -3182,7 +3774,7 @@ var CursorAdapter = class {
 };
 async function readExisting2(path) {
   try {
-    return await readFile13(path, "utf8");
+    return await readFile14(path, "utf8");
   } catch {
     return null;
   }
@@ -3201,13 +3793,13 @@ import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
 
 // src/openspec/inspector.ts
-import { readdir, stat as stat8 } from "fs/promises";
-import { join as join17 } from "path";
+import { readdir as readdir2, stat as stat8 } from "fs/promises";
+import { join as join18 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join17(projectRoot, "openspec");
-  const changesPath = join17(openspecPath, "changes");
-  const legacyArchivePath = join17(openspecPath, "archive");
-  const changesArchivePath = join17(changesPath, "archive");
+  const openspecPath = join18(projectRoot, "openspec");
+  const changesPath = join18(openspecPath, "changes");
+  const legacyArchivePath = join18(openspecPath, "archive");
+  const changesArchivePath = join18(changesPath, "archive");
   return {
     exists: await exists5(openspecPath),
     changes: await listDirectories(changesPath, { exclude: ["archive"] }),
@@ -3215,13 +3807,13 @@ async function inspectOpenSpecProject(projectRoot) {
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join17(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join17(changePath, "tasks.md");
-  const specsPath = join17(changePath, "specs");
+  const changePath = join18(projectRoot, "openspec", "changes", changeId);
+  const tasksPath = join18(changePath, "tasks.md");
+  const specsPath = join18(changePath, "specs");
   return {
     changeId,
     exists: await exists5(changePath),
-    hasProposal: await exists5(join17(changePath, "proposal.md")),
+    hasProposal: await exists5(join18(changePath, "proposal.md")),
     hasTasks: await exists5(tasksPath),
     hasSpecs: await exists5(specsPath),
     tasksPath,
@@ -3230,7 +3822,7 @@ async function inspectOpenSpecChange(projectRoot, changeId) {
 }
 async function listDirectories(path, options = {}) {
   try {
-    const entries = await readdir(path, { withFileTypes: true });
+    const entries = await readdir2(path, { withFileTypes: true });
     const excluded = new Set(options.exclude ?? []);
     return entries.filter((entry) => entry.isDirectory() && !excluded.has(entry.name)).map((entry) => entry.name);
   } catch {
@@ -3398,12 +3990,12 @@ function parseCommands(help) {
 }
 
 // src/scanner/package.ts
-import { readFile as readFile14, stat as stat9 } from "fs/promises";
-import { join as join18 } from "path";
+import { readFile as readFile15, stat as stat9 } from "fs/promises";
+import { join as join19 } from "path";
 import { parse as parse2 } from "yaml";
 async function readPackageJson(projectRoot) {
   try {
-    return JSON.parse(await readFile14(join18(projectRoot, "package.json"), "utf8"));
+    return JSON.parse(await readFile15(join19(projectRoot, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -3469,7 +4061,7 @@ function detectFramework(pkg) {
 }
 async function detectLanguage(projectRoot, pkg) {
   const deps = { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
-  if (deps.typescript || await exists6(join18(projectRoot, "tsconfig.json"))) {
+  if (deps.typescript || await exists6(join19(projectRoot, "tsconfig.json"))) {
     return "typescript";
   }
   return "javascript";
@@ -3484,7 +4076,7 @@ async function detectWorkspaces(projectRoot, pkg) {
     return packageWorkspaces;
   }
   try {
-    const workspace = parse2(await readFile14(join18(projectRoot, "pnpm-workspace.yaml"), "utf8"));
+    const workspace = parse2(await readFile15(join19(projectRoot, "pnpm-workspace.yaml"), "utf8"));
     return (workspace?.packages ?? []).map((path) => ({
       name: path,
       path,
@@ -3504,7 +4096,7 @@ async function detectLockManagers(projectRoot) {
   ];
   const found = [];
   for (const [file, manager] of lockFiles) {
-    if (await exists6(join18(projectRoot, file))) {
+    if (await exists6(join19(projectRoot, file))) {
       found.push(manager);
     }
   }
@@ -3529,13 +4121,13 @@ async function exists6(path) {
 }
 
 // src/scanner/routes.ts
-import { readdir as readdir2, stat as stat10 } from "fs/promises";
-import { join as join19, relative, sep } from "path";
+import { readdir as readdir3, stat as stat10 } from "fs/promises";
+import { join as join20, relative, sep } from "path";
 async function scanRoutes(projectRoot) {
   const candidates = ["src/routes", "src/pages", "app", "pages"];
   const routes = [];
   for (const candidate of candidates) {
-    const root = join19(projectRoot, candidate);
+    const root = join20(projectRoot, candidate);
     if (!await exists7(root)) {
       continue;
     }
@@ -3560,10 +4152,10 @@ function inferRoutePath(relativePath) {
   return `/${withoutIndex}`.replace(/\/+/g, "/");
 }
 async function listFiles(root) {
-  const entries = await readdir2(root, { withFileTypes: true });
+  const entries = await readdir3(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join19(root, entry.name);
+    const path = join20(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {
@@ -3805,7 +4397,7 @@ function renderModelPolicyActionHint(policyMode, language) {
   if (policyMode === "confirm") {
     return language === "en" ? "Choose whether to continue this command or stop and switch models." : "\u8BF7\u9009\u62E9\u7EE7\u7EED\u6267\u884C\u672C\u547D\u4EE4\uFF0C\u6216\u505C\u6B62\u540E\u624B\u52A8\u5207\u6362\u6A21\u578B\u3002";
   }
-  return language === "en" ? "This is advisory; the command will continue. Set FET_MODEL_POLICY=confirm if you want an explicit stop/continue prompt." : "\u8BE5\u63D0\u9192\u4EC5\u4F5C\u4E3A\u5EFA\u8BAE\uFF0C\u547D\u4EE4\u4F1A\u7EE7\u7EED\u6267\u884C\u3002\u5982\u9700\u663E\u5F0F\u9009\u62E9\u505C\u6B62\u6216\u7EE7\u7EED\uFF0C\u53EF\u8BBE\u7F6E FET_MODEL_POLICY=confirm\u3002";
+  return language === "en" ? "This is advisory because FET_MODEL_POLICY=warn; the command will continue." : "\u5F53\u524D\u8BBE\u7F6E FET_MODEL_POLICY=warn\uFF0C\u8BE5\u63D0\u9192\u4EC5\u4F5C\u4E3A\u5EFA\u8BAE\uFF0C\u547D\u4EE4\u4F1A\u7EE7\u7EED\u6267\u884C\u3002";
 }
 async function warnIfContextPlaceholdersRemain(ctx) {
   if (["init", "update-context", "fill-context", "doctor"].includes(ctx.command)) {