context-vault 3.7.0 → 3.9.0

package/bin/cli.js

@@ -301,12 +301,24 @@ const TOOLS = [
   {
     id: 'antigravity',
     name: 'Antigravity (Gemini CLI)',
-    detect: () => anyDirExists(join(HOME, '.gemini', 'antigravity'), join(HOME, '.gemini')),
+    detect: async () =>
+      anyDirExists(join(HOME, '.gemini', 'antigravity'), join(HOME, '.gemini')) ||
+      (await commandExistsAsync('gemini')),
     configType: 'json',
     configPath: join(HOME, '.gemini', 'antigravity', 'mcp_config.json'),
     configKey: 'mcpServers',
-    rulesPath: null,
-    rulesMethod: null,
+    rulesPath: join(HOME, '.gemini', 'antigravity', 'rules', 'context-vault.md'),
+    rulesMethod: 'write',
+  },
+  {
+    id: 'google-ai',
+    name: 'Google AI / Gemini CLI',
+    detect: () => existsSync(join(HOME, '.gemini', 'mcp_config.json')),
+    configType: 'json',
+    configPath: join(HOME, '.gemini', 'mcp_config.json'),
+    configKey: 'mcpServers',
+    rulesPath: join(HOME, '.gemini', 'rules', 'context-vault.md'),
+    rulesMethod: 'write',
   },
   {
     id: 'cline',
@@ -401,6 +413,9 @@ ${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('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
   ${cyan('update')}                     Check for and install updates
   ${cyan('uninstall')}                  Remove MCP configs and optionally data
 `);
@@ -757,6 +772,7 @@ async function runSetup() {
     if (userLevel === 'beginner') {
       console.log('  Install an AI tool first:');
       console.log(dim('    Claude Code:  https://docs.anthropic.com/en/docs/claude-code'));
+      console.log(dim('    Gemini CLI:   https://github.com/google-gemini/gemini-cli'));
       console.log(dim('    Cursor:       https://cursor.com'));
       console.log(dim('    Windsurf:     https://codeium.com/windsurf'));
       console.log();
@@ -2769,8 +2785,8 @@ 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);
-      const IRREGULAR_PLURALS = { activity: 'activities', inbox: 'inboxes', index: 'indexes', match: 'matches' };
-      const plural = IRREGULAR_PLURALS[kind] || (kind.endsWith('s') ? kind : kind + 's');
+      const IRREGULAR_PLURALS = { activity: 'activities', inbox: 'inboxes', index: 'indexes', match: 'matches', entity: 'entities', summary: 'summaries' };
+      const plural = IRREGULAR_PLURALS[kind] || (kind.endsWith('y') ? kind.slice(0, -1) + 'ies' : kind.endsWith('s') || kind.endsWith('x') || kind.endsWith('ch') || kind.endsWith('sh') ? kind + 'es' : kind + 's');
       console.log(`    ${dim(bar)} ${countStr} ${plural}`);
     }
   } else {
@@ -4376,6 +4392,35 @@ async function runPostToolCall() {
 }
 
 async function runSave() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault save')}
+
+  Save an entry to the vault from CLI.
+
+${bold('Required:')}
+  --kind <kind>        Entry kind (insight, decision, pattern, reference, event)
+  --title <title>      Entry title
+
+${bold('Content')} (one of):
+  --body <text>        Inline body text
+  --file <path>        Read body from a file
+  (stdin)              Pipe content via stdin
+
+${bold('Optional:')}
+  --tags <a,b,c>       Comma-separated tags
+  --tier <tier>        working (default) or durable
+  --source <source>    Source label (default: cli)
+  --identity-key <key> Identity key (for entity kinds)
+  --meta <json>        Additional metadata as JSON
+
+${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"
+`);
+    return;
+  }
+
   const kind = getFlag('--kind');
   const title = getFlag('--title');
   const tags = getFlag('--tags');
@@ -4473,6 +4518,30 @@ async function runSave() {
 }
 
 async function runSearch() {
+  if (flags.has('--help')) {
+    console.log(`
+  ${bold('context-vault search')} <query> [options]
+
+  Search vault entries from CLI using hybrid semantic + full-text search.
+
+${bold('Usage:')}
+  context-vault search "express middleware"
+  context-vault search --kind insight --tags "bucket:myproject"
+  context-vault search "auth" --limit 20 --format json
+
+${bold('Options:')}
+  --kind <kind>        Filter by kind (insight, decision, pattern, reference, event)
+  --tags <a,b,c>       Filter by tags (comma-separated)
+  --limit <n>          Max results (default: 10)
+  --sort <mode>        Sort by: relevance (default), recent
+  --format <fmt>       Output format: plain (default), json
+  --scope <scope>      Search scope: hot (default), events, all
+  --full               Show full entry body (not truncated)
+  --query <text>       Explicit query (alternative to positional args)
+`);
+    return;
+  }
+
   const kind = getFlag('--kind');
   const tagsStr = getFlag('--tags');
   const limit = parseInt(getFlag('--limit') || '10', 10);
@@ -6915,10 +6984,923 @@ ${progArgs.map(a => `    <string>${a}</string>`).join('\n')}
   }
 }
 
+async function runStats() {
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase } = await import('@context-vault/core/db');
+  const { gatherRecallSummary, gatherCoRetrievalSummary } = await import('../dist/stats/recall.js');
+
+  const sub = args[1];
+  if (!sub || sub === 'recall') {
+    await runStatsRecall({ resolveConfig, initDatabase, gatherRecallSummary });
+  } else if (sub === 'co-retrieval') {
+    await runStatsCoRetrieval({ resolveConfig, initDatabase, gatherCoRetrievalSummary });
+  } else {
+    console.error(red(`  Unknown stats subcommand: ${sub}`));
+    console.error(`  Available: recall, co-retrieval`);
+    process.exit(1);
+  }
+}
+
+async function runStatsRecall({ resolveConfig, initDatabase, gatherRecallSummary }) {
+  const config = resolveConfig();
+  let db;
+  try {
+    db = await initDatabase(config.dbPath);
+  } catch (e) {
+    console.error(red(`  Database not accessible: ${e.message}`));
+    process.exit(1);
+  }
+
+  let s;
+  try {
+    s = gatherRecallSummary({ db, config });
+  } finally {
+    db.close();
+  }
+
+  const ratioPct = Math.round(s.ratio * 100);
+  const targetPct = Math.round(s.target * 100);
+  const statusIcon = s.ratio >= s.target ? green('✓') : yellow('·');
+  console.log();
+  console.log(`  ${bold('◇ context-vault stats recall')}`);
+  console.log();
+  console.log(`  ${statusIcon} Recall ratio:     ${bold(s.ratio.toFixed(2))} (target: ${s.target.toFixed(2)})`);
+  console.log(`    Total entries:    ${s.total_entries}`);
+  console.log(`    Recalled (1+):    ${s.recalled_entries} (${ratioPct}%)`);
+  console.log(`    Never recalled:   ${s.never_recalled} (${100 - ratioPct}%)`);
+  console.log(`    Avg recall count: ${s.avg_recall_count} (among recalled entries)`);
+
+  if (s.top_recalled.length) {
+    console.log();
+    console.log(`  ${bold('Top recalled:')}`);
+    for (let i = 0; i < s.top_recalled.length; i++) {
+      const e = s.top_recalled[i];
+      const title = (e.title || '(untitled)').slice(0, 50);
+      console.log(`    ${i + 1}. "${title}" (recall: ${e.recall_count}, sessions: ${e.recall_sessions})`);
+    }
+  }
+
+  if (s.dead_entry_count > 0) {
+    console.log();
+    console.log(`  ${bold('Dead entries')} ${dim('(saved >30 days ago, never recalled):')}`);
+    console.log(`    - ${s.dead_entry_count} entries across ${s.dead_bucket_count} buckets`);
+    if (s.top_dead_buckets.length) {
+      const bucketStr = s.top_dead_buckets.map((b) => `${b.bucket} (${b.count})`).join(', ');
+      console.log(`    - Top dead buckets: ${bucketStr}`);
+    }
+  }
+
+  console.log();
+}
+
+async function runStatsCoRetrieval({ resolveConfig, initDatabase, gatherCoRetrievalSummary }) {
+  const config = resolveConfig();
+  let db;
+  try {
+    db = await initDatabase(config.dbPath);
+  } catch (e) {
+    console.error(red(`  Database not accessible: ${e.message}`));
+    process.exit(1);
+  }
+
+  let s;
+  try {
+    s = gatherCoRetrievalSummary({ db, config });
+  } finally {
+    db.close();
+  }
+
+  console.log();
+  console.log(`  ${bold('◇ context-vault stats co-retrieval')}`);
+  console.log();
+  console.log(`  Co-retrieval pairs: ${bold(String(s.total_pairs))}`);
+
+  if (s.top_pairs.length) {
+    console.log();
+    console.log(`  ${bold('Strongest pairs:')}`);
+    for (let i = 0; i < s.top_pairs.length; i++) {
+      const p = s.top_pairs[i];
+      const titleA = (p.title_a || '(untitled)').slice(0, 40);
+      const titleB = (p.title_b || '(untitled)').slice(0, 40);
+      console.log(`    ${i + 1}. "${titleA}" <-> "${titleB}" (weight: ${p.weight})`);
+    }
+  }
+
+  console.log();
+  console.log(`  Graph density: ${s.graph_density.toFixed(4)} ${dim('(sparse, expected for early usage)')}`);
+  console.log();
+}
+
 async function runServe() {
   await import('../dist/server.js');
 }
 
