context-vault 2.17.0 → 3.0.1

package/bin/cli.js

@@ -34,7 +34,7 @@ const HOME = homedir();
 
 const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
 const VERSION = pkg.version;
-const SERVER_PATH = resolve(ROOT, "src", "server", "index.js");
+const SERVER_PATH = resolve(ROOT, "src", "server.js");
 
 /** Detect if running as an npm-installed package (global or local) vs local dev clone */
 function isInstalledPackage() {
@@ -282,7 +282,7 @@ function printDetectionResults(results) {
   }
 }
 
-function showHelp() {
+function showHelp(showAll = false) {
   console.log(`
   ${bold("◇ context-vault")} ${dim(`v${VERSION}`)}
   ${dim("Persistent memory for AI agents")}
@@ -293,37 +293,50 @@ ${bold("Usage:")}
   ${dim("No command → runs setup (first time) or shows status (existing vault)")}
 
 ${bold("Commands:")}
-  ${cyan("setup")}                 Interactive MCP server installer
-  ${cyan("connect")} --key cv_...  Connect AI tools to hosted vault
-  ${cyan("switch")} local|hosted      Switch between local and hosted MCP modes
-  ${cyan("serve")}                 Start the MCP server (used by AI clients)
-  ${cyan("hooks")} install|uninstall  Install or remove Claude Code memory hook
-  ${cyan("claude")} install|uninstall  Alias for hooks install|uninstall
-  ${cyan("skills")} install          Install bundled Claude Code skills
-  ${cyan("health")}                Quick health check — vault, DB, entry count
-  ${cyan("restart")}               Stop running MCP server processes (client auto-restarts)
-  ${cyan("flush")}                 Check vault health and confirm DB is accessible
-  ${cyan("recall")}                Search vault from a Claude Code hook (reads stdin)
-  ${cyan("session-capture")}       Save a session summary entry (reads JSON from stdin)
-  ${cyan("session-end")}           Run session-end hook (parse transcript + capture)
-  ${cyan("post-tool-call")}        Run post-tool-call hook (log tool usage)
-  ${cyan("save")}                  Save an entry to the vault from CLI
-  ${cyan("search")}                Search vault entries from CLI
-  ${cyan("reindex")}               Rebuild search index from knowledge files
-  ${cyan("prune")}                 Remove expired entries (use --dry-run to preview)
-  ${cyan("status")}                Show vault diagnostics
-  ${cyan("doctor")}                Diagnose and repair common issues
-  ${cyan("update")}                Check for and install updates
-  ${cyan("uninstall")}             Remove MCP configs and optionally data
-  ${cyan("import")} <path>          Import entries from file or directory
-  ${cyan("export")}                Export vault to JSON or CSV
-  ${cyan("ingest")} <url>          Fetch URL and save as vault entry
-  ${cyan("ingest-project")} <path>  Scan project directory and register as project entity
-  ${cyan("migrate")}               Migrate vault between local and hosted
-  ${cyan("consolidate")}           Find hot tags and cold entries for maintenance
-
-${bold("Options:")}
+  ${cyan("setup")}                      Interactive MCP server installer
+  ${cyan("connect")} --key cv_...       Connect AI tools to hosted vault
+  ${cyan("switch")} local|hosted        Switch between local and hosted MCP modes
+  ${cyan("serve")}                      Start the MCP server (used by AI clients)
+  ${cyan("hooks")} install|uninstall    Install or remove Claude Code memory hook
+  ${cyan("claude")} install|uninstall   Alias for hooks install|uninstall
+  ${cyan("skills")} install             Install bundled Claude Code skills
+  ${cyan("health")}                     Quick health check — vault, DB, entry count
+  ${cyan("status")}                     Show vault diagnostics
+  ${cyan("doctor")}                     Diagnose and repair common issues
+  ${cyan("restart")}                    Stop running MCP server processes (client auto-restarts)
+  ${cyan("search")}                     Search vault entries from CLI
+  ${cyan("save")}                       Save an entry to the vault from CLI
+  ${cyan("import")} <path>              Import entries from file, directory, or .zip archive
+  ${cyan("export")}                     Export vault entries (JSON, CSV, or portable ZIP)
+  ${cyan("ingest")} <url>               Fetch URL and save as vault entry
+  ${cyan("ingest-project")} <path>      Scan project directory and register as project entity
+  ${cyan("reindex")}                    Rebuild search index from knowledge files
+  ${cyan("migrate-dirs")} [--dry-run]   Rename plural vault dirs to singular (post-2.18.0)
+  ${cyan("archive")}                    Archive old ephemeral/event entries (use --dry-run to preview)
+  ${cyan("restore")} <id>               Restore an archived entry back into the vault
+  ${cyan("prune")}                      Remove expired entries (use --dry-run to preview)
+  ${cyan("update")}                     Check for and install updates
+  ${cyan("uninstall")}                  Remove MCP configs and optionally data
+`);
+
+  if (showAll) {
+    console.log(`${bold("Plumbing")} ${dim("(internal — hook implementations and maintenance utilities):")}
+  ${cyan("recall")}                     Search vault from a Claude Code hook (reads stdin)
+  ${cyan("session-capture")}            Save a session summary entry (reads JSON from stdin)
+  ${cyan("session-end")}                Run session-end hook (parse transcript + capture)
+  ${cyan("post-tool-call")}             Run post-tool-call hook (log tool usage)
+  ${cyan("flush")}                      Check vault health and confirm DB is accessible
+  ${cyan("consolidate")}                Find hot tags and cold entries for maintenance
+  ${cyan("migrate")}                    Migrate vault between local and hosted
+`);
+  } else {
+    console.log(`  ${dim("Run")} ${dim("context-vault --help --all")} ${dim("to show internal plumbing commands.")}
+`);
+  }
+
+  console.log(`${bold("Options:")}
   --help                Show this help
+  --help --all          Show all commands including internal plumbing
   --version             Show version
   --vault-dir <path>    Set vault directory (setup/serve)
   --yes                 Non-interactive mode (accept all defaults)
@@ -361,6 +374,26 @@ async function runSetup() {
     } catch {}
 
     if (latestVersion === VERSION) {
+      // Even when "up to date", ensure the launcher points to a valid server
+      const dataDir = join(HOME, ".context-mcp");
+      const launcherPath = join(dataDir, "server.mjs");
+      let launcherOk = false;
+      if (existsSync(launcherPath)) {
+        const content = readFileSync(launcherPath, "utf-8");
+        const m = content.match(/import "(.+?)"/);
+        if (m && existsSync(m[1])) launcherOk = true;
+      }
+      if (!launcherOk && !isNpx()) {
+        mkdirSync(dataDir, { recursive: true });
+        writeFileSync(launcherPath, `import "${SERVER_PATH}";\n`);
+        console.log(
+          green(`  ✓ context-vault v${VERSION} is up to date`) +
+            dim(`  (vault: ${existingVault})`),
+        );
+        console.log(dim(`  ↳ Repaired server launcher → ${SERVER_PATH}`));
+        console.log();
+        return;
+      }
       console.log(
         green(`  ✓ context-vault v${VERSION} is up to date`) +
           dim(`  (vault: ${existingVault})`),
@@ -788,7 +821,7 @@ async function runSetup() {
       }, 100);
 
       try {
-        const { embed } = await import("@context-vault/core/index/embed");
+        const { embed } = await import("@context-vault/core/embed");
         let timeoutHandle;
         const timeout = new Promise((_, reject) => {
           timeoutHandle = setTimeout(
@@ -1023,7 +1056,7 @@ async function runSetup() {
   // Verify DB is accessible
   let dbAccessible = false;
   try {
-    const { initDatabase } = await import("@context-vault/core/index/db");
+    const { initDatabase } = await import("@context-vault/core/db");
     const db = await initDatabase(vaultConfig.dbPath);
     db.prepare("SELECT 1").get();
     db.close();
@@ -1566,7 +1599,7 @@ async function runSwitch() {
   if (target === "local") {
     const launcherPath = join(dataDir, "server.mjs");
     if (!existsSync(launcherPath)) {
-      const serverAbs = resolve(ROOT, "src", "server", "index.js");
+      const serverAbs = resolve(ROOT, "src", "server.js");
       mkdirSync(dataDir, { recursive: true });
       writeFileSync(launcherPath, `import "${serverAbs}";\n`);
     }
@@ -1662,10 +1695,10 @@ async function runSwitch() {
 async function runReindex() {
   console.log(dim("Loading vault..."));
 
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { resolveConfig } = await import("@context-vault/core/config");
   const { initDatabase, prepareStatements, insertVec, deleteVec } =
-    await import("@context-vault/core/index/db");
-  const { embed } = await import("@context-vault/core/index/embed");
+    await import("@context-vault/core/db");
+  const { embed } = await import("@context-vault/core/embed");
   const { reindex } = await import("@context-vault/core/index");
 
   const config = resolveConfig();
@@ -1696,12 +1729,86 @@ async function runReindex() {
   console.log(`  ${dim("·")} ${stats.unchanged} unchanged`);
 }
 
+async function runMigrateDirs() {
+  const dryRun = flags.has("--dry-run");
+
+  // Vault dir: positional arg (skip --flags), or fall back to configured vault
+  const positional = args.slice(1).find((a) => !a.startsWith("--"));
+  let vaultDir = positional;
+
+  if (!vaultDir) {
+    const { resolveConfig } = await import("@context-vault/core/config");
+    const config = resolveConfig();
+    if (!config.vaultDirExists) {
+      console.error(red(`Vault directory not found: ${config.vaultDir}`));
+      console.error("Run " + cyan("context-vault setup") + " to configure.");
+      process.exit(1);
+    }
+    vaultDir = config.vaultDir;
+  }
+
+  if (!existsSync(vaultDir) || !statSync(vaultDir).isDirectory()) {
+    console.error(red(`Error: ${vaultDir} is not a directory`));
+    process.exit(1);
+  }
+
+  const { planMigration, executeMigration } =
+    await import("@context-vault/core/migrate-dirs");
+
+  const ops = planMigration(vaultDir);
+
+  if (ops.length === 0) {
+    console.log(green("✓ No plural directories found — vault is up to date."));
+    return;
+  }
+
+  if (dryRun) {
+    console.log(dim("Dry run — no files will be moved.\n"));
+  }
+
+  for (const op of ops) {
+    const fileLabel = `${op.fileCount} ${op.fileCount === 1 ? "file" : "files"}`;
+    const actionLabel = op.action === "rename" ? "RENAME" : "MERGE";
+    const suffix = dryRun ? dim(" [dry-run]") : "";
+    console.log(
+      `  ${cyan(actionLabel)}: ${op.pluralName}/ → ${op.singularName}/ (${fileLabel})${suffix}`,
+    );
+  }
+
+  if (dryRun) {
+    console.log();
+    console.log(
+      dim(
+        `  ${ops.length} ${ops.length === 1 ? "directory" : "directories"} would be renamed/merged.`,
+      ),
+    );
+    console.log(dim("  Remove --dry-run to apply."));
+    return;
+  }
+
+  const { renamed, merged, errors } = executeMigration(ops);
+
+  console.log();
+  if (renamed > 0) console.log(green(`✓ Renamed: ${renamed}`));
+  if (merged > 0) console.log(green(`✓ Merged:  ${merged}`));
+  if (errors.length > 0) {
+    for (const e of errors) console.log(red(`  ✗ ${e}`));
+  }
+
+  if (renamed + merged > 0) {
+    console.log();
+    console.log(
+      dim("Run `context-vault reindex` to rebuild the search index."),
+    );
+  }
+}
+
 async function runPrune() {
   const dryRun = flags.has("--dry-run");
 
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { resolveConfig } = await import("@context-vault/core/config");
   const { initDatabase, prepareStatements, insertVec, deleteVec } =
-    await import("@context-vault/core/index/db");
+    await import("@context-vault/core/db");
   const { pruneExpired } = await import("@context-vault/core/index");
 
   const config = resolveConfig();
@@ -1759,12 +1866,169 @@ async function runPrune() {
   }
 }
 
+async function runArchive() {
+  const dryRun = flags.has("--dry-run");
+
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { initDatabase, prepareStatements, insertVec, deleteVec } =
+    await import("@context-vault/core/db");
+  const { findArchiveCandidates, archiveEntries } =
+    await import("@context-vault/core/archive");
+
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red(`Vault directory not found: ${config.vaultDir}`));
+    console.error("Run " + cyan("context-vault setup") + " to configure.");
+    process.exit(1);
+  }
+
+  const db = await initDatabase(config.dbPath);
+
+  if (dryRun) {
+    const ctx = {
+      db,
+      config,
+      stmts: prepareStatements(db),
+      embed: async () => null,
+      insertVec: () => {},
+      deleteVec: () => {},
+    };
+    const candidates = findArchiveCandidates(ctx);
+    db.close();
+
+    if (candidates.length === 0) {
+      console.log(green("  No entries eligible for archiving."));
+      const lifecycle = config.lifecycle || {};
+      console.log(dim("\n  Retention windows:"));
+      for (const [tier, rules] of Object.entries(lifecycle)) {
+        if (rules?.archiveAfterDays) {
+          console.log(dim(`    ${tier}: archive after ${rules.archiveAfterDays} days`));
+        }
+      }
+      return;
+    }
+
+    console.log(
+      `\n  ${bold(String(candidates.length))} ${candidates.length === 1 ? "entry" : "entries"} eligible for archiving:\n`,
+    );
+    for (const e of candidates) {
+      const label = e.title ? `${e.kind}: ${e.title}` : `${e.kind} (${e.id})`;
+      const age = e.updated_at || e.created_at;
+      console.log(
+        `  ${dim("-")} ${label} ${dim(`(tier=${e.tier}, last updated ${age})`)}`,
+      );
+    }
+    console.log(dim("\n  Dry run — no entries were archived."));
+    console.log(dim("  Remove --dry-run to archive."));
+    return;
+  }
+
+  const stmts = prepareStatements(db);
+  const ctx = {
+    db,
+    config,
+    stmts,
+    embed: async () => null,
+    insertVec: (r, e) => insertVec(stmts, r, e),
+    deleteVec: (r) => deleteVec(stmts, r),
+  };
+
+  const result = await archiveEntries(ctx);
+  db.close();
+
+  if (result.count === 0) {
+    console.log(green("  No entries eligible for archiving."));
+  } else {
+    console.log(
+      green(
+        `  ✓ Archived ${result.count} ${result.count === 1 ? "entry" : "entries"} to _archive/`,
+      ),
+    );
+    console.log(
+      dim(`  Files moved to: ${join(config.vaultDir, "_archive")}`),
+    );
+    console.log(
+      dim("  Restore with: context-vault restore <id>"),
+    );
+  }
+}
+
+async function runRestore() {
+  const entryId = args[1];
+
+  if (!entryId || entryId.startsWith("--")) {
+    const { resolveConfig } = await import("@context-vault/core/config");
+    const { listArchivedEntries } =
+      await import("@context-vault/core/archive");
+
+    const config = resolveConfig();
+
+    console.log(`\n  ${bold("context-vault restore")} <id>\n`);
+    console.log(`  Restore an archived entry back into the active vault.\n`);
+
+    if (config.vaultDirExists) {
+      const entries = listArchivedEntries(config.vaultDir);
+      if (entries.length > 0) {
+        console.log(`  ${bold("Archived entries")} (${entries.length}):\n`);
+        for (const e of entries.slice(0, 20)) {
+          const label = e.title
+            ? `${e.kind}: ${e.title.slice(0, 60)}`
+            : `${e.kind} (${e.id})`;
+          console.log(`    ${dim(e.id || "?")}  ${label}`);
+        }
+        if (entries.length > 20) {
+          console.log(dim(`\n    ... and ${entries.length - 20} more`));
+        }
+      } else {
+        console.log(dim("  No archived entries found."));
+      }
+    }
+    console.log();
+    return;
+  }
+
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { initDatabase, prepareStatements, insertVec, deleteVec } =
+    await import("@context-vault/core/db");
+  const { embed } = await import("@context-vault/core/embed");
+  const { restoreEntry } = await import("@context-vault/core/archive");
+
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red(`Vault directory not found: ${config.vaultDir}`));
+    console.error("Run " + cyan("context-vault setup") + " to configure.");
+    process.exit(1);
+  }
+
+  const db = await initDatabase(config.dbPath);
+  const stmts = prepareStatements(db);
+  const ctx = {
+    db,
+    config,
+    stmts,
+    embed,
+    insertVec: (r, e) => insertVec(stmts, r, e),
+    deleteVec: (r) => deleteVec(stmts, r),
+  };
+
+  const result = await restoreEntry(ctx, entryId);
+  db.close();
+
+  if (result.restored) {
+    console.log(green(`  ✓ Restored ${result.kind} entry: ${result.id}`));
+    console.log(dim(`  File: ${result.filePath}`));
+  } else {
+    console.error(red(`  ✗ ${result.reason}`));
+    process.exit(1);
+  }
+}
+
 async function runStatus() {
-  const { resolveConfig } = await import("@context-vault/core/core/config");
-  const { initDatabase } = await import("@context-vault/core/index/db");
-  const { gatherVaultStatus } = await import("@context-vault/core/core/status");
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { initDatabase } = await import("@context-vault/core/db");
+  const { gatherVaultStatus } = await import("../src/status.js");
   const { errorLogPath, errorLogCount } =
-    await import("@context-vault/core/core/error-log");
+    await import("../src/error-log.js");
 
   const config = resolveConfig();
 
@@ -1827,7 +2091,7 @@ async function runStatus() {
       const filled = maxCount > 0 ? Math.round((c / maxCount) * BAR_WIDTH) : 0;
       const bar = "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
       const countStr = String(c).padStart(4);
-      console.log(`  ${countStr} ${kind}s   ${dim(bar)}`);
+      console.log(`    ${dim(bar)} ${countStr} ${kind}s`);
     }
   } else {
     console.log(`\n  ${dim("(empty — no entries indexed)")}`);
@@ -1853,6 +2117,15 @@ async function runStatus() {
     }
   }
 
+  if (status.archivedCount > 0) {
+    console.log();
+    console.log(
+      dim(
+        `  ${status.archivedCount} archived ${status.archivedCount === 1 ? "entry" : "entries"} in _archive/ (excluded from search)`,
+      ),
+    );
+  }
+
   if (status.stalePaths) {
     console.log();
     console.log(yellow("  Stale paths detected in DB."));
@@ -2044,7 +2317,7 @@ async function runMigrate() {
     return;
   }
 
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { resolveConfig } = await import("@context-vault/core/config");
   const config = resolveConfig();
 
   if (direction === "to-hosted") {
@@ -2098,20 +2371,33 @@ async function runImport() {
   const target = args[1];
   if (!target) {
     console.log(`\n  ${bold("context-vault import")} <path>\n`);
-    console.log(`  Import entries from a file or directory.\n`);
-    console.log(`  Supported formats: .md, .csv, .tsv, .json, .txt\n`);
+    console.log(`  Import entries from a file, directory, or portable archive.\n`);
+    console.log(`  Supported formats: .md, .csv, .tsv, .json, .txt, .zip\n`);
     console.log(`  Options:`);
     console.log(`    --kind <kind>    Default kind (default: insight)`);
     console.log(`    --source <src>   Default source (default: cli-import)`);
     console.log(`    --dry-run        Show parsed entries without importing`);
+    console.log(`    --vault <path>   Target vault directory (default: configured vault)`);
     console.log();
     return;
   }
 
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const dryRun = flags.has("--dry-run");
+  const targetPath = resolve(target);
+
+  if (!existsSync(targetPath)) {
+    console.error(red(`  Path not found: ${targetPath}`));
+    process.exit(1);
+  }
+
+  if (targetPath.endsWith(".zip")) {
+    return runImportZip(targetPath, dryRun);
+  }
+
+  const { resolveConfig } = await import("@context-vault/core/config");
   const { initDatabase, prepareStatements, insertVec, deleteVec } =
-    await import("@context-vault/core/index/db");
-  const { embed } = await import("@context-vault/core/index/embed");
+    await import("@context-vault/core/db");
+  const { embed } = await import("@context-vault/core/embed");
   const { parseFile, parseDirectory } =
     await import("@context-vault/core/capture/importers");
   const { importEntries } =
@@ -2120,13 +2406,6 @@ async function runImport() {
 
   const kind = getFlag("--kind") || undefined;
   const source = getFlag("--source") || "cli-import";
-  const dryRun = flags.has("--dry-run");
-
-  const targetPath = resolve(target);
-  if (!existsSync(targetPath)) {
-    console.error(red(`  Path not found: ${targetPath}`));
-    process.exit(1);
-  }
 
   const stat = statSync(targetPath);
   let entries;
@@ -2197,17 +2476,215 @@ async function runImport() {
   console.log();
 }
 
+async function runImportZip(zipPath, dryRun) {
+  const AdmZip = (await import("adm-zip")).default;
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { initDatabase, prepareStatements, insertVec, deleteVec } =
+    await import("@context-vault/core/db");
+  const { embed } = await import("@context-vault/core/embed");
+  const { indexEntry } = await import("@context-vault/core/index");
+  const { parseFrontmatter } = await import("@context-vault/core/frontmatter");
+  const { categoryDirFor } = await import("@context-vault/core/categories");
+  const { mkdirSync, writeFileSync, existsSync: existsFn } = await import("node:fs");
+  const { join: joinPath, basename: baseName } = await import("node:path");
+
+  let zip;
+  try {
+    zip = new AdmZip(zipPath);
+  } catch (e) {
+    console.error(red(`\n  Failed to open archive: ${e.message}\n`));
+    process.exit(1);
+  }
+
+  const manifestEntry = zip.getEntry("manifest.json");
+  if (!manifestEntry) {
+    console.error(red("\n  Invalid archive: missing manifest.json\n"));
+    process.exit(1);
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(zip.readAsText("manifest.json"));
+  } catch {
+    console.error(red("\n  Invalid archive: corrupt manifest.json\n"));
+    process.exit(1);
+  }
+
+  const indexEntry_ = zip.getEntry("index.json");
+  if (!indexEntry_) {
+    console.error(red("\n  Invalid archive: missing index.json\n"));
+    process.exit(1);
+  }
+
+  let index;
+  try {
+    index = JSON.parse(zip.readAsText("index.json"));
+  } catch {
+    console.error(red("\n  Invalid archive: corrupt index.json\n"));
+    process.exit(1);
+  }
+
+  const entries = index.entries || [];
+  if (entries.length === 0) {
+    console.log(yellow("\n  Archive contains no entries.\n"));
+    return;
+  }
+
+  console.log(`\n  ${bold("◇ context-vault import")} ${dim(baseName(zipPath))}`);
+  console.log(dim(`  Archive: v${manifest.version} · ${manifest.entry_count} entries · ${manifest.context_vault_version || "?"}`));
+
+  const kindCounts = {};
+  for (const e of entries) {
+    kindCounts[e.kind] = (kindCounts[e.kind] || 0) + 1;
+  }
+  console.log();
+  for (const [k, count] of Object.entries(kindCounts).sort((a, b) => b[1] - a[1])) {
+    console.log(`    ${k}: ${count}`);
+  }
+
+  const vaultDirOverride = getFlag("--vault");
+  const config = (await import("@context-vault/core/config")).resolveConfig();
+  const targetVaultDir = vaultDirOverride ? resolve(vaultDirOverride) : config.vaultDir;
+
+  if (!existsFn(targetVaultDir)) {
+    console.error(red(`\n  Vault directory not found: ${targetVaultDir}`));
+    console.error(`  Run ${cyan("context-vault setup")} to configure.`);
+    process.exit(1);
+  }
+
+  const db = await initDatabase(config.dbPath);
+  const stmts = prepareStatements(db);
+  const ctx = {
+    db,
+    config: { ...config, vaultDir: targetVaultDir },
+    stmts,
+    embed,
+    insertVec: (r, e) => insertVec(stmts, r, e),
+    deleteVec: (r) => deleteVec(stmts, r),
+  };
+
+  const existingIds = new Set();
+  const allIds = db.prepare("SELECT id FROM vault").all();
+  for (const row of allIds) existingIds.add(row.id);
+
+  let imported = 0;
+  let skippedDuplicate = 0;
+  let skippedMissing = 0;
+  let failed = 0;
+  const errors = [];
+
+  if (dryRun) {
+    for (let i = 0; i < Math.min(entries.length, 25); i++) {
+      const e = entries[i];
+      const isDuplicate = existingIds.has(e.id);
+      const tagStr = e.tags?.length ? ` ${dim(`[${e.tags.join(", ")}]`)}` : "";
+      const statusIcon = isDuplicate ? yellow("~") : green("+");
+      const statusText = isDuplicate ? dim(" (duplicate, would skip)") : "";
+      console.log(`\n  ${statusIcon} ${dim(`[${i + 1}]`)} ${e.kind} — ${e.title || e.id}${tagStr}${statusText}`);
+    }
+    if (entries.length > 25) {
+      console.log(dim(`\n  ... and ${entries.length - 25} more`));
+    }
+    const wouldSkip = entries.filter((e) => existingIds.has(e.id)).length;
+    console.log(`\n  ${dim(`Would import ${entries.length - wouldSkip}, skip ${wouldSkip} duplicates.`)}`);
+    console.log(dim("  Dry run — no entries were imported.\n"));
+    db.close();
+    return;
+  }
+
+  for (let i = 0; i < entries.length; i++) {
+    const entryMeta = entries[i];
+    process.stdout.write(`\r  Importing... ${i + 1}/${entries.length}`);
+
+    if (existingIds.has(entryMeta.id)) {
+      skippedDuplicate++;
+      continue;
+    }
+
+    const zipEntry = zip.getEntry(entryMeta.file);
+    if (!zipEntry) {
+      skippedMissing++;
+      continue;
+    }
+
+    const mdContent = zip.readAsText(entryMeta.file);
+    const { meta: fmMeta, body: rawBody } = parseFrontmatter(mdContent);
+
+    const kind = entryMeta.kind || fmMeta.kind || "insight";
+    const categoryDir = categoryDirFor(kind);
+    const targetDir = joinPath(targetVaultDir, categoryDir, kind);
+
+    try {
+      mkdirSync(targetDir, { recursive: true });
+
+      const fileName = baseName(entryMeta.file);
+      const filePath = joinPath(targetDir, fileName);
+      writeFileSync(filePath, mdContent);
+
+      const id = fmMeta.id || entryMeta.id;
+      const tags = Array.isArray(fmMeta.tags) ? fmMeta.tags : entryMeta.tags || [];
+      const title = fmMeta.title || entryMeta.title || null;
+      const source = fmMeta.source || entryMeta.source || "archive-import";
+      const identity_key = fmMeta.identity_key || entryMeta.identity_key || null;
+      const expires_at = fmMeta.expires_at || entryMeta.expires_at || null;
+      const createdAt = fmMeta.created || entryMeta.created_at || new Date().toISOString();
+
+      await indexEntry(ctx, {
+        id,
+        kind,
+        category: entryMeta.category || undefined,
+        title,
+        body: rawBody,
+        meta: null,
+        tags,
+        source,
+        filePath,
+        createdAt,
+        identity_key,
+        expires_at,
+      });
+
+      imported++;
+    } catch (e) {
+      failed++;
+      errors.push({ id: entryMeta.id, error: e.message });
+    }
+  }
+
+  db.close();
+
+  console.log(`\r  ${green("✓")} Import complete                    `);
+  console.log(`    ${green("+")} ${imported} imported`);
+  if (skippedDuplicate > 0) {
+    console.log(`    ${dim("~")} ${skippedDuplicate} skipped (already exist)`);
+  }
+  if (skippedMissing > 0) {
+    console.log(`    ${yellow("!")} ${skippedMissing} skipped (file missing in archive)`);
+  }
+  if (failed > 0) {
+    console.log(`    ${red("x")} ${failed} failed`);
+    for (const e of errors.slice(0, 5)) {
+      console.log(`      ${dim(e.error)}`);
+    }
+  }
+  console.log();
+}
+
 async function runExport() {
   const format = getFlag("--format") || "json";
-  const output = getFlag("--output");
+  const output = getFlag("--output") || getFlag("-o");
   const rawPageSize = getFlag("--page-size");
   const pageSize = rawPageSize
     ? Math.max(1, parseInt(rawPageSize, 10) || 100)
     : null;
 
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  if (format === "zip") {
+    return runExportZip();
+  }
+
+  const { resolveConfig } = await import("@context-vault/core/config");
   const { initDatabase, prepareStatements } =
-    await import("@context-vault/core/index/db");
+    await import("@context-vault/core/db");
   const { writeFileSync } = await import("node:fs");
 
   const config = resolveConfig();
@@ -2223,7 +2700,6 @@ async function runExport() {
 
   let entries;
   if (pageSize) {
-    // Paginated: fetch in chunks to avoid loading everything into memory
     entries = [];
     let offset = 0;
     const stmt = db.prepare(
@@ -2293,6 +2769,188 @@ async function runExport() {
   }
 }
 
+async function runExportZip() {
+  const output = getFlag("--output") || getFlag("-o");
+  const dryRun = flags.has("--dry-run");
+  const tagsRaw = getFlag("--tags");
+  const kindRaw = getFlag("--kind");
+  const since = getFlag("--since");
+  const until = getFlag("--until");
+  const exportAll = flags.has("--all");
+
+  const tagsFilter = tagsRaw
+    ? tagsRaw.split(",").map((t) => t.trim()).filter(Boolean)
+    : null;
+  const kindFilter = kindRaw
+    ? kindRaw.split(",").map((k) => k.trim()).filter(Boolean)
+    : null;
+
+  if (!exportAll && !tagsFilter && !kindFilter && !since && !until) {
+    console.log(`\n  ${bold("context-vault export --format zip")} [options]\n`);
+    console.log(`  Export vault entries as a portable ZIP archive.\n`);
+    console.log(`  ${bold("Filters (at least one required, or use --all):")}`);
+    console.log(`    --tags <t1,t2>       Filter by tags (comma-separated)`);
+    console.log(`    --kind <k1,k2>       Filter by kind (comma-separated)`);
+    console.log(`    --since <YYYY-MM-DD> Entries created on or after date`);
+    console.log(`    --until <YYYY-MM-DD> Entries created on or before date`);
+    console.log(`    --all                Export all entries\n`);
+    console.log(`  ${bold("Options:")}`);
+    console.log(`    --output, -o <path>  Output file path`);
+    console.log(`    --dry-run            Show what would be exported\n`);
+    console.log(`  ${bold("Examples:")}`);
+    console.log(`    context-vault export --tags stormfors --format zip -o stormfors.zip`);
+    console.log(`    context-vault export --kind decision,pattern --format zip`);
+    console.log(`    context-vault export --since 2026-01-01 --until 2026-02-28 --format zip`);
+    console.log(`    context-vault export --all --format zip --dry-run\n`);
+    return;
+  }
+
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { initDatabase } = await import("@context-vault/core/db");
+  const { readFileSync: readFs, existsSync: existsFn } = await import("node:fs");
+  const { basename } = await import("node:path");
+
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red(`  Vault directory not found: ${config.vaultDir}`));
+    process.exit(1);
+  }
+
+  const db = await initDatabase(config.dbPath);
+
+  const conditions = ["(expires_at IS NULL OR expires_at > datetime('now'))"];
+  const params = [];
+
+  if (tagsFilter) {
+    const tagClauses = tagsFilter.map(() =>
+      "EXISTS (SELECT 1 FROM json_each(vault.tags) WHERE json_each.value = ?)"
+    );
+    conditions.push(`(${tagClauses.join(" OR ")})`);
+    params.push(...tagsFilter);
+  }
+
+  if (kindFilter) {
+    const placeholders = kindFilter.map(() => "?").join(", ");
+    conditions.push(`kind IN (${placeholders})`);
+    params.push(...kindFilter);
+  }
+
+  if (since) {
+    conditions.push("created_at >= ?");
+    params.push(since.includes("T") ? since : `${since}T00:00:00.000Z`);
+  }
+
+  if (until) {
+    conditions.push("created_at <= ?");
+    params.push(until.includes("T") ? until : `${until}T23:59:59.999Z`);
+  }
+
+  const sql = `SELECT * FROM vault WHERE ${conditions.join(" AND ")} ORDER BY created_at DESC`;
+  const rows = db.prepare(sql).all(...params);
+  db.close();
+
+  if (rows.length === 0) {
+    console.log(yellow("\n  No entries match the given filters.\n"));
+    return;
+  }
+
+  const kindCounts = {};
+  for (const row of rows) {
+    kindCounts[row.kind] = (kindCounts[row.kind] || 0) + 1;
+  }
+
+  console.log(`\n  ${bold(String(rows.length))} entries match filters:\n`);
+  for (const [k, count] of Object.entries(kindCounts).sort((a, b) => b[1] - a[1])) {
+    console.log(`    ${k}: ${count}`);
+  }
+
+  const earliest = rows[rows.length - 1]?.created_at;
+  const latest = rows[0]?.created_at;
+  console.log(dim(`\n  Date range: ${earliest?.slice(0, 10) || "?"} → ${latest?.slice(0, 10) || "?"}`));
+
+  if (dryRun) {
+    console.log();
+    for (let i = 0; i < Math.min(rows.length, 25); i++) {
+      const r = rows[i];
+      const tags = safeJsonParse(r.tags, []);
+      const tagStr = tags.length ? ` ${dim(`[${tags.join(", ")}]`)}` : "";
+      console.log(`  ${dim(`[${i + 1}]`)} ${r.kind} — ${r.title || (r.body || "").slice(0, 60)}${tagStr}`);
+    }
+    if (rows.length > 25) {
+      console.log(dim(`  ... and ${rows.length - 25} more`));
+    }
+    console.log(dim("\n  Dry run — no archive created.\n"));
+    return;
+  }
+
+  const AdmZip = (await import("adm-zip")).default;
+  const zip = new AdmZip();
+
+  const indexEntries = [];
+  let filesSkipped = 0;
+
+  for (const row of rows) {
+    const entryPath = `entries/${row.kind}/${basename(row.file_path || `${row.id}.md`)}`;
+
+    let fileContent = null;
+    if (row.file_path && existsFn(row.file_path)) {
+      fileContent = readFs(row.file_path);
+    }
+
+    if (!fileContent) {
+      filesSkipped++;
+      continue;
+    }
+
+    zip.addFile(entryPath, fileContent);
+
+    indexEntries.push({
+      id: row.id,
+      kind: row.kind,
+      category: row.category,
+      title: row.title || null,
+      tags: safeJsonParse(row.tags, []),
+      source: row.source || null,
+      identity_key: row.identity_key || null,
+      expires_at: row.expires_at || null,
+      created_at: row.created_at,
+      file: entryPath,
+    });
+  }
+
+  const manifest = {
+    version: 1,
+    created_at: new Date().toISOString(),
+    context_vault_version: VERSION,
+    entry_count: indexEntries.length,
+    date_range: { earliest, latest },
+    filters: {
+      tags: tagsFilter || null,
+      kind: kindFilter || null,
+      since: since || null,
+      until: until || null,
+      all: exportAll || false,
+    },
+  };
+
+  zip.addFile("manifest.json", Buffer.from(JSON.stringify(manifest, null, 2)));
+  zip.addFile("index.json", Buffer.from(JSON.stringify({ entries: indexEntries }, null, 2)));
+
+  const today = new Date().toISOString().slice(0, 10);
+  const defaultName = tagsFilter
+    ? `vault-${tagsFilter[0]}-${today}.zip`
+    : `vault-export-${today}.zip`;
+  const outputPath = resolve(output || defaultName);
+
+  zip.writeZip(outputPath);
+
+  console.log(`\n  ${green("✓")} Exported ${indexEntries.length} entries to ${outputPath}`);
+  if (filesSkipped > 0) {
+    console.log(yellow(`  ⚠ ${filesSkipped} entries skipped (file not found on disk)`));
+  }
+  console.log();
+}
+
 function safeJsonParse(str, fallback) {
   if (!str) return fallback;
   try {
@@ -2361,10 +3019,10 @@ async function runIngest() {
     return;
   }
 
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { resolveConfig } = await import("@context-vault/core/config");
   const { initDatabase, prepareStatements, insertVec, deleteVec } =
-    await import("@context-vault/core/index/db");
-  const { embed } = await import("@context-vault/core/index/embed");
+    await import("@context-vault/core/db");
+  const { embed } = await import("@context-vault/core/embed");
   const { captureAndIndex } = await import("@context-vault/core/capture");
 
   const config = resolveConfig();
@@ -2428,10 +3086,10 @@ async function runIngestProject() {
 
   console.log(dim(`  Scanning ${projectPath}...`));
 
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { resolveConfig } = await import("@context-vault/core/config");
   const { initDatabase, prepareStatements, insertVec, deleteVec } =
-    await import("@context-vault/core/index/db");
-  const { embed } = await import("@context-vault/core/index/embed");
+    await import("@context-vault/core/db");
+  const { embed } = await import("@context-vault/core/embed");
   const { captureAndIndex } = await import("@context-vault/core/capture");
   const { existsSync: fsExists, readFileSync: fsRead } =
     await import("node:fs");
@@ -2642,21 +3300,21 @@ async function runRecall() {
 
   let db;
   try {
-    const { resolveConfig } = await import("@context-vault/core/core/config");
+    const { resolveConfig } = await import("@context-vault/core/config");
     const config = resolveConfig();
 
     if (!config.vaultDirExists) return;
 
     const { initDatabase, prepareStatements } =
-      await import("@context-vault/core/index/db");
-    const { embed } = await import("@context-vault/core/index/embed");
+      await import("@context-vault/core/db");
+    const { embed } = await import("@context-vault/core/embed");
     const { hybridSearch } = await import("@context-vault/core/retrieve/index");
 
     db = await initDatabase(config.dbPath);
     const stmts = prepareStatements(db);
     const ctx = { db, config, stmts, embed };
 
-    const { categoryFor } = await import("@context-vault/core/core/categories");
+    const { categoryFor } = await import("@context-vault/core/categories");
     const recall = config.recall;
 
     const results = await hybridSearch(ctx, query, {
@@ -2696,8 +3354,8 @@ async function runRecall() {
 }
 
 async function runFlush() {
-  const { resolveConfig } = await import("@context-vault/core/core/config");
-  const { initDatabase } = await import("@context-vault/core/index/db");
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { initDatabase } = await import("@context-vault/core/db");
 
   let db;
   try {
@@ -2743,12 +3401,12 @@ async function runSessionCapture() {
     }
     const { kind, title, body, tags, source } = payload;
     if (!kind || !body) return;
-    const { resolveConfig } = await import("@context-vault/core/core/config");
+    const { resolveConfig } = await import("@context-vault/core/config");
     const config = resolveConfig();
     if (!config.vaultDirExists) return;
     const { initDatabase, prepareStatements, insertVec, deleteVec } =
-      await import("@context-vault/core/index/db");
-    const { embed } = await import("@context-vault/core/index/embed");
+      await import("@context-vault/core/db");
+    const { embed } = await import("@context-vault/core/embed");
     const { captureAndIndex } = await import("@context-vault/core/capture");
     db = await initDatabase(config.dbPath);
     const stmts = prepareStatements(db);
@@ -2827,7 +3485,7 @@ async function runSave() {
 
   let db;
   try {
-    const { resolveConfig } = await import("@context-vault/core/core/config");
+    const { resolveConfig } = await import("@context-vault/core/config");
     const config = resolveConfig();
     if (!config.vaultDirExists) {
       console.error(
@@ -2836,8 +3494,8 @@ async function runSave() {
       process.exit(1);
     }
     const { initDatabase, prepareStatements, insertVec, deleteVec } =
-      await import("@context-vault/core/index/db");
-    const { embed } = await import("@context-vault/core/index/embed");
+      await import("@context-vault/core/db");
+    const { embed } = await import("@context-vault/core/embed");
     const { captureAndIndex } = await import("@context-vault/core/capture");
     db = await initDatabase(config.dbPath);
     const stmts = prepareStatements(db);
@@ -2881,6 +3539,7 @@ async function runSearch() {
   const sort = getFlag("--sort") || "relevance";
   const format = getFlag("--format") || "plain";
   const showFull = flags.has("--full");
+  const scopeArg = getFlag("--scope"); // "hot" | "events" | "all"
 
   const valuedFlags = new Set([
     "--kind",
@@ -2888,6 +3547,7 @@ async function runSearch() {
     "--limit",
     "--sort",
     "--format",
+    "--scope",
   ]);
 
   const queryParts = [];
@@ -2909,7 +3569,7 @@ async function runSearch() {
 
   let db;
   try {
-    const { resolveConfig } = await import("@context-vault/core/core/config");
+    const { resolveConfig } = await import("@context-vault/core/config");
     const config = resolveConfig();
     if (!config.vaultDirExists) {
       console.error(red("No vault found. Run: context-vault setup"));
@@ -2917,8 +3577,8 @@ async function runSearch() {
     }
 
     const { initDatabase, prepareStatements } =
-      await import("@context-vault/core/index/db");
-    const { embed } = await import("@context-vault/core/index/embed");
+      await import("@context-vault/core/db");
+    const { embed } = await import("@context-vault/core/embed");
     const { hybridSearch } = await import("@context-vault/core/retrieve/index");
 
     db = await initDatabase(config.dbPath);
@@ -2927,8 +3587,18 @@ async function runSearch() {
 
     let results;
 
+    // Resolve scope → category/exclude filter
+    const validScopes = new Set(["hot", "events", "all"]);
+    const resolvedScope = validScopes.has(scopeArg) ? scopeArg : "hot";
+    const scopeCategoryFilter = resolvedScope === "events" ? "event" : null;
+    const scopeExcludeEvents = resolvedScope === "hot";
+
     if (query) {
-      results = await hybridSearch(ctx, query, { limit: limit * 2 });
+      results = await hybridSearch(ctx, query, {
+        limit: limit * 2,
+        categoryFilter: scopeCategoryFilter,
+        excludeEvents: scopeExcludeEvents,
+      });
 
       if (kind) {
         results = results.filter((r) => r.kind === kind);
@@ -2941,6 +3611,10 @@ async function runSearch() {
         sql += " AND kind = ?";
         params.push(kind);
       }
+      if (scopeCategoryFilter) {
+        sql += " AND category = ?";
+        params.push(scopeCategoryFilter);
+      }
       sql += " ORDER BY COALESCE(updated_at, created_at) DESC LIMIT ?";
       params.push(limit);
       results = db.prepare(sql).all(...params);
@@ -3662,9 +4336,9 @@ ${bold("Commands:")}
 }
 
 async function runDoctor() {
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { resolveConfig } = await import("@context-vault/core/config");
   const { errorLogPath, errorLogCount } =
-    await import("@context-vault/core/core/error-log");
+    await import("../src/error-log.js");
 
   console.log();
   console.log(`  ${bold("◇ context-vault doctor")} ${dim(`v${VERSION}`)}`);
@@ -3738,7 +4412,7 @@ async function runDoctor() {
     let db;
     if (existsSync(config.dbPath)) {
       try {
-        const { initDatabase } = await import("@context-vault/core/index/db");
+        const { initDatabase } = await import("@context-vault/core/db");
         db = await initDatabase(config.dbPath);
         const schemaRow = db.prepare("PRAGMA user_version").get();
         const schemaVersion = schemaRow?.user_version ?? "unknown";
@@ -3760,7 +4434,7 @@ async function runDoctor() {
 
     // ── Embedding model ──────────────────────────────────────────────────
     try {
-      const { embed } = await import("@context-vault/core/index/embed");
+      const { embed } = await import("@context-vault/core/embed");
       const vec = await embed("doctor check");
       if (vec && vec.length > 0) {
         console.log(
@@ -3840,7 +4514,7 @@ async function runDoctor() {
             console.log(`    ${dim(`${row.created_at} — ${row.title}`)}`);
           }
           console.log(
-            `    ${dim('Review: context-vault search --kind feedback --tag auto-captured')}`,
+            `    ${dim("Review: context-vault search --kind feedback --tag auto-captured")}`,
           );
         }
       } catch {
@@ -3953,9 +4627,7 @@ async function runDoctor() {
         console.log(
           `  ${yellow("!")} ${tool.name}: using old name "context-mcp"`,
         );
-        console.log(
-          `    ${dim("Fix: run context-vault setup to update")}`,
-        );
+        console.log(`    ${dim("Fix: run context-vault setup to update")}`);
         anyToolConfigured = true;
       }
     } catch {
@@ -3979,9 +4651,7 @@ async function runDoctor() {
   }
 
   if (!anyToolConfigured) {
-    console.log(
-      `  ${yellow("!")} No AI tools have context-vault configured`,
-    );
+    console.log(`  ${yellow("!")} No AI tools have context-vault configured`);
     console.log(`    ${dim("Fix: run context-vault setup")}`);
     allOk = false;
   }
@@ -4106,14 +4776,10 @@ async function runDoctor() {
 
       if (hookCount === 0) {
         console.log(`  ${dim("-")} No context-vault hooks installed`);
-        console.log(
-          `    ${dim("Optional: run context-vault hooks install")}`,
-        );
+        console.log(`    ${dim("Optional: run context-vault hooks install")}`);
       }
     } catch {
-      console.log(
-        `  ${yellow("!")} Could not read ${settingsPath}`,
-      );
+      console.log(`  ${yellow("!")} Could not read ${settingsPath}`);
     }
   } else {
     console.log(`  ${dim("-")} No Claude Code settings found`);
@@ -4134,9 +4800,9 @@ async function runDoctor() {
 }
 
 async function runHealth() {
-  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { resolveConfig } = await import("@context-vault/core/config");
   const { initDatabase, testConnection } =
-    await import("@context-vault/core/index/db");
+    await import("@context-vault/core/db");
 
   let config;
   let healthy = true;
@@ -4325,8 +4991,8 @@ async function runConsolidate() {
   const dryRun = flags.has("--dry-run");
   const tagArg = getFlag("--tag");
 
-  const { resolveConfig } = await import("@context-vault/core/core/config");
-  const { initDatabase } = await import("@context-vault/core/index/db");
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { initDatabase } = await import("@context-vault/core/db");
   const { findHotTags, findColdEntries } =
     await import("@context-vault/core/consolidation/index");
 
@@ -4445,7 +5111,7 @@ async function runConsolidate() {
       );
       console.log(
         dim(
-          `  To archive: use context-vault search --kind <kind> and review manually.`,
+          `  To archive: run context-vault archive (or --dry-run to preview).`,
         ),
       );
     }
@@ -4455,7 +5121,7 @@ async function runConsolidate() {
 }
 
 async function runServe() {
-  await import("../src/server/index.js");
+  await import("../src/server.js");
 }
 
 async function main() {
@@ -4465,7 +5131,7 @@ async function main() {
   }
 
   if (flags.has("--help") || command === "help") {
-    showHelp();
+    showHelp(flags.has("--all"));
     return;
   }
 
@@ -4537,6 +5203,15 @@ async function main() {
     case "reindex":
       await runReindex();
       break;
+    case "migrate-dirs":
+      await runMigrateDirs();
+      break;
+    case "archive":
+      await runArchive();
+      break;
+    case "restore":
+      await runRestore();
+      break;
     case "prune":
       await runPrune();
       break;