@zosmaai/pi-llm-wiki 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-11
+
+### Added
+- **Phase 1 — Auto-recall** (PR #19 by @arjun-zosma): New `wiki_recall` tool for explicit searches. Extension now auto-searches wiki before every user turn via `before_agent_start` hook. Matching pages injected as "Relevant Wiki Knowledge" into system prompt. 8 new tests.
+- **Phase 2 — Auto-capture** (PR #20 by @arjun-zosma): New `wiki_retro` tool for saving atomic insights from completed tasks. Creates source packets with manifest, extracted text, and source page. 4 new tests.
+- **Phase 3 — MCP Server** (PR #21 by @arjun-zosma): Standalone MCP server using `@modelcontextprotocol/server` (v2 SDK) with stdio transport. Exposes 5 tools: wiki_recall, wiki_search, wiki_status, wiki_retro, wiki_capture_source. Cross-platform reach to Claude Code, Cursor, Windsurf.
+- **12 extension tools** (up from 10): wiki_recall (auto at turn start) and wiki_retro (manual at task end)
+- **SKILL.md**: Auto-Recall section, wiki_recall + wiki_retro tool docs, "Task → Capture → Retro" workflow
+
+### Changed
+- Extension registers 12 tools instead of 10
+- Status bar now shows "12 tools, auto-recall active"
+
+## [0.5.0] - 2026-05-11
+
+### Added
+- **Overhauled README**: npm downloads badge, slash commands table, guardrails section, skill behavior, vault layout, source packet format, integration flow, linking style guide
+- **Better npm discoverability**: 19 keywords (was 10), expanded description with search terms, `files` field to slim package
+- **GitHub topics**: pi, llm-wiki, knowledge-base, wiki, markdown, obsidian, karpathy, second-brain, pkm, memory
+
+## [0.4.0] - 2026-05-11
+
+- JSON file support (PR #15 by jfraser)
+- Extractor strategy pattern refactor
+
+## [0.3.0] - 2026-05-07
+
+- Release
+
+## [0.2.2] - 2026-05-03
+
+- Fix: CodeQL alerts for safe tag stripping and entity decoding
+- Fix: README contributors via contrib.rocks
+- Added: Features section and env var documentation
+
+## [0.2.1] - 2026-04-29
+
+- Minor fixes
+
 ## [0.2.0] - 2026-04-28
 
 ### Added

package/README.md

@@ -2,53 +2,264 @@
 
 [![CI](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/ci.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
+[![npm downloads](https://img.shields.io/npm/dm/@zosmaai/pi-llm-wiki)](https://www.npmjs.com/package/@zosmaai/pi-llm-wiki)
 [![Coverage](https://codecov.io/gh/zosmaai/pi-llm-wiki/branch/main/graph/badge.svg)](https://codecov.io/gh/zosmaai/pi-llm-wiki)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![CodeQL](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml/badge.svg)](https://github.com/zosmaai/pi-llm-wiki/actions/workflows/codeql.yml)
 
-Self-maintaining, Obsidian-compatible knowledge base for [pi](https://pi.dev). Following Andrej Karpathy's LLM Wiki pattern.
+**Self-maintaining, Obsidian-compatible knowledge base for [pi](https://pi.dev).**
+Follows Andrej Karpathy's [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
 
-## Install
+Turn raw sources (URLs, PDFs, markdown, JSON, XML) into a durable, interlinked, LLM-maintained wiki that compounds over time.
+
+---
+
+## Quick Start
 
 ```bash
 pi install npm:@zosmaai/pi-llm-wiki
 ```
 
-## Quick Start
-
 ```
 /wiki-init "AI Engineering"
+/wiki-ingest
+/wiki-query What are the key patterns?
 ```
 
-Drop sources into `raw/`, then:
+---
+
+## Why This Package?
+
+Most file-based LLM workflows behave like one-shot RAG: the model searches raw documents every time you ask a question. Synthesis is ephemeral.
+
+**pi-llm-wiki** creates a middle layer:
+
+- **Raw source packets** preserve source-of-truth inputs
+- **Source pages** summarize what each source says
+- **Canonical wiki pages** track what the wiki currently believes
+- **Generated metadata** keeps everything searchable and navigable
 
+The result is a wiki that **compounds** as you capture sources, ask questions, and file durable analyses.
+
+---
+
+## Features
+
+| Capability | Description |
+|------------|-------------|
+| 🔗 **Immutable source capture** | URLs, local files (PDF/md/txt/html/XML/JSON), or pasted text → structured source packets |
+| 🧠 **Automated ingestion** | `wiki_ingest` batch-processes sources into concept, entity, synthesis & analysis pages |
+| 🔍 **Full-text search** | Generated registry with keyword lookup across all pages and sources |
+| 🩺 **Mechanical linting** | Orphans, broken links, duplicate aliases, coverage gaps, stale captures |
+| 📊 **Dashboard** | `wiki_status` — counts, source states, recent activity |
+| 🤖 **Auto-update watch** | `wiki_watch` — schedule periodic discovery + ingest |
+| 📝 **Obsidian-friendly** | Folder-qualified wikilinks, stable source-ID citations, compatible vault |
+| 🛡️ **Guardrails** | Blocks direct edits to raw sources and generated metadata |
+| 🔧 **Configurable PDF extraction** | MarkItDown timeout via `WIKI_MARKITDOWN_TIMEOUT_MS` env var |
+| 🧪 **38+ tests, CI, CodeQL** | TypeScript, Vitest, Biome, Codecov |
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
+| `wiki_capture_source` | Capture a URL, local file, or pasted text into an immutable source packet |
+| `wiki_ingest` | Process uningested source packets into wiki pages (batch) |
+| `wiki_ensure_page` | Resolve or safely create entity / concept / synthesis / analysis pages |
+| `wiki_search` | Search the generated wiki registry |
+| `wiki_lint` | Deterministic health checks (orphans, gaps, contradictions, auto-fix) |
+| `wiki_status` | Show counts, source states, and recent activity |
+| `wiki_rebuild_meta` | Force a full metadata rebuild (registry, backlinks, index, log) |
+| `wiki_log_event` | Append a structured event to the wiki activity log |
+| `wiki_watch` | Schedule automatic wiki updates (daily / weekly / hourly) |
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/wiki-status` | Show a concise operational summary |
+| `/wiki-lint [mode]` | Run mechanical lint (`all`, `links`, `orphans`, `frontmatter`, `duplicates`, `coverage`, `staleness`) |
+| `/wiki-rebuild` | Force a full metadata rebuild |
+
+---
+
+## Quick Start (Detailed)
+
+### 1) Create a new wiki
+
+```bash
+mkdir my-wiki
+cd my-wiki
+pi
 ```
-/wiki-ingest
-/wiki-query What are the key patterns?
+
+Ask pi:
+
+```
+Initialize an llm wiki here for AI research.
 ```
 
-## What It Does
+This calls `wiki_bootstrap` and creates:
 
-| Tool                  | Purpose                                       |
-| --------------------- | --------------------------------------------- |
-| `wiki_bootstrap`      | Initialize a new wiki vault                   |
-| `wiki_capture_source` | Capture URL/file/text into immutable packet   |
-| `wiki_ingest`         | Process sources into wiki pages               |
-| `wiki_ensure_page`    | Create entity/concept/synthesis/analysis page |
-| `wiki_search`         | Search the wiki registry                      |
-| `wiki_lint`           | Health check (orphans, gaps, contradictions)  |
-| `wiki_status`         | Stats dashboard                               |
-| `wiki_rebuild_meta`   | Force metadata rebuild                        |
-| `wiki_log_event`      | Record custom event                           |
-| `wiki_watch`          | Schedule auto-updates                         |
+```
+raw/
+wiki/
+meta/
+.wiki/
+WIKI_SCHEMA.md
+```
 
-## Features
+### 2) Capture a source
 
-- **Configurable PDF extraction** — MarkItDown timeout adjustable via `WIKI_MARKITDOWN_TIMEOUT_MS` env var
-- **Smart content detection** — PDF bytes sniffed even from non-`.pdf` URLs, never written as markdown
-- **Original artifacts preserved** — URL captures save the fetched payload under `original/source.*`
-- **Clickable source links** — Captured URLs render as clickable Markdown links in source pages
-- **Reliable prompt forwarding** — Slash commands properly forward user arguments to the model
+```
+Capture this article into the wiki: https://example.com/some-article
+```
+
+```
+Capture this PDF into the wiki: ./papers/context-windows.pdf
+```
+
+```
+Capture these notes into the wiki: ...pasted text...
+```
+
+### 3) Integrate the source
+
+1. Capture the source
+2. Read `wiki/sources/SRC-*.md`
+3. Update that source page
+4. Search for impacted canonical pages with `wiki_search`
+5. Create missing pages with `wiki_ensure_page`
+6. Update concept / entity / synthesis pages with citations
+7. Mark the integration with `wiki_log_event kind=integrate`
+
+### 4) Query the wiki
+
+```
+Based on the wiki, what are the main tradeoffs between long-context models and RAG?
+```
+
+By default, query mode is **read-only**. To file a durable answer:
+
+```
+Answer the question and file the result as an analysis page.
+```
+
+---
+
+## Vault Layout
+
+```
+my-wiki/
+├─ raw/
+│  └─ sources/
+│     └─ SRC-2026-05-11-001/
+│        ├─ manifest.json
+│        ├─ original/           # Original artifact
+│        ├─ extracted.md        # Normalized text
+│        └─ attachments/
+├─ wiki/
+│  ├─ sources/                  # Source pages (what each source says)
+│  ├─ concepts/                 # Concepts and recurring ideas
+│  ├─ entities/                 # People, orgs, products, papers, systems
+│  ├─ syntheses/                # Cross-source theses and tensions
+│  └─ analyses/                 # Durable filed answers from queries
+├─ meta/
+│  ├─ registry.json             # Auto-generated search index
+│  ├─ backlinks.json
+│  ├─ index.md
+│  ├─ events.jsonl              # Append-only event log
+│  ├─ log.md
+│  └─ lint-report.md
+├─ .wiki/
+│  ├─ config.json
+│  └─ templates/
+└─ WIKI_SCHEMA.md
+```
+
+### Ownership Model
+
+| Path | Owner | Rule |
+|------|-------|------|
+| `raw/**` | Extension tools | Immutable after capture |
+| `wiki/**` | Model + user | Editable knowledge pages |
+| `meta/registry.json` | Extension | Generated |
+| `meta/backlinks.json` | Extension | Generated |
+| `meta/index.md` | Extension | Generated |
+| `meta/events.jsonl` | Extension / tool | Append-only |
+| `meta/log.md` | Extension | Generated from events |
+| `meta/lint-report.md` | Extension | Generated |
+| `WIKI_SCHEMA.md` | Human + explicit request | Operating manual |
+
+---
+
+## Linking & Citation Style
+
+### Internal Navigation
+
+```markdown
+[[concepts/retrieval-augmented-generation]]
+[[entities/openai|OpenAI]]
+[[syntheses/long-context-vs-rag]]
+```
+
+### Factual Citations
+
+```markdown
+[[sources/SRC-2026-04-04-001|SRC-2026-04-04-001]]
+```
+
+Stable source-page IDs keep provenance stable even if titles change.
+
+---
+
+## Guardrails
+
+The extension **blocks** direct tool-call edits to:
+
+- `raw/**` — immutable source artifacts
+- `meta/registry.json`
+- `meta/backlinks.json`
+- `meta/events.jsonl`
+- `meta/index.md`
+- `meta/log.md`
+- `meta/lint-report.md`
+
+If the model directly edits `wiki/**` using Pi's built-in `write` or `edit` tools, the extension **automatically rebuilds** generated metadata at the end of the agent turn.
+
+---
+
+## Source Packet Format
+
+Each captured source is stored as a structured packet:
+
+```
+raw/sources/SRC-YYYY-MM-DD-NNN/
+├─ manifest.json     # Capture metadata (title, URL, format, timestamp)
+├─ original/         # Original artifact (preserved as-is)
+├─ extracted.md      # Normalized text (PDF→md, XML→md, JSON→md, etc.)
+└─ attachments/      # Future attachment downloads
+```
+
+This preserves both the **original artifact** and a **normalized extracted view** for reading.
+
+---
+
+## Skill Behavior
+
+The bundled `llm-wiki` skill teaches the model to:
+
+- ❌ Never edit raw sources directly
+- ❌ Never edit generated metadata files
+- ✅ Capture first, integrate second
+- ✅ Search before creating new canonical pages
+- ✅ Cite facts using source-page IDs
+- ✅ Keep query mode read-only by default
+- ✅ Use "Tensions / caveats" and "Open questions" when evidence is mixed
+
+---
 
 ## Architecture
 
@@ -61,19 +272,27 @@ meta/                   # Auto-generated registry, backlinks, index, log
 .wiki/                  # Config and templates
 ```
 
-Read [docs/architecture.md](docs/architecture.md) for details.
+Read [docs/architecture.md](docs/architecture.md) for the full design document.
+
+---
 
 ## Documentation
 
-- [Architecture](docs/architecture.md) — How the four layers work
-- [Commands](docs/commands.md) — All slash commands and tools
-- [Obsidian Integration](docs/obsidian.md) — Vault setup and recommended plugins
-- [Configuration](docs/configuration.md) — Wiki modes, topics, settings
-- [API](docs/api.md) — Extension tool reference
+| Document | What it covers |
+|----------|---------------|
+| [Architecture](docs/architecture.md) | How the four layers work, ownership model |
+| [Commands](docs/commands.md) | All slash commands and tool reference |
+| [Obsidian Integration](docs/obsidian.md) | Vault setup and recommended plugins |
+| [Configuration](docs/configuration.md) | Wiki modes, topics, environment variables |
+| [API](docs/api.md) | Extension tool parameter reference |
+
+---
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, test patterns, and PR workflow.
+
+---
 
 ## Star History
 
@@ -88,7 +307,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ---
 
 <div align="center">
-  <sub>Built with ❤️ by <a href="https://github.com/zosmaai">zosmaai</a></sub>
+  <sub>Built with ❤️ by <a href="https://github.com/zosmaai">zosmaai</a> · </sub>
+  <a href="https://pi.dev">pi.dev</a> · <a href="https://github.com/zosmaai/pi-llm-wiki/issues">Issues</a>
 </div>
 
 ## License

package/extensions/llm-wiki/index.ts

@@ -1,5 +1,9 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { installGuardrails } from "./lib/guardrails.js";
+import { formatRecallContext, registerWikiRecall, searchWiki } from "./lib/recall.js";
+import { registerWikiRetro } from "./lib/retro.js";
 import {
   registerWikiBootstrap,
   registerWikiCaptureSource,
@@ -12,25 +16,22 @@ import {
   registerWikiStatus,
   registerWikiWatch,
 } from "./lib/tools.js";
+import { getVaultPaths, resolveVaultRoot } from "./lib/utils.js";
 
 /**
  * @zosmaai/pi-llm-wiki — LLM Wiki extension for Pi
  *
- * Registers 10 custom tools and installs guardrails:
- * - wiki_bootstrap      Initialize a new vault
- * - wiki_capture_source Capture URL/file/text into source packet
- * - wiki_ingest         Get batch of sources needing synthesis
- * - wiki_ensure_page    Create canonical page from template
- * - wiki_search         Search generated registry
- * - wiki_lint           Health check with auto-fix
- * - wiki_status         Instant stats from registry
- * - wiki_rebuild_meta   Force metadata rebuild
- * - wiki_log_event      Append event and regenerate log
- * - wiki_watch          Schedule auto-updates
+ * Registers 11 custom tools and installs guardrails:
+ * All 10 original tools + wiki_recall (auto-recall at session start)
  *
  * Guardrails:
  * - Blocks direct edits to raw/** and meta/**
  * - Auto-rebuilds metadata after wiki/** edits
+ *
+ * Auto-recall:
+ * - before_agent_start hook searches wiki for pages relevant to user prompt
+ * - Injects matching knowledge as system context
+ * - wiki_recall tool available for explicit deep searches
  */
 
 export default function (pi: ExtensionAPI) {
@@ -44,10 +45,36 @@ export default function (pi: ExtensionAPI) {
   registerWikiRebuildMeta(pi);
   registerWikiLogEvent(pi);
   registerWikiWatch(pi);
+  registerWikiRecall(pi);
+  registerWikiRetro(pi);
 
   installGuardrails(pi);
 
   pi.on("session_start", async (_event, ctx) => {
-    ctx.ui.setStatus("llm-wiki", "🧠 LLM Wiki (10 tools, guardrails active)");
+    ctx.ui.setStatus("llm-wiki", "🧠 LLM Wiki (11 tools, auto-recall active)");
+  });
+
+  // ─── Auto-recall hook ──────────────────────────────
+  // Before each agent turn, search the wiki for pages relevant
+  // to the user's prompt and inject them as system context.
+  pi.on("before_agent_start", async (event, _ctx) => {
+    const root = resolveVaultRoot(process.cwd());
+    if (!existsSync(join(root, ".wiki", "config.json"))) {
+      return; // No wiki vault — nothing to recall
+    }
+
+    const paths = getVaultPaths(root);
+    const prompt = event.prompt || "";
+    if (!prompt.trim()) return;
+
+    const results = searchWiki(paths, prompt);
+    if (results.length === 0) return;
+
+    const context = formatRecallContext(results);
+    if (!context) return;
+
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n${context}`,
+    };
   });
 }

package/extensions/llm-wiki/lib/recall.ts

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import type { Registry } from "./metadata.js";
+import { type VaultPaths, getVaultPaths, readJson, readText, resolveVaultRoot } from "./utils.js";
+
+// ─── Public API ────────────────────────────────────────
+
+export interface RecallResult {
+  /** Page identifier (folder-qualified, e.g. "concepts/rag") */
+  id: string;
+  /** Page title */
+  title: string;
+  /** Page type: source, entity, concept, synthesis, analysis */
+  type: string;
+  /** First N chars of page content for context */
+  preview: string;
+  /** Relative path from wiki root */
+  path: string;
+}
+
+/**
+ * Search the wiki registry for pages matching a query.
+ * Returns up to `maxResults` matches, each with a content preview.
+ */
+export function searchWiki(paths: VaultPaths, query: string, maxResults = 5): RecallResult[] {
+  const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
+    version: "1.0",
+    last_updated: "",
+    pages: {},
+  });
+
+  const q = query.toLowerCase();
+  const terms = q
+    .split(/\s+/)
+    .filter((t) => t.length > 2)
+    .slice(0, 10);
+
+  if (terms.length === 0) return [];
+
+  type Scored = { id: string; entry: Registry["pages"][string]; score: number };
+  const scored: Scored[] = [];
+
+  for (const [id, entry] of Object.entries(registry.pages)) {
+    let score = 0;
+    const title = String(entry.title || "").toLowerCase();
+    const type = String(entry.type || "").toLowerCase();
+
+    for (const term of terms) {
+      if (id.toLowerCase().includes(term)) score += 3;
+      if (title.includes(term)) score += 4;
+      if (type.includes(term)) score += 1;
+    }
+
+    // Boost if query terms appear in tags/categories
+    const tags = String(entry.tags || entry.category || entry.domain || "");
+    for (const term of terms) {
+      if (tags.toLowerCase().includes(term)) score += 2;
+    }
+
+    if (score > 0) {
+      scored.push({ id, entry, score });
+    }
+  }
+
+  scored.sort((a, b) => b.score - a.score);
+  const top = scored.slice(0, maxResults);
+
+  return top.map(({ id, entry }) => {
+    // Try to read page content for preview
+    let preview = "";
+    const pagePath = join(paths.wiki, `${id}.md`);
+    if (existsSync(pagePath)) {
+      const content = readFileSync(pagePath, "utf-8");
+      // Strip frontmatter
+      const body = content.replace(/^---[\s\S]*?---\n/, "").trim();
+      preview = body.slice(0, 200).replace(/\n/g, " ");
+    }
+
+    return {
+      id,
+      title: String(entry.title || id),
+      type: String(entry.type || "page"),
+      preview,
+      path: pagePath,
+    };
+  });
+}
+
+/**
+ * Format recall results as a compact system-prompt section.
+ */
+export function formatRecallContext(results: RecallResult[]): string {
+  if (results.length === 0) return "";
+
+  const lines: string[] = [
+    "## Relevant Wiki Knowledge",
+    "",
+    `_${results.length} page(s) matched your query — reviewed automatically by LLM Wiki._`,
+    "",
+  ];
+
+  for (const r of results) {
+    lines.push(`- **[[${r.id}]]** — *${r.type}* — ${r.title}`);
+    if (r.preview) {
+      // Truncate preview to one line
+      const preview = r.preview.length > 120 ? `${r.preview.slice(0, 120)}…` : r.preview;
+      lines.push(`  ${preview}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "Use `read` to view full pages. Add new findings via wiki_ensure_page or wiki_retro.",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+// ─── Tool Registration ──────────────────────────────────
+
+/**
+ * Register the `wiki_recall` tool.
+ * The model can call this explicitly to search the wiki.
+ * It is also called automatically via before_agent_start hook.
+ */
+export function registerWikiRecall(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "wiki_recall",
+    label: "Wiki Recall",
+    description:
+      "Search the wiki for pages relevant to a query. " +
+      "Returns matching page IDs, titles, types, and content previews. " +
+      "Called automatically at session start — use explicitly to dig deeper.",
+    promptSnippet: "Recall wiki knowledge relevant to the current task",
+    promptGuidelines: [
+      "Use wiki_recall at the START of every task to find relevant wiki knowledge.",
+      "The extension auto-calls wiki_recall — but calling it explicitly with specific terms gets better results.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({
+        description: "Search query — use the user's full request or key terms",
+      }),
+      max_results: Type.Optional(
+        Type.Number({ description: "Max results (default: 5, max: 10)", default: 5 }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const root = resolveVaultRoot(process.cwd());
+      const paths = getVaultPaths(root);
+
+      if (!existsSync(join(root, ".wiki", "config.json"))) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No wiki vault found at this location. Initialize one with wiki_bootstrap first.",
+            },
+          ],
+          details: { error: "no_vault" } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+
+      const maxResults = Math.min(params.max_results ?? 5, 10);
+      const results = searchWiki(paths, params.query, maxResults);
+
+      if (results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No wiki pages found matching "${params.query}". Use wiki_search for broader results.`,
+            },
+          ],
+          details: { query: params.query, matches: [] } as Record<string, unknown>,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `🧠 **${results.length} wiki page(s) relevant** to "${params.query}":`,
+              "",
+              ...results.map(
+                (r) =>
+                  `- [[${r.id}]] — *${r.type}* — ${r.title}${
+                    r.preview ? `\n  > ${r.preview.slice(0, 150)}` : ""
+                  }`,
+              ),
+              "",
+              "Use `read` on any page for full content.",
+              "Use `wiki_retro` to save new insights from this task.",
+            ].join("\n"),
+          },
+        ],
+        details: { query: params.query, matches: results.map((r) => r.id) } as Record<
+          string,
+          unknown
+        >,
+      };
+    },
+  });
+}