@zosmaai/pi-llm-wiki 0.12.1 → 0.12.2

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

@@ -8,6 +8,8 @@ import { scheduleReindex } from "./indexing.js";
 import { runIngestSynthesis } from "./ingest-worker.js";
 import {
   createKnowledgeDocument,
+  type KnowledgeValue,
+  parseMarkdownFrontmatter,
   serializeKnowledgeDocument,
   writeKnowledgeDocumentFile,
 } from "./knowledge-document.js";
@@ -18,6 +20,7 @@ import {
 } from "./knowledge-links.js";
 import { repairLegacyKnowledgeDocuments } from "./legacy-repair.js";
 import { appendEvent, type Registry, rebuildMetadata, rebuildMetadataLight } from "./metadata.js";
+import { readQmdIndexStatus, reindexQmdVault } from "./qmd-indexing.js";
 import type { Runtime } from "./runtime.js";
 import { captureFile, captureText, captureUrl } from "./source-packet.js";
 import { loadTaskConfig, parseModelRef, resolveWikilinkValidation } from "./task-config.js";
@@ -38,7 +41,7 @@ import {
   inspectVaultFormat,
   inspectWritableVault,
 } from "./vault-format.js";
-import { getWikiStatus, searchRegistry } from "./wiki-service.js";
+import { getWikiStatus, reindexWiki, searchRegistry } from "./wiki-service.js";
 
 /**
  * All LLM Wiki custom tools.
@@ -414,6 +417,8 @@ export function registerWikiIngest(pi: ExtensionAPI, runtime?: Runtime): void {
                 model: resolved.model as Parameters<typeof runIngestSynthesis>[0]["model"],
                 apiKey: resolved.apiKey,
                 headers: resolved.headers,
+                streamFn: resolved.streamFn as Parameters<typeof runIngestSynthesis>[0]["streamFn"],
+                env: resolved.env,
                 paths,
                 sourceId: s.id,
                 manifest: s.manifest,
@@ -506,6 +511,11 @@ export function registerWikiIngest(pi: ExtensionAPI, runtime?: Runtime): void {
 
 // ─── 4. wiki_ensure_page ────────────────────────────────
 
+// Frontmatter fields wiki_ensure_page generates or derives itself (title also
+// determines the filename). Model-supplied values for these are ignored rather
+// than merged (issue #241).
+const RESERVED_FRONTMATTER = new Set(["type", "title", "created", "updated", "sources", "id"]);
+
 export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): void {
   pi.registerTool({
     name: "wiki_ensure_page",
@@ -515,6 +525,7 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
     promptGuidelines: [
       "Use wiki_ensure_page before creating pages to avoid duplicates.",
       "Search existing pages first with wiki_search.",
+      "Content may begin with a YAML frontmatter block; its fields are merged into the page frontmatter, and generated fields are reserved.",
     ],
     parameters: Type.Object({
       type: Type.String({
@@ -523,7 +534,10 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
       }),
       title: Type.String({ description: "Page title" }),
       content: Type.Optional(
-        Type.String({ description: "Optional initial content (otherwise uses template)" }),
+        Type.String({
+          description:
+            "Optional Markdown body. May begin with a YAML frontmatter block, whose fields are merged into the page frontmatter; generated fields (type, title, created, updated, sources) are reserved and ignored.",
+        }),
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -568,6 +582,25 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
       const today = fmtDate();
       let body = params.content ?? buildPageBody(type, params.title);
 
+      // #241: models sometimes pass a YAML frontmatter block inside content.
+      // Consume it (with the same hardened parser used for page reads) and merge
+      // its fields into the generated frontmatter, instead of writing the block
+      // verbatim into the body (duplicate frontmatter, and the model's fields
+      // silently never took effect). Generated fields are reserved; a
+      // frontmatter-only content falls back to the template body.
+      const extraFrontmatter: Record<string, KnowledgeValue> = {};
+      if (body.trimStart().startsWith("---")) {
+        const parsed = parseMarkdownFrontmatter(body, `${folder}/${slug}.md`);
+        if (parsed.ok) {
+          for (const [key, value] of Object.entries(parsed.mapping)) {
+            if (!RESERVED_FRONTMATTER.has(key)) {
+              extraFrontmatter[key] = value;
+            }
+          }
+          body = parsed.body.trim() ? parsed.body : buildPageBody(type, params.title);
+        }
+      }
+
       // Pre-write wikilink gate (#172): validate/normalize caller-supplied content.
       const mode = resolveWikilinkValidation(loadTaskConfig(ctx.cwd));
       let wikilinkIssues: string[] = [];
@@ -609,6 +642,7 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
           title: params.title,
           created: today,
           updated: today,
+          ...extraFrontmatter,
         },
         body,
       );
@@ -875,8 +909,9 @@ export function registerWikiLint(pi: ExtensionAPI, runtime?: Runtime): void {
  * Run the wiki health scan (issue #77 extracted it from the tool body so it can
  * run off-thread via `dispatchReported`). Returns the human-readable summary.
  */
