@zosmaai/pi-llm-wiki 0.11.4 → 0.11.6

package/extensions/llm-wiki/index.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { bootstrapVault } from "./lib/bootstrap.js";
+import { registerWikiDashboardCommand } from "./lib/dashboard-command.js";
 import { installGuardrails } from "./lib/guardrails.js";
 import { buildAgentStartInjection, normalizeSystemPrompt } from "./lib/inject.js";
 import { registerWikiModelCommand } from "./lib/model-command.js";
@@ -20,6 +21,7 @@ import {
 } from "./lib/recall.js";
 import { registerWikiRetro } from "./lib/retro.js";
 import { registerBackgroundRuntime } from "./lib/runtime.js";
+import { registerWikiSettingsCommand } from "./lib/settings-command.js";
 import {
   loadTaskConfig,
   noticesEnabled,
@@ -131,6 +133,8 @@ export default function (pi: ExtensionAPI) {
   // background task model. The taskModel config field + resolveModel already
   // exist; this exposes them to the user (default stays the session model).
   registerWikiModelCommand(pi, runtime);
+  registerWikiSettingsCommand(pi, runtime);
+  registerWikiDashboardCommand(pi, runtime);
   const reminderState = createReminderState();
   registerWikiObserve(pi, runtime, reminderState);
   // Visible observe/retro reminder by default (issue #77); silenced when the

package/extensions/llm-wiki/lib/dashboard-command.ts

@@ -0,0 +1,106 @@
+/**
+ * /wiki-dashboard command.
+ *
+ * Read-only mirror of /wiki-settings: one persistent screen, Esc closes.
+ * Unlike settings there is no per-key change — every line is computed once
+ * from on-disk vault state (see lib/dashboard.ts) and rendered as plain
+ * text through a Container + Text.
+ */
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { Container, Text, matchesKey } from "@mariozechner/pi-tui";
+import { type DashboardStats, collectDashboardStats } from "./dashboard.js";
+import type { Runtime } from "./runtime.js";
+
+type App = ExtensionAPI;
+
+const TYPE_ORDER = [
+  "concept",
+  "entity",
+  "source",
+  "skill",
+  "analysis",
+  "synthesis",
+  "requirement",
+  "short",
+  "shared",
+];
+const KIND_ORDER = ["observe", "retro", "synth", "intake"];
+
+function orderedPairs(counts: Record<string, number>): string {
+  const keys = Object.keys(counts);
+  const known = TYPE_ORDER.filter((k) => counts[k] !== undefined);
+  const rest = keys
+    .filter((k) => !TYPE_ORDER.includes(k))
+    .sort()
+    .slice(0, 3); // cap the tail: the dashboard is a glance, not a census
+  const all = [...known, ...rest];
+  if (all.length === 0) return "—";
+  return all.map((k) => `${k} ${counts[k]}`).join(" · ");
+}
+
+function orderedKinds(counts: Record<string, number>): string {
+  const keys = Object.keys(counts);
+  const known = KIND_ORDER.filter((k) => counts[k] !== undefined);
+  const rest = keys
+    .filter((k) => !KIND_ORDER.includes(k))
+    .sort()
+    .slice(0, 3);
+  return [...known, ...rest].map((k) => `${k} ${counts[k]}`).join(" · ");
+}
+
+function renderStatsLines(s: DashboardStats): string[] {
+  const emb = s.embEnabled ? `${s.embFiles}/${s.pageCount}` : "—";
+  return [
+    `Wiki Dashboard · ${s.root}`,
+    "",
+    `Pages   ${s.pageCount} · ${s.sizeKB}KB · ${orderedPairs(s.byType)}`,
+    `Fresh   last touch ${s.lastTouch || "never"} · stale(>30d) ${s.staleCount}`,
+    `Acts 7d ${s.last7dTotal > 0 ? orderedKinds(s.last7dByKind) : "none"} · total ${s.last7dTotal}/${s.totalEvents}`,
+    `Queue   raw ${s.rawQueue} · emb ${emb}`,
+    `Links   zero-backlink ${s.zeroBacklinks} · full scan: /wiki-lint`,
+    "",
+    "Esc to close",
+  ];
+}
+
+/** One-screen read-only TUI; handles Esc and `q`. */
+export class DashboardScreen extends Container {
+  private doneFn: (result?: unknown) => void;
+
+  constructor(lines: string[], close: (result?: unknown) => void) {
+    super();
+    this.doneFn = close;
+    this.addChild(new Text(lines.join("\n"), 1, 1));
+  }
+
+  handleInput(data: string): void {
+    // ponytail: matchesKey handles every terminal key shape (raw bytes,
+    // kitty CSI-u like \u001b[27u for Esc, ctrl combos) — a raw === "\u001b"
+    // check only works in terminals without the kitty keyboard protocol,
+    // which is exactly where Ghostty users' Esc went nowhere.
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+      this.doneFn();
+    }
+  }
+}
+
+/**
+ * Register the /wiki-dashboard command.
+ */
+export function registerWikiDashboardCommand(pi: ExtensionAPI, runtime: Runtime): void {
+  pi.registerCommand("wiki-dashboard", {
+    description:
+      "Show a read-only LLM Wiki dashboard (pages, freshness, activity, queue, links, emb)",
+    handler: async (_args: string, ctx: ExtensionCommandContext): Promise<void> => {
+      runtime.ensureConfig(ctx.cwd);
+      if (!ctx.hasUI) {
+        ctx.ui.notify("LLM Wiki: /wiki-dashboard requires an interactive UI.", "warning");
+        return;
+      }
+      const stats = await collectDashboardStats(ctx.cwd);
+      await ctx.ui.custom((_tui, _theme, _keybindings, close) => {
+        return new DashboardScreen(renderStatsLines(stats), close);
+      });
+    },
+  });
+}

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

@@ -0,0 +1,210 @@
+/**
+ * Read-only vault statistics for the /wiki-dashboard screen.
+ *
+ * Everything is computed from pre-existing on-disk state:
+ *  - page tree (paths.wiki + skills dir): counts, mtimes, sizes
+ *  - meta/registry.json: page types (values; keys can carry legacy prefix noise)
+ *  - meta/backlinks.json: zero-inbound pages
+ *  - meta/events.jsonl: activity stream (observes/retros/syntheses...)
+ *  - raw/sources: pending ingest queue
+ *  - emb/: embedding coverage
+ *
+ * No writes, no LLM calls, no new files. Pure reader.
+ */
+import { readFile, readdir, stat } from "node:fs/promises";
+import type { VaultPaths } from "./utils.js";
+import { readJson, resolveVaultPaths } from "./utils.js";
+
+interface PageInfo {
+  rel: string;
+  mtime: number;
+  bytes: number;
+}
+
+export interface DashboardStats {
+  /** Vault root directory, as shown in the header. */
+  root: string;
+  /** Total .md pages across wiki + skills dirs (filesystem truth). */
+  pageCount: number;
+  /** Page count by registry type; unknown types fall back to the folder name. */
+  byType: Record<string, number>;
+  /** Total page size in KB (rounded up to at least 1). */
+  sizeKB: number;
+  /** Human age of the most recent page touch: "now" | "Xm" | "Xh" | "Xd" | "". */
+  lastTouch: string;
+  /** Pages untouched for 30+ days. */
+  staleCount: number;
+  /** Event kinds (observe/retro/synth/intake/...) seen in the last 7 days. */
+  last7dByKind: Record<string, number>;
+  /** Total events in the last 7 days. */
+  last7dTotal: number;
+  /** Total parseable events recorded. */
+  totalEvents: number;
+  /** Number of raw source packets awaiting ingest (subdirs of raw/sources). */
+  rawQueue: number;
+  /** Pages with zero backlinks (from backlinks.json). */
+  zeroBacklinks: number;
+  /** .bin files in emb/ (meaningful when embeddings are enabled). */
+  embFiles: number;
+  /** Emb dir is populated — embeddings appear enabled. */
+  embEnabled: boolean;
+}
+
+/** Directories excluded from the page walk (infrastructure, not pages). */
+const SKIP_DIRS = new Set([
+  "templates",
+  "cases",
+  "outputs",
+  ".discoveries",
+  "raw",
+  "meta",
+  "emb",
+  ".git",
+]);
+
+async function walkPages(dir: string, rel: string, out: PageInfo[]): Promise<void> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const childRel = rel === "" ? e.name : `${rel}/${e.name}`;
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        await walkPages(`${dir}/${e.name}`, childRel, out);
+        continue;
+      }
+      if (!e.name.endsWith(".md")) continue;
+      try {
+        const st = await stat(`${dir}/${e.name}`);
+        out.push({ rel: childRel, mtime: st.mtimeMs, bytes: st.size });
+      } catch {
+        // unreadable file: skip
+      }
+    }
+  } catch {
+    // missing dir (empty vault): nothing to walk
+  }
+}
+
+function humanAge(ms: number): string {
+  const mins = Math.floor(ms / 60_000);
+  if (mins < 1) return "now";
+  if (mins < 60) return `${mins}m`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 48) return `${hrs}h`;
+  return `${Math.floor(hrs / 24)}d`;
+}
+
+async function readEvents(metaDir: string) {
+  const byKind: Record<string, number> = {};
+  let recent = 0;
+  let total = 0;
+  try {
+    const raw = await readFile(`${metaDir}/events.jsonl`, "utf-8");
+    const cutoff = Date.now() - 7 * 86400_000;
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      let ev: { timestamp?: unknown; kind?: unknown };
+      try {
+        ev = JSON.parse(line);
+      } catch {
+        continue; // corrupted line: skip, not fatal
+      }
+      const ts = typeof ev.timestamp === "string" ? Date.parse(ev.timestamp) : Number.NaN;
+      const kind = typeof ev.kind === "string" && ev.kind ? ev.kind : "event";
+      total += 1;
+      if (Number.isFinite(ts) && ts >= cutoff) {
+        byKind[kind] = (byKind[kind] ?? 0) + 1;
+        recent += 1;
+      }
+    }
+  } catch {
+    // no events file: zeros
+  }
+  return { byKind, recent, total };
+}
+
+/**
+ * Collect all dashboard stats for the vault reachable from `cwd`.
+ * Reuses the extension's own path resolution (same root the tools see).
+ */
+export async function collectDashboardStats(cwd: string): Promise<DashboardStats> {
+  const paths: VaultPaths = resolveVaultPaths(cwd);
+
+  const pages: PageInfo[] = [];
+  await walkPages(paths.wiki, "", pages);
+  // skill pages register as type:skill and live under <dotWiki>/skills
+  try {
+    const st = await stat(`${paths.dotWiki}/skills`);
+    if (st.isDirectory()) {
+      await walkPages(`${paths.dotWiki}/skills`, "skills", pages);
+    }
+  } catch {
+    // no skills dir: fine
+  }
+
+  // type map from registry values — keys may carry legacy noise, so normalize
+  const registry = readJson<{ pages?: Record<string, { type?: string }> }>(
+    `${paths.meta}/registry.json`,
+    { pages: {} },
+  );
+  const typeByKey: Record<string, string> = {};
+  for (const [key, val] of Object.entries(registry.pages ?? {})) {
+    const norm = key.startsWith('"') ? key.slice(1) : key;
+    if (val?.type) typeByKey[norm] = val.type;
+  }
+  const byType: Record<string, number> = {};
+  for (const p of pages) {
+    const slug = p.rel.endsWith(".md") ? p.rel.slice(0, -3) : p.rel;
+    const type = typeByKey[slug] ?? p.rel.split("/")[0] ?? "other";
+    byType[type] = (byType[type] ?? 0) + 1;
+  }
+
+  let sizeBytes = 0;
+  let latestMtime = 0;
+  const staleCutoff = Date.now() - 30 * 86400_000;
+  let stale = 0;
+  for (const p of pages) {
+    sizeBytes += p.bytes;
+    if (p.mtime > latestMtime) latestMtime = p.mtime;
+    if (p.mtime < staleCutoff) stale += 1;
+  }
+
+  const events = await readEvents(paths.meta);
+
+  let rawQueue = 0;
+  try {
+    const pkts = await readdir(paths.rawSources, { withFileTypes: true });
+    for (const e of pkts) {
+      if (e.isDirectory()) rawQueue += 1; // each subdirectory is one packet
+    }
+  } catch {
+    // no raw/sources: empty queue
+  }
+
+  const backlinks = readJson<Record<string, string[]>>(`${paths.meta}/backlinks.json`, {});
+  const zeroBacklinks = Object.values(backlinks).filter((v) => (v ?? []).length === 0).length;
+
+  let embFiles = 0;
+  try {
+    const embEntries = await readdir(`${paths.dotWiki}/emb`);
+    embFiles = embEntries.filter((f) => f.endsWith(".bin")).length;
+  } catch {
+    // no emb dir: none
+  }
+
+  return {
+    root: paths.root,
+    pageCount: pages.length,
+    byType,
+    sizeKB: Math.max(1, Math.round(sizeBytes / 1024)),
+    lastTouch: pages.length === 0 ? "" : humanAge(Date.now() - latestMtime),
+    staleCount: stale,
+    last7dByKind: events.byKind,
+    last7dTotal: events.recent,
+    totalEvents: events.total,
+    rawQueue,
+    zeroBacklinks,
+    embFiles,
+    embEnabled: embFiles > 0,
+  };
+}

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

