context-vault 3.4.4 → 3.4.5

package/node_modules/@context-vault/core/src/config.ts

@@ -1,9 +1,30 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { DEFAULT_GROWTH_THRESHOLDS, DEFAULT_LIFECYCLE } from './constants.js';
 import type { VaultConfig } from './types.js';
 
+/**
+ * Guard against writes to the real config file during test runs.
+ * Set CONTEXT_VAULT_TEST=1 in test helpers to activate.
+ *
+ * Allows writes if the target path is under a temp directory (tests with
+ * HOME overridden to a temp dir). Blocks writes to non-temp paths.
+ */
+export function assertNotTestMode(targetPath: string): void {
+  if (process.env.CONTEXT_VAULT_TEST !== '1') return;
+  const resolved = resolve(targetPath);
+  const tmp = tmpdir();
+  // Allow writes to temp directories (tests with HOME isolation)
+  if (resolved.startsWith(tmp) || resolved.startsWith('/tmp/') || resolved.startsWith('/var/folders/')) {
+    return;
+  }
+  throw new Error(
+    `[context-vault] Refusing to write to real config in test mode (${targetPath}). ` +
+      'Set HOME or CONTEXT_VAULT_DATA_DIR to a temp directory.'
+  );
+}
+
 export function parseArgs(argv: string[]): Record<string, string | number> {
   const args: Record<string, string | number> = {};
   for (let i = 2; i < argv.length; i++) {

package/node_modules/@context-vault/core/src/frontmatter.ts

@@ -59,6 +59,8 @@ export function parseFrontmatter(text: string): {
 const RESERVED_FM_KEYS = new Set([
   'id',
   'title',
+  'kind',
+  'tier',
   'tags',
   'source',
   'created',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-vault",
-  "version": "3.4.4",
+  "version": "3.4.5",
   "type": "module",
   "description": "Persistent memory for AI agents — saves and searches knowledge across sessions",
   "bin": {
@@ -63,7 +63,7 @@
     "@context-vault/core"
   ],
   "dependencies": {
-    "@context-vault/core": "^3.4.4",
+    "@context-vault/core": "^3.4.5",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "adm-zip": "^0.5.16",
     "sqlite-vec": "^0.1.0"

package/scripts/prepack.js

@@ -35,3 +35,20 @@ delete corePkg.dependencies;
 writeFileSync(corePkgPath, JSON.stringify(corePkg, null, 2) + '\n');
 
 console.log('[prepack] Bundled @context-vault/core into node_modules');
+
+// Copy monorepo-level assets (agent-rules.md, setup-prompt.md) into local assets/
+// so they ship with the npm package.
+const MONOREPO_ASSETS = join(LOCAL_ROOT, '..', '..', 'assets');
+const LOCAL_ASSETS = join(LOCAL_ROOT, 'assets');
+const ASSET_FILES = ['agent-rules.md', 'setup-prompt.md'];
+
+for (const file of ASSET_FILES) {
+  const src = join(MONOREPO_ASSETS, file);
+  const dest = join(LOCAL_ASSETS, file);
+  try {
+    cpSync(src, dest);
+    console.log(`[prepack] Copied ${file} to assets/`);
+  } catch (e) {
+    console.warn(`[prepack] Warning: could not copy ${file}: ${e.message}`);
+  }
+}

package/src/helpers.ts

@@ -58,4 +58,29 @@ export function ensureValidKind(kind: string): ToolResult | null {
   return null;
 }
 
+const KIND_ICONS: Record<string, string> = {
+  insight: '◆',
+  decision: '◇',
+  pattern: '◈',
+  reference: '▸',
+  event: '○',
+  session: '◎',
+  brief: '▪',
+  bucket: '▫',
+  contact: '●',
+  project: '■',
+  tool: '▹',
+  source: '►',
+  feedback: '◉',
+};
+
+export function kindIcon(kind: string): string {
+  return KIND_ICONS[kind] || '·';
+}
+
+export function fmtDate(date: string | null | undefined): string {
+  if (!date) return '';
+  return date.split('T')[0];
+}
+
 export { pkg };

package/src/server.ts

@@ -7,9 +7,9 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, unlinkSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -312,6 +312,29 @@ async function main(): Promise<void> {
 
     config.vaultDirExists = existsSync(config.vaultDir);
 
+    // Validate vaultDir sanity
+    const osTmp = tmpdir();
+    const isTempPath = config.vaultDir.startsWith(osTmp) ||
+      config.vaultDir.startsWith('/tmp/') ||
+      config.vaultDir.startsWith('/var/folders/');
+    if (isTempPath) {
+      console.error(`[context-vault] WARNING: vaultDir points to a temp directory: ${config.vaultDir}`);
+      console.error(`[context-vault] This is likely from a test run that overwrote ~/.context-mcp/config.json`);
+      console.error(`[context-vault] Fix: run 'context-vault reconnect' or 'context-vault setup'`);
+    }
+
+    if (config.vaultDirExists) {
+      try {
+        const entries = readdirSync(config.vaultDir);
+        const hasMdFiles = entries.some(f => f.endsWith('.md'));
+        const hasMarker = entries.includes('.context-mcp');
+        if (!hasMdFiles && hasMarker) {
+          console.error(`[context-vault] WARNING: vaultDir has no markdown files but has a marker file`);
+          console.error(`[context-vault] The vault may be misconfigured. Run 'context-vault reconnect'`);
+        }
+      } catch {}
+    }
+
     console.error(`[context-vault] Vault: ${config.vaultDir}`);
     console.error(`[context-vault] Database: ${config.dbPath}`);
     console.error(`[context-vault] Dev dir: ${config.devDir}`);

package/src/tools/context-status.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { gatherVaultStatus, computeGrowthWarnings } from '../status.js';
 import { errorLogPath, errorLogCount } from '../error-log.js';
-import { ok, err } from '../helpers.js';
+import { ok, err, kindIcon } from '../helpers.js';
 import type { LocalCtx, ToolResult } from '../types.js';
 
 function relativeTime(ts: number): string {
@@ -30,53 +30,53 @@ export function handler(_args: Record<string, any>, ctx: LocalCtx): ToolResult {
     const hasIssues = status.stalePaths || (status.embeddingStatus?.missing ?? 0) > 0;
     const healthIcon = hasIssues ? '⚠' : '✓';
 
+    const schemaVersion = (ctx.db.prepare('PRAGMA user_version').get() as any)?.user_version ?? 'unknown';
+    const embedPct = status.embeddingStatus
+      ? (status.embeddingStatus.total > 0 ? Math.round((status.embeddingStatus.indexed / status.embeddingStatus.total) * 100) : 100)
+      : null;
+    const embedStr = status.embeddingStatus
+      ? `${status.embeddingStatus.indexed}/${status.embeddingStatus.total} (${embedPct}%)`
+      : 'n/a';
+    const modelStr = status.embedModelAvailable === false ? '⚠ unavailable' : status.embedModelAvailable === true ? '✓ loaded' : 'unknown';
+
     const lines = [
-      `## ${healthIcon} Vault Status (connected)`,
+      `## ${healthIcon} Vault Dashboard`,
       ``,
-      `Vault:     ${config.vaultDir} (${config.vaultDirExists ? status.fileCount + ' files' : 'missing'})`,
-      `Database:  ${config.dbPath} (${status.dbSize})`,
-      `Dev dir:   ${config.devDir}`,
-      `Data dir:  ${config.dataDir}`,
-      `Config:    ${config.configPath}`,
-      `Resolved via: ${status.resolvedFrom}`,
-      `Schema:    v9 (updated_at, superseded_by)`,
+      `| | |`,
+      `|---|---|`,
+      `| **Vault** | ${config.vaultDir} (${config.vaultDirExists ? status.fileCount + ' files' : '⚠ missing'}) |`,
+      `| **Database** | ${config.dbPath} (${status.dbSize}) |`,
+      `| **Schema** | v${schemaVersion} |`,
+      `| **Embeddings** | ${embedStr} |`,
+      `| **Model** | ${modelStr} |`,
+      `| **Event decay** | ${config.eventDecayDays} days |`,
     ];
-
-    if (status.embeddingStatus) {
-      const { indexed, total, missing } = status.embeddingStatus;
-      const pct = total > 0 ? Math.round((indexed / total) * 100) : 100;
-      lines.push(`Embeddings: ${indexed}/${total} (${pct}%)`);
-    }
-    if (status.embedModelAvailable === false) {
-      lines.push(`Embed model: unavailable (semantic search disabled, FTS still works)`);
-    } else if (status.embedModelAvailable === true) {
-      lines.push(`Embed model: loaded`);
-    }
-    lines.push(`Decay:     ${config.eventDecayDays} days (event recency window)`);
     if (status.expiredCount > 0) {
-      lines.push(
-        `Expired:   ${status.expiredCount} entries pending prune (run \`context-vault prune\` to remove now)`
-      );
+      lines.push(`| **Expired** | ${status.expiredCount} pending prune |`);
     }
 
+    // Indexed kinds as compact table
     lines.push(``, `### Indexed`);
-
     if (status.kindCounts.length) {
-      for (const { kind, c } of status.kindCounts) lines.push(`- ${c} ${kind}s`);
+      lines.push('| Kind | Count |');
+      lines.push('|---|---|');
+      for (const { kind, c } of status.kindCounts) {
+        lines.push(`| ${kindIcon(kind)} \`${kind}\` | ${c} |`);
+      }
     } else {
-      lines.push(`- (empty)`);
+      lines.push(`_(empty vault)_`);
     }
 
     if (status.categoryCounts.length) {
       lines.push(``);
       lines.push(`### Categories`);
-      for (const { category, c } of status.categoryCounts) lines.push(`- ${category}: ${c}`);
+      for (const { category, c } of status.categoryCounts) lines.push(`- **${category}**: ${c}`);
     }
 
     if (status.subdirs.length) {
       lines.push(``);
-      lines.push(`### Disk Directories`);
-      for (const { name, count } of status.subdirs) lines.push(`- ${name}/: ${count} files`);
+      lines.push(`### Disk`);
+      for (const { name, count } of status.subdirs) lines.push(`- \`${name}/\` ${count} files`);
     }
 
     if (status.stalePaths) {

package/src/tools/get-context.ts

@@ -8,7 +8,7 @@ import { normalizeKind } from '@context-vault/core/files';
 import { parseContextParam } from '@context-vault/core/context';
 import { resolveTemporalParams } from '../temporal.js';
 import { collectLinkedEntries } from '../linking.js';
-import { ok, err, errWithHint } from '../helpers.js';
+import { ok, err, errWithHint, kindIcon, fmtDate } from '../helpers.js';
 import { isEmbedAvailable } from '@context-vault/core/embed';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
@@ -633,23 +633,24 @@ export async function handler(
     const r = filtered[i];
     const isSkeleton = i >= effectivePivot;
     const entryTags = r.tags ? JSON.parse(r.tags) : [];
-    const tagStr = entryTags.length ? entryTags.join(', ') : 'none';
-    const relPath =
-      r.file_path && config.vaultDir
-        ? r.file_path.replace(config.vaultDir + '/', '')
-        : r.file_path || 'n/a';
-    const skeletonLabel = isSkeleton ? ' ⊘ skeleton' : '';
+    const tagStr = entryTags.length ? entryTags.join(', ') : '';
+    const icon = kindIcon(r.kind);
+    const skeletonLabel = isSkeleton ? ' `skeleton`' : '';
+    const tierLabel = r.tier ? `**${r.tier}**` : '';
+    const dateStr = r.updated_at && r.updated_at !== r.created_at
+      ? `${fmtDate(r.created_at)} (upd ${fmtDate(r.updated_at)})`
+      : fmtDate(r.created_at);
     lines.push(
-      `### [${i + 1}/${filtered.length}] ${r.title || '(untitled)'} [${r.kind}/${r.category}]${skeletonLabel}`
-    );
-    const dateStr =
-      r.updated_at && r.updated_at !== r.created_at
-        ? `${r.created_at} (updated ${r.updated_at})`
-        : r.created_at || '';
-    const tierStr = r.tier ? ` · tier: ${r.tier}` : '';
-    lines.push(
-      `${r.score.toFixed(3)} · ${tagStr} · ${relPath} · ${dateStr} · skeleton: ${isSkeleton}${tierStr} · id: \`${r.id}\``
+      `### ${icon} ${r.title || '(untitled)'}${skeletonLabel}`
     );
+    const meta = [
+      `\`${r.score.toFixed(2)}\``,
+      `\`${r.kind}\``,
+      tierLabel,
+      tagStr,
+      dateStr,
+    ].filter(Boolean).join(' · ');
+    lines.push(`${meta}  \nid: \`${r.id}\``);
     const stalenessResult = checkStaleness(r);
     if (stalenessResult) {
       r.stale = true;
@@ -691,15 +692,13 @@ export async function handler(
     if (uniqueLinked.length > 0) {
       lines.push(`## Linked Entries (${uniqueLinked.length} via related_to)\n`);
       for (const r of uniqueLinked) {
-        const direction = forward.some((f: any) => f.id === r.id) ? '→ forward' : '← backlink';
+        const direction = forward.some((f: any) => f.id === r.id) ? '→' : '←';
         const entryTags = r.tags ? JSON.parse(r.tags) : [];
-        const tagStr = entryTags.length ? entryTags.join(', ') : 'none';
-        const relPath =
-          r.file_path && config.vaultDir
-            ? r.file_path.replace(config.vaultDir + '/', '')
-            : r.file_path || 'n/a';
-        lines.push(`### ${r.title || '(untitled)'} [${r.kind}/${r.category}] ${direction}`);
-        lines.push(`${tagStr} · ${relPath} · id: \`${r.id}\``);
+        const tagStr = entryTags.length ? entryTags.join(', ') : '';
+        const icon = kindIcon(r.kind);
+        lines.push(`### ${icon} ${r.title || '(untitled)'} ${direction}`);
+        const meta = [`\`${r.kind}\``, tagStr].filter(Boolean).join(' · ');
+        lines.push(`${meta}  \nid: \`${r.id}\``);
         lines.push(truncateBody(r.body, body_limit ?? 300));
         lines.push('');
       }

package/src/tools/list-context.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { normalizeKind } from '@context-vault/core/files';
 import { categoryFor } from '@context-vault/core/categories';
-import { ok, err, errWithHint } from '../helpers.js';
+import { ok, err, errWithHint, kindIcon, fmtDate } from '../helpers.js';
 import { resolveTemporalParams } from '../temporal.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
@@ -124,18 +124,15 @@ export async function handler(
       `> ℹ Event search limited to last ${days} days. Use \`since\` parameter for older results.\n`
     );
   }
+  lines.push('| | Title | Kind | Tags | Date | ID |');
+  lines.push('|---|---|---|---|---|---|');
   for (const r of filtered) {
     const entryTags = r.tags ? JSON.parse(r.tags) : [];
-    const tagStr = entryTags.length ? entryTags.join(', ') : 'none';
-    const dateStr =
-      r.updated_at && r.updated_at !== r.created_at
-        ? `${r.created_at} (updated ${r.updated_at})`
-        : r.created_at;
-    lines.push(
-      `- **${r.title || '(untitled)'}** [${r.kind}/${r.category}] — ${tagStr} — ${dateStr} — \`${r.id}\``
-    );
-    if (r.preview)
-      lines.push(`  ${r.preview.replace(/\n+/g, ' ').trim()}${r.preview.length >= 120 ? '…' : ''}`);
+    const tagStr = entryTags.length ? entryTags.join(', ') : '';
+    const date = fmtDate(r.updated_at && r.updated_at !== r.created_at ? r.updated_at : r.created_at);
+    const icon = kindIcon(r.kind);
+    const title = (r.title || '(untitled)').replace(/\|/g, '\\|');
+    lines.push(`| ${icon} | **${title}** | \`${r.kind}\` | ${tagStr} | ${date} | \`${r.id}\` |`);
   }
 
   if (effectiveOffset + effectiveLimit < total) {

package/src/tools/save-context.ts

@@ -4,7 +4,7 @@ import { indexEntry } from '@context-vault/core/index';
 import { categoryFor, defaultTierFor } from '@context-vault/core/categories';
 import { normalizeKind } from '@context-vault/core/files';
 import { parseContextParam } from '@context-vault/core/context';
-import { ok, err, errWithHint, ensureVaultExists, ensureValidKind } from '../helpers.js';
+import { ok, err, errWithHint, ensureVaultExists, ensureValidKind, kindIcon } from '../helpers.js';
 import { maybeShowFeedbackPrompt } from '../telemetry.js';
 import { validateRelatedTo } from '../linking.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
@@ -82,13 +82,13 @@ async function findSimilar(
 }
 
 function formatSimilarWarning(similar: any[]): string {
-  const lines = ['', '⚠ Similar entries already exist:'];
+  const lines = ['', '### ⚠ Similar entries'];
   for (const e of similar) {
-    const score = e.score.toFixed(2);
-    const title = e.title ? `"${e.title}"` : '(no title)';
-    lines.push(`  - ${title} (${score}) — id: ${e.id}`);
+    const score = (e.score * 100).toFixed(0);
+    const title = e.title ? `**${e.title}**` : '(no title)';
+    lines.push(`- ${title} \`${score}%\` · \`${e.id}\``);
   }
-  lines.push('  Consider using `id: <existing>` in save_context to update instead.');
+  lines.push('_Use `id` param to update instead of creating a duplicate._');
   return lines.join('\n');
 }
 
@@ -142,13 +142,12 @@ export function buildConflictCandidates(similarEntries: any[]): any[] {
 }
 
 function formatConflictSuggestions(candidates: any[]): string {
-  const lines = ['', '── Conflict Resolution Suggestions ──'];
+  const lines = ['', '### Conflict Resolution'];
   for (const c of candidates) {
-    const titleDisplay = c.title ? `"${c.title}"` : '(no title)';
-    lines.push(
-      `  [${c.suggested_action}] ${titleDisplay} (${(c.score * 100).toFixed(0)}%) — id: ${c.id}`
-    );
-    lines.push(`    ${c.reasoning_context}`);
+    const titleDisplay = c.title ? `**${c.title}**` : '(no title)';
+    const actionIcon = c.suggested_action === 'SKIP' ? '⊘' : c.suggested_action === 'UPDATE' ? '↻' : '＋';
+    lines.push(`${actionIcon} **${c.suggested_action}** ${titleDisplay} \`${(c.score * 100).toFixed(0)}%\` · \`${c.id}\``);
+    lines.push(`  ${c.reasoning_context}`);
   }
   return lines.join('\n');
 }
@@ -606,11 +605,19 @@ export async function handler(
   const relPath = entry.filePath
     ? entry.filePath.replace(config.vaultDir + '/', '')
     : entry.filePath;
-  const parts = [`✓ Saved ${normalizedKind} → ${relPath}`, `  id: ${entry.id}`];
-  if (title) parts.push(`  title: ${title}`);
-  if (tags?.length) parts.push(`  tags: ${tags.join(', ')}`);
-  parts.push(`  tier: ${effectiveTier}`);
-  parts.push('', '_Use this id to update or delete later._');
+  const icon = kindIcon(normalizedKind);
+  const parts = [
+    `## ✓ Saved`,
+    `${icon} **${title || '(untitled)'}**`,
+    `\`${normalizedKind}\` · **${effectiveTier}**${tags?.length ? ` · ${tags.join(', ')}` : ''}`,
+    `\`${entry.id}\` → ${relPath}`,
+  ];
+  if (effectiveTier === 'ephemeral') {
+    parts.push(
+      '',
+      '_Note: ephemeral entries are excluded from default search. Use `include_ephemeral: true` in get_context to find them._'
+    );
+  }
   const hasBucketTag = (tags || []).some(
     (t: any) => typeof t === 'string' && t.startsWith('bucket:')
   );
@@ -624,18 +631,25 @@ export async function handler(
     (t: any) => typeof t === 'string' && t.startsWith('bucket:')
   );
   for (const bt of bucketTags) {
-    const bucketUserClause = '';
-    const bucketParams = false ? [bt] : [bt];
     const exists = ctx.db
       .prepare(
-        `SELECT 1 FROM vault WHERE kind = 'bucket' AND identity_key = ? ${bucketUserClause} LIMIT 1`
+        `SELECT 1 FROM vault WHERE kind = 'bucket' AND identity_key = ? LIMIT 1`
       )
-      .get(...bucketParams);
+      .get(bt);
     if (!exists) {
-      parts.push(
-        ``,
-        `_Note: bucket '${bt}' is not registered. Use save_context(kind: "bucket", identity_key: "${bt}") to register it._`
-      );
+      // Auto-register the bucket silently
+      const bucketName = bt.replace(/^bucket:/, '');
+      try {
+        await captureAndIndex(ctx, {
+          kind: 'bucket',
+          title: bucketName,
+          body: `Bucket for project: ${bucketName}`,
+          tags: [bt],
+          identity_key: bt,
+        });
+      } catch {
+        // Non-fatal: bucket registration failure should not block the save
+      }
     }
   }
   if (similarEntries.length) {

package/src/tools/session-start.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { execSync } from 'node:child_process';
-import { ok, err, ensureVaultExists } from '../helpers.js';
+import { readdirSync } from 'node:fs';
+import { ok, err, ensureVaultExists, kindIcon, fmtDate } from '../helpers.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
 const DEFAULT_MAX_TOKENS = 4000;
@@ -67,11 +68,13 @@ function estimateTokens(text: string | null | undefined): number {
 
 function formatEntry(entry: any): string {
   const tags = entry.tags ? JSON.parse(entry.tags) : [];
-  const tagStr = tags.length ? tags.join(', ') : 'none';
-  const date = entry.updated_at || entry.created_at || 'unknown';
+  const tagStr = tags.length ? tags.join(', ') : '';
+  const date = fmtDate(entry.updated_at || entry.created_at);
+  const icon = kindIcon(entry.kind);
+  const meta = [`\`${entry.kind}\``, tagStr, date].filter(Boolean).join(' · ');
   return [
-    `- **${entry.title || '(untitled)'}** [${entry.kind}]`,
-    `  tags: ${tagStr} | ${date} | id: \`${entry.id}\``,
+    `- ${icon} **${entry.title || '(untitled)'}**`,
+    `  ${meta} · \`${entry.id}\``,
     `  ${truncateBody(entry.body).replace(/\n+/g, ' ').trim()}`,
   ].join('\n');
 }
@@ -88,6 +91,30 @@ export async function handler(
 
   await ensureIndexed();
 
+  // Sanity check: compare DB entries vs disk files
+  let indexWarning = '';
+  try {
+    const dbCount = (ctx.db.prepare('SELECT COUNT(*) as cnt FROM vault').get() as any)?.cnt ?? 0;
+    let diskCount = 0;
+    const walk = (dir: string, depth = 0) => {
+      if (depth > 3 || diskCount >= 100) return;
+      try {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          if (diskCount >= 100) return;
+          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== '_archive') {
+            walk(`${dir}/${entry.name}`, depth + 1);
+          } else if (entry.name.endsWith('.md')) {
+            diskCount++;
+          }
+        }
+      } catch {}
+    };
+    walk(config.vaultDir);
+    if (diskCount >= 100 && dbCount < diskCount / 10) {
+      indexWarning = `\n> **WARNING:** Vault has significantly more files on disk (~${diskCount}+) than indexed entries (${dbCount}). The search index may be out of sync. Run \`context-vault reconnect\` to fix.\n`;
+    }
+  } catch {}
+
   const effectiveProject = project?.trim() || detectProject();
   const tokenBudget = max_tokens || DEFAULT_MAX_TOKENS;
 
@@ -175,6 +202,10 @@ export async function handler(
       return true;
     }).length;
 
+  if (indexWarning) {
+    sections.push(indexWarning);
+  }
+
   sections.push('---');
   sections.push(
     `_${tokensUsed} / ${tokenBudget} tokens used | project: ${effectiveProject || 'unscoped'}_`