@tricknowtech/context 0.1.1 → 0.2.0

package/README.md

@@ -18,10 +18,17 @@ Open the same project on a second machine and the assistant knows nothing. Your
 
 ```bash
 ctx push      # collect context into the store
-ctx pull      # restore it on another machine
+ctx pull      # restore it, and print where you left off
 ctx status    # what changed since the last push
+ctx handoff   # show or write the session handoff
+ctx doctor    # check the setup is actually wired correctly
 ```
 
+Start with `ctx doctor` if anything seems off — it verifies the pieces that
+fail silently, including whether your store is accidentally gitignored (in
+which case it never reaches the other machine) and whether restored memory
+lands where Claude Code actually reads it.
+
 Commit `.contextsync/` and your teammates — and your other laptop — get the same context on clone.
 
 ### It skips what git already carries
@@ -46,7 +53,25 @@ Claude Code names its per-project directories after the absolute project path
 
 `/context push` asks the model to write `.contextsync/handoff.json` first — goal, decisions made, open threads, files touched, next step. Only the model has the conversation; only the CLI has the disk, so the slash command is the one place both are available.
 
-On the other machine, `/context pull` restores everything and reads the handoff back, so the new session starts oriented instead of blank.
+On the other machine, `/context pull` restores everything and reads the handoff back, so the new session starts oriented instead of blank:
+
+```
+Where you left off  (2h ago)
+
+  Goal       Build the context-sync tool and publish it
+  Next step  Start the cloud remote, leading with the token-scoping fix
+
+  Decided:
+    · Local-first: store is committed to the repo, cloud is an optional remote
+  Still open:
+    · mcp:* token abilities are granted but never checked
+```
+
+The handoff is validated on write and on read — a model-authored file that's
+malformed is reported rather than silently ignored, since a handoff that looks
+present but says nothing is worse than an obviously absent one. `ctx push`
+tells you when no handoff was written, so you never discover it only after
+arriving on the other machine.
 
 ## Safety
 

package/dist/{chunk-BWATZKYM.js → chunk-6GB2SN2L.js}

@@ -403,6 +403,86 @@ function summarize(files) {
   return out;
 }
 
+// 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
 import fs4 from "fs";
 import path4 from "path";
@@ -689,6 +769,10 @@ export {
   collect,
   describeExcluded,
   summarize,
+  validateHandoff,
+  formatHandoff,
+  handoffAge,
+  isStale,
   SLASH_COMMAND_PATH,
   SLASH_COMMAND_BODY,
   installSlashCommand,

package/dist/cli.cjs

@@ -36,6 +36,7 @@ __export(cli_exports, {
 module.exports = __toCommonJS(cli_exports);
 
 // src/commands.ts
+var import_node_child_process2 = require("child_process");
 var import_node_fs7 = __toESM(require("fs"), 1);
 var import_node_path6 = __toESM(require("path"), 1);
 
@@ -448,6 +449,86 @@ 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);
@@ -824,6 +905,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);
@@ -853,12 +948,108 @@ 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_path6.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_path6.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`");
+  check(
+    import_node_fs7.default.existsSync(import_node_path6.default.join(root, SLASH_COMMAND_PATH)),
+    "/context slash command",
+    import_node_fs7.default.existsSync(import_node_path6.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_path6.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;
@@ -867,10 +1058,14 @@ function cmdStatus() {
   const manifest = store.readManifest();
   const { tiers } = effectiveTiers(cfg);
   const { files, skippedTracked } = 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))}/`,
     `Tiers    ${cfg.tiers.join(", ")}`,
+    `Handoff  ${handoffLabel}`,
     `Remotes  ${Object.keys(cfg.remotes).length > 0 ? Object.keys(cfg.remotes).join(", ") : "none (local only)"}`,
     ""
   ];
@@ -912,13 +1107,16 @@ function cmdStatus() {
 }
 
 // src/cli.ts
+var VERSION = "0.2.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 +1127,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 +1166,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();

package/dist/cli.js

@@ -3,6 +3,7 @@ import {
   ALL_TIERS,
   LOCAL_TIERS,
   LocalStore,
+  SLASH_COMMAND_PATH,
   collect,
   configPath,
   cwdKey,
@@ -11,18 +12,24 @@ import {
   ensureGitignoreEntries,
   findProjectRoot,
   formatBytes,
+  formatHandoff,
   formatHits,
+  handoffAge,
   installSlashCommand,
   isGitRepo,
+  isStale,
   loadConfig,
+  resolveTemplate,
   saveConfig,
   scanFiles,
   storeDir,
   summarize,
-  userClaudeDir
-} from "./chunk-BWATZKYM.js";
+  userClaudeDir,
+  validateHandoff
+} from "./chunk-6GB2SN2L.js";
 
 // src/commands.ts
