codebase-context 1.6.2 → 1.8.0

package/dist/index.js

@@ -1,31 +1,28 @@
 #!/usr/bin/env node
-/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * MCP Server for Codebase Context
  * Provides codebase indexing and semantic search capabilities
  */
 import { promises as fs } from 'fs';
 import path from 'path';
-import { glob } from 'glob';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { CodebaseIndexer } from './core/indexer.js';
-import { CodebaseSearcher } from './core/search.js';
 import { analyzerRegistry } from './core/analyzer-registry.js';
 import { AngularAnalyzer } from './analyzers/angular/index.js';
 import { GenericAnalyzer } from './analyzers/generic/index.js';
-import { InternalFileGraph } from './utils/usage-tracker.js';
 import { IndexCorruptedError } from './errors/index.js';
 import { CODEBASE_CONTEXT_DIRNAME, MEMORY_FILENAME, INTELLIGENCE_FILENAME, KEYWORD_INDEX_FILENAME, VECTOR_DB_DIRNAME } from './constants/codebase-context.js';
-import { appendMemoryFile, readMemoriesFile, filterMemories, applyUnfilteredLimit, withConfidence } from './memory/store.js';
-import { handleMemoryCli } from './cli.js';
+import { appendMemoryFile } from './memory/store.js';
+import { handleCliCommand } from './cli.js';
+import { startFileWatcher } from './core/file-watcher.js';
+import { createAutoRefreshController } from './core/auto-refresh.js';
 import { parseGitLogLineToMemory } from './memory/git-memory.js';
-import { buildEvidenceLock } from './preflight/evidence-lock.js';
-import { shouldIncludePatternConflictCategory } from './preflight/query-scope.js';
-import { isComplementaryPatternCategory, isComplementaryPatternConflict, shouldSkipLegacyTestingFrameworkCategory } from './patterns/semantics.js';
+import { isComplementaryPatternCategory, shouldSkipLegacyTestingFrameworkCategory } from './patterns/semantics.js';
 import { CONTEXT_RESOURCE_URI, isContextResourceUri } from './resources/uri.js';
-import { assessSearchQuality } from './core/search-quality.js';
+import { readIndexMeta, validateIndexArtifacts } from './core/index-meta.js';
+import { TOOLS, dispatchTool } from './tools/index.js';
 analyzerRegistry.register(new AngularAnalyzer());
 analyzerRegistry.register(new GenericAnalyzer());
 // Resolve root path with validation
@@ -56,6 +53,70 @@ const LEGACY_PATHS = {
     keywordIndex: path.join(ROOT_PATH, '.codebase-index.json'),
     vectorDb: path.join(ROOT_PATH, '.codebase-index')
 };
+export const INDEX_CONSUMING_TOOL_NAMES = [
+    'search_codebase',
+    'get_symbol_references',
+    'detect_circular_dependencies',
+    'get_team_patterns',
+    'get_codebase_metadata'
+];
+export const INDEX_CONSUMING_RESOURCE_NAMES = ['Codebase Intelligence'];
+async function requireValidIndex(rootPath) {
+    const meta = await readIndexMeta(rootPath);
+    await validateIndexArtifacts(rootPath, meta);
+    // Optional artifact presence informs confidence.
+    const hasIntelligence = await fileExists(PATHS.intelligence);
+    return {
+        status: 'ready',
+        confidence: hasIntelligence ? 'high' : 'low',
+        action: 'served',
+        ...(hasIntelligence ? {} : { reason: 'Optional intelligence artifact missing' })
+    };
+}
+async function ensureValidIndexOrAutoHeal() {
+    if (indexState.status === 'indexing') {
+        return {
+            status: 'indexing',
+            confidence: 'low',
+            action: 'served',
+            reason: 'Indexing in progress'
+        };
+    }
+    try {
+        return await requireValidIndex(ROOT_PATH);
+    }
+    catch (error) {
+        if (error instanceof IndexCorruptedError) {
+            const reason = error.message;
+            console.error(`[Index] ${reason}`);
+            console.error('[Auto-Heal] Triggering full re-index...');
+            await performIndexing();
+            if (indexState.status === 'ready') {
+                try {
+                    let validated = await requireValidIndex(ROOT_PATH);
+                    validated = { ...validated, action: 'rebuilt-and-served', reason };
+                    return validated;
+                }
+                catch (revalidateError) {
+                    const msg = revalidateError instanceof Error ? revalidateError.message : String(revalidateError);
+                    return {
+                        status: 'rebuild-required',
+                        confidence: 'low',
+                        action: 'rebuild-failed',
+                        reason: `Auto-heal completed but index did not validate: ${msg}`
+                    };
+                }
+            }
+            return {
+                status: 'rebuild-required',
+                confidence: 'low',
+                action: 'rebuild-failed',
+                reason: `Auto-heal failed: ${indexState.error || reason}`
+            };
+        }
+        throw error;
+    }
+}
 /**
  * Check if file/directory exists
  */
