@zosmaai/pi-llm-wiki 0.10.7 → 0.11.0

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

@@ -0,0 +1,84 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { KnowledgeDiagnostic } from "./knowledge-document.js";
+import { type ProjectionResult, appendEvent, rebuildMetadata } from "./metadata.js";
+import { type VaultPaths, ensureVaultStructure, fmtDate, writeJson } from "./utils.js";
+import { inspectWritableVault, readVaultConfig } from "./vault-format.js";
+
+export const WIKI_SCHEMA = [
+  "# LLM Wiki Schema",
+  "",
+  "## Ownership Rules",
+  "",
+  "| Path | Owner | Rule |",
+  "|------|-------|------|",
+  "| raw/** | extension | immutable after capture |",
+  "| wiki/** | model + user | editable knowledge pages |",
+  "| meta/* | extension | auto-generated |",
+  "| . | human + explicit request | operating rules |",
+  "",
+  "## Source Packet Format",
+  "",
+  "```",
+  "raw/sources/SRC-YYYY-MM-DD-NNN/",
+  "  manifest.json",
+  "  original/",
+  "  extracted.md",
+  "  attachments/",
+  "```",
+  "",
+  "## Page Types",
+  "",
+  "- **source** — what this specific source says",
+  "- **entity** — people, orgs, tools, products",
+  "- **concept** — ideas, patterns, frameworks",
+  "- **synthesis** — cross-source theses and tensions",
+  "- **analysis** — durable filed answers from queries",
+  "- **requirement** — atomic requirements with status, priority, and traceability",
+  "",
+  "## Linking Style",
+  "",
+  "- New internal links: [label](/folder/page.md)",
+  "- Legacy readable links: [[folder/page]]",
+  "- Source citation: [source](/sources/SRC-YYYY-MM-DD-NNN.md)",
+  "",
+].join("\n");
+
+export interface BootstrapInput {
+  topic: string;
+  mode: string;
+}
+
+export type BootstrapResult =
+  | { ok: true; created: boolean; projection: ProjectionResult }
+  | { ok: false; created: false; diagnostics: KnowledgeDiagnostic[] };
+
+export function bootstrapVault(paths: VaultPaths, input: BootstrapInput): BootstrapResult {
+  const configPath = join(paths.dotWiki, "config.json");
+  const created = !existsSync(paths.dotWiki);
+  let existing: Record<string, unknown> = {};
+
+  if (!created) {
+    const writable = inspectWritableVault(paths);
+    if (!writable.ok) return { ok: false, created: false, diagnostics: writable.diagnostics };
+    const config = readVaultConfig(paths);
+    if (!config.ok) return { ok: false, created: false, diagnostics: [config.diagnostic] };
+    existing = config.config;
+  }
+
+  const config: Record<string, unknown> = {
+    ...existing,
+    name: input.topic,
+    mode: input.mode,
+    topic: input.topic,
+    created: existing.created ?? fmtDate(),
+    version: existing.version ?? "1.0",
+    ...(created ? { knowledge_format: "okf-0.2" } : {}),
+  };
+
+  ensureVaultStructure(paths);
+  writeJson(configPath, config);
+  writeFileSync(join(paths.dotWiki, "WIKI_SCHEMA.md"), WIKI_SCHEMA, "utf8");
+  appendEvent(paths, { kind: "bootstrap", topic: input.topic, mode: input.mode });
+  return { ok: true, created, projection: rebuildMetadata(paths) };
+}

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

@@ -3,10 +3,12 @@ import { existsSync, readFileSync } from "node:fs";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { join } from "node:path";
+import { parseKnowledgeDocument } from "./knowledge-document.js";
 import type { Registry } from "./metadata.js";
 import type { LaunchCtx, Runtime } from "./runtime.js";
 import type { TaskConfig } from "./task-config.js";