@@ -79,12 +79,34 @@ function parseMoveDestination(line: string): string | undefined {
 function scanPatchString(input: string): MutationScan {
   const paths: string[] = [];
   let sawHeader = false;
+  let sawApplyPatchHeader = false;
+  let applyPatchComplete = true;
   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();
+    const raw = line.replace(/\r$/, "");
+    // apply_patch envelope headers (#162): matched on the raw (untrimmed)
+    // line so body rows (space/+/- prefixed) that quote the envelope shape
+    // are never mistaken for headers.
+    const fileOp = /^\*{3}\s+(?:update|add|delete)\s+file:\s*(\S.*)$/i.exec(raw);
+    if (fileOp) {
+      sawApplyPatchHeader = true;
+      const path = normalizeMutationPath(fileOp[1]);
+      if (path) paths.push(path);
+      else applyPatchComplete = false;
+      continue;
+    }
+    const moveTo = /^\*{3}\s+move\s+to:\s*(\S.*)$/i.exec(raw);
+    if (moveTo) {
+      sawApplyPatchHeader = true;
+      const destination = normalizeMutationPath(moveTo[1]);
+      if (destination) paths.push(destination);
+      else applyPatchComplete = false;
+      continue;
+    }
+    const trimmed = raw.trim();
     if (trimmed.startsWith("[")) {
       sawHeader = true;
       sectionHasMove = false;
@@ -102,6 +124,9 @@ function scanPatchString(input: string): MutationScan {
     }
   }
 
+  if (sawApplyPatchHeader) {
+    return { paths, complete: applyPatchComplete && paths.length > 0 };
+  }
   return { paths, complete: sawHeader && complete };
 }
 

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

@@ -63,7 +63,7 @@ export function detectHost(): HostKind {
     if (segments.includes(".pi")) return "pi";
   }
 
-  if (process.env.OMP_PROFILE !== undefined) return "omp";
+  if (process.env.OMP_PROFILE) return "omp";
   return "pi";
 }
 