@@ -120,6 +181,7 @@ const PKG_VERSION = JSON.parse(await fs.readFile(new URL('../package.json', impo
 const indexState = {
     status: 'idle'
 };
+const autoRefresh = createAutoRefreshController();
 const server = new Server({
     name: 'codebase-context',
     version: PKG_VERSION
@@ -129,228 +191,6 @@ const server = new Server({
         resources: {}
     }
 });
-const TOOLS = [
-    {
-        name: 'search_codebase',
-        description: 'Search the indexed codebase. Returns ranked results and a searchQuality confidence summary. ' +
-            'IMPORTANT: Pass the intent="edit"|"refactor"|"migrate" to get preflight: edit readiness check with evidence gating.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                query: {
-                    type: 'string',
-                    description: 'Natural language search query'
-                },
-                intent: {
-                    type: 'string',
-                    enum: ['explore', 'edit', 'refactor', 'migrate'],
-                    description: 'Optional. Use "edit", "refactor", or "migrate" to get the full preflight card before making changes.'
-                },
-                limit: {
-                    type: 'number',
-                    description: 'Maximum number of results to return (default: 5)',
-                    default: 5
-                },
-                includeSnippets: {
-                    type: 'boolean',
-                    description: 'Include code snippets in results (default: false). If you need code, prefer read_file instead.',
-                    default: false
-                },
-                filters: {
-                    type: 'object',
-                    description: 'Optional filters',
-                    properties: {
-                        framework: {
-                            type: 'string',
-                            description: 'Filter by framework (angular, react, vue)'
-                        },
-                        language: {
-                            type: 'string',
-                            description: 'Filter by programming language'
-                        },
-                        componentType: {
-                            type: 'string',
-                            description: 'Filter by component type (component, service, directive, etc.)'
-                        },
-                        layer: {
-                            type: 'string',
-                            description: 'Filter by architectural layer (presentation, business, data, state, core, shared)'
-                        },
-                        tags: {
-                            type: 'array',
-                            items: { type: 'string' },
-                            description: 'Filter by tags'
-                        }
-                    }
-                }
-            },
-            required: ['query']
-        }
-    },
-    {
-        name: 'get_codebase_metadata',
-        description: 'Get codebase metadata including framework information, dependencies, architecture patterns, ' +
-            'and project statistics.',
-        inputSchema: {
-            type: 'object',
-            properties: {}
-        }
-    },
-    {
-        name: 'get_indexing_status',
-        description: 'Get current indexing status: state, statistics, and progress. ' +
-            'Use refresh_index to manually trigger re-indexing when needed.',
-        inputSchema: {
-            type: 'object',
-            properties: {}
-        }
-    },
-    {
-        name: 'refresh_index',
-        description: 'Re-index the codebase. Supports full re-index or incremental mode. ' +
-            'Use incrementalOnly=true to only process files changed since last index.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                reason: {
-                    type: 'string',
-                    description: 'Reason for refreshing the index (for logging)'
-                },
-                incrementalOnly: {
-                    type: 'boolean',
-                    description: 'If true, only re-index files changed since last full index (faster). Default: false (full re-index)'
-                }
-            }
-        }
-    },
-    {
-        name: 'get_style_guide',
-        description: 'Query style guide rules and architectural patterns from project documentation.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                query: {
-                    type: 'string',
-                    description: 'Query for specific style guide rules (e.g., "component naming", "service patterns")'
-                },
-                category: {
-                    type: 'string',
-                    description: 'Filter by category (naming, structure, patterns, testing)'
-                }
-            }
-        }
-    },
-    {
-        name: 'get_team_patterns',
-        description: 'Get actionable team pattern recommendations based on codebase analysis. ' +
-            'Returns consensus patterns for DI, state management, testing, library wrappers, etc.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                category: {
-                    type: 'string',
-                    description: 'Pattern category to retrieve',
-                    enum: ['all', 'di', 'state', 'testing', 'libraries']
-                }
-            }
-        }
-    },
-    {
-        name: 'get_component_usage',
-        description: 'Find WHERE a library or component is used in the codebase. ' +
-            "This is 'Find Usages' - returns all files that import a given package/module. " +
-            "Example: get_component_usage('@mycompany/utils') -> shows all files using it.",
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: {
-                    type: 'string',
-                    description: "Import source to find usages for (e.g., 'primeng/table', '@mycompany/ui/button', 'lodash')"
-                }
-            },
-            required: ['name']
-        }
-    },
-    {
-        name: 'detect_circular_dependencies',
-        description: 'Analyze the import graph to detect circular dependencies between files. ' +
-            'Circular dependencies can cause initialization issues, tight coupling, and maintenance problems. ' +
-            'Returns all detected cycles sorted by length (shorter cycles are often more problematic).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                scope: {
-                    type: 'string',
-                    description: "Optional path prefix to limit analysis (e.g., 'src/features', 'libs/shared')"
-                }
-            }
-        }
-    },
-    {
-        name: 'remember',
-        description: 'CALL IMMEDIATELY when user explicitly asks to remember/record something.\n\n' +
-            'USER TRIGGERS:\n' +
-            '- "Remember this: [X]"\n' +
-            '- "Record this: [Y]"\n' +
-            '- "Save this for next time: [Z]"\n\n' +
-            'DO NOT call unless user explicitly requests it.\n\n' +
-            'HOW TO WRITE:\n' +
-            '- ONE convention per memory (if user lists 5 things, call this 5 times)\n' +
-            '- memory: 5-10 words (the specific rule)\n' +
-            '- reason: 1 sentence (why it matters)\n' +
-            '- Skip: one-time features, code examples, essays',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                type: {
-                    type: 'string',
-                    enum: ['convention', 'decision', 'gotcha', 'failure'],
-                    description: 'Type of memory being recorded. Use "failure" for things that were tried and failed - ' +
-                        'prevents repeating the same mistakes.'
-                },
-                category: {
-                    type: 'string',
-                    description: 'Broader category for filtering',
-                    enum: ['tooling', 'architecture', 'testing', 'dependencies', 'conventions']
-                },
-                memory: {
-                    type: 'string',
-                    description: 'What to remember (concise)'
-                },
-                reason: {
-                    type: 'string',
-                    description: 'Why this matters or what breaks otherwise'
-                }
-            },
-            required: ['type', 'category', 'memory', 'reason']
-        }
-    },
-    {
-        name: 'get_memory',
-        description: 'Retrieves team conventions, architectural decisions, and known gotchas.\n' +
-            'CALL BEFORE suggesting patterns, libraries, or architecture.\n\n' +
-            'Filters: category (tooling/architecture/testing/dependencies/conventions), type (convention/decision/gotcha), query (keyword search).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                category: {
-                    type: 'string',
-                    description: 'Filter by category',
-                    enum: ['tooling', 'architecture', 'testing', 'dependencies', 'conventions']
-                },
-                type: {
-                    type: 'string',
-                    description: 'Filter by memory type',
-                    enum: ['convention', 'decision', 'gotcha', 'failure']
-                },
-                query: {
-                    type: 'string',
-                    description: 'Keyword search across memory and reason'
-                }
-            }
-        }
-    }
-];
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools: TOOLS };
 });
