gitnexus 1.4.7 → 1.4.9

package/dist/core/wiki/generator.d.ts

@@ -12,11 +12,10 @@
 import { type LLMConfig } from './llm-client.js';
 export interface WikiOptions {
     force?: boolean;
-    model?: string;
-    baseUrl?: string;
-    apiKey?: string;
     maxTokensPerModule?: number;
     concurrency?: number;
+    /** If true, stop after building module tree for user review */
+    reviewOnly?: boolean;
 }
 export interface WikiMeta {
     fromCommit: string;
@@ -32,6 +31,12 @@ export interface ModuleTreeNode {
     children?: ModuleTreeNode[];
 }
 export type ProgressCallback = (phase: string, percent: number, detail?: string) => void;
+export interface WikiRunResult {
+    pagesGenerated: number;
+    mode: 'full' | 'incremental' | 'up-to-date';
+    failedModules: string[];
+    moduleTree?: ModuleTreeNode[];
+}
 export declare class WikiGenerator {
     private repoPath;
     private storagePath;
@@ -47,17 +52,24 @@ export declare class WikiGenerator {
     private lastPercent;
     /**
      * Create streaming options that report LLM progress to the progress bar.
-     * Uses the last known percent so streaming doesn't reset the bar backwards.
+     *
+     * Progress calculation:
+     * - If fixedPercent is provided, we show incremental progress within that phase
+     *   based on token generation (e.g., grouping at 15% → 15-28%)
+     * - If fixedPercent is NOT provided, we only update the label with token count
+     *   but keep the current percentage (avoids fluctuation during module generation)
+     *
+     * Also touches the DB connection periodically to prevent idle timeout.
      */
     private streamOpts;
+    /**
+     * Route LLM call to the appropriate provider (OpenAI-compatible or Cursor CLI).
+     */
+    private invokeLLM;
     /**
      * Main entry point. Runs the full pipeline or incremental update.
      */
-    run(): Promise<{
-        pagesGenerated: number;
-        mode: 'full' | 'incremental' | 'up-to-date';
-        failedModules: string[];
-    }>;
+    run(): Promise<WikiRunResult>;
     private ensureHTMLViewer;
     private fullGeneration;
     private buildModuleTree;
@@ -71,6 +83,8 @@ export declare class WikiGenerator {
     private fallbackGrouping;
     /**
      * Split a large module into sub-modules by subdirectory.
+     * Uses the full subDir path for naming to avoid slug collisions
+     * (e.g., "synapse-screen/src" vs "synapse-core/src").
      */
     private splitBySubdirectory;
     /**
@@ -84,6 +98,11 @@ export declare class WikiGenerator {
     private generateOverview;
     private incrementalUpdate;
     private getCurrentCommit;
+    /**
+     * Check if fromCommit is an ancestor of toCommit (reachable in git history).
+     * Returns false if commits are on divergent branches or fromCommit doesn't exist.
+     */
+    private isCommitReachable;
     private getChangedFiles;
     private readSourceFiles;
     private truncateSource;

package/dist/core/wiki/generator.js

@@ -12,9 +12,10 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { execSync, execFileSync } from 'child_process';
-import { initWikiDb, closeWikiDb, getFilesWithExports, getAllFiles, getIntraModuleCallEdges, getInterModuleCallEdges, getProcessesForFiles, getAllProcesses, getInterModuleEdgesForOverview, } from './graph-queries.js';
+import { initWikiDb, closeWikiDb, touchWikiDb, getFilesWithExports, getAllFiles, getIntraModuleCallEdges, getInterModuleCallEdges, getProcessesForFiles, getAllProcesses, getInterModuleEdgesForOverview, } from './graph-queries.js';
 import { generateHTMLViewer } from './html-viewer.js';
 import { callLLM, estimateTokens, } from './llm-client.js';
+import { callCursorLLM, resolveCursorConfig, } from './cursor-client.js';
 import { GROUPING_SYSTEM_PROMPT, GROUPING_USER_PROMPT, MODULE_SYSTEM_PROMPT, MODULE_USER_PROMPT, PARENT_SYSTEM_PROMPT, PARENT_USER_PROMPT, OVERVIEW_SYSTEM_PROMPT, OVERVIEW_USER_PROMPT, fillTemplate, formatFileListForGrouping, formatDirectoryTree, formatCallEdges, formatProcesses, } from './prompts.js';
 import { shouldIgnorePath } from '../../config/ignore-service.js';
 // ─── Constants ────────────────────────────────────────────────────────
@@ -51,17 +52,55 @@ export class WikiGenerator {
     lastPercent = 0;
     /**
      * Create streaming options that report LLM progress to the progress bar.
-     * Uses the last known percent so streaming doesn't reset the bar backwards.
+     *
+     * Progress calculation:
+     * - If fixedPercent is provided, we show incremental progress within that phase
+     *   based on token generation (e.g., grouping at 15% → 15-28%)
+     * - If fixedPercent is NOT provided, we only update the label with token count
+     *   but keep the current percentage (avoids fluctuation during module generation)
+     *
+     * Also touches the DB connection periodically to prevent idle timeout.
      */
-    streamOpts(label, fixedPercent) {
+    streamOpts(label, fixedPercent, percentRange = 10) {
+        const hasFixedStart = fixedPercent !== undefined;
+        const startPercent = fixedPercent ?? this.lastPercent;
+        const expectedTokens = 2000;
+        let lastTouch = Date.now();
         return {
             onChunk: (chars) => {
                 const tokens = Math.round(chars / 4);
-                const pct = fixedPercent ?? this.lastPercent;
-                this.onProgress('stream', pct, `${label} (${tokens} tok)`);
+                if (hasFixedStart) {
+                    // For fixed phases (like grouping), show incremental progress
+                    const progress = Math.min(1, tokens / expectedTokens);
+                    const pct = Math.round(startPercent + (progress * percentRange));
+                    this.onProgress('stream', pct, `${label} (${tokens} tok)`);
+                }
+                else {
+                    // For module generation, only update the label, keep current percent
+                    this.onProgress('stream', this.lastPercent, `${label} (${tokens} tok)`);
+                }
+                // Touch DB every 60s to prevent idle timeout during long LLM calls
+                const now = Date.now();
+                if (now - lastTouch > 60_000) {
+                    touchWikiDb();
+                    lastTouch = now;
+                }
             },
         };
     }
+    /**
+     * Route LLM call to the appropriate provider (OpenAI-compatible or Cursor CLI).
+     */
+    async invokeLLM(prompt, systemPrompt, options) {
+        if (this.llmConfig.provider === 'cursor') {
+            const cursorConfig = resolveCursorConfig({
+                model: this.llmConfig.model,
+                workingDirectory: this.repoPath,
+            });
+            return callCursorLLM(prompt, cursorConfig, systemPrompt, options);
+        }
+        return callLLM(prompt, this.llmConfig, systemPrompt, options);
+    }
     /**
      * Main entry point. Runs the full pipeline or incremental update.
      */
@@ -144,6 +183,13 @@ export class WikiGenerator {
         // Phase 1: Build module tree
         const moduleTree = await this.buildModuleTree(enrichedFiles);
         pagesGenerated = 0;
+        // If reviewOnly mode, save tree and stop for user to review/edit
+        if (this.options.reviewOnly) {
+            await this.saveModuleTree(moduleTree);
+            this.onProgress('review', 30, 'Module tree ready for review');
+            const reviewResult = { pagesGenerated: 0, mode: 'full', failedModules: [], moduleTree };
+            return reviewResult;
+        }
         // Phase 2: Generate module pages (parallel with concurrency limit)
         const totalModules = this.countModules(moduleTree);
         let modulesProcessed = 0;
@@ -213,6 +259,19 @@ export class WikiGenerator {
     }
     // ─── Phase 1: Build Module Tree ────────────────────────────────────
     async buildModuleTree(files) {
+        // First, check for user-edited module_tree.json (from --review workflow)
+        const editablePath = path.join(this.wikiDir, 'module_tree.json');
+        try {
+            const edited = await fs.readFile(editablePath, 'utf-8');
+            const parsed = JSON.parse(edited);
+            if (Array.isArray(parsed) && parsed.length > 0) {
+                this.onProgress('grouping', 25, 'Using edited module tree');
+                return parsed;
+            }
+        }
+        catch {
+            // No edited tree, check for original snapshot
+        }
         // Check for existing immutable snapshot (resumability)
         const snapshotPath = path.join(this.wikiDir, 'first_module_tree.json');
         try {
@@ -233,7 +292,7 @@ export class WikiGenerator {
             FILE_LIST: fileList,
             DIRECTORY_TREE: dirTree,
         });
-        const response = await callLLM(prompt, this.llmConfig, GROUPING_SYSTEM_PROMPT, this.streamOpts('Grouping files', 15));
+        const response = await this.invokeLLM(prompt, GROUPING_SYSTEM_PROMPT, this.streamOpts('Grouping files', 15, 13));
         const grouping = this.parseGroupingResponse(response.content, files);
         // Convert to tree nodes
         const tree = [];
@@ -243,8 +302,14 @@ export class WikiGenerator {
             // Token budget check — split if too large
             const totalTokens = await this.estimateModuleTokens(modulePaths);
             if (totalTokens > this.maxTokensPerModule && modulePaths.length > 3) {
-                node.children = this.splitBySubdirectory(moduleName, modulePaths);
-                node.files = []; // Parent doesn't own files directly when split
+                const children = this.splitBySubdirectory(moduleName, modulePaths);
+                // Only create hierarchy if we actually got multiple children
+                // If splitting results in 1 child, keep files flat (avoid redundant nesting)
+                if (children.length > 1) {
+                    node.children = children;
+                    node.files = []; // Parent doesn't own files directly when split
+                }
+                // If only 1 child, keep original flat structure (files stay in node.files)
             }
             tree.push(node);
         }
@@ -322,12 +387,13 @@ export class WikiGenerator {
     }
     /**
      * Split a large module into sub-modules by subdirectory.
+     * Uses the full subDir path for naming to avoid slug collisions
+     * (e.g., "synapse-screen/src" vs "synapse-core/src").
      */
     splitBySubdirectory(moduleName, files) {
         const subGroups = new Map();
         for (const fp of files) {
             const parts = fp.replace(/\\/g, '/').split('/');
-            // Use the deepest common-ish directory
             const subDir = parts.length > 2 ? parts.slice(0, 2).join('/') : parts[0];
             let group = subGroups.get(subDir);
             if (!group) {
@@ -336,11 +402,17 @@ export class WikiGenerator {
             }
             group.push(fp);
         }
-        return Array.from(subGroups.entries()).map(([subDir, subFiles]) => ({
-            name: `${moduleName} — ${path.basename(subDir)}`,
-            slug: this.slugify(`${moduleName}-${path.basename(subDir)}`),
-            files: subFiles,
-        }));
+        // Check if basenames are unique; if not, use the full subDir path
+        const basenames = Array.from(subGroups.keys()).map(s => path.basename(s));
+        const hasCollisions = new Set(basenames).size < basenames.length;
+        return Array.from(subGroups.entries()).map(([subDir, subFiles]) => {
+            const label = hasCollisions ? subDir.replace(/\//g, '-') : path.basename(subDir);
+            return {
+                name: `${moduleName} — ${label}`,
+                slug: this.slugify(`${moduleName}-${label}`),
+                files: subFiles,
+            };
+        });
     }
     // ─── Phase 2: Generate Module Pages ─────────────────────────────────
     /**
@@ -370,7 +442,7 @@ export class WikiGenerator {
             INCOMING_CALLS: formatCallEdges(interCalls.incoming),
             PROCESSES: formatProcesses(processes),
         });
-        const response = await callLLM(prompt, this.llmConfig, MODULE_SYSTEM_PROMPT, this.streamOpts(node.name));
+        const response = await this.invokeLLM(prompt, MODULE_SYSTEM_PROMPT, this.streamOpts(node.name));
         // Write page with front matter
         const pageContent = `# ${node.name}\n\n${response.content}`;
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
@@ -406,7 +478,7 @@ export class WikiGenerator {
             CROSS_MODULE_CALLS: formatCallEdges(crossCalls),
             CROSS_PROCESSES: formatProcesses(processes),
         });
-        const response = await callLLM(prompt, this.llmConfig, PARENT_SYSTEM_PROMPT, this.streamOpts(node.name));
+        const response = await this.invokeLLM(prompt, PARENT_SYSTEM_PROMPT, this.streamOpts(node.name));
         const pageContent = `# ${node.name}\n\n${response.content}`;
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
@@ -442,7 +514,7 @@ export class WikiGenerator {
             MODULE_EDGES: edgesText,
             TOP_PROCESSES: formatProcesses(topProcesses),
         });
-        const response = await callLLM(prompt, this.llmConfig, OVERVIEW_SYSTEM_PROMPT, this.streamOpts('Generating overview', 88));
+        const response = await this.invokeLLM(prompt, OVERVIEW_SYSTEM_PROMPT, this.streamOpts('Generating overview', 88));
         const pageContent = `# ${path.basename(this.repoPath)} — Wiki\n\n${response.content}`;
         await fs.writeFile(path.join(this.wikiDir, 'overview.md'), pageContent, 'utf-8');
     }
@@ -451,6 +523,13 @@ export class WikiGenerator {
         this.onProgress('incremental', 5, 'Detecting changes...');
         // Get changed files since last generation
         const changedFiles = this.getChangedFiles(existingMeta.fromCommit, currentCommit);
+        // If null, commits are on divergent branches (e.g., wiki generated on feature branch,
+        // now running on main). Fall back to full generation.
+        if (changedFiles === null) {
+            this.onProgress('incremental', 10, 'Branch diverged, running full generation...');
+            const fullResult = await this.fullGeneration(currentCommit);
+            return { ...fullResult, mode: 'incremental' };
+        }
         if (changedFiles.length === 0) {
             // No file changes but commit differs (e.g. merge commit)
             await this.saveWikiMeta({
@@ -559,13 +638,31 @@ export class WikiGenerator {
             return '';
         }
     }
+    /**
+     * Check if fromCommit is an ancestor of toCommit (reachable in git history).
+     * Returns false if commits are on divergent branches or fromCommit doesn't exist.
+     */
+    isCommitReachable(fromCommit, toCommit) {
+        try {
+            execFileSync('git', ['merge-base', '--is-ancestor', fromCommit, toCommit], { cwd: this.repoPath, stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     getChangedFiles(fromCommit, toCommit) {
+        // First check if fromCommit is reachable from toCommit
+        // This handles the case where wiki was generated on a different branch
+        if (!this.isCommitReachable(fromCommit, toCommit)) {
+            return null; // Signal that we can't compute diff (divergent branches)
+        }
         try {
             const output = execFileSync('git', ['diff', `${fromCommit}..${toCommit}`, '--name-only'], { cwd: this.repoPath }).toString().trim();
             return output ? output.split('\n').filter(Boolean) : [];
         }
         catch {
-            return [];
+            return null; // Treat git errors as needing full regen
         }
     }
     async readSourceFiles(filePaths) {

package/dist/core/wiki/graph-queries.d.ts

@@ -4,6 +4,10 @@
  * Encapsulated Cypher queries against the GitNexus knowledge graph.
  * Uses the MCP-style pooled lbug-adapter for connection management.
  */
+/**
+ * Touch the wiki DB connection to prevent idle timeout during long LLM calls.
+ */
+export declare function touchWikiDb(): void;
 export interface FileWithExports {
     filePath: string;
     symbols: Array<{

package/dist/core/wiki/graph-queries.js

@@ -4,8 +4,14 @@
  * Encapsulated Cypher queries against the GitNexus knowledge graph.
  * Uses the MCP-style pooled lbug-adapter for connection management.
  */
-import { initLbug, executeQuery, closeLbug } from '../../mcp/core/lbug-adapter.js';
+import { initLbug, executeQuery, closeLbug, touchRepo } from '../../mcp/core/lbug-adapter.js';
 const REPO_ID = '__wiki__';
+/**
+ * Touch the wiki DB connection to prevent idle timeout during long LLM calls.
+ */
+export function touchWikiDb() {
+    touchRepo(REPO_ID);
+}
 /**
  * Initialize the LadybugDB connection for wiki generation.
  */

package/dist/core/wiki/llm-client.d.ts

@@ -6,12 +6,14 @@
  *
  * Config priority: CLI flags > env vars > defaults
  */
+export type LLMProvider = 'openai' | 'cursor';
 export interface LLMConfig {
     apiKey: string;
     baseUrl: string;
     model: string;
     maxTokens: number;
     temperature: number;
+    provider?: LLMProvider;
 }
 export interface LLMResponse {
     content: string;

package/dist/core/wiki/llm-client.js

@@ -15,23 +15,27 @@
 export async function resolveLLMConfig(overrides) {
     const { loadCLIConfig } = await import('../../storage/repo-manager.js');
     const savedConfig = await loadCLIConfig();
+    const provider = overrides?.provider || savedConfig.provider || 'openai';
     const apiKey = overrides?.apiKey
         || process.env.GITNEXUS_API_KEY
         || process.env.OPENAI_API_KEY
         || savedConfig.apiKey
         || '';
+    // For cursor provider, only use model if explicitly provided (default is 'auto' handled by CLI)
+    // For openai provider, use model with fallback to default
+    const model = provider === 'cursor'
+        ? (overrides?.model || savedConfig.cursorModel || '')
+        : (overrides?.model || process.env.GITNEXUS_MODEL || savedConfig.model || 'minimax/minimax-m2.5');
     return {
         apiKey,
         baseUrl: overrides?.baseUrl
             || process.env.GITNEXUS_LLM_BASE_URL
             || savedConfig.baseUrl
             || 'https://openrouter.ai/api/v1',
-        model: overrides?.model
-            || process.env.GITNEXUS_MODEL
-            || savedConfig.model
-            || 'minimax/minimax-m2.5',
+        model,
         maxTokens: overrides?.maxTokens ?? 16_384,
         temperature: overrides?.temperature ?? 0,
+        provider,
     };
 }
 /**

package/dist/core/wiki/prompts.d.ts

@@ -6,11 +6,11 @@
  */
 export declare const GROUPING_SYSTEM_PROMPT = "You are a documentation architect. Given a list of source files with their exported symbols, group them into logical documentation modules.\n\nRules:\n- Each module should represent a cohesive feature, layer, or domain\n- Every file must appear in exactly one module\n- Module names should be human-readable (e.g. \"Authentication\", \"Database Layer\", \"API Routes\")\n- Aim for 5-15 modules for a typical project. Fewer for small projects, more for large ones\n- Group by functionality, not by file type or directory structure alone\n- Do NOT create modules for tests, configs, or non-source files";
 export declare const GROUPING_USER_PROMPT = "Group these source files into documentation modules.\n\n**Files and their exports:**\n{{FILE_LIST}}\n\n**Directory structure:**\n{{DIRECTORY_TREE}}\n\nRespond with ONLY a JSON object mapping module names to file path arrays. No markdown, no explanation.\nExample format:\n{\n  \"Authentication\": [\"src/auth/login.ts\", \"src/auth/session.ts\"],\n  \"Database\": [\"src/db/connection.ts\", \"src/db/models.ts\"]\n}";
-export declare const MODULE_SYSTEM_PROMPT = "You are a technical documentation writer. Write clear, developer-focused documentation for a code module.\n\nRules:\n- Reference actual function names, class names, and code patterns \u2014 do NOT invent APIs\n- Use the call graph and execution flow data for accuracy, but do NOT mechanically list every edge\n- Include Mermaid diagrams only when they genuinely help understanding. Keep them small (5-10 nodes max)\n- Structure the document however makes sense for this module \u2014 there is no mandatory format\n- Write for a developer who needs to understand and contribute to this code";
+export declare const MODULE_SYSTEM_PROMPT = "You are a technical documentation writer. Write clear, developer-focused documentation for a code module.\n\nRules:\n- Output ONLY the documentation content \u2014 no meta-commentary like \"I've written...\", \"Here's the documentation...\", \"The documentation covers...\", or similar\n- Start directly with the module heading and content\n- Reference actual function names, class names, and code patterns \u2014 do NOT invent APIs\n- Use the call graph and execution flow data for accuracy, but do NOT mechanically list every edge\n- Include Mermaid diagrams only when they genuinely help understanding. Keep them small (5-10 nodes max)\n- Structure the document however makes sense for this module \u2014 there is no mandatory format\n- Write for a developer who needs to understand and contribute to this code";
 export declare const MODULE_USER_PROMPT = "Write documentation for the **{{MODULE_NAME}}** module.\n\n## Source Code\n\n{{SOURCE_CODE}}\n\n## Call Graph & Execution Flows (reference for accuracy)\n\nInternal calls: {{INTRA_CALLS}}\nOutgoing calls: {{OUTGOING_CALLS}}\nIncoming calls: {{INCOMING_CALLS}}\nExecution flows: {{PROCESSES}}\n\n---\n\nWrite comprehensive documentation for this module. Cover its purpose, how it works, its key components, and how it connects to the rest of the codebase. Use whatever structure best fits this module \u2014 you decide the sections and headings. Include a Mermaid diagram only if it genuinely clarifies the architecture.";
-export declare const PARENT_SYSTEM_PROMPT = "You are a technical documentation writer. Write a summary page for a module that contains sub-modules. Synthesize the children's documentation \u2014 do not re-read source code.\n\nRules:\n- Reference actual components from the child modules\n- Focus on how the sub-modules work together, not repeating their individual docs\n- Keep it concise \u2014 the reader can click through to child pages for detail\n- Include a Mermaid diagram only if it genuinely clarifies how the sub-modules relate";
+export declare const PARENT_SYSTEM_PROMPT = "You are a technical documentation writer. Write a summary page for a module that contains sub-modules. Synthesize the children's documentation \u2014 do not re-read source code.\n\nRules:\n- Output ONLY the documentation content \u2014 no meta-commentary like \"I've written...\", \"Here's the documentation...\", \"The documentation covers...\", or similar\n- Start directly with the module heading and content\n- Reference actual components from the child modules\n- Focus on how the sub-modules work together, not repeating their individual docs\n- Keep it concise \u2014 the reader can click through to child pages for detail\n- Include a Mermaid diagram only if it genuinely clarifies how the sub-modules relate";
 export declare const PARENT_USER_PROMPT = "Write documentation for the **{{MODULE_NAME}}** module, which contains these sub-modules:\n\n{{CHILDREN_DOCS}}\n\nCross-module calls: {{CROSS_MODULE_CALLS}}\nShared execution flows: {{CROSS_PROCESSES}}\n\n---\n\nWrite a concise overview of this module group. Explain its purpose, how the sub-modules fit together, and the key workflows that span them. Link to sub-module pages (e.g. `[Sub-module Name](sub-module-slug.md)`) rather than repeating their content. Use whatever structure fits best.";
-export declare const OVERVIEW_SYSTEM_PROMPT = "You are a technical documentation writer. Write the top-level overview page for a repository wiki. This is the first page a new developer sees.\n\nRules:\n- Be clear and welcoming \u2014 this is the entry point to the entire codebase\n- Reference actual module names so readers can navigate to their docs\n- Include a high-level Mermaid architecture diagram showing only the most important modules and their relationships (max 10 nodes). A new dev should grasp it in 10 seconds\n- Do NOT create module index tables or list every module with descriptions \u2014 just link to module pages naturally within the text\n- Use the inter-module edges and execution flow data for accuracy, but do NOT dump them raw";
+export declare const OVERVIEW_SYSTEM_PROMPT = "You are a technical documentation writer. Write the top-level overview page for a repository wiki. This is the first page a new developer sees.\n\nRules:\n- Output ONLY the documentation content \u2014 no meta-commentary like \"I've written...\", \"Here's the documentation...\", \"The page has been rewritten...\", or similar\n- Start directly with the project heading and content\n- Be clear and welcoming \u2014 this is the entry point to the entire codebase\n- Reference actual module names so readers can navigate to their docs\n- Include a high-level Mermaid architecture diagram showing only the most important modules and their relationships (max 10 nodes). A new dev should grasp it in 10 seconds\n- Do NOT create module index tables or list every module with descriptions \u2014 just link to module pages naturally within the text\n- Use the inter-module edges and execution flow data for accuracy, but do NOT dump them raw";
 export declare const OVERVIEW_USER_PROMPT = "Write the overview page for this repository's wiki.\n\n## Project Info\n\n{{PROJECT_INFO}}\n\n## Module Summaries\n\n{{MODULE_SUMMARIES}}\n\n## Reference Data (for accuracy \u2014 do not reproduce verbatim)\n\nInter-module call edges: {{MODULE_EDGES}}\nKey system flows: {{TOP_PROCESSES}}\n\n---\n\nWrite a clear overview of this project: what it does, how it's architected, and the key end-to-end flows. Include a simple Mermaid architecture diagram (max 10 nodes, big-picture only). Link to module pages (e.g. `[Module Name](module-slug.md)`) naturally in the text rather than listing them in a table. If project config was provided, include brief setup instructions. Structure the page however reads best.";
 /**
  * Replace {{PLACEHOLDER}} tokens in a template string.

package/dist/core/wiki/prompts.js

@@ -32,6 +32,8 @@ Example format:
 export const MODULE_SYSTEM_PROMPT = `You are a technical documentation writer. Write clear, developer-focused documentation for a code module.
 
 Rules:
+- Output ONLY the documentation content — no meta-commentary like "I've written...", "Here's the documentation...", "The documentation covers...", or similar
+- Start directly with the module heading and content
 - Reference actual function names, class names, and code patterns — do NOT invent APIs
 - Use the call graph and execution flow data for accuracy, but do NOT mechanically list every edge
 - Include Mermaid diagrams only when they genuinely help understanding. Keep them small (5-10 nodes max)
@@ -57,6 +59,8 @@ Write comprehensive documentation for this module. Cover its purpose, how it wor
 export const PARENT_SYSTEM_PROMPT = `You are a technical documentation writer. Write a summary page for a module that contains sub-modules. Synthesize the children's documentation — do not re-read source code.
 
 Rules:
+- Output ONLY the documentation content — no meta-commentary like "I've written...", "Here's the documentation...", "The documentation covers...", or similar
+- Start directly with the module heading and content
 - Reference actual components from the child modules
 - Focus on how the sub-modules work together, not repeating their individual docs
 - Keep it concise — the reader can click through to child pages for detail
@@ -75,6 +79,8 @@ Write a concise overview of this module group. Explain its purpose, how the sub-
 export const OVERVIEW_SYSTEM_PROMPT = `You are a technical documentation writer. Write the top-level overview page for a repository wiki. This is the first page a new developer sees.
 
 Rules:
+- Output ONLY the documentation content — no meta-commentary like "I've written...", "Here's the documentation...", "The page has been rewritten...", or similar
+- Start directly with the project heading and content
 - Be clear and welcoming — this is the entry point to the entire codebase
 - Reference actual module names so readers can navigate to their docs
 - Include a high-level Mermaid architecture diagram showing only the most important modules and their relationships (max 10 nodes). A new dev should grasp it in 10 seconds

package/dist/mcp/core/embedder.js

@@ -5,9 +5,9 @@
  * For MCP, we only need to compute query embeddings, not batch embed.
  */
 import { pipeline, env } from '@huggingface/transformers';
+import { isHttpMode, getHttpDimensions, httpEmbedQuery } from '../../core/embeddings/http-client.js';
 // Model config
 const MODEL_ID = 'Snowflake/snowflake-arctic-embed-xs';
-const EMBEDDING_DIMS = 384;
 // Module-level state for singleton pattern
 let embedderInstance = null;
 let isInitializing = false;
@@ -16,6 +16,9 @@ let initPromise = null;
  * Initialize the embedding model (lazy, on first search)
  */
 export const initEmbedder = async () => {
+    if (isHttpMode()) {
+        throw new Error('initEmbedder() should not be called in HTTP mode.');
+    }
     if (embedderInstance) {
         return embedderInstance;
     }
@@ -75,11 +78,14 @@ export const initEmbedder = async () => {
 /**
  * Check if embedder is ready
  */
-export const isEmbedderReady = () => embedderInstance !== null;
+export const isEmbedderReady = () => isHttpMode() || embedderInstance !== null;
 /**
  * Embed a query text for semantic search
  */
 export const embedQuery = async (query) => {
+    if (isHttpMode()) {
+        return httpEmbedQuery(query);
+    }
     const embedder = await initEmbedder();
     const result = await embedder(query, {
         pooling: 'mean',
@@ -90,7 +96,9 @@ export const embedQuery = async (query) => {
 /**
  * Get embedding dimensions
  */
-export const getEmbeddingDims = () => EMBEDDING_DIMS;
+export const getEmbeddingDims = () => {
+    return getHttpDimensions() ?? 384;
+};
 /**
  * Cleanup embedder
  */

package/dist/mcp/core/lbug-adapter.d.ts

@@ -15,6 +15,11 @@
 import lbug from '@ladybugdb/core';
 /** Saved real stdout.write — used to silence LadybugDB native output without race conditions */
 export declare const realStdoutWrite: any;
+/**
+ * Touch a repo to reset its idle timeout.
+ * Call this during long-running operations to prevent the connection from being closed.
+ */
+export declare const touchRepo: (repoId: string) => void;
 /**
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).

package/dist/mcp/core/lbug-adapter.js

@@ -46,6 +46,16 @@ function ensureIdleTimer() {
         idleTimer.unref();
     }
 }
+/**
+ * Touch a repo to reset its idle timeout.
+ * Call this during long-running operations to prevent the connection from being closed.
+ */
+export const touchRepo = (repoId) => {
+    const entry = pool.get(repoId);
+    if (entry) {
+        entry.lastUsed = Date.now();
+    }
+};
 /**
  * Evict the least-recently-used repo if pool is at capacity
  */
@@ -109,6 +119,7 @@ function closeOne(repoId) {
  * Create a new Connection from a repo's Database.
  * Silences stdout to prevent native module output from corrupting MCP stdio.
  */
+let activeQueryCount = 0;
 function silenceStdout() {
     if (stdoutSilenceCount++ === 0) {
         process.stdout.write = (() => true);
@@ -122,8 +133,10 @@ function restoreStdout() {
 }
 // Safety watchdog: restore stdout if it gets stuck silenced (e.g. native crash
 // inside createConnection before restoreStdout runs).
+// Exempts active queries and pre-warm — these legitimately hold silence for
+// longer than 1 second (queries can take up to QUERY_TIMEOUT_MS = 30s).
 setInterval(() => {
-    if (stdoutSilenceCount > 0 && !preWarmActive) {
+    if (stdoutSilenceCount > 0 && !preWarmActive && activeQueryCount === 0) {
         stdoutSilenceCount = 0;
         process.stdout.write = realStdoutWrite;
     }
@@ -389,6 +402,8 @@ export const executeQuery = async (repoId, cypher) => {
     }
     entry.lastUsed = Date.now();
     const conn = await checkout(entry);
+    silenceStdout();
+    activeQueryCount++;
     try {
         const queryResult = await withTimeout(conn.query(cypher), QUERY_TIMEOUT_MS, 'Query');
         const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
@@ -396,6 +411,8 @@ export const executeQuery = async (repoId, cypher) => {
         return rows;
     }
     finally {
+        activeQueryCount--;
+        restoreStdout();
         checkin(entry, conn);
     }
 };
@@ -410,6 +427,8 @@ export const executeParameterized = async (repoId, cypher, params) => {
     }
     entry.lastUsed = Date.now();
     const conn = await checkout(entry);
+    silenceStdout();
+    activeQueryCount++;
     try {
         const stmt = await withTimeout(conn.prepare(cypher), QUERY_TIMEOUT_MS, 'Prepare');
         if (!stmt.isSuccess()) {
@@ -422,6 +441,8 @@ export const executeParameterized = async (repoId, cypher, params) => {
         return rows;
     }
     finally {
+        activeQueryCount--;
+        restoreStdout();
         checkin(entry, conn);
     }
 };
@@ -448,7 +469,7 @@ export const closeLbug = async (repoId) => {
  */
 export const isLbugReady = (repoId) => pool.has(repoId);
 /** Regex to detect write operations in user-supplied Cypher queries */
-export const CYPHER_WRITE_RE = /\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH)\b/i;
+export const CYPHER_WRITE_RE = /(?<!:)\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH|FOREACH)\b/i;
 /** Check if a Cypher query contains write operations */
 export function isWriteQuery(query) {
     return CYPHER_WRITE_RE.test(query);