@doquflow/server 0.3.0 → 0.4.0

package/dist/extractor.js

@@ -48,6 +48,35 @@ const RE_PROCESS_ENV = /\bprocess\.env\.([A-Z_][A-Z0-9_]*)/g;
 const RE_DOTNET_ENV = /\bEnvironment\.GetEnvironmentVariable\(\s*["']([^"']+)["']/g;
 const RE_ICONFIG = /\bIConfiguration\b/g;
 const RE_APPSETTINGS = /\bappsettings(?:\.[A-Za-z0-9]+)?\.json\b/g;
+// ─── Go ─────────────────────────────────────────────────────────────────────
+// type FooBar struct | type FooBar interface
+const RE_GO_TYPE = /\btype\s+([A-Z]\w*)\s+(?:struct|interface)/g;
+// func FuncName( or func (recv *Type) MethodName(
+const RE_GO_FUNC = /\bfunc\s+(?:\([^)]+\)\s+)?([A-Za-z_]\w*)\s*\(/g;
+// import "pkg" or import ( "pkg" ) — individual quoted paths inside import blocks
+const RE_GO_IMPORT = /^\s+["']([^"'\s]+)["']\s*(?:\/\/.*)?$/gm;
+// os.Getenv("KEY") or os.LookupEnv("KEY")
+const RE_GO_ENV = /\bos\.(?:Getenv|LookupEnv)\s*\(\s*["']([A-Z_][A-Z0-9_]*)["']/g;
+// gorilla/mux, gin, chi, echo, stdlib: router.GET("/path", ...)
+const RE_GO_HTTP = /\b(?:r|router|e|mux|g|app)\s*\.\s*(?:HandleFunc|GET|POST|PUT|DELETE|PATCH|Handle|Any)\s*\(\s*["']([^"']+)["']/g;
+// GORM explicit table: db.Table("name")
+const RE_GO_GORM_TABLE = /\bdb\s*\.\s*Table\s*\(\s*["']([^"']+)["']/g;
+// ─── Ruby / Rails ────────────────────────────────────────────────────────────
+// class Foo or module Bar
+const RE_RUBY_CLASS = /\b(?:class|module)\s+([A-Z]\w*(?:::[A-Z]\w*)*)/g;
+// def method_name or def self.method_name
+const RE_RUBY_DEF = /^\s*def\s+(?:self\.)?([a-z_]\w*)/gm;
+// require 'gem' or require_relative '../path'
+const RE_RUBY_REQUIRE = /\brequire(?:_relative)?\s+["']([^"']+)["']/g;
+// ENV['KEY'] or ENV["KEY"]
+const RE_RUBY_ENV = /\bENV\s*\[\s*["']([A-Z_][A-Z0-9_]*)["']\s*\]/g;
+// Rails routes: get '/path', post '/path', resources :users, root 'home#index'
+const RE_RAILS_ROUTE = /^\s*(?:get|post|put|delete|patch|resources|resource|root)\s+["']([^"']+)["']/gm;
+// ActiveRecord associations: has_many :users, belongs_to :user
+const RE_AR_HAS = /\bhas_(?:many|one)\s+:(\w+)/g;
+const RE_AR_BELONGS = /\bbelongs_to\s+:(\w+)/g;
+// Explicit table name: self.table_name = 'table'
+const RE_AR_TABLE = /\bself\.table_name\s*=\s*["']([^"']+)["']/g;
 // SQL keywords and noise that the regex may pick up as table names.
 // Also strips single-letter hits (LINQ aliases: `from u in _db.Users` → u).
 const SQL_KEYWORD_NOISE = new Set([
@@ -77,11 +106,17 @@ function cleanTableNames(names) {
     });
 }
 function extract(content) {
-    const classes = collect(new RegExp(RE_CLASS.source, "g"), content);
+    const classes = uniq([
+        ...collect(new RegExp(RE_CLASS.source, "g"), content),
+        ...collect(new RegExp(RE_GO_TYPE.source, "g"), content),
+        ...collect(new RegExp(RE_RUBY_CLASS.source, "g"), content),
+    ]);
     const functions = uniq([
         ...collect(new RegExp(RE_FUNC_KW.source, "g"), content),
         ...collect(new RegExp(RE_FUNC_ARROW.source, "g"), content),
         ...collect(new RegExp(RE_METHOD_TS.source, "gm"), content),
+        ...collect(new RegExp(RE_GO_FUNC.source, "g"), content),
+        ...collect(new RegExp(RE_RUBY_DEF.source, "gm"), content),
     ]).filter((n) => !["if", "for", "while", "switch", "catch", "return", "function"].includes(n));
     const dependencies = uniq([
         ...collect(new RegExp(RE_USING.source, "g"), content),
@@ -89,6 +124,8 @@ function extract(content) {
         ...collect(new RegExp(RE_REQUIRE.source, "g"), content),
         ...collect(new RegExp(RE_DECORATOR.source, "g"), content),
         ...collect(new RegExp(RE_NEW_CLASS.source, "g"), content),
+        ...collect(new RegExp(RE_GO_IMPORT.source, "gm"), content),
+        ...collect(new RegExp(RE_RUBY_REQUIRE.source, "g"), content),
     ]);
     const db_tables = uniq(cleanTableNames([
         ...collect(new RegExp(RE_SQL_TABLE.source, "gi"), content),
@@ -96,6 +133,10 @@ function extract(content) {
         ...collect(new RegExp(RE_TABLE_ATTR.source, "g"), content),
         ...collect(new RegExp(RE_TABLE_FLUENT.source, "g"), content),
         ...collect(new RegExp(RE_EF_PROP.source, "g"), content),
+        ...collect(new RegExp(RE_GO_GORM_TABLE.source, "g"), content),
+        ...collect(new RegExp(RE_AR_HAS.source, "g"), content),
+        ...collect(new RegExp(RE_AR_BELONGS.source, "g"), content),
+        ...collect(new RegExp(RE_AR_TABLE.source, "g"), content),
     ]));
     const endpoints = uniq([
         ...collect(new RegExp(RE_DOTNET_ROUTE.source, "g"), content),
@@ -106,11 +147,15 @@ function extract(content) {
         ...collect(new RegExp(RE_FLASK.source, "g"), content),
         ...collect(new RegExp(RE_FASTAPI.source, "g"), content),
         ...collect(new RegExp(RE_DJANGO.source, "g"), content),
+        ...collect(new RegExp(RE_GO_HTTP.source, "g"), content),
+        ...collect(new RegExp(RE_RAILS_ROUTE.source, "gm"), content),
     ]);
     const config_refs = [];
     config_refs.push(...collect(new RegExp(RE_CFG_CONNSTR.source, "g"), content).map((s) => `ConnectionStrings:${s}`));
     config_refs.push(...collect(new RegExp(RE_PROCESS_ENV.source, "g"), content).map((s) => `process.env.${s}`));
     config_refs.push(...collect(new RegExp(RE_DOTNET_ENV.source, "g"), content));
+    config_refs.push(...collect(new RegExp(RE_GO_ENV.source, "g"), content).map((s) => `os.Getenv(${s})`));
+    config_refs.push(...collect(new RegExp(RE_RUBY_ENV.source, "g"), content).map((s) => `ENV[${s}]`));
     if (RE_ICONFIG.test(content))
         config_refs.push("IConfiguration");
     if (RE_APPSETTINGS.test(content))

package/dist/index.js

@@ -18,6 +18,7 @@ const save_answer_as_page_1 = require("./tools/save-answer-as-page");
 const lint_wiki_1 = require("./tools/lint-wiki");
 const get_schema_guidance_1 = require("./tools/get-schema-guidance");
 const preview_generation_1 = require("./tools/preview-generation");
+const generate_dependency_graph_1 = require("./tools/generate-dependency-graph");
 const server = new index_js_1.Server({ name: "docuflow", version: "0.1.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools: [
@@ -104,7 +105,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: "list_wiki",
-            description: "List all wiki pages in .docuflow/wiki/, optionally filtered by category. Returns metadata (title, created_at, sources, tags) and page counts by category.",
+            description: "List all wiki pages in .docuflow/wiki/, optionally filtered by category. Returns metadata (title, created_at, sources, tags, stale) and page counts by category. Pages not updated in 30+ days are flagged stale:true.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -240,6 +241,26 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                 required: ["tool_name", "project_path", "params"],
             },
         },
+        {
+            name: "generate_dependency_graph",
+            description: "Scan a project and build a dependency graph showing how modules import each other, which DB tables are shared, and which files are most connected. Returns nodes, edges, shared tables, and the top 10 most-connected modules. Use this to understand coupling and identify risky files to change.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_path: { type: "string", description: "Root directory of the project to analyse." },
+                    extensions: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional extension filter e.g. [\".ts\",\".go\"]. If omitted, all non-binary files are scanned.",
+                    },
+                    focus: {
+                        type: "string",
+                        description: "Optional: filter graph to neighbours of a specific file or module name (partial match, e.g. 'user-service').",
+                    },
+                },
+                required: ["project_path"],
+            },
+        },
     ],
 }));
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
@@ -288,6 +309,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         else if (name === "preview_generation") {
             result = await (0, preview_generation_1.previewGeneration)(args);
         }
+        else if (name === "generate_dependency_graph") {
+            result = await (0, generate_dependency_graph_1.generateDependencyGraph)(args);
+        }
         else {
             result = { error: `Unknown tool: ${name}` };
         }

package/dist/tools/generate-dependency-graph.js

@@ -0,0 +1,162 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDependencyGraph = generateDependencyGraph;
+const node_path_1 = __importDefault(require("node:path"));
+const list_modules_1 = require("./list-modules");
+async function generateDependencyGraph(input) {
+    try {
+        const projectPath = node_path_1.default.resolve(input.project_path);
+        // Scan all modules
+        const listResult = await (0, list_modules_1.listModules)({
+            path: projectPath,
+            extensions: input.extensions,
+        });
+        const modules = listResult.modules ?? [];
+        if (modules.length === 0) {
+            return {
+                nodes: [],
+                edges: [],
+                shared_tables: {},
+                shared_endpoints: {},
+                most_connected: [],
+                summary: "No source files found in the project.",
+            };
+        }
+        // Build id from relative path (normalised for use as node id)
+        const relPath = (filePath) => node_path_1.default.relative(projectPath, filePath).replace(/\\/g, "/");
+        // Build nodes map
+        const nodeMap = new Map();
+        for (const mod of modules) {
+            const id = relPath(mod.path);
+            nodeMap.set(id, {
+                id,
+                label: node_path_1.default.basename(mod.path),
+                language: mod.language,
+                classes: mod.classes.length,
+                functions: mod.functions.length,
+                db_tables: mod.db_tables,
+                endpoints: mod.endpoints,
+            });
+        }
+        // Build import edges: for each module's dependency list, look for matches in node IDs
+        const edges = [];
+        const edgeSet = new Set(); // avoid duplicates
+        for (const mod of modules) {
+            const fromId = relPath(mod.path);
+            for (const dep of mod.dependencies) {
+                // Try to resolve dep to a known node (relative path match or basename match)
+                for (const [nodeId] of nodeMap) {
+                    // Match if the dependency string is contained in the node path
+                    // (e.g., dep = "./user-service" matches "src/user-service.ts")
+                    const depNorm = dep.replace(/^[./]+/, "").replace(/\\/g, "/").toLowerCase();
+                    const nodeNorm = nodeId.replace(/\\/g, "/").toLowerCase();
+                    if (depNorm.length > 2 &&
+                        (nodeNorm.includes(depNorm) || nodeNorm.replace(/\.\w+$/, "").endsWith(depNorm))) {
+                        const key = `${fromId}->${nodeId}`;
+                        if (fromId !== nodeId && !edgeSet.has(key)) {
+                            edgeSet.add(key);
+                            edges.push({ from: fromId, to: nodeId, type: "imports" });
+                        }
+                    }
+                }
+            }
+        }
+        // Shared DB tables
+        const tableToModules = new Map();
+        for (const mod of modules) {
+            for (const table of mod.db_tables) {
+                const key = table.toLowerCase();
+                if (!tableToModules.has(key))
+                    tableToModules.set(key, []);
+                tableToModules.get(key).push(relPath(mod.path));
+            }
+        }
+        const shared_tables = {};
+        for (const [table, mods] of tableToModules) {
+            if (mods.length > 1) {
+                shared_tables[table] = mods;
+                // Add shared_table edges
+                for (let i = 0; i < mods.length; i++) {
+                    for (let j = i + 1; j < mods.length; j++) {
+                        const key = `${mods[i]}<>${mods[j]}:${table}`;
+                        if (!edgeSet.has(key)) {
+                            edgeSet.add(key);
+                            edges.push({ from: mods[i], to: mods[j], type: "shared_table" });
+                        }
+                    }
+                }
+            }
+        }
+        // Shared endpoints
+        const endpointToModules = new Map();
+        for (const mod of modules) {
+            for (const ep of mod.endpoints) {
+                if (!endpointToModules.has(ep))
+                    endpointToModules.set(ep, []);
+                endpointToModules.get(ep).push(relPath(mod.path));
+            }
+        }
+        const shared_endpoints = {};
+        for (const [ep, mods] of endpointToModules) {
+            if (mods.length > 1)
+                shared_endpoints[ep] = mods;
+        }
+        // Most connected nodes (by total edge count)
+        const connectionCount = new Map();
+        for (const edge of edges) {
+            connectionCount.set(edge.from, (connectionCount.get(edge.from) ?? 0) + 1);
+            connectionCount.set(edge.to, (connectionCount.get(edge.to) ?? 0) + 1);
+        }
+        const most_connected = Array.from(connectionCount.entries())
+            .map(([id, count]) => ({
+            id,
+            label: nodeMap.get(id)?.label ?? id,
+            connection_count: count,
+        }))
+            .sort((a, b) => b.connection_count - a.connection_count)
+            .slice(0, 10);
+        // Apply focus filter: if focus is set, only include nodes/edges reachable from it
+        let nodes = Array.from(nodeMap.values());
+        let filteredEdges = edges;
+        if (input.focus) {
+            const focusNorm = input.focus.toLowerCase();
+            const focusId = nodes.find((n) => n.id.toLowerCase().includes(focusNorm))?.id;
+            if (focusId) {
+                const reachable = new Set([focusId]);
+                // BFS: include direct neighbours
+                for (const e of edges) {
+                    if (e.from === focusId)
+                        reachable.add(e.to);
+                    if (e.to === focusId)
+                        reachable.add(e.from);
+                }
+                nodes = nodes.filter((n) => reachable.has(n.id));
+                filteredEdges = edges.filter((e) => reachable.has(e.from) && reachable.has(e.to));
+            }
+        }
+        const sharedTableCount = Object.keys(shared_tables).length;
+        const summary = [
+            `${nodes.length} modules, ${filteredEdges.length} dependencies`,
+            sharedTableCount > 0 ? `${sharedTableCount} shared DB table(s)` : null,
+            most_connected.length > 0
+                ? `Most connected: ${most_connected[0].label} (${most_connected[0].connection_count} links)`
+                : null,
+        ]
+            .filter(Boolean)
+            .join(" · ");
+        return {
+            nodes,
+            edges: filteredEdges,
+            shared_tables,
+            shared_endpoints,
+            most_connected,
+            summary,
+        };
+    }
+    catch (e) {
+        return { error: e?.message ?? String(e) };
+    }
+}

package/dist/tools/ingest-source.js

@@ -6,6 +6,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ingestSource = ingestSource;
 const node_path_1 = __importDefault(require("node:path"));
 const filesystem_1 = require("../filesystem");
+/**
+ * Find the first paragraph in the source that mentions the given name.
+ * Returns cleaned text (stripped of markdown syntax), up to 400 chars.
+ */
+function findContextParagraph(content, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`\\b${escaped}\\b`, "i");
+    const paragraphs = content.split(/\n{2,}/);
+    for (const para of paragraphs) {
+        if (!re.test(para))
+            continue;
+        const clean = para
+            .replace(/^#+\s*/gm, "")
+            .replace(/\*\*?([^*]+)\*\*?/g, "$1")
+            .replace(/`([^`]+)`/g, "$1")
+            .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+            .trim();
+        if (clean.length > 20)
+            return clean.substring(0, 400);
+    }
+    return null;
+}
 /**
  * Simple markdown-based entity extraction.
  * Looks for patterns like:
@@ -88,7 +110,7 @@ function extractFromMarkdown(content) {
  * Convert a source document into a collection of wiki pages.
  * For each distinct entity/concept, create a page.
  */
-function generateWikiPages(sourceId, sourceTitle, extracted) {
+function generateWikiPages(sourceId, sourceTitle, extracted, sourceContent) {
     const now = new Date().toISOString();
     const pages = [];
     // Create summary page (synthesis)
@@ -111,11 +133,15 @@ function generateWikiPages(sourceId, sourceTitle, extracted) {
     // Create entity pages
     for (const entity of extracted.entities) {
         const entityId = `entity_${entity.name.replace(/[^a-z0-9]/gi, "_").toLowerCase()}`;
+        const contextPara = findContextParagraph(sourceContent, entity.name);
+        const overview = contextPara
+            ? `${contextPara}\n\n*Introduced in: ${sourceTitle}*`
+            : `Introduced in: ${sourceTitle}`;
         const entityPage = {
             id: entityId,
             title: entity.name,
             category: "entity",
-            content: `# ${entity.name}\n\n**Type:** ${entity.type}\n\n## Overview\n\nIntroduced in: ${sourceTitle}`,
+            content: `# ${entity.name}\n\n**Type:** ${entity.type}\n\n## Overview\n\n${overview}`,
             frontmatter: {
                 created_at: now,
                 updated_at: now,
@@ -130,11 +156,15 @@ function generateWikiPages(sourceId, sourceTitle, extracted) {
     // Create concept pages
     for (const concept of extracted.concepts) {
         const conceptId = `concept_${concept.replace(/[^a-z0-9]/gi, "_").toLowerCase()}`;
+        const contextPara = findContextParagraph(sourceContent, concept);
+        const definition = contextPara
+            ? `${contextPara}\n\n*Introduced in: ${sourceTitle}*`
+            : `To be expanded with additional sources.\n\n*Introduced in: ${sourceTitle}*`;
         const conceptPage = {
             id: conceptId,
             title: concept,
             category: "concept",
-            content: `# ${concept}\n\n**Introduced in:** ${sourceTitle}\n\n## Definition\n\nTo be expanded with additional sources.`,
+            content: `# ${concept}\n\n## Definition\n\n${definition}`,
             frontmatter: {
                 created_at: now,
                 updated_at: now,
@@ -172,7 +202,7 @@ async function ingestSource(input) {
         // Extract information
         const extracted = extractFromMarkdown(sourceContent);
         // Generate wiki pages
-        const wikiPages = generateWikiPages(sourceTitle, sourceTitle, extracted);
+        const wikiPages = generateWikiPages(sourceTitle, sourceTitle, extracted, sourceContent);
         // Write all pages
         const pagesCreated = [];
         for (const page of wikiPages) {

package/dist/tools/lint-wiki.js

@@ -74,11 +74,9 @@ function extractLinks(content) {
     }
     return links;
 }
-function findOrphanPages(wikiPath, allPageIds) {
+function findOrphanPages(pageMap) {
     const issues = [];
-    for (const pageId of allPageIds) {
-        // Pages with no inbound links are orphans
-        const filePath = path.join(wikiPath, `${pageId}.md`);
+    for (const [pageId, filePath] of pageMap) {
         if (!fs.existsSync(filePath))
             continue;
         const content = fs.readFileSync(filePath, "utf-8");
@@ -96,11 +94,10 @@ function findOrphanPages(wikiPath, allPageIds) {
     }
     return issues;
 }
-function findStalePages(wikiPath, allPageIds) {
+function findStalePages(pageMap) {
     const issues = [];
     const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
-    for (const pageId of allPageIds) {
-        const filePath = path.join(wikiPath, `${pageId}.md`);
+    for (const [pageId, filePath] of pageMap) {
         if (!fs.existsSync(filePath))
             continue;
         const content = fs.readFileSync(filePath, "utf-8");
@@ -121,17 +118,16 @@ function findStalePages(wikiPath, allPageIds) {
     }
     return issues;
 }
-function findMissingReferences(wikiPath, allPageIds) {
+function findMissingReferences(pageMap) {
     const issues = [];
-    for (const pageId of allPageIds) {
-        const filePath = path.join(wikiPath, `${pageId}.md`);
+    for (const [pageId, filePath] of pageMap) {
         if (!fs.existsSync(filePath))
             continue;
         const content = fs.readFileSync(filePath, "utf-8");
         const { body } = parsePageMetadata(content);
         const links = extractLinks(body);
         for (const link of links) {
-            if (!allPageIds.has(link)) {
+            if (!pageMap.has(link)) {
                 issues.push({
                     type: "missing_ref",
                     page_id: pageId,
@@ -145,10 +141,9 @@ function findMissingReferences(wikiPath, allPageIds) {
     }
     return issues;
 }
-function findMetadataGaps(wikiPath, allPageIds) {
+function findMetadataGaps(pageMap) {
     const issues = [];
-    for (const pageId of allPageIds) {
-        const filePath = path.join(wikiPath, `${pageId}.md`);
+    for (const [pageId, filePath] of pageMap) {
         if (!fs.existsSync(filePath))
             continue;
         const content = fs.readFileSync(filePath, "utf-8");
@@ -289,32 +284,33 @@ async function lintWiki(params) {
     if (!fs.existsSync(wikiPath)) {
         throw new Error(`Wiki not found at ${wikiPath}`);
     }
-    // Collect all page IDs
-    const allPageIds = new Set();
+    // Collect all page IDs mapped to their full file paths
+    const pageMap = new Map();
     for (const categoryDir of fs.readdirSync(wikiPath)) {
         const categoryPath = path.join(wikiPath, categoryDir);
         if (!fs.statSync(categoryPath).isDirectory())
             continue;
         for (const file of fs.readdirSync(categoryPath)) {
             if (file.endsWith(".md")) {
-                allPageIds.add(file.replace(".md", ""));
+                const pageId = file.replace(".md", "");
+                pageMap.set(pageId, path.join(categoryPath, file));
             }
         }
     }
     // Run checks
     let issues = [];
     if (check_type === "all" || check_type === "orphans") {
-        issues.push(...findOrphanPages(wikiPath, allPageIds));
+        issues.push(...findOrphanPages(pageMap));
     }
     if (check_type === "all" || check_type === "contradictions") {
         issues.push(...findContradictions(wikiPath));
     }
     if (check_type === "all" || check_type === "stale") {
-        issues.push(...findStalePages(wikiPath, allPageIds));
+        issues.push(...findStalePages(pageMap));
     }
     if (check_type === "all" || check_type === "metadata") {
-        issues.push(...findMissingReferences(wikiPath, allPageIds));
-        issues.push(...findMetadataGaps(wikiPath, allPageIds));
+        issues.push(...findMissingReferences(pageMap));
+        issues.push(...findMetadataGaps(pageMap));
     }
     // Calculate metrics
     const metrics = {
@@ -326,7 +322,7 @@ async function lintWiki(params) {
     };
     // Build result
     const result = {
-        total_pages: allPageIds.size,
+        total_pages: pageMap.size,
         issues_found: issues,
         metrics,
         recommendations: [],

package/dist/tools/list-wiki.js

@@ -7,6 +7,19 @@ exports.listWiki = listWiki;
 const node_path_1 = __importDefault(require("node:path"));
 const promises_1 = __importDefault(require("node:fs/promises"));
 const filesystem_1 = require("../filesystem");
+const PLURAL_TO_SINGULAR = {
+    entities: "entity",
+    concepts: "concept",
+    timelines: "timeline",
+    syntheses: "synthesis",
+};
+const SINGULAR_TO_PLURAL = {
+    entity: "entities",
+    concept: "concepts",
+    timeline: "timelines",
+    synthesis: "syntheses",
+};
+const STALE_DAYS = 30;
 /**
  * Parse frontmatter from markdown
  */
@@ -49,15 +62,17 @@ async function listWiki(input) {
         const wikiDir = node_path_1.default.join(docuDir, "wiki");
         const pages = [];
         const categories = {};
-        // Build list of categories to scan
+        const now = Date.now();
+        // Build list of categories to scan — always use correct plural directory names
         let categoriesToScan = ["entities", "concepts", "timelines", "syntheses"];
         if (input.category) {
-            categoriesToScan = [`${input.category}s`];
+            const pluralDir = SINGULAR_TO_PLURAL[input.category] ?? `${input.category}s`;
+            categoriesToScan = [pluralDir];
         }
         // Scan each category
         for (const categoryDir of categoriesToScan) {
             const fullCategoryPath = node_path_1.default.join(wikiDir, categoryDir);
-            const category = categoryDir.replace("s", ""); // entities → entity
+            const category = PLURAL_TO_SINGULAR[categoryDir] ?? categoryDir;
             try {
                 const files = await promises_1.default.readdir(fullCategoryPath);
                 let categoryCount = 0;
@@ -71,15 +86,19 @@ async function listWiki(input) {
                     const fm = parseFrontmatter(read.content);
                     const title = extractTitle(read.content);
                     const pageId = file.replace(".md", "");
+                    const updatedAt = fm.updated_at ?? new Date().toISOString();
+                    const updatedMs = new Date(updatedAt).getTime();
+                    const stale = !isNaN(updatedMs) && (now - updatedMs) > STALE_DAYS * 86_400_000;
                     pages.push({
                         id: pageId,
                         title,
                         category,
                         path: node_path_1.default.relative(docuDir, filePath),
                         created_at: fm.created_at ?? new Date().toISOString(),
-                        updated_at: fm.updated_at ?? new Date().toISOString(),
+                        updated_at: updatedAt,
                         sources: fm.sources ?? [],
                         tags: fm.tags ?? [],
+                        stale,
                     });
                     categoryCount++;
                 }
@@ -93,6 +112,7 @@ async function listWiki(input) {
         }
         return {
             total_pages: pages.length,
+            stale_pages: pages.filter((p) => p.stale).length,
             pages: pages.sort((a, b) => a.title.localeCompare(b.title)),
             categories,
         };
@@ -100,6 +120,7 @@ async function listWiki(input) {
     catch (e) {
         return {
             total_pages: 0,
+            stale_pages: 0,
             pages: [],
             categories: {},
             error: e?.message ?? String(e),

package/dist/tools/preview-generation.js

@@ -5,6 +5,35 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.previewGeneration = previewGeneration;
 const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+async function countWikiPages(wikiDir) {
+    let total = 0;
+    for (const cat of ["entities", "concepts", "timelines", "syntheses"]) {
+        try {
+            const files = await promises_1.default.readdir(node_path_1.default.join(wikiDir, cat));
+            total += files.filter((f) => f.endsWith(".md")).length;
+        }
+        catch {
+            // directory may not exist
+        }
+    }
+    return total;
+}
+async function getSourceFileSize(sourcesDir, filename) {
+    try {
+        const stat = await promises_1.default.stat(node_path_1.default.join(sourcesDir, filename));
+        return stat.size;
+    }
+    catch {
+        return 0;
+    }
+}
+function predictPageCount(fileSizeBytes) {
+    // Rough heuristic: ~1 wiki page per 800 bytes of source
+    const low = Math.max(1, Math.floor(fileSizeBytes / 1200));
+    const high = Math.max(2, Math.ceil(fileSizeBytes / 600));
+    return `${low}–${high}`;
+}
 /**
  * preview_generation
  *
@@ -24,37 +53,45 @@ const node_path_1 = __importDefault(require("node:path"));
  */
 async function previewGeneration(input) {
     const projectPath = node_path_1.default.resolve(input.project_path);
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const wikiDir = node_path_1.default.join(docuDir, "wiki");
+    const sourcesDir = node_path_1.default.join(docuDir, "sources");
     const toolName = input.tool_name;
     const params = input.params;
-    // Define preview for each tool
-    const previews = {
-        ingest_source: (projectPath, params) => ({
+    // Read real wiki state upfront
+    const existingPageCount = await countWikiPages(wikiDir);
+    if (toolName === "ingest_source") {
+        const filename = params.source_filename ?? "";
+        const fileSize = await getSourceFileSize(sourcesDir, filename);
+        const predictedNew = predictPageCount(fileSize);
+        const sizeLabel = fileSize > 0 ? `${Math.round(fileSize / 1024)}KB` : "unknown size";
+        return {
             tool_name: "ingest_source",
             tool_description: "Process a new source and integrate it into the wiki",
             input_provided: params,
             predicted_actions: [
-                "✓ Read the source file(s)",
-                "✓ Extract entities and concepts",
-                "✓ Generate or update wiki pages",
-                "✓ Create cross-references",
-                "✓ Update index.md with new entities",
+                `✓ Read ${filename} (${sizeLabel})`,
+                "✓ Extract entities and concepts from markdown",
+                "✓ Generate wiki pages (one per entity/concept found)",
+                "✓ Create cross-references between pages",
+                "✓ Update index.md with new entries",
                 "✓ Append entry to log.md",
             ],
             predicted_outputs: [
                 {
                     type: "Wiki Pages",
-                    description: "5-20 new or updated wiki pages depending on source size",
-                    example: "entities/ServiceName.md, concepts/Pattern.md, syntheses/Integration.md",
+                    description: `Estimated ${predictedNew} new pages (wiki currently has ${existingPageCount})`,
+                    example: "entities/ServiceName.md, concepts/Pattern.md, syntheses/source_name.md",
                 },
                 {
                     type: "Index Update",
-                    description: "Updated index.md with new pages and metadata",
+                    description: "index.md gets new page entries with metadata",
                     example: "index.md entry with source, date, page count",
                 },
                 {
                     type: "Log Entry",
-                    description: "New line in log.md documenting the ingest",
-                    example: "[2026-04-17 14:23] ingest | source_name.md → 12 pages created, 5 updated",
+                    description: "log.md records this ingest",
+                    example: `[${new Date().toISOString().slice(0, 10)}] ingest | ${filename} → N pages created`,
                 },
             ],
             data_modified: true,
@@ -67,8 +104,10 @@ async function previewGeneration(input) {
             ],
             estimated_impact: "high",
             proceed_recommendation: "✓ Safe to proceed. Source will be integrated and wiki will grow. This is expected behavior.",
-        }),
-        query_wiki: (projectPath, params) => ({
+        };
+    }
+    if (toolName === "query_wiki") {
+        return {
             tool_name: "query_wiki",
             tool_description: "Search and synthesize answers from the wiki",
             input_provided: params,
@@ -81,8 +120,8 @@ async function previewGeneration(input) {
             predicted_outputs: [
                 {
                     type: "Answer",
-                    description: "Synthesized answer to your question",
-                    example: 'The system uses MCP protocol to communicate with tools...',
+                    description: `Synthesized answer from up to ${existingPageCount} wiki pages`,
+                    example: "The system uses MCP protocol to communicate with tools...",
                 },
                 {
                     type: "Source Pages",
@@ -92,15 +131,19 @@ async function previewGeneration(input) {
                 {
                     type: "Confidence",
                     description: "How well the question was answered (0-100)",
-                    example: "85 (good coverage, some gaps possible)",
+                    example: existingPageCount > 10 ? "85 (good coverage)" : "50 (sparse wiki — add more sources)",
                 },
             ],
             data_modified: false,
             files_affected: [],
             estimated_impact: "low",
-            proceed_recommendation: "✓ Safe to proceed. This is a read-only operation. No wiki data will be changed.",
-        }),
-        lint_wiki: (projectPath, params) => ({
+            proceed_recommendation: existingPageCount === 0
+                ? "⚠ Wiki is empty — ingest sources first for useful answers."
+                : "✓ Safe to proceed. This is a read-only operation. No wiki data will be changed.",
+        };
+    }
+    if (toolName === "lint_wiki") {
+        return {
             tool_name: "lint_wiki",
             tool_description: "Health check the wiki for issues",
             input_provided: params,
@@ -115,13 +158,13 @@ async function previewGeneration(input) {
             predicted_outputs: [
                 {
                     type: "Issues",
-                    description: "Potential problems found in the wiki",
-                    example: "5 orphan pages, 2 stale (>30 days), 3 broken references",
+                    description: `Scanning ${existingPageCount} wiki pages for problems`,
+                    example: "N orphan pages, N stale (>30 days), N broken references",
                 },
                 {
                     type: "Health Score",
                     description: "Overall wiki health (0-100)",
-                    example: "78/100 (Good, some maintenance recommended)",
+                    example: existingPageCount > 0 ? "Score will vary — run to find out" : "N/A (no pages yet)",
                 },
                 {
                     type: "Recommendations",
@@ -132,15 +175,18 @@ async function previewGeneration(input) {
             data_modified: false,
             files_affected: [],
             estimated_impact: "low",
-            proceed_recommendation: "✓ Safe to proceed. This is a read-only diagnostic. It will report issues but not fix them.",
-        }),
-        save_answer_as_page: (projectPath, params) => ({
+            proceed_recommendation: existingPageCount === 0
+                ? "⚠ Wiki is empty — nothing to lint yet. Ingest sources first."
+                : "✓ Safe to proceed. This is a read-only diagnostic. It will report issues but not fix them.",
+        };
+    }
+    if (toolName === "save_answer_as_page") {
+        return {
             tool_name: "save_answer_as_page",
             tool_description: "Save an answer as a new wiki page (enables knowledge compounding)",
             input_provided: params,
             predicted_actions: [
-                "✓ Extract the answer from conversation",
-                "✓ Create markdown file with frontmatter metadata",
+                "✓ Format the answer as markdown with frontmatter",
                 "✓ Place in appropriate category (synthesis or concept)",
                 "✓ Update index.md with new page",
                 "✓ Add log entry",
@@ -148,13 +194,13 @@ async function previewGeneration(input) {
             predicted_outputs: [
                 {
                     type: "New Wiki Page",
-                    description: "New markdown file in wiki/syntheses/ or wiki/concepts/",
-                    example: ".docuflow/wiki/syntheses/query_result_20260417.md",
+                    description: `New markdown file — wiki will have ${existingPageCount + 1} pages`,
+                    example: ".docuflow/wiki/syntheses/query_result_<date>.md",
                 },
                 {
                     type: "Metadata",
                     description: "YAML frontmatter with creation date, tags, sources",
-                    example: "created_at: 2026-04-17, sources: [5 pages], tags: [architecture]",
+                    example: `created_at: ${new Date().toISOString().slice(0, 10)}, tags: [synthesis]`,
                 },
             ],
             data_modified: true,
@@ -165,48 +211,18 @@ async function previewGeneration(input) {
             ],
             estimated_impact: "medium",
             proceed_recommendation: "✓ This compounds knowledge in your wiki! Proceed to file interesting discoveries.",
-        }),
-        lint_wiki_with_check: (projectPath, params) => ({
-            tool_name: "lint_wiki",
-            tool_description: "Run specific lint check on the wiki",
-            input_provided: params,
-            predicted_actions: [
-                `✓ Run ${params.check_type || "all"} lint checks`,
-                "✓ Analyze wiki for specific issues",
-                "✓ Generate targeted recommendations",
-            ],
-            predicted_outputs: [
-                {
-                    type: "Check Results",
-                    description: `Results for ${params.check_type || "all checks"}`,
-                    example: "5 issues found of this type",
-                },
-                {
-                    type: "Recommendations",
-                    description: "How to fix the issues",
-                    example: "Delete orphan pages, add missing references",
-                },
-            ],
-            data_modified: false,
-            files_affected: [],
-            estimated_impact: "low",
-            proceed_recommendation: "✓ Safe to proceed. This is diagnostic and won't modify wiki data.",
-        }),
-    };
-    // Get preview based on tool name
-    const previewFn = previews[toolName];
-    if (!previewFn) {
-        return {
-            tool_name: toolName,
-            tool_description: "Unknown tool",
-            input_provided: params,
-            predicted_actions: ["❌ Tool not found"],
-            predicted_outputs: [],
-            data_modified: false,
-            files_affected: [],
-            estimated_impact: "low",
-            proceed_recommendation: "❌ Unknown tool. Check tool name and try again.",
         };
     }
-    return previewFn(projectPath, params);
+    // Unknown tool fallback
+    return {
+        tool_name: toolName,
+        tool_description: "Unknown tool",
+        input_provided: params,
+        predicted_actions: ["❌ Tool not found"],
+        predicted_outputs: [],
+        data_modified: false,
+        files_affected: [],
+        estimated_impact: "low",
+        proceed_recommendation: "❌ Unknown tool. Check tool name and try again.",
+    };
 }

package/dist/tools/read-specs.js

@@ -7,6 +7,7 @@ exports.readSpecs = readSpecs;
 const node_path_1 = __importDefault(require("node:path"));
 const promises_1 = __importDefault(require("node:fs/promises"));
 const filesystem_1 = require("../filesystem");
+const STALE_DAYS = 30;
 async function readSpecs(input) {
     const projectPath = node_path_1.default.resolve(input.project_path);
     const docuDir = node_path_1.default.join(projectPath, ".docuflow");
@@ -20,12 +21,15 @@ async function readSpecs(input) {
         const needle = input.module_name.replace(/\.md$/i, "").toLowerCase();
         entries = entries.filter((s) => s.filename.replace(/\.md$/i, "").toLowerCase() === needle);
     }
+    const now = Date.now();
     const specs = [];
     for (const entry of entries) {
         const filePath = node_path_1.default.join(docuDir, "specs", entry.filename);
         try {
             const content = await promises_1.default.readFile(filePath, "utf8");
-            specs.push({ filename: entry.filename, written_at: entry.written_at, content });
+            const writtenMs = entry.written_at ? new Date(entry.written_at).getTime() : NaN;
+            const stale = !isNaN(writtenMs) && (now - writtenMs) > STALE_DAYS * 86_400_000;
+            specs.push({ filename: entry.filename, written_at: entry.written_at, stale, content });
         }
         catch {
             // spec entry exists in index but file missing — skip silently

package/dist/tools/save-answer-as-page.js

@@ -34,6 +34,12 @@ inbound_links: ${JSON.stringify([])}
 outbound_links: ${JSON.stringify(sources)}
 ---
 `;
+        const CATEGORY_DIR = {
+            synthesis: "syntheses",
+            entity: "entities",
+            concept: "concepts",
+            timeline: "timelines",
+        };
         // Build page content
         const pageContent = `${frontmatterYaml}
 # ${input.page_title}
@@ -49,7 +55,7 @@ ${input.answer}
 ## Related Pages
 
 ${sources.length > 0
-            ? sources.map((s) => `- [\`${s}\`](../CATEGORY/${s}.md)`).join("\n")
+            ? sources.map((s) => `- [\`${s}\`](../${CATEGORY_DIR[category] ?? category + "s"}/${s}.md)`).join("\n")
             : "No source pages linked."}
 
 ---

package/dist/tools/update-index.js

@@ -58,6 +58,12 @@ async function updateIndex(input) {
         // Scan all wiki pages
         const entries = [];
         const categories = ["entities", "concepts", "timelines", "syntheses"];
+        const PLURAL_TO_SINGULAR = {
+            entities: "entity",
+            concepts: "concept",
+            timelines: "timeline",
+            syntheses: "synthesis",
+        };
         for (const category of categories) {
             const categoryDir = node_path_1.default.join(wikiDir, category);
             try {
@@ -75,7 +81,7 @@ async function updateIndex(input) {
                     entries.push({
                         id: pageId,
                         title,
-                        category: category.replace("s", ""), // entities → entity
+                        category: PLURAL_TO_SINGULAR[category] ?? category.replace(/s$/, ""),
                         path: node_path_1.default.relative(docuDir, filePath),
                         created_at: fm.created_at ?? new Date().toISOString(),
                     });

package/dist/tools/wiki-search.js

@@ -93,10 +93,16 @@ async function wikiSearch(input) {
                 // Category may not exist
             }
         }
+        const PLURAL_TO_SINGULAR = {
+            entities: "entity",
+            concepts: "concept",
+            timelines: "timeline",
+            syntheses: "synthesis",
+        };
         // Second pass: search all pages
         for (const categoryDir of categoriesToScan) {
             const fullCategoryPath = node_path_1.default.join(wikiDir, categoryDir);
-            const category = categoryDir.replace("s", ""); // entities → entity
+            const category = PLURAL_TO_SINGULAR[categoryDir] ?? categoryDir.replace(/s$/, "");
             try {
                 const files = await promises_1.default.readdir(fullCategoryPath);
                 for (const file of files) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doquflow/server",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Docuflow MCP server — lets AI agents read codebases and persist living specs",
   "author": "Docuflow <hello@doquflows.dev>",
   "license": "MIT",