cntx-ui 3.1.4 → 3.1.13

package/dist/lib/agent-runtime.js

@@ -104,12 +104,12 @@ This agent is **stateful**. All interactions in this directory are logged to a p
      * Now logs the discovery process to memory
      */
     async discoverCodebase(options = {}) {
-        const { scope = 'all', includeDetails = true } = options;
+        const { scope = 'all', includeDetails = true, verbose = false } = options;
         try {
             await this.logInteraction('agent', `Starting codebase discovery for scope: ${scope}`);
             const discovery = {
                 overview: await this.getCodebaseOverview(),
-                bundles: await this.analyzeBundles(scope),
+                bundles: await this.analyzeBundles(scope, verbose),
                 architecture: await this.analyzeArchitecture(),
                 patterns: await this.identifyPatterns(),
                 recommendations: []
@@ -133,19 +133,56 @@ This agent is **stateful**. All interactions in this directory are logged to a p
      * Now recalls previous context from SQLite
      */
     async answerQuery(question, options = {}) {
-        const { maxResults = 10, includeCode = false } = options;
+        const { maxResults = 10, includeCode = false, query } = options;
+        const actualQuestion = question || query;
+        if (!actualQuestion) {
+            throw new Error('Missing question or query for search.');
+        }
         try {
-            await this.logInteraction('user', question);
+            await this.logInteraction('user', actualQuestion);
             // Perform semantic search via Vector Store
-            const combinedResults = await this.cntxServer.vectorStore.search(question, { limit: maxResults });
+            let combinedResults = await this.cntxServer.vectorStore.search(actualQuestion, { limit: maxResults });
+            // Heuristic fallback for common onboarding questions if results are poor
+            const lowConfidence = combinedResults.length === 0 || combinedResults[0].similarity < 0.6;
+            const isEntryQuery = /entry|start|main|index|run/i.test(actualQuestion);
+            const isModelQuery = /model|schema|data|db|database/i.test(actualQuestion);
+            let fallbackFiles = [];
+            if (lowConfidence && (isEntryQuery || isModelQuery)) {
+                const allFiles = this.cntxServer.fileSystemManager.getAllFiles();
+                if (isEntryQuery) {
+                    // Look for common entry points like main.tsx, main.rs, App.tsx, etc.
+                    const entryPatterns = [/main\./i, /index\./i, /app\./i, /router\./i, /server\./i];
+                    entryPatterns.forEach(pattern => {
+                        fallbackFiles.push(...allFiles.filter(f => pattern.test(f)).slice(0, 3));
+                    });
+                }
+                if (isModelQuery) {
+                    const modelPatterns = [/model/i, /schema/i, /db/i, /database/i, /entity/i];
+                    modelPatterns.forEach(pattern => {
+                        fallbackFiles.push(...allFiles.filter(f => pattern.test(f)).slice(0, 3));
+                    });
+                }
+                fallbackFiles = [...new Set(fallbackFiles)].slice(0, 8);
+            }
             // Generate contextual answer
-            const answer = await this.generateContextualAnswer(question, { chunks: combinedResults, files: [] }, includeCode);
+            const answer = await this.generateContextualAnswer(question, {
+                chunks: combinedResults,
+                files: fallbackFiles
+            }, includeCode);
+            // If no semantic results but we found fallbacks, improve the answer
+            if (combinedResults.length === 0 && fallbackFiles.length > 0) {
+                answer.response = `I couldn't find exact semantic matches, but based on common project structures, these files look relevant: ${fallbackFiles.join(', ')}`;
+                answer.confidence = 0.4;
+            }
             const response = {
                 question,
                 answer: answer.response,
                 evidence: answer.evidence,
                 confidence: answer.confidence,
-                relatedFiles: [...new Set(combinedResults.map(c => c.filePath))].slice(0, 5)
+                relatedFiles: [...new Set([
+                        ...combinedResults.map(c => c.filePath),
+                        ...fallbackFiles
+                    ])].slice(0, 8)
             };
             await this.logInteraction('agent', response.answer, { response });
             return response;
@@ -158,14 +195,18 @@ This agent is **stateful**. All interactions in this directory are logged to a p
      * Feature Investigation Mode: Now persists the investigation approach
      */
     async investigateFeature(featureDescription, options = {}) {
-        const { includeRecommendations = true } = options;
+        const { includeRecommendations = true, feature, description, area } = options;
+        const actualDescription = featureDescription || feature || description || area;
+        if (!actualDescription) {
+            throw new Error('Missing feature description for investigation.');
+        }
         try {
-            await this.logInteraction('user', `Investigating feature: ${featureDescription}`);
+            await this.logInteraction('user', `Investigating feature: ${actualDescription}`);
             const investigation = {
-                feature: featureDescription,
-                existing: await this.findExistingImplementations(featureDescription),
-                related: await this.findRelatedCode(featureDescription),
-                integration: await this.findIntegrationPoints(featureDescription)
+                feature: actualDescription,
+                existing: await this.findExistingImplementations(actualDescription),
+                related: await this.findRelatedCode(actualDescription),
+                integration: await this.findIntegrationPoints(actualDescription)
             };
             if (includeRecommendations) {
                 investigation.approach = await this.suggestImplementationApproach(investigation);
@@ -180,8 +221,9 @@ This agent is **stateful**. All interactions in this directory are logged to a p
     // --- Helper Methods ---
     async getCodebaseOverview() {
         const bundles = Array.from(this.cntxServer.bundleManager.getAllBundleInfo());
-        const totalFiles = bundles.reduce((sum, b) => sum + b.fileCount, 0);
-        const totalSize = bundles.reduce((sum, b) => sum + b.size, 0);
+        const totalFiles = this.cntxServer.fileSystemManager.getAllFiles().length;
+        const masterBundle = bundles.find(b => b.name === 'master');
+        const totalSize = masterBundle ? masterBundle.size : bundles.reduce((sum, b) => sum + b.size, 0);
         return {
             projectPath: this.cntxServer.CWD,
             totalBundles: bundles.length,
@@ -190,19 +232,57 @@ This agent is **stateful**. All interactions in this directory are logged to a p
             bundleNames: bundles.map(b => b.name)
         };
     }
-    async analyzeBundles(scope) {
+    async analyzeBundles(scope, verbose = false) {
         const bundles = this.cntxServer.bundleManager.getAllBundleInfo();
         const filtered = scope === 'all' ? bundles : bundles.filter(b => b.name === scope);
-        return filtered.map(b => ({
-            ...b,
-            purpose: this.inferBundlePurpose(b.name, b.files || [])
-        }));
+        return filtered.map(b => {
+            const files = b.files || [];
+            const purpose = this.inferBundlePurpose(b.name, files);
+            // Implement compact mode: only show top 5 files if not verbose
+            let displayFiles = files;
+            if (!verbose && files.length > 5) {
+                // Pick high-signal files: main, index, App, or just the first few
+                const keyFiles = files.filter(f => /main|index|app|router|api|models/i.test(f));
+                displayFiles = [...new Set([...keyFiles, ...files])].slice(0, 5);
+            }
+            return {
+                ...b,
+                purpose,
+                files: displayFiles,
+                totalFiles: files.length,
+                isTruncated: !verbose && files.length > 5
+            };
+        });
     }
     inferBundlePurpose(name, files) {
-        if (name.includes('component') || name.includes('ui'))
-            return 'UI Components';
-        if (name.includes('api') || name.includes('server'))
-            return 'Backend API';
+        const n = name.toLowerCase();
+        if (n.includes('component') || n.includes('ui') || n.includes('view') || n.includes('screen'))
+            return 'UI Components & Views';
+        if (n.includes('api') || n.includes('server') || n.includes('backend') || n.includes('netlify'))
+            return 'Backend API & Functions';
+        if (n.includes('hook'))
+            return 'React Hooks';
+        if (n.includes('util') || n.includes('helper'))
+            return 'Utility functions';
+        if (n.includes('lib') || n.includes('service') || n.includes('store'))
+            return 'Business logic & services';
+        if (n.includes('database') || n.includes('db') || n.includes('model') || n.includes('schema'))
+            return 'Data models & DB';
+        if (n.includes('test') || n.includes('spec'))
+            return 'Test suite';
+        if (n.includes('doc') || n.includes('readme'))
+            return 'Documentation';
+        if (n.includes('script') || n.includes('bin'))
+            return 'Scripts & CLI';
+        if (n.includes('asset') || n.includes('public'))
+            return 'Assets & static files';
+        if (n.includes('style') || n.includes('css'))
+            return 'Styles';
+        // Fallback to file extension analysis if name is generic
+        if (files.some(f => f.endsWith('.rs')))
+            return 'Rust Source';
+        if (files.some(f => f.endsWith('.ts') || f.endsWith('.tsx')))
+            return 'TypeScript Source';
         return 'General Module';
     }
     async analyzeArchitecture() {
@@ -247,30 +327,86 @@ This agent is **stateful**. All interactions in this directory are logged to a p
         return [{ type: 'info', message: 'Continue organizing by semantic purpose.' }];
     }
     async findExistingImplementations(featureDescription) {
-        return await this.cntxServer.vectorStore.search(featureDescription, { limit: 5 });
+        const results = await this.cntxServer.vectorStore.search(featureDescription, { limit: 5 });
+        return results.map(r => ({
+            file: r.filePath,
+            name: r.name,
+            purpose: r.purpose,
+            relevance: r.similarity
+        }));
     }
     async findRelatedCode(featureDescription) {
-        return [];
+        // Search for keywords in the description
+        const keywords = featureDescription.split(' ').filter(w => w.length > 4);
+        const allFiles = this.cntxServer.fileSystemManager.getAllFiles();
+        const matches = allFiles.filter(f => keywords.some(k => f.toLowerCase().includes(k.toLowerCase()))).slice(0, 5);
+        return matches.map(f => ({
+            file: f,
+            reason: 'Filename contains relevant keywords'
+        }));
     }
     async findIntegrationPoints(featureDescription) {
-        return [];
+        const existing = await this.findExistingImplementations(featureDescription);
+        const related = await this.findRelatedCode(featureDescription);
+        const candidates = [...new Set([
+                ...existing.map(e => e.file),
+                ...related.map(r => r.file)
+            ])];
+        return candidates.map(f => {
+            const ext = path.extname(f);
+            let role = 'Likely touch point';
+            if (ext === '.rs')
+                role = 'Backend logic (Rust)';
+            if (ext === '.tsx')
+                role = 'UI/Frontend component';
+            if (f.includes('router') || f.includes('api'))
+                role = 'API/Routing';
+            if (f.includes('store') || f.includes('hook'))
+                role = 'State/Data management';
+            return { file: f, role };
+        });
     }
     async suggestImplementationApproach(investigation) {
-        return { strategy: 'TBD', description: 'Ready to plan' };
+        const points = investigation.integration || [];
+        if (points.length === 0) {
+            return {
+                strategy: 'Exploratory Search',
+                description: 'No clear integration points found. Recommendation: Perform a broader semantic search for core business entities.'
+            };
+        }
+        const primaryFile = points[0].file;
+        return {
+            strategy: `Extend ${primaryFile}`,
+            description: `Based on the feature description, the primary integration point seems to be ${primaryFile}. You should examine this file and its dependencies to determine the exact insertion point.`,
+            steps: [
+                `1. Analyze ${primaryFile} for existing patterns.`,
+                `2. Check related files: ${points.slice(1, 3).map((p) => p.file).join(', ')}`,
+                `3. Implement the feature following the established coding style.`
+            ]
+        };
     }
     async generateContextualAnswer(question, results, includeCode) {
         let response = `Based on the codebase analysis:\n\n`;
-        if (results.chunks.length > 0) {
+        const hasSemantic = results.chunks.length > 0;
+        const hasFallbacks = results.files && results.files.length > 0;
+        if (hasSemantic) {
             const top = results.chunks[0];
             response += `The most relevant implementation found is \`${top.name}\` in \`${top.filePath}\` (Purpose: ${top.purpose}).\n\n`;
         }
+        else if (hasFallbacks) {
+            response += `I couldn't find an exact semantic match for your query, but these files look like strong candidates for the entry point or data model:\n\n`;
+            results.files.forEach((f) => {
+                response += `- \`${f}\`\n`;
+            });
+            response += `\nYou should start by examining these files.`;
+        }
         else {
             response += `No direct semantic matches found. Try refining your query.`;
         }
         return {
             response,
             evidence: results.chunks.slice(0, 3),
-            confidence: results.chunks.length > 0 ? 0.8 : 0.2
+            confidence: hasSemantic ? 0.8 : (hasFallbacks ? 0.4 : 0.2)
         };
     }
 }

package/dist/lib/api-router.js

@@ -286,8 +286,12 @@ export default class APIRouter {
     }
     async handlePostSemanticSearch(req, res) {
         const body = await this.getRequestBody(req);
-        const { query, limit = 20 } = JSON.parse(body);
-        const results = await this.vectorStore.search(query, { limit });
+        const { query, question, limit = 20 } = JSON.parse(body);
+        const searchTerm = query || question;
+        if (!searchTerm) {
+            return this.sendError(res, 400, 'Missing search term (query or question)');
+        }
+        const results = await this.vectorStore.search(searchTerm, { limit });
         this.sendResponse(res, 200, { results });
     }
     async handleGetVectorDbStatus(req, res) {

package/dist/lib/mcp-server.js

@@ -6,8 +6,10 @@ import { readFileSync } from 'fs';
 import { join } from 'path';
 export class MCPServer {
     cntxServer;
-    constructor(cntxServer) {
+    version;
+    constructor(cntxServer, version = '3.0.0') {
         this.cntxServer = cntxServer;
+        this.version = version;
         // Listen for MCP requests on stdin
         process.stdin.on('data', (data) => {
             this.handleInput(data.toString());
@@ -36,7 +38,7 @@ export class MCPServer {
                         resources: {},
                         prompts: {}
                     },
-                    serverInfo: { name: 'cntx-ui', version: '3.0.0' }
+                    serverInfo: { name: 'cntx-ui', version: this.version }
                 }));
             case 'tools/list':
                 return this.sendResponse(this.handleListTools(id));

package/dist/lib/semantic-splitter.js

@@ -28,6 +28,8 @@ export default class SemanticSplitter {
             includeContext: true, // Include imports/types needed
             minFunctionSize: 40, // Skip tiny functions
             minStructureSize: 20, // Skip tiny structures
+            verbose: options.verbose || false,
+            isMcp: options.isMcp || false,
             ...options
         };
         // Initialize tree-sitter parsers
@@ -55,6 +57,14 @@ export default class SemanticSplitter {
         this.parsers.toml.setLanguage(Toml);
         this.heuristicsManager = new HeuristicsManager();
     }
+    log(message) {
+        if (this.options.isMcp) {
+            process.stderr.write(message + '\n');
+        }
+        else {
+            console.log(message);
+        }
+    }
     getParser(filePath) {
         const ext = extname(filePath);
         switch (ext) {
@@ -77,10 +87,10 @@ export default class SemanticSplitter {
      * Now accepts a pre-filtered list of files from FileSystemManager
      */
     async extractSemanticChunks(projectPath, files = [], bundleConfig = null) {
-        console.log('🔪 Starting surgical semantic splitting via tree-sitter...');
-        console.log(`📂 Project path: ${projectPath}`);
+        this.log('🔪 Starting surgical semantic splitting via tree-sitter...');
+        this.log(`📂 Project path: ${projectPath}`);
         this.bundleConfig = bundleConfig;
-        console.log(`📁 Processing ${files.length} filtered files`);
+        this.log(`📁 Processing ${files.length} filtered files`);
         const allChunks = [];
         for (const filePath of files) {
             try {
@@ -88,10 +98,13 @@ export default class SemanticSplitter {
                 allChunks.push(...fileChunks);
             }
             catch (error) {
-                console.warn(`Failed to process ${filePath}: ${error.message}`);
+                console.warn(`⚠️ Failed to process ${filePath}: ${error.message}`);
+                if (this.options.verbose) {
+                    console.error(error.stack);
+                }
             }
         }
-        console.log(`🧩 Created ${allChunks.length} semantic chunks across project`);
+        this.log(`🧩 Created ${allChunks.length} semantic chunks across project`);
         return {
             summary: {
                 totalFiles: files.length,
@@ -108,43 +121,52 @@ export default class SemanticSplitter {
         const content = readFileSync(fullPath, 'utf8');
         // Skip files larger than 200KB — tree-sitter and embeddings can't handle them well
         if (content.length > 200_000) {
-            console.warn(`Skipping ${relativePath}: file too large (${Math.round(content.length / 1024)}KB)`);
+            this.log(`⚠️  Skipping ${relativePath}: file too large (${Math.round(content.length / 1024)}KB)`);
             return [];
         }
         const parser = this.getParser(relativePath);
-        const tree = parser.parse(content);
-        const root = tree.rootNode;
-        const ext = extname(relativePath).toLowerCase();
-        const elements = {
-            functions: [],
-            types: [],
-            imports: []
-        };
-        if (['.js', '.jsx', '.ts', '.tsx', '.rs'].includes(ext)) {
-            elements.imports = this.extractImports(root, content, relativePath);
-            // Traverse AST for functions and types
-            this.traverse(root, content, relativePath, elements);
-        }
-        else if (ext === '.json') {
-            this.extractJsonStructures(root, content, relativePath, elements);
-        }
-        else if (ext === '.css' || ext === '.scss') {
-            this.extractCssStructures(root, content, relativePath, elements);
-        }
-        else if (ext === '.html') {
-            this.extractHtmlStructures(root, content, relativePath, elements);
-        }
-        else if (ext === '.sql') {
-            this.extractSqlStructures(root, content, relativePath, elements);
-        }
-        else if (ext === '.md') {
-            this.extractMarkdownStructures(root, content, relativePath, elements);
+        try {
+            const tree = parser.parse(content);
+            const root = tree.rootNode;
+            const ext = extname(relativePath).toLowerCase();
+            const elements = {
+                functions: [],
+                types: [],
+                imports: []
+            };
+            if (['.js', '.jsx', '.ts', '.tsx', '.rs'].includes(ext)) {
+                elements.imports = this.extractImports(root, content, relativePath);
+                // Traverse AST for functions and types
+                this.traverse(root, content, relativePath, elements);
+            }
+            else if (ext === '.json') {
+                this.extractJsonStructures(root, content, relativePath, elements);
+            }
+            else if (ext === '.css' || ext === '.scss') {
+                this.extractCssStructures(root, content, relativePath, elements);
+            }
+            else if (ext === '.html') {
+                this.extractHtmlStructures(root, content, relativePath, elements);
+            }
+            else if (ext === '.sql') {
+                this.extractSqlStructures(root, content, relativePath, elements);
+            }
+            else if (ext === '.md') {
+                this.extractMarkdownStructures(root, content, relativePath, elements);
+            }
+            else if (ext === '.toml') {
+                this.extractTomlStructures(root, content, relativePath, elements);
+            }
+            // Create chunks from elements
+            return this.createChunks(elements, content, relativePath);
         }
-        else if (ext === '.toml') {
-            this.extractTomlStructures(root, content, relativePath, elements);
+        catch (error) {
+            this.log(`⚠️  Parser failed for ${relativePath}: ${error.message}`);
+            if (this.options.verbose) {
+                console.error(error.stack);
+            }
+            return [];
         }
-        // Create chunks from elements
-        return this.createChunks(elements, content, relativePath);
     }
     traverse(node, content, filePath, elements) {
         // Detect Function Declarations (JS/TS)

package/dist/lib/simple-vector-store.js

@@ -59,7 +59,7 @@ export default class SimpleVectorStore {
      * Semantic Search across persistent embeddings
      */
     async search(query, options = {}) {
-        const { limit = 10, threshold = 0.5 } = options;
+        const { limit = 10, threshold = 0.2 } = options;
         const queryEmbedding = await this.generateEmbedding(query);
         // Load all embeddings from DB
         const rows = this.db.db.prepare('SELECT chunk_id, embedding FROM vector_embeddings WHERE model_name = ?').all(this.modelName);

package/dist/lib/websocket-manager.js

@@ -7,35 +7,50 @@ export default class WebSocketManager {
     bundleManager;
     configManager;
     verbose;
+    isMcp;
     clients;
     wss;
     constructor(bundleManager, configManager, options = {}) {
         this.bundleManager = bundleManager;
         this.configManager = configManager;
         this.verbose = options.verbose || false;
+        this.isMcp = options.isMcp || false;
         this.clients = new Set();
         this.wss = null;
     }
+    log(message) {
+        if (this.isMcp) {
+            process.stderr.write(message + '\n');
+        }
+        else {
+            console.log(message);
+        }
+    }
     initialize(httpServer) {
         this.wss = new WebSocketServer({ server: httpServer });
         this.wss.on('connection', (ws) => {
             this.handleConnection(ws);
         });
+        this.wss.on('error', (error) => {
+            if (this.verbose) {
+                console.error('🔌 WebSocket server error:', error.message);
+            }
+        });
         if (this.verbose) {
-            console.log('🔌 WebSocket server initialized');
+            this.log('🔌 WebSocket server initialized');
         }
     }
     handleConnection(ws) {
         this.clients.add(ws);
         if (this.verbose) {
-            console.log(`📱 WebSocket client connected (${this.clients.size} total clients)`);
+            this.log(`📱 WebSocket client connected (${this.clients.size} total clients)`);
         }
         // Send initial status
         this.sendUpdate(ws);
         ws.on('close', () => {
             this.clients.delete(ws);
             if (this.verbose) {
-                console.log(`📱 WebSocket client disconnected (${this.clients.size} total clients)`);
+                this.log(`📱 WebSocket client disconnected (${this.clients.size} total clients)`);
             }
         });
         ws.on('error', (error) => {
@@ -58,7 +73,7 @@ export default class WebSocketManager {
     }
     handleClientMessage(ws, data) {
         if (this.verbose) {
-            console.log('📩 Received client message:', data.type);
+            this.log('📩 Received client message: ' + data.type);
         }
         switch (data.type) {
             case 'ping':
@@ -94,7 +109,7 @@ export default class WebSocketManager {
      */
     broadcastUpdate() {
         if (this.verbose) {
-            console.log('📢 Broadcasting status update to all clients');
+            this.log('📢 Broadcasting status update to all clients');
         }
         this.clients.forEach(client => {
             this.sendUpdate(client);
@@ -135,7 +150,7 @@ export default class WebSocketManager {
     }
     broadcastBundleUpdate(bundleName) {
         if (this.verbose) {
-            console.log(`📢 Broadcasting update for bundle: ${bundleName}`);
+            this.log(`📢 Broadcasting update for bundle: ${bundleName}`);
         }
         const bundle = this.configManager.getBundles().get(bundleName);
         if (!bundle)
@@ -186,7 +201,7 @@ export default class WebSocketManager {
     close() {
         if (this.wss) {
             if (this.verbose) {
-                console.log('🔌 Closing WebSocket server');
+                this.log('🔌 Closing WebSocket server');
             }
             this.clients.forEach(client => {
                 try {
@@ -200,7 +215,7 @@ export default class WebSocketManager {
             });
             this.wss.close(() => {
                 if (this.verbose) {
-                    console.log('🔌 WebSocket server closed');
+                    this.log('🔌 WebSocket server closed');
                 }
             });
             this.clients.clear();

package/dist/server.js

@@ -38,6 +38,7 @@ function getProjectName(cwd) {
 export class CntxServer {
     CWD;
     CNTX_DIR;
+    version;
     verbose;
     isMcp;
     mcpServerStarted;
@@ -66,6 +67,20 @@ export class CntxServer {
         this.mcpServerStarted = false;
         this.mcpServer = null;
         this.initMessages = [];
+        // Read package version
+        try {
+            let pkgDir = __dirname;
+            let pkgPath = join(pkgDir, 'package.json');
+            if (!existsSync(pkgPath)) {
+                pkgDir = join(__dirname, '..');
+                pkgPath = join(pkgDir, 'package.json');
+            }
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            this.version = pkg.version;
+        }
+        catch {
+            this.version = '3.1.5';
+        }
         // Ensure directory exists
         if (!existsSync(this.CNTX_DIR))
             mkdirSync(this.CNTX_DIR, { recursive: true });
@@ -74,13 +89,18 @@ export class CntxServer {
         this.databaseManager = this.configManager.dbManager;
         this.fileSystemManager = new FileSystemManager(cwd, { verbose: this.verbose });
         this.bundleManager = new BundleManager(this.configManager, this.fileSystemManager, this.verbose);
-        this.webSocketManager = new WebSocketManager(this.bundleManager, this.configManager, { verbose: this.verbose });
+        this.webSocketManager = new WebSocketManager(this.bundleManager, this.configManager, {
+            verbose: this.verbose,
+            isMcp: this.isMcp
+        });
         this.artifactManager = new ArtifactManager(cwd);
         // AI Components
         this.semanticSplitter = new SemanticSplitter({
             maxChunkSize: 2000,
             includeContext: true,
-            minFunctionSize: 50
+            minFunctionSize: 50,
+            verbose: this.verbose,
+            isMcp: this.isMcp
         });
         this.vectorStore = new SimpleVectorStore(this.databaseManager, {
             modelName: 'Xenova/all-MiniLM-L6-v2',
@@ -201,11 +221,15 @@ export class CntxServer {
     }
     startMCPServer() {
         if (!this.mcpServer) {
-            this.mcpServer = new MCPServer(this);
+            this.mcpServer = new MCPServer(this, this.version);
             this.mcpServerStarted = true;
         }
     }
     async listen(port = 3333, host = 'localhost') {
+        if (this.isMcp) {
+            this.log('Mode: MCP (stdio) - Skipping HTTP server start');
+            return null;
+        }
         const server = createServer((req, res) => {
             const url = parse(req.url || '/', true);
             // Serve static files from web/dist
@@ -215,12 +239,30 @@ export class CntxServer {
             // Route API requests
             this.apiRouter.handleRequest(req, res, url);
         });
-        this.webSocketManager.initialize(server);
-        return new Promise((resolve) => {
-            server.listen(port, host, () => {
-                this.log(`🚀 cntx-ui server running at http://${host}:${port}`);
-                resolve(server);
+        return new Promise((resolve, reject) => {
+            let currentPort = port;
+            const maxRetries = 10;
+            let retries = 0;
+            const tryListen = (p) => {
+                server.listen(p, host, () => {
+                    this.webSocketManager.initialize(server);
+                    this.log(`🚀 cntx-ui server running at http://${host}:${p}`);
+                    resolve(server);
+                });
+            };
+            server.on('error', (e) => {
+                if (e.code === 'EADDRINUSE' && retries < maxRetries) {
+                    retries++;
+                    const failedPort = currentPort;
+                    currentPort++;
+                    this.log(`⚠️  Port ${failedPort} busy, trying ${currentPort}...`);
+                    tryListen(currentPort);
+                }
+                else {
+                    reject(e);
+                }
             });
+            tryListen(currentPort);
         });
     }
     handleStaticFile(req, res, url) {
@@ -377,6 +419,11 @@ export async function initConfig(cwd = process.cwd()) {
         cpSync(agentRulesSource, agentRulesDest, { recursive: true });
         server.log('📁 Created agent-rules directory with templates');
     }
+    // 5. Trigger initial semantic scan (master bundle)
+    server.log('🔪 Performing initial semantic scan...');
+    await server.init({ skipFileWatcher: true, skipBundleGeneration: true });
+    await server.bundleManager.regenerateBundle('master');
+    server.log('✅ Project is ready for AI agents');
     return server.initMessages;
 }
 export async function generateBundle(name) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cntx-ui",
   "type": "module",
-  "version": "3.1.4",
+  "version": "3.1.13",
   "description": "Autonomous Repository Intelligence engine with web UI and MCP server. Unified semantic code understanding, local RAG, and agent working memory.",
   "keywords": [
     "repository-intelligence",