pi-para 0.5.2 → 0.5.5

package/dist/tools.js

@@ -6,13 +6,12 @@
  *
  * Factory functions (createXxxExecute) close over wikiDir and store — no ctx dependency.
  */
-import { StringEnum } from "@mariozechner/pi-ai";
-import { Text } from "@mariozechner/pi-tui";
+import { StringEnum } from "@earendil-works/pi-ai";
+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 { reindex } from "./store.js";
-import { readPage, writePage, movePage, listPages, readIndex, writeIndex, readSchema, appendLog, gitCommit, rebuildIndex, PARA_CATEGORIES, } from "./wiki.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";
@@ -20,6 +19,8 @@ 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)" });
@@ -64,6 +65,16 @@ const WikiWriteParams = Type.Object({
     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",
@@ -189,15 +200,25 @@ function createQueryExecute(_wikiDir, store, getScope, getGraphBoost) {
         };
     };
 }
+// -- 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
-        const allRefs = await listPages(wikiDir);
-        const allSlugs = new Set(allRefs.map(r => r.slug));
+        // 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
@@ -212,21 +233,38 @@ function createWriteExecute(wikiDir, store, getScope, markDirty) {
             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) {
-                // Edit mode: apply targeted oldText→newText replacements
+                // 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
                 }
-                let editedBody = existing.body;
                 const errors = [];
                 for (const edit of edits) {
-                    const idx = editedBody.indexOf(edit.oldText);
-                    if (idx === -1) {
+                    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)}..."`);
-                        continue;
                     }
-                    editedBody = editedBody.slice(0, idx) + edit.newText + editedBody.slice(idx + edit.oldText.length);
+                    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;
@@ -336,8 +374,12 @@ function createWriteExecute(wikiDir, store, getScope, markDirty) {
             });
             logAppended = true;
         }
-        // Re-index for BM25 (fast). Do NOT embed — deferred to shutdown.
-        await reindex(store);
+        // 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
@@ -347,9 +389,12 @@ function createWriteExecute(wikiDir, store, getScope, markDirty) {
                 : `wiki: ${pagesWritten.join(", ")}`;
             await gitCommit(wikiDir, commitMsg);
         }
