@tricknowtech/context 0.1.0 → 0.2.0

package/dist/cli.js

@@ -3,25 +3,33 @@ import {
   ALL_TIERS,
   LOCAL_TIERS,
   LocalStore,
+  SLASH_COMMAND_PATH,
   collect,
   configPath,
   cwdKey,
   defaultConfig,
+  describeExcluded,
   ensureGitignoreEntries,
   findProjectRoot,
   formatBytes,
+  formatHandoff,
   formatHits,
+  handoffAge,
   installSlashCommand,
   isGitRepo,
+  isStale,
   loadConfig,
+  resolveTemplate,
   saveConfig,
   scanFiles,
   storeDir,
   summarize,
-  userClaudeDir
-} from "./chunk-DEH5MUFT.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) {
@@ -129,7 +137,28 @@ function cmdPush(opts = {}) {
   if (skippedTracked.length > 0) {
     lines.push("", `${skippedTracked.length} project files skipped \u2014 git already tracks them.`);
   }
+  const excluded = describeExcluded(root, tiers);
+  if (excluded.length > 0) {
+    lines.push("", "Not included (by design):");
+    for (const g of excluded) {
+      lines.push(`  ${g.label.padEnd(22)} ${formatBytes(g.bytes).padStart(9)}  ${g.reason}`);
+    }
+  }
   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);
@@ -159,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;
@@ -173,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)"}`,
     ""
   ];
@@ -218,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.)
@@ -235,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.0"] };
+  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") });
@@ -256,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);
@@ -299,12 +304,41 @@ var PROJECT_CONTEXT_GLOBS = [
   ".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(out, sourcePath, storePath, tier, sourceRoot, ctx) {
   let size = 0;
   try {
@@ -339,10 +373,24 @@ function collect(projectRoot, cfg, tiers) {
       }
       push(files, abs, `project/${rel}`, "core", "project", ctx);
     }
-    const memoryDir = import_node_path3.default.join(userClaude, "projects", key, "memory");
-    for (const abs of walk(memoryDir, { exclude })) {
-      const rel = toPosix(import_node_path3.default.relative(memoryDir, abs));
-      push(files, abs, `memory/${rel}`, "core", "user", 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 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 })) {
@@ -378,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 = {
@@ -393,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);
@@ -671,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,
@@ -687,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-DEH5MUFT.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
 };