pi-para 0.6.7 → 0.7.1

package/dist/tools.js

@@ -1,799 +1,17 @@
-/**
- * Tool registrations — wiki tools for both pi's session agent and standalone mini-agent.
- *
- * Tool implementations are shared between both consumers. Only the registration
- * wrapper differs (pi.registerTool vs AgentTool).
- *
- * Factory functions (createXxxExecute) close over wikiDir and store — no ctx dependency.
- */
-import { StringEnum } from "@earendil-works/pi-ai";
+/** Tool registration composition for pi sessions and standalone mini-agents. */
 import { Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
-import { resolveSource, truncateSource, detectSourceType } from "./ingest.js";
-import { queryWiki as queryWikiLib, formatQueryResults, formatFreshness } from "./query.js";
-import { readPage, writePage, movePage, listPages, listPageSlugs, readIndex, writeIndex, readSchema, appendLog, gitCommit, rebuildIndex, PARA_CATEGORIES, } from "./wiki.js";
-import { validateFrontmatter, parseFrontmatter, CURRENT_SCHEMA_VERSION, migrateToLatest, } from "./frontmatter.js";
-import { extractWikilinks, autoLinkSlugs, syncFrontmatterLinks } from "./link-utils.js";
-import { normalizeTags, normalizeScopes } from "./tag-registry.js";
-import { redactSecrets } from "./redact.js";
-import { lintWiki } from "./lint.js";
-import { generateOverviewPrompt } from "./summarize.js";
-import { INGEST_PROMPT, QUERY_PROMPT, LINT_PROMPT, } from "./templates/prompts.js";
-import { enqueueWikiMaintenance } from "./scheduler/index.js";
-import { WIKI_TOOL_DESCRIPTIONS, WIKI_TOOL_SNIPPETS, getWikiToolGuidelines, } from "./wiki-tool-guidance.js";
-// -- Parameter schemas -------------------------------------------------------
-const PARA_ENUM = StringEnum(["projects", "areas", "resources", "archives"], { description: "PARA category" });
-const PARA_ENUM_NO_ARCHIVES = StringEnum(["projects", "areas", "resources"], { description: "PARA category (archives excluded for new content)" });
-const WikiIngestParams = Type.Object({
-    source: Type.String({ description: "URL, file path, or raw text to ingest" }),
-    sourceType: Type.Optional(StringEnum(["url", "file", "text"], {
-        description: "Source type (auto-detected if omitted)",
-    })),
-    category: Type.Optional(PARA_ENUM_NO_ARCHIVES),
-    scope: Type.Optional(Type.Array(Type.String(), { description: "Scope tags for the ingested content" })),
-});
-const WikiQueryParams = Type.Object({
-    query: Type.String({ description: "Natural language search query" }),
-    global: Type.Optional(Type.Boolean({ description: "Search all scopes, not just current project" })),
-    category: Type.Optional(PARA_ENUM),
-    limit: Type.Optional(Type.Number({ description: "Max results (default 10)" })),
-});
-const WikiEditSchema = Type.Object({
-    oldText: Type.String({ description: "Exact text to find in the page body" }),
-    newText: Type.String({ description: "Replacement text" }),
-});
-const WikiWritePageSchema = Type.Object({
-    category: PARA_ENUM,
-    slug: Type.String({ description: "Page slug (lowercase, hyphens)" }),
-    title: Type.String({ description: "Page title" }),
-    scope: Type.Array(Type.String(), { description: "Scope tags" }),
-    tags: Type.Array(Type.String(), { description: "Topic tags" }),
-    body: Type.String({ description: "Page body in markdown (wiki summary format)" }),
-    mode: StringEnum(["create", "replace", "append", "edit"], {
-        description: "Write mode: create new, replace existing, append to existing, or edit specific sections",
-    }),
-    edits: Type.Optional(Type.Array(WikiEditSchema, {
-        description: "For mode=edit: targeted text replacements (oldText→newText). Page must exist.",
-    })),
-});
-const WikiWriteParams = Type.Object({
-    pages: Type.Array(WikiWritePageSchema, {
-        description: "Pages to write or update",
-    }),
-    // DEPRECATED: indexContent is ignored. Index is auto-rebuilt from all pages on disk.
-    // Kept in schema to avoid breaking existing callers.
-    indexContent: Type.Optional(Type.String({ description: "Updated index.md content (full replacement)" })),
-    logSummary: Type.Optional(Type.String({ description: "One-line summary for log.md" })),
-});
-const WikiEditParams = Type.Object({
-    path: Type.String({ description: "Existing page path (e.g. 'resources/ssl-cert-gotchas')" }),
-    edits: Type.Array(WikiEditSchema, {
-        description: "Atomic exact text replacements. Every oldText must appear exactly once or no changes are written.",
-    }),
-    title: Type.Optional(Type.String({ description: "Optional replacement page title" })),
-    scope: Type.Optional(Type.Array(Type.String(), { description: "Optional replacement scope tags" })),
-    tags: Type.Optional(Type.Array(Type.String(), { description: "Optional replacement topic tags" })),
-    logSummary: Type.Optional(Type.String({ description: "One-line summary for log.md" })),
-});
-const WikiReadParams = Type.Object({
-    path: Type.String({
-        description: "Page path (e.g. 'projects/auth-refactor') or page title",
-    }),
-});
-const WikiMoveParams = Type.Object({
-    path: Type.String({
-        description: "Current page path (e.g. 'projects/auth-refactor')",
-    }),
-    to: PARA_ENUM,
-});
-const WikiLintParams = Type.Object({
-    autoFix: Type.Optional(Type.Boolean({ description: "Auto-fix simple issues (default true)" })),
-});
-const WikiMigrateParams = Type.Object({});
-const WikiSummarizeParams = Type.Object({
-    target: Type.String({
-        description: "Page path, category name (e.g. 'projects'), or 'all'",
-    }),
-    depth: Type.Optional(StringEnum(["brief", "detailed"], {
-        description: "Summary depth (default brief)",
-    })),
-});
-// -- Source resolution helpers -----------------------------------------------
-/** Resolve a page path like "projects/auth-refactor" into category + slug. */
-function parsePagePath(path) {
-    const parts = path.split("/");
-    if (parts.length === 2) {
-        const cat = parts[0];
-        if (PARA_CATEGORIES.includes(cat)) {
-            const slug = parts[1].replace(/\.md$/, "");
-            return { category: cat, slug };
-        }
-    }
-    return null;
-}
-// -- Factory: wiki_ingest execute --------------------------------------------
-function createIngestExecute(wikiDir, _store, getScope) {
-    return async (params) => {
-        const scope = getScope();
-        const resolved = await resolveSource(wikiDir, {
-            source: params.source,
-            sourceType: params.sourceType,
-            scope: params.scope,
-            category: params.category,
-        }, scope);
-        const categoryHint = resolved.categoryHint
-            ? `\nSuggested PARA category: ${resolved.categoryHint}`
-            : "";
-        // Assemble the tool result with instructions for the LLM
-        const toolResultText = [
-            INGEST_PROMPT,
-            "",
-            `Current scope: ${resolved.scopeName} (tags: ${resolved.scopeTags.join(", ")})`,
-            categoryHint,
-            resolved.rawPath ? `Raw source saved to: ${resolved.rawPath}` : "",
-            "",
-            "<wiki-schema>",
-            resolved.schema,
-            "</wiki-schema>",
-            "",
-            "<wiki-index>",
-            resolved.index,
-            "</wiki-index>",
-            "",
-            "<source-content>",
-            truncateSource(resolved.content),
-            "</source-content>",
-            "",
-            "Now analyze the source content and use wiki_write to create/update pages, update the index, and log the operation.",
-        ].join("\n");
-        return {
-            content: [{ type: "text", text: toolResultText }],
-            details: {
-                sourceType: resolved.sourceType,
-                rawPath: resolved.rawPath,
-                sourceLength: resolved.content.length,
-            },
-        };
-    };
-}
-// -- Factory: wiki_query execute ---------------------------------------------
-function createQueryExecute(_wikiDir, store, getScope, getGraphBoost) {
-    return async (params) => {
-        const scope = getScope();
-        const result = await queryWikiLib(store, {
-            query: params.query,
-            global: params.global,
-            category: params.category,
-            limit: params.limit,
-            graphBoost: getGraphBoost?.() ?? true,
-        }, scope);
-        if (result.results.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `No wiki pages found for "${params.query}". The wiki may not have content on this topic yet.`,
-                    },
-                ],
-                details: {
-                    resultCount: 0,
-                    scopeUsed: result.wasGlobal ? "global" : scope.name,
-                },
-            };
-        }
-        const formatted = formatQueryResults(result.results);
-        const toolResultText = [
-            QUERY_PROMPT,
-            "",
-            `Query: "${params.query}"`,
-            `Scope: ${result.wasGlobal ? "global (all scopes)" : scope.name}`,
-            `Results: ${result.results.length}`,
-            "",
-            formatted,
-        ].join("\n");
-        return {
-            content: [{ type: "text", text: toolResultText }],
-            details: {
-                resultCount: result.results.length,
-                scopeUsed: result.wasGlobal ? "global" : scope.name,
-            },
-        };
-    };
-}
-// -- Background maintenance --------------------------------------------------
-/**
- * Schedule index rebuild + QMD reindex after latency-sensitive edits.
- * Debounced per wiki directory and coordinated through the scheduler queue so
- * multiple Pi processes do not run the same maintenance task concurrently.
- */
-function scheduleWikiMaintenance(wikiDir, store, markDirty) {
-    enqueueWikiMaintenance(wikiDir, store, markDirty);
-}
-// -- Factory: wiki_write execute ---------------------------------------------
-function createWriteExecute(wikiDir, store, getScope, markDirty) {
-    return async (params) => {
-        const pagesWritten = [];
-        const pagesSkipped = [];
-        const now = new Date().toISOString();
-        const scope = getScope();
-        // Gather all existing slugs for auto-linking (slug-only readdir scan;
-        // reading/parsing every page here made wiki_write scale poorly)
-        const allSlugs = await listPageSlugs(wikiDir);
-        for (const pageSpec of params.pages) {
-            // Sanitize slug
-            const slug = pageSpec.slug
-                .toLowerCase()
-                .replace(/[^a-z0-9-]/g, "-")
-                .replace(/-+/g, "-")
-                .replace(/^-|-$/g, "");
-            if (!slug) {
-                continue; // skip invalid slugs
-            }
-            const existing = await readPage(wikiDir, pageSpec.category, slug);
-            const pagePath = `${pageSpec.category}/${slug}`;
-            // Track this slug for auto-linking other pages in this batch
-            allSlugs.add(slug);
-            if (pageSpec.mode === "create" && existing) {
-                pagesSkipped.push(`${pagePath} (already exists; use mode=replace, mode=append, or wiki_edit)`);
-                continue;
-            }
-            if (pageSpec.mode === "edit" && !existing) {
-                pagesSkipped.push(`${pagePath} (missing; wiki_write mode=edit requires an existing page)`);
-                continue;
-            }
-            if (pageSpec.mode === "edit" && existing) {
-                // Legacy edit mode: keep for compatibility, but make it atomic like wiki_edit.
-                const edits = pageSpec.edits ?? [];
-                if (edits.length === 0) {
-                    continue; // no edits to apply
-                }
-                const errors = [];
-                for (const edit of edits) {
-                    const first = existing.body.indexOf(edit.oldText);
-                    const last = existing.body.lastIndexOf(edit.oldText);
-                    if (first === -1) {
-                        errors.push(`oldText not found: "${edit.oldText.slice(0, 60)}..."`);
-                    }
-                    else if (first !== last) {
-                        errors.push(`oldText is not unique: "${edit.oldText.slice(0, 60)}..."`);
-                    }
-                }
-                if (errors.length > 0) {
-                    pagesSkipped.push(`${pagePath} (${errors.join("; ")})`);
-                    continue;
-                }
-                let editedBody = existing.body;
-                for (const edit of edits) {
-                    editedBody = editedBody.replace(edit.oldText, edit.newText);
-                }
-                const linkedBody = redactSecrets(autoLinkSlugs(editedBody, allSlugs, slug)).text;
-                const rawScope = pageSpec.scope.length > 0 ? pageSpec.scope : existing.frontmatter.scope;
-                const newScope = normalizeScopes(rawScope);
-                const newTags = pageSpec.tags.length > 0 ? pageSpec.tags : existing.frontmatter.tags;
-                const updatedPage = {
-                    category: pageSpec.category,
-                    slug,
-                    frontmatter: {
-                        ...existing.frontmatter,
-                        title: pageSpec.title || existing.frontmatter.title,
-                        scope: newScope,
-                        tags: normalizeTags(newTags, newScope),
-                        updated: now,
-                        links: syncFrontmatterLinks(linkedBody),
-                    },
-                    body: linkedBody,
-                };
-                await writePage(wikiDir, updatedPage);
-                pagesWritten.push(pagePath + (errors.length > 0 ? ` (${errors.length} edit(s) failed)` : ""));
-            }
-            else if (pageSpec.mode === "append" && existing) {
-                // Append to existing page body
-                const combinedBody = existing.body.trimEnd() + "\n\n" + pageSpec.body;
-                const linkedBody = redactSecrets(autoLinkSlugs(combinedBody, allSlugs, slug)).text;
-                const mergedTags = [...new Set([...existing.frontmatter.tags, ...pageSpec.tags])];
-                const mergedScope = normalizeScopes([...new Set([...existing.frontmatter.scope, ...pageSpec.scope])]);
-                const updatedPage = {
-                    ...existing,
-                    body: linkedBody,
-                    frontmatter: {
-                        ...existing.frontmatter,
-                        updated: now,
-                        tags: normalizeTags(mergedTags, mergedScope),
-                        scope: mergedScope,
-                        links: syncFrontmatterLinks(linkedBody),
-                    },
-                };
-                await writePage(wikiDir, updatedPage);
-                pagesWritten.push(pagePath);
-            }
-            else if (pageSpec.mode === "replace" && existing) {
-                // Replace existing page body, update frontmatter
-                const linkedBody = redactSecrets(autoLinkSlugs(pageSpec.body, allSlugs, slug)).text;
-                const rawScope = pageSpec.scope.length > 0 ? pageSpec.scope : existing.frontmatter.scope;
-                const newScope = normalizeScopes(rawScope);
-                const newTags = pageSpec.tags.length > 0 ? pageSpec.tags : existing.frontmatter.tags;
-                const updatedPage = {
-                    category: pageSpec.category,
-                    slug,
-                    frontmatter: {
-                        ...existing.frontmatter,
-                        title: pageSpec.title,
-                        para: pageSpec.category,
-                        scope: newScope,
-                        tags: normalizeTags(newTags, newScope),
-                        updated: now,
-                        links: syncFrontmatterLinks(linkedBody),
-                    },
-                    body: linkedBody,
-                };
-                await writePage(wikiDir, updatedPage);
-                pagesWritten.push(pagePath);
-            }
-            else {
-                // Create new page (or mode=create/replace on non-existing)
-                const linkedBody = redactSecrets(autoLinkSlugs(pageSpec.body, allSlugs, slug)).text;
-                const rawScope = pageSpec.scope.length > 0 ? pageSpec.scope : [scope.name];
-                const newScope = normalizeScopes(rawScope);
-                const frontmatter = validateFrontmatter({
-                    title: pageSpec.title,
-                    para: pageSpec.category,
-                    scope: newScope,
-                    tags: normalizeTags(pageSpec.tags, newScope),
-                    sources: [],
-                    created: now,
-                    updated: now,
-                    links: syncFrontmatterLinks(linkedBody),
-                });
-                const newPage = {
-                    category: pageSpec.category,
-                    slug,
-                    frontmatter,
-                    body: linkedBody,
-                };
-                await writePage(wikiDir, newPage);
-                pagesWritten.push(pagePath);
-            }
-        }
-        // Always auto-rebuild index from disk.
-        // The LLM's indexContent is unreliable — it only knows about pages
-        // in its context, so it produces partial indexes that overwrite
-        // the full one. indexContent parameter is deprecated and ignored.
-        let indexUpdated = false;
-        if (pagesWritten.length > 0) {
-            await rebuildIndex(wikiDir);
-            indexUpdated = true;
-        }
-        // Append to log.md if summary provided
-        let logAppended = false;
-        if (params.logSummary && pagesWritten.length > 0) {
-            await appendLog(wikiDir, {
-                date: now.split("T")[0],
-                operation: "ingest",
-                summary: params.logSummary,
-                pages: pagesWritten,
-            });
-            logAppended = true;
-        }
-        // Defer QMD BM25 reindex to the debounced background maintenance queue
-        // (same as wiki_edit). Immediate post-write queries are safe: queryWiki
-        // retries with a fresh store.update() before returning zero results.
-        if (pagesWritten.length > 0) {
-            scheduleWikiMaintenance(wikiDir, store, markDirty);
-        }
-        // Mark context cache dirty so before_agent_start rebuilds
-        markDirty();
-        // Git auto-commit
-        if (pagesWritten.length > 0) {
-            const commitMsg = params.logSummary
-                ? params.logSummary
-                : `wiki: ${pagesWritten.join(", ")}`;
-            await gitCommit(wikiDir, commitMsg);
-        }
-        const summary = [
-            pagesWritten.length > 0
-                ? `Wrote ${pagesWritten.length} page(s): ${pagesWritten.join(", ")}`
-                : "No pages written.",
-            pagesSkipped.length > 0 ? `Skipped ${pagesSkipped.length} page(s): ${pagesSkipped.join(", ")}` : "",
-        ].filter(Boolean).join("\n");
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: [
-                        summary,
-                        indexUpdated ? "Updated index.md." : "",
-                        logAppended ? `Logged: ${params.logSummary}` : "",
-                    ]
-                        .filter(Boolean)
-                        .join("\n"),
-                },
-            ],
-            details: {
-                pagesWritten,
-                indexUpdated,
-                logAppended,
-                pagesSkipped,
-            },
-        };
-    };
-}
-// -- Factory: wiki_read execute ----------------------------------------------
-function createEditExecute(wikiDir, store, markDirty) {
-    return async (params) => {
-        const parsed = parsePagePath(params.path);
-        if (!parsed) {
-            return {
-                content: [{ type: "text", text: `Invalid page path: ${params.path}` }],
-                details: { pagesWritten: [], pagesSkipped: [params.path], indexUpdated: false, logAppended: false },
-            };
-        }
-        const existing = await readPage(wikiDir, parsed.category, parsed.slug);
-        const pagePath = `${parsed.category}/${parsed.slug}`;
-        if (!existing) {
-            return {
-                content: [{ type: "text", text: `Page not found: ${pagePath}` }],
-                details: { pagesWritten: [], pagesSkipped: [pagePath], indexUpdated: false, logAppended: false },
-            };
-        }
-        if (params.edits.length === 0) {
-            return {
-                content: [{ type: "text", text: "No edits supplied." }],
-                details: { pagesWritten: [], pagesSkipped: [pagePath], indexUpdated: false, logAppended: false },
-            };
-        }
-        // Atomic validation: all oldText strings must exist exactly once before writing.
-        const errors = [];
-        for (const edit of params.edits) {
-            const first = existing.body.indexOf(edit.oldText);
-            const last = existing.body.lastIndexOf(edit.oldText);
-            if (first === -1) {
-                errors.push(`oldText not found: "${edit.oldText.slice(0, 60)}..."`);
-            }
-            else if (first !== last) {
-                errors.push(`oldText is not unique: "${edit.oldText.slice(0, 60)}..."`);
-            }
-        }
-        if (errors.length > 0) {
-            return {
-                content: [{ type: "text", text: `No changes written.\n${errors.join("\n")}` }],
-                details: { pagesWritten: [], pagesSkipped: [pagePath], indexUpdated: false, logAppended: false },
-            };
-        }
-        let editedBody = existing.body;
-        for (const edit of params.edits) {
-            editedBody = editedBody.replace(edit.oldText, edit.newText);
-        }
-        // Surgical edit path: do not scan/autolink/rebuild/reindex the whole wiki.
-        // wiki_edit is often called mid-task and must stay fast; broader maintenance
-        // can run via wiki_lint/rebuildIndex or on startup.
-        const linkedBody = redactSecrets(editedBody).text;
-        const now = new Date().toISOString();
-        const rawScope = params.scope ?? existing.frontmatter.scope;
-        const newScope = normalizeScopes(rawScope);
-        const rawTags = params.tags ?? existing.frontmatter.tags;
-        const updatedPage = {
-            category: parsed.category,
-            slug: parsed.slug,
-            frontmatter: {
-                ...existing.frontmatter,
-                title: params.title ?? existing.frontmatter.title,
-                scope: newScope,
-                tags: normalizeTags(rawTags, newScope),
-                updated: now,
-                links: syncFrontmatterLinks(linkedBody),
-            },
-            body: linkedBody,
-        };
-        await writePage(wikiDir, updatedPage);
-        if (params.logSummary) {
-            await appendLog(wikiDir, {
-                date: now.split("T")[0],
-                operation: "edit",
-                summary: params.logSummary,
-                pages: [pagePath],
-            });
-        }
-        markDirty();
-        await gitCommit(wikiDir, params.logSummary ?? `wiki_edit: ${pagePath}`);
-        scheduleWikiMaintenance(wikiDir, store, markDirty);
-        return {
-            content: [{ type: "text", text: `Edited ${pagePath}. Scheduled background index/search refresh.` }],
-            details: {
-                pagesWritten: [pagePath],
-                pagesSkipped: [],
-                indexUpdated: false,
-                logAppended: !!params.logSummary,
-            },
-        };
-    };
-}
-function createReadExecute(wikiDir) {
-    return async (params) => {
-        const now = Date.now();
-        const normalizedPath = params.path.trim().toLowerCase().replace(/^\/+/, "");
-        if (normalizedPath === "index" || normalizedPath === "index.md" || normalizedPath === "wiki-index") {
-            const index = await readIndex(wikiDir);
-            return {
-                content: [{ type: "text", text: index }],
-                details: { found: true, path: "index.md" },
-            };
-        }
-        // Try parsing as category/slug path
-        const parsed = parsePagePath(params.path);
-        if (parsed) {
-            const page = await readPage(wikiDir, parsed.category, parsed.slug);
-            if (page) {
-                const fm = page.frontmatter;
-                const freshness = formatFreshness(fm.updated, now);
-                const header = [
-                    `# ${fm.title}`,
-                    `PARA: ${fm.para} | Scope: ${fm.scope.join(", ")} | Tags: ${fm.tags.join(", ")}`,
-                    `Created: ${fm.created} | Updated: ${fm.updated} | ${freshness}`,
-                    fm.sources.length > 0 ? `Sources: ${fm.sources.join(", ")}` : "",
-                    fm.links.length > 0 ? `Links: ${fm.links.map((l) => `[[${l}]]`).join(", ")}` : "",
-                ]
-                    .filter(Boolean)
-                    .join("\n");
-                return {
-                    content: [{ type: "text", text: `${header}\n\n${page.body}` }],
-                    details: { found: true, path: `${parsed.category}/${parsed.slug}` },
-                };
-            }
-        }
-        // Try finding by title (case-insensitive search across all pages)
-        const allPages = await listPages(wikiDir);
-        const titleLower = params.path.toLowerCase();
-        for (const ref of allPages) {
-            if (ref.title.toLowerCase() === titleLower || ref.slug === titleLower) {
-                const page = await readPage(wikiDir, ref.category, ref.slug);
-                if (page) {
-                    const fm = page.frontmatter;
-                    const freshness = formatFreshness(fm.updated, now);
-                    const header = [
-                        `# ${fm.title}`,
-                        `PARA: ${fm.para} | Scope: ${fm.scope.join(", ")} | Tags: ${fm.tags.join(", ")}`,
-                        `Created: ${fm.created} | Updated: ${fm.updated} | ${freshness}`,
-                        fm.sources.length > 0 ? `Sources: ${fm.sources.join(", ")}` : "",
-                        fm.links.length > 0 ? `Links: ${fm.links.map((l) => `[[${l}]]`).join(", ")}` : "",
-                    ]
-                        .filter(Boolean)
-                        .join("\n");
-                    return {
-                        content: [{ type: "text", text: `${header}\n\n${page.body}` }],
-                        details: { found: true, path: `${ref.category}/${ref.slug}` },
-                    };
-                }
-            }
-        }
-        return {
-            content: [{ type: "text", text: `Page not found: "${params.path}"` }],
-            details: { found: false },
-        };
-    };
-}
-// -- Factory: wiki_move execute ----------------------------------------------
-function createMoveExecute(wikiDir, store, markDirty) {
-    return async (params) => {
-        const parsed = parsePagePath(params.path);
-        if (!parsed) {
-            throw new Error(`Invalid page path: "${params.path}". Expected format: category/slug`);
-        }
-        const page = await readPage(wikiDir, parsed.category, parsed.slug);
-        if (!page) {
-            throw new Error(`Page not found: "${params.path}"`);
-        }
-        if (parsed.category === params.to) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Page "${params.path}" is already in ${params.to}. No move needed.`,
-                    },
-                ],
-                details: { from: params.path, to: `${params.to}/${parsed.slug}` },
-            };
-        }
-        const ref = {
-            category: parsed.category,
-            slug: parsed.slug,
-            title: page.frontmatter.title,
-            path: `${parsed.category}/${parsed.slug}.md`,
-        };
-        await movePage(wikiDir, ref, params.to);
-        // Rebuild index.md inline (fast, single-pass); defer QMD reindex to the
-        // debounced background maintenance queue like wiki_write/wiki_edit.
-        await rebuildIndex(wikiDir);
-        scheduleWikiMaintenance(wikiDir, store, markDirty);
-        markDirty();
-        // Git commit
-        await gitCommit(wikiDir, `move: ${page.frontmatter.title} → ${params.to}`);
-        // Log the move
-        const now = new Date().toISOString();
-        await appendLog(wikiDir, {
-            date: now.split("T")[0],
-            operation: "move",
-            summary: `Moved ${page.frontmatter.title} from ${parsed.category} to ${params.to}`,
-            pages: [`${params.to}/${parsed.slug}`],
-        });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Moved "${page.frontmatter.title}" from ${parsed.category}/ to ${params.to}/`,
-                },
-            ],
-            details: {
-                from: `${parsed.category}/${parsed.slug}`,
-                to: `${params.to}/${parsed.slug}`,
-            },
-        };
-    };
-}
-// -- Factory: wiki_lint execute ----------------------------------------------
-function createLintExecute(wikiDir, store, markDirty, getLintConfig) {
-    return async (params) => {
-        const configured = getLintConfig?.();
-        const report = await lintWiki(wikiDir, {
-            autoFix: params.autoFix ?? configured?.autoFix ?? true,
-            staleDays: configured?.staleDays ?? 90,
-        });
-        if (report.fixed.length > 0) {
-            scheduleWikiMaintenance(wikiDir, store, markDirty);
-        }
-        const { issues, fixed, stats } = report;
-        // Format report for the LLM
-        const parts = [];
-        parts.push("## Wiki Lint Report\n");
-        parts.push(`Total pages: ${stats.totalPages}`);
-        parts.push(`By category: ${PARA_CATEGORIES.map((c) => `${c}: ${stats.byCategory[c]}`).join(", ")}`);
-        parts.push(`Total links: ${stats.totalLinks} (broken: ${stats.brokenLinks})`);
-        parts.push(`Orphan pages: ${stats.orphanPages}`);
-        if (stats.oldestPage)
-            parts.push(`Oldest page: ${stats.oldestPage}`);
-        if (stats.newestPage)
-            parts.push(`Newest page: ${stats.newestPage}`);
-        if (stats.lastIngest)
-            parts.push(`Last ingest: ${stats.lastIngest}`);
-        if (fixed.length > 0) {
-            parts.push(`\n## Auto-fixed (${fixed.length})\n`);
-            for (const f of fixed) {
-                parts.push(`- [${f.severity}] ${f.page ?? ""}: ${f.message}`);
-            }
-        }
-        if (issues.length > 0) {
-            parts.push(`\n## Remaining Issues (${issues.length})\n`);
-            for (const issue of issues) {
-                parts.push(`- [${issue.severity}] ${issue.category}${issue.page ? ` (${issue.page})` : ""}: ${issue.message}`);
-            }
-            parts.push("");
-            parts.push(LINT_PROMPT);
-        }
-        else {
-            parts.push("\nNo remaining issues. Wiki is healthy.");
-        }
-        return {
-            content: [{ type: "text", text: parts.join("\n") }],
-            details: {
-                issueCount: issues.length,
-                fixedCount: fixed.length,
-                stats,
-            },
-        };
-    };
-}
-// -- Factory: wiki_summarize execute -----------------------------------------
-function createSummarizeExecute(wikiDir, getScope) {
-    return async (params) => {
-        const scope = getScope();
-        const pages = [];
-        if (params.target === "all") {
-            // Summarize entire wiki
-            const refs = await listPages(wikiDir);
-            for (const ref of refs) {
-                const page = await readPage(wikiDir, ref.category, ref.slug);
-                if (page)
-                    pages.push(page);
-            }
-        }
-        else if (PARA_CATEGORIES.includes(params.target)) {
-            // Summarize a category
-            const refs = await listPages(wikiDir, params.target);
-            for (const ref of refs) {
-                const page = await readPage(wikiDir, ref.category, ref.slug);
-                if (page)
-                    pages.push(page);
-            }
-        }
-        else {
-            // Summarize a single page
-            const parsed = parsePagePath(params.target);
-            if (parsed) {
-                const page = await readPage(wikiDir, parsed.category, parsed.slug);
-                if (page)
-                    pages.push(page);
-            }
-            else {
-                // Try finding by slug alone across categories
-                const allPages = await listPages(wikiDir);
-                const targetLower = params.target.toLowerCase();
-                for (const ref of allPages) {
-                    if (ref.slug === targetLower || ref.title.toLowerCase() === targetLower) {
-                        const page = await readPage(wikiDir, ref.category, ref.slug);
-                        if (page)
-                            pages.push(page);
-                        break;
-                    }
-                }
-            }
-        }
-        if (pages.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `No pages found for target "${params.target}". Nothing to summarize.`,
-                    },
-                ],
-                details: { target: params.target, pageCount: 0 },
-            };
-        }
-        // Generate a bounded overview prompt for the LLM. For large targets like
-        // `all`, brief mode must not dump every full page body into model context.
-        const depth = params.depth ?? "brief";
-        const overviewPrompt = generateOverviewPrompt(pages, scope, { depth });
-        const depthNote = depth === "detailed"
-            ? "\nProvide a DETAILED summary with full Key Facts, Insights, and Connections for each theme."
-            : "\nProvide a BRIEF overview — one paragraph per theme, focus on high-level patterns.";
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: overviewPrompt + depthNote +
-                        "\n\nYou may optionally create a summary page via wiki_write if the overview is worth preserving.",
-                },
-            ],
-            details: {
-                target: params.target,
-                pageCount: pages.length,
-            },
-        };
-    };
-}
-// -- Factory: wiki_migrate execute -------------------------------------------
-function createMigrateExecute(wikiDir) {
-    return async () => {
-        const allRefs = await listPages(wikiDir);
-        let migratedCount = 0;
-        for (const ref of allRefs) {
-            const page = await readPage(wikiDir, ref.category, ref.slug);
-            if (!page)
-                continue;
-            const version = page.frontmatter.schemaVersion ?? 1;
-            if (version >= CURRENT_SCHEMA_VERSION)
-                continue;
-            const rawObj = page.frontmatter;
-            const result = migrateToLatest(rawObj, page.body);
-            const migratedFm = result.fm;
-            migratedFm.updated = new Date().toISOString();
-            await writePage(wikiDir, {
-                category: ref.category,
-                slug: ref.slug,
-                frontmatter: migratedFm,
-                body: result.body,
-            });
-            migratedCount++;
-        }
-        const summary = migratedCount > 0
-            ? `Migrated ${migratedCount} page(s) to schema version ${CURRENT_SCHEMA_VERSION}.`
-            : `All ${allRefs.length} page(s) already at schema version ${CURRENT_SCHEMA_VERSION}.`;
-        return {
-            content: [{ type: "text", text: summary }],
-            details: { migratedCount, totalPages: allRefs.length },
-        };
-    };
-}
-// -- Wikilink extraction helper (re-exported from link-utils) ----------------
-// extractWikilinks, autoLinkSlugs, syncFrontmatterLinks imported above
+import { detectSourceType } from "./ingest.js";
+import { CURRENT_SCHEMA_VERSION } from "./frontmatter.js";
+import { WIKI_TOOL_DESCRIPTIONS, WIKI_TOOL_SNIPPETS, getWikiToolGuidelines } from "./wiki-tool-guidance.js";
+import { createIngestExecute } from "./tools/ingest.js";
+import { createQueryExecute } from "./tools/query.js";
+import { createWriteExecute } from "./tools/write.js";
+import { createEditExecute, createReadExecute } from "./tools/edit-read.js";
+import { createMoveExecute } from "./tools/move.js";
+import { createLintExecute } from "./tools/lint.js";
+import { createMigrateExecute } from "./tools/migrate.js";
+import { createSummarizeExecute } from "./tools/summarize.js";
+import { WikiIngestParams, WikiQueryParams, WikiEditParams, WikiWriteParams, WikiReadParams, WikiMoveParams, WikiLintParams, WikiMigrateParams, WikiSummarizeParams, } from "./tools/schemas.js";
 // -- Public API: register tools for pi session -------------------------------
 /**
  * Register all wiki tools with the pi extension API.