+import { execFileSync } from "child_process";
 import fs from "fs";
 import path from "path";
 function ok(lines) {
@@ -138,6 +145,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);
@@ -167,12 +188,108 @@ 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 (${path.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 ? `${path.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`");
+  check(
+    fs.existsSync(path.join(root, SLASH_COMMAND_PATH)),
+    "/context slash command",
+    fs.existsSync(path.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 {
+      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 = path.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;
@@ -181,10 +298,14 @@ function cmdStatus() {
   const manifest = store.readManifest();
   const { tiers } = effectiveTiers(cfg);
   const { files, skippedTracked } = 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    ${path.relative(root, storeDir(root))}/`,
     `Tiers    ${cfg.tiers.join(", ")}`,
+    `Handoff  ${handoffLabel}`,
     `Remotes  ${Object.keys(cfg.remotes).length > 0 ? Object.keys(cfg.remotes).join(", ") : "none (local only)"}`,
     ""
   ];
@@ -226,13 +347,16 @@ function cmdStatus() {
 }
 
 // src/cli.ts
+var VERSION = "0.2.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.)
@@ -243,20 +367,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") });
@@ -264,6 +406,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();

package/dist/index.cjs

@@ -45,13 +45,17 @@ __export(index_exports, {
   configPath: () => configPath,
   cwdKey: () => cwdKey,
   defaultConfig: () => defaultConfig,
+  describeExcluded: () => describeExcluded,
   ensureGitignoreEntries: () => ensureGitignoreEntries,
   findProjectRoot: () => findProjectRoot,
   formatBytes: () => formatBytes,
+  formatHandoff: () => formatHandoff,
   formatHits: () => formatHits,
   gitTrackedSet: () => gitTrackedSet,
+  handoffAge: () => handoffAge,
   installSlashCommand: () => installSlashCommand,
   isGitRepo: () => isGitRepo,
+  isStale: () => isStale,
   loadConfig: () => loadConfig,
   makeTemplate: () => makeTemplate,
   matchesAny: () => matchesAny,
@@ -61,6 +65,7 @@ __export(index_exports, {
   storeDir: () => storeDir,
   summarize: () => summarize,
   userClaudeDir: () => userClaudeDir,
+  validateHandoff: () => validateHandoff,
   walk: () => walk
 });
 module.exports = __toCommonJS(index_exports);
@@ -421,6 +426,44 @@ function collect(projectRoot, cfg, tiers) {
   }
   return { files, skippedTracked, ctx };
 }
+function describeExcluded(projectRoot, tiers) {
+  const userClaude = userClaudeDir();
+  const key = cwdKey(projectRoot);
+  const out = [];
+  const measure = (dir, filter) => {
+    let files = 0;
+    let bytes = 0;
+    for (const abs of walk(dir, { exclude: [] })) {
+      if (filter && !filter(abs)) continue;
+      files++;
+      try {
+        bytes += import_node_fs3.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}`));
+    if (m.files > 0) {
+      out.push({
+        label: "session transcripts",
+        ...m,
+        reason: "cloud-only \u2014 append-only logs this large would permanently bloat the repo"
+      });
+    }
+  }
+  for (const [dir, label, reason] of [
+    ["uploads", "pasted files/images", "session-scoped binaries; regenerate rather than sync"],
+    ["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));
+    if (m.files > 0) out.push({ label, ...m, reason });
+  }
+  return out.filter((g) => g.bytes > 0);
+}
 function summarize(files) {
   const empty = { count: 0, bytes: 0 };
   const out = {
@@ -436,6 +479,86 @@ function summarize(files) {
   return out;
 }
 
+// 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);
@@ -714,13 +837,17 @@ var LOCAL_TIERS = ["core", "handoff", "artifacts"];
   configPath,
   cwdKey,
   defaultConfig,
+  describeExcluded,
   ensureGitignoreEntries,
   findProjectRoot,
   formatBytes,
+  formatHandoff,
   formatHits,
   gitTrackedSet,
+  handoffAge,
   installSlashCommand,
   isGitRepo,
+  isStale,
   loadConfig,
   makeTemplate,
   matchesAny,
@@ -730,5 +857,6 @@ var LOCAL_TIERS = ["core", "handoff", "artifacts"];
   storeDir,
   summarize,
   userClaudeDir,
+  validateHandoff,
   walk
 });

package/dist/index.d.cts

@@ -155,11 +155,47 @@ interface CollectResult {
  *    repo and are exactly what never makes it to a second machine today.
  */
 declare function collect(projectRoot: string, cfg: ProjectConfig, tiers: Tier[]): CollectResult;
+interface ExcludedGroup {
+    label: string;
+    files: number;
+    bytes: number;
+    reason: string;
+}
+/**
+ * What was deliberately left behind, and why.
+ *
+ * Without this a user sees "13 files synced" against a ~400 MB context
+ * directory and reasonably concludes the tool is broken. Naming the omissions
+ * — with sizes — is the difference between a considered exclusion and a
+ * silent one.
+ */
+declare function describeExcluded(projectRoot: string, tiers: Tier[]): ExcludedGroup[];
 declare function summarize(files: CollectedFile[]): Record<Tier, {
     count: number;
     bytes: number;
 }>;
 
+/**
+ * The handoff is the whole point of the tool — files alone tell you what a
+ * project knows, but not where you stopped. It is written by the model (only
+ * it has the conversation) and read back on the other machine.
+ *
+ * Because a model writes it, it needs real validation: a silently malformed
+ * handoff is worse than none, since `pull` would look like it worked while
+ * handing back nothing usable.
+ */
+interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+    handoff?: Handoff;
+}
+declare function validateHandoff(raw: unknown): ValidationResult;
+/** Render a handoff for a human picking the work back up. */
+declare function formatHandoff(h: Handoff): string[];
+declare function handoffAge(h: Handoff): string;
+/** True when the handoff predates the newest synced content by a wide margin. */
+declare function isStale(h: Handoff, newestContentMs: number): boolean;
+
 declare const STORE_DIR = ".contextsync";
 declare const CONFIG_FILE = "config.json";
 declare const HANDOFF_FILE = "handoff.json";
@@ -266,4 +302,4 @@ declare class LocalStore implements Store {
     writeHandoff(handoff: Handoff): void;
 }
 
-export { ALL_TIERS, CONFIG_FILE, type CollectResult, type CollectedFile, DEFAULT_EXCLUDE, HANDOFF_FILE, HARD_DENY, type Handoff, LOCAL_TIERS, LocalStore, MANIFEST_FILE, type Manifest, type ManifestEntry, type ProjectConfig, type RemoteConfig, type RestoreResult, SLASH_COMMAND_BODY, SLASH_COMMAND_PATH, STORE_DIR, type SecretHit, type SourceRoot, type Store, type TemplateContext, type Tier, collect, configPath, cwdKey, defaultConfig, ensureGitignoreEntries, findProjectRoot, formatBytes, formatHits, gitTrackedSet, installSlashCommand, isGitRepo, loadConfig, makeTemplate, matchesAny, resolveTemplate, saveConfig, scanFiles, storeDir, summarize, userClaudeDir, walk };
+export { ALL_TIERS, CONFIG_FILE, type CollectResult, type CollectedFile, DEFAULT_EXCLUDE, type ExcludedGroup, HANDOFF_FILE, HARD_DENY, type Handoff, LOCAL_TIERS, LocalStore, MANIFEST_FILE, type Manifest, type ManifestEntry, type ProjectConfig, type RemoteConfig, type RestoreResult, SLASH_COMMAND_BODY, SLASH_COMMAND_PATH, STORE_DIR, type SecretHit, type SourceRoot, type Store, type TemplateContext, type Tier, type ValidationResult, collect, configPath, cwdKey, defaultConfig, describeExcluded, ensureGitignoreEntries, findProjectRoot, formatBytes, formatHandoff, formatHits, gitTrackedSet, handoffAge, installSlashCommand, isGitRepo, isStale, loadConfig, makeTemplate, matchesAny, resolveTemplate, saveConfig, scanFiles, storeDir, summarize, userClaudeDir, validateHandoff, walk };

package/dist/index.d.ts

@@ -155,11 +155,47 @@ interface CollectResult {
  *    repo and are exactly what never makes it to a second machine today.
  */
 declare function collect(projectRoot: string, cfg: ProjectConfig, tiers: Tier[]): CollectResult;
+interface ExcludedGroup {
+    label: string;
+    files: number;
+    bytes: number;
+    reason: string;
+}
+/**
+ * What was deliberately left behind, and why.
+ *
+ * Without this a user sees "13 files synced" against a ~400 MB context
+ * directory and reasonably concludes the tool is broken. Naming the omissions
+ * — with sizes — is the difference between a considered exclusion and a
+ * silent one.
+ */
+declare function describeExcluded(projectRoot: string, tiers: Tier[]): ExcludedGroup[];
 declare function summarize(files: CollectedFile[]): Record<Tier, {
     count: number;
     bytes: number;
 }>;
 
+/**
+ * The handoff is the whole point of the tool — files alone tell you what a
+ * project knows, but not where you stopped. It is written by the model (only
+ * it has the conversation) and read back on the other machine.
+ *
+ * Because a model writes it, it needs real validation: a silently malformed
+ * handoff is worse than none, since `pull` would look like it worked while
+ * handing back nothing usable.
+ */
+interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+    handoff?: Handoff;
+}
+declare function validateHandoff(raw: unknown): ValidationResult;
+/** Render a handoff for a human picking the work back up. */
+declare function formatHandoff(h: Handoff): string[];
+declare function handoffAge(h: Handoff): string;
+/** True when the handoff predates the newest synced content by a wide margin. */
+declare function isStale(h: Handoff, newestContentMs: number): boolean;
+
 declare const STORE_DIR = ".contextsync";
 declare const CONFIG_FILE = "config.json";
 declare const HANDOFF_FILE = "handoff.json";
@@ -266,4 +302,4 @@ declare class LocalStore implements Store {
     writeHandoff(handoff: Handoff): void;
 }
 
-export { ALL_TIERS, CONFIG_FILE, type CollectResult, type CollectedFile, DEFAULT_EXCLUDE, HANDOFF_FILE, HARD_DENY, type Handoff, LOCAL_TIERS, LocalStore, MANIFEST_FILE, type Manifest, type ManifestEntry, type ProjectConfig, type RemoteConfig, type RestoreResult, SLASH_COMMAND_BODY, SLASH_COMMAND_PATH, STORE_DIR, type SecretHit, type SourceRoot, type Store, type TemplateContext, type Tier, collect, configPath, cwdKey, defaultConfig, ensureGitignoreEntries, findProjectRoot, formatBytes, formatHits, gitTrackedSet, installSlashCommand, isGitRepo, loadConfig, makeTemplate, matchesAny, resolveTemplate, saveConfig, scanFiles, storeDir, summarize, userClaudeDir, walk };
+export { ALL_TIERS, CONFIG_FILE, type CollectResult, type CollectedFile, DEFAULT_EXCLUDE, type ExcludedGroup, HANDOFF_FILE, HARD_DENY, type Handoff, LOCAL_TIERS, LocalStore, MANIFEST_FILE, type Manifest, type ManifestEntry, type ProjectConfig, type RemoteConfig, type RestoreResult, SLASH_COMMAND_BODY, SLASH_COMMAND_PATH, STORE_DIR, type SecretHit, type SourceRoot, type Store, type TemplateContext, type Tier, type ValidationResult, collect, configPath, cwdKey, defaultConfig, describeExcluded, ensureGitignoreEntries, findProjectRoot, formatBytes, formatHandoff, formatHits, gitTrackedSet, handoffAge, installSlashCommand, isGitRepo, isStale, loadConfig, makeTemplate, matchesAny, resolveTemplate, saveConfig, scanFiles, storeDir, summarize, userClaudeDir, validateHandoff, walk };

package/dist/index.js

@@ -14,13 +14,17 @@ import {
   configPath,
   cwdKey,
   defaultConfig,
+  describeExcluded,
   ensureGitignoreEntries,
   findProjectRoot,
   formatBytes,
+  formatHandoff,
   formatHits,
   gitTrackedSet,
+  handoffAge,
   installSlashCommand,
   isGitRepo,
+  isStale,
   loadConfig,
   makeTemplate,
   matchesAny,
@@ -30,8 +34,9 @@ import {
   storeDir,
   summarize,
   userClaudeDir,
+  validateHandoff,
   walk
-} from "./chunk-BWATZKYM.js";
+} from "./chunk-6GB2SN2L.js";
 export {
   ALL_TIERS,
   CONFIG_FILE,
@@ -48,13 +53,17 @@ export {
   configPath,
   cwdKey,
   defaultConfig,
+  describeExcluded,
   ensureGitignoreEntries,
   findProjectRoot,
   formatBytes,
+  formatHandoff,
   formatHits,
   gitTrackedSet,
+  handoffAge,
   installSlashCommand,
   isGitRepo,
+  isStale,
   loadConfig,
   makeTemplate,
   matchesAny,
@@ -64,5 +73,6 @@ export {
   storeDir,
   summarize,
   userClaudeDir,
+  validateHandoff,
   walk
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tricknowtech/context",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Carry a project's LLM context — memory, skills, instructions and session handoff — between machines. Local-first, commit it to your repo.",
   "type": "module",
   "main": "./dist/index.cjs",