@doquflow/server 0.2.0 → 0.3.0

package/dist/tools/ingest-source.js

@@ -0,0 +1,222 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ingestSource = ingestSource;
+const node_path_1 = __importDefault(require("node:path"));
+const filesystem_1 = require("../filesystem");
+/**
+ * Simple markdown-based entity extraction.
+ * Looks for patterns like:
+ * - **Entity:** or ### Entity Headers
+ * - Lists of concepts
+ * - Tool/component mentions
+ */
+function extractFromMarkdown(content) {
+    const lines = content.split("\n");
+    const entities = [];
+    const concepts = new Set();
+    const relationships = [];
+    // Extract first 500 chars as summary (non-empty)
+    const summary = content
+        .split("\n")
+        .filter((l) => l.trim().length > 0 && !l.startsWith("#") && !l.startsWith("```") && !l.startsWith("["))
+        .slice(0, 3)
+        .join(" ")
+        .substring(0, 500);
+    // Find headers (entities/concepts)
+    for (const line of lines) {
+        // ### Header → entity/concept
+        if (line.match(/^###\s+/)) {
+            const header = line.replace(/^###\s+/, "").trim();
+            if (header && !header.startsWith("[") && !header.startsWith("{")) {
+                entities.push({ name: header, type: "concept" });
+            }
+        }
+        // **bold text** → potential entity (but not arrays or JSON)
+        const boldMatches = line.matchAll(/\*\*([^*]+)\*\*/g);
+        for (const match of boldMatches) {
+            const text = match[1].trim();
+            // Skip if it looks like JSON or code
+            if (text.length > 2 &&
+                text.length < 100 &&
+                !text.includes("[") &&
+                !text.includes("{") &&
+                !text.includes('"') &&
+                !text.includes("`")) {
+                entities.push({ name: text, type: "entity" });
+            }
+        }
+    }
+    // Find relationship patterns like "X integrates Y" or "X depends on Y"
+    const relWords = [
+        { word: "integrates", rel: "integrates" },
+        { word: "depends on", rel: "depends_on" },
+        { word: "extends", rel: "extends" },
+        { word: "uses", rel: "uses" },
+        { word: "manages", rel: "manages" },
+    ];
+    for (const line of lines) {
+        for (const { word, rel } of relWords) {
+            const regex = new RegExp(`([A-Z][A-Za-z0-9_]+)\\s+${word}\\s+([A-Z][A-Za-z0-9_]+)`, "gi");
+            const matches = line.matchAll(regex);
+            for (const match of matches) {
+                relationships.push({ from: match[1], to: match[2], relation: rel });
+            }
+        }
+    }
+    // Collect concepts from lines containing "concept:", "pattern:", etc (skip arrays)
+    const conceptLines = lines.filter((l) => /concept|pattern|principle|approach/i.test(l) && !l.startsWith("[") && !l.startsWith("{"));
+    for (const line of conceptLines) {
+        const conceptMatch = line.match(/:\s*([^[\]{}"`.]+?)(?:\.|$)/);
+        if (conceptMatch) {
+            const concept = conceptMatch[1].trim();
+            if (concept && concept.length < 100) {
+                concepts.add(concept);
+            }
+        }
+    }
+    return {
+        summary,
+        entities: Array.from(new Set(entities.map((e) => JSON.stringify(e)))).map((s) => JSON.parse(s)),
+        concepts: Array.from(concepts),
+        relationships,
+    };
+}
+/**
+ * Convert a source document into a collection of wiki pages.
+ * For each distinct entity/concept, create a page.
+ */
+function generateWikiPages(sourceId, sourceTitle, extracted) {
+    const now = new Date().toISOString();
+    const pages = [];
+    // Create summary page (synthesis)
+    const summaryId = `source_${sourceId.replace(/[^a-z0-9]/gi, "_").toLowerCase()}`;
+    const summaryPage = {
+        id: summaryId,
+        title: `Source: ${sourceTitle}`,
+        category: "synthesis",
+        content: `# ${sourceTitle}\n\n${extracted.summary}\n\n## Key Entities\n\n${extracted.entities.map((e) => `- **${e.name}** (${e.type})`).join("\n")}`,
+        frontmatter: {
+            created_at: now,
+            updated_at: now,
+            sources: [sourceId],
+            tags: ["source", "ingested"],
+            inbound_links: [],
+            outbound_links: extracted.entities.map((e) => `entity_${e.name.replace(/[^a-z0-9]/gi, "_").toLowerCase()}`),
+        },
+    };
+    pages.push(summaryPage);
+    // Create entity pages
+    for (const entity of extracted.entities) {
+        const entityId = `entity_${entity.name.replace(/[^a-z0-9]/gi, "_").toLowerCase()}`;
+        const entityPage = {
+            id: entityId,
+            title: entity.name,
+            category: "entity",
+            content: `# ${entity.name}\n\n**Type:** ${entity.type}\n\n## Overview\n\nIntroduced in: ${sourceTitle}`,
+            frontmatter: {
+                created_at: now,
+                updated_at: now,
+                sources: [sourceId],
+                tags: [entity.type],
+                inbound_links: [summaryId],
+                outbound_links: [],
+            },
+        };
+        pages.push(entityPage);
+    }
+    // Create concept pages
+    for (const concept of extracted.concepts) {
+        const conceptId = `concept_${concept.replace(/[^a-z0-9]/gi, "_").toLowerCase()}`;
+        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.`,
+            frontmatter: {
+                created_at: now,
+                updated_at: now,
+                sources: [sourceId],
+                tags: ["concept"],
+                inbound_links: [summaryId],
+                outbound_links: [],
+            },
+        };
+        pages.push(conceptPage);
+    }
+    return pages;
+}
+async function ingestSource(input) {
+    try {
+        const projectPath = node_path_1.default.resolve(input.project_path);
+        const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+        const sourcesDir = node_path_1.default.join(docuDir, "sources");
+        const wikiDir = node_path_1.default.join(docuDir, "wiki");
+        // Read source file
+        const sourceFile = node_path_1.default.join(sourcesDir, input.source_filename);
+        const fileRead = await (0, filesystem_1.safeReadFile)(sourceFile);
+        if (fileRead.error) {
+            return {
+                source_id: input.source_filename,
+                summary: `Error reading source: ${fileRead.error}`,
+                pages_created: [],
+                pages_updated: [],
+                entities_discovered: [],
+                contradictions: [],
+            };
+        }
+        const sourceContent = fileRead.content ?? "";
+        const sourceTitle = input.source_filename.replace(".md", "");
+        // Extract information
+        const extracted = extractFromMarkdown(sourceContent);
+        // Generate wiki pages
+        const wikiPages = generateWikiPages(sourceTitle, sourceTitle, extracted);
+        // Write all pages
+        const pagesCreated = [];
+        for (const page of wikiPages) {
+            // Determine category subdirectory - use correct plural forms
+            const pluralMap = {
+                entity: "entities",
+                concept: "concepts",
+                timeline: "timelines",
+                synthesis: "syntheses",
+            };
+            const categoryDir = node_path_1.default.join(wikiDir, pluralMap[page.category] || page.category + "s");
+            await (0, filesystem_1.ensureDir)(categoryDir);
+            // Create page file with frontmatter
+            const frontmatterYaml = `---
+created_at: ${page.frontmatter.created_at}
+updated_at: ${page.frontmatter.updated_at}
+sources: ${JSON.stringify(page.frontmatter.sources)}
+tags: ${JSON.stringify(page.frontmatter.tags)}
+inbound_links: ${JSON.stringify(page.frontmatter.inbound_links)}
+outbound_links: ${JSON.stringify(page.frontmatter.outbound_links)}
+---
+`;
+            const pageContent = frontmatterYaml + "\n" + page.content;
+            const pageFile = node_path_1.default.join(categoryDir, `${page.id}.md`);
+            await (0, filesystem_1.writeFileAtomic)(pageFile, pageContent);
+            pagesCreated.push(page.id);
+        }
+        return {
+            source_id: sourceTitle,
+            summary: extracted.summary,
+            pages_created: pagesCreated,
+            pages_updated: [],
+            entities_discovered: extracted.entities.map((e) => e.name),
+            contradictions: [],
+        };
+    }
+    catch (e) {
+        return {
+            source_id: input.source_filename,
+            summary: `Ingest failed: ${e?.message ?? String(e)}`,
+            pages_created: [],
+            pages_updated: [],
+            entities_discovered: [],
+            contradictions: [],
+        };
+    }
+}

package/dist/tools/lint-wiki.js

@@ -0,0 +1,346 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintWiki = lintWiki;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function parsePageMetadata(content) {
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!frontmatterMatch) {
+        return { metadata: null, body: content };
+    }
+    const frontmatterStr = frontmatterMatch[1];
+    const body = frontmatterMatch[2];
+    const metadata = {
+        created_at: extractYamlField(frontmatterStr, "created_at") || new Date().toISOString(),
+        updated_at: extractYamlField(frontmatterStr, "updated_at") || new Date().toISOString(),
+        sources: parseYamlArray(frontmatterStr, "sources") || [],
+        tags: parseYamlArray(frontmatterStr, "tags") || [],
+        inbound_links: parseYamlArray(frontmatterStr, "inbound_links") || [],
+        outbound_links: parseYamlArray(frontmatterStr, "outbound_links") || [],
+    };
+    return { metadata, body };
+}
+function extractYamlField(yaml, field) {
+    const regex = new RegExp(`^${field}:\\s*(.+)$`, "m");
+    const match = yaml.match(regex);
+    return match ? match[1].trim() : null;
+}
+function parseYamlArray(yaml, field) {
+    const regex = new RegExp(`^${field}:\\s*\\[(.+)\\]$`, "m");
+    const match = yaml.match(regex);
+    if (!match)
+        return [];
+    return match[1].split(",").map((s) => s.trim().replace(/['"]/g, ""));
+}
+function extractLinks(content) {
+    const linkRegex = /\[([^\]]+)\]\(\.\/([^)]+)\)/g;
+    const links = [];
+    let match;
+    while ((match = linkRegex.exec(content)) !== null) {
+        links.push(match[2].replace(".md", ""));
+    }
+    return links;
+}
+function findOrphanPages(wikiPath, allPageIds) {
+    const issues = [];
+    for (const pageId of allPageIds) {
+        // Pages with no inbound links are orphans
+        const filePath = path.join(wikiPath, `${pageId}.md`);
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { metadata } = parsePageMetadata(content);
+        if (metadata && metadata.inbound_links.length === 0) {
+            issues.push({
+                type: "orphan",
+                page_id: pageId,
+                page_title: extractPageTitle(content),
+                severity: "medium",
+                detail: `Page has no inbound links from other wiki pages`,
+                suggestion: `Consider linking this page from related entity or concept pages, or remove if not needed.`,
+            });
+        }
+    }
+    return issues;
+}
+function findStalePages(wikiPath, allPageIds) {
+    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`);
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { metadata } = parsePageMetadata(content);
+        if (metadata) {
+            const updatedAt = new Date(metadata.updated_at);
+            if (updatedAt < thirtyDaysAgo) {
+                issues.push({
+                    type: "stale",
+                    page_id: pageId,
+                    page_title: extractPageTitle(content),
+                    severity: "low",
+                    detail: `Page last updated ${Math.floor((Date.now() - updatedAt.getTime()) / (24 * 60 * 60 * 1000))} days ago`,
+                    suggestion: `Consider reviewing and updating if new information is available.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+function findMissingReferences(wikiPath, allPageIds) {
+    const issues = [];
+    for (const pageId of allPageIds) {
+        const filePath = path.join(wikiPath, `${pageId}.md`);
+        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)) {
+                issues.push({
+                    type: "missing_ref",
+                    page_id: pageId,
+                    page_title: extractPageTitle(content),
+                    severity: "high",
+                    detail: `References non-existent page: ${link}`,
+                    suggestion: `Check if ${link} should be created or if the reference should be updated.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+function findMetadataGaps(wikiPath, allPageIds) {
+    const issues = [];
+    for (const pageId of allPageIds) {
+        const filePath = path.join(wikiPath, `${pageId}.md`);
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { metadata } = parsePageMetadata(content);
+        if (!metadata) {
+            issues.push({
+                type: "metadata_gap",
+                page_id: pageId,
+                page_title: extractPageTitle(content),
+                severity: "medium",
+                detail: `Page missing YAML frontmatter with metadata`,
+                suggestion: `Add frontmatter with created_at, updated_at, sources, tags, and links.`,
+            });
+        }
+        else {
+            if (!metadata.created_at || !metadata.updated_at) {
+                issues.push({
+                    type: "metadata_gap",
+                    page_id: pageId,
+                    page_title: extractPageTitle(content),
+                    severity: "low",
+                    detail: `Page missing timestamp metadata (created_at or updated_at)`,
+                    suggestion: `Ensure all pages have creation and update timestamps in frontmatter.`,
+                });
+            }
+            if (metadata.sources.length === 0) {
+                issues.push({
+                    type: "metadata_gap",
+                    page_id: pageId,
+                    page_title: extractPageTitle(content),
+                    severity: "low",
+                    detail: `Page has no source references`,
+                    suggestion: `Add source document references to improve traceability.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+function findContradictions(wikiPath) {
+    const issues = [];
+    const pageContents = new Map();
+    // Load all pages
+    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"))
+                continue;
+            const pageId = file.replace(".md", "");
+            const content = fs.readFileSync(path.join(categoryPath, file), "utf-8");
+            const title = extractPageTitle(content);
+            pageContents.set(pageId, { title, content });
+        }
+    }
+    // Look for contradiction patterns
+    const contradictionPatterns = [
+        { pattern: /should be|must be/i, opposite: /should not be|must not be/i },
+        { pattern: /recommended/i, opposite: /not recommended/i },
+        { pattern: /required/i, opposite: /optional/i },
+    ];
+    const contentArray = Array.from(pageContents.values()).map((p) => p.content);
+    for (let i = 0; i < contentArray.length; i++) {
+        for (let j = i + 1; j < contentArray.length; j++) {
+            for (const { pattern, opposite } of contradictionPatterns) {
+                if (pattern.test(contentArray[i]) && opposite.test(contentArray[j])) {
+                    const key1 = Array.from(pageContents.entries()).find(([, v]) => v.content === contentArray[i])?.[0];
+                    const key2 = Array.from(pageContents.entries()).find(([, v]) => v.content === contentArray[j])?.[0];
+                    if (key1 && key2) {
+                        issues.push({
+                            type: "contradiction",
+                            page_id: key1,
+                            page_title: pageContents.get(key1)?.title || key1,
+                            severity: "high",
+                            detail: `Potential contradiction with ${key2}`,
+                            suggestion: `Review both pages and resolve conflicting statements.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+function extractPageTitle(content) {
+    const match = content.match(/^#+\s+(.+)$/m);
+    return match ? match[1].trim() : "Untitled";
+}
+function calculateHealthScore(result) {
+    const { issues_found, total_pages } = result;
+    if (total_pages === 0)
+        return 100;
+    const issueWeights = {
+        high: 10,
+        medium: 5,
+        low: 2,
+    };
+    let penalty = 0;
+    for (const issue of issues_found) {
+        penalty += issueWeights[issue.severity];
+    }
+    const maxPenalty = total_pages * 10;
+    const score = Math.max(0, 100 - (penalty / maxPenalty) * 100);
+    return Math.round(score);
+}
+function generateRecommendations(result) {
+    const recommendations = [];
+    if (result.metrics.orphan_pages > 0) {
+        recommendations.push(`${result.metrics.orphan_pages} orphan pages found. Consider linking them or removing if outdated.`);
+    }
+    if (result.metrics.missing_refs > 0) {
+        recommendations.push(`${result.metrics.missing_refs} broken references found. Update or create missing pages.`);
+    }
+    if (result.metrics.stale_pages > 0) {
+        recommendations.push(`${result.metrics.stale_pages} pages not updated in 30+ days. Review and refresh content.`);
+    }
+    if (result.metrics.metadata_gaps > 0) {
+        recommendations.push(`${result.metrics.metadata_gaps} pages have metadata gaps. Add source references and timestamps.`);
+    }
+    if (result.metrics.contradictions > 0) {
+        recommendations.push(`${result.metrics.contradictions} potential contradictions found. Review and resolve.`);
+    }
+    if (result.health_score >= 90) {
+        recommendations.push("✓ Wiki is in excellent health! Continue maintaining current standards.");
+    }
+    else if (result.health_score >= 70) {
+        recommendations.push("Wiki health is good. Address high-severity issues to improve further.");
+    }
+    else if (result.health_score < 50) {
+        recommendations.push("⚠ Wiki needs maintenance. Prioritize fixing high-severity issues.");
+    }
+    return recommendations;
+}
+async function lintWiki(params) {
+    const { project_path, check_type = "all" } = params;
+    const wikiPath = path.join(project_path, ".docuflow", "wiki");
+    if (!fs.existsSync(wikiPath)) {
+        throw new Error(`Wiki not found at ${wikiPath}`);
+    }
+    // Collect all page IDs
+    const allPageIds = new Set();
+    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", ""));
+            }
+        }
+    }
+    // Run checks
+    let issues = [];
+    if (check_type === "all" || check_type === "orphans") {
+        issues.push(...findOrphanPages(wikiPath, allPageIds));
+    }
+    if (check_type === "all" || check_type === "contradictions") {
+        issues.push(...findContradictions(wikiPath));
+    }
+    if (check_type === "all" || check_type === "stale") {
+        issues.push(...findStalePages(wikiPath, allPageIds));
+    }
+    if (check_type === "all" || check_type === "metadata") {
+        issues.push(...findMissingReferences(wikiPath, allPageIds));
+        issues.push(...findMetadataGaps(wikiPath, allPageIds));
+    }
+    // Calculate metrics
+    const metrics = {
+        orphan_pages: issues.filter((i) => i.type === "orphan").length,
+        contradictions: issues.filter((i) => i.type === "contradiction").length,
+        stale_pages: issues.filter((i) => i.type === "stale").length,
+        missing_refs: issues.filter((i) => i.type === "missing_ref").length,
+        metadata_gaps: issues.filter((i) => i.type === "metadata_gap").length,
+    };
+    // Build result
+    const result = {
+        total_pages: allPageIds.size,
+        issues_found: issues,
+        metrics,
+        recommendations: [],
+        health_score: 0,
+    };
+    // Calculate health score and recommendations
+    result.health_score = calculateHealthScore(result);
+    result.recommendations = generateRecommendations(result);
+    // Append to log.md
+    const logPath = path.join(project_path, ".docuflow", "log.md");
+    if (fs.existsSync(logPath)) {
+        const timestamp = new Date().toISOString();
+        const logEntry = `\n## [${timestamp}] lint | Wiki lint check completed\n\n- Pages checked: ${result.total_pages}\n- Issues found: ${result.issues_found.length}\n- Health score: ${result.health_score}%\n- High severity: ${metrics.contradictions + metrics.missing_refs}\n`;
+        fs.appendFileSync(logPath, logEntry);
+    }
+    return result;
+}

package/dist/tools/list-wiki.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listWiki = listWiki;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const filesystem_1 = require("../filesystem");
+/**
+ * Parse frontmatter from markdown
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const yaml = match[1];
+    const result = {};
+    for (const line of yaml.split("\n")) {
+        if (!line.trim())
+            continue;
+        const [key, ...valueParts] = line.split(":");
+        const value = valueParts.join(":").trim();
+        try {
+            if (value.startsWith("[") || value.startsWith("{")) {
+                result[key.trim()] = JSON.parse(value);
+            }
+            else {
+                result[key.trim()] = value;
+            }
+        }
+        catch {
+            result[key.trim()] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Extract title from markdown
+ */
+function extractTitle(content) {
+    const match = content.match(/^#\s+(.+?)$/m);
+    return match ? match[1].trim() : "Untitled";
+}
+async function listWiki(input) {
+    try {
+        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 pages = [];
+        const categories = {};
+        // Build list of categories to scan
+        let categoriesToScan = ["entities", "concepts", "timelines", "syntheses"];
+        if (input.category) {
+            categoriesToScan = [`${input.category}s`];
+        }
+        // Scan each category
+        for (const categoryDir of categoriesToScan) {
+            const fullCategoryPath = node_path_1.default.join(wikiDir, categoryDir);
+            const category = categoryDir.replace("s", ""); // entities → entity
+            try {
+                const files = await promises_1.default.readdir(fullCategoryPath);
+                let categoryCount = 0;
+                for (const file of files) {
+                    if (!file.endsWith(".md"))
+                        continue;
+                    const filePath = node_path_1.default.join(fullCategoryPath, file);
+                    const read = await (0, filesystem_1.safeReadFile)(filePath);
+                    if (read.error || read.binary || !read.content)
+                        continue;
+                    const fm = parseFrontmatter(read.content);
+                    const title = extractTitle(read.content);
+                    const pageId = file.replace(".md", "");
+                    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(),
+                        sources: fm.sources ?? [],
+                        tags: fm.tags ?? [],
+                    });
+                    categoryCount++;
+                }
+                if (categoryCount > 0) {
+                    categories[category] = categoryCount;
+                }
+            }
+            catch (e) {
+                // Category directory may not exist yet
+            }
+        }
+        return {
+            total_pages: pages.length,
+            pages: pages.sort((a, b) => a.title.localeCompare(b.title)),
+            categories,
+        };
+    }
+    catch (e) {
+        return {
+            total_pages: 0,
+            pages: [],
+            categories: {},
+            error: e?.message ?? String(e),
+        };
+    }
+}