-        const summary = pagesWritten.length > 0
-            ? `Wrote ${pagesWritten.length} page(s): ${pagesWritten.join(", ")}`
-            : "No pages written.";
+        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: [
                 {
@@ -367,14 +412,112 @@ function createWriteExecute(wikiDir, store, getScope, markDirty) {
                 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) {
@@ -457,9 +600,10 @@ function createMoveExecute(wikiDir, store, markDirty) {
             path: `${parsed.category}/${parsed.slug}.md`,
         };
         await movePage(wikiDir, ref, params.to);
-        // Re-index and rebuild index.md
-        await reindex(store);
+        // 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}`);
@@ -588,9 +732,11 @@ function createSummarizeExecute(wikiDir, getScope) {
                 details: { target: params.target, pageCount: 0 },
             };
         }
-        // Generate overview prompt for the LLM
-        const overviewPrompt = generateOverviewPrompt(pages, scope);
-        const depthNote = params.depth === "detailed"
+        // 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 {
@@ -647,13 +793,14 @@ function createMigrateExecute(wikiDir) {
 /**
  * Register all wiki tools with the pi extension API.
  *
- * Tools: wiki_ingest, wiki_query, wiki_write, wiki_read,
+ * Tools: wiki_ingest, wiki_query, wiki_write, wiki_edit, wiki_read,
  *        wiki_move, wiki_lint, wiki_summarize
  */
 export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphBoost) {
     const ingestExec = createIngestExecute(wikiDir, store, getScope);
     const queryExec = createQueryExecute(wikiDir, store, getScope, getGraphBoost);
     const writeExec = createWriteExecute(wikiDir, store, getScope, markDirty);
+    const editExec = createEditExecute(wikiDir, store, markDirty);
     const readExec = createReadExecute(wikiDir);
     const moveExec = createMoveExecute(wikiDir, store, markDirty);
     const lintExec = createLintExecute(wikiDir);
@@ -663,13 +810,9 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
     pi.registerTool({
         name: "wiki_ingest",
         label: "Wiki Ingest",
-        description: "Ingest a source (URL, file path, or raw text) into the wiki. " +
-            "Fetches the content, saves a raw copy, and returns it with schema and index " +
-            "so you can synthesize wiki pages via wiki_write.",
-        promptSnippet: "Ingest a URL, file, or text into the PARA wiki knowledge base",
-        promptGuidelines: [
-            "Use wiki_ingest when the user provides a URL, file path, or text to add to the knowledge base.",
-        ],
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_ingest,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_ingest,
+        promptGuidelines: getWikiToolGuidelines("wiki_ingest"),
         parameters: WikiIngestParams,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             ctx.ui.setStatus("pi-para", "wiki: ingesting...");
@@ -709,15 +852,9 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
     pi.registerTool({
         name: "wiki_query",
         label: "Wiki Query",
-        description: "Search the wiki knowledge base with a natural language query. " +
-            "Returns relevant pages with content snippets. " +
-            "Use global=true to search across all project scopes.",
-        promptSnippet: "Search the PARA wiki for relevant knowledge pages",
-        promptGuidelines: [
-            "Use wiki_query BEFORE answering questions that might have relevant context in the wiki — architecture decisions, past debugging solutions, project conventions, or domain knowledge.",
-            "Use wiki_query when the user asks about something you previously discussed or captured in the wiki.",
-            "Wiki results include freshness indicators (FRESH/AGING/STALE/VERY STALE). When a page is AGING or STALE and makes claims about code, files, configs, ports, or APIs — verify against the actual source before trusting. If you find the wiki is wrong, fix it immediately with wiki_write(mode: 'edit').",
-        ],
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_query,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_query,
+        promptGuidelines: getWikiToolGuidelines("wiki_query"),
         parameters: WikiQueryParams,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             ctx.ui.setStatus("pi-para", "wiki: searching...");
@@ -747,20 +884,44 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
                 theme.fg("dim", ` scope: ${details.scopeUsed}`), 0, 0);
         },
     });
+    // -- wiki_edit --
+    pi.registerTool({
+        name: "wiki_edit",
+        label: "Wiki Edit",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_edit,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_edit,
+        promptGuidelines: getWikiToolGuidelines("wiki_edit"),
+        parameters: WikiEditParams,
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            ctx.ui.setStatus("pi-para", "wiki: editing...");
+            try {
+                return await editExec(params);
+            }
+            finally {
+                ctx.ui.setStatus("pi-para", undefined);
+            }
+        },
+        renderCall(args, theme) {
+            return new Text(theme.fg("toolTitle", theme.bold("wiki_edit ")) +
+                theme.fg("muted", args.path ?? "") +
+                theme.fg("dim", ` (${args.edits?.length ?? 0} edit(s))`), 0, 0);
+        },
+        renderResult(result, _options, theme) {
+            const details = result.details;
+            if (details?.pagesWritten?.length) {
+                return new Text(theme.fg("success", `Edited ${details.pagesWritten.join(", ")}`), 0, 0);
+            }
+            const t = result.content[0];
+            return new Text(theme.fg("warning", t?.type === "text" ? t.text : "No changes"), 0, 0);
+        },
+    });
     // -- wiki_write --
     pi.registerTool({
         name: "wiki_write",
         label: "Wiki Write",
-        description: "Write or update wiki pages. Supports create, replace, append, and edit modes. " +
-            "Optionally update index.md and append to log.md. " +
-            "Pages are automatically re-indexed for search after writing.",
-        promptSnippet: "Write/update PARA wiki pages with frontmatter and markdown body. Use mode=edit with edits[{oldText,newText}] to surgically update sections.",
-        promptGuidelines: [
-            "Use wiki_write after wiki_ingest to create/update pages based on the ingested content.",
-            "Use wiki_write to save valuable answers or synthesis back into the wiki when they add new knowledge.",
-            "After making significant architectural decisions, solving debugging problems, establishing project conventions, or completing substantial implementation work, use wiki_write to persist the knowledge without being asked.",
-            "Prefer mode=edit with edits[{oldText,newText}] to update specific sections of existing pages. Use mode=append to add new sections. Only use mode=replace when rewriting the entire page.",
-        ],
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_write,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_write,
+        promptGuidelines: getWikiToolGuidelines("wiki_write"),
         parameters: WikiWriteParams,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             ctx.ui.setStatus("pi-para", "wiki: writing...");
@@ -795,6 +956,9 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
                 parts.push(theme.fg("success", `Wrote ${details.pagesWritten.length} page(s): `) +
                     theme.fg("muted", details.pagesWritten.join(", ")));
             }
+            if (details.pagesSkipped?.length) {
+                parts.push(theme.fg("warning", `Skipped ${details.pagesSkipped.length} page(s): `) + theme.fg("muted", details.pagesSkipped.join(", ")));
+            }
             if (details.indexUpdated)
                 parts.push(theme.fg("dim", "Updated index.md"));
             if (details.logAppended)
@@ -806,12 +970,9 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
     pi.registerTool({
         name: "wiki_read",
         label: "Wiki Read",
-        description: "Read a specific wiki page by path (e.g. 'projects/auth-refactor') " +
-            "or by title. Returns the full page content with frontmatter metadata and a freshness indicator.",
-        promptSnippet: "Read a wiki page by path or title. Includes freshness indicator — verify STALE pages against actual code before trusting.",
-        promptGuidelines: [
-            "wiki_read results include a freshness indicator (FRESH/AGING/STALE/VERY STALE). When a page is AGING or STALE, verify claims about code, configs, or APIs against the actual source before trusting. Fix incorrect wiki pages with wiki_write(mode: 'edit').",
-        ],
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_read,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_read,
+        promptGuidelines: getWikiToolGuidelines("wiki_read"),
         parameters: WikiReadParams,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             ctx.ui.setStatus("pi-para", "wiki: reading...");
@@ -838,9 +999,9 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
     pi.registerTool({
         name: "wiki_move",
         label: "Wiki Move",
-        description: "Move a wiki page between PARA categories (e.g. move a completed project to archives). " +
-            "Updates frontmatter and re-indexes.",
-        promptSnippet: "Move a wiki page between PARA categories",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_move,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_move,
+        promptGuidelines: getWikiToolGuidelines("wiki_move"),
         parameters: WikiMoveParams,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             ctx.ui.setStatus("pi-para", "wiki: moving...");
@@ -869,10 +1030,9 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
     pi.registerTool({
         name: "wiki_lint",
         label: "Wiki Lint",
-        description: "Run wiki health checks: orphan pages, broken links, stale pages, " +
-            "scope drift, archive candidates, missing pages, frontmatter issues, " +
-            "index drift, and duplicate slugs. Auto-fixes simple issues by default.",
-        promptSnippet: "Run wiki health checks and auto-fix issues",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_lint,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_lint,
+        promptGuidelines: getWikiToolGuidelines("wiki_lint"),
         parameters: WikiLintParams,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             ctx.ui.setStatus("pi-para", "wiki: linting...");
@@ -912,9 +1072,9 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
     pi.registerTool({
         name: "wiki_migrate",
         label: "Wiki Migrate",
-        description: "Migrate all wiki pages to the current schema version. " +
-            "Runs pending schema migrations on any pages with an older schemaVersion.",
-        promptSnippet: "Batch-migrate all wiki pages to the current schema version",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_migrate,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_migrate,
+        promptGuidelines: getWikiToolGuidelines("wiki_migrate"),
         parameters: WikiMigrateParams,
         async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
             ctx.ui.setStatus("pi-para", "wiki: migrating...");
@@ -944,11 +1104,9 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
     pi.registerTool({
         name: "wiki_summarize",
         label: "Wiki Summarize",
-        description: "Summarize a page, category, or the entire wiki. " +
-            "Target can be a page path (e.g. 'projects/auth-refactor'), " +
-            "a category name (e.g. 'projects'), or 'all'. " +
-            "Returns content with a summary prompt for you to synthesize.",
-        promptSnippet: "Summarize wiki pages, categories, or the entire wiki",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_summarize,
+        promptSnippet: WIKI_TOOL_SNIPPETS.wiki_summarize,
+        promptGuidelines: getWikiToolGuidelines("wiki_summarize"),
         parameters: WikiSummarizeParams,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             ctx.ui.setStatus("pi-para", "wiki: summarizing...");
@@ -983,44 +1141,51 @@ export function registerTools(pi, wikiDir, store, getScope, markDirty, getGraphB
 /**
  * Create standalone AgentTool instances for the mini-agent (capture/lint/summarize).
  * Returns only the tools needed for autonomous wiki operations:
- * wiki_write, wiki_read, wiki_query, wiki_move.
+ * wiki_write, wiki_edit, wiki_read, wiki_query, wiki_move.
  */
 export function createStandaloneTools(wikiDir, store, getScope, markDirty) {
     const noopDirty = markDirty ?? (() => { });
     const writeExec = createWriteExecute(wikiDir, store, getScope, noopDirty);
+    const editExec = createEditExecute(wikiDir, store, noopDirty);
     const readExec = createReadExecute(wikiDir);
     const queryExec = createQueryExecute(wikiDir, store, getScope);
     const moveExec = createMoveExecute(wikiDir, store, noopDirty);
     const wikiWrite = {
         name: "wiki_write",
         label: "Wiki Write",
-        description: "Write or update wiki pages. Supports create, replace, and append modes. " +
-            "Optionally update index.md and append to log.md.",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_write,
         parameters: WikiWriteParams,
         execute: (_toolCallId, params) => writeExec(params),
     };
+    const wikiEdit = {
+        name: "wiki_edit",
+        label: "Wiki Edit",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_edit,
+        parameters: WikiEditParams,
+        execute: (_toolCallId, params) => editExec(params),
+    };
     const wikiRead = {
         name: "wiki_read",
         label: "Wiki Read",
-        description: "Read a specific wiki page by path (e.g. 'projects/auth-refactor') or by title.",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_read,
         parameters: WikiReadParams,
         execute: (_toolCallId, params) => readExec(params),
     };
     const wikiQuery = {
         name: "wiki_query",
         label: "Wiki Query",
-        description: "Search the wiki knowledge base with a natural language query. Returns relevant pages.",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_query,
         parameters: WikiQueryParams,
         execute: (_toolCallId, params) => queryExec(params),
     };
     const wikiMove = {
         name: "wiki_move",
         label: "Wiki Move",
-        description: "Move a wiki page between PARA categories.",
+        description: WIKI_TOOL_DESCRIPTIONS.wiki_move,
         parameters: WikiMoveParams,
         execute: (_toolCallId, params) => moveExec(params),
     };
-    return [wikiWrite, wikiRead, wikiQuery, wikiMove];
+    return [wikiWrite, wikiEdit, wikiRead, wikiQuery, wikiMove];
 }
 // -- Utilities ---------------------------------------------------------------
 function formatBytes(bytes) {