+async function runTeam() {
+  const subcommand = args[1];
+  const { getRemoteConfig, saveRemoteConfig } = await import('@context-vault/core/config');
+  const dataDir = join(HOME, '.context-mcp');
+
+  if (subcommand === 'join') {
+    const teamId = args[2];
+    if (!teamId) {
+      console.error(`\n  ${red('Usage:')} context-vault team join <team-id>\n`);
+      process.exit(1);
+    }
+
+    const remote = getRemoteConfig(dataDir);
+    if (!remote || !remote.enabled || !remote.apiKey) {
+      console.error(`\n  ${red('✘')} Remote is not configured. Run ${cyan('context-vault remote setup')} first.\n`);
+      process.exit(1);
+    }
+
+    console.log(`\n  Testing connection to team ${dim(teamId)}...`);
+    try {
+      const res = await fetch(`${remote.url.replace(/\/$/, '')}/api/team/${teamId}/status`, {
+        headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+        signal: AbortSignal.timeout(10000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        saveRemoteConfig({ teamId }, dataDir);
+        console.log(`  ${green('✓')} Joined team: ${bold(data.name || teamId)}`);
+        if (data.entry_count != null) {
+          console.log(`  ${dim(`${data.entry_count} entries, ${data.member_count || '?'} members`)}`);
+        }
+      } else {
+        const text = await res.text().catch(() => '');
+        console.error(`  ${red('✘')} Failed to connect to team: HTTP ${res.status}`);
+        if (text) console.error(`  ${dim(text.slice(0, 200))}`);
+        process.exit(1);
+      }
+    } catch (e) {
+      console.error(`  ${red('✘')} Connection failed: ${e.message}`);
+      process.exit(1);
+    }
+    console.log();
+    return;
+  }
+
+  if (subcommand === 'leave') {
+    const remote = getRemoteConfig(dataDir);
+    if (!remote?.teamId) {
+      console.log(`\n  ${dim('Not currently in a team.')}\n`);
+      return;
+    }
+    saveRemoteConfig({ teamId: '' }, dataDir);
+    console.log(`\n  ${green('✓')} Left team. Team vault queries disabled.\n`);
+    return;
+  }
+
+  if (subcommand === 'status') {
+    const remote = getRemoteConfig(dataDir);
+    console.log();
+    console.log(`  ${bold('◇ Team Status')}`);
+    console.log();
+
+    if (!remote || !remote.teamId) {
+      console.log(`  Team:    ${dim('not joined')}`);
+      console.log(`  ${dim('Run')} ${cyan('context-vault team join <team-id>')} ${dim('to connect.')}`);
+      console.log();
+      return;
+    }
+
+    console.log(`  Team ID: ${remote.teamId}`);
+
+    if (remote.enabled && remote.apiKey) {
+      console.log(`  Checking status...`);
+      try {
+        const res = await fetch(`${remote.url.replace(/\/$/, '')}/api/team/${remote.teamId}/status`, {
+          headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+          signal: AbortSignal.timeout(10000),
+        });
+        if (res.ok) {
+          const data = await res.json();
+          console.log(`  Name:    ${data.name || dim('(unnamed)')}`);
+          console.log(`  Members: ${data.member_count ?? dim('?')}`);
+          console.log(`  Entries: ${data.entry_count ?? dim('?')}`);
+          console.log(`  Health:  ${green('connected')}`);
+        } else {
+          console.log(`  Health:  ${red('error')} (HTTP ${res.status})`);
+        }
+      } catch (e) {
+        console.log(`  Health:  ${red('unreachable')} (${e.message})`);
+      }
+    } else {
+      console.log(`  Health:  ${yellow('remote not configured')}`);
+    }
+    console.log();
+    return;
+  }
+
+  if (subcommand === 'seed') {
+    const teamIdFlag = getFlag('--team');
+    const tagsFlag = getFlag('--tags');
+    const remote = getRemoteConfig(dataDir);
+
+    if (!remote || !remote.enabled || !remote.apiKey) {
+      console.error(`\n  ${red('✘')} Remote is not configured. Run ${cyan('context-vault remote setup')} first.\n`);
+      process.exit(1);
+    }
+
+    const teamId = teamIdFlag || remote.teamId;
+    if (!teamId) {
+      console.error(`\n  ${red('✘')} No team ID. Pass ${cyan('--team <id>')} or join a team first.\n`);
+      process.exit(1);
+    }
+
+    // Load local vault DB
+    const { resolveConfig } = await import('@context-vault/core/config');
+    const config = resolveConfig();
+
+    let DatabaseSync;
+    try {
+      DatabaseSync = (await import('node:sqlite')).DatabaseSync;
+    } catch {
+      console.error(`\n  ${red('✘')} Node.js SQLite not available. Requires Node >= 22.5.\n`);
+      process.exit(1);
+    }
+
+    const db = new DatabaseSync(config.dbPath, { open: true });
+
+    // Build query based on tag filter
+    let sql = 'SELECT id, kind, category, title, body, tags, meta, source, identity_key, tier FROM vault WHERE superseded_by IS NULL';
+    const params = [];
+
+    if (tagsFlag) {
+      sql += ' AND tags LIKE ?';
+      params.push(`%"${tagsFlag}"%`);
+    }
+
+    const rows = db.prepare(sql).all(...params);
+    db.close();
+
+    let publishedKnowledge = 0;
+    let federatedEntities = 0;
+    let skippedEvents = 0;
+    let blockedPrivacy = 0;
+    const blockedEntries = [];
+    let errors = 0;
+
+    const apiUrl = remote.url.replace(/\/$/, '');
+
+    console.log();
+    console.log(`  ${bold('◇ Team Seed')}`);
+    console.log(`  Team: ${teamId}`);
+    console.log(`  Filter: ${tagsFlag || dim('(all entries)')}`);
+    console.log(`  Entries: ${rows.length}`);
+    console.log();
+
+    if (isDryRun) {
+      for (const row of rows) {
+        if (row.category === 'event') {
+          skippedEvents++;
+        } else if (row.category === 'entity') {
+          federatedEntities++;
+        } else {
+          publishedKnowledge++;
+        }
+      }
+      console.log(`  ${dim('[dry run]')}`);
+      console.log(`  Would publish: ${green(publishedKnowledge)} knowledge, ${cyan(federatedEntities)} entities`);
+      console.log(`  Would skip:    ${dim(skippedEvents)} events (private)`);
+      console.log();
+      return;
+    }
+
+    for (const row of rows) {
+      if (row.category === 'event') {
+        skippedEvents++;
+        continue;
+      }
+
+      const tags = row.tags ? JSON.parse(row.tags) : [];
+      const meta = row.meta ? JSON.parse(row.meta) : {};
+
+      try {
+        const res = await fetch(`${apiUrl}/api/vault/publish`, {
+          method: 'POST',
+          headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+          signal: AbortSignal.timeout(15000),
+          body: JSON.stringify({
+            entryId: row.id,
+            teamId,
+            visibility: 'team',
+            kind: row.kind,
+            title: row.title,
+            body: row.body,
+            tags,
+            meta,
+            source: row.source,
+            identity_key: row.identity_key,
+            tier: row.tier,
+            category: row.category,
+          }),
+        });
+
+        if (res.ok) {
+          if (row.category === 'entity') {
+            federatedEntities++;
+          } else {
+            publishedKnowledge++;
+          }
+        } else if (res.status === 422) {
+          const data = await res.json().catch(() => ({}));
+          if (data.code === 'PRIVACY_SCAN_FAILED') {
+            const matchTypes = Array.isArray(data.matches) ? data.matches.map(m => m.type) : [];
+            const uniqueTypes = [...new Set(matchTypes)];
+            console.log(`  ${yellow('!')} Blocked: "${row.title || row.id}" (${uniqueTypes.join(', ') || 'sensitive content'})`);
+            blockedPrivacy++;
+            blockedEntries.push({ title: row.title || row.id, types: uniqueTypes });
+          } else {
+            errors++;
+            console.error(`  ${red('!')} 422 for "${row.title || row.id}": ${data.error || 'unknown'}`);
+          }
+        } else {
+          const data = await res.json().catch(() => ({}));
+          if (data.conflict) {
+            console.log(`  ${yellow('!')} Conflict for "${row.title || row.id}": ${data.conflict.suggestion || 'similar entry exists'}`);
+          }
+          if (row.category === 'entity') {
+            federatedEntities++;
+          } else {
+            publishedKnowledge++;
+          }
+        }
+      } catch (e) {
+        errors++;
+        console.error(`  ${red('✘')} Failed: ${row.title || row.id} (${e.message})`);
+      }
+
+      // Progress indicator every 10 entries
+      const processed = publishedKnowledge + federatedEntities + skippedEvents + blockedPrivacy + errors;
+      if (processed % 10 === 0) {
+        process.stdout.write(`  ${dim(`${processed}/${rows.length}...`)}\r`);
+      }
+    }
+
+    console.log(`  Seeded: ${green(publishedKnowledge)} published, ${cyan(federatedEntities)} federated, ${dim(skippedEvents)} skipped (events), ${blockedPrivacy > 0 ? yellow(blockedPrivacy) : dim(blockedPrivacy)} blocked (privacy scan)`);
+    if (errors > 0) {
+      console.log(`  Errors:  ${red(errors)}`);
+    }
+    if (blockedEntries.length > 0) {
+      console.log();
+      console.log(`  ${yellow('Blocked entries (review and clean before re-seeding):')}`);
+      for (const entry of blockedEntries) {
+        console.log(`    - ${entry.title} [${entry.types.join(', ')}]`);
+      }
+    }
+    console.log();
+    return;
+  }
+
+  // Default: show team help
+  console.log();
+  console.log(`  ${bold('◇ context-vault team')}`);
+  console.log();
+  console.log(`  ${cyan('join <team-id>')}    Join a team vault`);
+  console.log(`  ${cyan('leave')}             Leave the current team`);
+  console.log(`  ${cyan('status')}            Show team connection status`);
+  console.log(`  ${cyan('seed')}              Publish local entries to team vault`);
+  console.log(`    ${dim('--team <id>')}      Team ID (defaults to joined team)`);
+  console.log(`    ${dim('--tags <filter>')}  Filter entries by tag (e.g. bucket:stormfors)`);
+  console.log(`    ${dim('--dry-run')}        Preview without publishing`);
+  console.log();
+}
+
+async function runRemote() {
+  const subcommand = args[1];
+  const { getRemoteConfig, saveRemoteConfig } = await import('@context-vault/core/config');
+  const dataDir = join(HOME, '.context-mcp');
+
+  if (subcommand === 'setup') {
+    const readline = await import('node:readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+    console.log();
+    console.log(`  ${bold('◇ Remote Vault Setup')}`);
+    console.log();
+
+    const defaultUrl = 'https://api.context-vault.com';
+    const urlInput = await ask(`  API URL ${dim(`(${defaultUrl})`)}: `);
+    const url = urlInput.trim() || defaultUrl;
+
+    const apiKey = await ask('  API Key: ');
+    rl.close();
+
+    if (!apiKey.trim()) {
+      console.error(`\n  ${red('✘')} API key is required.`);
+      process.exit(1);
+    }
+
+    console.log(`\n  Testing connection to ${dim(url)}...`);
+    try {
+      const res = await fetch(`${url.replace(/\/$/, '')}/api/vault/status`, {
+        headers: { 'Authorization': `Bearer ${apiKey.trim()}`, 'Content-Type': 'application/json' },
+        signal: AbortSignal.timeout(10000),
+      });
+      if (res.ok) {
+        saveRemoteConfig({ enabled: true, url, apiKey: apiKey.trim() }, dataDir);
+        console.log(`  ${green('✓')} Connected successfully. Remote sync enabled.`);
+        console.log(dim(`  Config saved to ${join(dataDir, 'config.json')}`));
+      } else {
+        const text = await res.text().catch(() => '');
+        console.error(`  ${red('✘')} Connection failed: HTTP ${res.status}`);
+        if (text) console.error(`  ${dim(text.slice(0, 200))}`);
+        process.exit(1);
+      }
+    } catch (e) {
+      console.error(`  ${red('✘')} Connection failed: ${e.message}`);
+      process.exit(1);
+    }
+    console.log();
+    return;
+  }
+
+  if (subcommand === 'status') {
+    const remote = getRemoteConfig(dataDir);
+    console.log();
+    console.log(`  ${bold('◇ Remote Status')}`);
+    console.log();
+    if (!remote) {
+      console.log(`  Remote:  ${dim('not configured')}`);
+      console.log(`  ${dim('Run')} ${cyan('context-vault remote setup')} ${dim('to connect.')}`);
+    } else {
+      const keyPreview = remote.apiKey ? remote.apiKey.slice(0, 6) + '...' : dim('(none)');
+      console.log(`  Enabled: ${remote.enabled ? green('yes') : red('no')}`);
+      console.log(`  URL:     ${remote.url}`);
+      console.log(`  API Key: ${keyPreview}`);
+
+      if (remote.enabled && remote.apiKey) {
+        console.log(`\n  Testing connection...`);
+        try {
+          const res = await fetch(`${remote.url.replace(/\/$/, '')}/api/vault/status`, {
+            headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(10000),
+          });
+          if (res.ok) {
+            console.log(`  ${green('✓')} Remote is reachable.`);
+          } else {
+            console.log(`  ${red('✘')} HTTP ${res.status}`);
+          }
+        } catch (e) {
+          console.log(`  ${red('✘')} ${e.message}`);
+        }
+      }
+    }
+    console.log();
+    return;
+  }
+
+  if (subcommand === 'disconnect') {
+    const remote = getRemoteConfig(dataDir);
+    if (!remote || !remote.enabled) {
+      console.log(`\n  ${dim('Remote sync is already disabled.')}\n`);
+      return;
+    }
+    saveRemoteConfig({ enabled: false }, dataDir);
+    console.log(`\n  ${green('✓')} Remote sync disabled. API key preserved (re-enable with ${cyan('context-vault remote setup')}).\n`);
+    return;
+  }
+
+  if (subcommand === 'sync') {
+    await runRemoteSync(getRemoteConfig, dataDir);
+    return;
+  }
+
+  if (subcommand === 'pull') {
+    await runRemotePull(getRemoteConfig, dataDir);
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold('◇ context-vault remote')}`);
+  console.log();
+  console.log(`  ${cyan('setup')}       Connect to a hosted vault API`);
+  console.log(`  ${cyan('status')}      Show remote config and test connection`);
+  console.log(`  ${cyan('sync')}  ${dim('[--full] [--dry-run]')}  Sync local vault to hosted`);
+  console.log(`  ${cyan('pull')}        Pull remote entries to local`);
+  console.log(`  ${cyan('disconnect')}  Disable remote sync (preserves API key)`);
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// remote sync — push local vault to hosted
+// ---------------------------------------------------------------------------
+async function runRemoteSync(getRemoteConfig, dataDir) {
+  const remote = getRemoteConfig(dataDir);
+  if (!remote || !remote.enabled || !remote.apiKey) {
+    console.error(`\n  ${red('✘')} Remote is not configured. Run ${cyan('context-vault remote setup')} first.\n`);
+    process.exit(1);
+  }
+
+  const isFullSync = flags.has('--full');
+  const { createHash } = await import('node:crypto');
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const config = resolveConfig();
+
+  let DatabaseSync;
+  try {
+    DatabaseSync = (await import('node:sqlite')).DatabaseSync;
+  } catch {
+    console.error(`\n  ${red('✘')} Node.js SQLite not available. Requires Node >= 22.5.\n`);
+    process.exit(1);
+  }
+
+  const db = new DatabaseSync(config.dbPath, { open: true });
+  const apiUrl = remote.url.replace(/\/$/, '');
+
+  function contentHash(entry) {
+    const data = (entry.title || '') + (entry.body || '') + JSON.stringify(entry.tags || []) + JSON.stringify(entry.meta || {});
+    return createHash('sha256').update(data).digest('hex');
+  }
+
+  console.log();
+  console.log(`  ${bold('◇ Remote Sync')}`);
+  console.log();
+
+  // Read all local entries
+  const localRows = db.prepare(
+    'SELECT id, kind, category, title, body, tags, meta, source, identity_key, tier, expires_at, created_at, updated_at FROM vault WHERE superseded_by IS NULL'
+  ).all();
+  db.close();
+
+  const localEntries = localRows.map((row) => ({
+    ...row,
+    tags: typeof row.tags === 'string' ? JSON.parse(row.tags) : (row.tags || []),
+    meta: typeof row.meta === 'string' ? JSON.parse(row.meta) : (row.meta || {}),
+  }));
+
+  console.log(`  Local entries: ${localEntries.length}`);
+
+  let toUpload;
+
+  if (isFullSync) {
+    console.log(`  Mode: ${cyan('full')} (uploading all entries)`);
+    toUpload = localEntries;
+  } else {
+    // Fetch remote manifest
+    console.log(`  Fetching remote manifest...`);
+    let manifest;
+    try {
+      const res = await fetch(`${apiUrl}/api/vault/manifest`, {
+        headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+        signal: AbortSignal.timeout(30000),
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        console.error(`  ${red('✘')} Manifest fetch failed: HTTP ${res.status}`);
+        if (text) console.error(`  ${dim(text.slice(0, 200))}`);
+        process.exit(1);
+      }
+      manifest = await res.json();
+    } catch (e) {
+      console.error(`  ${red('✘')} Manifest fetch failed: ${e.message}`);
+      process.exit(1);
+    }
+
+    const remoteEntries = manifest.entries || [];
+    const remoteMap = new Map();
+    for (const entry of remoteEntries) {
+      remoteMap.set(entry.id, entry);
+    }
+
+    // If remote manifest has content_hash, do a hash diff. Otherwise fall back to full sync.
+    const hasContentHash = remoteEntries.length > 0 && remoteEntries[0].content_hash;
+
+    if (!hasContentHash && remoteEntries.length > 0) {
+      console.log(`  ${yellow('!')} Remote manifest lacks content_hash. Falling back to full upload.`);
+      toUpload = localEntries;
+    } else {
+      toUpload = [];
+      let unchanged = 0;
+      for (const entry of localEntries) {
+        const remoteEntry = remoteMap.get(entry.id);
+        if (!remoteEntry) {
+          toUpload.push(entry);
+        } else if (remoteEntry.content_hash !== contentHash(entry)) {
+          toUpload.push(entry);
+        } else {
+          unchanged++;
+        }
+      }
+      console.log(`  Unchanged: ${unchanged}`);
+    }
+  }
+
+  const newCount = toUpload.length;
+  console.log(`  To upload: ${newCount}`);
+
+  if (newCount === 0) {
+    console.log(`\n  ${green('✓')} Everything is in sync.\n`);
+    await drainOfflineQueue(apiUrl, remote.apiKey);
+    return;
+  }
+
+  if (isDryRun) {
+    console.log();
+    for (const entry of toUpload.slice(0, 20)) {
+      console.log(`  ${dim(entry.id)} ${entry.kind || '?'} ${entry.title || dim('(untitled)')}`);
+    }
+    if (toUpload.length > 20) {
+      console.log(`  ${dim(`... and ${toUpload.length - 20} more`)}`);
+    }
+    console.log(`\n  ${dim('Dry run. No changes made.')}\n`);
+    return;
+  }
+
+  // Stream as NDJSON
+  console.log(`  Uploading...`);
+  const ndjsonBody = toUpload.map((entry) => JSON.stringify(entry)).join('\n') + '\n';
+
+  let jobId, entriesUploaded;
+  try {
+    const res = await fetch(`${apiUrl}/api/vault/import/stream`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${remote.apiKey}`,
+        'Content-Type': 'application/x-ndjson',
+      },
+      body: ndjsonBody,
+      signal: AbortSignal.timeout(120000),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      console.error(`  ${red('✘')} Upload failed: HTTP ${res.status}`);
+      if (text) console.error(`  ${dim(text.slice(0, 200))}`);
+      process.exit(1);
+    }
+    const data = await res.json();
+    jobId = data.job_id;
+    entriesUploaded = data.entries_uploaded || newCount;
+  } catch (e) {
+    console.error(`  ${red('✘')} Upload failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  console.log(`  ${green('✓')} Uploaded ${entriesUploaded} entries.`);
+
+  if (!jobId) {
+    console.log(`\n  ${green('✓')} Sync complete (no job tracking available).\n`);
+    await drainOfflineQueue(apiUrl, remote.apiKey);
+    return;
+  }
+
+  // Poll job status until embeddings complete
+  console.log(`  Job: ${dim(jobId)}`);
+  console.log(`  Waiting for embeddings...`);
+
+  let attempts = 0;
+  const maxAttempts = 300; // 10 min max
+  while (attempts < maxAttempts) {
+    await new Promise((r) => setTimeout(r, 2000));
+    attempts++;
+    try {
+      const res = await fetch(`${apiUrl}/api/vault/jobs/${jobId}`, {
+        headers: { 'Authorization': `Bearer ${remote.apiKey}` },
+        signal: AbortSignal.timeout(10000),
+      });
+      if (!res.ok) {
+        if (res.status === 404) {
+          console.log(`  ${yellow('!')} Job not found (server may not support job tracking yet).`);
+          break;
+        }
+        continue;
+      }
+      const job = await res.json();
+      const embedded = job.entries_embedded || 0;
+      const total = job.total_entries || entriesUploaded;
+      const pct = total > 0 ? Math.round((embedded / total) * 100) : 0;
+      process.stdout.write(`\r  Embeddings: ${embedded}/${total} (${pct}%)   `);
+
+      if (job.status === 'complete') {
+        process.stdout.write('\n');
+        console.log(`  ${green('✓')} Embeddings complete.`);
+        break;
+      }
+      if (job.status === 'failed') {
+        process.stdout.write('\n');
+        console.error(`  ${red('✘')} Embedding job failed.`);
+        if (job.errors) console.error(`  ${dim(JSON.stringify(job.errors).slice(0, 300))}`);
+        break;
+      }
+    } catch {
+      // Transient error, keep polling
+    }
+  }
+
+  if (attempts >= maxAttempts) {
+    console.log(`\n  ${yellow('!')} Timed out waiting for embeddings. They will complete in the background.`);
+  }
+
+  console.log(`\n  ${green('✓')} Synced ${entriesUploaded} entries.\n`);
+  await drainOfflineQueue(apiUrl, remote.apiKey);
+}
+
+// ---------------------------------------------------------------------------
+// remote pull — fetch remote entries to local
+// ---------------------------------------------------------------------------
+async function runRemotePull(getRemoteConfig, dataDir) {
+  const remote = getRemoteConfig(dataDir);
+  if (!remote || !remote.enabled || !remote.apiKey) {
+    console.error(`\n  ${red('✘')} Remote is not configured. Run ${cyan('context-vault remote setup')} first.\n`);
+    process.exit(1);
+  }
+
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const config = resolveConfig();
+
+  let DatabaseSync;
+  try {
+    DatabaseSync = (await import('node:sqlite')).DatabaseSync;
+  } catch {
+    console.error(`\n  ${red('✘')} Node.js SQLite not available. Requires Node >= 22.5.\n`);
+    process.exit(1);
+  }
+
+  const db = new DatabaseSync(config.dbPath, { open: true });
+  const apiUrl = remote.url.replace(/\/$/, '');
+
+  console.log();
+  console.log(`  ${bold('◇ Remote Pull')}`);
+  console.log();
+
+  // Fetch remote manifest
+  console.log(`  Fetching remote manifest...`);
+  let manifest;
+  try {
+    const res = await fetch(`${apiUrl}/api/vault/manifest`, {
+      headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+      signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      console.error(`  ${red('✘')} Manifest fetch failed: HTTP ${res.status}`);
+      if (text) console.error(`  ${dim(text.slice(0, 200))}`);
+      db.close();
+      process.exit(1);
+    }
+    manifest = await res.json();
+  } catch (e) {
+    console.error(`  ${red('✘')} Manifest fetch failed: ${e.message}`);
+    db.close();
+    process.exit(1);
+  }
+
+  const remoteEntries = manifest.entries || [];
+  console.log(`  Remote entries: ${remoteEntries.length}`);
+
+  // Build local manifest
+  const localRows = db.prepare('SELECT id, updated_at FROM vault').all();
+  const localMap = new Map();
+  for (const row of localRows) {
+    localMap.set(row.id, row.updated_at);
+  }
+
+  // Diff: remote entries not in local, or remote.updated_at > local.updated_at
+  const toPull = [];
+  for (const entry of remoteEntries) {
+    const localUpdated = localMap.get(entry.id);
+    if (!localUpdated) {
+      toPull.push(entry.id);
+    } else if (entry.updated_at && entry.updated_at > localUpdated) {
+      toPull.push(entry.id);
+    }
+  }
+
+  console.log(`  To pull: ${toPull.length}`);
+
+  if (toPull.length === 0) {
+    console.log(`\n  ${green('✓')} Local vault is up to date.\n`);
+    db.close();
+    await drainOfflineQueue(apiUrl, remote.apiKey);
+    return;
+  }
+
+  if (isDryRun) {
+    for (const id of toPull.slice(0, 20)) {
+      const remoteEntry = remoteEntries.find((e) => e.id === id);
+      console.log(`  ${dim(id)} ${remoteEntry?.kind || '?'} ${remoteEntry?.title || dim('(untitled)')}`);
+    }
+    if (toPull.length > 20) {
+      console.log(`  ${dim(`... and ${toPull.length - 20} more`)}`);
+    }
+    console.log(`\n  ${dim('Dry run. No changes made.')}\n`);
+    db.close();
+    return;
+  }
+
+  // Batch fetch in groups of 100
+  let pulled = 0;
+
+  // Ensure vault table has the columns we need for INSERT OR REPLACE
+  const insertStmt = db.prepare(`
+    INSERT OR REPLACE INTO vault (id, kind, category, title, body, tags, meta, source, identity_key, tier, expires_at, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  for (let i = 0; i < toPull.length; i += 100) {
+    const batch = toPull.slice(i, i + 100);
+    const idsParam = batch.join(',');
+    try {
+      const res = await fetch(`${apiUrl}/api/vault/entries?ids=${encodeURIComponent(idsParam)}`, {
+        headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+        signal: AbortSignal.timeout(30000),
+      });
+      if (!res.ok) {
+        console.error(`  ${red('✘')} Batch fetch failed: HTTP ${res.status}`);
+        continue;
+      }
+      const data = await res.json();
+      const entries = data.entries || data;
+      for (const entry of (Array.isArray(entries) ? entries : [])) {
+        const tags = typeof entry.tags === 'string' ? entry.tags : JSON.stringify(entry.tags || []);
+        const meta = typeof entry.meta === 'string' ? entry.meta : JSON.stringify(entry.meta || {});
+        insertStmt.run(
+          entry.id,
+          entry.kind || null,
+          entry.category || 'knowledge',
+          entry.title || null,
+          entry.body || '',
+          tags,
+          meta,
+          entry.source || null,
+          entry.identity_key || null,
+          entry.tier || 'working',
+          entry.expires_at || null,
+          entry.created_at || new Date().toISOString(),
+          entry.updated_at || new Date().toISOString()
+        );
+        pulled++;
+      }
+    } catch (e) {
+      console.error(`  ${yellow('!')} Batch fetch error: ${e.message}`);
+    }
+    process.stdout.write(`\r  Progress: ${Math.min(i + 100, toPull.length)}/${toPull.length}   `);
+  }
+
+  db.close();
+  process.stdout.write('\n');
+  console.log(`\n  ${green('✓')} Pulled ${pulled} entries from remote.\n`);
+  await drainOfflineQueue(apiUrl, remote.apiKey);
+}
+
+// ---------------------------------------------------------------------------
+// Offline queue drain — best-effort, runs after any successful remote call
+// ---------------------------------------------------------------------------
+async function drainOfflineQueue(apiUrl, apiKey) {
+  const queuePath = join(HOME, '.context-mcp', 'sync-queue.jsonl');
+  if (!existsSync(queuePath)) return;
+
+  let lines;
+  try {
+    const content = readFileSync(queuePath, 'utf-8').trim();
+    if (!content) {
+      unlinkSync(queuePath);
+      return;
+    }
+    lines = content.split('\n').filter(Boolean);
+  } catch {
+    return;
+  }
+
+  if (lines.length === 0) {
+    try { unlinkSync(queuePath); } catch {}
+    return;
+  }
+
+  console.log(`  ${dim(`Draining offline queue (${lines.length} entries)...`)}`);
+  const remaining = [];
+
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      const res = await fetch(`${apiUrl}/api/vault/entries`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(entry),
+        signal: AbortSignal.timeout(10000),
+      });
+      if (!res.ok) {
+        remaining.push(line);
+      }
+    } catch {
+      remaining.push(line);
+    }
+  }
+
+  if (remaining.length > 0) {
+    writeFileSync(queuePath, remaining.join('\n') + '\n');
+    console.log(`  ${yellow('!')} ${remaining.length} entries still queued (will retry next sync).`);
+  } else {
+    try { unlinkSync(queuePath); } catch {}
+    console.log(`  ${green('✓')} Offline queue drained.`);
+  }
+}
+
 async function main() {
   if (flags.has('--version') || command === 'version') {
     console.log(VERSION);
@@ -6926,8 +7908,13 @@ async function main() {
   }
 
   if (flags.has('--help') || command === 'help') {
-    showHelp(flags.has('--all'));
-    return;
+    // Commands with their own --help handling: delegate to them
+    const commandsWithHelp = new Set(['save', 'search', 'rules', 'hooks', 'daemon', 'team', 'remote']);
+    if (!command || command === 'help' || !commandsWithHelp.has(command)) {
+      showHelp(flags.has('--all'));
+      return;
+    }
+    // Fall through to command switch for commands with built-in --help
   }
 
   if (!command) {
@@ -7049,6 +8036,15 @@ async function main() {
     case 'debug':
       await runDebug();
       break;
+    case 'stats':
+      await runStats();
+      break;
+    case 'remote':
+      await runRemote();
+      break;
+    case 'team':
+      await runTeam();
+      break;
     default:
       console.error(red(`Unknown command: ${command}`));
       console.error(`Run ${cyan('context-vault --help')} for usage.`);