@@ -369,12 +209,27 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
 });
 async function generateCodebaseContext() {
     const intelligencePath = PATHS.intelligence;
+    const index = await ensureValidIndexOrAutoHeal();
+    if (index.status === 'indexing') {
+        return ('# Codebase Intelligence\n\n' +
+            'Index is still being built. Retry in a moment.\n\n' +
+            `Index: ${index.status} (${index.confidence}, ${index.action})` +
+            (index.reason ? `\nReason: ${index.reason}` : ''));
+    }
+    if (index.action === 'rebuild-failed') {
+        return ('# Codebase Intelligence\n\n' +
+            'Index rebuild required before intelligence can be served.\n\n' +
+            `Index: ${index.status} (${index.confidence}, ${index.action})` +
+            (index.reason ? `\nReason: ${index.reason}` : ''));
+    }
     try {
         const content = await fs.readFile(intelligencePath, 'utf-8');
         const intelligence = JSON.parse(content);
         const lines = [];
         lines.push('# Codebase Intelligence');
         lines.push('');
+        lines.push(`Index: ${index.status} (${index.confidence}, ${index.action})${index.reason ? ` — ${index.reason}` : ''}`);
+        lines.push('');
         lines.push('WARNING: This is what YOUR codebase actually uses, not generic recommendations.');
         lines.push('These are FACTS from analyzing your code, not best practices from the internet.');
         lines.push('');
@@ -535,7 +390,7 @@ async function extractGitMemories() {
     }
     return added;
 }
-async function performIndexing(incrementalOnly) {
+async function performIndexingOnce(incrementalOnly) {
     indexState.status = 'indexing';
     const mode = incrementalOnly ? 'incremental' : 'full';
     console.error(`Indexing (${mode}): ${ROOT_PATH}`);
@@ -577,6 +432,19 @@ async function performIndexing(incrementalOnly) {
         console.error('Indexing failed:', indexState.error);
     }
 }
+async function performIndexing(incrementalOnly) {
+    let nextMode = incrementalOnly;
+    for (;;) {
+        await performIndexingOnce(nextMode);
+        const shouldRunQueuedRefresh = autoRefresh.consumeQueuedRefresh(indexState.status);
+        if (!shouldRunQueuedRefresh)
+            return;
+        if (process.env.CODEBASE_CONTEXT_DEBUG) {
+            console.error('[file-watcher] Running queued auto-refresh');
+        }
+        nextMode = true;
+    }
+}
 async function shouldReindex() {
     const indexPath = PATHS.keywordIndex;
     try {
@@ -590,1106 +458,79 @@ async function shouldReindex() {
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-        switch (name) {
-            case 'search_codebase': {
-                const { query, limit, filters, intent, includeSnippets } = args;
-                const queryStr = typeof query === 'string' ? query.trim() : '';
-                if (!queryStr) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'error',
-                                    errorCode: 'invalid_params',
-                                    message: "Invalid params: 'query' is required and must be a non-empty string.",
-                                    hint: "Provide a query like 'how are routes configured' or 'AlbumApiService'."
-                                }, null, 2)
-                            }
-                        ],
-                        isError: true
-                    };
-                }
-                if (indexState.status === 'indexing') {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'indexing',
-                                    message: 'Index is still being built. Retry in a moment.',
-                                    progress: indexState.indexer?.getProgress()
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-                if (indexState.status === 'error') {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'error',
-                                    message: `Indexing failed: ${indexState.error}`
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-                const searcher = new CodebaseSearcher(ROOT_PATH);
-                let results;
-                const searchProfile = intent && ['explore', 'edit', 'refactor', 'migrate'].includes(intent)
-                    ? intent
-                    : 'explore';
-                try {
-                    results = await searcher.search(queryStr, limit || 5, filters, {
-                        profile: searchProfile
-                    });
-                }
-                catch (error) {
-                    if (error instanceof IndexCorruptedError) {
-                        console.error('[Auto-Heal] Index corrupted. Triggering full re-index...');
-                        await performIndexing();
-                        if (indexState.status === 'ready') {
-                            console.error('[Auto-Heal] Success. Retrying search...');
-                            const freshSearcher = new CodebaseSearcher(ROOT_PATH);
-                            try {
-                                results = await freshSearcher.search(queryStr, limit || 5, filters, {
-                                    profile: searchProfile
-                                });
-                            }
-                            catch (retryError) {
-                                return {
-                                    content: [
-                                        {
-                                            type: 'text',
-                                            text: JSON.stringify({
-                                                status: 'error',
-                                                message: `Auto-heal retry failed: ${retryError instanceof Error ? retryError.message : String(retryError)}`
-                                            }, null, 2)
-                                        }
-                                    ]
-                                };
-                            }
-                        }
-                        else {
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            status: 'error',
-                                            message: `Auto-heal failed: Indexing ended with status '${indexState.status}'`,
-                                            error: indexState.error
-                                        }, null, 2)
-                                    }
-                                ]
-                            };
-                        }
-                    }
-                    else {
-                        throw error; // Propagate unexpected errors
-                    }
-                }
-                // Load memories for keyword matching, enriched with confidence
-                const allMemories = await readMemoriesFile(PATHS.memory);
-                const allMemoriesWithConf = withConfidence(allMemories);
-                const queryTerms = queryStr.toLowerCase().split(/\s+/).filter(Boolean);
-                const relatedMemories = allMemoriesWithConf
-                    .filter((m) => {
-                    const searchText = `${m.memory} ${m.reason}`.toLowerCase();
-                    return queryTerms.some((term) => searchText.includes(term));
-                })
-                    .sort((a, b) => b.effectiveConfidence - a.effectiveConfidence);
-                // Load intelligence data for enrichment (all intents, not just preflight)
-                let intelligence = null;
-                try {
-                    const intelligenceContent = await fs.readFile(PATHS.intelligence, 'utf-8');
-                    intelligence = JSON.parse(intelligenceContent);
-                }
-                catch {
-                    /* graceful degradation — intelligence file may not exist yet */
-                }
-                function computeIndexConfidence() {
-                    let confidence = 'stale';
-                    if (intelligence?.generatedAt) {
-                        const indexAge = Date.now() - new Date(intelligence.generatedAt).getTime();
-                        const hoursOld = indexAge / (1000 * 60 * 60);
-                        if (hoursOld < 24) {
-                            confidence = 'fresh';
-                        }
-                        else if (hoursOld < 168) {
-                            confidence = 'aging';
-                        }
-                    }
-                    return confidence;
-                }
-                // Cheap impact breadth estimate from the import graph (used for risk assessment).
-                function computeImpactCandidates(resultPaths) {
-                    const impactCandidates = [];
-                    if (!intelligence?.internalFileGraph?.imports)
-                        return impactCandidates;
-                    const allImports = intelligence.internalFileGraph.imports;
-                    for (const [file, deps] of Object.entries(allImports)) {
-                        if (deps.some((dep) => resultPaths.some((rp) => dep.endsWith(rp) || rp.endsWith(dep)))) {
-                            if (!resultPaths.some((rp) => file.endsWith(rp) || rp.endsWith(file))) {
-                                impactCandidates.push(file);
-                            }
-                        }
-                    }
-                    return impactCandidates;
-                }
-                // Build reverse import map from intelligence graph
-                const reverseImports = new Map();
-                if (intelligence?.internalFileGraph?.imports) {
-                    for (const [file, deps] of Object.entries(intelligence.internalFileGraph.imports)) {
-                        for (const dep of deps) {
-                            if (!reverseImports.has(dep))
-                                reverseImports.set(dep, []);
-                            reverseImports.get(dep).push(file);
-                        }
-                    }
-                }
-                // Enrich a search result with relationship data
-                function enrichResult(r) {
-                    const rPath = r.filePath;
-                    // importedBy: files that import this result (reverse lookup)
-                    const importedBy = [];
-                    for (const [dep, importers] of reverseImports) {
-                        if (dep.endsWith(rPath) || rPath.endsWith(dep)) {
-                            importedBy.push(...importers);
-                        }
-                    }
-                    // imports: files this result depends on (forward lookup)
-                    const imports = [];
-                    if (intelligence?.internalFileGraph?.imports) {
-                        for (const [file, deps] of Object.entries(intelligence.internalFileGraph.imports)) {
-                            if (file.endsWith(rPath) || rPath.endsWith(file)) {
-                                imports.push(...deps);
-                            }
-                        }
-                    }
-                    // testedIn: heuristic — same basename with .spec/.test extension
-                    const testedIn = [];
-                    const baseName = path.basename(rPath).replace(/\.[^.]+$/, '');
-                    if (intelligence?.internalFileGraph?.imports) {
-                        for (const file of Object.keys(intelligence.internalFileGraph.imports)) {
-                            const fileBase = path.basename(file);
-                            if ((fileBase.includes('.spec.') || fileBase.includes('.test.')) &&
-                                fileBase.startsWith(baseName)) {
-                                testedIn.push(file);
-                            }
-                        }
-                    }
-                    // Only return if we have at least one piece of data
-                    if (importedBy.length === 0 && imports.length === 0 && testedIn.length === 0) {
-                        return undefined;
-                    }
-                    return {
-                        ...(importedBy.length > 0 && { importedBy }),
-                        ...(imports.length > 0 && { imports }),
-                        ...(testedIn.length > 0 && { testedIn })
-                    };
-                }
-                const searchQuality = assessSearchQuality(query, results);
-                // Always-on edit preflight (lite): do not require intent and keep payload small.
-                let editPreflight = undefined;
-                if (intelligence && (!intent || intent === 'explore')) {
-                    try {
-                        const resultPaths = results.map((r) => r.filePath);
-                        const impactCandidates = computeImpactCandidates(resultPaths);
-                        let riskLevel = 'low';
-                        if (impactCandidates.length > 10) {
-                            riskLevel = 'high';
-                        }
-                        else if (impactCandidates.length > 3) {
-                            riskLevel = 'medium';
-                        }
-                        // Use existing pattern intelligence for evidenceLock scoring, but keep the output payload lite.
-                        const preferredPatternsForEvidence = [];
-                        const patterns = intelligence.patterns || {};
-                        for (const [_, data] of Object.entries(patterns)) {
-                            if (data.primary) {
-                                const p = data.primary;
-                                if (p.trend === 'Rising' || p.trend === 'Stable') {
-                                    preferredPatternsForEvidence.push({
-                                        pattern: p.name,
-                                        ...(p.canonicalExample && { example: p.canonicalExample.file })
-                                    });
-                                }
-                            }
-                        }
-                        editPreflight = {
-                            mode: 'lite',
-                            riskLevel,
-                            confidence: computeIndexConfidence(),
-                            evidenceLock: buildEvidenceLock({
-                                results,
-                                preferredPatterns: preferredPatternsForEvidence.slice(0, 5),
-                                relatedMemories,
-                                failureWarnings: [],
-                                patternConflicts: [],
-                                searchQualityStatus: searchQuality.status
-                            })
-                        };
-                    }
-                    catch {
-                        // editPreflight is best-effort - never fail search over it
-                    }
-                }
-                // Compose preflight card for edit/refactor/migrate intents
-                let preflight = undefined;
-                const preflightIntents = ['edit', 'refactor', 'migrate'];
-                if (intent && preflightIntents.includes(intent) && intelligence) {
-                    try {
-                        // --- Avoid / Prefer patterns ---
-                        const avoidPatterns = [];
-                        const preferredPatterns = [];
-                        const patterns = intelligence.patterns || {};
-                        for (const [category, data] of Object.entries(patterns)) {
-                            // Primary pattern = preferred if Rising or Stable
-                            if (data.primary) {
-                                const p = data.primary;
-                                if (p.trend === 'Rising' || p.trend === 'Stable') {
-                                    preferredPatterns.push({
-                                        pattern: p.name,
-                                        category,
-                                        adoption: p.frequency,
-                                        trend: p.trend,
-                                        guidance: p.guidance,
-                                        ...(p.canonicalExample && { example: p.canonicalExample.file })
-                                    });
-                                }
-                            }
-                            // Also-detected patterns that are Declining = avoid
-                            if (data.alsoDetected) {
-                                for (const alt of data.alsoDetected) {
-                                    if (alt.trend === 'Declining') {
-                                        avoidPatterns.push({
-                                            pattern: alt.name,
-                                            category,
-                                            adoption: alt.frequency,
-                                            trend: 'Declining',
-                                            guidance: alt.guidance
-                                        });
-                                    }
-                                }
-                            }
-                        }
-                        // --- Impact candidates (files importing the result files) ---
-                        const resultPaths = results.map((r) => r.filePath);
-                        const impactCandidates = computeImpactCandidates(resultPaths);
-                        // --- Risk level (based on circular deps + impact breadth) ---
-                        let riskLevel = 'low';
-                        let cycleCount = 0;
-                        if (intelligence.internalFileGraph) {
-                            try {
-                                const graph = InternalFileGraph.fromJSON(intelligence.internalFileGraph, ROOT_PATH);
-                                // Use directory prefixes as scope (not full file paths)
-                                // findCycles(scope) filters files by startsWith, so a full path would only match itself
-                                const scopes = new Set(resultPaths.map((rp) => {
-                                    const lastSlash = rp.lastIndexOf('/');
-                                    return lastSlash > 0 ? rp.substring(0, lastSlash + 1) : rp;
-                                }));
-                                for (const scope of scopes) {
-                                    const cycles = graph.findCycles(scope);
-                                    cycleCount += cycles.length;
-                                }
-                            }
-                            catch {
-                                // Graph reconstruction failed — skip cycle check
-                            }
-                        }
-                        if (cycleCount > 0 || impactCandidates.length > 10) {
-                            riskLevel = 'high';
-                        }
-                        else if (impactCandidates.length > 3) {
-                            riskLevel = 'medium';
-                        }
-                        // --- Golden files (exemplar code) ---
-                        const goldenFiles = (intelligence.goldenFiles || []).slice(0, 3).map((g) => ({
-                            file: g.file,
-                            score: g.score
-                        }));
-                        // --- Confidence (index freshness) ---
-                        const confidence = computeIndexConfidence();
-                        // --- Failure memories (1.5x relevance boost) ---
-                        const failureWarnings = relatedMemories
-                            .filter((m) => m.type === 'failure' && !m.stale)
-                            .map((m) => ({
-                            memory: m.memory,
-                            reason: m.reason,
-                            confidence: m.effectiveConfidence
-                        }))
-                            .slice(0, 3);
-                        const preferredPatternsForOutput = preferredPatterns.slice(0, 5);
-                        const avoidPatternsForOutput = avoidPatterns.slice(0, 5);
-                        // --- Pattern conflicts (split decisions within categories) ---
-                        const patternConflicts = [];
-                        const hasUnitTestFramework = Boolean(patterns.unitTestFramework?.primary);
-                        for (const [cat, data] of Object.entries(patterns)) {
-                            if (shouldSkipLegacyTestingFrameworkCategory(cat, patterns))
-                                continue;
-                            if (!shouldIncludePatternConflictCategory(cat, query))
-                                continue;
-                            if (!data.primary || !data.alsoDetected?.length)
-                                continue;
-                            const primaryFreq = parseFloat(data.primary.frequency) || 100;
-                            if (primaryFreq >= 80)
-                                continue;
-                            for (const alt of data.alsoDetected) {
-                                const altFreq = parseFloat(alt.frequency) || 0;
-                                if (altFreq >= 20) {
-                                    if (isComplementaryPatternConflict(cat, data.primary.name, alt.name))
-                                        continue;
-                                    if (hasUnitTestFramework && cat === 'testingFramework')
-                                        continue;
-                                    patternConflicts.push({
-                                        category: cat,
-                                        primary: { name: data.primary.name, adoption: data.primary.frequency },
-                                        alternative: { name: alt.name, adoption: alt.frequency }
-                                    });
-                                }
-                            }
-                        }
-                        const evidenceLock = buildEvidenceLock({
-                            results,
-                            preferredPatterns: preferredPatternsForOutput,
-                            relatedMemories,
-                            failureWarnings,
-                            patternConflicts,
-                            searchQualityStatus: searchQuality.status
-                        });
-                        // Bump risk if there are active failure memories for this area
-                        if (failureWarnings.length > 0 && riskLevel === 'low') {
-                            riskLevel = 'medium';
-                        }
-                        // If evidence triangulation is weak, avoid claiming low risk
-                        if (evidenceLock.status === 'block' && riskLevel === 'low') {
-                            riskLevel = 'medium';
-                        }
-                        // If epistemic stress says abstain, bump risk
-                        if (evidenceLock.epistemicStress?.abstain && riskLevel === 'low') {
-                            riskLevel = 'medium';
-                        }
-                        preflight = {
-                            intent,
-                            riskLevel,
-                            confidence,
-                            evidenceLock,
-                            ...(preferredPatternsForOutput.length > 0 && {
-                                preferredPatterns: preferredPatternsForOutput
-                            }),
-                            ...(avoidPatternsForOutput.length > 0 && {
-                                avoidPatterns: avoidPatternsForOutput
-                            }),
-                            ...(goldenFiles.length > 0 && { goldenFiles }),
-                            ...(impactCandidates.length > 0 && {
-                                impactCandidates: impactCandidates.slice(0, 10)
-                            }),
-                            ...(cycleCount > 0 && { circularDependencies: cycleCount }),
-                            ...(failureWarnings.length > 0 && { failureWarnings })
-                        };
-                    }
-                    catch {
-                        // Preflight construction failed — skip preflight, don't fail the search
-                    }
-                }
-                // For edit/refactor/migrate: return full preflight card (risk, patterns, impact, etc.).
-                // For explore or lite-only: return flattened { ready, reason }.
-                let preflightPayload;
-                if (preflight) {
-                    const el = preflight.evidenceLock;
-                    // Full card per tool schema; add top-level ready/reason for backward compatibility
-                    preflightPayload = {
-                        ...preflight,
-                        ready: el?.readyToEdit ?? false,
-                        ...(el && !el.readyToEdit && el.nextAction && { reason: el.nextAction })
-                    };
-                }
-                else if (editPreflight) {
-                    const el = editPreflight.evidenceLock;
-                    preflightPayload = {
-                        ready: el?.readyToEdit ?? false,
-                        ...(el && !el.readyToEdit && el.nextAction && { reason: el.nextAction })
-                    };
-                }
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                status: 'success',
-                                searchQuality: {
-                                    status: searchQuality.status,
-                                    confidence: searchQuality.confidence,
-                                    ...(searchQuality.status === 'low_confidence' &&
-                                        searchQuality.nextSteps?.[0] && {
-                                        hint: searchQuality.nextSteps[0]
-                                    })
-                                },
-                                ...(preflightPayload && { preflight: preflightPayload }),
-                                results: results.map((r) => {
-                                    const relationships = enrichResult(r);
-                                    // Condensed relationships: importedBy count + hasTests flag
-                                    const condensedRel = relationships
-                                        ? {
-                                            ...(relationships.importedBy &&
-                                                relationships.importedBy.length > 0 && {
-                                                importedByCount: relationships.importedBy.length
-                                            }),
-                                            ...(relationships.testedIn &&
-                                                relationships.testedIn.length > 0 && { hasTests: true })
-                                        }
-                                        : undefined;
-                                    const hasCondensedRel = condensedRel && Object.keys(condensedRel).length > 0;
-                                    return {
-                                        file: `${r.filePath}:${r.startLine}-${r.endLine}`,
-                                        summary: r.summary,
-                                        score: Math.round(r.score * 100) / 100,
-                                        ...(r.componentType && r.layer && { type: `${r.componentType}:${r.layer}` }),
-                                        ...(r.trend && r.trend !== 'Stable' && { trend: r.trend }),
-                                        ...(r.patternWarning && { patternWarning: r.patternWarning }),
-                                        ...(hasCondensedRel && { relationships: condensedRel }),
-                                        ...(includeSnippets && r.snippet && { snippet: r.snippet })
-                                    };
-                                }),
-                                totalResults: results.length,
-                                ...(relatedMemories.length > 0 && {
-                                    relatedMemories: relatedMemories
-                                        .slice(0, 3)
-                                        .map((m) => `${m.memory} (${m.effectiveConfidence})`)
-                                })
-                            }, null, 2)
-                        }
-                    ]
-                };
-            }
-            case 'get_indexing_status': {
-                const progress = indexState.indexer?.getProgress();
+        // Gate INDEX_CONSUMING tools on a valid, healthy index
+        let indexSignal;
+        if (INDEX_CONSUMING_TOOL_NAMES.includes(name)) {
+            if (indexState.status === 'indexing') {
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
-                                status: indexState.status,
-                                rootPath: ROOT_PATH,
-                                lastIndexed: indexState.lastIndexed?.toISOString(),
-                                stats: indexState.stats
-                                    ? {
-                                        totalFiles: indexState.stats.totalFiles,
-                                        indexedFiles: indexState.stats.indexedFiles,
-                                        totalChunks: indexState.stats.totalChunks,
-                                        duration: `${(indexState.stats.duration / 1000).toFixed(2)}s`,
-                                        incremental: indexState.stats.incremental
-                                    }
-                                    : undefined,
-                                progress: progress
-                                    ? {
-                                        phase: progress.phase,
-                                        percentage: progress.percentage,
-                                        filesProcessed: progress.filesProcessed,
-                                        totalFiles: progress.totalFiles
-                                    }
-                                    : undefined,
-                                error: indexState.error,
-                                hint: 'Use refresh_index to manually trigger re-indexing when needed.'
-                            }, null, 2)
+                                status: 'indexing',
+                                message: 'Index build in progress — please retry shortly'
+                            })
                         }
                     ]
                 };
             }
