@zosmaai/pi-llm-wiki 0.11.2 → 0.11.4

package/commands/wiki-run.md

@@ -0,0 +1,31 @@
+---
+description: Run the full wiki cycle: discover → ingest → lint. Optionally schedule for auto-updates.
+argument-hint: "[--schedule daily|weekly]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-run
+
+Run the complete wiki maintenance cycle: discover new sources, ingest them, and lint for health.
+
+## User Arguments
+
+$ARGUMENTS
+
+## Steps
+
+1. **Discover:** Use web search to find new sources on the wiki's topic, then capture each with `wiki_capture_source(url=<url>)` (max 5-10).
+2. **Ingest:** Call `wiki_ingest(batch_size=3)` and process returned sources — read extracted.md, update source pages, create entity/concept pages, add cross-references.
+3. **Lint:** Call `wiki_lint(auto_fix=false)` to run a health check.
+4. If critical gaps found → optionally run one more discover+ingest cycle.
+5. Save summary to `.llm-wiki/outputs/run-YYYY-MM-DD.md` using the `write` tool.
+6. Report final summary.
+
+### Scheduling
+
+If `--schedule` is provided, call `wiki_watch(interval=<daily|weekly|hourly>)`.
+
+**Important:** `wiki_watch` does NOT install a schedule. It only prints a `crontab` line.
+Report the printed line to the user verbatim and tell them to install it themselves with
+`crontab -e`. Do not claim the schedule is active until they confirm they have done so.

package/commands/wiki-skills.md

@@ -0,0 +1,26 @@
+---
+description: Search the wiki's distilled skills and past cases for patterns relevant to the current task — "have I done something like this before?".
+argument-hint: "[query] [--kind skill|case]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-skills
+
+Search the agent working-memory layer of the wiki: reusable **skills** distilled from past trajectories, and specific past **cases**.
+
+## User Arguments
+
+$ARGUMENTS
+
+## Steps
+
+1. Call `wiki_recall_skill` with:
+   - `query`: the current task description or key terms (defaults to `$ARGUMENTS`)
+   - `kind`: optional — `skill`, `case`, or `any` (default)
+   - `max_results`: optional (default 5)
+2. Read the most relevant skill/case pages with `read`.
+3. Apply the recalled pattern to the current task, citing the source page with `[[skills/...]]` or `[[cases/...]]` where helpful.
+4. If no relevant skill/case exists, proceed with the task and consider running `/wiki-record` afterward so the next attempt benefits.
+
+**Tip:** Skills generalize across many trajectories ("how I do X"); cases are concrete past runs ("the time I did X for project Y"). Search `any` first, then narrow.

package/commands/wiki-status.md