@@ -123,3 +123,23 @@ export function resolveProjectSettingsPath(cwd: string, host: HostKind = detectH
 
   return join(native, "settings.json");
 }
+
+/**
+ * The global (user-level) settings file this extension writes to.
+ *
+ * Always writes to `settings.json` inside the agent dir — both hosts read it.
+ */
+export function resolveGlobalSettingsPath(host: HostKind = detectHost()): string {
+  let agentDir = "";
+  try {
+    agentDir = getAgentDir();
+  } catch {
+    agentDir = "";
+  }
+  if (!agentDir) {
+    // Fallback: ~/.pi/agent/settings.json
+    const home = process.env.HOME || "~";
+    return join(home, ".pi", "agent", "settings.json");
+  }
+  return join(agentDir, "settings.json");
+}

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

@@ -13,9 +13,15 @@ import {
   serializeKnowledgeDocument,
   writeKnowledgeDocumentFile,
 } from "./knowledge-document.js";
+import {
+  type WikilinkValidationMode,
+  auditWikilinks,
+  buildWikilinkIndex,
+} from "./knowledge-links.js";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
 import { runSubAgent } from "./subagent.js";
-import { type VaultPaths, fmtDate, slugify } from "./utils.js";
+import { resolveWikilinkValidation } from "./task-config.js";
+import { type VaultPaths, fmtDate, readJson, slugify } from "./utils.js";
 import { VaultWriteError, assertWritableVault } from "./vault-format.js";
 
 /**
@@ -84,6 +90,8 @@ export interface CommitResult {
   entitiesLinked: string[];
   conceptsLinked: string[];
   contradictions: number;
+  /** Wikilink gate diagnostics from `commitSynthesis` (warn/normalize modes). */
+  wikilinkDiagnostics?: KnowledgeDiagnostic[];
 }
 
 export type CommitSynthesisOutcome =
