@zosmaai/pi-llm-wiki 0.11.2 → 0.11.3

package/CHANGELOG.md

@@ -18,6 +18,7 @@
 - **Personal wiki created at doubled path `~/.llm-wiki/.llm-wiki/…`**: `getPersonalWikiRoot()` returned the dot-dir itself (`~/.llm-wiki`) while `getVaultPaths()` then appended another `.llm-wiki/` segment, so the personal vault was written to `~/.llm-wiki/.llm-wiki/wiki/…`. Fixed by aligning `getPersonalWikiRoot()` with the same "root = parent of `.llm-wiki/`" contract used by project vaults. `WIKI_HOME` continues to override the parent.
 
 ### Added
+- **`wiki_bootstrap` over MCP, so MCP-only clients can create a vault** (Issue #130): the README aims the standalone MCP server at Claude Code, Cursor and Windsurf — clients with no access to the Pi extension — yet all five MCP tools failed closed with `No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.`, naming a tool those clients did not have. Short of installing pi or hand-building the `.llm-wiki/` tree, there was no path to a working vault. `bootstrapVault()` is pure Node (`node:fs`, `node:path`, sibling lib modules) with no model and no credentials in play, so it is now exposed as a sixth MCP tool through a thin `bootstrapOperation` adapter, keeping Pi and MCP over one implementation. Bootstrap resolves its target with `getVaultPaths(WIKI_ROOT)` rather than the usual `resolveVaultPaths()`: resolution deliberately walks up to a parent vault and then falls back to the personal vault, which is right for reading and writing pages but would create the vault somewhere other than where the client pointed the server. There is no `root` parameter, so the server stays confined to its configured root, and `mode` accepts the same free-form `personal`/`company` string the Pi tool takes. Re-running is safe: an existing vault has its config updated and metadata rebuilt, and pages are untouched. The two guards on the MCP surface (`test/mcp-parity.test.ts` and `test/mcp-package.test.ts`) were deliberately widened from five tools to six, `scripts/mcp-smoke.mjs` now requires the tool on the packed artifact, and every README's MCP table lists it.
 - **Visible wiki activity + background/reported mutations** (Issue #77): the wiki was effectively invisible — recall was appended only to the **system prompt**, the observe/retro reminder was sent with `display: false`, and the lone user-facing cue was a static status line. The wiki now surfaces what it does, and mutating work is pushed off the agent's critical path.
   - **Visible surfaces**: a one-time **session notice** (`buildSessionNotice`) announces the full loop — retrieval (recall → `wiki_search` → `read`, all synchronous because the LLM consumes their output) and capture (`wiki_observe` → `wiki_retro`, background + reported); the periodic reminder is now `display: true` and names **both** capture tools (`buildReminderText`); and the status line becomes **recall-aware** (`🧠 LLM Wiki — recalled N page(s) for this task`) when auto-recall matches.
   - **Background + reported principle**: only `wiki_search` / `read` / `wiki_recall` stay synchronous. Heavy mutations — `wiki_rebuild_meta`, `wiki_reindex_embeddings`, `wiki_lint` — now dispatch to the background runtime and **report a visible completion message** instead of blocking the turn; `wiki_ingest` gained a persistent completion report alongside its toast. New `Runtime.report()` / `Runtime.launchReported()` primitives and a `dispatchReported()` tool helper (with a synchronous fallback when no runtime is available, preserving prior behavior and unit tests).

package/README.de.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
 
-The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.es.md

@@ -330,10 +330,11 @@ Esto preserva tanto el **artefacto original** como una **vista extraída normali
 
 Usa el wiki desde **cualquier herramienta compatible con MCP** — Claude Code, Cursor, Windsurf y otras.
 
-El paquete incluye un servidor MCP independiente que expone 5 herramientas de wiki por stdio:
+El paquete incluye un servidor MCP independiente que expone 6 herramientas de wiki por stdio:
 
 | Herramienta | Descripción |
 |-------------|-------------|
+| `wiki_bootstrap` | Inicializa un nuevo vault de wiki con configuración, plantillas, esquema y metadatos |
 | `wiki_recall` | Busca en el wiki páginas relevantes para la tarea |
 | `wiki_search` | Búsqueda completa del registro |
 | `wiki_status` | Estadísticas del wiki (conteos de páginas, desglose por tipo) |

package/README.fr.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
 
-The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.hi.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
 
-The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.ja.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
 
-The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.ko.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
 
-The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.md

@@ -342,10 +342,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
 
-The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |
@@ -480,6 +481,13 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>James Fraser</b></sub>
                 </a>
             </td>
+            <td align="center">
+                <a href="https://github.com/mkuhl">
+                    <img src="https://avatars.githubusercontent.com/u/61073?v=4" width="64;" alt="mkuhl"/>
+                    <br />
+                    <sub><b>Mike P. Kuhl</b></sub>
+                </a>
+            </td>
             <td align="center">
                 <a href="https://github.com/CelestialCreator">
                     <img src="https://avatars.githubusercontent.com/u/177931942?v=4" width="64;" alt="CelestialCreator"/>
@@ -501,13 +509,6 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>Daniel Naab</b></sub>
                 </a>
             </td>
-            <td align="center">
-                <a href="https://github.com/mkuhl">
-                    <img src="https://avatars.githubusercontent.com/u/61073?v=4" width="64;" alt="mkuhl"/>
-                    <br />
-                    <sub><b>Mike P. Kuhl</b></sub>
-                </a>
-            </td>
             <td align="center">
                 <a href="https://github.com/deestax">
                     <img src="https://avatars.githubusercontent.com/u/152369481?v=4" width="64;" alt="deestax"/>

package/README.pt.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
 
-The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.ru.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
 
-The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.zh.md

@@ -330,10 +330,11 @@ my-wiki/
 
 从 **任何 MCP 兼容工具** 使用 wiki——Claude Code、Cursor、Windsurf 等。
 
-包附带独立 MCP 服务器，通过 stdio 暴露 5 个 wiki 工具：
+包附带独立 MCP 服务器，通过 stdio 暴露 6 个 wiki 工具：
 
 | 工具 | 描述 |
 |------|------|
+| `wiki_bootstrap` | 用配置、模板、模式和元数据初始化新的 wiki vault |
 | `wiki_recall` | 搜索 wiki 中与任务相关的页面 |
 | `wiki_search` | 完整注册表搜索 |
 | `wiki_status` | Wiki 统计（页面计数、类型分解） |

package/dist/extensions/llm-wiki/lib/runtime.js

@@ -143,9 +143,21 @@ export class Runtime {
      */
     launchReported(ctx, label, work) {
         return this.launchTask(ctx, label, async () => {
+            // Capture synchronously — after `await work()` the extension ctx may be
+            // a stale proxy (newSession/fork/switchSession/reload) and accessing
+            // ctx.hasUI or ctx.ui on it throws (see launchTask).
+            const hasUI = ctx.hasUI;
+            const ui = ctx.ui;
             const summary = await work();
-            if (summary)
+            if (summary) {
+                // Instant completion feedback: the nextTurn report below is queued for
+                // the next user prompt, so without a toast a background task looks
+                // stuck. Mirrors the failure notification in launchTask and the
+                // success toast already used by wiki_ingest.
+                if (hasUI && ui)
+                    ui.notify(summary.split("\n")[0].replace(/\*\*/g, ""), "info");
                 this.report(summary);
+            }
         });
     }
     /**

package/dist/extensions/llm-wiki/lib/tools.js

@@ -694,7 +694,7 @@ export function registerWikiLint(pi, runtime) {
             // run it in the background and report the health summary (issue #77).
             return dispatchReported(runtime, ctx, {
                 label: `lint:${paths.root}`,
-                started: "\u{1F9F9} LLM Wiki: lint started in the background — the health report will be posted when it completes.",
+                started: "\u{1F9F9} LLM Wiki: lint started in the background — the health report will be posted with your next message.",
                 work: async () => runWikiLint(paths, params.auto_fix === true),
             });
         },
@@ -827,11 +827,14 @@ function runWikiLint(paths, autoFix) {
         "",
     ].filter(Boolean);
     const reportPath = autoFix ? join(paths.outputs, `lint-${fmtDate()}.md`) : undefined;
+    // The gap snapshot is generated discovery metadata consumed by wiki_status:
+    // persist it on every successful lint so status never reports a stale count.
+    // Corrective actions below (report, event, meta rebuild) stay autoFix-only.
+    writeJson(join(paths.discoveries, "gaps.json"), {
+        gaps,
+        generated: new Date().toISOString(),
+    });
     if (autoFix && reportPath) {
-        writeJson(join(paths.discoveries, "gaps.json"), {
-            gaps,
-            generated: new Date().toISOString(),
-        });
         mkdirSync(paths.outputs, { recursive: true });
         writeFileSync(reportPath, `${reportLines.join("\n")}\n`, "utf8");
         appendEvent(paths, {
@@ -954,7 +957,7 @@ export function registerWikiRebuildMeta(pi, runtime) {
             // report on completion (issue #77).
             return dispatchReported(runtime, ctx, {
                 label: `rebuild_meta:${paths.root}`,
-                started: "\u{1F9E0} LLM Wiki: metadata rebuild started in the background — the result will be reported when it completes.",
+                started: "\u{1F9E0} LLM Wiki: metadata rebuild started in the background — the result will be reported with your next message.",
                 work: async () => {
                     const result = rebuildMetadata(paths);
                     // No rebuild_meta event — rebuild is a projection, not an authoritative mutation
@@ -1027,7 +1030,7 @@ export function registerWikiReindexEmbeddings(pi, runtime) {
             // report the stats on completion (issue #77).
             return dispatchReported(runtime, ctx, {
                 label: `reindex_embeddings:${paths.root}`,
-                started: `\u{1F9E0} LLM Wiki: embedding reindex started in the background (${embedder.model}) — stats will be reported when it completes.`,
+                started: `\u{1F9E0} LLM Wiki: embedding reindex started in the background (${embedder.model}) — stats will be reported with your next message.`,
                 details: { enabled: true, model: embedder.model },
                 work: async () => {
                     const stats = await reindexEmbeddings(paths, embedder, { force: params.force === true });

package/dist/mcp/index.js

@@ -13,9 +13,9 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
-import { resolveVaultPaths } from "../extensions/llm-wiki/lib/utils.js";
+import { getVaultPaths, resolveVaultPaths } from "../extensions/llm-wiki/lib/utils.js";
 import { createExecApi } from "./exec.js";
-import { captureSourceOperation, recallOperation, retroOperation, searchOperation, statusOperation, } from "./operations.js";
+import { bootstrapOperation, captureSourceOperation, recallOperation, retroOperation, searchOperation, statusOperation, } from "./operations.js";
 const execApi = createExecApi();
 // ─── Vault Detection ────────────────────────────────────
 /** Resolve vault paths, same as Pi extension. */
@@ -23,6 +23,18 @@ function getPaths() {
     const root = process.env.WIKI_ROOT || process.cwd();
     return resolveVaultPaths(root);
 }
+/**
+ * The vault root this server was configured with, without resolution.
+ *
+ * `getPaths()` RESOLVES an existing vault: on a root that has none it walks up
+ * to a parent vault and then falls back to the personal vault. That is right
+ * for reading and writing pages, and wrong for creating one — bootstrap must
+ * create the vault where the client pointed the server, not wherever
+ * resolution lands. The Pi tool draws the same distinction.
+ */
+function getConfiguredPaths() {
+    return getVaultPaths(process.env.WIKI_ROOT || process.cwd());
+}
 function hasVault() {
     const paths = getPaths();
     return existsSync(join(paths.dotWiki, "config.json"));
@@ -32,9 +44,49 @@ const server = new McpServer({
     name: "llm-wiki",
     version: "1.0.0",
 });
+// ---- wiki_bootstrap ----
+//
+// Registered first, and the only tool not gated on an existing vault: the
+// other five fail closed with a message naming this one, which an MCP-only
+// client could not act on while it was extension-only (issue #130).
+server.registerTool("wiki_bootstrap", {
+    description: "Create an LLM Wiki vault at this server's wiki root (WIKI_ROOT, or the working directory). Writes config, schema, templates and metadata scaffolding. Run this first when no vault exists; safe to re-run on an existing vault, where it updates the config and rebuilds metadata without touching pages.",
+    inputSchema: z.object({
+        topic: z.string().describe("Main topic of the wiki"),
+        mode: z.string().optional().describe("personal or company (default: personal)"),
+    }),
+}, async ({ topic, mode }) => {
+    const paths = getConfiguredPaths();
+    const result = await bootstrapOperation(paths, { topic, mode });
+    if (!result.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Vault error: ${result.diagnostics[0].message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const warnings = result.diagnostics.map((d) => `⚠️ ${d.code}: ${d.message}`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: [
+                    `${result.created ? "Wiki vault created" : "Wiki vault updated"} at ${paths.root}`,
+                    "Structure: .llm-wiki/{raw,wiki,meta} plus config and WIKI_SCHEMA.md",
+                    "Next: capture a source with wiki_capture_source, or save an insight with wiki_retro.",
+                    ...warnings,
+                ].join("\n"),
+            },
+        ],
+    };
+});
 // ---- wiki_recall ----
 server.registerTool("wiki_recall", {
-    description: "Search the wiki for pages relevant to a query. Returns matching page IDs, titles, types, and content previews.",
+    description: "Search the wiki for pages relevant to a query. Searches the resolved vault and the personal vault (~/.llm-wiki) together, deduplicated, with personal hits labelled. Returns matching page IDs, titles, types, and content previews.",
     inputSchema: z.object({
         query: z.string().describe("Search query — use the user's full request or key terms"),
         max_results: z.number().optional().default(5).describe("Max results (default: 5, max: 10)"),

package/dist/mcp/operations.js

@@ -5,8 +5,9 @@
  * used by Pi tools. No operation parses YAML, scans files, scores
  * registry entries, or builds page strings itself.
  */
+import { bootstrapVault } from "../extensions/llm-wiki/lib/bootstrap.js";
 import { rebuildMetadata } from "../extensions/llm-wiki/lib/metadata.js";
-import { searchWiki } from "../extensions/llm-wiki/lib/recall.js";
+import { searchWikiLayered } from "../extensions/llm-wiki/lib/recall.js";
 import { saveInsight } from "../extensions/llm-wiki/lib/retro.js";
 import { captureFile, captureText, captureUrl } from "../extensions/llm-wiki/lib/source-packet.js";
 import { VaultWriteError, inspectVaultFormat, inspectWritableVault, } from "../extensions/llm-wiki/lib/vault-format.js";
@@ -19,9 +20,44 @@ function projectionOutcome(projection) {
             diagnostics: projection.diagnostics.map(({ code, message }) => ({ code, message })),
         };
 }
-/** Shared recall operation: calls searchWiki and appends vault diagnostics. */
+/**
+ * Shared bootstrap operation: create (or update) the vault at `paths`.
+ *
+ * This is the one operation that must work when no vault exists — every other
+ * one fails closed naming it. `bootstrapVault` is pure Node (`node:fs`,
+ * `node:path` and sibling lib modules), so it needs no model and no
+ * credentials, which is what makes it fit the MCP surface.
+ *
+ * A failed projection rebuild is reported as diagnostics alongside `ok: true`:
+ * the vault has been written to disk by then, and `wiki_lint` is the repair
+ * path, so failing the call outright would misreport what happened.
+ */
+export async function bootstrapOperation(paths, input) {
+    const result = bootstrapVault(paths, { topic: input.topic, mode: input.mode ?? "personal" });
+    if (!result.ok) {
+        return {
+            ok: false,
+            diagnostics: result.diagnostics.map(({ code, message }) => ({ code, message })),
+        };
+    }
+    const projection = projectionOutcome(result.projection);
+    return {
+        ok: true,
+        created: result.created,
+        diagnostics: projection.ok ? [] : projection.diagnostics,
+    };
+}
+/**
+ * Shared recall operation: layered search plus vault diagnostics.
+ *
+ * Layering is the shared contract, not an extension-only feature: MCP clients
+ * get the same personal + project merge the Pi `wiki_recall` tool does.
+ * `searchWikiLayered` appends personal-vault hits, deduplicates by page ID and
+ * tags personal results with `vaultLabel`. It is a no-op when no personal vault
+ * exists, or when the resolved vault IS the personal vault.
+ */
 export async function recallOperation(paths, query, maxResults = 5) {
-    const results = searchWiki(paths, query, maxResults);
+    const results = searchWikiLayered(paths, query, maxResults);
     const vaultState = inspectVaultFormat(paths);
     return {
         results,

package/docs/api.md

@@ -223,6 +223,10 @@ Deterministic health check of the wiki. Scans for orphan pages (no inbound links
 (linked but not created), and contradiction markers. Optionally auto-creates stub pages for
 knowledge gaps cited in two or more pages.
 
+Runs **asynchronously**: the tool acknowledges immediately and scans off-thread. On completion a
+UI toast fires instantly (when a UI is available) and the full health report is delivered with
+the next user message.
+
 **Parameters**
 
 | Name | Type | Required | Description |
@@ -277,9 +281,13 @@ Health is `"⚠️ Warning"` when orphan count exceeds 5, `"🔴 Empty"` when th
 
 ## wiki_rebuild_meta
 
-Force a full synchronous rebuild of all generated metadata: `registry.json`, `backlinks.json`,
+Force a full rebuild of all generated metadata: `registry.json`, `backlinks.json`,
 `index.md`, `log.md`. Use when metadata appears out of sync with actual wiki files.
 
+Runs **asynchronously**: the tool acknowledges immediately and rebuilds off-thread. On completion
+a UI toast fires instantly (when a UI is available) and the result is delivered with the next
+user message.
+
 If `meta/events.jsonl` is missing or unreadable, rebuild reports a warning and preserves existing log projections while continuing to rebuild registry, backlinks, and indexes. A present zero-byte event file is an intentional empty history.
 
 **Parameters**

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

@@ -213,8 +213,20 @@ export class Runtime {
    */
   launchReported(ctx: LaunchCtx, label: string, work: () => Promise<string | null>): Promise<void> {
     return this.launchTask(ctx, label, async () => {
+      // Capture synchronously — after `await work()` the extension ctx may be
+      // a stale proxy (newSession/fork/switchSession/reload) and accessing
+      // ctx.hasUI or ctx.ui on it throws (see launchTask).
+      const hasUI = ctx.hasUI;
+      const ui = ctx.ui;
       const summary = await work();
-      if (summary) this.report(summary);
+      if (summary) {
+        // Instant completion feedback: the nextTurn report below is queued for
+        // the next user prompt, so without a toast a background task looks
+        // stuck. Mirrors the failure notification in launchTask and the
+        // success toast already used by wiki_ingest.
+        if (hasUI && ui) ui.notify(summary.split("\n")[0].replace(/\*\*/g, ""), "info");
+        this.report(summary);
+      }
     });
   }
 

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

@@ -821,7 +821,7 @@ export function registerWikiLint(pi: ExtensionAPI, runtime?: Runtime): void {
       return dispatchReported(runtime, ctx as ToolCtx, {
         label: `lint:${paths.root}`,
         started:
-          "\u{1F9F9} LLM Wiki: lint started in the background — the health report will be posted when it completes.",
+          "\u{1F9F9} LLM Wiki: lint started in the background — the health report will be posted with your next message.",
         work: async () => runWikiLint(paths, params.auto_fix === true),
       });
     },
@@ -962,11 +962,14 @@ function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
     "",
   ].filter(Boolean);
   const reportPath = autoFix ? join(paths.outputs, `lint-${fmtDate()}.md`) : undefined;
+  // The gap snapshot is generated discovery metadata consumed by wiki_status:
+  // persist it on every successful lint so status never reports a stale count.
+  // Corrective actions below (report, event, meta rebuild) stay autoFix-only.
+  writeJson(join(paths.discoveries, "gaps.json"), {
+    gaps,
+    generated: new Date().toISOString(),
+  });
   if (autoFix && reportPath) {
-    writeJson(join(paths.discoveries, "gaps.json"), {
-      gaps,
-      generated: new Date().toISOString(),
-    });
     mkdirSync(paths.outputs, { recursive: true });
     writeFileSync(reportPath, `${reportLines.join("\n")}\n`, "utf8");
     appendEvent(paths, {
@@ -1106,7 +1109,7 @@ export function registerWikiRebuildMeta(pi: ExtensionAPI, runtime?: Runtime): vo
       return dispatchReported(runtime, ctx as ToolCtx, {
         label: `rebuild_meta:${paths.root}`,
         started:
-          "\u{1F9E0} LLM Wiki: metadata rebuild started in the background — the result will be reported when it completes.",
+          "\u{1F9E0} LLM Wiki: metadata rebuild started in the background — the result will be reported with your next message.",
         work: async () => {
           const result = rebuildMetadata(paths);
           // No rebuild_meta event — rebuild is a projection, not an authoritative mutation
@@ -1187,7 +1190,7 @@ export function registerWikiReindexEmbeddings(pi: ExtensionAPI, runtime?: Runtim
       // report the stats on completion (issue #77).
       return dispatchReported(runtime, ctx as ToolCtx, {
         label: `reindex_embeddings:${paths.root}`,
-        started: `\u{1F9E0} LLM Wiki: embedding reindex started in the background (${embedder.model}) — stats will be reported when it completes.`,
+        started: `\u{1F9E0} LLM Wiki: embedding reindex started in the background (${embedder.model}) — stats will be reported with your next message.`,
         details: { enabled: true, model: embedder.model },
         work: async () => {
           const stats = await reindexEmbeddings(paths, embedder, { force: params.force === true });

package/mcp/index.ts

@@ -15,9 +15,10 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
-import { resolveVaultPaths } from "../extensions/llm-wiki/lib/utils.js";
+import { getVaultPaths, resolveVaultPaths } from "../extensions/llm-wiki/lib/utils.js";
 import { createExecApi } from "./exec.js";
 import {
+  bootstrapOperation,
   captureSourceOperation,
   recallOperation,
   retroOperation,
@@ -35,6 +36,19 @@ function getPaths(): ReturnType<typeof resolveVaultPaths> {
   return resolveVaultPaths(root);
 }
 
+/**
+ * The vault root this server was configured with, without resolution.
+ *
+ * `getPaths()` RESOLVES an existing vault: on a root that has none it walks up
+ * to a parent vault and then falls back to the personal vault. That is right
+ * for reading and writing pages, and wrong for creating one — bootstrap must
+ * create the vault where the client pointed the server, not wherever
+ * resolution lands. The Pi tool draws the same distinction.
+ */
+function getConfiguredPaths(): ReturnType<typeof getVaultPaths> {
+  return getVaultPaths(process.env.WIKI_ROOT || process.cwd());
+}
+
 function hasVault(): boolean {
   const paths = getPaths();
   return existsSync(join(paths.dotWiki, "config.json"));
@@ -47,13 +61,62 @@ const server = new McpServer({
   version: "1.0.0",
 });
 
+// ---- wiki_bootstrap ----
+//
+// Registered first, and the only tool not gated on an existing vault: the
+// other five fail closed with a message naming this one, which an MCP-only
+// client could not act on while it was extension-only (issue #130).
+
+server.registerTool(
+  "wiki_bootstrap",
+  {
+    description:
+      "Create an LLM Wiki vault at this server's wiki root (WIKI_ROOT, or the working directory). Writes config, schema, templates and metadata scaffolding. Run this first when no vault exists; safe to re-run on an existing vault, where it updates the config and rebuilds metadata without touching pages.",
+    inputSchema: z.object({
+      topic: z.string().describe("Main topic of the wiki"),
+      mode: z.string().optional().describe("personal or company (default: personal)"),
+    }),
+  },
+  async ({ topic, mode }) => {
+    const paths = getConfiguredPaths();
+    const result = await bootstrapOperation(paths, { topic, mode });
+
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Vault error: ${result.diagnostics[0].message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const warnings = result.diagnostics.map((d) => `⚠️ ${d.code}: ${d.message}`);
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: [
+            `${result.created ? "Wiki vault created" : "Wiki vault updated"} at ${paths.root}`,
+            "Structure: .llm-wiki/{raw,wiki,meta} plus config and WIKI_SCHEMA.md",
+            "Next: capture a source with wiki_capture_source, or save an insight with wiki_retro.",
+            ...warnings,
+          ].join("\n"),
+        },
+      ],
+    };
+  },
+);
+
 // ---- wiki_recall ----
 
 server.registerTool(
   "wiki_recall",
   {
     description:
-      "Search the wiki for pages relevant to a query. Returns matching page IDs, titles, types, and content previews.",
+      "Search the wiki for pages relevant to a query. Searches the resolved vault and the personal vault (~/.llm-wiki) together, deduplicated, with personal hits labelled. Returns matching page IDs, titles, types, and content previews.",
     inputSchema: z.object({
       query: z.string().describe("Search query — use the user's full request or key terms"),
       max_results: z.number().optional().default(5).describe("Max results (default: 5, max: 10)"),

package/mcp/operations.ts

@@ -7,8 +7,9 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { bootstrapVault } from "../extensions/llm-wiki/lib/bootstrap.js";
 import { type ProjectionResult, rebuildMetadata } from "../extensions/llm-wiki/lib/metadata.js";
-import { searchWiki } from "../extensions/llm-wiki/lib/recall.js";
+import { type RecallResult, searchWikiLayered } from "../extensions/llm-wiki/lib/recall.js";
 import { saveInsight } from "../extensions/llm-wiki/lib/retro.js";
 import { captureFile, captureText, captureUrl } from "../extensions/llm-wiki/lib/source-packet.js";
 import type { VaultPaths } from "../extensions/llm-wiki/lib/utils.js";
@@ -30,16 +31,58 @@ function projectionOutcome(
       };
 }
 
-/** Shared recall operation: calls searchWiki and appends vault diagnostics. */
+/**
+ * Shared bootstrap operation: create (or update) the vault at `paths`.
+ *
+ * This is the one operation that must work when no vault exists — every other
+ * one fails closed naming it. `bootstrapVault` is pure Node (`node:fs`,
+ * `node:path` and sibling lib modules), so it needs no model and no
+ * credentials, which is what makes it fit the MCP surface.
+ *
+ * A failed projection rebuild is reported as diagnostics alongside `ok: true`:
+ * the vault has been written to disk by then, and `wiki_lint` is the repair
+ * path, so failing the call outright would misreport what happened.
+ */
+export async function bootstrapOperation(
+  paths: VaultPaths,
+  input: { topic: string; mode?: string },
+): Promise<
+  | { ok: true; created: boolean; diagnostics: Array<{ code: string; message: string }> }
+  | { ok: false; diagnostics: Array<{ code: string; message: string }> }
+> {
+  const result = bootstrapVault(paths, { topic: input.topic, mode: input.mode ?? "personal" });
+  if (!result.ok) {
+    return {
+      ok: false,
+      diagnostics: result.diagnostics.map(({ code, message }) => ({ code, message })),
+    };
+  }
+  const projection = projectionOutcome(result.projection);
+  return {
+    ok: true,
+    created: result.created,
+    diagnostics: projection.ok ? [] : projection.diagnostics,
+  };
+}
+
+/**
+ * Shared recall operation: layered search plus vault diagnostics.
+ *
+ * Layering is the shared contract, not an extension-only feature: MCP clients
+ * get the same personal + project merge the Pi `wiki_recall` tool does.
+ * `searchWikiLayered` appends personal-vault hits, deduplicates by page ID and
+ * tags personal results with `vaultLabel`. It is a no-op when no personal vault
+ * exists, or when the resolved vault IS the personal vault.
+ */
 export async function recallOperation(
   paths: VaultPaths,
   query: string,
   maxResults = 5,
 ): Promise<{
-  results: Array<{ id: string; title: string; type: string; preview?: string }>;
+  results: RecallResult[];
   diagnostics: Array<{ code: string; message: string }>;
 }> {
-  const results = searchWiki(paths, query, maxResults);
+  const results = searchWikiLayered(paths, query, maxResults);
   const vaultState = inspectVaultFormat(paths);
   return {
     results,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "Self-maintaining LLM Wiki for Pi — Karpathy-pattern knowledge base with immutable source capture, automated ingestion, search, linting, and Obsidian-compatible vault. auto-updating personal & company wiki.",
   "keywords": [
     "pi",