@tricknowtech/context 0.1.1 → 0.3.0

package/dist/cli.cjs

@@ -36,16 +36,17 @@ __export(cli_exports, {
 module.exports = __toCommonJS(cli_exports);
 
 // src/commands.ts
-var import_node_fs7 = __toESM(require("fs"), 1);
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_child_process2 = require("child_process");
+var import_node_fs8 = __toESM(require("fs"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
 
 // src/collector.ts
-var import_node_fs3 = __toESM(require("fs"), 1);
-var import_node_path3 = __toESM(require("path"), 1);
+var import_node_fs4 = __toESM(require("fs"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 
-// src/config.ts
-var import_node_crypto = __toESM(require("crypto"), 1);
+// src/assistants.ts
 var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_os2 = __toESM(require("os"), 1);
 var import_node_path2 = __toESM(require("path"), 1);
 
 // src/fsutil.ts
@@ -62,8 +63,9 @@ function cwdKey(absPath) {
 function makeTemplate(absPath, ctx) {
   const candidates = [
     [ctx.userClaude, "{userClaude}"],
-    [ctx.project, "{project}"]
-  ].sort((a, b) => b[0].length - a[0].length);
+    [ctx.project, "{project}"],
+    [ctx.home, "{home}"]
+  ].filter(([root]) => Boolean(root)).sort((a, b) => b[0].length - a[0].length);
   let out2 = absPath;
   for (const [root, token] of candidates) {
     if (absPath === root || absPath.startsWith(root + import_node_path.default.sep)) {
@@ -74,7 +76,7 @@ function makeTemplate(absPath, ctx) {
   return ctx.cwdKey ? out2.split(ctx.cwdKey).join("{cwdKey}") : out2;
 }
 function resolveTemplate(template, ctx) {
-  const expanded = template.split("{userClaude}").join(ctx.userClaude).split("{project}").join(ctx.project).split("{cwdKey}").join(ctx.cwdKey);
+  const expanded = template.split("{userClaude}").join(ctx.userClaude).split("{project}").join(ctx.project).split("{home}").join(ctx.home).split("{cwdKey}").join(ctx.cwdKey);
   return import_node_path.default.normalize(expanded);
 }
 function toPosix(p) {
@@ -196,7 +198,176 @@ function formatBytes(n) {
   return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
 }
 
+// src/assistants.ts
+function filesIn(dir, exclude, prefix) {
+  return walk(dir, { exclude }).map((abs) => ({
+    abs,
+    rel: `${prefix}/${toPosix(import_node_path2.default.relative(dir, abs))}`
+  }));
+}
+function fileIfExists(abs, rel) {
+  return import_node_fs2.default.existsSync(abs) ? [{ abs, rel }] : [];
+}
+function planStem(fileName) {
+  return fileName.replace(/\.md$/, "").replace(/-agent-[0-9a-f]+$/i, "");
+}
+function relatedByProject(dir, projectRoot, exclude) {
+  const all = walk(dir, { exclude });
+  if (all.length === 0) return [];
+  const projectName = import_node_path2.default.basename(projectRoot);
+  const related = /* @__PURE__ */ new Set();
+  const stems = /* @__PURE__ */ new Set();
+  for (const abs of all) {
+    let text = "";
+    try {
+      text = import_node_fs2.default.readFileSync(abs, "utf8");
+    } catch {
+      continue;
+    }
+    if (text.includes(projectRoot) || text.includes(projectName)) {
+      related.add(abs);
+      stems.add(planStem(import_node_path2.default.basename(abs)));
+    }
+  }
+  for (const abs of all) {
+    if (stems.has(planStem(import_node_path2.default.basename(abs)))) related.add(abs);
+  }
+  return [...related];
+}
+var ADAPTERS = [
+  {
+    id: "claude",
+    name: "Claude Code",
+    projectGlobs: [
+      "CLAUDE.md",
+      "CLAUDE.local.md",
+      "**/CLAUDE.md",
+      ".claude/settings.json",
+      ".claude/settings.local.json",
+      ".claude/memory/",
+      ".claude/plans/",
+      ".claude/commands/",
+      ".claude/agents/",
+      ".claude/skills/"
+    ],
+    userDir: () => userClaudeDir(),
+    collectUser: (projectRoot, _home, exclude) => {
+      const root = userClaudeDir();
+      const out2 = [];
+      const key = cwdKey(projectRoot);
+      const projectsDir = import_node_path2.default.join(root, "projects");
+      let keys = [];
+      try {
+        keys = import_node_fs2.default.readdirSync(projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && (d.name === key || d.name.startsWith(key + "-"))).map((d) => d.name);
+      } catch {
+        keys = [];
+      }
+      for (const k of keys) {
+        const memDir = import_node_path2.default.join(projectsDir, k, "memory");
+        const prefix = k === key ? "memory" : `memory-sub/${k.slice(key.length + 1)}`;
+        out2.push(...filesIn(memDir, exclude, prefix));
+      }
+      out2.push(...filesIn(import_node_path2.default.join(root, "skills"), exclude, "skills"));
+      out2.push(...filesIn(import_node_path2.default.join(root, "agents"), exclude, "agents"));
+      for (const abs of relatedByProject(import_node_path2.default.join(root, "plans"), projectRoot, exclude)) {
+        out2.push({ abs, rel: `plans/${import_node_path2.default.basename(abs)}` });
+      }
+      out2.push(...fileIfExists(import_node_path2.default.join(root, "CLAUDE.md"), "user/CLAUDE.md"));
+      out2.push(...fileIfExists(import_node_path2.default.join(root, "settings.json"), "user/settings.json"));
+      return out2;
+    }
+  },
+  {
+    id: "codex",
+    name: "OpenAI Codex",
+    projectGlobs: ["AGENTS.md", "**/AGENTS.md", ".codex/"],
+    userDir: (home) => import_node_path2.default.join(home, ".codex"),
+    collectUser: (projectRoot, home, exclude) => {
+      const root = import_node_path2.default.join(home, ".codex");
+      const out2 = [];
+      out2.push(...fileIfExists(import_node_path2.default.join(root, "AGENTS.md"), "user/AGENTS.md"));
+      out2.push(...fileIfExists(import_node_path2.default.join(root, "config.toml"), "user/config.toml"));
+      out2.push(...filesIn(import_node_path2.default.join(root, "prompts"), exclude, "prompts"));
+      return out2;
+    }
+  },
+  {
+    id: "cursor",
+    name: "Cursor",
+    // `.cursorrules` is the legacy single-file form; `.cursor/rules/*.mdc` is current.
+    projectGlobs: [".cursorrules", ".cursor/rules/", ".cursor/"],
+    userDir: (home) => import_node_path2.default.join(home, ".cursor"),
+    collectUser: (_projectRoot, home, exclude) => filesIn(import_node_path2.default.join(home, ".cursor", "rules"), exclude, "rules")
+  },
+  {
+    id: "copilot",
+    name: "GitHub Copilot",
+    projectGlobs: [
+      ".github/copilot-instructions.md",
+      ".github/instructions/",
+      ".github/prompts/"
+    ]
+  },
+  {
+    id: "windsurf",
+    name: "Windsurf",
+    projectGlobs: [".windsurfrules", ".windsurf/rules/", ".windsurf/"],
+    userDir: (home) => import_node_path2.default.join(home, ".windsurf")
+  },
+  {
+    id: "gemini",
+    name: "Gemini CLI",
+    projectGlobs: ["GEMINI.md", "**/GEMINI.md", ".gemini/"],
+    userDir: (home) => import_node_path2.default.join(home, ".gemini"),
+    collectUser: (_projectRoot, home, exclude) => {
+      const root = import_node_path2.default.join(home, ".gemini");
+      const out2 = [];
+      out2.push(...fileIfExists(import_node_path2.default.join(root, "GEMINI.md"), "user/GEMINI.md"));
+      out2.push(...fileIfExists(import_node_path2.default.join(root, "settings.json"), "user/settings.json"));
+      out2.push(...filesIn(import_node_path2.default.join(root, "commands"), exclude, "commands"));
+      return out2;
+    }
+  },
+  {
+    id: "cline",
+    name: "Cline",
+    projectGlobs: [".clinerules", ".clinerules/"]
+  },
+  {
+    id: "aider",
+    name: "Aider",
+    projectGlobs: ["CONVENTIONS.md", ".aider.conf.yml", ".aider.conf.yaml"]
+  },
+  {
+    id: "continue",
+    name: "Continue",
+    projectGlobs: [".continue/", ".continuerules"],
+    userDir: (home) => import_node_path2.default.join(home, ".continue")
+  }
+];
+function adapterById(id) {
+  return ADAPTERS.find((a) => a.id === id);
+}
+function homeDir() {
+  return import_node_os2.default.homedir();
+}
+function detectAssistants(projectRoot, projectFiles) {
+  const home = homeDir();
+  return ADAPTERS.filter((a) => {
+    if (a.userDir) {
+      try {
+        if (import_node_fs2.default.existsSync(a.userDir(home))) return true;
+      } catch {
+      }
+    }
+    return projectFiles.some((rel) => matchesAny(rel, a.projectGlobs));
+  });
+}
+
 // src/config.ts
+var import_node_crypto = __toESM(require("crypto"), 1);
+var import_node_fs3 = __toESM(require("fs"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 var STORE_DIR = ".contextsync";
 var CONFIG_FILE = "config.json";
 var HANDOFF_FILE = "handoff.json";
@@ -225,29 +396,30 @@ var DEFAULT_EXCLUDE = [
 function defaultConfig(projectRoot) {
   return {
     projectId: import_node_crypto.default.randomUUID(),
-    name: import_node_path2.default.basename(projectRoot),
+    name: import_node_path3.default.basename(projectRoot),
     rootHint: projectRoot,
     tiers: ["core", "handoff"],
+    assistants: ["auto"],
     artifactPaths: ["graphify-out"],
     exclude: [...DEFAULT_EXCLUDE],
     remotes: {}
   };
 }
 function findProjectRoot(start = process.cwd()) {
-  let dir = import_node_path2.default.resolve(start);
+  let dir = import_node_path3.default.resolve(start);
   for (; ; ) {
-    if (import_node_fs2.default.existsSync(import_node_path2.default.join(dir, STORE_DIR, CONFIG_FILE))) return dir;
-    if (import_node_fs2.default.existsSync(import_node_path2.default.join(dir, ".git"))) return dir;
-    const parent = import_node_path2.default.dirname(dir);
+    if (import_node_fs3.default.existsSync(import_node_path3.default.join(dir, STORE_DIR, CONFIG_FILE))) return dir;
+    if (import_node_fs3.default.existsSync(import_node_path3.default.join(dir, ".git"))) return dir;
+    const parent = import_node_path3.default.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
 function storeDir(projectRoot) {
-  return import_node_path2.default.join(projectRoot, STORE_DIR);
+  return import_node_path3.default.join(projectRoot, STORE_DIR);
 }
 function configPath(projectRoot) {
-  return import_node_path2.default.join(storeDir(projectRoot), CONFIG_FILE);
+  return import_node_path3.default.join(storeDir(projectRoot), CONFIG_FILE);
 }
 function loadConfig(projectRoot) {
   const cfg = readJson(configPath(projectRoot));
@@ -256,7 +428,9 @@ function loadConfig(projectRoot) {
     ...defaultConfig(projectRoot),
     ...cfg,
     remotes: cfg.remotes ?? {},
-    tiers: cfg.tiers ?? ["core", "handoff"]
+    tiers: cfg.tiers ?? ["core", "handoff"],
+    // Stores written before multi-assistant support have no `assistants` key.
+    assistants: cfg.assistants ?? ["auto"]
   };
 }
 function saveConfig(projectRoot, cfg) {
@@ -264,54 +438,12 @@ function saveConfig(projectRoot, cfg) {
 }
 
 // src/collector.ts
-var PROJECT_CONTEXT_GLOBS = [
-  "CLAUDE.md",
-  "CLAUDE.local.md",
-  "AGENTS.md",
-  "**/CLAUDE.md",
-  "**/AGENTS.md",
-  ".cursorrules",
-  ".github/copilot-instructions.md",
-  ".claude/settings.json",
-  // `.local.json` variants are gitignored by default, so nothing else carries
-  // them — which makes them exactly the kind of file this tool exists for.
-  ".claude/settings.local.json",
-  ".claude/memory/",
-  ".claude/plans/",
-  ".claude/commands/",
-  ".claude/agents/",
-  ".claude/skills/"
-];
-function planStem(fileName) {
-  return fileName.replace(/\.md$/, "").replace(/-agent-[0-9a-f]+$/i, "");
-}
-function collectPlans(plansDir, projectRoot, exclude) {
-  const all = walk(plansDir, { exclude });
-  if (all.length === 0) return [];
-  const projectName = import_node_path3.default.basename(projectRoot);
-  const related = /* @__PURE__ */ new Set();
-  const stems = /* @__PURE__ */ new Set();
-  for (const abs of all) {
-    let text = "";
-    try {
-      text = import_node_fs3.default.readFileSync(abs, "utf8");
-    } catch {
-      continue;
-    }
-    if (text.includes(projectRoot) || text.includes(projectName)) {
-      related.add(abs);
-      stems.add(planStem(import_node_path3.default.basename(abs)));
-    }
-  }
-  for (const abs of all) {
-    if (stems.has(planStem(import_node_path3.default.basename(abs)))) related.add(abs);
-  }
-  return [...related];
-}
 function push(out2, sourcePath, storePath, tier, sourceRoot, ctx) {
   let size = 0;
   try {
-    size = import_node_fs3.default.statSync(sourcePath).size;
+    const st = import_node_fs4.default.statSync(sourcePath);
+    if (!st.isFile()) return;
+    size = st.size;
   } catch {
     return;
   }
@@ -324,76 +456,66 @@ function push(out2, sourcePath, storePath, tier, sourceRoot, ctx) {
     restoreTemplate: makeTemplate(sourcePath, ctx)
   });
 }
+function templateContextFor(projectRoot) {
+  return {
+    userClaude: userClaudeDir(),
+    project: projectRoot,
+    cwdKey: cwdKey(projectRoot),
+    home: homeDir()
+  };
+}
 function collect(projectRoot, cfg, tiers) {
-  const userClaude = userClaudeDir();
-  const key = cwdKey(projectRoot);
-  const ctx = { userClaude, project: projectRoot, cwdKey: key };
+  const ctx = templateContextFor(projectRoot);
+  const home = ctx.home;
   const files = [];
   const skippedTracked = [];
   const exclude = [...HARD_DENY, ...cfg.exclude];
   const tracked = gitTrackedSet(projectRoot);
+  const projectRel = walk(projectRoot, { exclude }).map((abs) => ({
+    abs,
+    rel: toPosix(import_node_path4.default.relative(projectRoot, abs))
+  }));
+  const configured = cfg.assistants && cfg.assistants.length > 0 && !cfg.assistants.includes("auto");
+  const assistants = configured ? cfg.assistants.map(adapterById).filter(Boolean) : detectAssistants(projectRoot, projectRel.map((p) => p.rel));
   if (tiers.includes("core")) {
-    for (const abs of walk(projectRoot, { exclude })) {
-      const rel = toPosix(import_node_path3.default.relative(projectRoot, abs));
-      if (!matchesAny(rel, PROJECT_CONTEXT_GLOBS)) continue;
-      if (tracked.has(abs)) {
-        skippedTracked.push(rel);
-        continue;
+    const claimed = /* @__PURE__ */ new Set();
+    for (const adapter of assistants) {
+      for (const { abs, rel } of projectRel) {
+        if (claimed.has(rel)) continue;
+        if (!matchesAny(rel, adapter.projectGlobs)) continue;
+        claimed.add(rel);
+        if (tracked.has(abs)) {
+          skippedTracked.push(rel);
+          continue;
+        }
+        push(files, abs, `project/${rel}`, "core", "project", ctx);
       }
-      push(files, abs, `project/${rel}`, "core", "project", ctx);
     }
-    const projectsDir = import_node_path3.default.join(userClaude, "projects");
-    let projectKeys = [];
-    try {
-      projectKeys = import_node_fs3.default.readdirSync(projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && (d.name === key || d.name.startsWith(key + "-"))).map((d) => d.name);
-    } catch {
-      projectKeys = [];
-    }
-    for (const pk of projectKeys) {
-      const memoryDir = import_node_path3.default.join(projectsDir, pk, "memory");
-      for (const abs of walk(memoryDir, { exclude })) {
-        const rel = toPosix(import_node_path3.default.relative(memoryDir, abs));
-        const storePath = pk === key ? `memory/${rel}` : `memory-sub/${pk.slice(key.length + 1)}/${rel}`;
-        push(files, abs, storePath, "core", "user", ctx);
+    for (const adapter of assistants) {
+      if (!adapter.collectUser) continue;
+      for (const { abs, rel } of adapter.collectUser(projectRoot, home, exclude)) {
+        push(files, abs, `assistants/${adapter.id}/${rel}`, "core", "user", ctx);
       }
     }
-    for (const abs of collectPlans(import_node_path3.default.join(userClaude, "plans"), projectRoot, exclude)) {
-      const rel = toPosix(import_node_path3.default.relative(import_node_path3.default.join(userClaude, "plans"), abs));
-      push(files, abs, `plans/${rel}`, "core", "user", ctx);
-    }
-    const skillsDir = import_node_path3.default.join(userClaude, "skills");
-    for (const abs of walk(skillsDir, { exclude })) {
-      const rel = toPosix(import_node_path3.default.relative(skillsDir, abs));
-      push(files, abs, `skills/${rel}`, "core", "user", ctx);
-    }
-    const agentsDir = import_node_path3.default.join(userClaude, "agents");
-    for (const abs of walk(agentsDir, { exclude })) {
-      const rel = toPosix(import_node_path3.default.relative(agentsDir, abs));
-      push(files, abs, `agents/${rel}`, "core", "user", ctx);
-    }
-    for (const name of ["CLAUDE.md", "settings.json"]) {
-      const abs = import_node_path3.default.join(userClaude, name);
-      if (import_node_fs3.default.existsSync(abs)) push(files, abs, `user/${name}`, "core", "user", ctx);
-    }
   }
   if (tiers.includes("artifacts")) {
     for (const relDir of cfg.artifactPaths) {
-      const absDir = import_node_path3.default.join(projectRoot, relDir);
+      const absDir = import_node_path4.default.join(projectRoot, relDir);
       for (const abs of walk(absDir, { exclude })) {
-        const rel = toPosix(import_node_path3.default.relative(absDir, abs));
+        const rel = toPosix(import_node_path4.default.relative(absDir, abs));
         push(files, abs, `artifacts/${relDir}/${rel}`, "artifacts", "project", ctx);
       }
     }
   }
   if (tiers.includes("transcripts")) {
-    const projDir = import_node_path3.default.join(userClaude, "projects", key);
+    const projDir = import_node_path4.default.join(userClaudeDir(), "projects", ctx.cwdKey);
     for (const abs of walk(projDir, { exclude })) {
-      const rel = toPosix(import_node_path3.default.relative(projDir, abs));
+      const rel = toPosix(import_node_path4.default.relative(projDir, abs));
       if (rel.startsWith("memory/")) continue;
-      push(files, abs, `transcripts/${rel}`, "transcripts", "user", ctx);
+      push(files, abs, `transcripts/claude/${rel}`, "transcripts", "user", ctx);
     }
   }
-  return { files, skippedTracked, ctx };
+  return { files, skippedTracked, assistants, ctx };
 }
 function describeExcluded(projectRoot, tiers) {
   const userClaude = userClaudeDir();
@@ -406,15 +528,17 @@ function describeExcluded(projectRoot, tiers) {
       if (filter && !filter(abs)) continue;
       files++;
       try {
-        bytes += import_node_fs3.default.statSync(abs).size;
+        bytes += import_node_fs4.default.statSync(abs).size;
       } catch {
       }
     }
     return { files, bytes };
   };
   if (!tiers.includes("transcripts")) {
-    const projDir = import_node_path3.default.join(userClaude, "projects", key);
-    const m = measure(projDir, (p) => !p.includes(`${import_node_path3.default.sep}memory${import_node_path3.default.sep}`));
+    const m = measure(
+      import_node_path4.default.join(userClaude, "projects", key),
+      (p) => !p.includes(`${import_node_path4.default.sep}memory${import_node_path4.default.sep}`)
+    );
     if (m.files > 0) {
       out2.push({
         label: "session transcripts",
@@ -428,7 +552,7 @@ function describeExcluded(projectRoot, tiers) {
     ["file-history", "edit-undo snapshots", "transient local undo state, not portable context"],
     ["tasks", "task outputs", "session-scoped tool output"]
   ]) {
-    const m = measure(import_node_path3.default.join(userClaude, dir));
+    const m = measure(import_node_path4.default.join(userClaude, dir));
     if (m.files > 0) out2.push({ label, ...m, reason });
   }
   return out2.filter((g) => g.bytes > 0);
@@ -448,9 +572,89 @@ function summarize(files) {
   return out2;
 }
 
+// src/handoff.ts
+function asStringArray(value) {
+  if (value === void 0 || value === null) return [];
+  if (!Array.isArray(value)) return null;
+  if (!value.every((v) => typeof v === "string")) return null;
+  return value;
+}
+function validateHandoff(raw) {
+  const errors = [];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, errors: ["handoff must be a JSON object"] };
+  }
+  const o = raw;
+  const goal = typeof o.goal === "string" ? o.goal.trim() : "";
+  const nextStep = typeof o.nextStep === "string" ? o.nextStep.trim() : "";
+  if (!goal) errors.push("`goal` is required (what the session set out to do)");
+  if (!nextStep) errors.push("`nextStep` is required (the single next action)");
+  const decisions = asStringArray(o.decisions);
+  const openThreads = asStringArray(o.openThreads);
+  const filesTouched = asStringArray(o.filesTouched);
+  if (decisions === null) errors.push("`decisions` must be an array of strings");
+  if (openThreads === null) errors.push("`openThreads` must be an array of strings");
+  if (filesTouched === null) errors.push("`filesTouched` must be an array of strings");
+  let updatedAt = typeof o.updatedAt === "string" ? o.updatedAt : "";
+  if (!updatedAt || Number.isNaN(Date.parse(updatedAt))) updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (errors.length > 0) return { ok: false, errors };
+  return {
+    ok: true,
+    errors: [],
+    handoff: {
+      updatedAt,
+      goal,
+      decisions: decisions ?? [],
+      openThreads: openThreads ?? [],
+      filesTouched: filesTouched ?? [],
+      nextStep,
+      ...typeof o.notes === "string" && o.notes.trim() ? { notes: o.notes.trim() } : {}
+    }
+  };
+}
+function ago(iso) {
+  const ms = Date.now() - Date.parse(iso);
+  if (Number.isNaN(ms)) return "unknown";
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+function formatHandoff(h) {
+  const lines = [`Where you left off  (${ago(h.updatedAt)})`, "", `  Goal       ${h.goal}`, `  Next step  ${h.nextStep}`];
+  if (h.decisions.length > 0) {
+    lines.push("", "  Decided:");
+    for (const d of h.decisions) lines.push(`    \xB7 ${d}`);
+  }
+  if (h.openThreads.length > 0) {
+    lines.push("", "  Still open:");
+    for (const t of h.openThreads) lines.push(`    \xB7 ${t}`);
+  }
+  if (h.filesTouched.length > 0) {
+    const shown = h.filesTouched.slice(0, 12);
+    lines.push("", "  Files touched:");
+    for (const f of shown) lines.push(`    ${f}`);
+    if (h.filesTouched.length > shown.length) {
+      lines.push(`    \u2026 and ${h.filesTouched.length - shown.length} more`);
+    }
+  }
+  if (h.notes) lines.push("", `  Notes: ${h.notes}`);
+  return lines;
+}
+function handoffAge(h) {
+  return ago(h.updatedAt);
+}
+function isStale(h, newestContentMs) {
+  const t = Date.parse(h.updatedAt);
+  if (Number.isNaN(t)) return true;
+  return newestContentMs - t > 60 * 60 * 1e3;
+}
+
 // src/scaffold.ts
-var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path4 = __toESM(require("path"), 1);
+var import_node_fs5 = __toESM(require("fs"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
 var SLASH_COMMAND_PATH = ".claude/commands/context.md";
 var SLASH_COMMAND_BODY = `---
 description: Sync this project's LLM context (memory, skills, instructions, handoff)
@@ -500,26 +704,26 @@ Run the context-sync action requested in: $ARGUMENTS
 Run: \`npx @tricknowtech/context status\` and summarize the result.
 `;
 function installSlashCommand(projectRoot) {
-  const dest = import_node_path4.default.join(projectRoot, SLASH_COMMAND_PATH);
-  if (import_node_fs4.default.existsSync(dest)) return { path: SLASH_COMMAND_PATH, written: false };
-  ensureDir(import_node_path4.default.dirname(dest));
-  import_node_fs4.default.writeFileSync(dest, SLASH_COMMAND_BODY, "utf8");
+  const dest = import_node_path5.default.join(projectRoot, SLASH_COMMAND_PATH);
+  if (import_node_fs5.default.existsSync(dest)) return { path: SLASH_COMMAND_PATH, written: false };
+  ensureDir(import_node_path5.default.dirname(dest));
+  import_node_fs5.default.writeFileSync(dest, SLASH_COMMAND_BODY, "utf8");
   return { path: SLASH_COMMAND_PATH, written: true };
 }
 function ensureGitignoreEntries(projectRoot, artifactsEnabled) {
-  const gitignore = import_node_path4.default.join(projectRoot, ".gitignore");
+  const gitignore = import_node_path5.default.join(projectRoot, ".gitignore");
   const wanted = [".contextsync/transcripts/"];
   if (!artifactsEnabled) wanted.push(".contextsync/artifacts/");
   let existing = "";
   try {
-    existing = import_node_fs4.default.readFileSync(gitignore, "utf8");
+    existing = import_node_fs5.default.readFileSync(gitignore, "utf8");
   } catch {
   }
   const lines = new Set(existing.split("\n").map((l) => l.trim()));
   const missing = wanted.filter((w) => !lines.has(w));
   if (missing.length === 0) return [];
   const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-  import_node_fs4.default.appendFileSync(
+  import_node_fs5.default.appendFileSync(
     gitignore,
     `${prefix}
 # tricknowtech context-sync \u2014 never commit these tiers
@@ -531,7 +735,7 @@ ${missing.join("\n")}
 }
 
 // src/secrets.ts
-var import_node_fs5 = __toESM(require("fs"), 1);
+var import_node_fs6 = __toESM(require("fs"), 1);
 var BENIGN_KEY = /(?:^|[_-])(?:input|output|prompt|completion|total|max|min|num|new|cache|cached|remaining|used|count|context|window|budget|estimated?)[_-]?tokens?$|tokens?[_-]?(?:count|used|limit|remaining|in|out|usage|per|budget)$/i;
 function looksLikeCredential(value) {
   if (/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/.test(value)) return false;
@@ -585,7 +789,7 @@ function scanFiles(files) {
   for (const file of files) {
     let buf;
     try {
-      buf = import_node_fs5.default.readFileSync(file.sourcePath);
+      buf = import_node_fs6.default.readFileSync(file.sourcePath);
     } catch {
       continue;
     }
@@ -623,8 +827,8 @@ function formatHits(hits) {
 }
 
 // src/store.ts
-var import_node_fs6 = __toESM(require("fs"), 1);
-var import_node_path5 = __toESM(require("path"), 1);
+var import_node_fs7 = __toESM(require("fs"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 var MANIFEST_FILE = "manifest.json";
 var LocalStore = class {
   constructor(projectRoot) {
@@ -635,13 +839,13 @@ var LocalStore = class {
     return storeDir(this.projectRoot);
   }
   write(files, projectRoot) {
-    for (const name of import_node_fs6.default.existsSync(this.dir) ? import_node_fs6.default.readdirSync(this.dir) : []) {
+    for (const name of import_node_fs7.default.existsSync(this.dir) ? import_node_fs7.default.readdirSync(this.dir) : []) {
       if (name === "config.json" || name === HANDOFF_FILE) continue;
-      import_node_fs6.default.rmSync(import_node_path5.default.join(this.dir, name), { recursive: true, force: true });
+      import_node_fs7.default.rmSync(import_node_path6.default.join(this.dir, name), { recursive: true, force: true });
     }
     const entries = [];
     for (const file of files) {
-      const dest = import_node_path5.default.join(this.dir, file.storePath);
+      const dest = import_node_path6.default.join(this.dir, file.storePath);
       try {
         copyFile(file.sourcePath, dest);
       } catch {
@@ -662,11 +866,11 @@ var LocalStore = class {
       writtenFrom: projectRoot,
       entries
     };
-    writeJson(import_node_path5.default.join(this.dir, MANIFEST_FILE), manifest);
+    writeJson(import_node_path6.default.join(this.dir, MANIFEST_FILE), manifest);
     return manifest;
   }
   readManifest() {
-    return readJson(import_node_path5.default.join(this.dir, MANIFEST_FILE));
+    return readJson(import_node_path6.default.join(this.dir, MANIFEST_FILE));
   }
   restore(ctx, opts = {}) {
     const manifest = this.readManifest();
@@ -674,12 +878,12 @@ var LocalStore = class {
     const skipped = [];
     if (!manifest) return { restored, skipped };
     for (const entry of manifest.entries) {
-      const src = import_node_path5.default.join(this.dir, entry.storePath);
-      if (!import_node_fs6.default.existsSync(src)) continue;
+      const src = import_node_path6.default.join(this.dir, entry.storePath);
+      if (!import_node_fs7.default.existsSync(src)) continue;
       const dest = resolveTemplate(entry.restoreTemplate, ctx);
-      if (!opts.force && import_node_fs6.default.existsSync(dest)) {
+      if (!opts.force && import_node_fs7.default.existsSync(dest)) {
         try {
-          if (!import_node_fs6.default.readFileSync(dest).equals(import_node_fs6.default.readFileSync(src))) {
+          if (!import_node_fs7.default.readFileSync(dest).equals(import_node_fs7.default.readFileSync(src))) {
             skipped.push(entry.storePath);
             continue;
           }
@@ -689,8 +893,8 @@ var LocalStore = class {
         }
       }
       try {
-        ensureDir(import_node_path5.default.dirname(dest));
-        import_node_fs6.default.copyFileSync(src, dest);
+        ensureDir(import_node_path6.default.dirname(dest));
+        import_node_fs7.default.copyFileSync(src, dest);
         restored.push(entry.storePath);
       } catch {
         skipped.push(entry.storePath);
@@ -699,10 +903,10 @@ var LocalStore = class {
     return { restored, skipped };
   }
   readHandoff() {
-    return readJson(import_node_path5.default.join(this.dir, HANDOFF_FILE));
+    return readJson(import_node_path6.default.join(this.dir, HANDOFF_FILE));
   }
   writeHandoff(handoff) {
-    writeJson(import_node_path5.default.join(this.dir, HANDOFF_FILE), handoff);
+    writeJson(import_node_path6.default.join(this.dir, HANDOFF_FILE), handoff);
   }
 };
 
@@ -727,12 +931,12 @@ function requireProject() {
   }
   const cfg = loadConfig(root);
   if (!cfg) {
-    return fail([`No context store found at ${import_node_path6.default.join(root, ".contextsync")}.`, "Run `ctx init` first."]);
+    return fail([`No context store found at ${import_node_path7.default.join(root, ".contextsync")}.`, "Run `ctx init` first."]);
   }
   return { root, cfg };
 }
 function templateContext(root) {
-  return { userClaude: userClaudeDir(), project: root, cwdKey: cwdKey(root) };
+  return templateContextFor(root);
 }
 function effectiveTiers(cfg) {
   const tiers = cfg.tiers.filter((t) => LOCAL_TIERS.includes(t));
@@ -750,7 +954,7 @@ function cmdInit(opts = {}) {
   saveConfig(root, cfg);
   const lines = [
     `Initialised context store for "${cfg.name}"`,
-    `  store   ${import_node_path6.default.relative(root, storeDir(root))}/`,
+    `  store   ${import_node_path7.default.relative(root, storeDir(root))}/`,
     `  tiers   ${cfg.tiers.join(", ")}`
   ];
   const slash = installSlashCommand(root);
@@ -768,7 +972,7 @@ function cmdPush(opts = {}) {
   if ("code" in found) return found;
   const { root, cfg } = found;
   const { tiers, refused } = effectiveTiers(cfg);
-  const { files, skippedTracked } = collect(root, cfg, tiers);
+  const { files, skippedTracked, assistants } = collect(root, cfg, tiers);
   const lines = [];
   if (refused.length > 0) {
     lines.push(
@@ -807,12 +1011,15 @@ function cmdPush(opts = {}) {
   } else {
     const store = new LocalStore(root);
     store.write(files, root);
-    lines.push(`Synced ${files.length} files (${formatBytes(totalBytes)}) to ${import_node_path6.default.relative(root, storeDir(root))}/`);
+    lines.push(`Synced ${files.length} files (${formatBytes(totalBytes)}) to ${import_node_path7.default.relative(root, storeDir(root))}/`);
   }
   for (const tier of ALL_TIERS) {
     const t = totals[tier];
     if (t.count > 0) lines.push(`  ${tier.padEnd(11)} ${String(t.count).padStart(4)} files  ${formatBytes(t.bytes)}`);
   }
+  if (assistants.length > 0) {
+    lines.push("", `Assistants: ${assistants.map((a) => a.name).join(", ")}`);
+  }
   if (skippedTracked.length > 0) {
     lines.push("", `${skippedTracked.length} project files skipped \u2014 git already tracks them.`);
   }
@@ -824,6 +1031,20 @@ function cmdPush(opts = {}) {
     }
   }
   if (!opts.dryRun) {
+    const store = new LocalStore(root);
+    const raw = store.readHandoff();
+    const v = raw ? validateHandoff(raw) : null;
+    if (!raw) {
+      lines.push(
+        "",
+        "No handoff written \u2014 the other machine will get your project knowledge but",
+        "not where you left off. Use `/context push` in Claude Code to include one."
+      );
+    } else if (v && !v.ok) {
+      lines.push("", "Handoff present but malformed (it will be ignored):", ...v.errors.map((e) => `  \xB7 ${e}`));
+    } else if (v?.ok && isStale(v.handoff, Date.now())) {
+      lines.push("", `Handoff is ${handoffAge(v.handoff)} \u2014 re-run \`/context push\` to refresh it.`);
+    }
     lines.push("", "Commit .contextsync/ to carry this context with the repo.");
   }
   return ok(lines);
@@ -835,7 +1056,7 @@ function cmdPull(opts = {}) {
   const store = new LocalStore(root);
   const manifest = store.readManifest();
   if (!manifest) {
-    return fail([`No manifest in ${import_node_path6.default.relative(root, storeDir(root))}/.`, "Run `ctx push` on the source machine first."]);
+    return fail([`No manifest in ${import_node_path7.default.relative(root, storeDir(root))}/.`, "Run `ctx push` on the source machine first."]);
   }
   const ctx = templateContext(root);
   const { restored, skipped } = store.restore(ctx, { force: opts.force });
@@ -853,12 +1074,114 @@ function cmdPull(opts = {}) {
       "Re-run with --force to overwrite them."
     );
   }
-  const handoff = store.readHandoff();
-  if (handoff) {
-    lines.push("", `Handoff (${handoff.updatedAt}):`, `  goal: ${handoff.goal}`, `  next: ${handoff.nextStep}`);
+  const raw = store.readHandoff();
+  if (!raw) {
+    lines.push(
+      "",
+      "No handoff in this store \u2014 you have the project knowledge, but not where the",
+      "last session stopped. Run `/context push` (not bare `ctx push`) on the other",
+      "machine: only the model can write the handoff, since only it has the conversation."
+    );
+    return ok(lines);
   }
+  const check = validateHandoff(raw);
+  if (!check.ok) {
+    lines.push("", "A handoff exists but is malformed and was ignored:", ...check.errors.map((e) => `  \xB7 ${e}`));
+    return ok(lines);
+  }
+  lines.push("", ...formatHandoff(check.handoff));
   return ok(lines);
 }
+function cmdHandoff(opts = {}) {
+  const found = requireProject();
+  if ("code" in found) return found;
+  const { root } = found;
+  const store = new LocalStore(root);
+  if (opts.set !== void 0) {
+    let parsed;
+    try {
+      parsed = JSON.parse(opts.set);
+    } catch (e) {
+      return fail([`Could not parse handoff JSON: ${e.message}`]);
+    }
+    const check2 = validateHandoff(parsed);
+    if (!check2.ok) return fail(["Handoff is not valid:", ...check2.errors.map((e) => `  \xB7 ${e}`)]);
+    store.writeHandoff(check2.handoff);
+    return ok([`Handoff saved (${import_node_path7.default.relative(root, storeDir(root))}/handoff.json).`, "", ...formatHandoff(check2.handoff)]);
+  }
+  const raw = store.readHandoff();
+  if (!raw) {
+    return ok([
+      "No handoff yet.",
+      "",
+      "Write one with `/context push` in Claude Code, or pipe JSON:",
+      `  ctx handoff --set '{"goal":"\u2026","nextStep":"\u2026"}'`
+    ]);
+  }
+  const check = validateHandoff(raw);
+  if (!check.ok) return fail(["Handoff is malformed:", ...check.errors.map((e) => `  \xB7 ${e}`)]);
+  return ok(formatHandoff(check.handoff));
+}
+function cmdDoctor() {
+  const root = findProjectRoot();
+  if (!root) return fail(["Not inside a project. Run `ctx init` first."]);
+  const lines = [];
+  let problems = 0;
+  const check = (okFlag, label, detail) => {
+    if (!okFlag) problems++;
+    lines.push(`  ${okFlag ? "\u2713" : "\u2717"} ${label.padEnd(28)} ${detail}`);
+  };
+  const cfg = loadConfig(root);
+  check(Boolean(cfg), "store initialised", cfg ? `${import_node_path7.default.relative(root, storeDir(root))}/` : "missing \u2014 run `ctx init`");
+  if (!cfg) return { code: 1, lines: ["Setup check", "", ...lines] };
+  const store = new LocalStore(root);
+  const manifest = store.readManifest();
+  check(Boolean(manifest), "pushed at least once", manifest ? `${manifest.entries.length} files` : "never \u2014 run `ctx push`");
+  const detected = collect(root, cfg, ["core"]).assistants;
+  check(
+    detected.length > 0,
+    "assistants detected",
+    detected.length > 0 ? detected.map((a) => a.name).join(", ") : "none \u2014 no known assistant config found"
+  );
+  check(
+    import_node_fs8.default.existsSync(import_node_path7.default.join(root, SLASH_COMMAND_PATH)),
+    "/context slash command",
+    import_node_fs8.default.existsSync(import_node_path7.default.join(root, SLASH_COMMAND_PATH)) ? SLASH_COMMAND_PATH : `missing \u2014 run \`ctx init --force\``
+  );
+  const inGit = isGitRepo(root);
+  check(inGit, "git repository", inGit ? "yes \u2014 store travels with the repo" : "no \u2014 the store will not sync anywhere");
+  let storeIgnored = false;
+  if (inGit) {
+    try {
+      (0, import_node_child_process2.execFileSync)("git", ["-C", root, "check-ignore", "-q", ".contextsync/config.json"], { stdio: "ignore" });
+      storeIgnored = true;
+    } catch {
+      storeIgnored = false;
+    }
+  }
+  check(!storeIgnored, "store is committable", storeIgnored ? "IGNORED by git \u2014 it will never reach another machine" : "not gitignored");
+  const ctx = templateContext(root);
+  const memEntry = manifest?.entries.find((e) => e.storePath.startsWith("memory/"));
+  if (memEntry) {
+    const dest = resolveTemplate(memEntry.restoreTemplate, ctx);
+    const expectedDir = import_node_path7.default.join(userClaudeDir(), "projects", cwdKey(root), "memory");
+    check(dest.startsWith(expectedDir), "memory restore path", dest.startsWith(expectedDir) ? expectedDir : `WRONG \u2192 ${dest}`);
+  } else {
+    check(false, "memory captured", "none found \u2014 is ~/.claude/projects/<key>/memory populated?");
+  }
+  const raw = store.readHandoff();
+  if (!raw) {
+    check(false, "handoff", "absent \u2014 `/context push` writes it; resume will have nothing to say");
+  } else {
+    const v = validateHandoff(raw);
+    check(v.ok, "handoff", v.ok ? `valid, ${handoffAge(v.handoff)}` : v.errors[0]);
+    if (v.ok && manifest && isStale(v.handoff, Date.parse(manifest.updatedAt))) {
+      lines.push("    ! handoff is much older than the last push \u2014 re-run `/context push`");
+    }
+  }
+  const header = problems === 0 ? "Setup check \u2014 all good" : `Setup check \u2014 ${problems} problem${problems === 1 ? "" : "s"}`;
+  return { code: problems === 0 ? 0 : 1, lines: [header, "", ...lines] };
+}
 function cmdStatus() {
   const found = requireProject();
   if ("code" in found) return found;
@@ -866,11 +1189,16 @@ function cmdStatus() {
   const store = new LocalStore(root);
   const manifest = store.readManifest();
   const { tiers } = effectiveTiers(cfg);
-  const { files, skippedTracked } = collect(root, cfg, tiers);
+  const { files, skippedTracked, assistants } = collect(root, cfg, tiers);
+  const rawHandoff = store.readHandoff();
+  const hv = rawHandoff ? validateHandoff(rawHandoff) : null;
+  const handoffLabel = !rawHandoff ? "none \u2014 run `/context push` to record where you left off" : hv?.ok ? `${handoffAge(hv.handoff)}` : "malformed (will be ignored)";
   const lines = [
     `Project  ${cfg.name}`,
-    `Store    ${import_node_path6.default.relative(root, storeDir(root))}/`,
+    `Store    ${import_node_path7.default.relative(root, storeDir(root))}/`,
     `Tiers    ${cfg.tiers.join(", ")}`,
+    `Handoff  ${handoffLabel}`,
+    `Tools    ${assistants.length > 0 ? assistants.map((a) => a.name).join(", ") : "none detected"}`,
     `Remotes  ${Object.keys(cfg.remotes).length > 0 ? Object.keys(cfg.remotes).join(", ") : "none (local only)"}`,
     ""
   ];
@@ -887,7 +1215,7 @@ function cmdStatus() {
     if (!e) return false;
     if (e.size !== f.size) return true;
     try {
-      return !import_node_fs7.default.readFileSync(import_node_path6.default.join(storeDir(root), k)).equals(import_node_fs7.default.readFileSync(f.sourcePath));
+      return !import_node_fs8.default.readFileSync(import_node_path7.default.join(storeDir(root), k)).equals(import_node_fs8.default.readFileSync(f.sourcePath));
     } catch {
       return true;
     }
@@ -912,13 +1240,16 @@ function cmdStatus() {
 }
 
 // src/cli.ts
+var VERSION = "0.3.0";
 var USAGE = `tricknowtech context-sync \u2014 carry a project's LLM context between machines
 
 Usage
   ctx init [--artifacts] [--force]   Create the store and install /context
   ctx push [--dry-run]               Collect context into the store
-  ctx pull [--force]                 Restore context from the store
-  ctx status                         Show what has changed since the last push
+  ctx pull [--force]                 Restore context, and show where you left off
+  ctx status                         What has changed since the last push
+  ctx handoff [--set '<json>']       Show or write the session handoff
+  ctx doctor                         Check the setup is actually wired correctly
 
 Options
   --artifacts       Include derived indexes (graphify-out/, etc.)
@@ -929,20 +1260,38 @@ Options
   -v, --version     Show version
 
 The store lives in .contextsync/ and is meant to be committed, so context
-travels with the code. Session transcripts are excluded from local mode.`;
+travels with the code. Session transcripts are excluded from local mode.
+
+Prefer \`/context push\` inside Claude Code over bare \`ctx push\`: only the
+model can write the handoff that lets the next machine resume the work.`;
 function parseArgs(argv) {
   const flags = /* @__PURE__ */ new Set();
+  const values = /* @__PURE__ */ new Map();
   let command = "";
-  for (const arg of argv) {
-    if (arg.startsWith("-")) flags.add(arg.replace(/^-+/, ""));
-    else if (!command) command = arg;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("-")) {
+      const name = arg.replace(/^-+/, "");
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        values.set(name.slice(0, eq), name.slice(eq + 1));
+        continue;
+      }
+      if (name === "set" && i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+        values.set(name, argv[++i]);
+        continue;
+      }
+      flags.add(name);
+    } else if (!command) {
+      command = arg;
+    }
   }
-  return { command, flags };
+  return { command, flags, values };
 }
 function run(argv) {
-  const { command, flags } = parseArgs(argv);
+  const { command, flags, values } = parseArgs(argv);
   if (flags.has("h") || flags.has("help")) return { code: 0, lines: [USAGE] };
-  if (flags.has("v") || flags.has("version")) return { code: 0, lines: ["0.1.1"] };
+  if (flags.has("v") || flags.has("version")) return { code: 0, lines: [VERSION] };
   switch (command) {
     case "init":
       return cmdInit({ artifacts: flags.has("artifacts"), force: flags.has("force") });
@@ -950,6 +1299,10 @@ function run(argv) {
       return cmdPush({ allowSecrets: flags.has("allow-secrets"), dryRun: flags.has("dry-run") });
     case "pull":
       return cmdPull({ force: flags.has("force") });
+    case "handoff":
+      return cmdHandoff({ set: values.get("set") });
+    case "doctor":
+      return cmdDoctor();
     case "status":
     case "":
       return cmdStatus();