-            case 'refresh_index': {
-                const { reason, incrementalOnly } = args;
-                const mode = incrementalOnly ? 'incremental' : 'full';
-                console.error(`Refresh requested (${mode}): ${reason || 'Manual trigger'}`);
-                performIndexing(incrementalOnly);
+            if (indexState.status === 'error') {
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
-                                status: 'started',
-                                mode,
-                                message: incrementalOnly
-                                    ? 'Incremental re-indexing started. Only changed files will be re-embedded.'
-                                    : 'Full re-indexing started. Check status with get_indexing_status.',
-                                reason
-                            }, null, 2)
+                                status: 'error',
+                                message: `Indexer error: ${indexState.error}`
+                            })
                         }
                     ]
                 };
             }
-            case 'get_codebase_metadata': {
-                const indexer = new CodebaseIndexer({ rootPath: ROOT_PATH });
-                const metadata = await indexer.detectMetadata();
-                // Load team patterns from intelligence file
-                let teamPatterns = {};
-                try {
-                    const intelligencePath = PATHS.intelligence;
-                    const intelligenceContent = await fs.readFile(intelligencePath, 'utf-8');
-                    const intelligence = JSON.parse(intelligenceContent);
-                    if (intelligence.patterns) {
-                        teamPatterns = {
-                            dependencyInjection: intelligence.patterns.dependencyInjection,
-                            stateManagement: intelligence.patterns.stateManagement,
-                            componentInputs: intelligence.patterns.componentInputs
-                        };
-                    }
-                }
-                catch (_error) {
-                    // No intelligence file or parsing error
-                }
+            indexSignal = await ensureValidIndexOrAutoHeal();
+            if (indexSignal.action === 'rebuild-failed') {
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
-                                status: 'success',
-                                metadata: {
-                                    name: metadata.name,
-                                    framework: metadata.framework,
-                                    languages: metadata.languages,
-                                    dependencies: metadata.dependencies.slice(0, 20),
-                                    architecture: metadata.architecture,
-                                    projectStructure: metadata.projectStructure,
-                                    statistics: metadata.statistics,
-                                    teamPatterns
-                                }
-                            }, null, 2)
+                                error: 'Index is corrupt and could not be rebuilt automatically.',
+                                index: indexSignal
+                            })
                         }