@@ -0,0 +1,16 @@
+---
+description: Show wiki health overview — source count, page stats, orphan count, last activity dates.
+argument-hint: ""
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-status
+
+Show a quick overview of wiki health and statistics.
+
+## Steps
+
+1. Call `wiki_status()` to get the current wiki health report.
+2. Present the results to the user.
+3. If health shows warnings (orphans > 5, many gaps), suggest running `/wiki-lint` for a detailed analysis.

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

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+/** Project config directory name per host. */
+const CONFIG_DIR = { pi: ".pi", omp: ".omp" };
+/** Settings file names inside a config directory, lowest → highest precedence. */
+const SETTINGS_FILES = ["settings.json", "config.yml", "config.yaml"];
+/**
+ * Detect which agent is hosting this extension.
+ *
+ * Ordered by reliability:
+ *  1. `LLM_WIKI_HOST` — explicit escape hatch (tests, exotic embeddings).
+ *  2. The agent directory path: pi resolves `~/.pi/agent`, omp `~/.omp/agent`.
+ *     A `PI_CODING_AGENT_DIR` override that keeps the marker segment still
+ *     classifies correctly; anything else falls through.
+ *  3. `OMP_PROFILE`, which omp sets on itself whenever a profile is active.
+ *  4. Default `pi` — the historical behaviour.
+ */
+export function detectHost() {
+    const forced = process.env.LLM_WIKI_HOST?.trim().toLowerCase();
+    if (forced === "omp" || forced === "pi")
+        return forced;
+    let agentDir = "";
+    try {
+        agentDir = getAgentDir();
+    }
+    catch {
+        agentDir = "";
+    }
+    if (agentDir) {
+        const segments = agentDir.split(/[\\/]/);
+        if (segments.includes(".omp"))
+            return "omp";
+        if (segments.includes(".pi"))
+            return "pi";
+    }
+    if (process.env.OMP_PROFILE !== undefined)
+        return "omp";
+    return "pi";
+}
+/**
+ * Every project settings file that may hold `llm-wiki` configuration, ordered
+ * from lowest to highest precedence so callers can merge left-to-right.
+ *
+ * The host's *native* directory is last (wins). The foreign directory is still
+ * read so a vault configured under pi keeps working after omp takes over the
+ * repository, and vice versa. Within a directory `config.yml` follows
+ * `settings.json`, matching omp's own project-settings precedence.
+ */
+export function listProjectSettingsFiles(cwd, host = detectHost()) {
+    const foreign = host === "omp" ? "pi" : "omp";
+    const files = [];
+    for (const kind of [foreign, host]) {
+        const dir = join(cwd, CONFIG_DIR[kind]);
+        for (const name of SETTINGS_FILES)
+            files.push(join(dir, name));
+    }
+    return files;
+}
+/**
+ * User-level settings files, lowest → highest precedence.
+ *
+ * `getAgentDir()` already resolves per host (`~/.pi/agent` vs `~/.omp/agent`),
+ * so only the file names differ: omp migrates `settings.json` into `config.yml`
+ * on first start, and a migrated install has *only* the YAML file.
+ */
+export function listGlobalSettingsFiles() {
+    let agentDir = "";
+    try {
+        agentDir = getAgentDir();
+    }
+    catch {
+        return [];
+    }
+    if (!agentDir)
+        return [];
+    return SETTINGS_FILES.map((name) => join(agentDir, name));
+}
+/**
+ * The project settings file this extension writes to.
+ *
+ * Always JSON (`settings.json`) — both hosts read it, and rewriting a user's
+ * hand-authored `config.yml` would destroy comments and formatting.
+ *
+ * Directory choice: an already-existing project config directory wins (so a
+ * repo that only has `.pi/` keeps a single settings file), otherwise the
+ * detected host's native directory is created.
+ */
+export function resolveProjectSettingsPath(cwd, host = detectHost()) {
+    const native = join(cwd, CONFIG_DIR[host]);
+    if (existsSync(native))
+        return join(native, "settings.json");
+    const foreign = join(cwd, CONFIG_DIR[host === "omp" ? "pi" : "omp"]);
+    if (existsSync(foreign))
+        return join(foreign, "settings.json");
+    return join(native, "settings.json");
+}

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

