@graphit/cli 0.1.51 → 0.1.107

package/hooks/hooks.json

@@ -26,6 +26,19 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/block-legacy-setup.mjs", "--hook", "PreToolUse"],
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Bash",

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@graphit/cli",
-  "version": "0.1.51",
+  "version": "0.1.107",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omry-graphit/graphit.git",
+    "directory": "cli"
+  },
   "type": "module",
   "bin": {
     "graphit": "./dist/index.js"
@@ -10,15 +15,18 @@
     "build": "npm run sync:version && tsc",
     "dev": "tsx src/index.ts",
     "lint": "npm run check:version && tsc --noEmit",
-    "test": "npm run build && node --test test/*.test.mjs",
+    "test": "npm run build && node scripts/generate-commands-doc.mjs --check && node --test test/*.test.mjs",
     "sync:version": "node scripts/sync-plugin-version.mjs",
-    "check:version": "node scripts/sync-plugin-version.mjs --check"
+    "check:version": "node scripts/sync-plugin-version.mjs --check",
+    "gen:commands": "node scripts/generate-commands-doc.mjs",
+    "check:commands": "node scripts/generate-commands-doc.mjs --check"
   },
   "engines": {
     "node": ">=18"
   },
   "files": [
     "dist",
+    "bin",
     "skills",
     "hooks",
     "scripts",

package/scripts/block-legacy-setup.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// PreToolUse(Bash) hook: block re-introducing a legacy copied install of the
+// Graphit skill (`graphit setup ... --legacy-copy`) for Claude Code or Codex
+// while the plugin bundle is the active source. The plugin bundle is the single
+// source of truth on those two platforms; a copied snapshot drifts and shadows
+// it, which is exactly the failure mode `graphit setup --remove-legacy-copies`
+// exists to undo. When the about-to-run Bash command matches, this prints a
+// remediation message and exits 2 (block). Every other command exits 0 (allow).
+//
+// Claude-Code-only progressive enhancement: Codex has no hook system, so this
+// invariant is restated as prose in the skill rather than enforced there. The
+// hook is purely additive - on the platforms that lack it, nothing changes.
+//
+// Defensive by contract: malformed input, a missing field, or any thrown error
+// resolves to exit 0 (allow). The hook must never block an unrelated command or
+// crash the agent's Bash flow on a parse error.
+
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Mirrors the plugin-root resolution used by plugin-status.mjs so the script is
+// portable across the Claude Code / Codex / standalone env layouts. Unused for
+// the block decision today, but kept consistent so future remediation can point
+// at bundle-relative paths without re-deriving the root.
+const pluginRoot =
+  process.env.CLAUDE_PLUGIN_ROOT ??
+  process.env.CODEX_PLUGIN_ROOT ??
+  process.env.GRAPHIT_PLUGIN_ROOT ??
+  dirname(dirname(fileURLToPath(import.meta.url)));
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function tryParseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+// Match `graphit setup` (or local dev `node dist/index.js setup`) combined with
+// the `--legacy-copy` flag, in either order, tolerating env prefixes
+// (GRAPHIT_API_URL=... graphit setup ...). Anchored on both the setup command
+// and the legacy-copy flag so plain `graphit setup` and unrelated commands that
+// merely mention "legacy" are never blocked.
+function isLegacyCopySetup(command) {
+  if (!command) return false;
+  const isSetup = /(?:graphit|index\.js)\s+setup\b/.test(command);
+  const hasLegacyCopyFlag = /--legacy-copy\b/.test(command);
+  return isSetup && hasLegacyCopyFlag;
+}
+
+const REMEDIATION =
+  "[Graphit plugin] Blocked `graphit setup --legacy-copy`. On Claude Code and " +
+  "Codex the Graphit plugin bundle is the active source of truth for the skill; " +
+  "a legacy copied snapshot drifts and shadows it. Do not re-introduce a copied " +
+  "install. If a stale copy is already present, remove it with " +
+  "`graphit setup --remove-legacy-copies` after confirming the plugin is " +
+  "installed. Plugin root: " +
+  pluginRoot;
+
+function main() {
+  const raw = readStdin();
+  if (!raw) return 0;
+
+  const payload = tryParseJson(raw);
+  if (!payload || payload.tool_name !== "Bash") return 0;
+
+  const command = payload.tool_input?.command ?? "";
+  if (!isLegacyCopySetup(command)) return 0;
+
+  process.stderr.write(`${REMEDIATION}\n`);
+  return 2;
+}
+
+let exitCode = 0;
+try {
+  exitCode = main();
+} catch {
+  // Never block an unrelated command or crash the agent's Bash flow on error.
+  exitCode = 0;
+}
+process.exit(exitCode);

package/scripts/generate-commands-doc.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// Generates the command reference injected into cli/skills/graphit/SKILL.md
+// between the COMMANDS:START / COMMANDS:END markers, from Commander metadata.
+// The CLI is the single source of truth - this never hand-maintains command facts.
+//
+//   node scripts/generate-commands-doc.mjs            # write the table into SKILL.md
+//   node scripts/generate-commands-doc.mjs --check    # exit 1 if SKILL.md is stale (CI gate)
+//   node scripts/generate-commands-doc.mjs --stdout    # print the block only (debug)
+//
+// Requires a prior `npm run build` (it imports the compiled registrars from dist/).
+
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Command } from "commander";
+
+const checkOnly = process.argv.includes("--check");
+const toStdout = process.argv.includes("--stdout");
+
+const cliRoot =
+  process.env.GRAPHIT_CLI_ROOT ??
+  join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const distCommandsDir = join(cliRoot, "dist", "commands");
+const skillPath = join(cliRoot, "skills", "graphit", "SKILL.md");
+
+const START = "<!-- COMMANDS:START -->";
+const END = "<!-- COMMANDS:END -->";
+
+// Mirrors index.ts registration order; groups not listed are appended alphabetically.
+const GROUP_ORDER = [
+  "auth", "kb", "query", "metadata", "ds", "dashboard",
+  "connector", "governance", "team", "plugin", "setup",
+];
+
+// Assemble a throwaway program by importing only the dist/ registrars (never
+// dist/index.js - that fires the update banner + program.parse() at load).
+async function buildProgram() {
+  if (!existsSync(distCommandsDir)) {
+    throw new Error(
+      `dist/commands not found at ${distCommandsDir} - run "npm run build" first`,
+    );
+  }
+  const program = new Command();
+  program.name("graphit");
+  const files = readdirSync(distCommandsDir)
+    .filter((f) => f.endsWith(".js"))
+    .sort(); // deterministic import order
+  for (const file of files) {
+    const mod = await import(pathToFileURL(join(distCommandsDir, file)).href);
+    for (const [name, value] of Object.entries(mod)) {
+      if (typeof value === "function" && /^register/.test(name)) {
+        value(program);
+      }
+    }
+  }
+  return program;
+}
+
+function esc(text) {
+  return String(text ?? "").replace(/\r?\n/g, " ").replace(/\|/g, "\\|").trim();
+}
+
+function formatArgs(cmd) {
+  return (cmd.registeredArguments ?? [])
+    .map((arg) => {
+      const name = arg.name() + (arg.variadic ? "..." : "");
+      return arg.required ? `<${name}>` : `[${name}]`;
+    })
+    .join(" ");
+}
+
+function formatFlags(cmd) {
+  return (cmd.options ?? [])
+    .map((opt) => opt.long ?? opt.flags)
+    .filter(Boolean)
+    .join(" ");
+}
+
+// A command earns its own row if it is a leaf OR it has its own args/options
+// (e.g. `query <sql>` both takes an arg and has the `metadata` sibling group).
+function hasOwnInvocation(cmd) {
+  return (
+    (cmd.registeredArguments ?? []).length > 0 ||
+    (cmd.options ?? []).length > 0
+  );
+}
+
+function collectRows(cmd, path, rows) {
+  const subs = cmd.commands ?? [];
+  if (subs.length === 0 || hasOwnInvocation(cmd)) {
+    rows.push({
+      command: `${path}${formatArgs(cmd) ? ` ${formatArgs(cmd)}` : ""}`,
+      description: cmd.description(),
+      flags: formatFlags(cmd),
+    });
+  }
+  for (const sub of subs) {
+    collectRows(sub, `${path} ${sub.name()}`.trim(), rows);
+  }
+}
+
+function orderGroups(names) {
+  return [...names].sort((a, b) => {
+    const ia = GROUP_ORDER.indexOf(a);
+    const ib = GROUP_ORDER.indexOf(b);
+    if (ia === -1 && ib === -1) return a.localeCompare(b);
+    if (ia === -1) return 1;
+    if (ib === -1) return -1;
+    return ia - ib;
+  });
+}
+
+function renderBlock(program) {
+  const groups = new Map();
+  for (const top of program.commands) {
+    const rows = [];
+    collectRows(top, top.name(), rows);
+    groups.set(top.name(), { description: top.description(), rows });
+  }
+  const lines = [
+    "",
+    "_Generated from the CLI by `npm run gen:commands` - do not hand-edit between the markers. Run `graphit <cmd> --help` for exact flag values and descriptions._",
+    "",
+  ];
+  for (const name of orderGroups(groups.keys())) {
+    const { description, rows } = groups.get(name);
+    lines.push(`**${name}**${description ? ` - ${esc(description)}` : ""}`);
+    for (const row of rows) {
+      const parts = [`- \`${row.command}\``];
+      if (row.description) parts.push(esc(row.description));
+      if (row.flags) parts.push(`\`${row.flags}\``);
+      lines.push(parts.join(" - "));
+    }
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function injectBetweenMarkers(content, block) {
+  const start = content.indexOf(START);
+  const end = content.indexOf(END);
+  if (start === -1 || end === -1) {
+    throw new Error(
+      `Missing ${START} / ${END} markers in ${skillPath} - add them before generating.`,
+    );
+  }
+  if (end < start) {
+    throw new Error(`${END} appears before ${START} in ${skillPath}`);
+  }
+  const before = content.slice(0, start + START.length);
+  const after = content.slice(end);
+  return `${before}\n${block}\n${after}`;
+}
+
+const program = await buildProgram();
+const block = renderBlock(program);
+
+if (toStdout) {
+  process.stdout.write(block);
+  process.exit(0);
+}
+
+// Normalize CRLF before compare so Windows checkouts don't report perpetual drift.
+const current = existsSync(skillPath)
+  ? readFileSync(skillPath, "utf-8").replace(/\r\n/g, "\n")
+  : "";
+const next = injectBetweenMarkers(current, block);
+
+if (current === next) {
+  console.error("Command table in SKILL.md is in sync.");
+  process.exit(0);
+}
+
+if (checkOnly) {
+  console.error(
+    "SKILL.md command table is stale - run: npm run gen:commands",
+  );
+  process.exit(1);
+}
+
+writeFileSync(skillPath, next, "utf-8");
+console.error(`Updated command table in ${skillPath}`);

package/scripts/plugin-status.mjs

@@ -1,12 +1,23 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const REGISTRY_URL = "https://registry.npmjs.org/@graphit/cli/latest";
-const TTL_MS = 24 * 60 * 60 * 1000;
+// Project #246: GRAPHIT_REGISTRY_URL lets tests point at a local server and
+// supports private/enterprise registries; defaults to the public npm registry.
+const REGISTRY_URL =
+  process.env.GRAPHIT_REGISTRY_URL ?? "https://registry.npmjs.org/@graphit/cli/latest";
+const PACKAGE_NAME = "@graphit/cli";
+// Project #246: ~4h TTL (was 24h) so a single-source bump reaches returning
+// sessions within one window (ARCH-2, PERF-2).
+const TTL_MS = 4 * 60 * 60 * 1000;
+// Project #246: version-cache schema. Bump when the cache shape changes; older
+// caches are then treated as a miss and refetched (self-healing).
+const CACHE_SCHEMA_VERSION = 1;
+// Strict semver. The wrapper enforces the same shape (SEC-6); keep them in sync.
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const args = new Set(process.argv.slice(2));
 const hookIndex = process.argv.indexOf("--hook");
 const hookEvent = hookIndex >= 0 ? process.argv[hookIndex + 1] : null;
@@ -15,11 +26,12 @@ const pluginRoot =
   process.env.CODEX_PLUGIN_ROOT ??
   process.env.GRAPHIT_PLUGIN_ROOT ??
   dirname(dirname(fileURLToPath(import.meta.url)));
-const cacheRoot =
-  process.env.CLAUDE_PLUGIN_DATA ??
-  process.env.CODEX_PLUGIN_DATA ??
-  process.env.GRAPHIT_PLUGIN_DATA ??
-  join(homedir(), ".graphit");
+// Project #246: the version cache must be shared between this SessionStart hook
+// and the bin/graphit wrapper (agent Bash tool). CLAUDE_PLUGIN_DATA is set
+// per-plugin/per-context by Claude Code and is NOT guaranteed identical across
+// those two contexts, so it is intentionally excluded here - a fixed, graphit-
+// owned dir guarantees both sides agree. GRAPHIT_PLUGIN_DATA overrides.
+const cacheRoot = process.env.GRAPHIT_PLUGIN_DATA ?? join(homedir(), ".graphit");
 
 function readJson(path) {
   return JSON.parse(readFileSync(path, "utf-8"));
@@ -89,34 +101,128 @@ function readCache(path) {
   }
 }
 
-function writeCache(path, entry) {
+function isStrictSemver(value) {
+  return typeof value === "string" && SEMVER_RE.test(value);
+}
+
+// SEC-6: the cache file is user-writable. Treat it as untrusted - require the
+// expected schema version, package name, a strict-semver version, and a numeric
+// timestamp. Anything else is treated as a miss (refetch / fall back).
+function isValidVersionCache(cache) {
+  return (
+    !!cache &&
+    cache.schemaVersion === CACHE_SCHEMA_VERSION &&
+    cache.packageName === PACKAGE_NAME &&
+    isStrictSemver(cache.latestVersion) &&
+    typeof cache.checkedAt === "number"
+  );
+}
+
+// SEC-4: atomic write (tmp + rename) so concurrent SessionStart writers can never
+// leave a torn/partial file for the wrapper or a later read.
+function atomicWriteJson(path, obj) {
+  const tmpPath = `${path}.${process.pid}.tmp`;
   try {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(entry), "utf-8");
+    writeFileSync(tmpPath, JSON.stringify(obj), "utf-8");
+    renameSync(tmpPath, path);
+  } catch {
+    // Writes here must never break startup hooks; clean up any temp file.
+    try {
+      rmSync(tmpPath, { force: true });
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function writeCache(path, latestVersion) {
+  atomicWriteJson(path, {
+    schemaVersion: CACHE_SCHEMA_VERSION,
+    packageName: PACKAGE_NAME,
+    latestVersion,
+    checkedAt: Date.now(),
+  });
+}
+
+function realpathSafe(path) {
+  try {
+    return realpathSync(path);
   } catch {
-    // Cache writes should never break startup hooks.
+    return path;
   }
 }
 
+// 4.1 (SEC-5): find a `graphit` on PATH that is NOT this plugin's bundled wrapper -
+// i.e. a legacy global @graphit/cli install. Because plugin executables are
+// appended to PATH (Phase 2 finding), any global install shadows the wrapper, so
+// its mere presence is the migration trigger. Returns the first such path or null.
+function detectForeignGraphit() {
+  const pathValue = process.env.PATH ?? "";
+  if (!pathValue) return null;
+  const names = process.platform === "win32" ? ["graphit.cmd", "graphit.ps1", "graphit"] : ["graphit"];
+  // On Windows the plugin ships graphit.cmd / graphit.ps1 alongside the POSIX
+  // `graphit`, so excluding only `bin/graphit` would leave our own .cmd/.ps1
+  // wrappers looking like a foreign global. Exclude every bundled wrapper name.
+  const ownWrapperReals = new Set(
+    names.map((name) => realpathSafe(join(pluginRoot, "bin", name))),
+  );
+  for (const dir of pathValue.split(delimiter).filter(Boolean)) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (!existsSync(candidate)) continue;
+      const real = realpathSafe(candidate);
+      if (ownWrapperReals.has(real)) continue; // our own bundled wrapper
+      if (/[/\\]plugins[/\\]/.test(real)) continue; // a plugin-cache wrapper
+      return candidate;
+    }
+  }
+  return null;
+}
+
+// Nudge throttle (US-3.2 / US-4.1: ~once/day). State is graphit-owned and atomic.
+const NUDGE_TTL_MS = 24 * 60 * 60 * 1000;
+const nudgeStatePath = join(cacheRoot, "nudge-state.json");
+
+function readNudgeState() {
+  const state = tryReadJson(nudgeStatePath);
+  if (state && state.schemaVersion === CACHE_SCHEMA_VERSION && state.nudges && typeof state.nudges === "object") {
+    return state;
+  }
+  return { schemaVersion: CACHE_SCHEMA_VERSION, nudges: {} };
+}
+
+function nudgeAllowed(state, key) {
+  const last = state.nudges[key];
+  return typeof last !== "number" || Date.now() - last >= NUDGE_TTL_MS;
+}
+
+function persistNudges(state, keys) {
+  if (keys.length === 0) return;
+  for (const key of keys) state.nudges[key] = Date.now();
+  atomicWriteJson(nudgeStatePath, state);
+}
+
 async function getLatestVersion(currentVersion) {
   if (args.has("--skip-network")) return null;
 
   const cachePath = join(cacheRoot, "plugin-status.json");
   const cache = readCache(cachePath);
-  if (cache?.latestVersion && Date.now() - cache.checkedAt < TTL_MS) {
-    return cache.latestVersion;
+  const cachedVersion = isValidVersionCache(cache) ? cache.latestVersion : null;
+  if (cachedVersion && Date.now() - cache.checkedAt < TTL_MS) {
+    return cachedVersion;
   }
 
   try {
     const response = await fetch(REGISTRY_URL, { signal: AbortSignal.timeout(1500) });
-    if (!response.ok) return cache?.latestVersion ?? null;
+    if (!response.ok) return cachedVersion;
     const data = await response.json();
-    if (data && typeof data.version === "string") {
-      writeCache(cachePath, { latestVersion: data.version, checkedAt: Date.now() });
+    if (data && isStrictSemver(data.version)) {
+      writeCache(cachePath, data.version);
       return data.version;
     }
   } catch {
-    return cache?.latestVersion ?? null;
+    return cachedVersion;
   }
 
   return currentVersion;
@@ -165,7 +271,9 @@ async function collectStatus() {
     [".claude-plugin/marketplace.json plugin", marketplacePlugin?.version],
     ["skills/graphit/VERSION.json", tryReadJson(join(pluginRoot, "skills", "graphit", "VERSION.json"))?.version],
     ["skills/graphit/SKILL.md", readFrontmatterVersion(join(pluginRoot, "skills", "graphit", "SKILL.md"))],
-    ["skills/graphit/graphit.mdc", readFrontmatterVersion(join(pluginRoot, "skills", "graphit", "graphit.mdc"))],
+    // The Cursor source file (skills/graphit/graphit.mdc) is frozen and no longer
+    // version-stamped, so it is intentionally excluded here. The copied-Cursor-home
+    // staleness checks below still run for existing Cursor users.
   ];
 
   for (const [label, version] of versionChecks) {
@@ -204,7 +312,7 @@ async function collectStatus() {
     findings.push({
       type: "package-update",
       message: `@graphit/cli update available: ${currentVersion} -> ${latestVersion}`,
-      remediation: "Update Graphit through your assistant's plugin manager. Claude Code users can run `claude plugin update graphit`; Codex plugin users should use the Codex plugin update command. Standalone npm users can run `npm update -g @graphit/cli`.",
+      remediation: "This update is for the npm CLI binary (@graphit/cli), a separate artifact from the skill bundle. Update the binary with `npm install -g @graphit/cli@latest` (not `npm update -g`, which respects the original semver range and can miss the latest). If `graphit` resolves to a custom npm prefix (compare `command -v graphit` with `npm prefix -g`), reinstall to that prefix with `npm install -g @graphit/cli@latest --prefix <dir>` (<dir> = the parent of the bin dir holding graphit). The Claude Code/Codex skill bundle updates separately via `claude plugin update graphit@graphit-plugin` and does NOT update the binary.",
     });
   }
 
@@ -251,13 +359,54 @@ function formatPlain(status) {
   ].join("\n");
 }
 
-function formatHookContext(status) {
-  if (status.findings.length === 0) return null;
+// Build the SessionStart agent nudges. Unlike --json (full diagnostics), the hook
+// surfaces only user-actionable, throttled items: the migration nudge (4.1), the
+// thin-layer /plugin update nudge (4.3), and legacy copied-skill cleanup. It does
+// NOT emit founder-only publish drift, nor the npm-install-g binary message - under
+// the plugin model the binary auto-updates via npx, so the bundle nudge is correct.
+function buildHookNudges(status) {
+  const state = readNudgeState();
+  const lines = [];
+  const shown = [];
+
+  // 4.1 Migration: a global @graphit/cli shadows the plugin's npx-backed wrapper.
+  const foreignGraphit = detectForeignGraphit();
+  if (foreignGraphit && nudgeAllowed(state, "legacy-global")) {
+    lines.push(
+      `- A legacy global \`graphit\` (@graphit/cli) at ${foreignGraphit} shadows the plugin's bundled CLI ` +
+        "(plugin executables are appended to PATH, so a global install wins). The plugin now delivers the CLI " +
+        "automatically via npx - tell the user once and offer to run `npm uninstall -g @graphit/cli` so it takes over.",
+    );
+    shown.push("legacy-global");
+  }
 
-  return [
-    "Graphit plugin status check found actionable update/version information.",
-    ...status.findings.map((finding) => `- ${finding.message}. ${finding.remediation}`),
-  ].join("\n");
+  // 4.3 Thin-layer: the plugin bundle is behind npm latest (the binary itself
+  // auto-updates via npx; only the skill/hook/wrapper bundle needs a manual update).
+  if (
+    status.latestVersion &&
+    compareVersions(status.latestVersion, status.currentVersion) > 0 &&
+    nudgeAllowed(state, "plugin-update")
+  ) {
+    lines.push(
+      `- A newer Graphit plugin is available (${status.currentVersion} -> ${status.latestVersion}). ` +
+        "Tell the user once to update the bundle with `/plugin update graphit@graphit-plugin`; " +
+        "the CLI binary itself updates automatically.",
+    );
+    shown.push("plugin-update");
+  }
+
+  // Legacy copied skill snapshots are real user-side issues - surface until removed.
+  for (const finding of status.findings) {
+    if (finding.type === "legacy-copied-skill-present" || finding.type === "copied-skill-stale") {
+      lines.push(`- ${finding.message}. ${finding.remediation}`);
+    }
+  }
+
+  if (lines.length === 0) return null;
+  return {
+    context: ["Graphit plugin status check found actionable update/version information.", ...lines].join("\n"),
+    persist: () => persistNudges(state, shown),
+  };
 }
 
 if (hookEvent && !shouldRunForPrompt()) {
@@ -269,14 +418,15 @@ const status = await collectStatus();
 if (args.has("--json")) {
   console.log(JSON.stringify(status, null, 2));
 } else if (hookEvent) {
-  const additionalContext = formatHookContext(status);
-  if (additionalContext) {
+  const nudge = buildHookNudges(status);
+  if (nudge) {
     console.log(JSON.stringify({
       hookSpecificOutput: {
         hookEventName: hookEvent,
-        additionalContext,
+        additionalContext: nudge.context,
       },
     }));
+    nudge.persist();
   }
 } else if (!args.has("--quiet") || status.findings.length > 0) {
   console.log(formatPlain(status));

package/scripts/sync-plugin-version.mjs

@@ -88,9 +88,29 @@ function updateVersionJson(path, packageName, version, changes) {
   );
 }
 
-function updateFrontmatterVersion(path, version, changes) {
+// Project #246: stamp BOTH the frontmatter skill_version AND the Codex-facing npx
+// invocation version (the concrete `npx -y @graphit/cli@<v>` form in the body) so
+// check:version fails if either drifts from package.json. Non-CC surfaces (Codex,
+// Cursor, terminal, CI) have no resolver hook, so the skill hands them a stamped
+// concrete version, not a placeholder; `@<exact>` placeholders are left untouched.
+function updateSkillFile(path, version, packageName, changes) {
   const content = readFileSync(path, "utf-8");
-  writeOrReport(path, upsertFrontmatterField(content, "skill_version", version), changes);
+  const stamped = upsertFrontmatterField(content, "skill_version", version);
+  const escapedPkg = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const npxVersionRe = new RegExp(`${escapedPkg}@\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?`, "g");
+  writeOrReport(path, stamped.replace(npxVersionRe, `${packageName}@${version}`), changes);
+}
+
+// Project #246: stamp the baked floor version into the bin/graphit wrapper(s) so
+// first-run/offline falls back to a real published version. Matches the bash
+// `FLOOR_VERSION="x"` and PowerShell `$FloorVersion = "x"` markers.
+function updateWrapperFloor(path, version, changes) {
+  if (!existsSync(path)) return;
+  const content = readFileSync(path, "utf-8");
+  const next = content
+    .replace(/^FLOOR_VERSION=".*"$/m, () => `FLOOR_VERSION="${version}"`)
+    .replace(/^\$FloorVersion = ".*"$/m, () => `$FloorVersion = "${version}"`);
+  writeOrReport(path, next, changes);
 }
 
 const packageJson = readJson(join(cliRoot, "package.json"));
@@ -102,8 +122,10 @@ updatePluginManifest(join(cliRoot, ".claude-plugin", "plugin.json"), version, ch
 updatePluginManifest(join(cliRoot, ".codex-plugin", "plugin.json"), version, changes);
 updateMarketplace(join(cliRoot, ".claude-plugin", "marketplace.json"), version, packageName, changes);
 updateVersionJson(join(cliRoot, "skills", "graphit", "VERSION.json"), packageName, version, changes);
-updateFrontmatterVersion(join(cliRoot, "skills", "graphit", "SKILL.md"), version, changes);
-updateFrontmatterVersion(join(cliRoot, "skills", "graphit", "graphit.mdc"), version, changes);
+updateSkillFile(join(cliRoot, "skills", "graphit", "SKILL.md"), version, packageName, changes);
+// graphit.mdc is the frozen Cursor mirror and is no longer stamped (Cursor unmaintained for Claude Code + Codex).
+updateWrapperFloor(join(cliRoot, "bin", "graphit"), version, changes);
+updateWrapperFloor(join(cliRoot, "bin", "graphit.ps1"), version, changes);
 
 if (changes.length > 0) {
   const rel = (path) => path.startsWith(`${cliRoot}/`) ? path.slice(cliRoot.length + 1) : path;