gitnexus 1.4.0 → 1.4.1

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

@@ -4,14 +4,16 @@
  * All prompts produce deterministic, source-grounded documentation.
  * Templates use {{PLACEHOLDER}} substitution.
  */
-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_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_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_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.";
+export declare const GROUPING_SYSTEM_PROMPT_LEGACY = "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_LEGACY = "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 GROUPING_SYSTEM_PROMPT = "You are a documentation architect. Given a list of source files with their exported symbols AND graph-detected community clusters, group them into logical documentation modules.\n\nRules:\n- Use the graph-detected communities as your PRIMARY signal for grouping\n- You may merge small communities, split large ones, or rename them for clarity\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- Consider inter-community coupling and cross-community processes when deciding merges\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**Graph-detected communities (primary signal):**\n{{COMMUNITY_GROUPS}}\n\n**Inter-community coupling:**\n{{INTER_COMMUNITY_EDGES}}\n\n**Cross-community execution flows:**\n{{CROSS_COMMUNITY_PROCESSES}}\n\n**Files and their exports (supplementary):**\n{{FILE_LIST}}\n\n**Directory structure (supplementary):**\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\n- Begin with a concise overview (2-4 sentences summarizing purpose). Place <!-- summary-end --> after this opening section.\n- Graph-derived call graphs and workflow diagrams are appended automatically -- do NOT replicate them\n- You may include additional conceptual Mermaid diagrams when they genuinely help understanding\n- When referencing other modules, use ONLY exact slugs from the module registry. Format: [Name](slug.md)";
+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## Other Modules (for cross-references)\n\n{{MODULE_REGISTRY}}\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\n- Begin with a concise overview (2-4 sentences summarizing purpose). Place <!-- summary-end --> after this opening section.\n- Cross-child call graphs are appended automatically -- do NOT replicate them\n- You may include additional conceptual Mermaid diagrams when they genuinely help understanding\n- When referencing other modules, use ONLY exact slugs from the module registry. Format: [Name](slug.md)";
+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## Other Modules (for cross-references)\n\n{{MODULE_REGISTRY}}\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\n- An architecture diagram is appended automatically -- do NOT replicate it\n- You may include additional conceptual Mermaid diagrams when they genuinely help understanding\n- When linking to modules, use ONLY exact slugs from the module registry. Format: [Name](slug.md)";
+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## Module Registry\n\n{{MODULE_REGISTRY}}\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.
  */
@@ -51,3 +53,45 @@ export declare function formatProcesses(processes: Array<{
         filePath: string;
     }>;
 }>): string;
+/**
+ * Shorten a file path for readability.
+ */
+export declare function shortPath(fp: string): string;
+/**
+ * Format community groups for the grouping prompt.
+ */
+export declare function formatCommunityGroups(groups: Array<{
+    label: string;
+    cohesion: number;
+    files: string[];
+    keywords: string[];
+}>): string;
+/**
+ * Format inter-community call edges for the grouping prompt.
+ */
+export declare function formatInterCommunityEdges(edges: Array<{
+    fromLabel: string;
+    toLabel: string;
+    callCount: number;
+    sampleCalls: Array<{
+        fromName: string;
+        toName: string;
+    }>;
+}>): string;
+/**
+ * Format cross-community processes for the grouping prompt.
+ */
+export declare function formatCrossCommunityProcesses(procs: Array<{
+    label: string;
+    communities: string[];
+    stepCount: number;
+}>): string;
+/**
+ * Format the module registry for injection into prompts.
+ * Shows all modules with their slugs and top symbols.
+ */
+export declare function formatModuleRegistry(registry: Map<string, {
+    name: string;
+    slug: string;
+    symbols: string[];
+}>, currentSlug?: string): string;

package/dist/core/wiki/prompts.js

@@ -5,98 +5,154 @@
  * Templates use {{PLACEHOLDER}} substitution.
  */
 // ─── Grouping Prompt ──────────────────────────────────────────────────
