@nick848/fet 1.0.4 → 1.0.6

package/dist/cli/index.js

@@ -2,15 +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 readFile6, stat as stat2 } from "fs/promises";
-import { join as join7 } 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";
@@ -118,23 +118,26 @@ 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 executable = env.FET_GITNEXUS_EXECUTABLE?.trim() || "gitnexus";
+  const command = resolveGitNexusCommand(env);
   try {
-    const { stdout, stderr } = await execFileAsync(executable, ["--version"], { shell: process.platform === "win32" });
+    const { stdout, stderr } = await execFileAsync(command.file, [...command.args, "--version"], { shell: process.platform === "win32" });
     return {
       installed: true,
-      executablePath: executable,
+      executablePath: command.label,
       version: (stdout.trim() || stderr.trim() || "unknown").split(/\r?\n/)[0] ?? "unknown",
       checkedAt
     };
   } catch (error) {
     return {
       installed: false,
-      executablePath: executable,
+      executablePath: command.label,
       version: null,
       checkedAt,
       error: error instanceof Error ? error.message : String(error)
@@ -148,7 +151,66 @@ function toGitNexusState(detection, previous) {
     executablePath: detection.installed ? detection.executablePath : null,
     version: detection.version,
     checkedAt: detection.checkedAt,
-    recommendationShownAt: previous?.recommendationShownAt ?? null
+    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) {
@@ -157,17 +219,27 @@ function renderGitNexusRecommendation(state) {
   }
   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) {
@@ -296,6 +368,12 @@ ${routes || "| [NEEDS LLM INPUT] | [NEEDS LLM INPUT] | low |"}
 
 [NEEDS LLM INPUT]
 
+## AI Work Guidelines
+
+- Prefer the project-level Andrej Karpathy inspired guidelines in .fet/karpathy-guidelines.md when using FET-managed IDE workflows.
+- For Codex, also read .codex/fet/karpathy-guidelines.md when present.
+- Treat those guidelines as secondary to the user's latest request and explicit OpenSpec artifacts.
+
 ## Scanner Metadata
 
 - Generated At: ${scan.generatedAt}
@@ -343,6 +421,97 @@ function renderFetConfig(scan) {
   });
 }
 
+// src/templates/karpathy-skills.ts
+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());
+  if (!existing || !existing.trim()) {
+    return `${block}
+`;
+  }
+  const start = existing.indexOf(BEGIN);
+  const end = existing.indexOf(END);
+  if (start !== -1 && end !== -1 && end > start) {
+    return `${existing.slice(0, start)}${block}${existing.slice(end + END.length)}`;
+  }
+  return `${existing.replace(/\s*$/, "")}
+
+${block}
+`;
+}
+function renderKarpathyCursorRule() {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: karpathy-skills
+FET:END -->
+
+---
+description: Andrej Karpathy inspired coding guidelines
+alwaysApply: true
+---
+
+${renderKarpathyGuidelinesBody()}
+`;
+}
+function renderKarpathyFetHandoff() {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: karpathy-skills
+FET:END -->
+
+# Andrej Karpathy Inspired Coding Guidelines
+
+${renderKarpathyGuidelinesBody()}
+`;
+}
+function renderManagedBlock(content) {
+  return `${BEGIN}
+${content}
+${END}`;
+}
+function renderKarpathyClaudeGuidelines() {
+  return `# Andrej Karpathy Inspired Coding Guidelines
+
+${renderKarpathyGuidelinesBody()}`;
+}
+function renderKarpathyGuidelinesBody() {
+  return `Source: ${KARPATHY_SKILLS_SOURCE}
+
+Use these project-level guidelines together with AGENTS.md, OpenSpec artifacts, and the user's latest request.
+
+## Think Before Coding
+
+- State important assumptions before editing.
+- Ask for clarification when ambiguity would change the implementation.
+- Surface tradeoffs instead of silently choosing a risky path.
+- Push back when a simpler approach better fits the request.
+
+## Simplicity First
+
+- Solve the requested problem with the smallest clear change.
+- Avoid speculative features, configuration, or abstraction.
+- Do not create abstractions for one-off code.
+- Prefer deleting complexity introduced by your own change over adding more structure.
+
+## Precise Edits
+
+- Touch only files and lines that directly serve the task.
+- Preserve existing style even when you personally prefer another pattern.
+- Do not refactor nearby code, comments, or formatting unless the task requires it.
+- Remove only dead imports, variables, or helpers made obsolete by your own change.
+
+## Goal-Driven Execution
+
+- Convert vague work into concrete success criteria.
+- For bugs, prefer a reproducing test or clear verification before the fix.
+- For multi-step work, keep a short plan and verify each meaningful step.
+- Continue iterating until the success criteria are met or a blocker is explicit.
+
+These guidelines intentionally favor caution over speed for non-trivial work. For obvious one-line fixes, use judgment and stay lightweight.`;
+}
+
 // src/templates/verify-instructions.ts
 function renderVerifyInstructions(changeId, generatedAt = (/* @__PURE__ */ new Date()).toISOString()) {
   return `---
@@ -370,27 +539,28 @@ fet verify --done --change ${changeId}
 }
 
 // src/templates/gitignore.ts
-var BEGIN = "# FET:BEGIN LOCAL STATE";
-var END = "# FET:END LOCAL STATE";
+var BEGIN2 = "# FET:BEGIN LOCAL STATE";
+var END2 = "# FET:END LOCAL STATE";
 var RULES = [
   "openspec/fet-state.json",
   "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}
+  const block = `${BEGIN2}
 ${RULES.join("\n")}
-${END}`;
+${END2}`;
   if (!existing || !existing.trim()) {
     return `${block}
 `;
   }
-  const start = existing.indexOf(BEGIN);
-  const end = existing.indexOf(END);
+  const start = existing.indexOf(BEGIN2);
+  const end = existing.indexOf(END2);
   if (start !== -1 && end !== -1 && end > start) {
-    return `${existing.slice(0, start)}${block}${existing.slice(end + END.length)}`;
+    return `${existing.slice(0, start)}${block}${existing.slice(end + END2.length)}`;
   }
   return `${existing.replace(/\s*$/, "")}
 
@@ -400,7 +570,7 @@ ${block}
 
 // src/commands/update-context.ts
 import { readFile as readFile5 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/config/yaml.ts
 import { readFile as readFile3 } from "fs/promises";
@@ -421,11 +591,11 @@ async function mergeFetConfig(configPath, renderedFetYaml) {
 
 // src/context-placeholders.ts
 import { readFile as readFile4 } from "fs/promises";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 var AGENTS_LLM_PLACEHOLDER_PATTERN = /\[NEEDS? LLM INPUT\]/g;
 async function countAgentsLlmPlaceholders(projectRoot) {
   try {
-    const content = await readFile4(join5(projectRoot, "AGENTS.md"), "utf8");
+    const content = await readFile4(join6(projectRoot, "AGENTS.md"), "utf8");
     return [...content.matchAll(AGENTS_LLM_PLACEHOLDER_PATTERN)].length;
   } catch {
     return 0;
@@ -454,9 +624,14 @@ async function updateContextCommand(ctx) {
 }
 async function updateContextFiles(ctx) {
   const scan = await ctx.scanner.scan(ctx.projectRoot, {});
-  const agentsPath = join6(ctx.projectRoot, "AGENTS.md");
-  const configPath = join6(ctx.projectRoot, "openspec", "config.yaml");
+  const agentsPath = join7(ctx.projectRoot, "AGENTS.md");
+  const configPath = join7(ctx.projectRoot, "openspec", "config.yaml");
+  const claudePath = join7(ctx.projectRoot, "CLAUDE.md");
+  const karpathyHandoffPath = join7(ctx.projectRoot, ".fet", "karpathy-guidelines.md");
+  const karpathyCursorPath = join7(ctx.projectRoot, ".cursor", "rules", "karpathy-guidelines.mdc");
   const existingAgents = await readOptional(agentsPath);
+  const existingClaude = await readOptional(claudePath);
+  const existingKarpathyCursor = await readOptional(karpathyCursorPath);
   const warnings = [...scan.warnings];
   if (existingAgents && hasInvalidManagedAutoRegion(existingAgents)) {
     throw new FetError({
@@ -482,6 +657,13 @@ async function updateContextFiles(ctx) {
   }
   await atomicWrite(agentsPath, replaceManagedRegion(existingAgents, renderAgentsMd(scan)));
   await atomicWrite(configPath, await mergeFetConfig(configPath, renderFetConfig(scan)));
+  await atomicWrite(claudePath, mergeKarpathyClaudeMd(existingClaude));
+  await atomicWrite(karpathyHandoffPath, renderKarpathyFetHandoff());
+  if (!existingKarpathyCursor || existingKarpathyCursor.includes("FET:MANAGED")) {
+    await atomicWrite(karpathyCursorPath, renderKarpathyCursorRule());
+  } else {
+    warnings.push(".cursor/rules/karpathy-guidelines.mdc exists and is not managed by FET; leaving it unchanged.");
+  }
   const placeholderCount = await countAgentsLlmPlaceholders(ctx.projectRoot);
   if (placeholderCount > 0) {
     warnings.push(renderAgentsPlaceholderWarning(placeholderCount));
@@ -505,7 +687,7 @@ async function readOptional(path) {
 
 // src/commands/init.ts
 async function initCommand(ctx) {
-  const alreadyInitialized = await exists(join7(ctx.projectRoot, "openspec", "config.yaml"));
+  const alreadyInitialized = await exists(join8(ctx.projectRoot, "openspec", "config.yaml"));
   let warnings = [];
   await withProjectLock(
     ctx.projectRoot,
@@ -527,7 +709,10 @@ async function initCommand(ctx) {
       const state = await ctx.stateStore.getOrCreateGlobal();
       state.openspec = identity;
       state.graph ??= {};
-      const gitnexus = toGitNexusState(await detectGitNexus(), state.graph.gitnexus);
+      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();
@@ -557,7 +742,7 @@ async function initCommand(ctx) {
   });
 }
 async function ensureGitignore(ctx) {
-  const gitignorePath = join7(ctx.projectRoot, ".gitignore");
+  const gitignorePath = join8(ctx.projectRoot, ".gitignore");
   const existing = await readOptional2(gitignorePath);
   await atomicWrite(gitignorePath, mergeGitignore(existing));
 }
@@ -570,7 +755,7 @@ async function readOptional2(path) {
 }
 async function exists(path) {
   try {
-    await stat2(path);
+    await stat3(path);
     return true;
   } catch {
     return false;
@@ -578,20 +763,20 @@ async function exists(path) {
 }
 
 // src/commands/doctor.ts
-import { readFile as readFile7, stat as stat3 } from "fs/promises";
-import { join as join8 } 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", join8(ctx.projectRoot, "AGENTS.md"), "AGENTS.md \u7F3A\u5931", "fet update-context"));
-  checks.push(await checkFile("config", join8(ctx.projectRoot, "openspec", "config.yaml"), "openspec/config.yaml \u7F3A\u5931", "fet init"));
+  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 = join8(ctx.projectRoot, "openspec", ".fet.lock");
+  const lockPath = join9(ctx.projectRoot, "openspec", ".fet.lock");
   if (await exists2(lockPath)) {
     if (options.fixLock) {
       await clearLock(ctx.projectRoot);
@@ -611,7 +796,10 @@ async function doctorCommand(ctx, options = {}) {
 }
 async function checkGitNexus(ctx) {
   const global = await ctx.stateStore.readGlobal();
-  const state = toGitNexusState(await detectGitNexus(), global?.graph?.gitnexus);
+  const state = mergeGitNexusGraphInfo(
+    toGitNexusState(await detectGitNexus(), global?.graph?.gitnexus),
+    await inspectGitNexusGraph(ctx.projectRoot)
+  );
   if (global) {
     global.graph ??= {};
     global.graph.gitnexus = state;
@@ -620,7 +808,7 @@ async function checkGitNexus(ctx) {
   return state.installed ? {
     id: "gitnexus",
     status: "pass",
-    message: `GitNexus detected: ${state.executablePath ?? "gitnexus"} (${state.version ?? "unknown"})`
+    message: `GitNexus detected: ${state.executablePath ?? "gitnexus"} (${state.version ?? "unknown"}), graph ${state.graphExists ? "found" : "not found"}`
   } : {
     id: "gitnexus",
     status: "warn",
@@ -649,7 +837,7 @@ async function checkFile(id, path, missing, suggestedCommand) {
 }
 async function checkPlaceholders(projectRoot) {
   try {
-    await readFile7(join8(projectRoot, "AGENTS.md"), "utf8");
+    await readFile7(join9(projectRoot, "AGENTS.md"), "utf8");
     const count2 = await countAgentsLlmPlaceholders(projectRoot);
     return count2 ? {
       id: "context-placeholders",
@@ -663,7 +851,7 @@ async function checkPlaceholders(projectRoot) {
 }
 async function exists2(path) {
   try {
-    await stat3(path);
+    await stat4(path);
     return true;
   } catch {
     return false;
@@ -672,13 +860,13 @@ async function exists2(path) {
 
 // src/commands/fill-context.ts
 import { mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname5, join as join9 } from "path";
+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 = join9(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) {
@@ -725,17 +913,268 @@ FET:END -->
 Use the IDE AI to complete FET-generated placeholders.
 
 1. Read AGENTS.md and openspec/config.yaml.
-2. Inspect README files, package scripts, routes, tests, source layout, and project conventions.
-3. Replace every \`[NEEDS LLM INPUT]\` or \`[NEED LLM INPUT]\` placeholder in AGENTS.md with concrete project-specific content.
-4. Preserve FET managed markers.
-5. Do not modify business code.
-6. Run \`fet doctor\` and confirm no AGENTS.md placeholder warning remains.
+2. Read .fet/karpathy-guidelines.md when it exists. For Codex, also read .codex/fet/karpathy-guidelines.md when it exists.
+3. Inspect README files, package scripts, routes, tests, source layout, and project conventions.
+4. Replace every \`[NEEDS LLM INPUT]\` or \`[NEED LLM INPUT]\` placeholder in AGENTS.md with concrete project-specific content.
+5. Preserve FET managed markers.
+6. Do not modify business code.
+7. Run \`fet doctor\` and confirm no AGENTS.md placeholder warning remains.
+`;
+}
+
+// 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 join11 } from "path";
+import { join as join13 } from "path";
 
 // src/state/project.ts
 import { execFile as execFile2 } from "child_process";
