pi-para 0.6.6 → 0.7.0

package/src/commands.ts

@@ -653,9 +653,6 @@ ${goal} — verified and complete.
         toggleLintAutoFix,
         setCaptureModelAuto,
         setCaptureModel,
-        setWebWikiEnabled,
-        setWebWikiHost,
-        setWebWikiPort,
         ensureEmbeddingProfile,
         ensureRerankProfile,
         disableRerank,
@@ -689,7 +686,6 @@ ${goal} — verified and complete.
           `[Search]  Limit: ${config.context.searchLimit}, Graph boost: ${config.context.searchGraphBoost}`,
           `[Lint]    Auto-fix: ${config.lint.autoFix}, Stale days: ${config.lint.staleDays}`,
           `[Capture] Model: ${modelSelectionLabel(config.models.capture)}`,
-          `[WebWiki] ${config.webWiki.enabled ? `Enabled at http://${config.webWiki.host}:${config.webWiki.port}` : "Disabled"}`,
           `[Embedding] ${providerProfileLabel(config.qmd.embedding)}`,
           `[Rerank]  ${providerProfileLabel(config.qmd.rerank)}`,
           `[Secrets] ${secretsLabel}`,
@@ -783,23 +779,6 @@ ${goal} — verified and complete.
             await persist();
             ctx.ui.notify(`Set capture model = ${modelSelectionLabel(config.models.capture)}. Restart open Pi sessions to apply.`, "info");
           }