@@ -239,6 +239,11 @@ export function buildReminderText() {
  * `options.display` (issue #77) controls whether the reminder is shown to the
  * user (`true`, the default) or injected silently into model context only
  * (`false`). Pass a resolver so the live `notices` config is read at send time.
+ *
+ * `options.enabled` gates the reminder entirely — note that `display: false`
+ * still injects it into model context, so it is NOT a way to switch the
+ * reminder off. Callers pass a resolver that answers "does a wiki apply to the
+ * current working directory", evaluated per turn because the session can move.
  */
 export function registerObservationReminder(pi, reminderState, options) {
     const REMINDER_INTERVAL = options?.turnsBetweenReminders ?? 5;
@@ -267,6 +272,10 @@ export function registerObservationReminder(pi, reminderState, options) {
         // errors cause multiple retries, each firing agent_end).
         if ("willRetry" in event && event.willRetry)
             return;
+        // No wiki applies here: never nag, and never accumulate a pending reminder
+        // that would fire the moment the session moves into a wiki-bearing project.
+        if (options?.enabled && !options.enabled())
+            return;
         turnsSinceLastReminder++;
         if (turnsSinceLastReminder < REMINDER_INTERVAL)
             return;

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/task-config.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { dirname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { detectHost, listGlobalSettingsFiles, listProjectSettingsFiles, resolveProjectSettingsPath, } from "./host.js";
 export const TASK_DEFAULTS = {};
 /**
  * Resolve whether user-facing wiki notices are enabled (issue #77). Defaults
@@ -9,6 +10,16 @@ export const TASK_DEFAULTS = {};
 export function noticesEnabled(config) {
     return config?.notices !== false;
 }
+/**
+ * Resolve whether the personal vault may serve as this project's ambient
+ * vault. Explicit `ambientPersonalVault` wins; otherwise the host decides
+ * (see the field docs on {@link TaskConfig.ambientPersonalVault}).
+ */
+export function personalVaultIsAmbient(config, host = detectHost()) {
+    if (typeof config?.ambientPersonalVault === "boolean")
+        return config.ambientPersonalVault;
+    return host === "pi";
+}
 /**
  * Resolve whether agent-trajectory working-memory is enabled (issue #80).
  * INVERSE polarity of `noticesEnabled`: defaults to `false`; only an explicit
@@ -64,6 +75,9 @@ function readNamespacedConfig(path) {
         if (typeof section.notices === "boolean") {
             out.notices = section.notices;
         }
+        if (typeof section.ambientPersonalVault === "boolean") {
+            out.ambientPersonalVault = section.ambientPersonalVault;
+        }
         if (typeof section.trajectories === "boolean") {
             out.trajectories = section.trajectories;
         }
@@ -121,14 +135,19 @@ export function validateSynthesisLanguage(tag) {
     return canonical[0];
 }
 /**
- * Read a settings JSON file as a plain object, or `{}` when it is absent or
+ * Read a settings file as a plain object, or `{}` when it is absent or
  * corrupt. Reads directly (no `existsSync` pre-check) so there is no
  * check-then-use race: a missing file throws ENOENT, which the catch treats
  * the same as an empty file.
+ *
+ * `config.yml` / `config.yaml` are parsed as YAML — that is the format oh-my-pi
+ * migrates its settings to. Everything else is JSON. JSON is a YAML subset, so
+ * the YAML parser also accepts a `.yml` file that actually holds JSON.
  */
 function readSettingsObject(path) {
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        const text = readFileSync(path, "utf-8");
+        const parsed = path.endsWith(".yml") || path.endsWith(".yaml") ? parseYaml(text) : JSON.parse(text);
         if (parsed && typeof parsed === "object")
             return parsed;
     }
@@ -138,64 +157,70 @@ function readSettingsObject(path) {
     return {};
 }
 /**
- * Persist (or clear) the wiki background `taskModel` in the PROJECT settings
- * file `<cwd>/.pi/settings.json` under the namespaced `llm-wiki` key (issue
- * #69). Project settings win over global in `loadTaskConfig`, so this takes
- * effect immediately on the next config load. Other top-level keys and other
- * `llm-wiki` settings are preserved; passing `undefined` removes the key
- * (reverting to the session model).
+ * Rewrite the `llm-wiki` section of the project settings file, preserving every
+ * other top-level key and every other setting in the section.
+ *
+ * The target file is chosen by `resolveProjectSettingsPath` — `.pi/settings.json`
+ * or `.omp/settings.json` depending on host and on what already exists — and is
+ * always JSON, which both hosts read.
  */
-export function persistTaskModel(cwd, model) {
-    const settingsPath = join(cwd, ".pi", "settings.json");
+function updateProjectSection(cwd, mutate) {
+    const settingsPath = resolveProjectSettingsPath(cwd);
     const raw = readSettingsObject(settingsPath);
     const existing = raw[SETTINGS_KEY];
     const section = existing && typeof existing === "object" ? { ...existing } : {};
-    if (model) {
-        section.taskModel = { provider: model.provider, id: model.id };
-    }
-    else {
-        // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key (vs setting undefined) keeps the JSON clean
-        delete section.taskModel;
-    }
+    mutate(section);
     raw[SETTINGS_KEY] = section;
     mkdirSync(dirname(settingsPath), { recursive: true });
     writeFileSync(settingsPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
 }
 /**
- * Persist the agent-trajectory flag in the PROJECT settings file
- * `<cwd>/.pi/settings.json` under the namespaced `llm-wiki` key (issue #80).
- * Mirrors `persistTaskModel`: project settings win in `loadTaskConfig`, other
- * keys are preserved. `true` writes `trajectories: true`; `false` removes the
- * key (reverting to the default-off behavior).
+ * Persist (or clear) the wiki background `taskModel` in the PROJECT settings
+ * file under the namespaced `llm-wiki` key (issue #69). Project settings win
+ * over global in `loadTaskConfig`, so this takes effect immediately on the next
+ * config load. Passing `undefined` removes the key (reverting to the session
+ * model).
+ */
+export function persistTaskModel(cwd, model) {
+    updateProjectSection(cwd, (section) => {
+        if (model) {
+            section.taskModel = { provider: model.provider, id: model.id };
+        }
+        else {
+            // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key (vs setting undefined) keeps the JSON clean
+            delete section.taskModel;
+        }
+    });
+}
+/**
+ * Persist the agent-trajectory flag in the PROJECT settings file under the
+ * namespaced `llm-wiki` key (issue #80). Mirrors `persistTaskModel`: `true`
+ * writes `trajectories: true`; `false` removes the key (reverting to the
+ * default-off behavior).
  */
 export function persistTrajectoriesEnabled(cwd, enabled) {
-    const settingsPath = join(cwd, ".pi", "settings.json");
-    const raw = readSettingsObject(settingsPath);
-    const existing = raw[SETTINGS_KEY];
-    const section = existing && typeof existing === "object" ? { ...existing } : {};
-    if (enabled) {
-        section.trajectories = true;
-    }
-    else {
-        // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key keeps the JSON clean (default is off)
-        delete section.trajectories;
-    }
-    raw[SETTINGS_KEY] = section;
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    writeFileSync(settingsPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
+    updateProjectSection(cwd, (section) => {
+        if (enabled) {
+            section.trajectories = true;
+        }
+        else {
+            // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key keeps the JSON clean (default is off)
+            delete section.trajectories;
+        }
+    });
 }
+/**
+ * Merge the `llm-wiki` section from every settings file both hosts may use,
+ * lowest precedence first: built-in defaults, then user-level files, then
+ * project-level files. Absent files contribute nothing.
+ */
 export function loadTaskConfig(cwd) {
-    let globalPath;
-    try {
-        globalPath = join(getAgentDir(), "settings.json");
+    const config = { ...TASK_DEFAULTS };
+    for (const path of listGlobalSettingsFiles()) {
+        Object.assign(config, readNamespacedConfig(path));
     }
-    catch {
-        globalPath = "";
+    for (const path of listProjectSettingsFiles(cwd)) {
+        Object.assign(config, readNamespacedConfig(path));
     }
-    const projectPath = join(cwd, ".pi", "settings.json");
-    return {
-        ...TASK_DEFAULTS,
-        ...(globalPath ? readNamespacedConfig(globalPath) : {}),
-        ...readNamespacedConfig(projectPath),
-    };
+    return config;
 }

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/extensions/llm-wiki/lib/utils.js

@@ -82,20 +82,46 @@ export function migrateDoubledPersonalVault(parentRoot = getPersonalWikiRoot())
 /**
  * Check if a vault is the personal wiki location.
  * Used in layered recall to avoid double-counting.
+ *
+ * Compares PHYSICAL paths, not strings. On image-based ("atomic") Linux
+ * distributions `/home` is a symlink to `var/home`, so `homedir()` yields the
+ * `$HOME` string (`/home/u`) while `process.cwd()` — and therefore the root
+ * `resolveVaultRoot()` walks up to — yields `/var/home/u`. A string compare
+ * calls the personal vault a project vault, which makes layered recall search
+ * the same vault twice and `vaultPageCount()` double-count it.
+ *
+ * Exact equality, NOT containment: a vault nested under the home directory
+ * (`~/projects/foo/.llm-wiki`) is a project vault and must stay one.
  */
 export function isPersonalVault(paths) {
-    return paths.root === getPersonalWikiRoot();
+    const personalRoot = getPersonalWikiRoot();
+    // Fast path: identical strings need no filesystem syscalls.
+    if (paths.root === personalRoot)
+        return true;
+    try {
+        return relativePhysicalPath(personalRoot, paths.root) === "";
+    }
+    catch {
+        // Unresolvable path (permissions, symlink cycle): fall back to "not
+        // personal" so layered recall degrades to searching both vaults rather
+        // than silently dropping the personal layer.
+        return false;
+    }
 }
 /**
- * Resolve vault root from cwd with personal fallback.
+ * Resolve the vault root that belongs to THIS project, or `null` when the
+ * project has none.
  *
  * Priority:
- * 1. cwd has .llm-wiki/ → project wiki (explicit)
- * 2. Walk up from cwd → parent project wiki
- * 3. ~/.llm-wiki/ exists → personal wiki
- * 4. Fallback: ~/.llm-wiki/ (create personal wiki)
+ * 1. cwd has `.llm-wiki/` (or legacy `.wiki/`) → project wiki (explicit)
+ * 2. `WIKI_HOME` → user-selected root, explicit enough to count as the project's
+ * 3. Walk up from cwd → parent project wiki (monorepo / nested workspace)
+ *
+ * Deliberately does NOT fall back to the personal wiki: callers that need the
+ * fallback use {@link resolveVaultRoot}, callers that must distinguish "this
+ * project has a wiki" from "some wiki exists somewhere" use this.
  */
-export function resolveVaultRoot(cwd) {
+export function resolveProjectVaultRoot(cwd) {
     // A vault rooted at cwd is always the project-local choice.
     if (detectVaultFormat(cwd) !== "none")
         return cwd;
@@ -103,19 +129,36 @@ export function resolveVaultRoot(cwd) {
     // over an unrelated personal vault found while walking parent directories.
     if (process.env.WIKI_HOME)
         return process.env.WIKI_HOME;
-    // Walk up looking for a vault sentinel (new or legacy)
+    // Walk up looking for a vault sentinel (new or legacy).
     let dir = cwd;
     while (dir !== dirname(dir)) {
         dir = dirname(dir);
-        if (detectVaultFormat(dir) !== "none")
-            return dir;
+        if (detectVaultFormat(dir) === "none")
+            continue;
+        // Skip the personal vault: it is an ancestor of EVERY project under the
+        // home directory (`~/projects/foo`, and on Windows even the temp dir), so
+        // counting it here would report a project vault for directories that have
+        // none. `resolveVaultRoot` still falls back to it explicitly.
+        if (isPersonalVault(getVaultPaths(dir)))
+            continue;
+        return dir;
     }
-    // Check personal wiki at ~/.llm-wiki/
-    const personalRoot = getPersonalWikiRoot();
-    if (detectVaultFormat(personalRoot) !== "none")
-        return personalRoot;
-    // Fallback: personal wiki
-    return personalRoot;
+    return null;
+}
+/**
+ * Resolve vault root from cwd with personal fallback.
+ *
+ * Priority:
+ * 1-3. {@link resolveProjectVaultRoot}
+ * 4. Personal wiki root (`~`, or `WIKI_HOME`) — used whether or not it already
+ *    holds a vault, so first-run bootstrap has somewhere to write.
+ */
+export function resolveVaultRoot(cwd) {
+    // Realpath the personal fallback so a symlinked `$HOME` (atomic-OS layouts)
+    // yields the PHYSICAL root the ancestor walk used to return — the #145
+    // regression guard pins that. `realpathWithMissingTail` also covers first-run
+    // bootstrap, where the personal root does not exist on disk yet.
+    return resolveProjectVaultRoot(cwd) ?? realpathWithMissingTail(getPersonalWikiRoot());
 }
 /** Get all vault paths for the new (.llm-wiki) layout. */
 export function getVaultPaths(root) {

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)"),