-export 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.
-
-Rules:
-- Each module should represent a cohesive feature, layer, or domain
-- Every file must appear in exactly one module
-- Module names should be human-readable (e.g. "Authentication", "Database Layer", "API Routes")
-- Aim for 5-15 modules for a typical project. Fewer for small projects, more for large ones
-- Group by functionality, not by file type or directory structure alone
+export const GROUPING_SYSTEM_PROMPT_LEGACY = `You are a documentation architect. Given a list of source files with their exported symbols, group them into logical documentation modules.
+
+Rules:
+- Each module should represent a cohesive feature, layer, or domain
+- Every file must appear in exactly one module
+- Module names should be human-readable (e.g. "Authentication", "Database Layer", "API Routes")
+- Aim for 5-15 modules for a typical project. Fewer for small projects, more for large ones
+- Group by functionality, not by file type or directory structure alone
 - Do NOT create modules for tests, configs, or non-source files`;
-export const GROUPING_USER_PROMPT = `Group these source files into documentation modules.
-
-**Files and their exports:**
-{{FILE_LIST}}
-
-**Directory structure:**
-{{DIRECTORY_TREE}}
-
-Respond with ONLY a JSON object mapping module names to file path arrays. No markdown, no explanation.
-Example format:
-{
-  "Authentication": ["src/auth/login.ts", "src/auth/session.ts"],
-  "Database": ["src/db/connection.ts", "src/db/models.ts"]
+export const GROUPING_USER_PROMPT_LEGACY = `Group these source files into documentation modules.
+
+**Files and their exports:**
+{{FILE_LIST}}
+
+**Directory structure:**
+{{DIRECTORY_TREE}}
+
+Respond with ONLY a JSON object mapping module names to file path arrays. No markdown, no explanation.
+Example format:
+{
+  "Authentication": ["src/auth/login.ts", "src/auth/session.ts"],
+  "Database": ["src/db/connection.ts", "src/db/models.ts"]
+}`;
+export const GROUPING_SYSTEM_PROMPT = `You are a documentation architect. Given a list of source files with their exported symbols AND graph-detected community clusters, group them into logical documentation modules.
+
+Rules:
+- Use the graph-detected communities as your PRIMARY signal for grouping
+- You may merge small communities, split large ones, or rename them for clarity
+- Every file must appear in exactly one module
+- Module names should be human-readable (e.g. "Authentication", "Database Layer", "API Routes")
+- Aim for 5-15 modules for a typical project. Fewer for small projects, more for large ones
+- Consider inter-community coupling and cross-community processes when deciding merges
+- Do NOT create modules for tests, configs, or non-source files`;
+export const GROUPING_USER_PROMPT = `Group these source files into documentation modules.
+
+**Graph-detected communities (primary signal):**
+{{COMMUNITY_GROUPS}}
+
+**Inter-community coupling:**
+{{INTER_COMMUNITY_EDGES}}
+
+**Cross-community execution flows:**
+{{CROSS_COMMUNITY_PROCESSES}}
+
+**Files and their exports (supplementary):**
+{{FILE_LIST}}
+
+**Directory structure (supplementary):**
+{{DIRECTORY_TREE}}
+
+Respond with ONLY a JSON object mapping module names to file path arrays. No markdown, no explanation.
+Example format:
+{
+  "Authentication": ["src/auth/login.ts", "src/auth/session.ts"],
+  "Database": ["src/db/connection.ts", "src/db/models.ts"]
 }`;
 // ─── Leaf Module Prompt ───────────────────────────────────────────────
-export const MODULE_SYSTEM_PROMPT = `You are a technical documentation writer. Write clear, developer-focused documentation for a code module.
-
-Rules:
-- 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)
-- Structure the document however makes sense for this module — there is no mandatory format
-- Write for a developer who needs to understand and contribute to this code`;
-export const MODULE_USER_PROMPT = `Write documentation for the **{{MODULE_NAME}}** module.
-
-## Source Code
-
-{{SOURCE_CODE}}
-
-## Call Graph & Execution Flows (reference for accuracy)
-
-Internal calls: {{INTRA_CALLS}}
-Outgoing calls: {{OUTGOING_CALLS}}
-Incoming calls: {{INCOMING_CALLS}}
-Execution flows: {{PROCESSES}}
-
----
-
+export const MODULE_SYSTEM_PROMPT = `You are a technical documentation writer. Write clear, developer-focused documentation for a code module.
+
+Rules:
+- 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)
+- Structure the document however makes sense for this module — there is no mandatory format
+- Write for a developer who needs to understand and contribute to this code
+- Begin with a concise overview (2-4 sentences summarizing purpose). Place <!-- summary-end --> after this opening section.
+- Graph-derived call graphs and workflow diagrams are appended automatically -- do NOT replicate them
+- You may include additional conceptual Mermaid diagrams when they genuinely help understanding
+- When referencing other modules, use ONLY exact slugs from the module registry. Format: [Name](slug.md)`;
+export const MODULE_USER_PROMPT = `Write documentation for the **{{MODULE_NAME}}** module.
+
+## Source Code
+
+{{SOURCE_CODE}}
+
+## Call Graph & Execution Flows (reference for accuracy)
+
+Internal calls: {{INTRA_CALLS}}
+Outgoing calls: {{OUTGOING_CALLS}}
+Incoming calls: {{INCOMING_CALLS}}
+Execution flows: {{PROCESSES}}
+
+## Other Modules (for cross-references)
+
+{{MODULE_REGISTRY}}
+
+---
+
 Write 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 — you decide the sections and headings. Include a Mermaid diagram only if it genuinely clarifies the architecture.`;
 // ─── Parent Module Prompt ─────────────────────────────────────────────