-                    ]
+                    ],
+                    isError: true
                 };
             }
-            case 'get_style_guide': {
-                const { query, category } = args;
-                const queryStr = typeof query === 'string' ? query.trim() : '';
-                const queryLower = queryStr.toLowerCase();
-                const queryTerms = queryLower.split(/\s+/).filter(Boolean);
-                const categoryLower = typeof category === 'string' ? category.trim().toLowerCase() : '';
-                const limitedMode = queryTerms.length === 0;
-                const LIMITED_MAX_FILES = 3;
-                const LIMITED_MAX_SECTIONS_PER_FILE = 2;
-                const styleGuidePatterns = [
-                    'STYLE_GUIDE.md',
-                    'CODING_STYLE.md',
-                    'ARCHITECTURE.md',
-                    'CONTRIBUTING.md',
-                    'docs/style-guide.md',
-                    'docs/coding-style.md',
-                    'docs/ARCHITECTURE.md'
-                ];
-                const foundGuides = [];
-                for (const pattern of styleGuidePatterns) {
-                    try {
-                        const files = await glob(pattern, {
-                            cwd: ROOT_PATH,
-                            absolute: true
-                        });
-                        for (const file of files) {
-                            try {
-                                // Normalize line endings to \n for consistent output
-                                const rawContent = await fs.readFile(file, 'utf-8');
-                                const content = rawContent.replace(/\r\n/g, '\n');
-                                const relativePath = path.relative(ROOT_PATH, file);
-                                // Find relevant sections based on query
-                                const sections = content.split(/^##\s+/m);
-                                const relevantSections = [];
-                                if (limitedMode) {
-                                    const headings = (content.match(/^##\s+.+$/gm) || [])
-                                        .map((h) => h.trim())
-                                        .filter(Boolean)
-                                        .slice(0, LIMITED_MAX_SECTIONS_PER_FILE);
-                                    if (headings.length > 0) {
-                                        relevantSections.push(...headings);
-                                    }
-                                    else {
-                                        const words = content.split(/\s+/).filter(Boolean);
-                                        if (words.length > 0) {
-                                            relevantSections.push(`Overview: ${words.slice(0, 80).join(' ')}...`);
-                                        }
-                                    }
-                                }
-                                else {
-                                    for (const section of sections) {
-                                        const sectionLower = section.toLowerCase();
-                                        const isRelevant = queryTerms.some((term) => sectionLower.includes(term));
-                                        if (isRelevant) {
-                                            // Limit section size to ~500 words
-                                            const words = section.split(/\s+/);
-                                            const truncated = words.slice(0, 500).join(' ');
-                                            relevantSections.push('## ' + (words.length > 500 ? truncated + '...' : section.trim()));
-                                        }
-                                    }
-                                }
-                                const categoryMatch = !categoryLower ||
-                                    relativePath.toLowerCase().includes(categoryLower) ||
-                                    relevantSections.some((section) => section.toLowerCase().includes(categoryLower));
-                                if (!categoryMatch) {
-                                    continue;
-                                }
-                                if (relevantSections.length > 0) {
-                                    foundGuides.push({
-                                        file: relativePath,
-                                        content: content.slice(0, 200) + '...',
-                                        relevantSections: relevantSections.slice(0, limitedMode ? LIMITED_MAX_SECTIONS_PER_FILE : 3)
-                                    });
-                                }
-                            }
-                            catch (_e) {
-                                // Skip unreadable files
-                            }
-                        }
-                    }
-                    catch (_e) {
-                        // Pattern didn't match, continue
-                    }
-                }
-                const results = limitedMode ? foundGuides.slice(0, LIMITED_MAX_FILES) : foundGuides;
-                if (results.length === 0) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'no_results',
-                                    message: limitedMode
-                                        ? 'No style guide files found in the default locations.'
-                                        : `No style guide content found matching: ${queryStr}`,
-                                    searchedPatterns: styleGuidePatterns,
-                                    hint: limitedMode
-                                        ? "Run get_style_guide with a query or category (e.g. category: 'testing') for targeted results."
-                                        : "Try broader terms like 'naming', 'patterns', 'testing', 'components'"
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                status: 'success',
-                                query: queryStr || undefined,
-                                category,
-                                limited: limitedMode,
-                                notice: limitedMode
-                                    ? 'No query provided. Results are capped. Provide query and/or category for targeted guidance.'
-                                    : undefined,
-                                resultLimits: limitedMode
-                                    ? {
-                                        maxFiles: LIMITED_MAX_FILES,
-                                        maxSectionsPerFile: LIMITED_MAX_SECTIONS_PER_FILE
-                                    }
-                                    : undefined,
-                                results,
-                                totalFiles: results.length,
-                                totalMatches: foundGuides.length
-                            }, null, 2)
-                        }
-                    ]
+        }
+        const ctx = {
+            indexState,
+            paths: PATHS,
+            rootPath: ROOT_PATH,
+            performIndexing
+        };
+        const result = await dispatchTool(name, args ?? {}, ctx);
+        // Inject IndexSignal into response so callers can inspect index health
+        if (indexSignal !== undefined && result.content?.[0]) {
+            try {
+                const parsed = JSON.parse(result.content[0].text);
+                result.content[0] = {
+                    type: 'text',
+                    text: JSON.stringify({ ...parsed, index: indexSignal })
                 };
             }
-            case 'get_team_patterns': {
-                const { category } = args;
-                try {
-                    const intelligencePath = PATHS.intelligence;
-                    const content = await fs.readFile(intelligencePath, 'utf-8');
-                    const intelligence = JSON.parse(content);
-                    const result = { status: 'success' };
-                    if (category === 'all' || !category) {
-                        result.patterns = intelligence.patterns || {};
-                        result.goldenFiles = intelligence.goldenFiles || [];
-                        if (intelligence.tsconfigPaths) {
-                            result.tsconfigPaths = intelligence.tsconfigPaths;
-                        }
-                    }
-                    else if (category === 'di') {
-                        result.dependencyInjection = intelligence.patterns?.dependencyInjection;
-                    }
-                    else if (category === 'state') {
-                        result.stateManagement = intelligence.patterns?.stateManagement;
-                    }
-                    else if (category === 'testing') {
-                        result.unitTestFramework = intelligence.patterns?.unitTestFramework;
-                        result.e2eFramework = intelligence.patterns?.e2eFramework;
-                        result.testingFramework = intelligence.patterns?.testingFramework;
-                        result.testMocking = intelligence.patterns?.testMocking;
-                    }
-                    else if (category === 'libraries') {
-                        result.topUsed = intelligence.importGraph?.topUsed || [];
-                        if (intelligence.tsconfigPaths) {
-                            result.tsconfigPaths = intelligence.tsconfigPaths;
-                        }
-                    }
-                    // Load and append matching memories
-                    try {
-                        const allMemories = await readMemoriesFile(PATHS.memory);
-                        // Map pattern categories to decision categories
-                        const categoryMap = {
-                            all: ['tooling', 'architecture', 'testing', 'dependencies', 'conventions'],
-                            di: ['architecture', 'conventions'],
-                            state: ['architecture', 'conventions'],
-                            testing: ['testing'],
-                            libraries: ['dependencies']
-                        };
-                        const relevantCategories = categoryMap[category || 'all'] || [];
-                        const matchingMemories = allMemories.filter((m) => relevantCategories.includes(m.category));
-                        if (matchingMemories.length > 0) {
-                            result.memories = matchingMemories;
-                        }
-                    }
-                    catch (_error) {
-                        // No memory file yet, that's fine - don't fail the whole request
-                    }
-                    // Detect pattern conflicts: primary < 80% and any alternative > 20%
-                    const conflicts = [];
-                    const patternsData = intelligence.patterns || {};
-                    const hasUnitTestFramework = Boolean(patternsData.unitTestFramework?.primary);
-                    for (const [cat, data] of Object.entries(patternsData)) {
-                        if (shouldSkipLegacyTestingFrameworkCategory(cat, patternsData))
-                            continue;
-                        if (category && category !== 'all' && cat !== category)
-                            continue;
-                        if (!data.primary || !data.alsoDetected?.length)
-                            continue;
-                        const primaryFreq = parseFloat(data.primary.frequency) || 100;
-                        if (primaryFreq >= 80)
-                            continue;
-                        for (const alt of data.alsoDetected) {
-                            const altFreq = parseFloat(alt.frequency) || 0;
-                            if (altFreq < 20)
-                                continue;
-                            if (isComplementaryPatternConflict(cat, data.primary.name, alt.name))
-                                continue;
-                            if (hasUnitTestFramework && cat === 'testingFramework')
-                                continue;
-                            conflicts.push({
-                                category: cat,
-                                primary: {
-                                    name: data.primary.name,
-                                    adoption: data.primary.frequency,
-                                    trend: data.primary.trend
-                                },
-                                alternative: {
-                                    name: alt.name,
-                                    adoption: alt.frequency,
-                                    trend: alt.trend
-                                },
-                                note: `Split decision: ${data.primary.frequency} ${data.primary.name} (${data.primary.trend || 'unknown'}) vs ${alt.frequency} ${alt.name} (${alt.trend || 'unknown'})`
-                            });
-                        }
-                    }
-                    if (conflicts.length > 0) {
-                        result.conflicts = conflicts;
-                    }
-                    return {
-                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
-                    };
-                }
-                catch (error) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'error',
-                                    message: 'Failed to load team patterns',
-                                    error: error instanceof Error ? error.message : String(error)
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-            }
-            case 'get_component_usage': {
-                const { name: componentName } = args;
-                try {
-                    const intelligencePath = PATHS.intelligence;
-                    const content = await fs.readFile(intelligencePath, 'utf-8');
-                    const intelligence = JSON.parse(content);
-                    const importGraph = intelligence.importGraph || {};
-                    const usages = importGraph.usages || {};
-                    // Find matching usages (exact match or partial match)
-                    let matchedUsage = usages[componentName];
-                    // Try partial match if exact match not found
-                    if (!matchedUsage) {
-                        const matchingKeys = Object.keys(usages).filter((key) => key.includes(componentName) || componentName.includes(key));
-                        if (matchingKeys.length > 0) {
-                            matchedUsage = usages[matchingKeys[0]];
-                        }
-                    }
-                    if (matchedUsage) {
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        status: 'success',
-                                        component: componentName,
-                                        usageCount: matchedUsage.usageCount,
-                                        usedIn: matchedUsage.usedIn
-                                    }, null, 2)
-                                }
-                            ]
-                        };
-                    }
-                    else {
-                        // Show top used as alternatives
-                        const topUsed = importGraph.topUsed || [];
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        status: 'not_found',
-                                        component: componentName,
-                                        message: `No usages found for '${componentName}'.`,
-                                        suggestions: topUsed.slice(0, 10)
-                                    }, null, 2)
-                                }
-                            ]
-                        };
-                    }
-                }
-                catch (error) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'error',
-                                    message: 'Failed to get component usage. Run indexing first.',
-                                    error: error instanceof Error ? error.message : String(error)
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-            }
-            case 'detect_circular_dependencies': {
-                const { scope } = args;
-                try {
-                    const intelligencePath = PATHS.intelligence;
-                    const content = await fs.readFile(intelligencePath, 'utf-8');
-                    const intelligence = JSON.parse(content);
-                    if (!intelligence.internalFileGraph) {
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        status: 'error',
-                                        message: 'Internal file graph not found. Please run refresh_index to rebuild the index with cycle detection support.'
-                                    }, null, 2)
-                                }
-                            ]
-                        };
-                    }
-                    // Reconstruct the graph from stored data
-                    const graph = InternalFileGraph.fromJSON(intelligence.internalFileGraph, ROOT_PATH);
-                    const cycles = graph.findCycles(scope);
-                    const graphStats = intelligence.internalFileGraph.stats || graph.getStats();
-                    if (cycles.length === 0) {
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        status: 'success',
-                                        message: scope
-                                            ? `No circular dependencies detected in scope: ${scope}`
-                                            : 'No circular dependencies detected in the codebase.',
-                                        scope,
-                                        graphStats
-                                    }, null, 2)
-                                }
-                            ]
-                        };
-                    }
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'warning',
-                                    message: `Found ${cycles.length} circular dependency cycle(s).`,
-                                    scope,
-                                    cycles: cycles.map((c) => ({
-                                        files: c.files,
-                                        length: c.length,
-                                        severity: c.length === 2 ? 'high' : c.length <= 3 ? 'medium' : 'low'
-                                    })),
-                                    count: cycles.length,
-                                    graphStats,
-                                    advice: 'Shorter cycles (length 2-3) are typically more problematic. Consider breaking the cycle by extracting shared dependencies.'
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-                catch (error) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'error',
-                                    message: 'Failed to detect circular dependencies. Run indexing first.',
-                                    error: error instanceof Error ? error.message : String(error)
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
+            catch {
+                /* response wasn't JSON, skip injection */
             }