-function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
+async function runWikiLint(paths: VaultPaths, autoFix: boolean): Promise<string> {
   assertWritableVault(paths);
+  const qmdStatus = await readQmdIndexStatus(paths);
   let repair: ReturnType<typeof repairLegacyKnowledgeDocuments> | undefined;
   if (autoFix) {
     let projection = rebuildMetadata(paths);
@@ -1034,6 +1069,26 @@ function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
     rebuildMetadataLight(paths);
   }
 
+  const qmdFindings: string[] = [];
+  if (qmdStatus.state === "stale") {
+    const components = JSON.stringify(
+      qmdStatus.repairComponents.length > 0 ? qmdStatus.repairComponents : ["lexical"],
+    );
+    qmdFindings.push(
+      `- QMD index stale (${qmdStatus.indexedManifestHash ? "manifest or model changed" : ""}): repair with \`wiki_reindex(scope="changed", components=${components}, vault="active")\``,
+    );
+  } else if (qmdStatus.state === "recovering") {
+    qmdFindings.push(
+      `- QMD swap interrupted (${qmdStatus.swapPhase ?? ""}): restart recovery via \`wiki_reindex(vault="active")\``,
+    );
+  } else if (qmdStatus.state === "error") {
+    qmdFindings.push(
+      `- QMD index error: ${qmdStatus.issues[0]?.message ?? "repair with wiki_reindex"} — \`wiki_reindex(scope="changed", components=${JSON.stringify(qmdStatus.repairComponents.length > 0 ? qmdStatus.repairComponents : ["lexical"])}, vault="active")\``,
+    );
+  } else if (qmdStatus.state === "missing") {
+    qmdFindings.push("- QMD index not built yet (informational): run wiki_reindex to build it");
+  }
+
   return [
     "🧹 **LLM Wiki lint complete**",
     "",
@@ -1047,6 +1102,10 @@ function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
     reportPath ? `📄 Report: \`${reportPath}\`` : "",
     repair?.manifestPath ? `🛟 Repair manifest: \`${repair.manifestPath}\`` : "",
     gaps.length ? `💡 ${gaps.length} knowledge gap(s) tracked` : "",
+    "",
+    "## QMD Index",
+    `- State: ${qmdStatus.state}`,
+    ...qmdFindings,
   ]
     .filter(Boolean)
     .join("\n");
@@ -1073,7 +1132,7 @@ export function registerWikiStatus(pi: ExtensionAPI): void {
         };
       }
 
-      const status = getWikiStatus(paths);
+      const status = await getWikiStatus(paths);
       const config = readJson<Record<string, unknown>>(join(paths.dotWiki, "config.json"), {});
       const backlinks = readJson<Record<string, string[]>>(join(paths.meta, "backlinks.json"), {});
 
@@ -1108,6 +1167,10 @@ export function registerWikiStatus(pi: ExtensionAPI): void {
         `Gaps: ${gaps.gaps?.length || 0}`,
         `Health: ${health}`,
         `Last updated: ${status.lastUpdated || "Never"}`,
+        `QMD index: ${status.qmd.state}`,
+        `QMD documents: ${status.qmd.totalDocuments} (${status.qmd.canonicalDocuments} canonical, ${status.qmd.evidenceDocuments} evidence)`,
+        `QMD embeddings pending: ${status.qmd.needsEmbedding}`,
+        `QMD package: ${status.qmd.qmdVersion}`,
         ...diagLines,
       ];
 
@@ -1123,6 +1186,7 @@ export function registerWikiStatus(pi: ExtensionAPI): void {
           gaps: gaps.gaps?.length || 0,
           health,
           blockingDiagnostics: status.blockingDiagnostics,
+          qmd: status.qmd,
         } as Record<string, unknown>,
       };
     },