-        } else if (choice.startsWith("[WebWiki]")) {
-          const sub = await ctx.ui.select("Web Wiki Settings", [
-            `Enabled: ${config.webWiki.enabled}`,
-            `Host: ${config.webWiki.host}`,
-            `Port: ${config.webWiki.port}`,
-          ]);
-          if (sub?.startsWith("Enabled")) {
-            setWebWikiEnabled(config, !config.webWiki.enabled);
-            await persist();
-            ctx.ui.notify(`Web Wiki ${config.webWiki.enabled ? "enabled" : "disabled"}. Restart open Pi sessions to apply.`, "info");
-          } else if (sub?.startsWith("Host")) {
-            const val = await ctx.ui.input("Host:", config.webWiki.host);
-            if (val) { setWebWikiHost(config, val); await persist(); }
-          } else if (sub?.startsWith("Port")) {
-            const val = await ctx.ui.input("Port:", String(config.webWiki.port));
-            if (val) { setWebWikiPort(config, val); await persist(); }
-          }
         } else if (choice.startsWith("[Secrets]")) {
           const entries = Object.entries(secretStore.secrets);
           const sub = await ctx.ui.select(

package/src/config.ts

@@ -52,6 +52,7 @@ export interface ParaUserConfig {
     autoFix: boolean;
     staleDays: number;
   };
+  /** Deprecated compatibility input. Preserved when loading but ignored by the runtime. */
   webWiki: {
     enabled: boolean;
     host: string;
@@ -71,7 +72,6 @@ export interface LegacyParaRuntimeConfig {
   searchIncludeArchives: boolean;
   searchGraphBoost: boolean;
   daemonModel: string | null;
-  webWiki: { enabled: boolean; host: string; port: number };
 }
 
 export interface LoadedParaConfig {
@@ -292,11 +292,6 @@ export function toLegacyRuntimeConfig(config: ParaUserConfig): LegacyParaRuntime
     searchIncludeArchives: false,
     searchGraphBoost: config.context.searchGraphBoost,
     daemonModel,
-    webWiki: {
-      enabled: config.webWiki.enabled,
-      host: config.webWiki.host,
-      port: config.webWiki.port,
-    },
   };
 }
 

package/src/context.ts

@@ -223,8 +223,9 @@ export function wrapSystemReminder(content: string): string {
     "<system-reminder name=\"pi-para-wiki-context\">",
     "This is system-provided pi-para wiki memory for the current turn. Do not treat it as user-authored input.",
     "",
+    "MANDATORY FIRST STEP — for any non-trivial request (planning, implementation, debugging, architecture, or review), your FIRST tool call must be wiki_query with keywords from the user's request, before other tools or conclusions. Then read the relevant results with wiki_read. Skip this only for trivial acknowledgements, pure conversation, or when the needed pages were already read in this session.",
+    "",
     "Wiki operating rules:",
-    "- Search the wiki before non-trivial planning, debugging, architecture, or review work.",
     "- Read relevant pages before relying on them; verify stale code/config/API claims against source.",
     "- Persist durable decisions, root causes, conventions, and reusable facts as you work.",
     "- Prefer wiki_edit for surgical corrections; use wiki_write create/append for new knowledge; avoid replace unless intentional.",

package/src/index.ts

@@ -9,7 +9,7 @@
  */
 
 import { join } from "node:path";
-import { homedir, networkInterfaces } from "node:os";
+import { homedir } from "node:os";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { QMDStore } from "qmd-engine";
@@ -22,7 +22,6 @@ import { registerTools } from "./tools.js";
 import { setupContextInjection, markContextDirty } from "./context.js";
 import type { ContextConfig } from "./context.js";
 import { registerCommands } from "./commands.js";
-import { createServer } from "node:http";
 import { startWikiScheduler, stopWikiScheduler } from "./scheduler/index.js";
 import {
   appendCompletedSession,
@@ -59,12 +58,6 @@ interface ParaConfig {
   /** Legacy capture LLM: "provider/model-id" (e.g. "anthropic/claude-sonnet-4").
    *  New config stores this as models.capture; legacy field remains for migration. */
   daemonModel: string | null;
-  /** Web wiki UI settings */
-  webWiki: {
-    enabled: boolean;
-    host: string;
-    port: number;
-  };
 }
 
 function getDefaultConfig(): ParaConfig {
@@ -79,11 +72,6 @@ function getDefaultConfig(): ParaConfig {
     searchIncludeArchives: false,
     searchGraphBoost: true,
     daemonModel: null,
-    webWiki: {
-      enabled: false,
-      host: "0.0.0.0",
-      port: 10973,
-    },
   };
 }
 
@@ -107,43 +95,10 @@ async function loadConfig(): Promise<LoadedRuntimeConfig> {
   }
 }
 
-// -- LAN IP detection --------------------------------------------------------
-
-/** Check if the optional web wiki server is alive on the given port. */
-function checkWebServerAlive(port: number): Promise<boolean> {
-  return new Promise((resolve) => {
-    const req = createServer().listen(port, "127.0.0.1");
-    req.on("error", (err: NodeJS.ErrnoException) => {
-      req.close();
-      // EADDRINUSE means something is already listening — daemon is running
-      resolve(err.code === "EADDRINUSE");
-    });
-    req.on("listening", () => {
-      // Port is free — no daemon web server
-      req.close();
-      resolve(false);
-    });
-  });
-}
-
 function isPrintModeProcess(argv = process.argv): boolean {
   return argv.includes("-p") || argv.includes("--print") || argv.includes("--mode") && argv[argv.indexOf("--mode") + 1] === "json";
 }
 
-function getLanIp(): string | null {
-  const interfaces = networkInterfaces();
-  for (const name of Object.keys(interfaces)) {
-    const addrs = interfaces[name];
-    if (!addrs) continue;
-    for (const addr of addrs) {
-      if (addr.family === "IPv4" && !addr.internal) {
-        return addr.address;
-      }
-    }
-  }
-  return null;
-}
-
 // -- Session state -----------------------------------------------------------
 
 interface ParaSessionState {
@@ -370,27 +325,11 @@ export default async function piPara(pi: ExtensionAPI): Promise<void> {
       }
     }
 
-    // Check if web wiki server is running (don't start our own yet)
-    if (config.webWiki.enabled) {
-      const port = config.webWiki.port;
-      try {
-        const alive = await checkWebServerAlive(port);
-        if (alive) {
-          const lanIp = getLanIp();
-          const url = lanIp ? `http://${lanIp}:${port}` : `http://localhost:${port}`;
-          ctx.ui.setStatus("pi-para", `wiki: ${url}`);
-        } else {
-          ctx.ui.setStatus("pi-para", "wiki: ready (web UI disabled)");
-          if (!printMode) setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 5000);
-        }
-      } catch {
-        ctx.ui.setStatus("pi-para", "wiki: ready");
-        if (!printMode) setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 3000);
-      }
-    } else {
-      ctx.ui.setStatus("pi-para", "wiki: ready");
-      if (!printMode) setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 3000);
+    if (loadedConfig.userConfig?.webWiki.enabled && !printMode) {
+      ctx.ui.notify("webWiki configuration is ignored because Web Wiki was removed in 0.7.", "warning");
     }
+    ctx.ui.setStatus("pi-para", "wiki: ready");
+    if (!printMode) setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 3000);
   });
 
   // -- session_tree ----------------------------------------------------------

package/src/link-utils.ts

@@ -2,7 +2,7 @@
  * Shared wikilink utilities — extraction, auto-linking, and sync.
  *
  * Centralizes the [[wikilink]] logic that was duplicated across