@@ -186,43 +194,23 @@ function getHeadings(lang?: string): Record<string, string> {
   };
 }
 
-function buildEntityPageBody(
-  title: string,
-  description: string,
-  sourceId: string,
-  lang?: string,
-): string {
+function buildEntityPageBody(title: string, description: string, sourceId: string): string {
   const desc = description.trim() || "One-line description.";
-  const h = getHeadings(lang);
   return `# ${title}
 
 ${desc}
 
-## ${h.overview}
-
-[Key facts]
-
 ## Links
 
 - [${sourceId}](/sources/${sourceId}.md)`;
 }
 
-function buildConceptPageBody(
-  title: string,
-  definition: string,
-  sourceId: string,
-  lang?: string,
-): string {
+function buildConceptPageBody(title: string, definition: string, sourceId: string): string {
   const def = definition.trim() || "One-line definition.";
-  const h = getHeadings(lang);
   return `# ${title}
 
 ${def}
 
-## ${h.definition}
-
-[Clear explanation]
-
 ## Links
 
 - [${sourceId}](/sources/${sourceId}.md)`;
@@ -321,6 +309,28 @@ export function buildIngestedSourcePage(
   return serializeKnowledgeDocument(doc);
 }
 
+/**
+ * Build the wikilink index used by the pre-write gate: every existing page id
+ * (from the registry) plus the page ids this commit is about to create, so a
+ * link to a sibling created in the same ingest resolves instead of
+ * false-positiving as missing.
+ */
+function buildIngestAuditIndex(
+  paths: VaultPaths,
+  sourceId: string,
+  data: SynthesisData,
+): ReturnType<typeof buildWikilinkIndex> {
+  const registry = readJson<{ pages: Record<string, unknown> }>(join(paths.meta, "registry.json"), {
+    pages: {},
+  });
+  const newIds = [
+    `sources/${sourceId}`,
+    ...data.entities.filter((e) => slugify(e.title)).map((e) => `entities/${slugify(e.title)}`),
+    ...data.concepts.filter((c) => slugify(c.title)).map((c) => `concepts/${slugify(c.title)}`),
+  ];
+  return buildWikilinkIndex([...Object.keys(registry.pages), ...newIds]);
+}
+
 /**
  * Persist a synthesis deterministically: rewrite the source page (status →
  * ingested), create missing entity/concept pages (existing pages are linked,
@@ -333,6 +343,7 @@ export function commitSynthesis(
   data: SynthesisData,
   date: string = fmtDate(),
   lang?: string,
+  wikilinkValidation?: WikilinkValidationMode,
 ): CommitSynthesisOutcome {
   const result: CommitResult = {
     sourceId,
@@ -353,6 +364,24 @@ export function commitSynthesis(
     throw error;
   }
 
+  // Pre-write wikilink gate (issue #172, Layer 2). Applies only to the
+  // model-authored source body; entity/concept pages are generated templates.
+  const mode = resolveWikilinkValidation({ wikilinkValidation });
+  let sourceBody = buildIngestedSourcePageBody(manifest, data, date, lang);
+  if (mode !== "off") {
+    const audit = auditWikilinks(
+      sourceBody,
+      buildIngestAuditIndex(paths, sourceId, data),
+      sourceId,
+      mode,
+    );
+    if (mode === "strict" && audit.diagnostics.length > 0) {
+      return { ok: false, sourceId, diagnostics: audit.diagnostics };
+    }
+    if (mode === "normalize") sourceBody = audit.body;
+    if (audit.diagnostics.length > 0) result.wikilinkDiagnostics = audit.diagnostics;
+  }
+
   // Patch existing documents so unknown fields, legacy sources, and titles survive.
   let sourceDocument: KnowledgeDocument;
   if (existsSync(result.sourcePage)) {
@@ -360,7 +389,7 @@ export function commitSynthesis(
     if (!parsed.ok) return { ok: false, sourceId, diagnostics: parsed.diagnostics };
     sourceDocument = patchKnowledgeDocument(parsed.document, {
       fields: { status: "ingested", updated: date },
-      body: buildIngestedSourcePageBody(manifest, data, date, lang),
+      body: sourceBody,
     });
   } else {
     sourceDocument = createKnowledgeDocument(
@@ -375,7 +404,7 @@ export function commitSynthesis(
         status: "ingested",
         updated: date,
       },
-      buildIngestedSourcePageBody(manifest, data, date, lang),
+      sourceBody,
     );
   }
   mkdirSync(join(paths.wiki, "sources"), { recursive: true });
@@ -399,7 +428,7 @@ export function commitSynthesis(
           created: date,
           updated: date,
         },
-        buildEntityPageBody(e.title, e.description, sourceId, lang),
+        buildEntityPageBody(e.title, e.description, sourceId),
         [{ id: sourceId, resource: `/sources/${sourceId}.md` }],
       );
       writeKnowledgeDocumentFile(pagePath, entityDoc);
@@ -425,7 +454,7 @@ export function commitSynthesis(
           created: date,
           updated: date,
         },
-        buildConceptPageBody(c.title, c.definition, sourceId, lang),
+        buildConceptPageBody(c.title, c.definition, sourceId),
         [{ id: sourceId, resource: `/sources/${sourceId}.md` }],
       );
       writeKnowledgeDocumentFile(pagePath, conceptDoc);
@@ -475,6 +504,10 @@ export interface RunIngestSynthesisArgs {
   signal?: AbortSignal;
   /** BCP 47 language tag for narrative content (issue #124). */
   synthesisLanguage?: string;
+  /** Max output tokens for synthesizer sub-agent (issue #160). Default 16384. */
+  synthesisMaxTokens?: number;
+  /** Wikilink write-gate mode for the ingested source body (issue #172). */
+  wikilinkValidation?: WikilinkValidationMode;
 }
 
 /**
@@ -496,6 +529,8 @@ export async function runIngestSynthesis(
     maxChars,
     signal,
     synthesisLanguage,
+    synthesisMaxTokens,
+    wikilinkValidation,
   } = args;
   const content = extracted.slice(0, maxChars ?? 24_000);
   if (!content.trim()) return undefined;
@@ -521,6 +556,7 @@ export async function runIngestSynthesis(
         params,
         undefined,
         synthesisLanguage,
+        wikilinkValidation,
       );
       if (!outcome.ok) {
         return {
@@ -549,6 +585,7 @@ export async function runIngestSynthesis(
     systemPrompt,
     userPrompt,
     tools: [commitTool as AgentTool],
+    maxTokens: synthesisMaxTokens ?? 16384,
     signal,
   });
 

package/extensions/llm-wiki/lib/knowledge-document.ts

@@ -21,6 +21,7 @@ export type DiagnosticCode =
   | "okf_version_mismatch"
   | "link_path_escape"
   | "link_unresolved"
+  | "link_ambiguous"
   | "event_source_missing"
   | "event_source_unreadable"
   | "event_invalid_json"
@@ -588,6 +589,22 @@ export function serializeKnowledgeDocument(document: KnowledgeDocument): string
   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: string): string {
+  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<T extends KnowledgeCreationFields>(
   path: string,
   fields: T & NoInfer<KnowledgeCreationFields>,
@@ -614,7 +631,7 @@ export function createKnowledgeDocument<T extends KnowledgeCreationFields>(
     ? { kind: "canonical" as const, value: sources }
     : { kind: "absent" as const };
 
-  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$/, ""),
@@ -643,7 +660,9 @@ export function patchKnowledgeDocument(
     }
   }
 
-  const newBody = patch.body ?? document.body;
+  const newBody = patch.body
+    ? escapeWikilinkAliasPipes(patch.body.replace(/\r\n?/g, "\n"))
+    : document.body;
 
   return {
     ...document,