-import { type VaultPaths, parseFrontmatter, readJson, writeJson } from "./utils.js";
+import { type VaultPaths, readJson, writeJson } from "./utils.js";
+import { assertWritableVault } from "./vault-format.js";
 
 /**
  * Background semantic embeddings, computed at write time (issue #66, epic #63).
@@ -166,6 +168,7 @@ export function readEmbeddingStore(paths: VaultPaths): EmbeddingStore {
 }
 
 export function writeEmbeddingStore(paths: VaultPaths, store: EmbeddingStore): void {
+  assertWritableVault(paths);
   writeJson(embeddingStorePath(paths), store);
 }
 
@@ -189,8 +192,9 @@ function readPageText(paths: VaultPaths, id: string): PageText | undefined {
   const pagePath = join(paths.wiki, `${id}.md`);
   if (!existsSync(pagePath)) return undefined;
   const raw = readFileSync(pagePath, "utf-8");
-  const { frontmatter, body } = parseFrontmatter(raw);
-  const text = buildEmbeddingText(id, frontmatter, body);
+  const result = parseKnowledgeDocument(raw, `${id}.md`);
+  if (!result.ok) return undefined;
+  const text = buildEmbeddingText(id, result.document.frontmatter, result.document.body);
   return { id, text, hash: contentHash(text) };
 }
 
@@ -205,6 +209,7 @@ export async function embedPages(
   embedder: Embedder,
   opts: { force?: boolean } = {},
 ): Promise<EmbedStats> {
+  assertWritableVault(paths);
   const store = readEmbeddingStore(paths);
   const targets: PageText[] = [];
   let skipped = 0;
@@ -251,6 +256,7 @@ export async function reindexEmbeddings(
   embedder: Embedder,
   opts: { force?: boolean } = {},
 ): Promise<ReindexStats> {
+  assertWritableVault(paths);
   const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
     version: "1.0",
     last_updated: "",

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

@@ -1,10 +1,11 @@
-import { resolve, sep } from "node:path";
 import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { scheduleReindex } from "./indexing.js";
 import { rebuildMetadataLight } from "./metadata.js";
 import type { Runtime } from "./runtime.js";
-import { isProtectedPath, resolveVaultPaths } from "./utils.js";
+import { isPathWithin, isProtectedPath, resolveVaultPaths } from "./utils.js";
+import type { VaultPaths } from "./utils.js";
+import { inspectVaultFormat, isGeneratedOkfPath } from "./vault-format.js";
 
 /**
  * Guardrails and auto-rebuild hooks for the LLM Wiki extension.
@@ -12,64 +13,208 @@ import { isProtectedPath, resolveVaultPaths } from "./utils.js";
 
 let pendingRebuild = false;
 
-const PATCH_HEADER = /^\[([^#\r\n]+)#[0-9A-F]{4}\]$/gm;
+const APPLY_PATCH_PATH_NOISE =
+  /^\*{0,3}\s*(?:(?:update|add|delete|move)[^A-Za-z0-9]*(?:file|to)?[^A-Za-z0-9]*:)?\s*\*{0,3}\s*/i;
+const PATCH_INPUT_KEYS: Record<string, true> = { input: true, _input: true, patch: true };
+const DESTINATION_KEYS: Record<string, true> = {
+  rename: true,
+  move: true,
+  dest: true,
+  destination: true,
+  newPath: true,
+};
 
