@zosmaai/pi-llm-wiki 0.11.4 → 0.11.5

package/dist/extensions/llm-wiki/lib/ingest-worker.js

@@ -365,7 +365,7 @@ Rules:
  * synthesis.
  */
 export async function runIngestSynthesis(args) {
-    const { model, apiKey, headers, paths, sourceId, manifest, extracted, maxChars, signal, synthesisLanguage, } = args;
+    const { model, apiKey, headers, paths, sourceId, manifest, extracted, maxChars, signal, synthesisLanguage, synthesisMaxTokens, } = args;
     const content = extracted.slice(0, maxChars ?? 24_000);
     if (!content.trim())
         return undefined;
@@ -402,6 +402,7 @@ export async function runIngestSynthesis(args) {
         systemPrompt,
         userPrompt,
         tools: [commitTool],
+        maxTokens: synthesisMaxTokens ?? 16384,
         signal,
     });
     if (committed)

package/dist/extensions/llm-wiki/lib/knowledge-document.js

@@ -383,6 +383,22 @@ export function serializeKnowledgeDocument(document) {
     const body = document.body.replace(/\r\n?/g, "\n").replace(/\n*$/, "");
     return body ? `---\n${yaml}---\n\n${body}\n` : `---\n${yaml}---\n`;
 }
