context-vault 3.18.0 → 3.20.0

package/bin/cli.js

@@ -240,6 +240,17 @@ function getFlag(name) {
   return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
 }
 
+function getFlagAll(name) {
+  const results = [];
+  for (let i = 0; i < args.length - 1; i++) {
+    if (args[i] === name) {
+      const val = args[i + 1];
+      if (val && !val.startsWith('--')) results.push(val);
+    }
+  }
+  return results;
+}
+
 function prompt(question, defaultVal) {
   if (isNonInteractive) return Promise.resolve(defaultVal || '');
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -447,6 +458,9 @@ ${bold('Commands:')}
   ${cyan('reconnect')}                  Fix vault path, kill stale servers, re-register MCP, reindex
   ${cyan('search')}                     Search vault entries from CLI
   ${cyan('save')}                       Save an entry to the vault from CLI
+  ${cyan('get')} <id|key>              Fetch a single entry by ULID or identity key
+  ${cyan('buckets')}                    List registered buckets with entry counts
+  ${cyan('dupes')}                      Find near-duplicate entries (read-only)
   ${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
@@ -462,6 +476,7 @@ ${bold('Commands:')}
   ${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('delete')} <id>                 Hard-delete entry by ULID (DB + vec + file; clears superseded_by refs)
   ${cyan('stale')}                      List entries with low freshness scores
   ${cyan('stats')} recall|co-retrieval  Measure recall ratio and co-retrieval graph
   ${cyan('remote')} setup|status|sync|pull  Connect to hosted vault (cloud sync)
@@ -2683,6 +2698,118 @@ async function runPrune() {
   }
 }
 
+async function runDelete() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault delete')} <id> [options]
+
+  Hard-delete a vault entry by ULID. Removes the DB row, vector-index row,
+  and the markdown file on disk. Also clears any ${cyan('superseded_by')} refs
+  on other entries that pointed at this one (no dangling links).
+
+  Distinct from ${cyan('archive')} (soft, reversible via ${cyan('restore')})
+  and ${cyan('prune')} (bulk by expiry policy).
+
+${bold('Usage:')}
+  context-vault delete <id>            Delete entry by ULID
+  context-vault delete <id> --dry-run  Show what would be deleted, no changes
+  context-vault delete <id> --yes      Skip confirmation prompt
+
+${bold('Examples:')}
+  context-vault delete 01KQ0123456789ABCDEFGHJKMN
+  context-vault delete 01KQ0123456789ABCDEFGHJKMN --yes
+`);
+    return;
+  }
+
+  const entryId = args[1];
+  if (!entryId || entryId.startsWith('--')) {
+    console.error(red('Error: entry id is required'));
+    console.error(`Usage: ${cyan('context-vault delete <id>')}`);
+    process.exit(1);
+  }
+
+  const dryRun = flags.has('--dry-run');
+
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase, prepareStatements, deleteVec } = await import('@context-vault/core/db');
+
+  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);
+  try {
+    const stmts = prepareStatements(db);
+    const row = stmts.getEntryById.get(entryId);
+    if (!row) {
+      console.error(red(`Error: no entry found with id ${entryId}`));
+      process.exit(1);
+    }
+
+    const label = row.title ? `${row.kind}: ${row.title}` : `${row.kind} (${row.id})`;
+    const filePath = row.file_path || null;
+
+    if (dryRun) {
+      console.log(`\n  Would delete: ${label}`);
+      if (filePath) console.log(dim(`    file: ${filePath}`));
+      console.log(dim(`    id:   ${row.id}`));
+      const referrers = db
+        .prepare('SELECT id, kind, title FROM vault WHERE superseded_by = ?')
+        .all(entryId);
+      if (referrers.length) {
+        console.log(dim(`    ${referrers.length} entr${referrers.length === 1 ? 'y has' : 'ies have'} superseded_by pointing here; those refs would be cleared:`));
+        for (const r of referrers) {
+          const rlabel = r.title ? `${r.kind}: ${r.title}` : `${r.kind} (${r.id})`;
+          console.log(dim(`      - ${rlabel}`));
+        }
+      }
+      console.log(dim('\n  Dry run — nothing changed.'));
+      return;
+    }
+
+    if (!isNonInteractive) {
+      const answer = await prompt(`Delete ${label}? (y/N)`, 'N');
+      if (!/^y(es)?$/i.test((answer || '').trim())) {
+        console.log(dim('  Aborted.'));
+        return;
+      }
+    }
+
+    const rowidRow = stmts.getRowid.get(entryId);
+    if (rowidRow?.rowid) {
+      try {
+        deleteVec(stmts, Number(rowidRow.rowid));
+      } catch {}
+    }
+    try {
+      stmts.clearSupersededByRef.run(entryId);
+    } catch {}
+    stmts.deleteEntry.run(entryId);
+
+    if (filePath) {
+      try {
+        unlinkSync(filePath);
+      } catch (e) {
+        if (e?.code !== 'ENOENT') {
+          console.error(yellow(`  Warning: could not remove file: ${e.message}`));
+        }
+      }
+    }
+
+    console.log(`${green('✓')} Deleted ${label}`);
+    console.log(dim(`  id: ${entryId}`));
+    if (filePath) console.log(dim(`  file removed: ${filePath}`));
+  } finally {
+    try {
+      db.close();
+    } catch {}
+  }
+}
+
 async function runArchive() {
   const dryRun = flags.has('--dry-run');
 
@@ -2908,6 +3035,226 @@ async function runCompact() {
   console.log(dim('  Use context-vault restore <id> to recover full body.'));
 }
 
+async function runGet() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault get')} <id|identity-key> [options]
+
+  Fetch a single vault entry by ULID or by identity key.
+
+${bold('Usage:')}
+  context-vault get 01KQ0123456789ABCDEFGHJKMN
+  context-vault get bucket:myproject --kind bucket
+  context-vault get myproject --kind bucket
+  context-vault get <id> --format json
+
+${bold('Options:')}
+  --kind <kind>     Resolve the argument as an identity key for this kind
+  --format <fmt>    Output format: plain (default), json
+  --full            Show full entry body (not truncated)
+`);
+    return;
+  }
+
+  const ref = args[1];
+  if (!ref || ref.startsWith('--')) {
+    console.error(red('Error: entry id or identity key is required'));
+    console.error(`Usage: ${cyan('context-vault get <id|identity-key>')}`);
+    process.exit(1);
+  }
+
+  const kindFlag = getFlag('--kind');
+  const format = getFlag('--format') || 'plain';
+  const showFull = flags.has('--full');
+
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase, prepareStatements } = await import('@context-vault/core/db');
+
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red('No vault found. Run: context-vault setup'));
+    process.exit(1);
+  }
+
+  const db = await initDatabase(config.dbPath);
+  try {
+    const stmts = prepareStatements(db);
+
+    let row = null;
+    if (kindFlag) {
+      const key = ref.includes(':') ? ref : `${kindFlag}:${ref}`;
+      row = stmts.getByIdentityKey.get(kindFlag, key) || stmts.getByIdentityKey.get(kindFlag, ref);
+    } else {
+      row = stmts.getEntryById.get(ref);
+      if (!row && ref.includes(':')) {
+        const inferredKind = ref.slice(0, ref.indexOf(':'));
+        row = stmts.getByIdentityKey.get(inferredKind, ref);
+      }
+    }
+
+    if (!row) {
+      console.error(red(`Error: no entry found for "${ref}"${kindFlag ? ` (kind ${kindFlag})` : ''}`));
+      process.exit(1);
+    }
+
+    if (format === 'json') {
+      console.log(JSON.stringify(row, null, 2));
+      return;
+    }
+
+    const tags = row.tags ? JSON.parse(row.tags) : [];
+    console.log(`\n  ${bold(row.title || `${row.kind} (${row.id})`)}`);
+    console.log(dim(`  id:      ${row.id}`));
+    console.log(dim(`  kind:    ${row.kind}${row.category ? `  category: ${row.category}` : ''}`));
+    if (row.identity_key) console.log(dim(`  key:     ${row.identity_key}`));
+    if (tags.length) console.log(dim(`  tags:    ${tags.join(', ')}`));
+    console.log(dim(`  created: ${row.created_at}${row.updated_at ? `  updated: ${row.updated_at}` : ''}`));
+    if (row.superseded_by) console.log(yellow(`  superseded_by: ${row.superseded_by}`));
+    const body = row.body || '';
+    const shown = showFull ? body : body.slice(0, 2000);
+    console.log('\n' + shown + (shown.length < body.length ? dim('\n  … (truncated; use --full)') : ''));
+  } finally {
+    db.close();
+  }
+}
+
+async function runBuckets() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault buckets')} [options]
+
+  List all registered bucket entities with entry counts. Buckets are named
+  scopes that group entries via ${cyan('bucket:')}-prefixed tags.
+
+${bold('Options:')}
+  --format <fmt>    Output format: plain (default), json
+`);
+    return;
+  }
+
+  const format = getFlag('--format') || 'plain';
+
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase } = await import('@context-vault/core/db');
+
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red('No vault found. Run: context-vault setup'));
+    process.exit(1);
+  }
+
+  const db = await initDatabase(config.dbPath);
+  try {
+    const buckets = db
+      .prepare(
+        `SELECT id, title, identity_key, body, tags, created_at, updated_at
+           FROM vault
+          WHERE kind = 'bucket'
+            AND (expires_at IS NULL OR expires_at > datetime('now'))
+            AND superseded_by IS NULL
+          ORDER BY title ASC`
+      )
+      .all();
+
+    const withCounts = buckets.map((b) => {
+      const name = b.identity_key?.replace(/^bucket:/, '') || b.title;
+      const c = db
+        .prepare(
+          `SELECT COUNT(*) AS c FROM vault
+            WHERE superseded_by IS NULL
+              AND (expires_at IS NULL OR expires_at > datetime('now'))
+              AND tags LIKE ?`
+        )
+        .get(`%"bucket:${name}"%`);
+      return { ...b, name, entry_count: c?.c ?? 0 };
+    });
+
+    if (format === 'json') {
+      console.log(JSON.stringify(withCounts, null, 2));
+      return;
+    }
+
+    if (!withCounts.length) {
+      console.log(dim('  No buckets registered.'));
+      return;
+    }
+
+    console.log(`\n  ${bold(`Registered buckets (${withCounts.length})`)}\n`);
+    for (const b of withCounts) {
+      const desc = b.body ? ` — ${b.body.split('\n')[0].slice(0, 60)}` : '';
+      console.log(`  ${cyan(b.name)} ${dim(`(${b.entry_count})`)}${dim(desc)}`);
+    }
+  } finally {
+    db.close();
+  }
+}
+
+async function runDupes() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault dupes')} [options]
+
+  Find near-duplicate entries by semantic + title similarity. Read-only —
+  reports groups, changes nothing.
+
+${bold('Options:')}
+  --threshold <n>   Similarity threshold 0..1 (default: 0.85)
+  --limit <n>       Max duplicate groups (default: 50)
+  --kind <kind>     Restrict to a single kind
+  --format <fmt>    Output format: plain (default), json
+`);
+    return;
+  }
+
+  const threshold = parseFloat(getFlag('--threshold') || '0.85');
+  const limit = parseInt(getFlag('--limit') || '50', 10);
+  const kind = getFlag('--kind') || undefined;
+  const format = getFlag('--format') || 'plain';
+
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase, prepareStatements } = await import('@context-vault/core/db');
+  const { embed } = await import('@context-vault/core/embed');
+  const { findDuplicates } = await import('@context-vault/core/consolidation');
+
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red('No vault found. Run: context-vault setup'));
+    process.exit(1);
+  }
+
+  const db = await initDatabase(config.dbPath);
+  try {
+    const stmts = prepareStatements(db);
+    const ctx = { db, config, stmts, embed };
+    const groups = await findDuplicates(ctx, { threshold, limit, kind, dryRun: true });
+
+    if (format === 'json') {
+      console.log(JSON.stringify(groups, null, 2));
+      return;
+    }
+
+    if (!groups.length) {
+      console.log(dim(`  No near-duplicates found (threshold ${threshold}).`));
+      return;
+    }
+
+    console.log(`\n  ${bold(`Near-duplicate groups (${groups.length})`)} ${dim(`threshold ${threshold}`)}\n`);
+    for (const g of groups) {
+      const dupCount = (g.duplicate_ids?.length ?? 0) + 1;
+      console.log(`  ${yellow(`${dupCount}×`)} ${g.canonical_title || ''} ${dim(`sim ${g.similarity}`)}`);
+      console.log(dim(`      canonical: ${g.canonical_id}`));
+      for (const id of g.duplicate_ids ?? []) {
+        console.log(dim(`      dup:       ${id}`));
+      }
+      for (const t of g.sample_titles ?? []) {
+        console.log(dim(`        · ${t}`));
+      }
+    }
+  } finally {
+    db.close();
+  }
+}
+
 async function runStatus() {
   const { resolveConfig } = await import('@context-vault/core/config');
   const { initDatabase } = await import('@context-vault/core/db');
@@ -4181,7 +4528,7 @@ ${bold('Examples:')}
   const dryRun = flags.has('--dry-run');
   const verbose = flags.has('--verbose');
 
-  const GMAIL_CLI_PATH = '/Users/admin/omni/workspaces/_archive/agent-tools/gmail-cli/cli.ts';
+  const GMAIL_CLI_PATH = join(homedir(), 'omni/workspaces/_archive/agent-tools/gmail-cli/cli.ts');
   const SKIP_LABELS = new Set([
     'CATEGORY_PROMOTIONS',
     'CATEGORY_SOCIAL',
@@ -4322,7 +4669,7 @@ ${bold('Examples:')}
 }
 
 async function runSlackBridge() {
-  const SLACK_CLI_PATH = '/Users/admin/omni/workspaces/_archive/agent-tools/slack-cli/cli.ts';
+  const SLACK_CLI_PATH = join(homedir(), 'omni/workspaces/_archive/agent-tools/slack-cli/cli.ts');
 
   if (flags.has('--help') || (!flags.has('--list-channels') && !getFlag('--channels'))) {
     console.log(`
@@ -5156,10 +5503,19 @@ ${bold('Optional:')}
   --source <source>    Source label (default: cli)
   --identity-key <key> Identity key (for entity kinds)
   --meta <json>        Additional metadata as JSON
+  --supersedes <id>    Mark this entry as superseding an existing entry
+                       (can be passed multiple times; old entries get
+                       reciprocal superseded_by link to this new entry)
+  --related-to <id>    Add a related-to link to another entry by ULID
+                       (can be passed multiple times; builds the graph)
 
 ${bold('Examples:')}
   context-vault save --kind insight --title "Express 5 gotcha" --body "body parser changed"
   echo "content" | context-vault save --kind reference --title "API notes"
+  context-vault save --kind decision --title "revised plan" --body "..." \\
+    --supersedes 01K9... --supersedes 01KA...
+  context-vault save --kind insight --title "graph node" --body "..." \\
+    --related-to 01KB... --related-to 01KC...
 `);
     return;
   }
@@ -5173,6 +5529,8 @@ ${bold('Examples:')}
   const bodyFlag = getFlag('--body');
   const identityKey = getFlag('--identity-key');
   const metaRaw = getFlag('--meta');
+  const supersedesList = getFlagAll('--supersedes');
+  const relatedToList = getFlagAll('--related-to');
 
   if (!kind) {
     console.error(red('Error: --kind is required'));
@@ -5248,8 +5606,17 @@ ${bold('Examples:')}
       ...(tier ? { tier } : {}),
       ...(identityKey ? { identity_key: identityKey } : {}),
       ...(meta !== undefined ? { meta } : {}),
+      ...(supersedesList.length ? { supersedes: supersedesList } : {}),
+      ...(relatedToList.length ? { related_to: relatedToList } : {}),
     });
     console.log(`${green('✓')} Saved ${kind} — id: ${entry.id}`);
+    if (supersedesList.length) {
+      console.log(dim(`  supersedes: ${supersedesList.join(', ')}`));
+      console.log(dim(`  (reciprocal superseded_by written to ${supersedesList.length} entr${supersedesList.length === 1 ? 'y' : 'ies'})`));
+    }
+    if (relatedToList.length) {
+      console.log(dim(`  related_to: ${relatedToList.join(', ')}`));
+    }
   } catch (e) {
     console.error(`${red('x')} Failed to save: ${e.message}`);
     process.exit(1);
@@ -5387,6 +5754,8 @@ ${bold('Options:')}
         created_at: r.created_at,
         updated_at: r.updated_at,
         body: showFull ? r.body : r.body?.slice(0, 200) || '',
+        summary_condensed: r.summary_condensed || null,
+        summary_keypoint: r.summary_keypoint || null,
       }));
       console.log(JSON.stringify(output, null, 2));
     } else if (format === 'table') {
@@ -6555,6 +6924,104 @@ async function runDoctor() {
       console.log(`    ${dim('Fix: run context-vault setup to download the model')}`);
     }
 
+    // ── Save/search roundtrip ────────────────────────────────────────────
+    // Canary save→search check against the LIVE vault. Detects within seconds
+    // when captureAndIndex returns success but data didn't land in the DB or
+    // isn't findable via search (the 2026-04-19 silent-drift incident class).
+    // kind='event' so the canary is never embedded — keeps the test stable
+    // when embeddings are degraded.
+    if (db) {
+      let canaryEntry = null;
+      let canaryStmts = null;
+      let dbMod = null;
+      try {
+        dbMod = await import('@context-vault/core/db');
+        const { embed } = await import('@context-vault/core/embed');
+        const { captureAndIndex } = await import('@context-vault/core/capture');
+        const { hybridSearch } = await import('@context-vault/core/search');
+
+        canaryStmts = dbMod.prepareStatements(db);
+
+        // Single alphanumeric token: stays one FTS term (no hyphen/underscore
+        // splitting), uniquely identifies the canary in tag-search fallback,
+        // and avoids collisions with anything else in the live vault.
+        const canaryRand =
+          Math.random().toString(36).slice(2, 10) + Math.random().toString(36).slice(2, 10);
+        const canaryToken = `dcanary${canaryRand}`;
+
+        const ctx = {
+          db,
+          config,
+          stmts: canaryStmts,
+          embed,
+          insertVec: (rowid, embedding) => dbMod.insertVec(canaryStmts, rowid, embedding),
+          deleteVec: (rowid) => dbMod.deleteVec(canaryStmts, rowid),
+          insertCtxVec: () => {},
+          deleteCtxVec: () => {},
+        };
+
+        canaryEntry = await captureAndIndex(ctx, {
+          kind: 'event',
+          title: 'doctor-canary',
+          body: canaryToken,
+          tags: [canaryToken, 'doctor-canary'],
+          source: 'doctor',
+        });
+
+        // Verify the persisted DB row matches what we saved before searching —
+        // catches the silent-wedge case where captureAndIndex returns success
+        // but the row never landed.
+        const persisted = canaryStmts.getEntryById.get(canaryEntry.id);
+        if (!persisted) {
+          throw new Error('canary save returned success but row missing from DB');
+        }
+        if (persisted.body !== canaryToken) {
+          throw new Error('canary persisted with wrong body');
+        }
+
+        // kindFilter='event' scopes the search to events only. Events are not
+        // embedded, so the vec lane is bypassed and the canary doesn't have to
+        // out-rank thousands of recalled knowledge entries to make the page.
+        const results = await hybridSearch(ctx, canaryToken, {
+          kindFilter: 'event',
+          limit: 10,
+        });
+        const found = results.find((r) => r.id === canaryEntry.id);
+        if (!found) {
+          throw new Error('canary saved but not returned by search');
+        }
+        if (found.body !== canaryToken) {
+          throw new Error('canary found but body mismatch');
+        }
+
+        console.log(`  ${green('✓')} Save/search roundtrip`);
+      } catch (e) {
+        console.log(`  ${red('✘')} Save/search roundtrip: ${e.message}`);
+        allOk = false;
+      } finally {
+        if (canaryEntry) {
+          try {
+            if (existsSync(canaryEntry.filePath)) {
+              unlinkSync(canaryEntry.filePath);
+            }
+          } catch {}
+          if (canaryStmts && dbMod) {
+            try {
+              const rowidRow = canaryStmts.getRowid.get(canaryEntry.id);
+              if (rowidRow?.rowid) {
+                try {
+                  dbMod.deleteVec(canaryStmts, Number(rowidRow.rowid));
+                } catch {}
+              }
+            } catch {}
+            try {
+              canaryStmts.deleteEntry.run(canaryEntry.id);
+            } catch {}
+          }
+        }
+      }
+    }
+
     // ── DB/filesystem consistency ─────────────────────────────────────────
     if (db && existsSync(config.vaultDir)) {
       try {
@@ -7400,11 +7867,46 @@ async function runStats() {
     await runStatsRecall({ resolveConfig, initDatabase, gatherRecallSummary });
   } else if (sub === 'co-retrieval') {
     await runStatsCoRetrieval({ resolveConfig, initDatabase, gatherCoRetrievalSummary });
+  } else if (sub === 'counts') {
+    await runStatsCounts({ resolveConfig, initDatabase });
   } else {
     console.error(red(`  Unknown stats subcommand: ${sub}`));
-    console.error(`  Available: recall, co-retrieval`);
+    console.error(`  Available: recall, co-retrieval, counts`);
+    process.exit(1);
+  }
+}
+
+async function runStatsCounts({ resolveConfig, initDatabase }) {
+  const format = getFlag('--format') || 'plain';
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red('No vault found. Run: context-vault setup'));
     process.exit(1);
   }
+  const db = await initDatabase(config.dbPath);
+  try {
+    const live = `superseded_by IS NULL AND (expires_at IS NULL OR expires_at > datetime('now'))`;
+    const total = db.prepare(`SELECT COUNT(*) AS c FROM vault WHERE ${live}`).get()?.c ?? 0;
+    const byKind = db
+      .prepare(`SELECT kind AS name, COUNT(*) AS count FROM vault WHERE ${live} GROUP BY kind ORDER BY count DESC`)
+      .all();
+    const byCategory = db
+      .prepare(`SELECT category AS name, COUNT(*) AS count FROM vault WHERE ${live} GROUP BY category ORDER BY count DESC`)
+      .all();
+
+    if (format === 'json') {
+      console.log(JSON.stringify({ total_entries: total, by_kind: byKind, by_category: byCategory }, null, 2));
+      return;
+    }
+
+    console.log(`\n  ${bold('Vault counts')}  ${dim(`total ${total}`)}\n`);
+    console.log(`  ${bold('By category')}`);
+    for (const c of byCategory) console.log(`    ${cyan((c.name || 'unknown').padEnd(12))} ${c.count}`);
+    console.log(`\n  ${bold('By kind')}`);
+    for (const k of byKind) console.log(`    ${cyan((k.name || 'unknown').padEnd(16))} ${k.count}`);
+  } finally {
+    db.close();
+  }
 }
 
 async function runStatsRecall({ resolveConfig, initDatabase, gatherRecallSummary }) {
@@ -8810,6 +9312,155 @@ ${bold('Examples:')}
   }
 }
 