-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:
-- 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
-- Include a Mermaid diagram only if it genuinely clarifies how the sub-modules relate`;
-export const PARENT_USER_PROMPT = `Write documentation for the **{{MODULE_NAME}}** module, which contains these sub-modules:
-
-{{CHILDREN_DOCS}}
-
-Cross-module calls: {{CROSS_MODULE_CALLS}}
-Shared execution flows: {{CROSS_PROCESSES}}
-
----
-
+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:
+- 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
+- Include a Mermaid diagram only if it genuinely clarifies how the sub-modules relate
+- Begin with a concise overview (2-4 sentences summarizing purpose). Place <!-- summary-end --> after this opening section.
+- Cross-child call graphs are appended automatically -- do NOT replicate them
+- You may include additional conceptual Mermaid diagrams when they genuinely help understanding
+- When referencing other modules, use ONLY exact slugs from the module registry. Format: [Name](slug.md)`;
+export const PARENT_USER_PROMPT = `Write documentation for the **{{MODULE_NAME}}** module, which contains these sub-modules:
+
+{{CHILDREN_DOCS}}
+
+Cross-module calls: {{CROSS_MODULE_CALLS}}
+Shared execution flows: {{CROSS_PROCESSES}}
+
+## Other Modules (for cross-references)
+
+{{MODULE_REGISTRY}}
+
+---
+
 Write 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.`;
 // ─── Overview Prompt ──────────────────────────────────────────────────
-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:
-- 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
-- Do NOT create module index tables or list every module with descriptions — just link to module pages naturally within the text
-- Use the inter-module edges and execution flow data for accuracy, but do NOT dump them raw`;
-export const OVERVIEW_USER_PROMPT = `Write the overview page for this repository's wiki.
-
-## Project Info
-
-{{PROJECT_INFO}}
-
-## Module Summaries
-
-{{MODULE_SUMMARIES}}
-
-## Reference Data (for accuracy — do not reproduce verbatim)
-
-Inter-module call edges: {{MODULE_EDGES}}
-Key system flows: {{TOP_PROCESSES}}
-
----
-
+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:
+- 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
+- Do NOT create module index tables or list every module with descriptions — just link to module pages naturally within the text
+- Use the inter-module edges and execution flow data for accuracy, but do NOT dump them raw
+- An architecture diagram is appended automatically -- do NOT replicate it
+- You may include additional conceptual Mermaid diagrams when they genuinely help understanding
+- When linking to modules, use ONLY exact slugs from the module registry. Format: [Name](slug.md)`;
+export const OVERVIEW_USER_PROMPT = `Write the overview page for this repository's wiki.
+
+## Project Info
+
+{{PROJECT_INFO}}
+
+## Module Summaries
+
+{{MODULE_SUMMARIES}}
+
+## Reference Data (for accuracy — do not reproduce verbatim)
+
+Inter-module call edges: {{MODULE_EDGES}}
+Key system flows: {{TOP_PROCESSES}}
+
+## Module Registry
+
+{{MODULE_REGISTRY}}
+
+---
+
 Write 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.`;
 // ─── Template Substitution Helper ─────────────────────────────────────
 /**
@@ -168,7 +224,65 @@ export function formatProcesses(processes) {
 /**
  * Shorten a file path for readability.
  */
