ai-mind-map 1.6.1 → 1.7.0

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * AI Mind Map — MCP Server Entry Point
+ * AI Mind Map — MCP Server Entry Point
  *
  * Creates the MCP server with stdio transport, registers all tools,
  * initialises ALL real subsystems (knowledge graph, change tracker,
@@ -16,27 +16,27 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import Database from 'better-sqlite3';
 import { loadConfig, parseCliArgs } from './config.js';
-// ── Knowledge Graph ───────────────────────────────────────────
+// ── Knowledge Graph ───────────────────────────────────────────
 import { KnowledgeGraph } from './knowledge-graph/graph.js';
 // Note: parser.ts exports functions (parseFile, parseFiles, etc.), not a class
 import { Indexer } from './knowledge-graph/indexer.js';
 import { PageRankEngine } from './knowledge-graph/pagerank.js';
-// ── Change Tracker ────────────────────────────────────────────
+// ── Change Tracker ────────────────────────────────────────────
 import { FileWatcher } from './change-tracker/watcher.js';
 import { DiffEngine } from './change-tracker/diff-engine.js';
 import { ChangeLog } from './change-tracker/change-log.js';
-// ── Memory ────────────────────────────────────────────────────
+// ── Memory ────────────────────────────────────────────────────
 import { SessionMemory } from './memory/session-memory.js';
 import { PersistentMemory } from './memory/persistent-memory.js';
 import { DecisionLog } from './memory/decision-log.js';
 import { syncSharedContext } from './memory/shared-sync.js';
-// ── Context Engine ────────────────────────────────────────────
+// ── Context Engine ────────────────────────────────────────────
 // compressor.ts exports functions: compress, detectContentType
 import { compress as compressContent } from './context/compressor.js';
 // progressive-disclosure.ts exports function: buildContextPackage
 import { buildContextPackage } from './context/progressive-disclosure.js';
 import { estimateTokens } from './utils/token-counter.js';
-// ── Tools ─────────────────────────────────────────────────────
+// ── Tools ─────────────────────────────────────────────────────
 import { registerGraphTools } from './tools/graph-tools.js';
 import { registerChangeTools } from './tools/change-tools.js';
 import { registerMemoryTools } from './tools/memory-tools.js';
@@ -53,7 +53,7 @@ import { ChangelogEngine } from './knowledge-graph/changelog.js';
 import { registerSessionTools } from './tools/session-tools.js';
 import { registerDigestTools } from './tools/digest-tools.js';
 // ============================================================
-// Logger — writes to stderr so MCP stdio is uncontaminated
+// Logger — writes to stderr so MCP stdio is uncontaminated
 // ============================================================
 const LOG_LEVELS = {
     debug: 0,
@@ -78,18 +78,18 @@ function log(level, message, ...extra) {
     }
 }
 // ============================================================
-// Adapters — Bridge real implementations to tool interfaces
+// Adapters — Bridge real implementations to tool interfaces
 // ============================================================
 /**
  * Creates an adapter that satisfies IKnowledgeGraph from the real
  * KnowledgeGraph and PageRankEngine classes.
  *
  * Key API mappings:
- * - graph.search(query, limit) — FTS5 search, no type filter param
- * - graph.getProjectOverview() — returns Map<string, GraphNode[]>, no args
- * - graph.findCallers(nodeId) / graph.findCallees(nodeId) — single nodeId arg
- * - graph.getNodesByName(name) — returns GraphNode[]
- * - graph.getFileStructure(filePath) — returns GraphNode[]
+ * - graph.search(query, limit) — FTS5 search, no type filter param
+ * - graph.getProjectOverview() — returns Map<string, GraphNode[]>, no args
+ * - graph.findCallers(nodeId) / graph.findCallees(nodeId) — single nodeId arg
+ * - graph.getNodesByName(name) — returns GraphNode[]
+ * - graph.getFileStructure(filePath) — returns GraphNode[]
  */
 function createGraphAdapter(graph, pagerank) {
     return {
@@ -248,10 +248,10 @@ function createGraphAdapter(graph, pagerank) {
  * DiffEngine and ChangeLog classes.
  *
  * Key API mappings:
- * - changeLog.getLatestSession() — returns ChangeSession | null
- * - changeLog.queryChanges(options) — options has `since` (timestamp), not `afterTimestamp`
- * - changeLog.generateSessionSummary(sessionId) — returns string
- * - changeLog.recordChange(change) — records a FileChange
+ * - changeLog.getLatestSession() — returns ChangeSession | null
+ * - changeLog.queryChanges(options) — options has `since` (timestamp), not `afterTimestamp`
+ * - changeLog.generateSessionSummary(sessionId) — returns string
+ * - changeLog.recordChange(change) — records a FileChange
  */
 function createChangeAdapter(diffEngine, changeLog, graph) {
     return {
@@ -383,13 +383,13 @@ function createChangeAdapter(diffEngine, changeLog, graph) {
  * DecisionLog, and SessionMemory.
  *
  * Key API mappings:
- * - persistentMemory.queryMemories(query) — query uses MemoryQuery shape
- * - persistentMemory.createMemory(input) — input is CreateMemoryInput
- * - persistentMemory.getStats() — returns MemoryStats
- * - decisionLog.queryDecisions(query) — query uses DecisionQuery
- * - decisionLog.createDecision(input) — returns { decision, conflicts }
- * - decisionLog.getActiveDecisions() — returns Decision[]
- * - sessionMemory.listRecentSessions(limit) — returns SessionListItem[]
+ * - persistentMemory.queryMemories(query) — query uses MemoryQuery shape
+ * - persistentMemory.createMemory(input) — input is CreateMemoryInput
+ * - persistentMemory.getStats() — returns MemoryStats
+ * - decisionLog.queryDecisions(query) — query uses DecisionQuery
+ * - decisionLog.createDecision(input) — returns { decision, conflicts }
+ * - decisionLog.getActiveDecisions() — returns Decision[]
+ * - sessionMemory.listRecentSessions(limit) — returns SessionListItem[]
  */
 function createMemoryAdapter(persistentMemory, decisionLog, sessionMemory) {
     return {
@@ -423,7 +423,7 @@ function createMemoryAdapter(persistentMemory, decisionLog, sessionMemory) {
             if (!params.status || params.status === 'active') {
                 return decisionLog.getActiveDecisions();
             }
-            // 'all' — query with no filters
+            // 'all' — query with no filters
             return decisionLog.queryDecisions({});
         },
         decide: (params) => {
@@ -492,8 +492,8 @@ function createSessionAdapter(sessionMemory) {
  * Creates an adapter that satisfies IContextEngine.
  *
  * Key API mappings:
- * - compress(text, level, contentType) — module-level function from compressor.ts
- * - buildContextPackage(...) — module-level function from progressive-disclosure.ts
+ * - compress(text, level, contentType) — module-level function from compressor.ts
+ * - buildContextPackage(...) — module-level function from progressive-disclosure.ts
  */
 function createContextAdapter(graph, persistentMemory, decisionLog, changeLog, config) {
     return {
@@ -534,7 +534,7 @@ function createContextAdapter(graph, persistentMemory, decisionLog, changeLog, c
                     tier2Data.graphNodes = graphNodes;
                 }
                 // Build context package
-                const pkg = buildContextPackage(projectInfo, tier2Data, {}, // Tier 3 data — empty for initial load
+                const pkg = buildContextPackage(projectInfo, tier2Data, {}, // Tier 3 data — empty for initial load
                 config.tokenBudgets, params.taskDescription);
                 return pkg;
             }
@@ -568,12 +568,12 @@ function createContextAdapter(graph, persistentMemory, decisionLog, changeLog, c
  * Creates an adapter that satisfies IIndexer.
  *
  * Key API mappings:
- * - indexer.fullIndex(onProgress?) — returns Promise<IndexStats>
+ * - indexer.fullIndex(onProgress?) — returns Promise<IndexStats>
  *   IndexStats has: filesScanned, filesParsed, filesSkipped, filesDeleted,
  *                   nodesCreated, edgesCreated, parseErrors, durationMs, languages
- * - graph.getStats() — returns { totalNodes, totalEdges, totalFiles, nodesByType, edgesByType, languageBreakdown }
- * - persistentMemory.getStats() — returns MemoryStats
- * - changeLog.getStats(topN?) — returns ChangeLogStats
+ * - graph.getStats() — returns { totalNodes, totalEdges, totalFiles, nodesByType, edgesByType, languageBreakdown }
+ * - persistentMemory.getStats() — returns MemoryStats
+ * - changeLog.getStats(topN?) — returns ChangeLogStats
  */
 function createIndexerAdapter(indexer, graph, persistentMemory, decisionLog, changeLog, config, watcher) {
     return {
@@ -609,13 +609,13 @@ function createIndexerAdapter(indexer, graph, persistentMemory, decisionLog, cha
             try {
                 // Re-target the indexer to the new project
                 indexer.setProjectRoot(resolvedPath);
-                log('info', `📁 Re-targeted to project: ${resolvedPath}`);
+                log('info', `📁 Re-targeted to project: ${resolvedPath}`);
                 // Also watch the new project directory for changes
                 if (watcher) {
                     watcher.addRoot(resolvedPath);
-                    log('info', `👁️ File watcher now also watching: ${resolvedPath}`);
+                    log('info', `👁️ File watcher now also watching: ${resolvedPath}`);
                 }
-                // Run full index on the new project (don't clear — multi-project)
+                // Run full index on the new project (don't clear — multi-project)
                 const result = await indexer.fullIndex();
                 return {
                     filesScanned: result.filesScanned,
@@ -715,6 +715,20 @@ class SessionTokenTracker {
         };
     }
 }
+/**
+ * Directories that should NEVER be indexed — IDE install dirs, tool dirs, etc.
+ */
+const BLOCKED_DIRECTORY_PATTERNS = [
+    'antigravity', '.gemini', '.cursor', '.vscode-server',
+    'program files', 'programdata', 'appdata',
+    'node_modules', '.npm', '.yarn',
+    'system32', 'windows',
+];
+/** Check if a path is a known IDE/tool directory that should never be indexed */
+function isBlockedDirectory(dirPath) {
+    const lower = dirPath.toLowerCase().replace(/\\/g, '/');
+    return BLOCKED_DIRECTORY_PATTERNS.some(pattern => lower.includes(pattern));
+}
 /**
  * Intercept an MCP tool response to inject session token metadata.
  *
@@ -732,23 +746,20 @@ function enrichToolResponse(response, tracker, estimator, graphNodeCount, getPro
         const tokensSaved = result.tokensSaved ?? 0;
         // Record in tracker
         tracker.record(0, outputTokens, tokensSaved);
-        // Always add session token metadata
-        result._sessionTokens = tracker.getSummary();
         // Always add project metadata
-        result._project = getProjectInfo();
-        // If result is empty/failed AND graph has no nodes, add auto-index hint
+        const projectInfo = getProjectInfo();
+        result._project = projectInfo;
+        // ALWAYS tell the agent to provide project path if no real project is indexed
         const nodeCount = graphNodeCount();
-        if (nodeCount === 0) {
-            const isEmpty = result.success === true && (result.data === null ||
-                (Array.isArray(result.data) && result.data.length === 0) ||
-                (typeof result.data === 'object' && result.data !== null && Object.keys(result.data).length === 0));
-            const isFail = result.success === false;
-            if (isEmpty || isFail) {
-                result._hint = '⚠️ No codebase index found. Call mindmap_reindex with the projectPath parameter ' +
-                    'set to the root directory of the user\'s project (e.g. "E:\\\\myproject"). ' +
-                    'This is a one-time operation that takes ~10-30 seconds.';
-            }
+        const rootIsBlocked = isBlockedDirectory(projectInfo.root);
+        if (nodeCount === 0 || rootIsBlocked) {
+            result._indexRequired = true;
+            result._action = 'REQUIRED: Call mindmap_reindex({ projectPath: "<USER_WORKSPACE_PATH>" }). ' +
+                'The current root "' + projectInfo.root + '" is NOT a user project. ' +
+                'Use the workspace/project directory that the user has open in their editor.';
         }
+        // Always add session token metadata
+        result._sessionTokens = tracker.getSummary();
         response.content[0].text = JSON.stringify(result);
     }
     catch {
@@ -760,7 +771,7 @@ function enrichToolResponse(response, tracker, estimator, graphNodeCount, getPro
 // Main entry point
 // ============================================================
 async function main() {
-    // ── 1. Parse CLI & load config ──────────────────────────────
+    // ── 1. Parse CLI & load config ──────────────────────────────
     let cliArgs;
     try {
         cliArgs = parseCliArgs();
@@ -771,7 +782,7 @@ async function main() {
         process.exit(1);
     }
     setLogLevel(cliArgs.logLevel);
-    log('info', '🧠 AI Mind Map MCP Server starting…');
+    log('info', '🧠 AI Mind Map MCP Server starting…');
     let config;
     try {
         config = await loadConfig(cliArgs);
@@ -784,7 +795,7 @@ async function main() {
         log('error', `Failed to load configuration: ${msg}`);
         process.exit(1);
     }
-    // ── 2. Initialise database directory ────────────────────────
+    // ── 2. Initialise database directory ────────────────────────
     try {
         ensureDbDirectory(config.dbPath);
     }
@@ -793,11 +804,11 @@ async function main() {
         log('error', `Failed to create DB directory: ${msg}`);
         process.exit(1);
     }
-    // ── 3. Initialise SQLite database ──────────────────────────
+    // ── 3. Initialise SQLite database ──────────────────────────
     // KnowledgeGraph manages its own db connection, but ChangeLog,
     // SessionMemory, PersistentMemory, and DecisionLog each need
     // a shared Database instance for their tables.
-    log('info', 'Initialising database…');
+    log('info', 'Initialising database…');
     let sharedDb;
     try {
         sharedDb = new Database(config.dbPath);
@@ -811,24 +822,24 @@ async function main() {
         log('error', `Failed to initialize database: ${msg}`);
         process.exit(1);
     }
-    // ── 4. Initialise real subsystems ──────────────────────────
-    log('info', 'Initialising subsystems…');
-    // Knowledge Graph — constructor takes dbPath string
+    // ── 4. Initialise real subsystems ──────────────────────────
+    log('info', 'Initialising subsystems…');
+    // Knowledge Graph — constructor takes dbPath string
     const graph = new KnowledgeGraph(config.dbPath);
-    // Indexer — constructor is Indexer(graph, config)
+    // Indexer — constructor is Indexer(graph, config)
     const indexer = new Indexer(graph, config);
-    // PageRankEngine — constructor is PageRankEngine(graph, config?)
+    // PageRankEngine — constructor is PageRankEngine(graph, config?)
     const pagerank = new PageRankEngine(graph);
-    // Changelog Engine — node-level change tracking (v1.4.0)
+    // Changelog Engine — node-level change tracking (v1.4.0)
     const changelogEngine = new ChangelogEngine(graph.getDb());
     indexer.setChangelog(changelogEngine);
-    log('info', '✅ Knowledge Graph initialized (with changelog engine)');
+    log('info', '✅ Knowledge Graph initialized (with changelog engine)');
     // Change Tracker
     // ChangeLog constructor takes ChangeLogConfig: { dbPath, retentionDays?, defaultSearchLimit? }
     const changeLog = new ChangeLog({ dbPath: config.dbPath });
     const diffEngine = new DiffEngine(config.projectRoot);
     let watcher = null;
-    // SessionMemory — must be created before watcher so it's available in the handler
+    // SessionMemory — must be created before watcher so it's available in the handler
     // SessionMemory constructor takes Database.Database instance
     const sessionMemory = new SessionMemory(sharedDb);
     const sessionId = sessionMemory.startSession();
@@ -841,6 +852,8 @@ async function main() {
             watchDebounceMs: config.watchDebounceMs,
             maxFileSize: config.maxFileSize,
         });
+        // Wire watcher to indexer so fullIndex() can pause/resume it
+        indexer.setWatcher(watcher);
         // FileWatcher emits 'changes' with WatcherEvent[]
         watcher.on('changes', async (events) => {
             log('debug', `File watcher detected ${events.length} changes`);
@@ -872,7 +885,7 @@ async function main() {
             pagerank.invalidateCache();
         });
     }
-    log('info', `✅ Change Tracker initialized (watcher: ${config.watchEnabled ? 'enabled' : 'disabled'})`);
+    log('info', `✅ Change Tracker initialized (watcher: ${config.watchEnabled ? 'enabled' : 'disabled'})`);
     // Memory
     // PersistentMemory constructor: (db, config?) where config is Pick<MindMapConfig['memory'], 'decayRate' | 'maxMemories' | 'importanceThreshold'>
     const persistentMemory = new PersistentMemory(sharedDb, {
@@ -884,7 +897,7 @@ async function main() {
     const decisionLog = new DecisionLog(sharedDb, {
         maxDecisions: config.memory.maxDecisions,
     });
-    log('info', `✅ Memory initialized (session: ${sessionMemory.getCurrentSessionId()})`);
+    log('info', `✅ Memory initialized (session: ${sessionMemory.getCurrentSessionId()})`);
     // Apply memory decay on startup
     try {
         const decayed = persistentMemory.applyDecay();
@@ -893,9 +906,9 @@ async function main() {
     catch (err) {
         log('warn', 'Failed to apply memory decay at startup', err);
     }
-    // Context Engine — no class instances needed; uses module-level functions
-    log('info', '✅ Context Engine initialized');
-    // ── 5. Build adapters ──────────────────────────────────────
+    // Context Engine — no class instances needed; uses module-level functions
+    log('info', '✅ Context Engine initialized');
+    // ── 5. Build adapters ──────────────────────────────────────
     const graphAdapter = createGraphAdapter(graph, pagerank);
     const changeAdapter = createChangeAdapter(diffEngine, changeLog, graph);
     const memoryAdapter = createMemoryAdapter(persistentMemory, decisionLog, sessionMemory);
@@ -906,25 +919,38 @@ async function main() {
     const tokenEstimator = {
         estimate: (text) => estimateTokens(text),
     };
-    // ── 6. Create MCP server ──────────────────────────────────
+    // ── 6. Create MCP server ──────────────────────────────────
     const server = new McpServer({
         name: 'ai-mind-map',
-        version: '1.6.1',
+        version: '1.7.0',
     }, {
         instructions: [
             '# AI Mind Map — Code Memory Engine',
             '',
-            'You have access to AI Mind Map, a persistent code memory system that saves you from re-reading files and losing context between sessions.',
+            '## ⚠ CRITICAL: FIRST STEP IN EVERY CONVERSATION',
+            'Before calling ANY other tool, you MUST ensure a project is indexed:',
+            '1. Check if `_indexRequired: true` appears in any response — if so, the index is empty or pointing at an IDE directory.',
+            '2. Call `mindmap_reindex({ projectPath: "<WORKSPACE>" })` where <WORKSPACE> is the user project directory from their open editor.',
+            '3. NEVER use paths containing: .gemini, antigravity, .cursor, .vscode, AppData, Program Files — these are IDE directories, NOT projects.',
+            '4. Example: `mindmap_reindex({ projectPath: "E:\\myproject" })`',
             '',
-            '## 🚀 FIRST CALL (every new conversation):',
-            'Call `mindmap_session_resume` FIRST. It returns:',
+            '## After Indexing - Resume Session:',
+            'Call `mindmap_session_resume`. It returns:',
             '- What the previous AI worked on',
             '- What code changed since then (function-level diffs)',
             '- Project structure + tech stack',
             '- Hot files (most frequently changed)',
-            'This ONE call replaces reading 10+ files.',
             '',
-            '## 📋 Tool Selection Guide:',
+            '## Project Indexing:',
+            'Every response includes `_project.root` and `_project.totalNodes`.',
+            'If `_indexRequired: true` appears, you MUST call `mindmap_reindex` with the correct project path.',
+            'NEVER index directories containing: antigravity, .gemini, .cursor, .vscode, AppData, Program Files.',
+            'The graph supports multiple projects — call `mindmap_reindex` with different paths to switch.',
+            '',
+            '## Token Tracking:',
+            'Every response includes `_sessionTokens` with cumulative usage.',
+            '',
+            '##  Tool Selection Guide:',
             '',
             '### When you need to UNDERSTAND the project:',
             '- `mindmap_digest` → Full project summary in <2000 tokens',
@@ -938,48 +964,47 @@ async function main() {
             '- `mindmap_trace_dependencies` → Who calls X? What does X call?',
             '',
             '### When you need to READ code:',
-            '- `mindmap_explain` → Get EVERYTHING about a symbol: signature, callers, callees, doc',
-            '- `mindmap_get_code_snippet` → Read actual source code for a function/class',
-            '- `mindmap_get_file_map` → All symbols in a file with signatures + line ranges',
+            '- `mindmap_get_code_snippet` → Read actual source code for a function/class',
+            '- `mindmap_get_file_map` → All symbols in a file with signatures + line ranges',
             '',
             '### When you need to know WHAT CHANGED:',
-            '- `mindmap_changelog` → Symbol-level diffs (added/modified/deleted functions)',
-            '- `mindmap_git_changes` → Git-aware changes with symbol mapping',
-            '- `mindmap_verify` → Check if your cached knowledge is still valid',
-            '- `mindmap_hotspots` → Most frequently changed files + symbols',
+            '- `mindmap_changelog` → Symbol-level diffs (added/modified/deleted functions)',
+            '- `mindmap_git_changes` → Git-aware changes with symbol mapping',
+            '- `mindmap_verify` → Check if your cached knowledge is still valid',
+            '- `mindmap_hotspots` → Most frequently changed files + symbols',
             '',
             '### When you need to REMEMBER:',
-            '- `mindmap_remember` → Save a fact/convention for future sessions',
-            '- `mindmap_recall` → Retrieve relevant memories for current task',
-            '- `mindmap_decide` → Record architectural decisions with rationale',
+            '- `mindmap_remember` → Save a fact/convention for future sessions',
+            '- `mindmap_recall` → Retrieve relevant memories for current task',
+            '- `mindmap_decide` → Record architectural decisions with rationale',
             '',
             '### When you finish work:',
-            '- `mindmap_session_end` → Save summary so next AI can resume instantly',
+            '- `mindmap_session_end` → Save summary so next AI can resume instantly',
             '',
             '### After editing code:',
-            '- `mindmap_verify_changes` → Verify your edits at the symbol level WITHOUT re-reading files',
+            '- `mindmap_verify_changes` → Verify your edits at the symbol level WITHOUT re-reading files',
             '',
-            '## ⚡ Token-Saving Rules:',
-            '1. ALWAYS call `mindmap_session_resume` first — never start blind',
-            '2. Use `mindmap_file_digest` BEFORE reading a full file — you may not need the full file',
-            '3. Use `mindmap_verify_changes` after editing to verify changes — do NOT re-read whole files',
+            '## âš¡ Token-Saving Rules:',
+            '1. ALWAYS call `mindmap_session_resume` first — never start blind',
+            '2. Use `mindmap_file_digest` BEFORE reading a full file — you may not need the full file',
+            '3. Use `mindmap_verify_changes` after editing to verify changes — do NOT re-read whole files',
             '4. Use `mindmap_changelog` instead of re-reading files to see what changed',
-            '5. Call `mindmap_session_end` when done — save context for next session',
+            '5. Call `mindmap_session_end` when done — save context for next session',
             '',
-            '## 🔄 Project Indexing:',
+            '## 🔄 Project Indexing:',
             'Every response includes `_project.root` showing which directory is currently indexed.',
             'If `_project.totalNodes` is 0, you MUST call `mindmap_reindex` with `projectPath` set to',
             'the user\'s project directory (e.g. their workspace root). This creates the knowledge graph.',
             'Example: `mindmap_reindex({ projectPath: "/home/user/my-project" })`',
-            'You can also reindex to switch between projects — the graph supports multiple projects.',
+            'You can also reindex to switch between projects — the graph supports multiple projects.',
             '',
-            '## 📊 Token Tracking:',
+            '## 📊 Token Tracking:',
             'Every response includes `_sessionTokens` with cumulative usage.',
         ].join('\n'),
     });
-    // ── 7. Register all tools ─────────────────────────────────
-    log('info', 'Registering MCP tools…');
-    // ── 7.0 Token tracking middleware ──────────────────────────
+    // ── 7. Register all tools ─────────────────────────────────
+    log('info', 'Registering MCP tools…');
+    // ── 7.0 Token tracking middleware ──────────────────────────
     // Wrap every tool handler to inject session token metadata
     const tokenTracker = new SessionTokenTracker();
     const originalToolFn = server.tool.bind(server);
@@ -1036,7 +1061,7 @@ async function main() {
     log('debug', 'Registered session tools (5)');
     registerDigestTools(server, graph, changelogEngine, config, tokenEstimator);
     log('debug', 'Registered digest tools (3)');
-    // ── mindmap_sync_shared_context ─────────────────────────────
+    // ── mindmap_sync_shared_context ─────────────────────────────
     server.tool('mindmap_sync_shared_context', 'Synchronise local memories, decisions, and learned rules with the team-shared `.mindmap-shared.json` file. ' +
         'Performs a bidirectional sync to import new conventions/decisions and export local updates.', {}, async () => {
         try {
@@ -1070,21 +1095,21 @@ async function main() {
         }
     });
     log('debug', 'Registered shared context sync tool');
-    log('info', '🔧 All MCP tools registered:');
+    log('info', '🔧 All MCP tools registered:');
     log('info', '  Graph:    mindmap_search, mindmap_get_structure, mindmap_trace_dependencies, mindmap_get_signature, mindmap_find_references, mindmap_get_file_map');
     log('info', '  Changes:  mindmap_what_changed, mindmap_session_diff, mindmap_impact_analysis');
     log('info', '  Memory:   mindmap_recall, mindmap_remember, mindmap_get_decisions, mindmap_decide, mindmap_session_summary, mindmap_sync_shared_context');
     log('info', '  Context:  mindmap_get_context, mindmap_compress, mindmap_reindex, mindmap_status');
     log('info', '  Debug:    mindmap_debug_changes, mindmap_file_before, mindmap_file_history');
     log('info', '  Flow:     mindmap_trace_flow, mindmap_interaction_map, mindmap_classify_file, mindmap_layer_overview');
-    log('info', '  Snapshot: mindmap_project_map, mindmap_change_delta, mindmap_session_kickoff ⭐');
+    log('info', '  Snapshot: mindmap_project_map, mindmap_change_delta, mindmap_session_kickoff ⭐');
     log('info', '  Advanced: mindmap_query_graph, mindmap_dead_code, mindmap_architecture, mindmap_get_code_snippet, mindmap_search_code, mindmap_list_projects, mindmap_health');
-    log('info', '  Smart:    mindmap_explain ⭐, mindmap_git_changes ⭐, mindmap_smart_search ⭐');
-    log('info', '  Evolving: mindmap_teach ⭐, mindmap_get_learned, mindmap_forget');
-    log('info', '  Semantic: mindmap_semantic_search ⭐, mindmap_semantic_stats, mindmap_synonyms');
-    log('info', '  Session:  mindmap_session_start 🆕, mindmap_session_resume 🔥🆕, mindmap_session_end, mindmap_changelog 🆕, mindmap_hotspots, mindmap_verify_changes 🆕');
-    log('info', '  Digest:   mindmap_digest ⭐, mindmap_file_digest ⭐, mindmap_verify');
-    // ── 7.3 Register MCP Prompts ──────────────────────────────
+    log('info', '  Smart:    mindmap_explain ⭐, mindmap_git_changes ⭐, mindmap_smart_search ⭐');
+    log('info', '  Evolving: mindmap_teach ⭐, mindmap_get_learned, mindmap_forget');
+    log('info', '  Semantic: mindmap_semantic_search ⭐, mindmap_semantic_stats, mindmap_synonyms');
+    log('info', '  Session:  mindmap_session_start 🆕, mindmap_session_resume 🔥🆕, mindmap_session_end, mindmap_changelog 🆕, mindmap_hotspots, mindmap_verify_changes 🆕');
+    log('info', '  Digest:   mindmap_digest ⭐, mindmap_file_digest ⭐, mindmap_verify');
+    // ── 7.3 Register MCP Prompts ──────────────────────────────
     // These are interactive workflow templates that AI agents can request
     server.prompt('start_session', 'Recommended first prompt for any AI coding session. Calls mindmap_session_resume and returns a complete project briefing.', async () => {
         // Auto-start session
@@ -1127,32 +1152,32 @@ async function main() {
                 }],
         };
     });
-    server.prompt('tool_guide', 'Complete guide to all AI Mind Map tools — when to use each one, organized by task.', async () => ({
+    server.prompt('tool_guide', 'Complete guide to all AI Mind Map tools — when to use each one, organized by task.', async () => ({
         messages: [{
                 role: 'user',
                 content: {
                     type: 'text',
                     text: [
-                        '# AI Mind Map — Complete Tool Guide',
+                        '# AI Mind Map — Complete Tool Guide',
                         '',
-                        '## 🚀 Session Lifecycle (use these to avoid re-reading code)',
+                        '## 🚀 Session Lifecycle (use these to avoid re-reading code)',
                         '| Tool | When to Use |',
                         '|------|------------|',
-                        '| `mindmap_session_resume` | **FIRST call every conversation** — returns project context + changes |',
+                        '| `mindmap_session_resume` | **FIRST call every conversation** — returns project context + changes |',
                         '| `mindmap_session_kickoff` | Full preamble: project map + change delta + memories in ONE call |',
                         '| `mindmap_session_start` | Start tracking a new task (records agent name + task) |',
                         '| `mindmap_session_end` | Save summary for next AI session |',
                         '',
-                        '## 🔍 Finding Code (instead of grep/reading files)',
+                        '## 🔍 Finding Code (instead of grep/reading files)',
                         '| Tool | When to Use |',
                         '|------|------------|',
-                        '| `mindmap_smart_search` | Search by function/class name — returns full context |',
+                        '| `mindmap_smart_search` | Search by function/class name — returns full context |',
                         '| `mindmap_semantic_search` | Search by concept ("error handling", "auth") |',
                         '| `mindmap_search_code` | Grep-like text search in code bodies |',
                         '| `mindmap_find_references` | Find all usages of a symbol |',
                         '| `mindmap_trace_dependencies` | Who calls X? What does X call? |',
                         '',
-                        '## 📖 Reading Code (without reading full files)',
+                        '## 📖 Reading Code (without reading full files)',
                         '| Tool | When to Use |',
                         '|------|------------|',
                         '| `mindmap_explain` | Get EVERYTHING about a symbol in one call |',
@@ -1161,14 +1186,14 @@ async function main() {
                         '| `mindmap_get_file_map` | All symbols in a file with signatures |',
                         '| `mindmap_get_signature` | Just the signature (cheapest read) |',
                         '',
-                        '## 📊 Understanding the Project',
+                        '## 📊 Understanding the Project',
                         '| Tool | When to Use |',
                         '|------|------------|',
                         '| `mindmap_digest` | Full project summary in <2000 tokens |',
                         '| `mindmap_architecture` | Architecture layers + patterns |',
                         '| `mindmap_project_map` | Complete project map |',
                         '',
-                        '## 🔄 Change Tracking',
+                        '## 🔄 Change Tracking',
                         '| Tool | When to Use |',
                         '|------|------------|',
                         '| `mindmap_changelog` | Symbol-level diffs since a time |',
@@ -1176,7 +1201,7 @@ async function main() {
                         '| `mindmap_verify` | Check if cached code is still valid |',
                         '| `mindmap_hotspots` | Most frequently changed files |',
                         '',
-                        '## 🧠 Memory & Decisions',
+                        '## 🧠 Memory & Decisions',
                         '| Tool | When to Use |',
                         '|------|------------|',
                         '| `mindmap_remember` | Save important facts for future |',
@@ -1188,22 +1213,22 @@ async function main() {
             }],
     }));
     log('debug', 'Registered 2 MCP prompts (start_session, tool_guide)');
-    // ── 7.5 Auto-sync shared context on startup ────────────────
+    // ── 7.5 Auto-sync shared context on startup ────────────────
     if (config.autoSyncSharedContext) {
-        log('info', '🔄 Auto-syncing shared context…');
+        log('info', '🔄 Auto-syncing shared context…');
         try {
             const syncStats = await syncSharedContext(config, graph, persistentMemory, decisionLog);
-            log('info', `✅ Shared context sync complete: ` +
+            log('info', `✅ Shared context sync complete: ` +
                 `Imported: ${syncStats.memoriesImported} memories, ${syncStats.decisionsImported} decisions, ${syncStats.rulesImported} rules. ` +
                 `Exported: ${syncStats.memoriesExported} memories, ${syncStats.decisionsExported} decisions, ${syncStats.rulesExported} rules.`);
         }
         catch (err) {
-            log('warn', `⚠️ Auto-sync of shared context failed: ${err instanceof Error ? err.message : String(err)}`);
+            log('warn', `⚠️ Auto-sync of shared context failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // ── 8. Smart auto-index (only if projectRoot looks like a real project) ──
+    // ── 8. Smart auto-index (only if projectRoot looks like a real project) ──
     if (config.memoryOnly) {
-        log('info', '🧠 Running in memoryOnly mode. Bypassing codebase parsing and indexing.');
+        log('info', '🧠 Running in memoryOnly mode. Bypassing codebase parsing and indexing.');
     }
     else {
         // Check if projectRoot is a real project (not an IDE install directory)
@@ -1214,33 +1239,33 @@ async function main() {
             'pubspec.yaml', 'Gemfile', '*.sln', '*.csproj',
         ];
         const isRealProject = projectMarkers.some(marker => existsSync(path.join(config.projectRoot, marker)));
-        if (!isRealProject) {
-            log('info', `⚠️ Project root "${config.projectRoot}" does not look like a code project (no .git, package.json, etc.).`);
+        if (!isRealProject || isBlockedDirectory(config.projectRoot)) {
+            log('info', `⚠️ Project root "${config.projectRoot}" does not look like a code project (no .git, package.json, etc.).`);
             log('info', '   Skipping auto-index. The AI agent will be prompted to call mindmap_reindex with the correct project path.');
         }
         else {
             const stats = graph.getStats();
             if (stats.totalNodes === 0) {
-                log('info', `📋 Real project detected at: ${config.projectRoot}. Running initial indexing…`);
+                log('info', `📋 Real project detected at: ${config.projectRoot}. Running initial indexing…`);
                 try {
                     const result = await indexer.fullIndex();
-                    log('info', `✅ Initial index complete: ${result.filesParsed} files, ${result.nodesCreated} nodes, ${result.edgesCreated} edges`);
+                    log('info', `✅ Initial index complete: ${result.filesParsed} files, ${result.nodesCreated} nodes, ${result.edgesCreated} edges`);
                     if (result.parseErrors > 0) {
-                        log('warn', `⚠️ ${result.parseErrors} parse errors (non-fatal)`);
+                        log('warn', `⚠️ ${result.parseErrors} parse errors (non-fatal)`);
                     }
                 }
                 catch (err) {
-                    log('warn', `⚠️ Initial indexing failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                    log('warn', `⚠️ Initial indexing failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
             else {
-                log('info', `📋 Existing index found: ${stats.totalNodes} nodes. Running incremental update…`);
+                log('info', `📋 Existing index found: ${stats.totalNodes} nodes. Running incremental update…`);
                 try {
                     const result = await indexer.incrementalIndex();
-                    log('info', `✅ Incremental update: ${result.filesParsed} files reindexed`);
+                    log('info', `✅ Incremental update: ${result.filesParsed} files reindexed`);
                 }
                 catch (err) {
-                    log('warn', `⚠️ Incremental update failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                    log('warn', `⚠️ Incremental update failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
         }
@@ -1258,30 +1283,30 @@ async function main() {
                     filePath: n.filePath,
                 })));
                 semanticEngine.rebuildIDF();
-                log('info', `🧠 Semantic index built: ${nonFileNodes.length} symbols indexed`);
+                log('info', `🧠 Semantic index built: ${nonFileNodes.length} symbols indexed`);
             }
         }
         catch (err) {
-            log('warn', `⚠️ Semantic index build failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+            log('warn', `⚠️ Semantic index build failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // ── 9. Start file watcher ──────────────────────────────────
+    // ── 9. Start file watcher ──────────────────────────────────
     if (watcher && !config.memoryOnly) {
         try {
             await watcher.start();
-            log('info', '👁️ File watcher started');
+            log('info', '👁️ File watcher started');
         }
         catch (err) {
-            log('warn', `⚠️ File watcher failed to start: ${err instanceof Error ? err.message : String(err)}`);
+            log('warn', `⚠️ File watcher failed to start: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // ── 10. Graceful shutdown ──────────────────────────────────
+    // ── 10. Graceful shutdown ──────────────────────────────────
     let shuttingDown = false;
     async function shutdown(signal) {
         if (shuttingDown)
             return;
         shuttingDown = true;
-        log('info', `Received ${signal}, shutting down gracefully…`);
+        log('info', `Received ${signal}, shutting down gracefully…`);
         try {
             // Stop file watcher
             if (watcher) {
@@ -1328,7 +1353,7 @@ async function main() {
             catch {
                 // Ignore close errors
             }
-            log('info', '✅ Cleanup complete. Goodbye!');
+            log('info', '✅ Cleanup complete. Goodbye!');
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -1347,12 +1372,12 @@ async function main() {
         const msg = reason instanceof Error ? reason.message : String(reason);
         log('error', `Unhandled rejection: ${msg}`);
     });
-    // ── 11. Connect transport and start serving ────────────────
-    log('info', 'Connecting stdio transport…');
+    // ── 11. Connect transport and start serving ────────────────
+    log('info', 'Connecting stdio transport…');
     try {
         const transport = new StdioServerTransport();
         await server.connect(transport);
-        log('info', '🧠 AI Mind Map MCP Server is LIVE. Waiting for requests…');
+        log('info', '🧠 AI Mind Map MCP Server is LIVE. Waiting for requests…');
         log('info', `   Project: ${config.projectRoot}`);
         log('info', `   Database: ${config.dbPath}`);
         log('info', `   Session: ${sessionMemory.getCurrentSessionId()}`);
@@ -1363,7 +1388,7 @@ async function main() {
         process.exit(1);
     }
 }
-// ── Kick off ────────────────────────────────────────────────
+// ── Kick off ────────────────────────────────────────────────
 main().catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`Fatal: ${msg}\n`);