+async function runSummarize() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault summarize')} [options]
+
+  Backfill precomputed summary tiers for vault entries.
+
+${bold('Usage:')}
+  context-vault summarize              # backfill entries missing summaries
+  context-vault summarize --force      # regenerate all summaries
+  context-vault summarize --dry-run    # show count of entries needing summaries
+
+${bold('Options:')}
+  --dry-run       Show count without processing
+  --force         Regenerate summaries for all entries (not just missing)
+`);
+    return;
+  }
+
+  const dryRun = flags.has('--dry-run');
+  const force = flags.has('--force');
+
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase } = await import('@context-vault/core/db');
+  const { generateSummaryTiers } = await import('@context-vault/core/summarize');
+
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red('No vault found. Run: context-vault setup'));
+    process.exit(1);
+  }
+
+  let db;
+  try {
+    db = await initDatabase(config.dbPath);
+  } catch (e) {
+    console.error(red(`Database error: ${e.message}`));
+    process.exit(1);
+  }
+
+  try {
+    const whereClause = force
+      ? 'WHERE superseded_by IS NULL'
+      : 'WHERE summary_condensed IS NULL AND superseded_by IS NULL';
+    const rows = db.prepare(`SELECT id, body FROM vault ${whereClause}`).all();
+
+    if (dryRun) {
+      console.log(`${rows.length} entries need summary generation${force ? ' (force mode)' : ''}`);
+      db.close();
+      return;
+    }
+
+    if (rows.length === 0) {
+      console.log(green('All entries already have summaries.'));
+      db.close();
+      return;
+    }
+
+    const updateStmt = db.prepare(
+      'UPDATE vault SET summary_condensed = ?, summary_keypoint = ? WHERE id = ?'
+    );
+    const BATCH = 50;
+    let processed = 0;
+
+    for (let i = 0; i < rows.length; i += BATCH) {
+      const batch = rows.slice(i, i + BATCH);
+      db.exec('BEGIN');
+      try {
+        for (const row of batch) {
+          const { condensed, keypoint } = generateSummaryTiers(row.body || '');
+          updateStmt.run(condensed || null, keypoint || null, row.id);
+          processed++;
+        }
+        db.exec('COMMIT');
+      } catch (e) {
+        db.exec('ROLLBACK');
+        throw e;
+      }
+      process.stderr.write(`\r  Processing: ${processed}/${rows.length}`);
+    }
+
+    process.stderr.write('\n');
+    console.log(green(`Done. Generated summaries for ${processed} entries.`));
+  } catch (e) {
+    console.error(red(`Summarize failed: ${e.message}`));
+    process.exit(1);
+  } finally {
+    try { db?.close(); } catch {}
+  }
+}
+
+
+async function runAssemble() {
+  if (flags.has("--help")) {
+    console.log(`\n  ${bold("context-vault assemble")} [options]\n\n  Assemble a role-aware, task-specific context payload.\n\n${bold("Usage:")}\n  context-vault assemble --role <role> --task <spec-path-or-text> --budget <tokens>\n\n${bold("Options:")}\n  --role <role>      Agent role (worker, pm, ceo, steer)\n  --task <text>      Task description or spec path\n  --budget <n>       Max tokens for the payload (default: 40000)\n  --format <fmt>     Output format: markdown (default), json\n  --dry-run          Show assembly plan but do not output full context\n`);
+    return;
+  }
+  
+  const role = getFlag("--role") || "worker";
+  const task = getFlag("--task");
+  const format = getFlag("--format") || "markdown";
+  const { resolveConfig } = await import("@context-vault/core/config");
+  const { initDatabase } = await import("@context-vault/core/db");
+  const { assembleContext } = await import("@context-vault/core");
+
+  const budget = parseInt(getFlag("--budget") || "40000", 10);
+  const dryRun = flags.has("--dry-run");
+
+  if (!task) {
+    console.error(`\n  ${red("Usage:")} context-vault assemble --role <role> --task <task>\n`);
+    process.exit(1);
+  }
+
+    const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red("No vault found."));
+    process.exit(1);
+  }
+  const db = await initDatabase(config.dbPath);
+  const result = await assembleContext(db, config, { role: role, task, budget });
+  if (format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    if (dryRun) {
+      const lines = [
+        `Assembly Plan:`,
+        `- Role: ${result.metadata.role}`,
+        `- Budget: ${result.metadata.budget} tokens`,
+        `- Used: ${result.metadata.tokens_used} tokens`,
+        `- Entries Included: ${result.metadata.entries_included}`,
+      ];
+      const included = result.metadata.included_entries || [];
+      if (included.length > 0) {
+        lines.push(`\nIncluded Entries:`);
+        for (const e of included) {
+          lines.push(`  [${e.status}] ${e.title}`);
+        }
+      } else {
+        lines.push(`\nIncluded Entries: (none)`);
+      }
+      console.log(lines.join('\n'));
+    } else {
+      console.log(result.markdown);
+    }
+  }
+  try { db.close(); } catch {}
+
+}
+
 async function runStale() {
   if (flags.has('--help')) {
     console.log(`