-function shortPath(fp) {
+export function shortPath(fp) {
     const parts = fp.replace(/\\/g, '/').split('/');
     return parts.length > 3 ? parts.slice(-3).join('/') : fp;
 }
+// ─── Community Formatting Helpers ────────────────────────────────────
+/**
+ * Format community groups for the grouping prompt.
+ */
+export function formatCommunityGroups(groups) {
+    if (groups.length === 0)
+        return 'No community data available.';
+    return groups
+        .map(g => {
+        const kwText = g.keywords.length > 0 ? `  Keywords: ${g.keywords.join(', ')}` : '';
+        const fileList = g.files.slice(0, 20).map(f => `    - ${f}`).join('\n');
+        const more = g.files.length > 20 ? `\n    ... and ${g.files.length - 20} more files` : '';
+        return `**${g.label}** (cohesion: ${g.cohesion.toFixed(2)}, ${g.files.length} files)\n${kwText}\n${fileList}${more}`;
+    })
+        .join('\n\n');
+}
+/**
+ * Format inter-community call edges for the grouping prompt.
+ */
+export function formatInterCommunityEdges(edges) {
+    if (edges.length === 0)
+        return 'No inter-community coupling detected.';
+    return edges
+        .slice(0, 20)
+        .map(e => {
+        const samples = e.sampleCalls.map(s => `${s.fromName} -> ${s.toName}`).join(', ');
+        return `${e.fromLabel} -> ${e.toLabel}: ${e.callCount} calls (${samples})`;
+    })
+        .join('\n');
+}
+/**
+ * Format cross-community processes for the grouping prompt.
+ */
+export function formatCrossCommunityProcesses(procs) {
+    if (procs.length === 0)
+        return 'No cross-community execution flows detected.';
+    return procs
+        .map(p => `"${p.label}" spans: ${p.communities.join(', ')} (${p.stepCount} steps)`)
+        .join('\n');
+}
+// ─── Module Registry Helper ──────────────────────────────────────────
+/**
+ * Format the module registry for injection into prompts.
+ * Shows all modules with their slugs and top symbols.
+ */
+export function formatModuleRegistry(registry, currentSlug) {
+    if (registry.size === 0)
+        return 'No module registry available.';
+    const lines = [];
+    for (const [, entry] of registry) {
+        if (entry.slug === currentSlug)
+            continue;
+        const symbols = entry.symbols.slice(0, 10).join(', ');
+        const symbolText = symbols ? ` — exports: ${symbols}` : '';
+        lines.push(`- [${entry.name}](${entry.slug}.md)${symbolText}`);
+    }
+    return lines.join('\n');
+}

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

@@ -16,7 +16,9 @@
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
  */
-export declare const initKuzu: (repoId: string, dbPath: string) => Promise<void>;
+export declare const initKuzu: (repoId: string, dbPath: string, opts?: {
+    pinned?: boolean;
+}) => Promise<void>;
 export declare const executeQuery: (repoId: string, cypher: string) => Promise<any[]>;
 /**
  * Execute a parameterized query on a specific repo's connection pool.

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

@@ -16,7 +16,7 @@ import fs from 'fs/promises';
 import kuzu from 'kuzu';
 const pool = new Map();
 /** Max repos in the pool (LRU eviction) */
-const MAX_POOL_SIZE = 5;
+const MAX_POOL_SIZE = 15;
 /** Idle timeout before closing a repo's connections */
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 /** Max connections per repo (caps concurrent queries per repo) */
@@ -36,7 +36,7 @@ function ensureIdleTimer() {
     idleTimer = setInterval(() => {
         const now = Date.now();
         for (const [repoId, entry] of pool) {
-            if (now - entry.lastUsed > IDLE_TIMEOUT_MS && entry.checkedOut === 0) {
+            if (!entry.pinned && now - entry.lastUsed > IDLE_TIMEOUT_MS && entry.checkedOut === 0) {
                 closeOne(repoId);
             }
         }
@@ -54,7 +54,7 @@ function evictLRU() {
     let oldestId = null;
     let oldestTime = Infinity;
     for (const [id, entry] of pool) {
-        if (entry.checkedOut === 0 && entry.lastUsed < oldestTime) {
+        if (!entry.pinned && entry.checkedOut === 0 && entry.lastUsed < oldestTime) {
             oldestTime = entry.lastUsed;
             oldestId = id;
         }
@@ -64,14 +64,26 @@ function evictLRU() {
     }
 }
 /**
- * Remove a repo from the pool without calling native close methods.
- *
- * KuzuDB's native .closeSync() triggers N-API destructor hooks that
- * segfault on Linux/macOS.  Pool databases are opened read-only, so
- * there is no WAL to flush — just deleting the pool entry and letting
- * the GC (or process exit) reclaim native resources is safe.
+ * Close all connections for a repo and remove it from the pool
  */
 function closeOne(repoId) {
+    const entry = pool.get(repoId);
+    if (!entry)
+        return;
+    for (const conn of entry.available) {
+        try {
+            conn.close();
+        }
+        catch (e) {
+            console.error('GitNexus [pool:close-conn]:', e instanceof Error ? e.message : e);
+        }
+    }
+    try {
+        entry.db.close();
+    }
+    catch (e) {
+        console.error('GitNexus [pool:close-db]:', e instanceof Error ? e.message : e);
+    }
     pool.delete(repoId);
 }
 /**
@@ -98,6 +110,20 @@ function createConnection(db) {
         restoreStdout();
     }
 }
+/**
+ * Load the FTS extension on a connection (best-effort, idempotent).
+ * Required before using QUERY_FTS_INDEX in search queries.
+ */
+async function loadFTSOnConnection(conn) {
+    try {
+        await conn.query('INSTALL fts');
+    }
+    catch { /* already installed */ }
+    try {
+        await conn.query('LOAD EXTENSION fts');
+    }
+    catch { /* already loaded or unavailable */ }
+}
 /** Query timeout in milliseconds */
 const QUERY_TIMEOUT_MS = 30_000;
 /** Waiter queue timeout in milliseconds */
@@ -108,7 +134,7 @@ const LOCK_RETRY_DELAY_MS = 2000;
  * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
  */
-export const initKuzu = async (repoId, dbPath) => {
+export const initKuzu = async (repoId, dbPath, opts) => {
     const existing = pool.get(repoId);
     if (existing) {
         existing.lastUsed = Date.now();
@@ -136,9 +162,11 @@ export const initKuzu = async (repoId, dbPath) => {
             // Pre-create a small pool of connections
             const available = [];
             for (let i = 0; i < INITIAL_CONNS_PER_REPO; i++) {
-                available.push(createConnection(db));
+                const conn = createConnection(db);
+                await loadFTSOnConnection(conn);
+                available.push(conn);
             }
-            pool.set(repoId, { db, available, checkedOut: 0, waiters: [], lastUsed: Date.now(), dbPath });
+            pool.set(repoId, { db, available, checkedOut: 0, waiters: [], lastUsed: Date.now(), dbPath, pinned: !!opts?.pinned });
             ensureIdleTimer();
             return;
         }
@@ -170,7 +198,10 @@ function checkout(entry) {
     const totalConns = entry.available.length + entry.checkedOut;
     if (totalConns < MAX_CONNS_PER_REPO) {
         entry.checkedOut++;
-        return Promise.resolve(createConnection(entry.db));
+        const conn = createConnection(entry.db);
+        // Load FTS on new connections (best-effort, don't block on failure)
+        loadFTSOnConnection(conn).catch(() => { });
+        return Promise.resolve(conn);
     }
     // At capacity — queue the caller with a timeout.
     return new Promise((resolve, reject) => {