-function collectMutationPaths(input: unknown, seen: WeakSet<object>): string[] {
+interface MutationScan {
+  paths: string[];
+  complete: boolean;
+}
+
+function normalizeMutationPath(target: string): string | undefined {
+  const trimmed = target.trim();
+  if (!trimmed) return undefined;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  const quoted = first === '"' || first === "'";
+  if (quoted !== (last === '"' || last === "'") || (quoted && first !== last)) {
+    return undefined;
+  }
+  const unquoted = quoted ? trimmed.slice(1, -1) : trimmed;
+  return unquoted.replace(APPLY_PATCH_PATH_NOISE, "") || undefined;
+}
+
+function parsePatchHeader(line: string): string | undefined {
+  const trimmed = line.replace(/\r$/, "").trimEnd();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return undefined;
+
+  const body = trimmed.slice(1, -1).trim();
+  const tag = /#[0-9A-Fa-f]{4}\s*$/.exec(body);
+  const rawTarget = tag ? body.slice(0, tag.index) : body.replace(/\s+$/, "");
+  if (!rawTarget || rawTarget.includes("#")) return undefined;
+
+  return normalizeMutationPath(rawTarget);
+}
+
+function parseMoveDestination(line: string): string | undefined {
+  const rawDestination = line.trim().slice(2).trim();
+  if (!rawDestination) return undefined;
+  const quote = rawDestination[0];
+  if (quote !== '"' && quote !== "'") return normalizeMutationPath(rawDestination);
+
+  let cursor = 1;
+  while (cursor < rawDestination.length) {
+    if (rawDestination[cursor] === "\\" && cursor + 1 < rawDestination.length) {
+      cursor += 2;
+      continue;
+    }
+    if (rawDestination[cursor] === quote) {
+      return cursor === rawDestination.length - 1
+        ? normalizeMutationPath(rawDestination)
+        : undefined;
+    }
+    cursor++;
+  }
+  return undefined;
+}
+
+function scanPatchString(input: string): MutationScan {
+  const paths: string[] = [];
+  let sawHeader = false;
+  let sectionHasMove = false;
+  let complete = true;
+  const stripped = input.startsWith("\uFEFF") ? input.slice(1) : input;
+
+  for (const line of stripped.split("\n")) {
+    const trimmed = line.replace(/\r$/, "").trim();
+    if (trimmed.startsWith("[")) {
+      sawHeader = true;
+      sectionHasMove = false;
+      const path = parsePatchHeader(line);
+      if (path) paths.push(path);
+      else complete = false;
+      continue;
+    }
+    if (!/^MV(?:\s|$)/.test(trimmed)) continue;
+    const destination = parseMoveDestination(trimmed);
+    if (!sawHeader || sectionHasMove || !destination) complete = false;
+    else {
+      paths.push(destination);
+      sectionHasMove = true;
+    }
+  }
+
+  return { paths, complete: sawHeader && complete };
+}
+
+function mergeMutationScans(target: MutationScan, source: MutationScan): void {
+  target.paths.push(...source.paths);
+  target.complete &&= source.complete;
+}
+
+function addMutationPath(scan: MutationScan, target: string): void {
+  const path = normalizeMutationPath(target);
+  if (path) scan.paths.push(path);
+  else scan.complete = false;
+}
+
+function collectMutationPaths(
+  input: unknown,
+  seen: WeakSet<object>,
+  stringsArePatches = false,
+): MutationScan {
   if (typeof input === "string") {
-    return Array.from(input.matchAll(PATCH_HEADER), ([, target]) => target);
+    return stringsArePatches ? scanPatchString(input) : { paths: [], complete: true };
+  }
+  if (!input || typeof input !== "object" || seen.has(input)) {
+    return { paths: [], complete: true };
   }
-  if (!input || typeof input !== "object" || seen.has(input)) return [];
 
   seen.add(input);
-  if (Array.isArray(input)) return input.flatMap((value) => collectMutationPaths(value, seen));
+  const scan: MutationScan = { paths: [], complete: true };
+  if (Array.isArray(input)) {
+    for (const value of input) {
+      mergeMutationScans(scan, collectMutationPaths(value, seen, stringsArePatches));
+    }
+    return scan;
+  }
 
-  const { path, ...nested } = input as Record<string, unknown>;
-  if (typeof path === "string" && path.length > 0) return [path];
+  const record = input as Record<string, unknown>;
+  if (typeof record.path === "string" && record.path.length > 0) {
+    addMutationPath(scan, record.path);
+  }
+  const eventPaths = Array.isArray(record.paths) ? record.paths : [record.paths];
+  for (const path of eventPaths) {
+    if (typeof path === "string" && path.length > 0) addMutationPath(scan, path);
+  }
+
+  for (const [key, value] of Object.entries(record)) {
+    if (key === "path" || key === "paths") continue;
+    if (DESTINATION_KEYS[key] === true) {
+      if (typeof value === "string" && value.length > 0) addMutationPath(scan, value);
+      else scan.complete = false;
+      continue;
+    }
+    const childStringsArePatches = stringsArePatches || PATCH_INPUT_KEYS[key] === true;
+    if (typeof value !== "string" && (!value || typeof value !== "object")) continue;
+    mergeMutationScans(scan, collectMutationPaths(value, seen, childStringsArePatches));
+  }
+  return scan;
+}
 
-  return Object.values(nested).flatMap((value) => collectMutationPaths(value, seen));
+function inspectMutationPaths(input: unknown): MutationScan {
+  const stringsArePatches = typeof input === "string" || Array.isArray(input);
+  const scan = collectMutationPaths(input, new WeakSet(), stringsArePatches);
+  return { paths: [...new Set(scan.paths)], complete: scan.complete };
 }
 
 /** Return every file path targeted by a write or patch-shaped edit input. */
 export function extractMutationPaths(input: unknown): string[] {
-  return [...new Set(collectMutationPaths(input, new WeakSet()))];
+  return inspectMutationPaths(input).paths;
 }
 
 /** True when a write or patch-shaped edit targets a page in the wiki directory. */
 export function hasWikiMutation(input: unknown, wikiPath: string): boolean {
-  const resolvedWikiPath = resolve(wikiPath);
-  return extractMutationPaths(input).some((path) => {
-    const resolvedPath = resolve(path);
-    return (
-      resolvedPath === resolvedWikiPath || resolvedPath.startsWith(`${resolvedWikiPath}${sep}`)
-    );
-  });
+  return extractMutationPaths(input).some((path) => isPathWithin(wikiPath, path));
+}
+
+export function mutationBlockReason(path: string, paths: VaultPaths): string | undefined {
+  const protectedPath = isProtectedPath(path, paths);
+  if (protectedPath.protected) return protectedPath.reason;
+
+  if (isPathWithin(paths.dotWiki, path)) {
+    const state = inspectVaultFormat(paths);
+    if (state.blocking) {
+      return `Wiki vault configuration is invalid: ${state.diagnostics[0].message}`;
+    }
+  }
+
+  if (isGeneratedOkfPath(path, paths)) {
+    return "Generated OKF indexes and log are read-only. Use wiki_rebuild_meta or the page-producing tool that owns the source mutation.";
+  }
+  return undefined;
 }
 
 /** Install guardrails on the extension API. */
 export function installGuardrails(pi: ExtensionAPI, runtime?: Runtime): void {
-  // Block direct edits to raw/ and meta/
+  // Block direct edits to raw/ and meta/, plus OKF generated projections
   pi.on("tool_call", async (event) => {
     if (isToolCallEventType("write", event)) {
       const path = event.input.path as string;
       const paths = resolveVaultPaths(process.cwd());
-      const check = isProtectedPath(path, paths);
-      if (check.protected) {
-        return { block: true, reason: check.reason };
-      }
+      const reason = mutationBlockReason(path, paths);
+      if (reason) return { block: true, reason };
     }
 
     if (isToolCallEventType("edit", event)) {
-      const targetPaths = extractMutationPaths(event.input);
-      if (targetPaths.length === 0) {
+      const mutation = inspectMutationPaths(event.input);
+      const targetPaths = mutation.paths;
+      if (!mutation.complete || targetPaths.length === 0) {
         return { block: true, reason: "Cannot determine the files targeted by this edit." };
       }
 
       const paths = resolveVaultPaths(process.cwd());
       for (const path of targetPaths) {
-        const check = isProtectedPath(path, paths);
-        if (check.protected) {
-          return { block: true, reason: check.reason };
-        }
+        const reason = mutationBlockReason(path, paths);
+        if (reason) return { block: true, reason };
       }
     }
   });

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

@@ -64,7 +64,8 @@ export function scheduleReindex(
       // that land during embedding are not lost.
       while (dirty.has(root)) {
         dirty.delete(root);
-        rebuildMetadataLight(paths);
+        const projection = rebuildMetadataLight(paths);
+        if (!projection.ok) continue;
 
         // Refresh embeddings only after metadata is consistent. Stale-aware and
         // a no-op unless an embedder is configured.

package/extensions/llm-wiki/lib/ingest-worker.ts

@@ -4,9 +4,19 @@ import type { AgentTool } from "@mariozechner/pi-agent-core";
 import type { Api, Model } from "@mariozechner/pi-ai";
 import { Type } from "typebox";
 import type { Static } from "typebox";
+import {
+  type KnowledgeDiagnostic,
+  type KnowledgeDocument,
+  createKnowledgeDocument,
+  patchKnowledgeDocument,
+  readKnowledgeDocumentFile,
+  serializeKnowledgeDocument,
+  writeKnowledgeDocumentFile,
+} from "./knowledge-document.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
 import { runSubAgent } from "./subagent.js";
 import { type VaultPaths, fmtDate, slugify } from "./utils.js";
+import { VaultWriteError, assertWritableVault } from "./vault-format.js";
 
 /**
  * Background ingest synthesis (issue #65, part of epic #63).
@@ -76,39 +86,51 @@ export interface CommitResult {
   contradictions: number;
 }
 
+export type CommitSynthesisOutcome =
+  | ({ ok: true } & CommitResult)
+  | { ok: false; sourceId: string; diagnostics: KnowledgeDiagnostic[] };
+
 // ── deterministic persistence (no LLM) ────────────────────
 
-function buildEntityPage(
-  title: string,
-  description: string,
-  date: string,
-  sourceId: string,
-): string {
+function buildEntityPageBody(title: string, description: string, sourceId: string): string {
   const desc = description.trim() || "One-line description.";
-  return `---\ntype: entity\ncreated: ${date}\nupdated: ${date}\nsources: [[[sources/${sourceId}]]]\n---\n\n# ${title}\n\n${desc}\n\n## Overview\n\n[Key facts]\n\n## Links\n\n- [[sources/${sourceId}]]\n`;
+  return `# ${title}
+
+${desc}
+
+## Overview
+
+[Key facts]
+
+## Links
+
+- [${sourceId}](/sources/${sourceId}.md)`;
 }
 
-function buildConceptPage(
-  title: string,
-  definition: string,
-  date: string,
-  sourceId: string,
-): string {
+function buildConceptPageBody(title: string, definition: string, sourceId: string): string {
   const def = definition.trim() || "One-line definition.";
-  return `---\ntype: concept\ncreated: ${date}\nupdated: ${date}\nsources: [[[sources/${sourceId}]]]\n---\n\n# ${title}\n\n${def}\n\n## Definition\n\n[Clear explanation]\n\n## Links\n\n- [[sources/${sourceId}]]\n`;
+  return `# ${title}
+
+${def}
+
+## Definition
+
+[Clear explanation]
+
+## Links
+
+- [${sourceId}](/sources/${sourceId}.md)`;
 }
 
-/** Rebuild the source page from synthesis data, marking it ingested. */
-export function buildIngestedSourcePage(
+/** Rebuild the source page body from synthesis data, marking it ingested. */
+export function buildIngestedSourcePageBody(
   manifest: Record<string, unknown>,
   data: SynthesisData,
-  date: string,
+  _date: string,
 ): string {
   const id = String(manifest.id);
   const title = String(manifest.title || id);
   const url = manifest.url ? `\n> _Original: [${manifest.url}](${manifest.url})_` : "";
-  const format = String(manifest.format || "unknown");
-  const captured = String(manifest.captured || date);
 
   const takeaways =
     data.key_takeaways.length > 0
@@ -116,11 +138,11 @@ export function buildIngestedSourcePage(
       : "- [None recorded]";
   const entities =
     data.entities.length > 0
-      ? data.entities.map((e) => `- [[entities/${slugify(e.title)}]]`).join("\n")
+      ? data.entities.map((e) => `- [${e.title}](/entities/${slugify(e.title)}.md)`).join("\n")
       : "- [None]";
   const concepts =
     data.concepts.length > 0
-      ? data.concepts.map((c) => `- [[concepts/${slugify(c.title)}]]`).join("\n")
+      ? data.concepts.map((c) => `- [${c.title}](/concepts/${slugify(c.title)}.md)`).join("\n")
       : "- [None]";
   const quotes =
     data.quotes && data.quotes.length > 0
@@ -133,7 +155,61 @@ export function buildIngestedSourcePage(
       ? `\n## Contradictions\n\n${data.contradictions.map((c) => `⚠️ **Contradiction**: ${c.trim()}`).join("\n")}\n`
       : "";
 
-  return `---\ntype: source\nformat: ${format}\nsource_id: ${id}\nraw_path: raw/sources/${id}/extracted.md\ncaptured: ${captured}\nstatus: ingested\nupdated: ${date}\n---\n\n# ${title}${url}\n\n## Summary\n\n${data.summary.trim()}\n\n## Key Takeaways\n\n${takeaways}\n\n## Entities Mentioned\n\n${entities}\n\n## Concepts Mentioned\n\n${concepts}\n\n## Notable Quotes\n\n${quotes}\n${contradictions}\n## Source Packet\n\n- **ID:** \`[[sources/${id}]]\`\n- **Extracted:** [raw/sources/${id}/extracted.md](../raw/sources/${id}/extracted.md)\n- **Manifest:** [raw/sources/${id}/manifest.json](../raw/sources/${id}/manifest.json)\n`;
+  return `# ${title}${url}
+
+## Summary
+
+${data.summary.trim()}
+
+## Key Takeaways
+
+${takeaways}
+
+## Entities Mentioned
+
+${entities}
+
+## Concepts Mentioned
+
+${concepts}
+
+## Notable Quotes
+
+${quotes}
+${contradictions}## Source Packet
+
+- **ID:** \`sources/${id}\`
+- **Extracted:** \`raw/sources/${id}/extracted.md\`
+- **Manifest:** \`raw/sources/${id}/manifest.json\`
+`;
+}
+
+/** Rebuild the source page from synthesis data, marking it ingested. */
+export function buildIngestedSourcePage(
+  manifest: Record<string, unknown>,
+  data: SynthesisData,
+  date: string,
+): string {
+  const id = String(manifest.id);
+  const title = String(manifest.title || id);
+  const format = String(manifest.format || "unknown");
+  const captured = String(manifest.captured || date);
+  const body = buildIngestedSourcePageBody(manifest, data, date);
+  const doc = createKnowledgeDocument(
+    `sources/${id}.md`,
+    {
+      type: "source",
+      title,
+      format,
+      source_id: id,
+      raw_path: `raw/sources/${id}/extracted.md`,
+      captured,
+      status: "ingested",
+      updated: date,
+    },
+    body,
+  );
+  return serializeKnowledgeDocument(doc);
 }
 
 /**
@@ -147,7 +223,7 @@ export function commitSynthesis(
   manifest: Record<string, unknown>,
   data: SynthesisData,
   date: string = fmtDate(),
-): CommitResult {
+): CommitSynthesisOutcome {
   const result: CommitResult = {
     sourceId,
     sourcePage: join(paths.wiki, "sources", `${sourceId}.md`),
@@ -158,9 +234,42 @@ export function commitSynthesis(
     contradictions: data.contradictions?.length ?? 0,
   };
 
-  // Source page (always rewritten from skeleton → ingested).
+  try {
+    assertWritableVault(paths);
+  } catch (error: unknown) {
+    if (error instanceof VaultWriteError) {
+      return { ok: false, sourceId, diagnostics: error.diagnostics };
+    }
+    throw error;
+  }
+
+  // Patch existing documents so unknown fields, legacy sources, and titles survive.
+  let sourceDocument: KnowledgeDocument;
+  if (existsSync(result.sourcePage)) {
+    const parsed = readKnowledgeDocumentFile(result.sourcePage, `sources/${sourceId}.md`);
+    if (!parsed.ok) return { ok: false, sourceId, diagnostics: parsed.diagnostics };
+    sourceDocument = patchKnowledgeDocument(parsed.document, {
+      fields: { status: "ingested", updated: date },
+      body: buildIngestedSourcePageBody(manifest, data, date),
+    });
+  } else {
+    sourceDocument = createKnowledgeDocument(
+      `sources/${sourceId}.md`,
+      {
+        type: "source",
+        title: String(manifest.title || sourceId),
+        format: String(manifest.format || "unknown"),
+        source_id: sourceId,
+        raw_path: `raw/sources/${sourceId}/extracted.md`,
+        captured: String(manifest.captured || date),
+        status: "ingested",
+        updated: date,
+      },
+      buildIngestedSourcePageBody(manifest, data, date),
+    );
+  }
   mkdirSync(join(paths.wiki, "sources"), { recursive: true });
-  writeFileSync(result.sourcePage, buildIngestedSourcePage(manifest, data, date), "utf-8");
+  writeKnowledgeDocumentFile(result.sourcePage, sourceDocument);
 
   // Entity pages — create if absent, link if present.
   mkdirSync(join(paths.wiki, "entities"), { recursive: true });
@@ -171,7 +280,19 @@ export function commitSynthesis(
     if (existsSync(pagePath)) {
       result.entitiesLinked.push(slug);
     } else {
-      writeFileSync(pagePath, buildEntityPage(e.title, e.description, date, sourceId), "utf-8");
+      const entityDoc = createKnowledgeDocument(
+        `entities/${slug}.md`,
+        {
+          type: "entity",
+          title: e.title,
+          description: e.description.trim() || "One-line description.",
+          created: date,
+          updated: date,
+        },
+        buildEntityPageBody(e.title, e.description, sourceId),
+        [{ id: sourceId, resource: `/sources/${sourceId}.md` }],
+      );
+      writeKnowledgeDocumentFile(pagePath, entityDoc);
       result.entitiesCreated.push(slug);
     }
   }
@@ -185,7 +306,19 @@ export function commitSynthesis(
     if (existsSync(pagePath)) {
       result.conceptsLinked.push(slug);
     } else {
-      writeFileSync(pagePath, buildConceptPage(c.title, c.definition, date, sourceId), "utf-8");
+      const conceptDoc = createKnowledgeDocument(
+        `concepts/${slug}.md`,
+        {
+          type: "concept",
+          title: c.title,
+          description: c.definition.trim() || "One-line definition.",
+          created: date,
+          updated: date,
+        },
+        buildConceptPageBody(c.title, c.definition, sourceId),
+        [{ id: sourceId, resource: `/sources/${sourceId}.md` }],
+      );
+      writeKnowledgeDocumentFile(pagePath, conceptDoc);
       result.conceptsCreated.push(slug);
     }
   }
@@ -199,7 +332,7 @@ export function commitSynthesis(
     background: true,
   });
 
-  return result;
+  return { ok: true, ...result };
 }
 
 // ── sub-agent synthesis (LLM) ─────────────────────────────
@@ -253,7 +386,15 @@ export async function runIngestSynthesis(
       "Persist the structured synthesis of this source into wiki pages. Call exactly once.",
     parameters: CommitSynthesisSchema,
     execute: async (_id, params) => {
-      committed = commitSynthesis(paths, sourceId, manifest, params);
+      const outcome = commitSynthesis(paths, sourceId, manifest, params);
+      if (!outcome.ok) {
+        return {
+          content: [{ type: "text", text: `Failed: ${outcome.diagnostics[0].message}` }],
+          details: { sourceId },
+          isError: true,
+        };
+      }
+      committed = outcome;
       const ack = `Committed: source page + ${committed.entitiesCreated.length} new entit${
         committed.entitiesCreated.length === 1 ? "y" : "ies"
       }, ${committed.conceptsCreated.length} new concept${