-            case 'remember': {
-                const args_typed = args;
-                const { type = 'decision', category, memory, reason } = args_typed;
-                try {
-                    const crypto = await import('crypto');
-                    const memoryPath = PATHS.memory;
-                    const hashContent = `${type}:${category}:${memory}:${reason}`;
-                    const hash = crypto.createHash('sha256').update(hashContent).digest('hex');
-                    const id = hash.substring(0, 12);
-                    const newMemory = {
-                        id,
-                        type,
-                        category,
-                        memory,
-                        reason,
-                        date: new Date().toISOString()
-                    };
-                    const result = await appendMemoryFile(memoryPath, newMemory);
-                    if (result.status === 'duplicate') {
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        status: 'info',
-                                        message: 'This memory was already recorded.',
-                                        memory: result.memory
-                                    }, null, 2)
-                                }
-                            ]
-                        };
-                    }
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'success',
-                                    message: 'Memory recorded successfully.',
-                                    memory: result.memory
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-                catch (error) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'error',
-                                    message: 'Failed to record memory.',
-                                    error: error instanceof Error ? error.message : String(error)
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-            }
-            case 'get_memory': {
-                const { category, type, query } = args;
-                try {
-                    const memoryPath = PATHS.memory;
-                    const allMemories = await readMemoriesFile(memoryPath);
-                    if (allMemories.length === 0) {
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        status: 'success',
-                                        message: "No team conventions recorded yet. Use 'remember' to build tribal knowledge or memory when the user corrects you over a repeatable pattern.",
-                                        memories: [],
-                                        count: 0
-                                    }, null, 2)
-                                }
-                            ]
-                        };
-                    }
-                    const filtered = filterMemories(allMemories, { category, type, query });
-                    const limited = applyUnfilteredLimit(filtered, { category, type, query }, 20);
-                    // Enrich with confidence decay
-                    const enriched = withConfidence(limited.memories);
-                    const staleCount = enriched.filter((m) => m.stale).length;
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'success',
-                                    count: enriched.length,
-                                    totalCount: limited.totalCount,
-                                    truncated: limited.truncated,
-                                    ...(staleCount > 0 && {
-                                        staleCount,
-                                        staleNote: `${staleCount} memor${staleCount === 1 ? 'y' : 'ies'} below 30% confidence. Consider reviewing or removing.`
-                                    }),
-                                    message: limited.truncated
-                                        ? 'Showing 20 most recent. Use filters (category/type/query) for targeted results.'
-                                        : undefined,
-                                    memories: enriched
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-                catch (error) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    status: 'error',
-                                    message: 'Failed to retrieve memories.',
-                                    error: error instanceof Error ? error.message : String(error)
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-            }
-            default:
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                error: `Unknown tool: ${name}`
-                            }, null, 2)
-                        }
-                    ],
-                    isError: true
-                };
         }