@@ -764,8 +1203,8 @@ async function git(cwd, args) {
 }
 
 // src/state/store.ts
-import { mkdir as mkdir4, readFile as readFile8 } from "fs/promises";
-import { join as join10 } 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"];
@@ -874,7 +1313,7 @@ var StateStore = class {
   }
   async writeGlobal(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir4(join10(this.projectRoot, "openspec"), { recursive: true });
+    await mkdir5(join12(this.projectRoot, "openspec"), { recursive: true });
     await atomicWrite(this.globalPath(), `${JSON.stringify(state, null, 2)}
 `);
   }
@@ -895,15 +1334,15 @@ var StateStore = class {
   }
   async writeChange(state) {
     state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await mkdir4(join10(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 join10(this.projectRoot, "openspec", "fet-state.json");
+    return join12(this.projectRoot, "openspec", "fet-state.json");
   }
   changePath(changeId) {
-    return join10(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
+    return join12(this.projectRoot, "openspec", "changes", changeId, "fet-state.json");
   }
 };
 function isNotFound(error) {
@@ -1020,7 +1459,7 @@ async function createChangelogEntry(projectRoot, changeId) {
   };
 }
 async function appendChangelog(projectRoot, entry) {
-  const changelogPath = join11(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}
@@ -1031,12 +1470,12 @@ ${block}` : block;
   await atomicWrite(changelogPath, next);
 }
 async function readChangeRequirement(projectRoot, changeId) {
-  const changeRoot = join11(projectRoot, "openspec", "changes", changeId);
-  const proposal = await readOptional3(join11(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(join11(changeRoot, "README.md"));
+  const readme = await readOptional3(join13(changeRoot, "README.md"));
   if (readme) {
     return summarizeMarkdown(readme);
   }
@@ -1180,8 +1619,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 join12 } 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, {});
@@ -1248,9 +1687,9 @@ async function verifyCommand(ctx, options) {
 async function writeInstructions(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join12(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join12(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";
@@ -1266,7 +1705,7 @@ async function writeInstructions(ctx, changeId) {
 async function markDone(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   const declaredAt = (/* @__PURE__ */ new Date()).toISOString();
-  const instructionsPath = join12(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");
@@ -1301,7 +1740,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) {
@@ -1419,9 +1858,9 @@ function renderIdeModelPolicy(command) {
 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 join13 } from "path";
+import { dirname as dirname7, join as join15 } from "path";
 
 // src/adapters/commands.ts
 var FET_WORKFLOW_COMMANDS = [
@@ -1437,7 +1876,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() {
@@ -1456,6 +1906,7 @@ Before doing FET or OpenSpec work in Codex, read:
 
 - AGENTS.md
 - openspec/config.yaml
+- .codex/fet/karpathy-guidelines.md
 - 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.
@@ -1467,10 +1918,13 @@ Command guides live in .codex/fet/commands/.
   };
 }
 function codexCommandFiles() {
-  return FET_ADAPTER_COMMANDS.map((command) => ({
-    path: `.codex/fet/commands/${command}.md`,
-    content: renderCommand(command)
-  }));
+  return [
+    codexKarpathyGuidelinesFile(),
+    ...FET_ADAPTER_COMMANDS.map((command) => ({
+      path: `.codex/fet/commands/${command}.md`,
+      content: renderCommand(command)
+    }))
+  ];
 }
 function codexSlashPromptFiles() {
   return FET_ADAPTER_COMMANDS.map((command) => ({
@@ -1478,6 +1932,22 @@ function codexSlashPromptFiles() {
     content: renderSlashPrompt(command)
   }));
 }
+function codexKarpathyGuidelinesFile() {
+  return {
+    path: ".codex/fet/karpathy-guidelines.md",
+    content: `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+FET:END -->
+
+# Andrej Karpathy Inspired Coding Guidelines
+
+${renderKarpathyGuidelinesBody()}
+`
+  };
+}
 function renderCommand(command) {
   if (command === "fill-context") {
     return renderFillContextCommand();
@@ -1485,26 +1955,32 @@ 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.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 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.
@@ -1527,6 +2003,8 @@ ${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.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 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:
@@ -1538,6 +2016,38 @@ 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.
+
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
+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();
@@ -1575,9 +2085,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}
@@ -1595,6 +2106,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.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 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:
@@ -1621,6 +2134,8 @@ ${renderIdeModelPolicy("fill-context")}
 
 Use this command to complete FET-generated project context placeholders with Codex.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 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:
@@ -1645,16 +2160,17 @@ Steps:
    fet fill-context
    \`\`\`
 2. Read AGENTS.md and openspec/config.yaml.
-3. Inspect the project to understand:
+3. Read .codex/fet/karpathy-guidelines.md.
+4. Inspect the project to understand:
    - source structure and major modules
    - framework and routing conventions
    - scripts, test commands, and build commands
    - coding conventions and project-specific patterns
    - important docs such as README files
-4. Replace every \`[NEEDS LLM INPUT]\` or \`[NEED LLM INPUT]\` placeholder in AGENTS.md with concrete, concise project-specific content.
-5. Preserve FET managed markers such as \`FET:BEGIN AUTO\`, \`FET:END AUTO\`, \`FET:BEGIN USER\`, and \`FET:END USER\`.
-6. Do not modify business code.
-7. Run:
+5. Replace every \`[NEEDS LLM INPUT]\` or \`[NEED LLM INPUT]\` placeholder in AGENTS.md with concrete, concise project-specific content.
+6. Preserve FET managed markers such as \`FET:BEGIN AUTO\`, \`FET:END AUTO\`, \`FET:BEGIN USER\`, and \`FET:END USER\`.
+7. Do not modify business code.
+8. Run:
    \`\`\`sh
    fet doctor
    \`\`\`
@@ -2033,7 +2549,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists3(join13(projectRoot, ".codex")) || await exists3(join13(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"
     };
   }
@@ -2072,7 +2588,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);
     }
@@ -2099,9 +2615,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join13(resolveCodexHome(), file.path);
+    return join15(resolveCodexHome(), file.path);
   }
-  return join13(projectRoot, file.path);
+  return join15(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -2110,7 +2626,7 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join13(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join15(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
@@ -2121,7 +2637,7 @@ async function readExisting(path) {
 }
 async function exists3(path) {
   try {
-    await stat5(path);
+    await stat6(path);
     return true;
   } catch {
     return false;
@@ -2129,8 +2645,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 join14 } 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() {
@@ -2166,7 +2682,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
@@ -2232,7 +2748,7 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists4(join14(projectRoot, ".cursor")),
+      detected: await exists4(join16(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
@@ -2249,7 +2765,7 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join14(projectRoot, file.path);
+      const target = join16(projectRoot, file.path);
       const existing = await readExisting2(target);
       if (existing && !existing.includes("FET:MANAGED") && !force) {
         throw new FetError({
@@ -2262,7 +2778,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);
     }
@@ -2272,7 +2788,7 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join14(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}`));
@@ -2295,7 +2811,7 @@ async function readExisting2(path) {
 }
 async function exists4(path) {
   try {
-    await stat6(path);
+    await stat7(path);
     return true;
   } catch {
     return false;
@@ -2307,13 +2823,13 @@ 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 join15 } from "path";
+import { readdir, stat as stat8 } from "fs/promises";
+import { join as join17 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join15(projectRoot, "openspec");
-  const changesPath = join15(openspecPath, "changes");
-  const legacyArchivePath = join15(openspecPath, "archive");
-  const changesArchivePath = join15(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"] }),
@@ -2321,13 +2837,13 @@ async function inspectOpenSpecProject(projectRoot) {
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join15(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join15(changePath, "tasks.md");
-  const specsPath = join15(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(join15(changePath, "proposal.md")),
+    hasProposal: await exists5(join17(changePath, "proposal.md")),
     hasTasks: await exists5(tasksPath),
     hasSpecs: await exists5(specsPath),
     tasksPath,
@@ -2345,7 +2861,7 @@ async function listDirectories(path, options = {}) {
 }
 async function exists5(path) {
   try {
-    await stat7(path);
+    await stat8(path);
     return true;
   } catch {
     return false;
@@ -2504,12 +3020,12 @@ function parseCommands(help) {
 }
 
 // src/scanner/package.ts
-import { readFile as readFile14, stat as stat8 } from "fs/promises";
-import { join as join16 } 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(join16(projectRoot, "package.json"), "utf8"));
+    return JSON.parse(await readFile14(join18(projectRoot, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -2575,7 +3091,7 @@ function detectFramework(pkg) {
 }
 async function detectLanguage(projectRoot, pkg) {
   const deps = { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
-  if (deps.typescript || await exists6(join16(projectRoot, "tsconfig.json"))) {
+  if (deps.typescript || await exists6(join18(projectRoot, "tsconfig.json"))) {
     return "typescript";
   }
   return "javascript";
@@ -2590,7 +3106,7 @@ async function detectWorkspaces(projectRoot, pkg) {
     return packageWorkspaces;
   }
   try {
-    const workspace = parse2(await readFile14(join16(projectRoot, "pnpm-workspace.yaml"), "utf8"));
+    const workspace = parse2(await readFile14(join18(projectRoot, "pnpm-workspace.yaml"), "utf8"));
     return (workspace?.packages ?? []).map((path) => ({
       name: path,
       path,
@@ -2610,7 +3126,7 @@ async function detectLockManagers(projectRoot) {
   ];
   const found = [];
   for (const [file, manager] of lockFiles) {
-    if (await exists6(join16(projectRoot, file))) {
+    if (await exists6(join18(projectRoot, file))) {
       found.push(manager);
     }
   }
@@ -2627,7 +3143,7 @@ function scriptCommand(packageManager, name) {
 }
 async function exists6(path) {
   try {
-    await stat8(path);
+    await stat9(path);
     return true;
   } catch {
     return false;
@@ -2635,13 +3151,13 @@ async function exists6(path) {
 }
 
 // src/scanner/routes.ts
-import { readdir as readdir2, stat as stat9 } from "fs/promises";
-import { join as join17, 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 = join17(projectRoot, candidate);
+    const root = join19(projectRoot, candidate);
     if (!await exists7(root)) {
       continue;
     }
@@ -2669,7 +3185,7 @@ async function listFiles(root) {
   const entries = await readdir2(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join17(root, entry.name);
+    const path = join19(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {
@@ -2680,7 +3196,7 @@ async function listFiles(root) {
 }
 async function exists7(path) {
   try {
-    await stat9(path);
+    await stat10(path);
     return true;
   } catch {
     return false;
@@ -2827,6 +3343,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) }))
 );