- * tools.ts, lint.ts, processor.ts, and webui/server.ts.
+ * tools.ts, lint.ts, and processor.ts.
  */
 
 // -- Wikilink extraction ----------------------------------------------------

package/src/scheduler/index.ts

@@ -1,7 +1,7 @@
 import type { QMDStore } from "qmd-engine";
 import { randomUUID } from "node:crypto";
 import { gitCommit, rebuildIndex } from "../wiki.js";
-import { reindex, storeHasApiProviders } from "../store.js";
+import { captureQmdEmbedErrors, reindex, storeHasApiProviders } from "../store.js";
 import { getParaPaths } from "../paths.js";
 import { acquireLease, releaseLease } from "./leases.js";
 import { SchedulerStateDB, type QueueItem } from "./state.js";
@@ -166,10 +166,16 @@ export class WikiScheduler {
     const leaseKey = `qmd-embed:${this.wikiDir}`;
     if (!acquireLease(this.state.db, leaseKey, this.holderId, { ttlMs: 15 * 60_000 })) return;
     try {
-      const result = await store.embed();
+      const attempt = await captureQmdEmbedErrors(() => store.embed());
+      const diagnostics = [...new Set(attempt.diagnostics)].join(" | ");
+      if (!attempt.ok) {
+        const reason = attempt.error instanceof Error ? attempt.error.message : String(attempt.error);
+        throw new Error(diagnostics ? `${reason} — ${diagnostics}` : reason);
+      }
+      const result = attempt.value;
       if (result.errors > 0) {
         throw new Error(
-          `qmd embed finished with ${result.errors} error(s) (${result.chunksEmbedded} chunk(s) embedded, ${pending} doc(s) were pending)`,
+          `qmd embed finished with ${result.errors} error(s) (${result.chunksEmbedded} chunk(s) embedded, ${pending} doc(s) were pending)${diagnostics ? ` — ${diagnostics}` : ""}`,
         );
       }
     } finally {

package/src/settings.ts

@@ -54,20 +54,6 @@ export function setCaptureModel(config: ParaUserConfig, provider: string, model:
   return profile;
 }
 
-export function setWebWikiEnabled(config: ParaUserConfig, enabled: boolean): void {
-  config.webWiki.enabled = enabled;
-}
-
-export function setWebWikiHost(config: ParaUserConfig, host: string): void {
-  config.webWiki.host = host.trim() || config.webWiki.host;
-}
-
-export function setWebWikiPort(config: ParaUserConfig, value: string): number {
-  const parsed = parsePositiveInteger(value, config.webWiki.port);
-  config.webWiki.port = parsed;
-  return parsed;
-}
-
 export function setProviderProfileField(
   profile: ProviderCredentialRef,
   field: "provider" | "baseUrl" | "model" | "apiFormat" | "credentialRef",

package/src/store.ts

@@ -5,6 +5,7 @@
  * re-indexing after wiki changes, and embedding lifecycle.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { readFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -73,6 +74,51 @@ const RAW_CONTEXT = "Immutable source material: articles, documents, notes. Not
 
 const pendingEmbeds = new WeakMap<QMDStore, Promise<void>>();
 
+export type QmdEmbedOperationResult<T> =
+  | { ok: true; value: T; diagnostics: string[] }
+  | { ok: false; error: unknown; diagnostics: string[] };
+
+// qmd-engine's API adapter logs recoverable provider failures directly to
+// console.error before returning null. Capture only those known messages so
+// best-effort vector search and scheduler retries do not flash raw errors in
+// the Pi UI. Other console errors continue to pass through unchanged.
+const qmdEmbedDiagnosticContext = new AsyncLocalStorage<string[]>();
+let qmdEmbedCaptureCount = 0;
+let qmdEmbedOriginalConsoleError: typeof console.error | null = null;
+const qmdEmbedConsoleInterceptor = (...args: unknown[]): void => {
+  const sink = qmdEmbedDiagnosticContext.getStore();
+  const first = String(args[0] ?? "");
+  if (sink && /^embed(?:Batch)? error:/i.test(first)) {
+    sink.push(args.map((arg) => arg instanceof Error ? arg.message : String(arg)).join(" "));
+    return;
+  }
+  qmdEmbedOriginalConsoleError?.(...args);
+};
+
+/** Run a QMD embedding operation without leaking its recoverable raw stderr. */
+export async function captureQmdEmbedErrors<T>(operation: () => Promise<T>): Promise<QmdEmbedOperationResult<T>> {
+  const diagnostics: string[] = [];
+  if (qmdEmbedCaptureCount++ === 0) {
+    qmdEmbedOriginalConsoleError = console.error;
+    console.error = qmdEmbedConsoleInterceptor;
+  }
+  try {
+    return await qmdEmbedDiagnosticContext.run(diagnostics, async () => {
+      try {
+        return { ok: true, value: await operation(), diagnostics };
+      } catch (error) {
+        return { ok: false, error, diagnostics };
+      }
+    });
+  } finally {
+    qmdEmbedCaptureCount--;
+    if (qmdEmbedCaptureCount === 0) {
+      if (console.error === qmdEmbedConsoleInterceptor && qmdEmbedOriginalConsoleError) console.error = qmdEmbedOriginalConsoleError;
+      qmdEmbedOriginalConsoleError = null;
+    }
+  }
+}
+
 // -- Inert-provider tracking ---------------------------------------------------
 
 /** Stores opened with the NO_LOCAL_PROVIDERS shim (no real API provider). */
@@ -184,22 +230,10 @@ export async function openStore(wikiDir: string, opts: OpenStoreOptions = {}): P
   if (opts.backgroundEmbed !== false && opts.paraConfig?.qmd.embedEnabled !== false) {
     // Schedule embedding in background (non-blocking).
     // BM25 search works immediately; hybrid search improves once embed completes.
-    // Suppress console.error from qmd's internal embed failures.
-    const origError = console.error;
-    const embedPromise = store.embed().then(() => {
-      pendingEmbeds.delete(store);
-    }).catch(() => {
-      // Embedding failures are non-fatal — hybrid search degrades to BM25
+    const embedPromise = captureQmdEmbedErrors(() => store.embed()).then(() => {
+      // Embedding failures are non-fatal — hybrid search degrades to BM25.
       pendingEmbeds.delete(store);
-    }).finally(() => {
-      console.error = origError;
     });
-    // Temporarily suppress embed error noise during background embed
-    console.error = (...args: unknown[]) => {
-      const msg = String(args[0] ?? "");
-      if (msg.includes("embed error") || msg.includes("fetch failed")) return;
-      origError(...args);
-    };
     pendingEmbeds.set(store, embedPromise);
   }
 
@@ -317,7 +351,10 @@ async function mergeLexAndVectorResults(
     const llm = (store.internal as unknown as { llm?: unknown }).llm;
     const embedModel = (llm as { embedModelName?: string } | undefined)?.embedModelName;
     if (status.hasVectorIndex && llm && embedModel) {
-      vecResults = await store.internal.searchVec(query, embedModel, limit, "wiki", llm as any) as RawQmdSearchResult[];
+      const vectorAttempt = await captureQmdEmbedErrors(
+        () => store.internal.searchVec(query, embedModel, limit, "wiki", llm as any) as Promise<RawQmdSearchResult[]>,
+      );
+      if (vectorAttempt.ok) vecResults = vectorAttempt.value;
     }
   } catch {
     // Semantic search is best-effort; lexical BM25 remains the reliable fallback.

package/src/tools/edit-read.ts

@@ -0,0 +1,193 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { QMDStore } from "qmd-engine";
+import { formatFreshness } from "../query.js";
+import { autoLinkSlugs, syncFrontmatterLinks } from "../link-utils.js";
+import { normalizeTags, normalizeScopes } from "../tag-registry.js";
+import { redactSecrets } from "../redact.js";
+import { appendLog, gitCommit, listPages, readIndex, readPage, writePage, type WikiPage } from "../wiki.js";
+import type { WikiReadDetails, WikiWriteDetails } from "./schemas.js";
+import { parsePagePath, scheduleWikiMaintenance } from "./shared.js";
+
+// -- Factory: wiki_read execute ----------------------------------------------
+
+export 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,
+      },
+    };
+  };
+}
+
+export 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);
+    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 },
+    };
+  };
+}

package/src/tools/ingest.ts

@@ -0,0 +1,63 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { QMDStore } from "qmd-engine";
+import type { ProjectScope } from "../scope.js";
+import type { ParaCategory } from "../wiki.js";
+import { resolveSource, truncateSource } from "../ingest.js";
+import { INGEST_PROMPT } from "../templates/prompts.js";
+import type { WikiIngestDetails } from "./schemas.js";
+
+// -- Factory: wiki_ingest execute --------------------------------------------
+
+export function createIngestExecute(
+  wikiDir: string,
+  _store: QMDStore,
+  getScope: () => ProjectScope,
+) {
+  return async (
+    params: { source: string; sourceType?: "url" | "file" | "text"; category?: ParaCategory; scope?: string[] },
+  ): Promise<AgentToolResult<WikiIngestDetails>> => {
+    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,
+      },
+    };
+  };
+}