@nick848/fet 1.0.3 → 1.0.5

package/dist/cli/index.js

@@ -2,14 +2,15 @@
 import {
   FetError,
   toFetError
-} from "../chunk-FZOVNHE7.js";
+} from "../chunk-V4ZRBF5L.js";
 
 // src/cli/index.ts
+import { createInterface } from "readline/promises";
 import { Command } from "commander";
 
 // src/commands/init.ts
-import { readFile as readFile5, stat as stat2 } from "fs/promises";
-import { join as join6 } from "path";
+import { readFile as readFile6, stat as stat3 } from "fs/promises";
+import { join as join8 } from "path";
 
 // src/fs/atomic-write.ts
 import { dirname } from "path";
@@ -115,16 +116,130 @@ async function writeInitJournal(projectRoot, journal) {
   );
 }
 
+// src/gitnexus.ts
+import { execFile } from "child_process";
+import { stat as stat2 } from "fs/promises";
+import { join as join4 } from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var DEFAULT_GRAPH_PATH = ".gitnexus";
+async function detectGitNexus(env = process.env) {
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const command = resolveGitNexusCommand(env);
+  try {
+    const { stdout, stderr } = await execFileAsync(command.file, [...command.args, "--version"], { shell: process.platform === "win32" });
+    return {
+      installed: true,
+      executablePath: command.label,
+      version: (stdout.trim() || stderr.trim() || "unknown").split(/\r?\n/)[0] ?? "unknown",
+      checkedAt
+    };
+  } catch (error) {
+    return {
+      installed: false,
+      executablePath: command.label,
+      version: null,
+      checkedAt,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function toGitNexusState(detection, previous) {
+  return {
+    provider: "gitnexus",
+    installed: detection.installed,
+    executablePath: detection.installed ? detection.executablePath : null,
+    version: detection.version,
+    checkedAt: detection.checkedAt,
+    recommendationShownAt: previous?.recommendationShownAt ?? null,
+    graphPath: previous?.graphPath ?? null,
+    graphExists: previous?.graphExists ?? false,
+    lastIndexedAt: previous?.lastIndexedAt ?? null,
+    lastRefreshAt: previous?.lastRefreshAt ?? null,
+    lastStatus: previous?.lastStatus ?? null,
+    setupHandoffPath: previous?.setupHandoffPath ?? null,
+    setupHandoffUpdatedAt: previous?.setupHandoffUpdatedAt ?? null,
+    handoffPath: previous?.handoffPath ?? null,
+    handoffUpdatedAt: previous?.handoffUpdatedAt ?? null
+  };
+}
+async function inspectGitNexusGraph(projectRoot, env = process.env) {
+  const relative2 = env.FET_GITNEXUS_GRAPH_PATH?.trim() || DEFAULT_GRAPH_PATH;
+  const graphPath = join4(projectRoot, relative2);
+  try {
+    const info = await stat2(graphPath);
+    return {
+      graphPath: relative2,
+      graphExists: true,
+      lastIndexedAt: info.mtime.toISOString()
+    };
+  } catch {
+    return {
+      graphPath: relative2,
+      graphExists: false,
+      lastIndexedAt: null
+    };
+  }
+}
+async function runGitNexus(args, options) {
+  const command = resolveGitNexusCommand(options.env ?? process.env);
+  const fullCommand = [command.file, ...command.args, ...args];
+  try {
+    const { stdout, stderr } = await execFileAsync(command.file, [...command.args, ...args], {
+      cwd: options.cwd,
+      shell: process.platform === "win32"
+    });
+    return {
+      exitCode: 0,
+      stdout,
+      stderr,
+      command: fullCommand
+    };
+  } catch (error) {
+    const maybe = error;
+    return {
+      exitCode: typeof maybe.code === "number" ? maybe.code : 1,
+      stdout: maybe.stdout ?? "",
+      stderr: maybe.stderr ?? (error instanceof Error ? error.message : String(error)),
+      command: fullCommand
+    };
+  }
+}
+function mergeGitNexusGraphInfo(state, graph2) {
+  return {
+    ...state,
+    graphPath: graph2.graphPath,
+    graphExists: graph2.graphExists,
+    lastIndexedAt: graph2.lastIndexedAt
+  };
+}
+function renderGitNexusRecommendation(state) {
+  if (state.installed) {
+    return `Optional GitNexus detected (${state.version ?? "unknown"}). You can generate a code graph after init; future OpenSpec artifacts should prefer the graph when it is available.`;
+  }
+  return "Optional GitNexus code graph support is not installed. Consider installing GitNexus later to speed up OpenSpec artifact generation and improve code insertion context.";
+}
+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 };
+}
+function splitCommand(value) {
+  const matches = value.match(/"[^"]+"|'[^']+'|\S+/g);
+  return (matches?.length ? matches : [value]).map((part) => part.replace(/^["']|["']$/g, ""));
+}
+
 // src/version.ts
 import { existsSync, readFileSync } from "fs";
-import { dirname as dirname4, join as join4, parse } from "path";
+import { dirname as dirname4, join as join5, parse } from "path";
 import { fileURLToPath } from "url";
 var FET_VERSION = readPackageVersion();
 function readPackageVersion() {
   let currentDir = dirname4(fileURLToPath(import.meta.url));
   const root = parse(currentDir).root;
   while (true) {
-    const packageJsonPath = join4(currentDir, "package.json");
+    const packageJsonPath = join5(currentDir, "package.json");
     if (existsSync(packageJsonPath)) {
       const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
       if (typeof packageJson.version === "string" && packageJson.version.length > 0) {
@@ -144,6 +259,7 @@ var AUTO_BEGIN = "<!-- FET:BEGIN AUTO -->";
 var AUTO_END = "<!-- FET:END AUTO -->";
 var USER_BEGIN = "<!-- FET:BEGIN USER -->";
 var USER_END = "<!-- FET:END USER -->";
+var LLM_PLACEHOLDER_PATTERN = /\[NEEDS? LLM INPUT\]/;
 function hasManagedAutoRegion(content) {
   return count(content, AUTO_BEGIN) === 1 && count(content, AUTO_END) === 1 && content.indexOf(AUTO_BEGIN) < content.indexOf(AUTO_END);
 }
@@ -163,11 +279,41 @@ function replaceManagedRegion(existing, generated) {
   }
   const before = existing.slice(0, start);
   const after = existing.slice(end + AUTO_END.length);
+  const existingAuto = extractAuto(existing);
   const generatedAuto = extractAuto(generated);
   return `${before}${AUTO_BEGIN}
-${generatedAuto}
+${mergeAutoRegion(existingAuto, generatedAuto)}
 ${AUTO_END}${after}`;
 }
+function mergeAutoRegion(existingAuto, generatedAuto) {
+  const generatedSections = splitMarkdownSections(generatedAuto);
+  const existingSections = new Map(splitMarkdownSections(existingAuto).map((section) => [section.heading, section]));
+  if (!generatedSections.length || !existingSections.size) {
+    return generatedAuto;
+  }
+  return generatedSections.map((section) => {
+    const existing = existingSections.get(section.heading);
+    if (existing && LLM_PLACEHOLDER_PATTERN.test(section.body) && !LLM_PLACEHOLDER_PATTERN.test(existing.body)) {
+      return existing.raw.trim();
+    }
+    return section.raw.trim();
+  }).join("\n\n");
+}
+function splitMarkdownSections(content) {
+  const matches = [...content.matchAll(/^## .+$/gm)];
+  if (!matches.length) {
+    return [];
+  }
+  return matches.map((match, index) => {
+    const start = match.index ?? 0;
+    const end = matches[index + 1]?.index ?? content.length;
+    const raw = content.slice(start, end).trim();
+    const newline = raw.indexOf("\n");
+    const heading = newline === -1 ? raw.trim() : raw.slice(0, newline).trim();
+    const body = newline === -1 ? "" : raw.slice(newline + 1).trim();
+    return { heading, body, raw };
+  });
+}
 function extractAuto(content) {
   const start = content.indexOf(AUTO_BEGIN);
   const end = content.indexOf(AUTO_END);
@@ -303,7 +449,8 @@ var RULES = [
   "openspec/.fet.lock",
   "openspec/.fet-init-journal.json",
   "openspec/changes/*/fet-state.json",
-  "openspec/changes/*/.fet/"
+  "openspec/changes/*/.fet/",
+  ".gitnexus/"
 ];
 function mergeGitignore(existing) {
   const block = `${BEGIN}
@@ -325,8 +472,8 @@ ${block}
 }
 
 // src/commands/update-context.ts
-import { readFile as readFile4 } from "fs/promises";
-import { join as join5 } from "path";
+import { readFile as readFile5 } from "fs/promises";
+import { join as join7 } from "path";
 
 // src/config/yaml.ts
 import { readFile as readFile3 } from "fs/promises";
@@ -345,23 +492,43 @@ async function mergeFetConfig(configPath, renderedFetYaml) {
   return doc.toString();
 }
 
+// src/context-placeholders.ts
+import { readFile as readFile4 } from "fs/promises";
+import { join as join6 } from "path";
+var AGENTS_LLM_PLACEHOLDER_PATTERN = /\[NEEDS? LLM INPUT\]/g;
+async function countAgentsLlmPlaceholders(projectRoot) {
+  try {
+    const content = await readFile4(join6(projectRoot, "AGENTS.md"), "utf8");
+    return [...content.matchAll(AGENTS_LLM_PLACEHOLDER_PATTERN)].length;
+  } catch {
+    return 0;
+  }
+}
+function renderAgentsPlaceholderWarning(count2) {
+  return `AGENTS.md still contains ${count2} LLM placeholder(s). Run fet fill-context first so your IDE AI can replace them. Continuing current command.`;
+}
+
 // src/commands/update-context.ts
 async function updateContextCommand(ctx) {
+  let contextResult = { warnings: [] };
   await withProjectLock(
     ctx.projectRoot,
     { command: "update-context", cwd: ctx.cwd, fetVersion: ctx.fetVersion },
-    async () => updateContextFiles(ctx)
+    async () => {
+      contextResult = await updateContextFiles(ctx);
+    }
   );
   ctx.output.result({
     ok: true,
     command: "update-context",
-    summary: "\u5DF2\u66F4\u65B0 AGENTS.md \u4E0E openspec/config.yaml \u7684 FET \u6258\u7BA1\u533A\u57DF\u3002"
+    summary: "\u5DF2\u66F4\u65B0 AGENTS.md \u4E0E openspec/config.yaml \u7684 FET \u6258\u7BA1\u533A\u57DF\u3002",
+    warnings: contextResult.warnings
   });
 }
 async function updateContextFiles(ctx) {
   const scan = await ctx.scanner.scan(ctx.projectRoot, {});
-  const agentsPath = join5(ctx.projectRoot, "AGENTS.md");
-  const configPath = join5(ctx.projectRoot, "openspec", "config.yaml");
+  const agentsPath = join7(ctx.projectRoot, "AGENTS.md");
+  const configPath = join7(ctx.projectRoot, "openspec", "config.yaml");
   const existingAgents = await readOptional(agentsPath);
   const warnings = [...scan.warnings];
   if (existingAgents && hasInvalidManagedAutoRegion(existingAgents)) {
@@ -388,6 +555,10 @@ async function updateContextFiles(ctx) {
   }
   await atomicWrite(agentsPath, replaceManagedRegion(existingAgents, renderAgentsMd(scan)));
   await atomicWrite(configPath, await mergeFetConfig(configPath, renderFetConfig(scan)));
+  const placeholderCount = await countAgentsLlmPlaceholders(ctx.projectRoot);
+  if (placeholderCount > 0) {
+    warnings.push(renderAgentsPlaceholderWarning(placeholderCount));
+  }
   const state = await ctx.stateStore.getOrCreateGlobal();
   state.context = {
     agentsMdUpdatedAt: scan.generatedAt,
@@ -399,7 +570,7 @@ async function updateContextFiles(ctx) {
 }
 async function readOptional(path) {
   try {
-    return await readFile4(path, "utf8");
+    return await readFile5(path, "utf8");
   } catch {
     return null;
   }
@@ -407,7 +578,8 @@ async function readOptional(path) {
 
 // src/commands/init.ts
 async function initCommand(ctx) {
-  const alreadyInitialized = await exists(join6(ctx.projectRoot, "openspec", "config.yaml"));
+  const alreadyInitialized = await exists(join8(ctx.projectRoot, "openspec", "config.yaml"));
+  let warnings = [];
   await withProjectLock(
     ctx.projectRoot,
     { command: "init", cwd: ctx.cwd, fetVersion: ctx.fetVersion },
@@ -423,9 +595,20 @@ async function initCommand(ctx) {
         }
       }
       const contextResult = await updateContextFiles(ctx);
+      warnings = contextResult.warnings;
       await ensureGitignore(ctx);
       const state = await ctx.stateStore.getOrCreateGlobal();
       state.openspec = identity;
+      state.graph ??= {};
+      const gitnexus = mergeGitNexusGraphInfo(
+        toGitNexusState(await detectGitNexus(), state.graph.gitnexus),
+        await inspectGitNexusGraph(ctx.projectRoot)
+      );
+      if (!gitnexus.installed && !gitnexus.recommendationShownAt) {
+        warnings.push(renderGitNexusRecommendation(gitnexus));
+        gitnexus.recommendationShownAt = (/* @__PURE__ */ new Date()).toISOString();
+      }
+      state.graph.gitnexus = gitnexus;
       for (const adapter of ctx.toolAdapters) {
         const plan = await adapter.planInstall(ctx.projectRoot);
         const result = await adapter.install(ctx.projectRoot, plan, ctx.yes);
@@ -439,33 +622,31 @@ async function initCommand(ctx) {
       journal.completedAt = (/* @__PURE__ */ new Date()).toISOString();
       await writeInitJournal(ctx.projectRoot, journal);
       await ctx.stateStore.writeGlobal(state);
-      for (const warning of contextResult.warnings) {
-        ctx.output.warn(warning);
-      }
     }
   );
   ctx.output.result({
     ok: true,
     command: "init",
     summary: "FET \u521D\u59CB\u5316\u5B8C\u6210\u3002",
+    warnings,
     nextSteps: ["\u4F7F\u7528 fet propose/new \u521B\u5EFA OpenSpec change", "\u4F7F\u7528 fet doctor \u68C0\u67E5\u9879\u76EE\u72B6\u6001"]
   });
 }
 async function ensureGitignore(ctx) {
-  const gitignorePath = join6(ctx.projectRoot, ".gitignore");
+  const gitignorePath = join8(ctx.projectRoot, ".gitignore");
   const existing = await readOptional2(gitignorePath);
   await atomicWrite(gitignorePath, mergeGitignore(existing));
 }
 async function readOptional2(path) {
   try {
-    return await readFile5(path, "utf8");
+    return await readFile6(path, "utf8");
   } catch {
     return null;
   }
 }
 async function exists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch {
     return false;
@@ -473,19 +654,20 @@ async function exists(path) {
 }
 
 // src/commands/doctor.ts
-import { readFile as readFile6, stat as stat3 } from "fs/promises";
-import { join as join7 } from "path";
+import { readFile as readFile7, stat as stat4 } from "fs/promises";
+import { join as join9 } from "path";
 async function doctorCommand(ctx, options = {}) {
   const checks = [];
   checks.push(await checkOpenSpec(ctx));
   checks.push(await checkState(ctx));
-  checks.push(await checkFile("agents", join7(ctx.projectRoot, "AGENTS.md"), "AGENTS.md \u7F3A\u5931", "fet update-context"));
-  checks.push(await checkFile("config", join7(ctx.projectRoot, "openspec", "config.yaml"), "openspec/config.yaml \u7F3A\u5931", "fet init"));
-  checks.push(await checkPlaceholders(join7(ctx.projectRoot, "AGENTS.md")));
+  checks.push(await checkFile("agents", join9(ctx.projectRoot, "AGENTS.md"), "AGENTS.md \u7F3A\u5931", "fet update-context"));
+  checks.push(await checkFile("config", join9(ctx.projectRoot, "openspec", "config.yaml"), "openspec/config.yaml \u7F3A\u5931", "fet init"));
+  checks.push(await checkPlaceholders(ctx.projectRoot));
+  checks.push(await checkGitNexus(ctx));
   for (const adapter of ctx.toolAdapters) {
     checks.push(...await adapter.doctor(ctx.projectRoot));
   }
-  const lockPath = join7(ctx.projectRoot, "openspec", ".fet.lock");
+  const lockPath = join9(ctx.projectRoot, "openspec", ".fet.lock");
   if (await exists2(lockPath)) {
     if (options.fixLock) {
       await clearLock(ctx.projectRoot);
@@ -503,6 +685,28 @@ async function doctorCommand(ctx, options = {}) {
     data: checks
   });
 }
+async function checkGitNexus(ctx) {
+  const global = await ctx.stateStore.readGlobal();
+  const state = mergeGitNexusGraphInfo(
+    toGitNexusState(await detectGitNexus(), global?.graph?.gitnexus),
+    await inspectGitNexusGraph(ctx.projectRoot)
+  );
+  if (global) {
+    global.graph ??= {};
+    global.graph.gitnexus = state;
+    await ctx.stateStore.writeGlobal(global);
+  }
+  return state.installed ? {
+    id: "gitnexus",
+    status: "pass",
+    message: `GitNexus detected: ${state.executablePath ?? "gitnexus"} (${state.version ?? "unknown"}), graph ${state.graphExists ? "found" : "not found"}`
+  } : {
+    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"
+  };
+}
 async function checkOpenSpec(ctx) {
   try {
     const identity = await ctx.openSpec.resolveExecutable();
@@ -522,10 +726,10 @@ async function checkState(ctx) {
 async function checkFile(id, path, missing, suggestedCommand) {
   return await exists2(path) ? { id, status: "pass", message: `${id} \u5B58\u5728` } : { id, status: "warn", message: missing, suggestedCommand };
 }
-async function checkPlaceholders(path) {
+async function checkPlaceholders(projectRoot) {
   try {
-    const content = await readFile6(path, "utf8");
-    const count2 = [...content.matchAll(/\[NEEDS? LLM INPUT\]/g)].length;
+    await readFile7(join9(projectRoot, "AGENTS.md"), "utf8");
+    const count2 = await countAgentsLlmPlaceholders(projectRoot);
     return count2 ? {
       id: "context-placeholders",
       status: "warn",
@@ -538,7 +742,7 @@ async function checkPlaceholders(path) {
 }
 async function exists2(path) {
   try {
-    await stat3(path);
+    await stat4(path);
     return true;
   } catch {
     return false;
@@ -546,15 +750,14 @@ async function exists2(path) {
 }
 
 // src/commands/fill-context.ts
-import { mkdir as mkdir3, readFile as readFile7 } from "fs/promises";
-import { dirname as dirname5, join as join8 } from "path";
-var placeholderPattern = /\[NEEDS? LLM INPUT\]/g;
+import { mkdir as mkdir3 } from "fs/promises";
+import { dirname as dirname5, join as join10 } from "path";
 async function fillContextCommand(ctx) {
   await withProjectLock(
     ctx.projectRoot,
     { command: "fill-context", cwd: ctx.cwd, fetVersion: ctx.fetVersion },
     async () => {
-      const handoffPath = join8(ctx.projectRoot, ".fet", "fill-context.md");
+      const handoffPath = join10(ctx.projectRoot, ".fet", "fill-context.md");
       await mkdir3(dirname5(handoffPath), { recursive: true });
       await atomicWrite(handoffPath, renderGenericHandoff());
       for (const adapter of ctx.toolAdapters) {
@@ -573,7 +776,7 @@ async function fillContextCommand(ctx) {
       }
     }
   );
-  const placeholders = await countPlaceholders(join8(ctx.projectRoot, "AGENTS.md"));
+  const placeholders = await countAgentsLlmPlaceholders(ctx.projectRoot);
   ctx.output.result({
     ok: true,
     command: "fill-context",
@@ -608,23 +811,265 @@ Use the IDE AI to complete FET-generated placeholders.
 6. Run \`fet doctor\` and confirm no AGENTS.md placeholder warning remains.
 `;
 }
-async function countPlaceholders(path) {
-  try {
-    const content = await readFile7(path, "utf8");
-    return [...content.matchAll(placeholderPattern)].length;
-  } catch {
-    return 0;
+
+// src/commands/graph.ts
+import { mkdir as mkdir4 } from "fs/promises";
+import { dirname as dirname6, join as join11 } from "path";
+async function graphCommand(ctx, action, args = []) {
+  switch (action) {
+    case "status":
+      await graphStatusCommand(ctx);
+      return;
+    case "doctor":
+      await graphDoctorCommand(ctx);
+      return;
+    case "setup":
+      await graphSetupCommand(ctx);
+      return;
+    case "handoff":
+      await graphHandoffCommand(ctx);
+      return;
+    case "init":
+      await graphAnalyzeCommand(ctx, "init", args);
+      return;
+    case "refresh":
+      await graphAnalyzeCommand(ctx, "refresh", args);
+      return;
   }
 }
+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."];
+  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.",
+    warnings,
+    nextSteps: result.state.installed && !result.state.graphExists ? ["Run fet graph init to build the first GitNexus graph"] : 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."] : []
+  ];
+  ctx.output.result({
+    ok: true,
+    command: "graph doctor",
+    summary: warnings.length ? `Graph doctor completed with ${warnings.length} warning(s).` : "Graph doctor completed without warnings.",
+    warnings,
+    nextSteps: warnings.length ? ["Run fet graph setup", "Run fet graph handoff", "Run fet graph init when GitNexus is installed"] : void 0,
+    data: result
+  });
+}
+async function graphSetupCommand(ctx) {
+  let result;
+  const handoffPath = join11(ctx.projectRoot, ".fet", "graph-setup.md");
+  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));
+    const global = await ctx.stateStore.getOrCreateGlobal();
+    global.graph ??= {};
+    global.graph.gitnexus = {
+      ...result.state,
+      setupHandoffPath: ".fet/graph-setup.md",
+      setupHandoffUpdatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await ctx.stateStore.writeGlobal(global);
+  });
+  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"],
+    data: {
+      path: ".fet/graph-setup.md",
+      gitnexus: result.state
+    }
+  });
+}
+async function graphHandoffCommand(ctx) {
+  let result;
+  const handoffPath = join11(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));
+    const global = await ctx.stateStore.getOrCreateGlobal();
+    global.graph ??= {};
+    global.graph.gitnexus = {
+      ...result.state,
+      handoffPath: ".fet/graph-handoff.md",
+      handoffUpdatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await ctx.stateStore.writeGlobal(global);
+  });
+  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"],
+    data: {
+      path: ".fet/graph-handoff.md",
+      gitnexus: result.state
+    }
+  });
+}
+async function graphAnalyzeCommand(ctx, mode, args) {
+  const detection = await detectGitNexus();
+  if (!detection.installed) {
+    throw new FetError({
+      code: "GRAPH_PROVIDER_NOT_FOUND" /* GraphProviderNotFound */,
+      message: "GitNexus is not installed or is not available on PATH.",
+      details: { executable: detection.executablePath, error: detection.error },
+      suggestedCommand: "fet graph setup"
+    });
+  }
+  const run = await runGitNexus(["analyze", ...args], { cwd: ctx.projectRoot });
+  if (run.exitCode !== 0) {
+    throw new FetError({
+      code: "GRAPH_COMMAND_FAILED" /* GraphCommandFailed */,
+      message: "GitNexus analyze failed.",
+      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 global = await ctx.stateStore.getOrCreateGlobal();
+  global.graph ??= {};
+  global.graph.gitnexus = {
+    ...result.state,
+    lastRefreshAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  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"],
+    data: {
+      gitnexus: global.graph.gitnexus,
+      run: {
+        command: run.command,
+        stdout: run.stdout.trim(),
+        stderr: run.stderr.trim()
+      }
+    }
+  });
+}
+async function refreshGraphState(ctx, options = {}) {
+  const global = await ctx.stateStore.getOrCreateGlobal();
+  global.graph ??= {};
+  const detection = await detectGitNexus();
+  const graph2 = await inspectGitNexusGraph(ctx.projectRoot);
+  let state = mergeGitNexusGraphInfo(toGitNexusState(detection, global.graph.gitnexus), graph2);
+  let gitnexusStatus = null;
+  if (options.runStatus && detection.installed) {
+    gitnexusStatus = await runGitNexus(["status"], { cwd: ctx.projectRoot });
+    state = {
+      ...state,
+      lastStatus: firstLine(gitnexusStatus.stdout) || firstLine(gitnexusStatus.stderr) || `exit ${gitnexusStatus.exitCode}`
+    };
+  }
+  if (options.write ?? true) {
+    global.graph.gitnexus = state;
+    await ctx.stateStore.writeGlobal(global);
+  }
+  return {
+    state,
+    gitnexusStatus: gitnexusStatus ? {
+      exitCode: gitnexusStatus.exitCode,
+      command: gitnexusStatus.command,
+      stdout: gitnexusStatus.stdout.trim(),
+      stderr: gitnexusStatus.stderr.trim()
+    } : null
+  };
+}
+async function writeHandoffFile(path, content) {
+  await mkdir4(dirname6(path), { recursive: true });
+  await atomicWrite(path, content);
+}
+function renderGraphSetupHandoff(state) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-setup
+FET:END -->
+
+# FET Graph Setup
+
+GitNexus graph support is optional. FET does not install GitNexus automatically and does not require graph support for OpenSpec workflows.
+
+Current status:
+
+- Installed: ${state.installed ? "yes" : "no"}
+- Executable: ${state.executablePath ?? "gitnexus"}
+- Version: ${state.version ?? "unknown"}
+- Graph path: ${state.graphPath ?? ".gitnexus"}
+- Graph exists: ${state.graphExists ? "yes" : "no"}
+
+Suggested 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.
+
+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.
+`;
+}
+function renderGraphUsageHandoff(state) {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: graph-handoff
+FET:END -->
+
+# FET Graph Handoff
+
+Use GitNexus graph context as an optional first pass before broad repository scans.
+
+Current status:
+
+- Installed: ${state.installed ? "yes" : "no"}
+- Graph path: ${state.graphPath ?? ".gitnexus"}
+- Graph exists: ${state.graphExists ? "yes" : "no"}
+- Last indexed at: ${state.lastIndexedAt ?? "unknown"}
+- Last status: ${state.lastStatus ?? "unknown"}
+
+When graph context is available:
+
+1. Use the graph to identify likely modules, dependencies, and insertion points.
+2. Read only the concrete source files needed to confirm behavior.
+3. Prefer OpenSpec artifacts and AGENTS.md over graph guesses when they conflict.
+4. Fall back to normal repository inspection if the graph is missing, stale, or incomplete.
+
+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.
+`;
+}
+function firstLine(value) {
+  return value.trim().split(/\r?\n/)[0]?.trim() || null;
+}
 
 // src/commands/proxy.ts
 import { readFile as readFile10 } from "fs/promises";
-import { join as join10 } from "path";
+import { join as join13 } from "path";
 
 // src/state/project.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
 async function detectProjectIdentity(projectRoot) {
   const [gitRoot, branch, headCommit] = await Promise.all([
     git(projectRoot, ["rev-parse", "--show-toplevel"]),
@@ -640,7 +1085,7 @@ async function detectProjectIdentity(projectRoot) {
 }
 async function git(cwd, args) {
   try {
-    const { stdout } = await execFileAsync("git", args, { cwd });
+    const { stdout } = await execFileAsync2("git", args, { cwd });
     return stdout.trim() || null;
   } catch {
     return null;
@@ -648,8 +1093,8 @@ async function git(cwd, args) {
 }
 
 // src/state/store.ts
-import { mkdir as mkdir4, readFile as readFile8 } from "fs/promises";
-import { join as join9 } from "path";
+import { mkdir as mkdir5, readFile as readFile8 } from "fs/promises";
+import { join as join12 } from "path";
 
 // src/state/schema.ts
 var phases = ["explore", "propose", "implement", "verify", "sync", "archive"];
@@ -670,6 +1115,7 @@ function createGlobalState(fetVersion, project) {
       scannerVersion: 1
     },
     toolAdapters: {},
+    graph: {},
     verifyAuthorization: null,
     lastDoctor: null
   };
@@ -757,7 +1203,7 @@ var StateStore = class {
   }
   async writeGlobal(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir4(join9(this.projectRoot, "openspec"), { recursive: true });
+    await mkdir5(join12(this.projectRoot, "openspec"), { recursive: true });
     await atomicWrite(this.globalPath(), `${JSON.stringify(state, null, 2)}
 `);
   }
@@ -778,15 +1224,15 @@ var StateStore = class {
   }
   async writeChange(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir4(join9(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
+    await mkdir5(join12(this.projectRoot, "openspec", "changes", state.changeId), { recursive: true });
     await atomicWrite(this.changePath(state.changeId), `${JSON.stringify(state, null, 2)}
 `);
   }
   globalPath() {
-    return join9(this.projectRoot, "openspec", "fet-state.json");
+    return join12(this.projectRoot, "openspec", "fet-state.json");
   }
   changePath(changeId) {
-    return join9(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
+    return join12(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
   }
 };
 function isNotFound(error) {
@@ -903,7 +1349,7 @@ async function createChangelogEntry(projectRoot, changeId) {
   };
 }
 async function appendChangelog(projectRoot, entry) {
-  const changelogPath = join10(projectRoot, "CHANGELOG.md");
+  const changelogPath = join13(projectRoot, "CHANGELOG.md");
   const existing = await readOptional3(changelogPath);
   const block = `updateTime: ${entry.updateTime}
 \u66F4\u65B0\u5185\u5BB9:${entry.content}
@@ -914,12 +1360,12 @@ ${block}` : block;
   await atomicWrite(changelogPath, next);
 }
 async function readChangeRequirement(projectRoot, changeId) {
-  const changeRoot = join10(projectRoot, "openspec", "changes", changeId);
-  const proposal = await readOptional3(join10(changeRoot, "proposal.md"));
+  const changeRoot = join13(projectRoot, "openspec", "changes", changeId);
+  const proposal = await readOptional3(join13(changeRoot, "proposal.md"));
   if (proposal) {
     return summarizeMarkdown(proposal);
   }
-  const readme = await readOptional3(join10(changeRoot, "README.md"));
+  const readme = await readOptional3(join13(changeRoot, "README.md"));
   if (readme) {
     return summarizeMarkdown(readme);
   }
@@ -1063,8 +1509,8 @@ async function assertVerified(ctx) {
 
 // src/commands/verify.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir5, readFile as readFile11, stat as stat4 } from "fs/promises";
-import { join as join11 } from "path";
+import { mkdir as mkdir6, readFile as readFile11, stat as stat5 } from "fs/promises";
+import { join as join14 } from "path";
 async function verifyCommand(ctx, options) {
   if (options.auto) {
     const scan = await ctx.scanner.scan(ctx.projectRoot, {});
@@ -1131,9 +1577,9 @@ async function verifyCommand(ctx, options) {
 async function writeInstructions(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join11(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join11(dir, "verify-instructions.md");
-  await mkdir5(dir, { recursive: true });
+  const dir = join14(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  const instructionsPath = join14(dir, "verify-instructions.md");
+  await mkdir6(dir, { recursive: true });
   await atomicWrite(instructionsPath, renderVerifyInstructions(changeId, generatedAt));
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
   state.currentPhase = "verify";
@@ -1149,7 +1595,7 @@ async function writeInstructions(ctx, changeId) {
 async function markDone(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const declaredAt = (/* @__PURE__ */ new Date()).toISOString();
-  const instructionsPath = join11(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
+  const instructionsPath = join14(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");
@@ -1184,7 +1630,7 @@ async function assertChangeExists(ctx, changeId) {
 }
 async function readInstructions(path, changeId) {
   try {
-    await stat4(path);
+    await stat5(path);
     const content = await readFile11(path, "utf8");
     const fileChangeId = readFrontMatterValue(content, "changeId");
     if (fileChangeId !== changeId) {
@@ -1235,13 +1681,76 @@ async function resolveChangeId(ctx) {
   });
 }
 
+// src/model-policy.ts
+var HIGH_COST_MODEL_PATTERNS = [
+  /gpt[-_ ]?5\.5/i,
+  /glm[-_ ]?5(?:\.1)?/i,
+  /claude.*opus/i,
+  /opus/i,
+  /claude.*sonnet/i,
+  /sonnet/i
+];
+var MODEL_ENV_KEYS = ["FET_IDE_MODEL", "FET_MODEL", "CODEX_MODEL", "CURSOR_MODEL", "OPENCODE_MODEL", "OPENAI_MODEL", "ANTHROPIC_MODEL"];
+function detectCurrentModel(env = process.env) {
+  for (const key of MODEL_ENV_KEYS) {
+    const value = env[key]?.trim();
+    if (value) {
+      return { source: key, name: value };
+    }
+  }
+  return null;
+}
+function isHighCostModel(model) {
+  return HIGH_COST_MODEL_PATTERNS.some((pattern) => pattern.test(model));
+}
+function getCommandModelPolicyMismatch(command, env = process.env) {
+  if (env.FET_MODEL_POLICY === "off" || env.FET_SKIP_MODEL_POLICY === "1") {
+    return null;
+  }
+  const detected = detectCurrentModel(env);
+  if (!detected) {
+    return null;
+  }
+  const highCost = isHighCostModel(detected.name);
+  if (command === "apply") {
+    if (!highCost) {
+      return {
+        command,
+        detected,
+        recommended: "high-cost",
+        reason: "fet apply is the implementation phase and is recommended to use a high-capability/high-cost model."
+      };
+    }
+    return null;
+  }
+  if (highCost) {
+    return {
+      command,
+      detected,
+      recommended: "low-cost",
+      reason: `fet ${command} is not the implementation phase and is recommended to use a lower-cost model.`
+    };
+  }
+  return null;
+}
+function formatModelPolicyMismatch(mismatch) {
+  const switchHint = mismatch.recommended === "high-cost" ? "Recommended models include GPT-5.5, GLM-5.1, GLM-5, Claude Opus, or Claude Sonnet." : "Recommended action: switch to a lower-cost model and reserve high-cost models for fet apply.";
+  return `${mismatch.reason} Detected ${mismatch.detected.source}="${mismatch.detected.name}". ${switchHint}`;
+}
+function renderIdeModelPolicy(command) {
+  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. If the current IDE model is lower-cost, tell the user and ask whether to stop for a model switch or continue anyway.";
+  }
+  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.";
+}
+
 // src/cli/context.ts
 import { resolve } from "path";
 
 // src/adapters/codex/index.ts
-import { mkdir as mkdir6, readFile as readFile12, stat as stat5 } from "fs/promises";
+import { mkdir as mkdir7, readFile as readFile12, stat as stat6 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname6, join as join12 } from "path";
+import { dirname as dirname7, join as join15 } from "path";
 
 // src/adapters/commands.ts
 var FET_WORKFLOW_COMMANDS = [
@@ -1257,7 +1766,18 @@ var FET_WORKFLOW_COMMANDS = [
   "bulk-archive",
   "onboard"
 ];
-var FET_ADAPTER_COMMANDS = [...FET_WORKFLOW_COMMANDS, "fill-context", "passthrough"];
+var FET_GRAPH_COMMANDS = ["graph-status", "graph-setup", "graph-init", "graph-refresh", "graph-doctor", "graph-handoff"];
+var FET_ADAPTER_COMMANDS = [...FET_WORKFLOW_COMMANDS, "fill-context", "passthrough", ...FET_GRAPH_COMMANDS];
+function renderFetAdapterUsage(command, args = "[...args]") {
+  if (command.startsWith("graph-")) {
+    const subcommand = command.slice("graph-".length);
+    return `fet graph ${subcommand}${args ? ` ${args}` : ""}`;
+  }
+  if (command === "passthrough") {
+    return `fet passthrough <openspec-command>${args ? ` ${args}` : ""}`;
+  }
+  return `fet ${command}${args ? ` ${args}` : ""}`;
+}
 
 // src/adapters/codex/templates.ts
 function codexGuideFile() {
@@ -1278,6 +1798,8 @@ Before doing FET or OpenSpec work in Codex, read:
 - openspec/config.yaml
 - the active change files under openspec/changes/<change-id>/, when a change is selected
 
+If GitNexus code graph context is available in the IDE or MCP tools, prefer it before broad repository scans. Use it to identify relevant modules, dependencies, and insertion points, then read only the concrete source files needed. If GitNexus is unavailable, continue with the normal FET/OpenSpec workflow.
+
 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/.
@@ -1303,22 +1825,30 @@ function renderCommand(command) {
   if (command === "passthrough") {
     return renderPassthroughCommand();
   }
+  if (command.startsWith("graph-")) {
+    return renderGraphCommand(command);
+  }
+  const usage = renderFetAdapterUsage(command, "");
   return `<!-- FET:MANAGED
 schemaVersion: 1
 fetVersion: ${FET_VERSION}
 generator: codex-adapter
 adapterVersion: 1
-command: fet ${command}
+command: ${usage}
 FET:END -->
 
-# fet ${command}
+# ${usage}
+
+${renderIdeModelPolicy(command)}
 
 When the user asks Codex to run the FET ${command} workflow, first make sure the project context is loaded from AGENTS.md and openspec/config.yaml.
 
+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.
+
 Then run:
 
 \`\`\`sh
-fet ${command}
+${usage}
 \`\`\`
 
 If the command needs a change id, pass it with \`--change <change-id>\` or use the active OpenSpec change from the user's request.
@@ -1337,8 +1867,12 @@ FET:END -->
 
 # fet passthrough
 
+${renderIdeModelPolicy("passthrough")}
+
 When the user asks Codex to run an OpenSpec command that FET does not manage as a first-class workflow command, use FET passthrough instead of calling OpenSpec directly.
 
+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.
+
 Then run:
 
 \`\`\`sh
@@ -1348,6 +1882,36 @@ fet passthrough <openspec-command> [...args]
 This preserves the FET entry point while allowing access to unmanaged or newly added OpenSpec commands. Passthrough does not update FET lifecycle state.
 `;
 }
+function renderGraphCommand(command) {
+  const usage = renderFetAdapterUsage(command, "");
+  const subcommand = command.slice("graph-".length);
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+command: ${usage}
+FET:END -->
+
+# ${usage}
+
+${renderIdeModelPolicy(command)}
+
+When the user asks Codex to work with optional GitNexus graph support, use FET as the entry point.
+
+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.
+
+Run:
+
+\`\`\`sh
+${usage}
+\`\`\`
+
+For graph init or refresh, pass extra GitNexus analyze arguments only when the user provides them.
+
+After the command completes, report the GitNexus state, generated handoff files, and next steps.
+`;
+}
 function renderSlashPrompt(command) {
   if (command === "continue") {
     return renderContinueSlashPrompt();
@@ -1385,9 +1949,10 @@ function renderSlashPrompt(command) {
   if (command === "passthrough") {
     return renderPassthroughSlashPrompt();
   }
-  const usage = command === "passthrough" ? "fet passthrough <openspec-command> [...args]" : `fet ${command} [...args]`;
-  const shellCommand = command === "passthrough" ? "fet passthrough $ARGUMENTS" : `fet ${command} $ARGUMENTS`;
-  const description = command === "passthrough" ? "Run an unmanaged OpenSpec command through FET passthrough" : `Run the FET-managed OpenSpec ${command} workflow`;
+  const usage = renderFetAdapterUsage(command);
+  const isGraph = command.startsWith("graph-");
+  const shellCommand = isGraph ? `${renderFetAdapterUsage(command, "")} $ARGUMENTS` : `fet ${command} $ARGUMENTS`;
+  const description = isGraph ? `Run optional GitNexus graph ${command.slice("graph-".length)} through FET` : `Run the FET-managed OpenSpec ${command} workflow`;
   return `<!-- FET:MANAGED
 schemaVersion: 1
 fetVersion: ${FET_VERSION}
@@ -1405,6 +1970,8 @@ Use FET as the entry point for this OpenSpec workflow.
 
 Before running the command, make sure the relevant project context is loaded from AGENTS.md and openspec/config.yaml. If a change id is needed and was not provided, infer it from the active FET/OpenSpec state when unambiguous; otherwise ask the user for the change id.
 
+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.
+
 Run:
 
 \`\`\`sh
@@ -1425,8 +1992,12 @@ FET:END -->
 
 # fet fill-context
 
+${renderIdeModelPolicy("fill-context")}
+
 Use this command to complete FET-generated project context placeholders with Codex.
 
+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.
+
 First run:
 
 \`\`\`sh
@@ -1809,6 +2380,7 @@ Output:
   );
 }
 function renderManagedSlashPrompt(command, description, body) {
+  const policyCommand = command.split(/\s+/)[1] ?? command;
   return `<!-- FET:MANAGED
 schemaVersion: 1
 fetVersion: ${FET_VERSION}
@@ -1822,6 +2394,10 @@ description: ${description}
 argument-hint: command arguments
 ---
 
+${renderIdeModelPolicy(policyCommand)}
+
+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.
+
 ${body}
 `;
 }
@@ -1832,7 +2408,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists3(join12(projectRoot, ".codex")) || await exists3(join12(projectRoot, "AGENTS.md")),
+      detected: await exists3(join15(projectRoot, ".codex")) || await exists3(join15(projectRoot, "AGENTS.md")),
       reason: "Codex adapter is available for projects that use AGENTS.md"
     };
   }
@@ -1871,7 +2447,7 @@ var CodexAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir6(dirname6(target), { recursive: true });
+      await mkdir7(dirname7(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(displayPath);
     }
@@ -1898,9 +2474,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join12(resolveCodexHome(), file.path);
+    return join15(resolveCodexHome(), file.path);
   }
-  return join12(projectRoot, file.path);
+  return join15(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -1909,7 +2485,7 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join12(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join15(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
@@ -1920,7 +2496,7 @@ async function readExisting(path) {
 }
 async function exists3(path) {
   try {
-    await stat5(path);
+    await stat6(path);
     return true;
   } catch {
     return false;
@@ -1928,8 +2504,8 @@ async function exists3(path) {
 }
 
 // src/adapters/cursor/index.ts
-import { mkdir as mkdir7, readFile as readFile13, stat as stat6 } from "fs/promises";
-import { dirname as dirname7, join as join13 } from "path";
+import { mkdir as mkdir8, readFile as readFile13, stat as stat7 } from "fs/promises";
+import { dirname as dirname8, join as join16 } from "path";
 
 // src/adapters/cursor/templates.ts
 function cursorSkillFiles() {
@@ -1957,6 +2533,7 @@ alwaysApply: false
 
 - AGENTS.md
 - openspec/config.yaml
+- GitNexus code graph context, when available. Prefer it before broad repository scans; if it is unavailable, continue normally.
 - \u5F53\u524D change \u76EE\u5F55\u4E0B\u7684 OpenSpec \u89C4\u5212\u4EA7\u7269
 
 \u5982\u679C\u7528\u6237\u8F93\u5165\u7C7B\u4F3C \`/fet apply\` \u7684\u8BF7\u6C42\uFF0CCursor \u5F53\u524D\u7248\u672C\u672A\u5FC5\u4F1A\u628A\u672C\u6587\u4EF6\u6CE8\u518C\u4E3A\u539F\u751F slash command\u3002\u6B64\u65F6\u8BF7\u628A\u5B83\u5F53\u4F5C\u5DE5\u4F5C\u6D41\u610F\u56FE\uFF0C\u5E76\u63D0\u793A\u7528\u6237\u5728\u7EC8\u7AEF\u6267\u884C\u5BF9\u5E94\u7684 \`fet <cmd>\` \u547D\u4EE4\u3002
@@ -1964,7 +2541,7 @@ alwaysApply: false
   };
 }
 function renderSkill(command) {
-  const usage = command === "passthrough" ? "fet passthrough <openspec-command> [...args]" : `fet ${command}`;
+  const usage = renderFetAdapterUsage(command, command === "passthrough" ? "[...args]" : "");
   if (command === "fill-context") {
     return `<!-- FET:MANAGED
 schemaVersion: 1
@@ -1982,6 +2559,10 @@ disable-model-invocation: false
 
 Run \`fet fill-context\` first if the IDE commands need refreshing.
 
+${renderIdeModelPolicy(command)}
+
+If GitNexus code graph context is available in Cursor, prefer it before broad repository scans. If it is unavailable, continue normally.
+
 Then read:
 
 - AGENTS.md
@@ -2004,6 +2585,10 @@ description: Run FET-managed OpenSpec ${command} workflow from the terminal
 disable-model-invocation: true
 ---
 
+${renderIdeModelPolicy(command)}
+
+If GitNexus code graph context is available in Cursor, prefer it before broad repository scans. If it is unavailable, continue normally.
+
 \u6CE8\u610F\uFF1A\u6B64\u6587\u4EF6\u91C7\u7528 Cursor Skill \u76EE\u5F55\u7ED3\u6784\u3002\u5B83\u63D0\u4F9B \`/fet-${command}\` \u98CE\u683C\u7684\u5DE5\u4F5C\u6D41\u8BF4\u660E\uFF0C\u4E0D\u627F\u8BFA\u6CE8\u518C \`/fet ${command}\` \u8FD9\u79CD\u5E26\u7A7A\u683C\u7684\u539F\u751F slash command\u3002
 
 \u8BF7\u5728\u7EC8\u7AEF\u4E2D\u6267\u884C\uFF1A
@@ -2022,7 +2607,7 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists4(join13(projectRoot, ".cursor")),
+      detected: await exists4(join16(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
@@ -2039,7 +2624,7 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join13(projectRoot, file.path);
+      const target = join16(projectRoot, file.path);
       const existing = await readExisting2(target);
       if (existing && !existing.includes("FET:MANAGED") && !force) {
         throw new FetError({
@@ -2052,7 +2637,7 @@ var CursorAdapter = 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(file.path);
     }
@@ -2062,7 +2647,7 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join13(projectRoot, file.path);
+      const target = join16(projectRoot, file.path);
       const content = await readExisting2(target);
       const managed = Boolean(content?.includes("FET:MANAGED"));
       const versionMatches = Boolean(content?.includes(`adapterVersion: ${this.adapterVersion}`));
@@ -2085,7 +2670,7 @@ async function readExisting2(path) {
 }
 async function exists4(path) {
   try {
-    await stat6(path);
+    await stat7(path);
     return true;
   } catch {
     return false;
@@ -2093,17 +2678,17 @@ async function exists4(path) {
 }
 
 // src/openspec/adapter.ts
-import { execFile as execFile3 } from "child_process";
-import { promisify as promisify3 } from "util";
+import { execFile as execFile4 } from "child_process";
+import { promisify as promisify4 } from "util";
 
 // src/openspec/inspector.ts
-import { readdir, stat as stat7 } from "fs/promises";
-import { join as join14 } from "path";
+import { readdir, stat as stat8 } from "fs/promises";
+import { join as join17 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join14(projectRoot, "openspec");
-  const changesPath = join14(openspecPath, "changes");
-  const legacyArchivePath = join14(openspecPath, "archive");
-  const changesArchivePath = join14(changesPath, "archive");
+  const openspecPath = join17(projectRoot, "openspec");
+  const changesPath = join17(openspecPath, "changes");
+  const legacyArchivePath = join17(openspecPath, "archive");
+  const changesArchivePath = join17(changesPath, "archive");
   return {
     exists: await exists5(openspecPath),
     changes: await listDirectories(changesPath, { exclude: ["archive"] }),
@@ -2111,13 +2696,13 @@ async function inspectOpenSpecProject(projectRoot) {
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join14(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join14(changePath, "tasks.md");
-  const specsPath = join14(changePath, "specs");
+  const changePath = join17(projectRoot, "openspec", "changes", changeId);
+  const tasksPath = join17(changePath, "tasks.md");
+  const specsPath = join17(changePath, "specs");
   return {
     changeId,
     exists: await exists5(changePath),
-    hasProposal: await exists5(join14(changePath, "proposal.md")),
+    hasProposal: await exists5(join17(changePath, "proposal.md")),
     hasTasks: await exists5(tasksPath),
     hasSpecs: await exists5(specsPath),
     tasksPath,
@@ -2135,7 +2720,7 @@ async function listDirectories(path, options = {}) {
 }
 async function exists5(path) {
   try {
-    await stat7(path);
+    await stat8(path);
     return true;
   } catch {
     return false;
@@ -2143,9 +2728,9 @@ async function exists5(path) {
 }
 
 // src/openspec/resolver.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-var execFileAsync2 = promisify2(execFile2);
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
+var execFileAsync3 = promisify3(execFile3);
 async function resolveOpenSpecExecutable() {
   const executablePath = await findExecutable();
   const version = await readVersion(executablePath);
@@ -2192,7 +2777,7 @@ async function readVersion(executablePath) {
   }
 }
 function exec(command, args) {
-  return execFileAsync2(command, args, { shell: process.platform === "win32" });
+  return execFileAsync3(command, args, { shell: process.platform === "win32" });
 }
 
 // src/openspec/runner.ts
@@ -2238,7 +2823,7 @@ async function runOpenSpec(executablePath, command, args, options) {
 }
 
 // src/openspec/adapter.ts
-var execFileAsync3 = promisify3(execFile3);
+var execFileAsync4 = promisify4(execFile4);
 var DefaultOpenSpecAdapter = class {
   identity;
   async resolveExecutable() {
@@ -2250,7 +2835,7 @@ var DefaultOpenSpecAdapter = class {
     const executable = identity.executablePath === "npx openspec" ? "npx" : identity.executablePath;
     const args = identity.executablePath === "npx openspec" ? ["openspec", "--help"] : ["--help"];
     try {
-      const { stdout } = await execFileAsync3(executable, args, { shell: process.platform === "win32" });
+      const { stdout } = await execFileAsync4(executable, args, { shell: process.platform === "win32" });
       return {
         version: identity.version,
         commands: parseCommands(stdout),
@@ -2294,12 +2879,12 @@ function parseCommands(help) {
 }
 
 // src/scanner/package.ts
-import { readFile as readFile14, stat as stat8 } from "fs/promises";
-import { join as join15 } from "path";
+import { readFile as readFile14, stat as stat9 } from "fs/promises";
+import { join as join18 } from "path";
 import { parse as parse2 } from "yaml";
 async function readPackageJson(projectRoot) {
   try {
-    return JSON.parse(await readFile14(join15(projectRoot, "package.json"), "utf8"));
+    return JSON.parse(await readFile14(join18(projectRoot, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -2365,7 +2950,7 @@ function detectFramework(pkg) {
 }
 async function detectLanguage(projectRoot, pkg) {
   const deps = { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
-  if (deps.typescript || await exists6(join15(projectRoot, "tsconfig.json"))) {
+  if (deps.typescript || await exists6(join18(projectRoot, "tsconfig.json"))) {
     return "typescript";
   }
   return "javascript";
@@ -2380,7 +2965,7 @@ async function detectWorkspaces(projectRoot, pkg) {
     return packageWorkspaces;
   }
   try {
-    const workspace = parse2(await readFile14(join15(projectRoot, "pnpm-workspace.yaml"), "utf8"));
+    const workspace = parse2(await readFile14(join18(projectRoot, "pnpm-workspace.yaml"), "utf8"));
     return (workspace?.packages ?? []).map((path) => ({
       name: path,
       path,
@@ -2400,7 +2985,7 @@ async function detectLockManagers(projectRoot) {
   ];
   const found = [];
   for (const [file, manager] of lockFiles) {
-    if (await exists6(join15(projectRoot, file))) {
+    if (await exists6(join18(projectRoot, file))) {
       found.push(manager);
     }
   }
@@ -2417,7 +3002,7 @@ function scriptCommand(packageManager, name) {
 }
 async function exists6(path) {
   try {
-    await stat8(path);
+    await stat9(path);
     return true;
   } catch {
     return false;
@@ -2425,13 +3010,13 @@ async function exists6(path) {
 }
 
 // src/scanner/routes.ts
-import { readdir as readdir2, stat as stat9 } from "fs/promises";
-import { join as join16, relative, sep } from "path";
+import { readdir as readdir2, stat as stat10 } from "fs/promises";
+import { join as join19, 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 = join16(projectRoot, candidate);
+    const root = join19(projectRoot, candidate);
     if (!await exists7(root)) {
       continue;
     }
@@ -2459,7 +3044,7 @@ async function listFiles(root) {
   const entries = await readdir2(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join16(root, entry.name);
+    const path = join19(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {
@@ -2470,7 +3055,7 @@ async function listFiles(root) {
 }
 async function exists7(path) {
   try {
-    await stat9(path);
+    await stat10(path);
     return true;
   } catch {
     return false;
@@ -2523,6 +3108,11 @@ var OutputWriter = class {
     }
   }
   warn(message, details) {
+    if (this.json) {
+      process.stderr.write(`${JSON.stringify({ ok: true, warning: message, details }, null, 2)}
+`);
+      return;
+    }
     if (!this.json) {
       process.stderr.write(`\u8B66\u544A\uFF1A${message}${formatDetails(details)}
 `);
@@ -2612,6 +3202,13 @@ program.name("fet").description("Frontend workflow orchestration tool built arou
 addGlobalOptions(program.command("init")).description("\u521D\u59CB\u5316 FET + OpenSpec").action(wrap("init", initCommand));
 addGlobalOptions(program.command("update-context")).description("\u66F4\u65B0\u9879\u76EE\u4E0A\u4E0B\u6587").action(wrap("update-context", updateContextCommand));
 addGlobalOptions(program.command("fill-context")).description("Refresh IDE prompts for filling AGENTS.md placeholders").action(wrap("fill-context", fillContextCommand));
+var graph = addGlobalOptions(program.command("graph").description("Manage optional GitNexus code graph support"));
+for (const action of ["status", "setup", "doctor", "handoff"]) {
+  addGlobalOptions(graph.command(action).description(`Run fet graph ${action}`)).action(wrap("graph", (ctx) => graphCommand(ctx, action)));
+}
+for (const action of ["init", "refresh"]) {
+  addGlobalOptions(graph.command(`${action} [args...]`).description(`Run GitNexus analyze for graph ${action}`).allowUnknownOption(true).passThroughOptions()).action(wrap("graph", (ctx, args = []) => graphCommand(ctx, action, args)));
+}
 addGlobalOptions(program.command("doctor").description("\u8BCA\u65AD\u72B6\u6001\u3001\u914D\u7F6E\u4E0E\u4E00\u81F4\u6027").option("--fix-lock", "\u6E05\u7406 FET \u9501\u6587\u4EF6")).action(
   wrap("doctor", (ctx, options) => doctorCommand(ctx, { fixLock: Boolean(options.fixLock) }))
 );
@@ -2633,6 +3230,8 @@ function wrap(command, handler) {
     const opts = isCommandLike(maybeCommand) ? { ...maybeCommand.parent?.opts(), ...maybeCommand.opts() } : program.opts();
     const ctx = await createCommandContext(command, { ...opts, ...extractGlobalOptions(args) });
     try {
+      await confirmModelPolicyRecommendation(ctx);
+      await warnIfContextPlaceholdersRemain(ctx);
       await handler(ctx, ...args);
     } catch (error) {
       const fetError = toFetError(error);
@@ -2641,6 +3240,40 @@ function wrap(command, handler) {
     }
   };
 }
+async function confirmModelPolicyRecommendation(ctx) {
+  const mismatch = getCommandModelPolicyMismatch(ctx.command);
+  if (!mismatch) {
+    return;
+  }
+  const warning = formatModelPolicyMismatch(mismatch);
+  ctx.output.warn(`${warning} You can stop now to switch models, or continue this command.`);
+  if (ctx.yes || ctx.json || !process.stdin.isTTY || !process.stderr.isTTY) {
+    return;
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = (await rl.question("Continue anyway? [y/N] ")).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      throw new FetError({
+        code: "USER_CANCELLED" /* UserCancelled */,
+        message: "Command cancelled so you can switch IDE model.",
+        details: { command: ctx.command, detected: mismatch.detected, recommended: mismatch.recommended },
+        suggestedCommand: `Switch IDE model, then rerun fet ${ctx.command}.`
+      });
+    }
+  } finally {
+    rl.close();
+  }
+}
+async function warnIfContextPlaceholdersRemain(ctx) {
+  if (["init", "update-context", "fill-context", "doctor"].includes(ctx.command)) {
+    return;
+  }
+  const count2 = await countAgentsLlmPlaceholders(ctx.projectRoot);
+  if (count2 > 0) {
+    ctx.output.warn(renderAgentsPlaceholderWarning(count2));
+  }
+}
 function isCommandLike(value) {
   return value instanceof Command;
 }