+        return result;
     }
     catch (error) {
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({
-                        error: error instanceof Error ? error.message : String(error),
-                        stack: error instanceof Error ? error.stack : undefined
-                    }, null, 2)
+                    text: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`
                 }
             ],
             isError: true
@@ -1759,6 +600,35 @@ async function main() {
     await server.connect(transport);
     if (process.env.CODEBASE_CONTEXT_DEBUG)
         console.error('[DEBUG] Server ready');
+    // Auto-refresh: watch for file changes and trigger incremental reindex
+    const debounceEnv = Number.parseInt(process.env.CODEBASE_CONTEXT_DEBOUNCE_MS ?? '', 10);
+    const debounceMs = Number.isFinite(debounceEnv) && debounceEnv >= 0 ? debounceEnv : 2000;
+    const stopWatcher = startFileWatcher({
+        rootPath: ROOT_PATH,
+        debounceMs,
+        onChanged: () => {
+            const shouldRunNow = autoRefresh.onFileChange(indexState.status === 'indexing');
+            if (!shouldRunNow) {
+                if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                    console.error('[file-watcher] Index in progress — queueing auto-refresh');
+                }
+                return;
+            }
+            if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                console.error('[file-watcher] Changes detected — incremental reindex starting');
+            }
+            void performIndexing(true);
+        }
+    });
+    process.once('exit', stopWatcher);
+    process.once('SIGINT', () => {
+        stopWatcher();
+        process.exit(0);
+    });
+    process.once('SIGTERM', () => {
+        stopWatcher();
+        process.exit(0);
+    });
 }
 // Export server components for programmatic use
 export { server, performIndexing, resolveRootPath, shouldReindex, TOOLS };
@@ -1766,10 +636,21 @@ export { server, performIndexing, resolveRootPath, shouldReindex, TOOLS };
 // Check if this module is the entry point
 const isDirectRun = process.argv[1]?.replace(/\\/g, '/').endsWith('index.js') ||
     process.argv[1]?.replace(/\\/g, '/').endsWith('index.ts');
+const CLI_SUBCOMMANDS = [
+    'memory',
+    'search',
+    'metadata',
+    'status',
+    'reindex',
+    'style-guide',
+    'patterns',
+    'refs',
+    'cycles'
+];
 if (isDirectRun) {
-    // CLI subcommand: memory list/add/remove
-    if (process.argv[2] === 'memory') {
-        handleMemoryCli(process.argv.slice(3)).catch((error) => {
+    const subcommand = process.argv[2];
+    if (CLI_SUBCOMMANDS.includes(subcommand) || subcommand === '--help') {
+        handleCliCommand(process.argv.slice(2)).catch((error) => {
             console.error('Error:', error instanceof Error ? error.message : String(error));
             process.exit(1);
         });