pi-para 0.5.2 → 0.6.0

package/src/tools.ts

@@ -7,22 +7,22 @@
  * Factory functions (createXxxExecute) close over wikiDir and store — no ctx dependency.
  */
 
-import { StringEnum } from "@mariozechner/pi-ai";
-import type { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import type { QMDStore } from "qmd-engine";
 import { Type } from "typebox";
 
 import type { ProjectScope } from "./scope.js";
 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,
+  listPageSlugs,
   readIndex,
   writeIndex,
   readSchema,
@@ -53,6 +53,12 @@ import {
   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 -------------------------------------------------------
 
@@ -124,6 +130,17 @@ const WikiWriteParams = Type.Object({
   ),
 });
 
+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",
@@ -173,6 +190,7 @@ interface WikiWriteDetails {
   pagesWritten: string[];
   indexUpdated: boolean;
   logAppended: boolean;
+  pagesSkipped?: string[];
 }
 
 interface WikiReadDetails {
@@ -325,6 +343,21 @@ function createQueryExecute(
   };
 }
 
+// -- 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: string,
+  store: QMDStore,
+  markDirty: () => void,
+): void {
+  enqueueWikiMaintenance(wikiDir, store, markDirty);
+}
+
 // -- Factory: wiki_write execute ---------------------------------------------
 
 function createWriteExecute(
@@ -350,12 +383,13 @@ function createWriteExecute(
     },
   ): Promise<AgentToolResult<WikiWriteDetails>> => {
     const pagesWritten: string[] = [];
+    const pagesSkipped: string[] = [];
     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
@@ -375,21 +409,39 @@ function createWriteExecute(
       // 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: string[] = [];
         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;
+          } else if (first !== last) {
+            errors.push(`oldText is not unique: "${edit.oldText.slice(0, 60)}..."`);
           }
-          editedBody = editedBody.slice(0, idx) + edit.newText + editedBody.slice(idx + edit.oldText.length);
+        }
+        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;
@@ -500,8 +552,12 @@ function createWriteExecute(
       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();
@@ -514,9 +570,12 @@ function createWriteExecute(
       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: [
@@ -535,6 +594,7 @@ function createWriteExecute(
         pagesWritten,
         indexUpdated,
         logAppended,
+        pagesSkipped,
       },
     };
   };
@@ -542,11 +602,129 @@ function createWriteExecute(
 
 // -- Factory: wiki_read execute ----------------------------------------------
 
+function createEditExecute(
+  wikiDir: string,
+  store: QMDStore,
+  markDirty: () => void,
+) {
+  return async (
+    params: {
+      path: string;
+      edits: Array<{ oldText: string; newText: string }>;
+      title?: string;
+      scope?: string[];
+      tags?: string[];
+      logSummary?: string;
+    },
+  ): Promise<AgentToolResult<WikiWriteDetails>> => {
+    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: string[] = [];
+    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: WikiPage = {
+      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: string) {
   return async (
     params: { path: string },
   ): Promise<AgentToolResult<WikiReadDetails>> => {
     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);
@@ -647,9 +825,10 @@ function createMoveExecute(
 
     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
@@ -794,10 +973,12 @@ function createSummarizeExecute(
       };
     }
 
-    // Generate overview prompt for the LLM
-    const overviewPrompt = generateOverviewPrompt(pages, scope);
+    // 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 =
-      params.depth === "detailed"
+      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.";
 
@@ -866,7 +1047,7 @@ function createMigrateExecute(
 /**
  * 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(
@@ -880,6 +1061,7 @@ export function registerTools(
   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);
@@ -890,14 +1072,9 @@ export function registerTools(
   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...");
@@ -938,16 +1115,9 @@ export function registerTools(
   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...");
@@ -977,21 +1147,44 @@ export function registerTools(
     },
   });
 
+  // -- 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 as WikiWriteDetails | undefined;
+      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...");
@@ -1023,6 +1216,9 @@ export function registerTools(
             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) parts.push(theme.fg("dim", "Logged operation"));
       return new Text(parts.join("\n") || theme.fg("dim", "No changes"), 0, 0);
@@ -1033,13 +1229,9 @@ export function registerTools(
   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...");
@@ -1070,10 +1262,9 @@ export function registerTools(
   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...");
@@ -1106,11 +1297,9 @@ export function registerTools(
   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...");
@@ -1149,10 +1338,9 @@ export function registerTools(
   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...");
@@ -1190,12 +1378,9 @@ export function registerTools(
   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...");
@@ -1231,7 +1416,7 @@ export function registerTools(
 /**
  * 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: string,
@@ -1241,6 +1426,7 @@ export function createStandaloneTools(
 ): AgentTool[] {
   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);
@@ -1248,18 +1434,23 @@ export function createStandaloneTools(
   const wikiWrite: AgentTool<typeof WikiWriteParams> = {
     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: AgentTool<typeof WikiEditParams> = {
+    name: "wiki_edit",
+    label: "Wiki Edit",
+    description: WIKI_TOOL_DESCRIPTIONS.wiki_edit,
+    parameters: WikiEditParams,
+    execute: (_toolCallId, params) => editExec(params),
+  };
+
   const wikiRead: AgentTool<typeof WikiReadParams> = {
     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),
   };
@@ -1267,8 +1458,7 @@ export function createStandaloneTools(
   const wikiQuery: AgentTool<typeof WikiQueryParams> = {
     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),
   };
@@ -1276,12 +1466,12 @@ export function createStandaloneTools(
   const wikiMove: AgentTool<typeof WikiMoveParams> = {
     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 ---------------------------------------------------------------