+/** Escape wikilink alias pipes so generated content remains valid in Markdown tables. */
+function escapeWikilinkAliasPipes(body) {
+    let inFence = false;
+    return body
+        .split("\n")
+        .map((line) => {
+        if (/^\s*(`{3,}|~{3,})/.test(line)) {
+            inFence = !inFence;
+            return line;
+        }
+        if (inFence)
+            return line;
+        return line.replace(/\[\[([^\]\n]*?)(?<!\\)\|([^\]\n]*?)\]\]/g, "[[$1\\|$2]]");
+    })
+        .join("\n");
+}
 export function createKnowledgeDocument(path, fields, body, sources) {
     if (Object.hasOwn(fields, "sources")) {
         throw new Error("Pass canonical sources as the fourth argument");
@@ -402,7 +418,7 @@ export function createKnowledgeDocument(path, fields, body, sources) {
     const sourcesUnion = sources
         ? { kind: "canonical", value: sources }
         : { kind: "absent" };
-    const normalizedBody = body.replace(/\r\n?/g, "\n").replace(/\n*$/, "");
+    const normalizedBody = escapeWikilinkAliasPipes(body.replace(/\r\n?/g, "\n")).replace(/\n*$/, "");
     return {
         id: path.replace(/\.md$/, ""),
         path,
@@ -425,7 +441,9 @@ export function patchKnowledgeDocument(document, patch) {
             }
         }
     }
-    const newBody = patch.body ?? document.body;
+    const newBody = patch.body
+        ? escapeWikilinkAliasPipes(patch.body.replace(/\r\n?/g, "\n"))
+        : document.body;
     return {
         ...document,
         frontmatter: newFrontmatter,

package/dist/extensions/llm-wiki/lib/knowledge-links.js

@@ -3,12 +3,15 @@ import { compareCodePoint } from "./vault-format.js";
 function diag(severity, code, path, message) {
     return { severity, code, path, message };
 }
+function normalizeWikilinkTarget(target) {
+    return target.trim().replace(/\\$/, "");
+}
 export function extractKnowledgeLinks(body) {
     const markdown = [];
     const wikilinks = [];
-    // Extract legacy wikilinks
+    // Extract legacy wikilinks. A table-safe alias uses an escaped pipe: [[target\\|alias]].
     for (const match of body.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
-        wikilinks.push({ target: match[1].trim(), offset: match.index ?? 0 });
+        wikilinks.push({ target: normalizeWikilinkTarget(match[1]), offset: match.index ?? 0 });
     }
     // Parse with CommonMark AST
     let tree;
@@ -72,7 +75,7 @@ export function extractKnowledgeLinks(body) {
 export function extractLegacyWikilinks(body) {
     const links = [];
     for (const match of body.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
-        links.push({ target: match[1].trim(), offset: match.index ?? 0 });
+        links.push({ target: normalizeWikilinkTarget(match[1]), offset: match.index ?? 0 });
     }
     return links;
 }

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

@@ -386,7 +386,7 @@ export function buildDirectoryIndexes(documents, config) {
             lines.push("## Directories");
             lines.push("");
             for (const subDir of [...dirs].sort(compareCodePoint)) {
-                const encoded = `${encodeRelativePath(subDir)}/`;
+                const encoded = encodeRelativePath(`${subDir}/index.md`);
                 lines.push(`- [${escapeLabel(subDir)}/](${encoded})`);
             }
         }

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

@@ -256,9 +256,11 @@ export function registerObservationReminder(pi, reminderState, options) {
         return true;
     };
     let turnsSinceLastReminder = 0;
+    let agentEndsInUserTurn = 0;
     pi.on("session_start", async () => {
         turnsSinceLastReminder = 0;
         reminderState.observeDoneThisSession = false;
+        agentEndsInUserTurn = 0;
     });
     // After compaction, reset turn counter so reminders resume
     // BUT preserve observeDoneThisSession — if the model already called
@@ -266,10 +268,18 @@ export function registerObservationReminder(pi, reminderState, options) {
     pi.on("session_compact", async () => {
         turnsSinceLastReminder = 0;
     });
+    // A retry re-runs the agent within the same user turn, and pi does not
+    // forward `willRetry` to extensions (zosmaai/pi-llm-wiki#151). Only the
+    // user-role message_start separates real user turns from retried agent
+    // runs, so the per-turn agent_end count resets there.
+    pi.on("message_start", async (event) => {
+        if (event.message.role === "user")
+            agentEndsInUserTurn = 0;
+    });
     pi.on("agent_end", async (event, _ctx) => {
-        // Skip reminder on retries — willRetry means pi will re-run the agent,
-        // and queuing another reminder would duplicate them (issue: connection
-        // errors cause multiple retries, each firing agent_end).
+        // Legacy guard: this pi build does not forward `willRetry` to extension
+        // events, but keep the check in case a future one does. The dedup that
+        // actually works is the per-turn agent_end count below.
         if ("willRetry" in event && event.willRetry)
             return;
         // No wiki applies here: never nag, and never accumulate a pending reminder
@@ -281,6 +291,12 @@ export function registerObservationReminder(pi, reminderState, options) {
             return;
         if (reminderState.observeDoneThisSession)
             return;
+        // One agent_end per user turn may queue a reminder. A rate-limit storm
+        // re-runs the agent several times within the same turn, each firing
+        // agent_end, so count them and let only the first through.
+        agentEndsInUserTurn++;
+        if (agentEndsInUserTurn > 1)
+            return;
         pi.sendMessage({
             customType: "wiki-observe-reminder",
             content: buildReminderText(),
@@ -288,5 +304,8 @@ export function registerObservationReminder(pi, reminderState, options) {
         }, {
             deliverAs: "nextTurn",
         });
+        // Reset the interval counter after queueing: without it the count stays
+        // at/above the threshold and every later agent_end queues a reminder.
+        turnsSinceLastReminder = 0;
     });
 }

package/dist/extensions/llm-wiki/lib/settings-command.js

@@ -0,0 +1,377 @@
+import { homedir } from "node:os";
+import { Container, Input, SettingsList, Spacer, Text, } from "@mariozechner/pi-tui";
+import { loadTaskConfig, loadTaskConfigSources, parseModelRef, persistSetting, trajectoriesEnabled, } from "./task-config.js";
+const SETTINGS = [
+    {
+        key: "taskModel",
+        label: "Model",
+        type: "model",
+        hint: "Model for background wiki tasks (provider/id).",
+        menuLabel: "Task model — provider/id, empty = session model",
+        format: (v) => {
+            const m = v;
+            return m ? `${m.provider}/${m.id}` : "(session model)";
+        },
+        toEdit: (v) => {
+            const m = v;
+            return m ? `${m.provider}/${m.id}` : "";
+        },
+        parse: (input) => parseModelRef(input),
+    },
+    {
+        key: "synthesisMaxTokens",
+        label: "Synthesis Tokens",
+        type: "number",
+        hint: "Max output tokens for wiki synthesis runs.",
+        defaultText: "16384",
+        format: (v) => (v != null ? String(v) : "16384 (default)"),
+        toEdit: (v) => (v != null ? String(v) : "16384"),
+        parse: (input) => {
+            const n = Number(input);
+            if (!Number.isFinite(n) || n <= 0)
+                return undefined;
+            return Math.floor(n);
+        },
+    },
+    {
+        key: "trajectories",
+        label: "Trajectories",
+        type: "boolean",
+        hint: "Capture agent trajectories into the vault.",
+        format: (v) => (v ? "ON" : "OFF"),
+        toEdit: () => "",
+        parse: (input) => Boolean(Boolean(input) && /on|true|1/i.test(input)),
+    },
+    {
+        key: "notices",
+        label: "Notices",
+        type: "boolean",
+        hint: "Show wiki recall/observation notice lines in chat.",
+        format: (v) => (v != null ? (v ? "ON" : "OFF") : "ON (default)"),
+        toEdit: () => "",
+        parse: (input) => Boolean(Boolean(input) && /on|true|1/i.test(input)),
+    },
+    {
+        key: "ambientPersonalVault",
+        label: "Ambient Personal",
+        type: "boolean",
+        hint: "Include the personal vault in ambient session context.",
+        format: (v) => (v != null ? (v ? "ON" : "OFF") : "host-dependent"),
+        toEdit: () => "",
+        parse: (input) => Boolean(Boolean(input) && /on|true|1/i.test(input)),
+    },
+    {
+        key: "synthesisLanguage",
+        label: "Synthesis Language",
+        type: "string",
+        hint: "Language for synthesized wiki content.",
+        defaultText: "en",
+        format: (v) => (v ? String(v) : "en (default)"),
+        toEdit: (v) => (v ? String(v) : "en"),
+        parse: (input) => {
+            const trimmed = input.trim();
+            return trimmed || undefined;
+        },
+    },
+    {
+        key: "semanticWeight",
+        label: "Semantic Weight",
+        type: "number",
+        hint: "0–1 weight for embedding (semantic) recall.",
+        defaultText: "0.5",
+        format: (v) => (v != null ? String(v) : "0.5 (default)"),
+        toEdit: (v) => (v != null ? String(v) : "0.5"),
+        parse: (input) => {
+            const n = Number(input);
+            if (!Number.isFinite(n) || n < 0 || n > 1)
+                return undefined;
+            return n;
+        },
+    },
+    {
+        key: "recallLinksThreshold",
+        label: "Recall Links",
+        type: "number",
+        hint: "Max recall links shown when the vault is large.",
+        defaultText: "50",
+        format: (v) => (v != null ? String(v) : "50 (default)"),
+        toEdit: (v) => (v != null ? String(v) : "50"),
+        parse: (input) => {
+            const n = Number(input);
+            if (!Number.isFinite(n) || n < 0)
+                return undefined;
+            return Math.floor(n);
+        },
+    },
+    {
+        key: "recallSkillInlineMax",
+        label: "Skill Inline Max",
+        type: "number",
+        hint: "Max characters inlined from recall into skill prompts.",
+        defaultText: "1600",
+        format: (v) => (v != null ? String(v) : "1600 (default)"),
+        toEdit: (v) => (v != null ? String(v) : "1600"),
+        parse: (input) => {
+            const n = Number(input);
+            if (!Number.isFinite(n) || n < 0)
+                return undefined;
+            return Math.floor(n);
+        },
+    },
+    {
+        key: "embeddingProvider",
+        label: "Embedding Provider",
+        type: "string",
+        hint: "Embedding provider (e.g. openai). Empty = embeddings disabled.",
+        format: (v) => (v ? String(v) : "(disabled)"),
+        toEdit: (v) => (v ? String(v) : ""),
+        parse: (input) => input.trim() || undefined,
+    },
+    {
+        key: "embeddingModel",
+        label: "Embedding Model",
+        type: "string",
+        hint: "Embedding model id.",
+        defaultText: "text-embedding-3-small",
+        format: (v) => (v ? String(v) : "text-embedding-3-small (default)"),
+        toEdit: (v) => (v ? String(v) : "text-embedding-3-small"),
+        parse: (input) => input.trim() || undefined,
+    },
+    {
+        key: "embeddingBaseUrl",
+        label: "Embedding Base URL",
+        type: "string",
+        hint: "Custom embeddings API base URL (optional).",
+        format: (v) => (v ? String(v) : "—"),
+        toEdit: (v) => (v ? String(v) : ""),
+        parse: (input) => input.trim() || undefined,
+    },
+    {
+        key: "embeddingApiKeyEnv",
+        label: "Embedding API Key Env",
+        type: "string",
+        hint: "Environment variable name holding the embeddings API key.",
+        defaultText: "OPENAI_API_KEY",
+        format: (v) => (v ? String(v) : "OPENAI_API_KEY (default)"),
+        toEdit: (v) => (v ? String(v) : "OPENAI_API_KEY"),
+        parse: (input) => input.trim() || undefined,
+    },
+];
+function isInsideHome(cwd) {
+    return cwd.startsWith(homedir());
+}
+/**
+ * Map effective settings + sources to pi-tui SettingItems.
+ *
+ * Exported for tests. `notify` is used by edit menus to report invalid input
+ * without closing the menu.
+ */
+export function buildSettingItems(sources, notify) {
+    return SETTINGS.map((def) => {
+        const entry = sources[def.key];
+        const value = entry?.value;
+        const source = entry?.source ?? "default";
+        const item = {
+            id: def.key,
+            label: def.label,
+            currentValue: def.format(value),
+            description: describeSetting(def, source),
+        };
+        if (def.type === "boolean") {
+            item.values = ["OFF", "ON"];
+            return item;
+        }
+        item.submenu = (_display, done) => {
+            const sub = new InputSubmenu(def.menuLabel ?? `Set ${def.label}`, def.toEdit(value));
+            sub.input.onSubmit = (raw) => {
+                const trimmed = raw.trim();
+                if (def.type === "model") {
+                    if (!trimmed) {
+                        done(""); // clear → back to session model
+                        return;
+                    }
+                    const ref = parseModelRef(trimmed);
+                    if (!ref) {
+                        notify(`LLM Wiki: could not parse "${trimmed}". Use provider/id.`, "error");
+                        return; // stay in the menu
+                    }
+                    done(`${ref.provider}/${ref.id}`);
+                    return;
+                }
+                if (!trimmed) {
+                    done(); // empty = no change
+                    return;
+                }
+                const parsed = def.parse(trimmed);
+                if (parsed === undefined) {
+                    notify(`LLM Wiki: invalid value "${trimmed}" for ${def.label}`, "error");
+                    return; // stay in the menu
+                }
+                done(String(parsed));
+            };
+            sub.input.onEscape = () => done();
+            return sub;
+        };
+        return item;
+    });
+}
+function describeSetting(def, source) {
+    const where = source === "default" ? "Not set — using default." : `Set in ${source} settings.`;
+    return `${def.hint}\n${where}`;
+}
+/**
+ * Parse the display string a SettingItem cycled/edited into back into the
+ * typed value to persist.
+ */
+function parseDisplay(def, display) {
+    if (def.type === "boolean")
+        return display === "ON";
+    if (def.type === "model")
+        return display ? parseModelRef(display) : undefined;
+    return def.parse(display);
+}
+function buildSettingsListTheme(theme) {
+    return {
+        label: (text, selected) => (selected ? theme.fg("accent", text) : text),
+        value: (text, selected) => (selected ? theme.fg("accent", text) : theme.fg("muted", text)),
+        description: (text) => theme.fg("dim", text),
+        cursor: theme.fg("accent", "→ "),
+        hint: (text) => theme.fg("dim", text),
+    };
+}
+/** Title + single-line input. SettingsList forwards all key input here. */
+class InputSubmenu extends Container {
+    input;
+    constructor(label, initialValue) {
+        super();
+        this.addChild(new Text(label, 0, 0));
+        this.input = new Input();
+        // Type the prefill instead of setValue(): setValue keeps the cursor at 0,
+        // which makes backspace no-op and typed input land before the prefill.
+        if (initialValue)
+            this.input.handleInput(initialValue);
+        this.addChild(this.input);
+    }
+    handleInput(data) {
+        this.input.handleInput(data);
+    }
+}
+/** Header + settings list. ui.custom gives this component focus. */
+class SettingsScreen extends Container {
+    list;
+    titleText;
+    constructor(title, list) {
+        super();
+        this.list = list;
+        this.titleText = new Text(title, 0, 0);
+        this.addChild(this.titleText);
+        this.addChild(new Spacer(1));
+        this.addChild(list);
+    }
+    handleInput(data) {
+        this.list.handleInput(data);
+    }
+    /** Update the header line in place (scope changes re-target it live). */
+    setTitle(title) {
+        this.titleText.setText(title);
+    }
+}
+/** Build the header title for the scope currently being written to. */
+function scopeTitle(scope) {
+    return `\u{1F9E0} LLM Wiki Settings \u2014 ${scope === "global" ? "Global" : "Project"} (Esc to close)`;
+}
+async function showSettingsTui(ui, cwd, scope) {
+    if (typeof ui.custom !== "function") {
+        ui.notify("LLM Wiki: this host does not support the settings screen. Edit settings.json directly.", "warning");
+        return;
+    }
+    // The editable Scope row re-targets where subsequent writes land; the
+    // picker / inside-home heuristic only chooses the starting value.
+    let writeScope = scope;
+    const scopeItem = {
+        id: "scope",
+        label: "Scope",
+        currentValue: writeScope === "global" ? "Global" : "Project",
+        values: ["Global", "Project"],
+        description: "Where edits are written. Global \u2192 ~/.pi/agent/settings.json \u00b7 Project \u2192 .pi/settings.json (this folder).",
+    };
+    const items = [scopeItem, ...buildSettingItems(loadTaskConfigSources(cwd), ui.notify.bind(ui))];
+    // Tracks the effective value so the reload note fires on actual changes.
+    let prevTrajectories = trajectoriesEnabled(loadTaskConfig(cwd));
+    let list;
+    let screenRef;
+    await ui.custom((_tui, theme, _keybindings, close) => {
+        list = new SettingsList(items, items.length, buildSettingsListTheme(theme), (id, display) => {
+            if (!list)
+                return;
+            // Scope row: re-target writes; nothing is persisted for it.
+            if (id === "scope") {
+                writeScope = display === "Global" ? "global" : "project";
+                list.updateValue("scope", display);
+                screenRef?.setTitle(scopeTitle(writeScope));
+                ui.notify(`LLM Wiki: writing to ${writeScope === "global"
+                    ? "Global (~/.pi/agent/settings.json)"
+                    : "Project (.pi/settings.json)"}`);
+                return;
+            }
+            const def = SETTINGS.find((d) => d.key === id);
+            if (!def)
+                return;
+            const value = parseDisplay(def, display);
+            // Non-model, non-boolean values are validated before done(); undefined
+            // here is only expected for the model-clear case.
+            if (value === undefined && def.type !== "model")
+                return;
+            try {
+                persistSetting(cwd, writeScope, def.key, value);
+            }
+            catch (err) {
+                ui.notify(`LLM Wiki: failed to save ${def.label}: ${err instanceof Error ? err.message : String(err)}`, "error");
+                return;
+            }
+            // Normalize the displayed value in place (e.g. cleared model shows
+            // "(session model)"; "0.50" becomes "0.5").
+            list.updateValue(id, def.format(value));
+            // trajectories gates tool registration at startup, so a live toggle
+            // cannot add/remove the 3 tools mid-session \u2014 say so on real changes.
+            if (def.key === "trajectories") {
+                const next = Boolean(value);
+                if (next !== prevTrajectories) {
+                    prevTrajectories = next;
+                    ui.notify("LLM Wiki: trajectory tools register at startup \u2014 new value applies after a reload");
+                }
+            }
+        }, () => close());
+        screenRef = new SettingsScreen(scopeTitle(writeScope), list);
+        return screenRef;
+    });
+}
+/**
+ * Register the /wiki-settings command.
+ */
+export function registerWikiSettingsCommand(pi, runtime) {
+    pi.registerCommand("wiki-settings", {
+        description: "View and edit LLM Wiki settings (model, tokens, behaviors, embeddings)",
+        handler: async (_args, ctx) => {
+            runtime.ensureConfig(ctx.cwd);
+            if (!ctx.hasUI) {
+                ctx.ui.notify("LLM Wiki: /wiki-settings requires an interactive UI. Edit settings.json directly instead.", "warning");
+                return;
+            }
+            let scope;
+            if (isInsideHome(ctx.cwd)) {
+                scope = "global";
+            }
+            else {
+                const pick = await ctx.ui.select("LLM Wiki \u2014 Settings scope?", [
+                    `Project (${ctx.cwd}/.pi/settings.json)`,
+                    "Global (~/.pi/agent/settings.json)",
+                ]);
+                if (pick === undefined)
+                    return;
+                scope = pick.startsWith("Project") ? "project" : "global";
+            }
+            await showSettingsTui(ctx.ui, ctx.cwd, scope);
+        },
+    });
+}

package/dist/extensions/llm-wiki/lib/task-config.js

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { detectHost, listGlobalSettingsFiles, listProjectSettingsFiles, resolveProjectSettingsPath, } from "./host.js";
+import { detectHost, listGlobalSettingsFiles, listProjectSettingsFiles, resolveGlobalSettingsPath, resolveProjectSettingsPath, } from "./host.js";
 export const TASK_DEFAULTS = {};
 /**
  * Resolve whether user-facing wiki notices are enabled (issue #77). Defaults
@@ -87,6 +87,10 @@ function readNamespacedConfig(path) {
             if (canonical)
                 out.synthesisLanguage = canonical;
         }
+        const maxTokens = section.synthesisMaxTokens;
+        if (typeof maxTokens === "number" && Number.isFinite(maxTokens) && maxTokens > 0) {
+            out.synthesisMaxTokens = Math.floor(maxTokens);
+        }
         return out;
     }
     catch {
@@ -156,6 +160,19 @@ function readSettingsObject(path) {
     }
     return {};
 }
+/**
+ * Rewrite the `llm-wiki` section of the global settings file.
+ */
+function updateGlobalSection(mutate) {
+    const settingsPath = resolveGlobalSettingsPath();
+    const raw = readSettingsObject(settingsPath);
+    const existing = raw[SETTINGS_KEY];
+    const section = existing && typeof existing === "object" ? { ...existing } : {};
+    mutate(section);
+    raw[SETTINGS_KEY] = section;
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
+}
 /**
  * Rewrite the `llm-wiki` section of the project settings file, preserving every
  * other top-level key and every other setting in the section.
@@ -224,3 +241,63 @@ export function loadTaskConfig(cwd) {
     }
     return config;
 }
+/**
+ * Resolve where each setting is defined: project > global > default.
+ */
+/** All known setting keys — needed because TASK_DEFAULTS is {} (zero-config). */
+const KNOWN_KEYS = [
+    "taskModel",
+    "embeddingProvider",
+    "embeddingModel",
+    "embeddingBaseUrl",
+    "embeddingApiKey",
+    "embeddingApiKeyEnv",
+    "semanticWeight",
+    "recallLinksThreshold",
+    "recallSkillInlineMax",
+    "notices",
+    "ambientPersonalVault",
+    "trajectories",
+    "synthesisLanguage",
+    "synthesisMaxTokens",
+];
+export function loadTaskConfigSources(cwd) {
+    const globalResult = {};
+    for (const path of listGlobalSettingsFiles()) {
+        Object.assign(globalResult, readNamespacedConfig(path));
+    }
+    const projectResult = {};
+    for (const path of listProjectSettingsFiles(cwd)) {
+        Object.assign(projectResult, readNamespacedConfig(path));
+    }
+    const effective = loadTaskConfig(cwd);
+    const out = {};
+    for (const key of KNOWN_KEYS) {
+        if (key in projectResult)
+            out[key] = { value: projectResult[key], source: "project" };
+        else if (key in globalResult)
+            out[key] = { value: globalResult[key], source: "global" };
+        else
+            out[key] = { value: effective[key], source: "default" };
+    }
+    return out;
+}
+/**
+ * Generic setting persist: writes any single setting to the chosen scope.
+ */
+export function persistSetting(cwd, scope, key, value) {
+    const mutate = (section) => {
+        if (value === undefined || value === null) {
+            delete section[key];
+        }
+        else {
+            section[key] = value;
+        }
+    };
+    if (scope === "project") {
+        updateProjectSection(cwd, mutate);
+    }
+    else if (scope === "global") {
+        updateGlobalSection(mutate);
+    }
+}

package/docs/api.md

@@ -2,7 +2,7 @@
 
 All tools registered by the extension. Parameters marked `?` are optional.
 
-13 tools are always registered. The 3 agent-trajectory tools
+14 tools are always registered. The 3 agent-trajectory tools
 (`wiki_capture_trajectory`, `wiki_distill_skills`, `wiki_recall_skill`) are **opt-in,
 off by default** (issue #80) — they are only registered when `llm-wiki.trajectories`
 is `true`; enable with `/wiki-trajectories on`.
@@ -458,6 +458,29 @@ Returns empty `matches: []` with a hint to capture work via `wiki_capture_trajec
 
 ---
 
+## wiki_reindex_embeddings
+
+Backfill or refresh semantic embeddings for the vault. Embeds pages that are new or stale
+(content changed); pass `force` to re-embed everything. No-op when no embedding provider is
+configured — set `llm-wiki.embeddingProvider` first (see `docs/configuration.md`).
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `force` | `boolean` | — | Re-embed every page, ignoring staleness (default: `false`) |
+
+**Returns**
+
+```
+details: { enabled: true, model: string, embedded: number, skipped: number, pruned: number }
+```
+
+Fails soft with `details: { enabled: false }` plus a hint to configure `embeddingProvider` when
+no embedding provider is set.
+
+---
+
 ## Error Shape
 
 All tools return `isError: true` in their result when a hard error occurs (no vault found, missing