@@ -8929,7 +9580,7 @@ async function main() {
 
   if (flags.has('--help') || command === 'help') {
     // Commands with their own --help handling: delegate to them
-    const commandsWithHelp = new Set(['save', 'search', 'rules', 'hooks', 'team', 'remote', 'ingest-comms', 'gmail-bridge', 'slack-bridge', 'contacts']);
+    const commandsWithHelp = new Set(['save', 'search', 'rules', 'hooks', 'team', 'remote', 'ingest-comms', 'gmail-bridge', 'slack-bridge', 'contacts', 'delete', 'get', 'buckets', 'dupes']);
     if (!command || command === 'help' || !commandsWithHelp.has(command)) {
       showHelp(flags.has('--all'));
       return;
@@ -9042,6 +9693,18 @@ async function main() {
     case 'prune':
       await runPrune();
       break;
+    case 'delete':
+      await runDelete();
+      break;
+    case 'get':
+      await runGet();
+      break;
+    case 'buckets':
+      await runBuckets();
+      break;
+    case 'dupes':
+      await runDupes();
+      break;
     case 'status':
       await runStatus();
       break;
@@ -9091,9 +9754,15 @@ async function main() {
     case 'compact':
       await runCompact();
       break;
+    case 'assemble':
+      await runAssemble();
+      break;
     case 'stale':
       await runStale();
       break;
+    case 'summarize':
+      await runSummarize();
+      break;
     default:
       console.error(red(`Unknown command: ${command}`));
       console.error(`Run ${cyan('context-vault --help')} for usage.`);