@zosmaai/pi-llm-wiki 0.11.1 → 0.11.3

package/CHANGELOG.md

@@ -3,6 +3,9 @@
 ## [Unreleased]
 
 ### Fixed
+- **MCP server failed to start on `@modelcontextprotocol/server` 2.0.0** (Issue #128): `mcp/index.ts` imported `StdioServerTransport` from the package root, but SDK 2.0.0 (published 2026-07-27) moved that export to the `./stdio` subpath, so `node dist/mcp/index.js` died with `SyntaxError: The requested module '@modelcontextprotocol/server' does not provide an export named 'StdioServerTransport'` before the transport ever connected. The declared range `^2.0.0-alpha.2` is a caret range over a prerelease, so it permits `2.0.0`: every fresh consumer install resolved the stable SDK against the pre-stable import, while `pnpm-lock.yaml` pinned the `2.0.0-alpha.2` floor — so `test/mcp-package.test.ts`, which does spawn the published command and complete the stdio handshake, only ever exercised the alpha where the root export still existed. Fixed by importing `StdioServerTransport` from `@modelcontextprotocol/server/stdio` (the `./stdio` subpath does not exist in `2.0.0-alpha.2`, so the range, the lockfile and the import move together), raising the range to `^2.0.0`, and refreshing the lockfile so the existing smoke test now runs against the SDK consumers actually get.
+- **Packaged MCP server was never exercised with consumer-resolved dependencies**: a new `packaged-mcp-consumer` CI job packs the tarball, installs it into a directory with **no lockfile**, prints the resolved SDK version, and runs `scripts/mcp-smoke.mjs` — the stdio handshake (`initialize` → `tools/list`) — against that install. This closes the whole class of failure behind Issue #128: a dependency range that resolves differently for consumers than for this repo's lockfile can no longer break the published server undetected.
+- **README documented a standalone MCP command that ships no JavaScript** (Issue #129): all ten READMEs pointed MCP clients at `node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js`, but the published `mcp/` directory contains only TypeScript (`index.ts`, `exec.ts`, `operations.ts`), so the documented command failed with `MODULE_NOT_FOUND` — independently of any dependency-resolution problem. The runnable entry is `dist/mcp/index.js`, which the package's own `pi.mcpservers` manifest already declared correctly. Every README now documents that path and adds an `mcpServers` config block for `.mcp.json` / `claude_desktop_config.json` using **absolute** paths, because MCP clients spawn the command without a shell: a `~` in `args` or `env` is passed through literally and the server fails to start behind a generic connection error. A new `test/package-structure.test.ts` case derives the expected path from `pi.mcpservers` — the same command `test/mcp-package.test.ts` spawns and handshakes with — and asserts every documented `…/mcp/index.js` occurrence in every README resolves to it, so docs cannot drift from the runnable entry point again.
 - **Authoritative activity history**: `meta/events.jsonl` is now documented as durable append-only extension state rather than rebuildable metadata. Missing or unreadable event sources warn and preserve existing Markdown logs while unrelated projections continue rebuilding.
 - **Portable log privacy**: local-file capture events no longer duplicate caller-supplied filesystem paths into `events.jsonl` or OKF `wiki/log.md`; exact paths remain in extension-owned raw manifests.
 - **Vault layout migration safety and packaging**: `scripts/migrate-llm-wiki.js` now runs on the minimum supported Node 18 runtime, accepts absolute or relative roots regardless of flag order, reserves the destination root atomically, uses no-clobber file moves, rejects destination collisions before moving data, and ships in the npm package. A durable journal records source hashes and completed moves so an interrupted migration resumes safely; file and directory durability boundaries are flushed before completion. Black-box tests cover paths with spaces, dry-run immutability, hash-preserving apply, idempotency, preflight/raced collisions, real subprocess `SIGKILL` recovery, doubled-layout recovery, packed-artifact contents, and packed execution on Node 18.
@@ -15,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) |
@@ -363,11 +364,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Skill-Verhalten

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) |
@@ -347,11 +348,29 @@ El paquete incluye un servidor MCP independiente que expone 5 herramientas de wi
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Independiente con cualquier cliente MCP:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Establece `WIKI_ROOT` en el directorio de tu vault de wiki. Si no está establecido, el servidor lo detecta automáticamente desde el directorio de trabajo actual.
 
+### Configuración del cliente
+
+El mismo servidor como entrada en `.mcp.json` (Claude Code) o `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> Los clientes MCP lanzan el comando **sin shell**, por lo que `~` nunca se expande. Un `~/my-wiki` en `args` o `env` se pasa literalmente y el servidor no arranca, algo que el cliente solo informa como un error de conexión genérico: usa rutas absolutas aquí. El fragmento de shell anterior sí funciona, porque tu shell expande `~` antes de que `node` lo reciba.
+
 ---
 
 ## Comportamiento de la Habilidad

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) |
@@ -363,11 +364,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Comportement de la Compétence

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) |
@@ -363,11 +364,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## स्किल व्यवहार

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) |
@@ -363,11 +364,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## スキルの動作

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) |
@@ -363,11 +364,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## 스킬 동작

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) |
@@ -359,11 +360,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Skill Behavior
@@ -462,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"/>
@@ -490,6 +516,8 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>Superdao</b></sub>
                 </a>
             </td>
+		</tr>
+		<tr>
             <td align="center">
                 <a href="https://github.com/mystery4f">
                     <img src="https://avatars.githubusercontent.com/u/40482524?v=4" width="64;" alt="mystery4f"/>

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) |
@@ -363,11 +364,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Comportamento da Skill

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) |
@@ -363,11 +364,29 @@ The package ships a standalone MCP server exposing 5 wiki tools over stdio:
 pi install npm:@zosmaai/pi-llm-wiki
 
 # Standalone with any MCP client:
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
 
+### Client configuration
+
+The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP clients spawn the command **without a shell**, so `~` is never expanded. A `~/my-wiki` in `args` or `env` is passed through literally and the server fails to start, which the client reports only as a generic connection error — use absolute paths here. The shell snippet above is fine: your shell expands `~` before `node` sees it.
+
 ---
 
 ## Поведение навыка

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 统计（页面计数、类型分解） |
@@ -347,11 +348,29 @@ my-wiki/
 pi install npm:@zosmaai/pi-llm-wiki
 
 # 独立使用任何 MCP 客户端：
-WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js
 ```
 
 设置 `WIKI_ROOT` 为您的 wiki vault 目录。如果未设置，服务器从当前工作目录自动检测。
 
+### 客户端配置
+
+在 `.mcp.json`（Claude Code）或 `claude_desktop_config.json` 中配置同一个服务器：
+
+```json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
+    }
+  }
+}
+```
+
+> MCP 客户端在**不经过 shell** 的情况下启动该命令，因此 `~` 不会被展开。`args` 或 `env` 中的 `~/my-wiki` 会被原样传递，服务器随即启动失败，而客户端只会报告一个笼统的连接错误——这里请使用绝对路径。上面的 shell 命令没有问题：`~` 由你的 shell 在 `node` 收到之前展开。
+
 ---
 
 ## 技能行为

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

@@ -10,11 +10,12 @@
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
+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. */
@@ -22,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"));
@@ -31,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

@@ -12,11 +12,13 @@
 
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
+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,
@@ -34,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"));
@@ -46,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.1",
+  "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",
@@ -73,7 +73,7 @@
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "@modelcontextprotocol/server": "^2.0.0",
     "mdast-util-from-markdown": "^2.0.3",
     "node-html-markdown": "^2.0.0",
     "yaml": "^2.9.0",