context-vault 3.16.1 → 3.17.0

package/bin/cli.js

@@ -451,6 +451,10 @@ ${bold('Commands:')}
   ${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('ingest-comms')}              Ingest structured comms from stdin (JSON lines, with dedup)
+  ${cyan('gmail-bridge')}              Fetch recent emails via gmail-cli and ingest into vault
+  ${cyan('slack-bridge')}              Fetch Slack messages from allowed channels and ingest
+  ${cyan('contacts')} list|show|add     Manage contact entities in the vault
   ${cyan('reindex')}                    Rebuild search index from knowledge files
   ${cyan('reclassify')}                 Move prompt-history entries from knowledge to event category
   ${cyan('sync')} [dir]                  Index .context/ files into vault DB (use --dry-run to preview)
@@ -458,6 +462,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('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)
   ${cyan('team')} join|leave|status|browse  Join or manage a team vault
@@ -3961,6 +3966,555 @@ async function runIngest() {
   console.log();
 }
 
+/**
+ * Shared ingest helper: dedup-check, build entry, save to vault.
+ * Returns 'saved' | 'skipped' | 'error'.
+ */
+async function ingestCommLine(parsed, { ctx, db, captureAndIndex, dryRun, verbose, sourceFlag, kindFlag, extraTags }) {
+  if (!parsed.id || !parsed.body) {
+    if (verbose) console.log(`  ${red('!')} Missing required field (id, body)`);
+    return 'error';
+  }
+
+  const source = parsed.source || sourceFlag;
+  if (!source) {
+    if (verbose) console.log(`  ${red('!')} No source (use --source flag or include in JSON)`);
+    return 'error';
+  }
+
+  const identityKey = `comms:${source}:${parsed.id}`;
+
+  if (!dryRun) {
+    const exists = db.prepare('SELECT 1 FROM vault WHERE identity_key = ? LIMIT 1').get(identityKey);
+    if (exists) {
+      if (verbose) console.log(`  ${dim('=')} [${source}] Already exists (${parsed.id})`);
+      return 'skipped';
+    }
+  }
+
+  const title = parsed.subject
+    ? `[${source}] ${parsed.subject}`
+    : parsed.from
+      ? `[${source}] Message from ${parsed.from}`
+      : `[${source}] ${parsed.id}`;
+
+  const lineTags = Array.isArray(parsed.tags) ? parsed.tags : [];
+  const allTags = [...new Set([...lineTags, ...extraTags, `source:${source}`])];
+
+  const meta = {};
+  if (parsed.from) meta.from = parsed.from;
+  if (parsed.to) meta.to = parsed.to;
+  if (parsed.date) meta.date = parsed.date;
+  if (parsed.thread_id) meta.thread_id = parsed.thread_id;
+  if (parsed.channel) meta.channel = parsed.channel;
+
+  if (dryRun) {
+    if (verbose) console.log(`  ${green('+')} [${source}] ${parsed.subject || parsed.id}`);
+    return 'saved';
+  }
+
+  try {
+    await captureAndIndex(ctx, {
+      kind: kindFlag,
+      title,
+      body: parsed.body,
+      tags: allTags,
+      source,
+      identity_key: identityKey,
+      meta: Object.keys(meta).length ? meta : null,
+    });
+    if (verbose) console.log(`  ${green('+')} [${source}] ${parsed.subject || parsed.id} (${parsed.id})`);
+    return 'saved';
+  } catch (e) {
+    if (verbose) console.log(`  ${red('!')} [${source}] Error saving ${parsed.id}: ${e.message}`);
+    return 'error';
+  }
+}
+
+async function runIngestComms() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault ingest-comms')}
+
+  Read structured communications from stdin (JSON lines) and save to vault with dedup.
+
+${bold('Flags:')}
+  --source <name>    Source identifier (gmail, slack, etc.) — required if not in JSON
+  --kind <kind>      Vault entry kind (default: event)
+  --tags t1,t2       Additional tags (merged with per-line tags)
+  --dry-run          Parse and validate without saving
+  --verbose          Print each entry as it's processed
+
+${bold('JSON line schema:')}
+  { "id": "msg-123", "body": "text", "source": "gmail", "subject": "...", "from": "...",
+    "to": [...], "date": "...", "thread_id": "...", "channel": "...", "tags": [...] }
+  Required fields: id, body. source from JSON overrides --source flag.
+
+${bold('Examples:')}
+  cat emails.jsonl | context-vault ingest-comms --source gmail
+  echo '{"id":"1","body":"hi","source":"slack"}' | context-vault ingest-comms
+`);
+    return;
+  }
+
+  const sourceFlag = getFlag('--source');
+  const kindFlag = getFlag('--kind') || 'event';
+  const tagsFlag = getFlag('--tags');
+  const extraTags = tagsFlag ? tagsFlag.split(',').map((t) => t.trim()) : [];
+  const dryRun = flags.has('--dry-run');
+  const verbose = flags.has('--verbose');
+
+  // Read all of stdin
+  let input;
+  if (!process.stdin.isTTY) {
+    input = await new Promise((res) => {
+      let data = '';
+      process.stdin.on('data', (chunk) => (data += chunk));
+      process.stdin.on('end', () => res(data));
+    });
+  } else {
+    console.log(`\n  ${bold('context-vault ingest-comms')}`);
+    console.log(`\n  Pipe JSON lines to stdin. Example:`);
+    console.log(`    cat emails.jsonl | context-vault ingest-comms --source gmail\n`);
+    return;
+  }
+
+  const lines = input.split('\n').filter((l) => l.trim());
+  if (!lines.length) {
+    console.log(`\n  No input lines received.\n`);
+    return;
+  }
+
+  // Bootstrap DB (unless dry-run)
+  let ctx, db;
+  if (!dryRun) {
+    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 config = resolveConfig();
+    if (!config.vaultDirExists) {
+      console.error(red(`\n  Vault directory not found: ${config.vaultDir}`));
+      process.exit(1);
+    }
+
+    db = await initDatabase(config.dbPath);
+    const stmts = prepareStatements(db);
+    ctx = {
+      db,
+      config,
+      stmts,
+      embed,
+      insertVec: (r, e) => insertVec(stmts, r, e),
+      deleteVec: (r) => deleteVec(stmts, r),
+    };
+  }
+
+  const { captureAndIndex } = dryRun ? {} : await import('@context-vault/core/capture');
+
+  let saved = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  console.log(dim(`\n  Processing stdin...`));
+
+  const opts = { ctx, db, captureAndIndex, dryRun, verbose, sourceFlag, kindFlag, extraTags };
+
+  for (let i = 0; i < lines.length; i++) {
+    let parsed;
+    try {
+      parsed = JSON.parse(lines[i]);
+    } catch {
+      errors++;
+      if (verbose) console.log(`  ${red('!')} Invalid JSON on line ${i + 1}`);
+      continue;
+    }
+
+    const result = await ingestCommLine(parsed, opts);
+    if (result === 'saved') saved++;
+    else if (result === 'skipped') skipped++;
+    else errors++;
+  }
+
+  if (db) db.close();
+
+  // Summary
+  if (dryRun) {
+    console.log(`  Dry run: ${saved} would be saved, ${skipped} duplicates, ${errors} errors\n`);
+  } else {
+    console.log(`  ${green('✓')} ${saved} saved, ${skipped} skipped (duplicates), ${errors} errors\n`);
+  }
+
+  const summaryParts = [];
+  if (sourceFlag) summaryParts.push(`Source: ${sourceFlag}`);
+  summaryParts.push(`Kind: ${kindFlag}`);
+  if (extraTags.length) summaryParts.push(`Tags: ${extraTags.join(', ')}`);
+  if (summaryParts.length) console.log(`  ${dim(summaryParts.join(' | '))}\n`);
+}
+
+async function runGmailBridge() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault gmail-bridge')}
+
+  Fetch recent emails via gmail-cli and ingest into the vault with dedup.
+
+${bold('Flags:')}
+  --account <name>   Gmail account (default: personal)
+  --max <n>          Maximum messages to fetch (default: 50)
+  --query <q>        Gmail search query (default: newer_than:1d)
+  --dry-run          Show what would be ingested without saving
+  --verbose          Print each entry as it's processed
+
+${bold('Examples:')}
+  context-vault gmail-bridge --dry-run --max 3
+  context-vault gmail-bridge --account stormfors --max 10
+  context-vault gmail-bridge --query "is:unread newer_than:3d"
+`);
+    return;
+  }
+
+  const account = getFlag('--account') || 'personal';
+  const max = getFlag('--max') || '50';
+  const query = getFlag('--query') || 'newer_than:1d';
+  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 SKIP_LABELS = new Set([
+    'CATEGORY_PROMOTIONS',
+    'CATEGORY_SOCIAL',
+    'CATEGORY_UPDATES',
+    'CATEGORY_FORUMS',
+  ]);
+  const SKIP_FROM_PATTERNS = [/noreply/i, /newsletter/i, /marketing/i, /digest/i];
+
+  console.log(dim(`\n  Fetching emails (account: ${account}, max: ${max}, query: ${query})...`));
+
+  let listOutput;
+  try {
+    listOutput = execFileSync('npx', ['tsx', GMAIL_CLI_PATH, 'list', '--account', account, '--max', max, '--query', query], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 60000,
+    });
+  } catch (e) {
+    const stderr = e.stderr ? e.stderr.trim() : '';
+    const msg = stderr || e.message;
+    console.error(red(`\n  Failed to list emails: ${msg}`));
+    process.exit(1);
+  }
+
+  let listResult;
+  try {
+    listResult = JSON.parse(listOutput);
+  } catch {
+    console.error(red(`\n  Failed to parse gmail-cli output as JSON.`));
+    if (verbose) console.error(dim(`  Raw output: ${listOutput.slice(0, 500)}`));
+    process.exit(1);
+  }
+
+  if (!listResult.ok || !Array.isArray(listResult.messages)) {
+    console.error(red(`\n  gmail-cli returned an error or unexpected format.`));
+    if (listResult.error) console.error(red(`  ${listResult.error}`));
+    process.exit(1);
+  }
+
+  const allMessages = listResult.messages;
+  const filtered = allMessages.filter((msg) => {
+    const labels = Array.isArray(msg.labels) ? msg.labels : [];
+    if (labels.some((l) => SKIP_LABELS.has(l))) return false;
+    const from = msg.from || '';
+    if (SKIP_FROM_PATTERNS.some((p) => p.test(from))) return false;
+    return true;
+  });
+
+  const skippedNewsletter = allMessages.length - filtered.length;
+  if (skippedNewsletter > 0) {
+    console.log(dim(`  Filtered out ${skippedNewsletter} newsletter/promo messages`));
+  }
+
+  if (!filtered.length) {
+    console.log(`\n  No messages to ingest after filtering.\n`);
+    return;
+  }
+
+  console.log(dim(`  ${filtered.length} messages to process...`));
+
+  // Bootstrap DB (unless dry-run)
+  let ctx, db, captureAndIndex;
+  if (!dryRun) {
+    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 captureMod = await import('@context-vault/core/capture');
+    captureAndIndex = captureMod.captureAndIndex;
+
+    const config = resolveConfig();
+    if (!config.vaultDirExists) {
+      console.error(red(`\n  Vault directory not found: ${config.vaultDir}`));
+      process.exit(1);
+    }
+
+    db = await initDatabase(config.dbPath);
+    const stmts = prepareStatements(db);
+    ctx = {
+      db,
+      config,
+      stmts,
+      embed,
+      insertVec: (r, e) => insertVec(stmts, r, e),
+      deleteVec: (r) => deleteVec(stmts, r),
+    };
+  }
+
+  const extraTags = ['bucket:comms', `account:${account}`];
+  const opts = { ctx, db, captureAndIndex, dryRun, verbose, sourceFlag: 'gmail', kindFlag: 'event', extraTags };
+
+  let saved = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  for (const msg of filtered) {
+    // Fetch full body for each message
+    let body = msg.snippet || '';
+    if (!dryRun) {
+      try {
+        const getOutput = execFileSync('npx', ['tsx', GMAIL_CLI_PATH, 'get', msg.id, '--account', account], {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 30000,
+        });
+        const fullMsg = JSON.parse(getOutput);
+        if (fullMsg.body) body = fullMsg.body;
+      } catch {
+        if (verbose) console.log(`  ${yellow('!')} Could not fetch body for ${msg.id}, using snippet`);
+      }
+    }
+
+    const parsed = {
+      id: msg.id,
+      source: 'gmail',
+      from: msg.from || '',
+      to: Array.isArray(msg.to) ? msg.to : [],
+      subject: msg.subject || '',
+      body,
+      date: msg.date || '',
+      thread_id: msg.threadId || '',
+      tags: extraTags,
+    };
+
+    const result = await ingestCommLine(parsed, opts);
+    if (result === 'saved') saved++;
+    else if (result === 'skipped') skipped++;
+    else errors++;
+  }
+
+  if (db) db.close();
+
+  if (dryRun) {
+    console.log(`\n  Dry run: ${saved} would be saved, ${skipped} duplicates, ${errors} errors\n`);
+  } else {
+    console.log(`\n  ${green('✓')} ${saved} saved, ${skipped} skipped (duplicates), ${errors} errors\n`);
+  }
+}
+
+async function runSlackBridge() {
+  const SLACK_CLI_PATH = '/Users/admin/omni/workspaces/_archive/agent-tools/slack-cli/cli.ts';
+
+  if (flags.has('--help') || (!flags.has('--list-channels') && !getFlag('--channels'))) {
+    console.log(`
+  ${bold('context-vault slack-bridge')}
+
+  Fetch recent Slack messages from allowed channels and ingest into the vault.
+
+${bold('Flags:')}
+  --channels <ids>     Comma-separated channel IDs (required, explicit allowlist)
+  --limit <n>          Messages per channel (default: 50)
+  --dry-run            Show what would be ingested without saving
+  --verbose            Print each entry as it's processed
+  --list-channels      List available channels and exit
+
+${bold('Examples:')}
+  context-vault slack-bridge --list-channels
+  context-vault slack-bridge --channels C123,C456 --dry-run
+  context-vault slack-bridge --channels C123 --limit 10
+`);
+    return;
+  }
+
+  // --list-channels: show available channels and exit
+  if (flags.has('--list-channels')) {
+    console.log(dim('\n  Fetching Slack channels...'));
+    let raw;
+    try {
+      raw = execFileSync('npx', ['tsx', SLACK_CLI_PATH, 'channels', '--limit', '100'], {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 60000,
+      });
+    } catch (e) {
+      const stderr = e.stderr ? e.stderr.trim() : '';
+      const msg = stderr || e.message;
+      console.error(red(`\n  Failed to list channels: ${msg}`));
+      process.exit(1);
+    }
+
+    let result;
+    try {
+      result = JSON.parse(raw);
+    } catch {
+      console.error(red('\n  Failed to parse slack-cli output as JSON.'));
+      process.exit(1);
+    }
+
+    const channels = Array.isArray(result.channels) ? result.channels : Array.isArray(result) ? result : [];
+    if (!channels.length) {
+      console.log('\n  No channels found.\n');
+      return;
+    }
+
+    console.log(`\n  ${bold('Available channels:')}\n`);
+    for (const ch of channels) {
+      const id = ch.id || ch.channel_id || '?';
+      const name = ch.name || ch.channel_name || '?';
+      console.log(`  ${cyan(id)}  ${name}`);
+    }
+    console.log();
+    return;
+  }
+
+  // Parse flags
+  const channelsRaw = getFlag('--channels');
+  const channelIds = channelsRaw.split(',').map((c) => c.trim()).filter(Boolean);
+  if (!channelIds.length) {
+    console.error(red('\n  --channels requires at least one channel ID.'));
+    process.exit(1);
+  }
+
+  const limit = getFlag('--limit') || '50';
+  const dryRun = flags.has('--dry-run');
+  const verbose = flags.has('--verbose');
+
+  // Bootstrap DB (unless dry-run)
+  let ctx, db, captureAndIndex;
+  if (!dryRun) {
+    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 captureMod = await import('@context-vault/core/capture');
+    captureAndIndex = captureMod.captureAndIndex;
+
+    const config = resolveConfig();
+    if (!config.vaultDirExists) {
+      console.error(red(`\n  Vault directory not found: ${config.vaultDir}`));
+      process.exit(1);
+    }
+
+    db = await initDatabase(config.dbPath);
+    const stmts = prepareStatements(db);
+    ctx = {
+      db,
+      config,
+      stmts,
+      embed,
+      insertVec: (r, e) => insertVec(stmts, r, e),
+      deleteVec: (r) => deleteVec(stmts, r),
+    };
+  }
+
+  const extraTags = ['bucket:comms'];
+  const opts = { ctx, db, captureAndIndex, dryRun, verbose, sourceFlag: 'slack', kindFlag: 'event', extraTags };
+
+  let totalSaved = 0;
+  let totalSkipped = 0;
+  let totalErrors = 0;
+
+  for (const channelId of channelIds) {
+    console.log(dim(`\n  Fetching messages from ${channelId} (limit: ${limit})...`));
+
+    let raw;
+    try {
+      raw = execFileSync('npx', ['tsx', SLACK_CLI_PATH, 'channel-history', channelId, '--limit', limit], {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 60000,
+      });
+    } catch (e) {
+      const stderr = e.stderr ? e.stderr.trim() : '';
+      const msg = stderr || e.message;
+      console.error(red(`  Failed to fetch channel ${channelId}: ${msg}`));
+      totalErrors++;
+      continue;
+    }
+
+    let result;
+    try {
+      result = JSON.parse(raw);
+    } catch {
+      console.error(red(`  Failed to parse output for channel ${channelId}.`));
+      totalErrors++;
+      continue;
+    }
+
+    if (!result.ok || !Array.isArray(result.messages)) {
+      console.error(red(`  slack-cli returned an error for channel ${channelId}.`));
+      if (result.error) console.error(red(`  ${result.error}`));
+      totalErrors++;
+      continue;
+    }
+
+    // Filter out bot messages
+    const messages = result.messages.filter((m) => !m.bot_id);
+    const botCount = result.messages.length - messages.length;
+    if (botCount > 0 && verbose) {
+      console.log(dim(`  Filtered out ${botCount} bot messages`));
+    }
+
+    if (!messages.length) {
+      console.log(dim(`  No messages to ingest for ${channelId}.`));
+      continue;
+    }
+
+    console.log(dim(`  ${messages.length} messages to process...`));
+
+    for (const msg of messages) {
+      const ts = msg.ts || '';
+      const epochSec = parseFloat(ts) || 0;
+      const isoDate = epochSec ? new Date(epochSec * 1000).toISOString() : '';
+
+      const parsed = {
+        id: `${channelId}:${ts}`,
+        source: 'slack',
+        from: msg.user || '',
+        to: [],
+        subject: null,
+        body: msg.text || '',
+        date: isoDate,
+        thread_id: msg.thread_ts || null,
+        channel: channelId,
+        tags: [...extraTags, `channel:${channelId}`],
+      };
+
+      const res = await ingestCommLine(parsed, opts);
+      if (res === 'saved') totalSaved++;
+      else if (res === 'skipped') totalSkipped++;
+      else totalErrors++;
+    }
+  }
+
+  if (db) db.close();
+
+  if (dryRun) {
+    console.log(`\n  Dry run: ${totalSaved} would be saved, ${totalSkipped} duplicates, ${totalErrors} errors\n`);
+  } else {
+    console.log(`\n  ${green('✓')} ${totalSaved} saved, ${totalSkipped} skipped (duplicates), ${totalErrors} errors\n`);
+  }
+}
+
 async function runIngestProject() {
   const rawPath = args[1];
   if (!rawPath) {
@@ -8060,6 +8614,313 @@ async function drainOfflineQueue(apiUrl, apiKey) {
   }
 }
 
+async function runContacts() {
+  const sub = args[1];
+
+  if (flags.has('--help') || !sub) {
+    console.log(`
+  ${bold('context-vault contacts')} <subcommand> [options]
+
+  Manage contact entities in the vault.
+
+${bold('Subcommands:')}
+  ${cyan('list')}                       List all contacts
+  ${cyan('show')} <identity_key>        Show a specific contact by identity key
+  ${cyan('add')}                        Add a new contact
+
+${bold('List options:')}
+  --tags <a,b,c>             Filter by tags (comma-separated)
+  --format <fmt>             Output format: plain (default), json
+
+${bold('Show options:')}
+  --format <fmt>             Output format: plain (default), json
+
+${bold('Add options:')}
+  --name <name>              Contact name (required)
+  --key <identity_key>       Identity key for lookup (required)
+  --email <email>            Email address
+  --role <role>              Role or title
+  --tags <a,b,c>             Additional tags (comma-separated)
+  --notes <text>             Free-form notes
+
+${bold('Examples:')}
+  context-vault contacts list
+  context-vault contacts list --tags "bucket:stormfors" --format json
+  context-vault contacts show felix-hellstrom
+  context-vault contacts add --name "Jane Doe" --key "jane-doe" --email "jane@example.com" --role "Engineer"
+`);
+    return;
+  }
+
+  const format = getFlag('--format') || 'plain';
+
+  let db;
+  try {
+    const { resolveConfig } = await import('@context-vault/core/config');
+    const config = resolveConfig();
+    if (!config.vaultDirExists) {
+      console.error(red('Error: vault not initialised — run `context-vault setup` first'));
+      process.exit(1);
+    }
+    const { initDatabase, prepareStatements, insertVec, deleteVec } =
+      await import('@context-vault/core/db');
+    db = await initDatabase(config.dbPath);
+    const stmts = prepareStatements(db);
+
+    if (sub === 'list') {
+      const tagsStr = getFlag('--tags');
+      let rows = db.prepare(
+        `SELECT id, title, identity_key, tags, body FROM vault WHERE kind = 'contact' AND superseded_by IS NULL ORDER BY title`
+      ).all();
+
+      if (tagsStr) {
+        const filterTags = tagsStr.split(',').map((t) => t.trim().toLowerCase());
+        rows = rows.filter((r) => {
+          const entryTags = r.tags ? JSON.parse(r.tags).map((t) => t.toLowerCase()) : [];
+          return filterTags.some((ft) => entryTags.includes(ft));
+        });
+      }
+
+      if (rows.length === 0) {
+        console.log(dim('No contacts found.'));
+        return;
+      }
+
+      if (format === 'json') {
+        const output = rows.map((r) => ({
+          id: r.id,
+          title: r.title,
+          identity_key: r.identity_key,
+          tags: r.tags ? JSON.parse(r.tags) : [],
+          body: r.body || '',
+        }));
+        console.log(JSON.stringify(output, null, 2));
+      } else {
+        const nameW = 30;
+        const keyW = 25;
+        console.log(`  ${bold('Name'.padEnd(nameW))} ${bold('Key'.padEnd(keyW))} ${bold('Tags')}`);
+        console.log(`  ${'─'.repeat(nameW)} ${'─'.repeat(keyW)} ${'─'.repeat(30)}`);
+        for (const r of rows) {
+          const name = (r.title || '').slice(0, nameW).padEnd(nameW);
+          const key = (r.identity_key || '').slice(0, keyW).padEnd(keyW);
+          const tags = r.tags ? JSON.parse(r.tags).join(', ') : '';
+          console.log(`  ${name} ${dim(key)} ${dim(tags)}`);
+        }
+        console.log(dim(`\n  ${rows.length} contact(s)`));
+      }
+
+    } else if (sub === 'show') {
+      const identityKey = args[2];
+      if (!identityKey || identityKey.startsWith('--')) {
+        console.error(red('Error: provide an identity_key, e.g. context-vault contacts show felix-hellstrom'));
+        process.exit(1);
+      }
+      const row = stmts.getByIdentityKey.get('contact', identityKey);
+      if (!row) {
+        console.error(red(`Error: no contact found with identity_key "${identityKey}"`));
+        process.exit(1);
+      }
+
+      if (format === 'json') {
+        console.log(JSON.stringify({
+          id: row.id,
+          title: row.title,
+          identity_key: row.identity_key,
+          tags: row.tags ? JSON.parse(row.tags) : [],
+          body: row.body || '',
+          created_at: row.created_at,
+          updated_at: row.updated_at,
+        }, null, 2));
+      } else {
+        console.log(`\n  ${bold(row.title || identityKey)}`);
+        console.log(`  ${dim('Key:')} ${row.identity_key}`);
+        const tags = row.tags ? JSON.parse(row.tags) : [];
+        if (tags.length) console.log(`  ${dim('Tags:')} ${tags.join(', ')}`);
+        if (row.created_at) console.log(`  ${dim('Created:')} ${row.created_at}`);
+        if (row.updated_at) console.log(`  ${dim('Updated:')} ${row.updated_at}`);
+        console.log(`\n${row.body || dim('(no body)')}\n`);
+      }
+
+    } else if (sub === 'add') {
+      const name = getFlag('--name');
+      const key = getFlag('--key');
+      const email = getFlag('--email');
+      const role = getFlag('--role');
+      const tagsStr = getFlag('--tags');
+      const notes = getFlag('--notes');
+
+      if (!name) {
+        console.error(red('Error: --name is required'));
+        process.exit(1);
+      }
+      if (!key) {
+        console.error(red('Error: --key is required'));
+        process.exit(1);
+      }
+
+      const existing = stmts.getByIdentityKey.get('contact', key);
+      if (existing) {
+        console.error(red(`Error: a contact with identity_key "${key}" already exists (id: ${existing.id}).`));
+        console.error(`Use ${cyan('context-vault save --kind contact --identity-key "' + key + '" --body "..."')} to update.`);
+        process.exit(1);
+      }
+
+      let body = `# ${name}\n`;
+      if (email) body += `\n## Contact\n${email}\n`;
+      if (role) body += `\n## Role\n${role}\n`;
+      if (notes) body += `\n## Notes\n${notes}\n`;
+
+      const parsedTags = ['contact'];
+      if (tagsStr) {
+        for (const t of tagsStr.split(',').map((t) => t.trim()).filter(Boolean)) {
+          if (!parsedTags.includes(t)) parsedTags.push(t);
+        }
+      }
+
+      const { embed } = await import('@context-vault/core/embed');
+      const { captureAndIndex } = await import('@context-vault/core/capture');
+      const ctx = {
+        db,
+        config,
+        stmts,
+        embed,
+        insertVec: (rowid, embedding) => insertVec(stmts, rowid, embedding),
+        deleteVec: (rowid) => deleteVec(stmts, rowid),
+      };
+      const entry = await captureAndIndex(ctx, {
+        kind: 'contact',
+        title: name,
+        body: body.trim(),
+        tags: parsedTags,
+        source: 'cli',
+        identity_key: key,
+      });
+      console.log(`${green('✓')} Contact saved — id: ${entry.id}, key: ${key}`);
+
+    } else {
+      console.error(red(`Unknown contacts subcommand: ${sub}`));
+      console.error(`Run ${cyan('context-vault contacts --help')} for usage.`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error(`${red('x')} contacts ${sub} failed: ${e.message}`);
+    process.exit(1);
+  } finally {
+    try { db?.close(); } catch {}
+  }
+}
+
+async function runStale() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault stale')} [options]
+
+  List vault entries with low freshness scores (context that may need attention).
+
+${bold('Usage:')}
+  context-vault stale                    # Entries scoring < 50 (stale + dormant)
+  context-vault stale --threshold 25     # Only dormant entries
+  context-vault stale --kind insight     # Filter by kind
+  context-vault stale --format json      # Structured output
+
+${bold('Options:')}
+  --threshold <n>    Score threshold (default: 50, entries below this are shown)
+  --kind <kind>      Filter by kind
+  --format <fmt>     Output format: plain (default), json
+  --limit <n>        Max entries to show (default: 50)
+`);
+    return;
+  }
+
+  const threshold = parseInt(getFlag('--threshold') || '50', 10);
+  const kind = getFlag('--kind');
+  const format = getFlag('--format') || 'plain';
+  const limit = parseInt(getFlag('--limit') || '50', 10);
+
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase } = await import('@context-vault/core/db');
+  const { computeFreshnessScore } = await import('@context-vault/core/search');
+
+  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 {
+    let sql = `SELECT * FROM vault WHERE superseded_by IS NULL AND (expires_at IS NULL OR expires_at > datetime('now'))`;
+    const params = [];
+    if (kind) {
+      sql += ' AND kind = ?';
+      params.push(kind);
+    }
+
+    const rows = db.prepare(sql).all(...params);
+
+    const scored = rows.map((row) => {
+      const { score, label } = computeFreshnessScore(row);
+      return { ...row, freshness_score: score, freshness_label: label };
+    });
+
+    const staleEntries = scored
+      .filter((e) => e.freshness_score < threshold)
+      .sort((a, b) => a.freshness_score - b.freshness_score)
+      .slice(0, limit);
+
+    if (format === 'json') {
+      const output = staleEntries.map((e) => ({
+        id: e.id,
+        kind: e.kind,
+        title: e.title,
+        freshness_score: e.freshness_score,
+        freshness_label: e.freshness_label,
+        created_at: e.created_at,
+        updated_at: e.updated_at,
+        last_accessed_at: e.last_accessed_at,
+        recall_count: e.recall_count,
+        recall_sessions: e.recall_sessions,
+      }));
+      console.log(JSON.stringify(output, null, 2));
+    } else {
+      console.log();
+      console.log(`  ${bold('Stale Entries')} ${dim(`(freshness < ${threshold})`)}`);
+      console.log();
+
+      if (staleEntries.length === 0) {
+        console.log(`  ${dim('No entries below threshold.')}`);
+      } else {
+        const labelColor = (label) => {
+          if (label === 'dormant') return red(label);
+          if (label === 'stale') return yellow(label);
+          return dim(label);
+        };
+
+        for (const entry of staleEntries) {
+          const title = entry.title || '(untitled)';
+          const score = String(entry.freshness_score).padStart(3);
+          console.log(`  ${dim(score)} ${labelColor(entry.freshness_label).padEnd(18)} ${entry.kind.padEnd(12)} ${title}`);
+        }
+
+        console.log();
+        const dormantCount = staleEntries.filter((e) => e.freshness_label === 'dormant').length;
+        const staleCount = staleEntries.filter((e) => e.freshness_label === 'stale').length;
+        console.log(`  ${dim('Total:')} ${staleEntries.length} entries (${dormantCount} dormant, ${staleCount} stale)`);
+      }
+      console.log();
+    }
+  } finally {
+    db.close();
+  }
+}
+
 async function main() {
   if (flags.has('--version') || command === 'version') {
     console.log(VERSION);
@@ -8068,7 +8929,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']);
+    const commandsWithHelp = new Set(['save', 'search', 'rules', 'hooks', 'team', 'remote', 'ingest-comms', 'gmail-bridge', 'slack-bridge', 'contacts']);
     if (!command || command === 'help' || !commandsWithHelp.has(command)) {
       showHelp(flags.has('--all'));
       return;
@@ -8148,6 +9009,18 @@ async function main() {
     case 'ingest-project':
       await runIngestProject();
       break;
+    case 'ingest-comms':
+      await runIngestComms();
+      break;
+    case 'gmail-bridge':
+      await runGmailBridge();
+      break;
+    case 'slack-bridge':
+      await runSlackBridge();
+      break;
+    case 'contacts':
+      await runContacts();
+      break;
     case 'reindex':
       await runReindex();
       break;
@@ -8218,6 +9091,9 @@ async function main() {
     case 'compact':
       await runCompact();
       break;
+    case 'stale':
+      await runStale();
+      break;
     default:
       console.error(red(`Unknown command: ${command}`));
       console.error(`Run ${cyan('context-vault --help')} for usage.`);