@@ -1170,6 +1234,22 @@ export function registerWikiRebuildMeta(pi: ExtensionAPI, runtime?: Runtime): vo
           const warnings = result.diagnostics.filter(
             (diagnostic) => diagnostic.severity === "warning",
           );
+          // After a successful projection, keep the generated QMD index in sync
+          // (model-free lexical pass). A QMD failure is a warning, never a
+          // projection failure.
+          const qmdResult = await reindexQmdVault(paths, {
+            scope: "changed",
+            components: ["lexical"],
+            force: false,
+          });
+          if (!qmdResult.ok) {
+            warnings.push({
+              severity: "warning" as const,
+              code: "qmd_index_error" as const,
+              path: paths.qmd,
+              message: qmdResult.errors[0]?.message ?? "QMD indexing failed",
+            });
+          }
           if (warnings.length > 0) {
             return `⚠️ LLM Wiki: metadata rebuilt with warnings — ${warnings
               .map((diagnostic) => `${diagnostic.code}: ${diagnostic.message}`)
@@ -1259,6 +1339,110 @@ export function registerWikiReindexEmbeddings(pi: ExtensionAPI, runtime?: Runtim
   });
 }
 
+export function registerWikiReindex(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "wiki_reindex",
+    label: "Wiki Reindex QMD",
+    description:
+      "Rebuild or repair the generated QMD index (meta/qmd) for the vault. " +
+      "Lexical indexing is model-free; selecting vectors may download " +
+      "approximately 2 GB of models on first use. Repair stale/error state. " +
+      "Active recall still uses the legacy heuristic until Phase 3.",
+    promptSnippet: "Rebuild the QMD search index",
+    promptGuidelines: [
+      "Use wiki_reindex to repair a stale, error, or recovering QMD index.",
+      "Lexical-only reindexing never loads a model.",
+      "Vector reindexing may download approximately 2 GB of models on first use.",
+    ],
+    parameters: Type.Object({
+      scope: Type.Optional(
+        Type.Union([Type.Literal("changed"), Type.Literal("all")], { default: "changed" }),
+      ),
+      components: Type.Optional(
+        Type.Array(Type.Union([Type.Literal("lexical"), Type.Literal("vectors")]), {
+          minItems: 1,
+          uniqueItems: true,
+          default: ["lexical", "vectors"],
+        }),
+      ),
+      force: Type.Optional(Type.Boolean({ default: false })),
+      vault: Type.Optional(
+        Type.Union(
+          [
+            Type.Literal("active"),
+            Type.Literal("personal"),
+            Type.Literal("project"),
+            Type.Literal("all"),
+          ],
+          { default: "active" },
+        ),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
+      const vaultCheck = inspectWritableVault(paths);
+      if (!vaultCheck.ok) {
+        return {
+          content: [
+            { type: "text", text: `Wiki vault error: ${vaultCheck.diagnostics[0].message}` },
+          ],
+          details: {
+            error: vaultCheck.diagnostics[0].code,
+            diagnostics: vaultCheck.diagnostics,
+          } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+
+      const scope = params.scope ?? "changed";
+      const components = params.components ?? ["lexical", "vectors"];
+      const force = params.force === true;
+      const vault = params.vault ?? "active";
+      const lexicalOnly = components.length === 1 && components[0] === "lexical";
+
+      // Warn before any vector work so the operator expects a large download.
+      if (components.includes("vectors") && signal && signal.aborted) {
+        return {
+          content: [{ type: "text", text: "QMD reindex cancelled before it started." }],
+          details: { cancelled: true } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+
+      const result = await reindexWiki(paths, {
+        scope,
+        components,
+        force,
+        vault,
+        signal,
+      });
+
+      const ok = result.results.every((r) => r.result.ok);
+      const lines = [
+        ok ? "✅ QMD indexing complete" : "⚠️ QMD indexing completed with errors",
+        ...result.results.map((r) => {
+          const st = r.result.status;
+          return `- ${r.label} (${r.root}): state=${st.state}, documents=${st.totalDocuments}, indexed=${r.result.documents.indexed}, updated=${r.result.documents.updated}, removed=${r.result.documents.removed}, vectors=${r.result.vectors.generated}`;
+        }),
+      ];
+      if (lexicalOnly) lines.push("Model-free lexical indexing — no model was downloaded.");
+      if (components.includes("vectors")) {
+        lines.push("⚠️ Vector indexing may download approximately 2 GB of models on first use.");
+      }
+      for (const r of result.results) {
+        for (const e of r.result.errors) lines.push(`- [${r.label}] ${e.code}: ${e.message}`);
+        for (const w of r.result.warnings) lines.push(`- [${r.label}] ${w.code}: ${w.message}`);
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: { scope, components, ...result } as Record<string, unknown>,
+        ...(ok ? {} : { isError: true }),
+      };
+    },
+  });
+}
+
 export function registerWikiLogEvent(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "wiki_log_event",

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

@@ -28,6 +28,11 @@ export interface VaultPaths {
   dotWiki: string;
   outputs: string;
   discoveries: string;
+  qmd: string;
+  qmdCurrent: string;
+  qmdDocuments: string;
+  qmdManifest: string;
+  qmdSwap: string;
 }
 
 /** Detect whether a vault root uses new (.llm-wiki) or legacy (.wiki) layout. */
@@ -200,31 +205,45 @@ export function resolveVaultRoot(cwd: string): string {
 
 /** Get all vault paths for the new (.llm-wiki) layout. */
 export function getVaultPaths(root: string): VaultPaths {
+  const meta = join(root, ".llm-wiki", "meta");
+  const qmd = join(meta, "qmd");
   return {
     root,
     raw: join(root, ".llm-wiki", "raw"),
     rawSources: join(root, ".llm-wiki", "raw", "sources"),
     rawTrajectories: join(root, ".llm-wiki", "raw", "trajectories"),
     wiki: join(root, ".llm-wiki", "wiki"),
-    meta: join(root, ".llm-wiki", "meta"),
+    meta,
     dotWiki: join(root, ".llm-wiki"),
     outputs: join(root, ".llm-wiki", "outputs"),
     discoveries: join(root, ".llm-wiki", ".discoveries"),
+    qmd,
+    qmdCurrent: join(qmd, "current"),
+    qmdDocuments: join(qmd, "documents"),
+    qmdManifest: join(qmd, "manifest.json"),
+    qmdSwap: join(qmd, "swap.json"),
   };
 }
 
 /** Get all vault paths for the legacy (.wiki) layout. */
 export function getLegacyVaultPaths(root: string): VaultPaths {
+  const meta = join(root, "meta");
+  const qmd = join(meta, "qmd");
   return {
     root,
     raw: join(root, "raw"),
     rawSources: join(root, "raw", "sources"),
     rawTrajectories: join(root, "raw", "trajectories"),
     wiki: join(root, "wiki"),
-    meta: join(root, "meta"),
+    meta,
     dotWiki: join(root, ".wiki"),
     outputs: join(root, "outputs"),
     discoveries: join(root, ".discoveries"),
+    qmd,
+    qmdCurrent: join(qmd, "current"),
+    qmdDocuments: join(qmd, "documents"),
+    qmdManifest: join(qmd, "manifest.json"),
+    qmdSwap: join(qmd, "swap.json"),
   };
 }
 

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

@@ -2,13 +2,24 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import type { KnowledgeDiagnostic } from "./knowledge-document.js";
 import type { Registry } from "./metadata.js";
+import {
+  awaitQmdIndexQueue,
+  type QmdGeneratedStatus,
+  type QmdIndexProgress,
+  type QmdIndexState,
+  type QmdReindexResult,
+  readQmdIndexStatus,
+  reindexQmdVault,
+} from "./qmd-indexing.js";
+import { QMD_PACKAGE_VERSION, resolveQmdModels } from "./qmd-store.js";
 import type { VaultPaths } from "./utils.js";
-import { readJson } from "./utils.js";
+import { getPersonalWikiPaths, isPersonalVault, readJson } from "./utils.js";
 import type { KnowledgeFormat } from "./vault-format.js";
 import {
   compareCodePoint,
   discoverKnowledgeDocuments,
   inspectVaultFormat,
+  inspectWritableVault,
 } from "./vault-format.js";
 
 /**
@@ -29,12 +40,13 @@ export interface WikiStatusSnapshot {
   byType: Record<string, number>;
   blockingDiagnostics: KnowledgeDiagnostic[];
   lastUpdated: string;
+  qmd: QmdGeneratedStatus;
 }
 
 /**
  * Search the registry for matching concepts.
  *
- * Matches ID, semantic title, type, category, domain, tags, aliases, and recall triggers.
+ * Matches ID, title, type, state, status, category, domain, tags, aliases, and recall triggers.
  * Preserves unknown types as strings.
  */
 export function searchRegistry(
@@ -102,6 +114,22 @@ function matchesField(id: string, entry: Record<string, unknown>, query: string)
   )
     return true;
 
+  // Match state
+  if (
+    String(entry.state || "")
+      .toLowerCase()
+      .includes(query)
+  )
+    return true;
+
+  // Match status
+  if (
+    String(entry.status || "")
+      .toLowerCase()
+      .includes(query)
+  )
+    return true;
+
   // Match category/domain
   if (
     String(entry.category || "")
@@ -146,9 +174,10 @@ function matchesField(id: string, entry: Record<string, unknown>, query: string)
 /**
  * Get a status snapshot of the wiki.
  *
- * Reports resolved knowledge_format, page counts, and blocking diagnostics.
+ * Reports resolved knowledge_format, page counts, blocking diagnostics, and
+ * generated QMD index status (read without opening any QMD store).
  */
-export function getWikiStatus(paths: VaultPaths): WikiStatusSnapshot {
+export async function getWikiStatus(paths: VaultPaths): Promise<WikiStatusSnapshot> {
   const vaultState = inspectVaultFormat(paths);
   const diagnostics = [...vaultState.diagnostics];
 
@@ -179,5 +208,132 @@ export function getWikiStatus(paths: VaultPaths): WikiStatusSnapshot {
     byType,
     blockingDiagnostics: diagnostics.filter((d) => d.severity === "error"),
     lastUpdated: registry?.last_updated || "",
+    qmd: await readQmdIndexStatus(paths),
+  };
+}
+
+// ─── Shared QMD reindex operation ─────────────────────────
+
+export type WikiReindexVault = "active" | "personal" | "project" | "all";
+
+export interface WikiReindexInput {
+  scope?: "changed" | "all";
+  components?: Array<"lexical" | "vectors">;
+  force?: boolean;
+  vault?: WikiReindexVault;
+  signal?: AbortSignal;
+  onProgress?: (progress: { vault: string; progress: QmdIndexProgress }) => void;
+}
+
+export interface WikiReindexResult {
+  vault: WikiReindexVault;
+  results: Array<{
+    root: string;
+    label: "active" | "personal" | "project";
+    result: QmdReindexResult;
+  }>;
+}
+
+function blockedReindexResult(
+  scope: "changed" | "all",
+  components: Array<"lexical" | "vectors">,
+  code: string,
+  message: string,
+): QmdReindexResult {
+  return {
+    ok: false,
+    scope,
+    components,
+    documents: { indexed: 0, updated: 0, unchanged: 0, removed: 0 },
+    vectors: { generated: 0, skipped: 0, errors: 0 },
+    elapsedMs: 0,
+    status: {
+      state: "error" as QmdIndexState,
+      qmdVersion: QMD_PACKAGE_VERSION,
+      models: resolveQmdModels(),
+      totalDocuments: 0,
+      canonicalDocuments: 0,
+      evidenceDocuments: 0,
+      needsEmbedding: 0,
+      hasVectorIndex: false,
+      repairComponents: [],
+      issues: [{ code, message }],
+    },
+    warnings: [],
+    errors: [{ code, message }],
   };
 }
+
+/**
+ * Reindex QMD stores for selected vaults, sequentially. Validates each vault
+ * immediately before work. One vault's failure does not prevent the others.
+ */
+export async function reindexWiki(
+  activePaths: VaultPaths,
+  input: WikiReindexInput,
+): Promise<WikiReindexResult> {
+  const scope = input.scope ?? "changed";
+  const components = input.components ?? ["lexical", "vectors"];
+  const force = input.force ?? false;
+  const vault = input.vault ?? "active";
+  const signal = input.signal;
+  const onProgress = input.onProgress;
+
+  const personalPaths = getPersonalWikiPaths();
+  const activeIsPersonal = isPersonalVault(activePaths);
+
+  const targets: Array<{ paths: VaultPaths; label: "active" | "personal" | "project" }> = [];
+  switch (vault) {
+    case "active":
+      targets.push({ paths: activePaths, label: activeIsPersonal ? "personal" : "active" });
+      break;
+    case "personal":
+      targets.push({ paths: personalPaths, label: "personal" });
+      break;
+    case "project":
+      if (!activeIsPersonal) targets.push({ paths: activePaths, label: "project" });
+      break;
+    case "all":
+      if (!activeIsPersonal) targets.push({ paths: activePaths, label: "project" });
+      targets.push({ paths: personalPaths, label: "personal" });
+      break;
+  }
+
+  const seen = new Set<string>();
+  const results: WikiReindexResult["results"] = [];
+  for (const target of targets) {
+    if (seen.has(target.paths.root)) continue;
+    seen.add(target.paths.root);
+
+    const check = inspectWritableVault(target.paths);
+    if (!check.ok) {
+      results.push({
+        root: target.paths.root,
+        label: target.label,
+        result: blockedReindexResult(
+          scope,
+          components,
+          check.diagnostics[0]?.code ?? "config_invalid_knowledge_format",
+          check.diagnostics[0]?.message ?? "Vault is not writable",
+        ),
+      });
+      continue;
+    }
+
+    const result = await reindexQmdVault(target.paths, {
+      scope,
+      components,
+      force,
+      signal,
+      onProgress: (p) => onProgress?.({ vault: target.paths.root, progress: p }),
+    });
+    results.push({ root: target.paths.root, label: target.label, result });
+  }
+
+  return { vault, results };
+}
+
+/** Test-only: drain/await in-process QMD reindex queue work for a vault root. */
+export function awaitWikiQmdIndexQueue(root: string): Promise<unknown> {
+  return awaitQmdIndexQueue(root);
+}

package/mcp/index.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
+import { recoverQmdIndex } from "../extensions/llm-wiki/lib/qmd-indexing.js";
 import {
   loadTaskConfig,
   resolveWikilinkValidation,
@@ -25,6 +26,7 @@ import {
   bootstrapOperation,
   captureSourceOperation,
   recallOperation,
+  reindexOperation,
   retroOperation,
   searchOperation,
   statusOperation,
@@ -68,7 +70,7 @@ const server = new McpServer({
 // ---- 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
+// other tools 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(
@@ -238,6 +240,65 @@ server.registerTool(
   },
 );
 
+// ---- wiki_reindex ----
+
+server.registerTool(
+  "wiki_reindex",
+  {
+    description:
+      "Rebuild or repair the generated QMD search index (meta/qmd) for the vault. " +
+      "Lexical indexing is model-free; selecting vectors may download approximately 2 GB " +
+      "of models on first use. Options: scope (changed|all), components (lexical|vectors), " +
+      "force, vault (active|personal|project|all).",
+    inputSchema: z.object({
+      scope: z.enum(["changed", "all"]).optional().default("changed").describe("changed or all"),
+      components: z
+        .array(z.enum(["lexical", "vectors"]))
+        .min(1)
+        .optional()
+        .describe("Index components (lexical|vectors)"),
+      force: z.boolean().optional().describe("Force full rebuild of selected components"),
+      vault: z
+        .enum(["active", "personal", "project", "all"])
+        .optional()
+        .default("active")
+        .describe("Which vaults to reindex"),
+    }),
+  },
+  async ({ scope, components, force, vault }) => {
+    if (!hasVault()) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: "No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const paths = getPaths();
+    const result = await reindexOperation(paths, {
+      scope,
+      components,
+      force,
+      vault,
+    });
+
+    const ok = result.results.every((r) => r.result.ok);
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+      ...(ok ? {} : { isError: true as const }),
+    };
+  },
+);
+
 // ---- wiki_retro ----
 
 server.registerTool(
@@ -363,6 +424,22 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error("🧠 LLM Wiki MCP Server running on stdio");
+
+  // Fire-and-forget QMD index recovery AFTER the transport is connected so
+  // clients are never blocked. A busy/live lock just logs a warning and MCP
+  // continues with current state untouched.
+  if (hasVault()) {
+    const paths = getPaths();
+    recoverQmdIndex(paths)
+      .then((result) => {
+        if (!result.ok) {
+          console.error(
+            `[llm-wiki] QMD recovery skipped: ${result.diagnostics[0]?.message ?? "locked"}`,
+          );
+        }
+      })
+      .catch((err) => console.error(`[llm-wiki] QMD recovery failed: ${(err as Error).message}`));
+  }
 }
 
 main().catch((err) => {