@zosmaai/pi-llm-wiki 0.11.3 → 0.11.5

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,7 +21,13 @@ import {
 } from "./lib/recall.js";
 import { registerWikiRetro } from "./lib/retro.js";
 import { registerBackgroundRuntime } from "./lib/runtime.js";
-import { loadTaskConfig, noticesEnabled, trajectoriesEnabled } from "./lib/task-config.js";
+import { registerWikiSettingsCommand } from "./lib/settings-command.js";
+import {
+  loadTaskConfig,
+  noticesEnabled,
+  personalVaultIsAmbient,
+  trajectoriesEnabled,
+} from "./lib/task-config.js";
 import {
   registerWikiBootstrap,
   registerWikiCaptureSource,
@@ -40,7 +47,11 @@ import {
   registerWikiDistillSkills,
   registerWikiRecallSkill,
 } from "./lib/trajectory.js";
-import { migrateDoubledPersonalVault, resolveVaultPaths } from "./lib/utils.js";
+import {
+  migrateDoubledPersonalVault,
+  resolveProjectVaultRoot,
+  resolveVaultPaths,
+} from "./lib/utils.js";
 import { inspectWritableVault } from "./lib/vault-format.js";
 import { applySessionStartStatus } from "./lib/visible-status.js";
 
@@ -68,6 +79,26 @@ export default function (pi: ExtensionAPI) {
   // work. Created first so tools (e.g. wiki_ingest) can dispatch to it.
   const runtime = registerBackgroundRuntime(pi);
 
+  /**
+   * Does a wiki apply to the directory this session is working in?
+   *
+   * Gates every AMBIENT surface — the ones that speak without being asked:
+   * session bootstrap/notice, the periodic observe/retro reminder, and
+   * `before_agent_start` recall injection. Tools and commands are registered
+   * regardless, so `/wiki-init` remains the way in.
+   *
+   * `resolveVaultRoot` falls back to the personal vault when a project has
+   * none, which is why the ambient surfaces used to fire in EVERY directory
+   * once a personal vault existed — reminders and unrelated cross-project
+   * recall hits leaking into repositories that never initialized a wiki.
+   * Under omp that fallback is off by default (`llm-wiki.ambientPersonalVault`);
+   * under pi it stays on, preserving the historical behavior.
+   *
+   * Resolved per call, not once at load: `cwd` changes within a session.
+   */
+  const wikiAppliesTo = (cwd: string): boolean =>
+    resolveProjectVaultRoot(cwd) !== null || personalVaultIsAmbient(runtime.config);
+
   registerWikiBootstrap(pi);
   registerWikiCaptureSource(pi, runtime);
   registerWikiIngest(pi, runtime);
@@ -102,13 +133,17 @@ 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
   // user sets `llm-wiki.notices: false`. Resolver reads the live config so the
-  // setting takes effect without a restart.
+  // setting takes effect without a restart. `display: false` still injects the
+  // reminder into model context, so the "no wiki here" case needs its own gate.
   registerObservationReminder(pi, reminderState, {
     display: () => noticesEnabled(runtime.config),
+    enabled: () => wikiAppliesTo(process.cwd()),
   });
 
   installGuardrails(pi, runtime);
@@ -137,6 +172,12 @@ export default function (pi: ExtensionAPI) {
       console.warn(`[llm-wiki] doubled-dotdir migration skipped: ${(err as Error).message}`);
     }
 
+    // Ambient gate. `ensureConfig` first so an explicit
+    // `llm-wiki.ambientPersonalVault` is honored on the very first session —
+    // `runtime.config` is otherwise empty until the first `turn_start`.
+    runtime.ensureConfig(process.cwd());
+    if (!wikiAppliesTo(process.cwd())) return;
+
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
       // Silently create the wiki vault — no UI prompts. Topic/mode will be
@@ -168,9 +209,8 @@ export default function (pi: ExtensionAPI) {
 
     // Surface the "wiki active" badge and the active background task model
     // (issue #69), both gated by `llm-wiki.notices` (issue #77, regression
-    // fixed in #83, helper extracted in #84). `ensureConfig` MUST run first so
-    // the gate sees the loaded project settings.
-    runtime.ensureConfig(process.cwd());
+    // fixed in #83, helper extracted in #84). The `ensureConfig` above the
+    // ambient gate already loaded the project settings this reads.
     applySessionStartStatus({
       ui: ctx.ui,
       runtime,
@@ -196,6 +236,8 @@ export default function (pi: ExtensionAPI) {
   //    from the user's first prompt and update config via wiki_bootstrap.
   // 2. Search both personal + project vaults for relevant pages.
   pi.on("before_agent_start", async (event, ctx) => {
+    if (!wikiAppliesTo(process.cwd())) return;
+
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
       return;

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

@@ -0,0 +1,145 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Host adapter for the two coding agents that can load this extension:
+ *
+ *  - **pi**   — `@mariozechner/pi-coding-agent`, config dir `.pi`
+ *  - **omp**  — oh-my-pi (`@oh-my-pi/pi-coding-agent`), config dir `.omp`
+ *
+ * omp rewrites `@mariozechner/pi-*` (and bare `typebox`) imports onto its own
+ * bundled packages at load time (its `legacy-pi-compat.ts`), so the *module
+ * graph* needs no changes. What does differ is the on-disk config layout:
+ *
+ * | | pi | omp |
+ * |---|---|---|
+ * | user dir      | `~/.pi/agent`   | `~/.omp/agent` |
+ * | project dir   | `<cwd>/.pi`     | `<cwd>/.omp`   |
+ * | settings file | `settings.json` | `settings.json`, then `config.yml` |
+ *
+ * omp explicitly does **not** read `.pi` (its config source order is
+ * `.omp` → `.claude` → `.codex` → `.gemini`), so a wiki configured under pi
+ * would silently lose its settings after switching hosts. This module keeps
+ * both layouts readable and picks a sensible file to write to.
+ *
+ * Everything here is additive: on pi with only a `.pi/` directory the effective
+ * behaviour is identical to the pre-compat code path, which keeps upstream
+ * merges clean.
+ */
+
+export type HostKind = "pi" | "omp";
+
+/** Project config directory name per host. */
+const CONFIG_DIR: Record<HostKind, string> = { pi: ".pi", omp: ".omp" };
+
+/** Settings file names inside a config directory, lowest → highest precedence. */
+const SETTINGS_FILES = ["settings.json", "config.yml", "config.yaml"] as const;
+
+/**
+ * Detect which agent is hosting this extension.
+ *
+ * Ordered by reliability:
+ *  1. `LLM_WIKI_HOST` — explicit escape hatch (tests, exotic embeddings).
+ *  2. The agent directory path: pi resolves `~/.pi/agent`, omp `~/.omp/agent`.
+ *     A `PI_CODING_AGENT_DIR` override that keeps the marker segment still
+ *     classifies correctly; anything else falls through.
+ *  3. `OMP_PROFILE`, which omp sets on itself whenever a profile is active.
+ *  4. Default `pi` — the historical behaviour.
+ */
+export function detectHost(): HostKind {
+  const forced = process.env.LLM_WIKI_HOST?.trim().toLowerCase();
+  if (forced === "omp" || forced === "pi") return forced;
+
+  let agentDir = "";
+  try {
+    agentDir = getAgentDir();
+  } catch {
+    agentDir = "";
+  }
+  if (agentDir) {
+    const segments = agentDir.split(/[\\/]/);
+    if (segments.includes(".omp")) return "omp";
+    if (segments.includes(".pi")) return "pi";
+  }
+
+  if (process.env.OMP_PROFILE) return "omp";
+  return "pi";
+}
+
+/**
+ * Every project settings file that may hold `llm-wiki` configuration, ordered
+ * from lowest to highest precedence so callers can merge left-to-right.
+ *
+ * The host's *native* directory is last (wins). The foreign directory is still
+ * read so a vault configured under pi keeps working after omp takes over the
+ * repository, and vice versa. Within a directory `config.yml` follows
+ * `settings.json`, matching omp's own project-settings precedence.
+ */
+export function listProjectSettingsFiles(cwd: string, host: HostKind = detectHost()): string[] {
+  const foreign: HostKind = host === "omp" ? "pi" : "omp";
+  const files: string[] = [];
+  for (const kind of [foreign, host]) {
+    const dir = join(cwd, CONFIG_DIR[kind]);
+    for (const name of SETTINGS_FILES) files.push(join(dir, name));
+  }
+  return files;
+}
+
+/**
+ * User-level settings files, lowest → highest precedence.
+ *
+ * `getAgentDir()` already resolves per host (`~/.pi/agent` vs `~/.omp/agent`),
+ * so only the file names differ: omp migrates `settings.json` into `config.yml`
+ * on first start, and a migrated install has *only* the YAML file.
+ */
+export function listGlobalSettingsFiles(): string[] {
+  let agentDir = "";
+  try {
+    agentDir = getAgentDir();
+  } catch {
+    return [];
+  }
+  if (!agentDir) return [];
+  return SETTINGS_FILES.map((name) => join(agentDir, name));
+}
+
+/**
+ * The project settings file this extension writes to.
+ *
+ * Always JSON (`settings.json`) — both hosts read it, and rewriting a user's
+ * hand-authored `config.yml` would destroy comments and formatting.
+ *
+ * Directory choice: an already-existing project config directory wins (so a
+ * repo that only has `.pi/` keeps a single settings file), otherwise the
+ * detected host's native directory is created.
+ */
+export function resolveProjectSettingsPath(cwd: string, host: HostKind = detectHost()): string {
+  const native = join(cwd, CONFIG_DIR[host]);
+  if (existsSync(native)) return join(native, "settings.json");
+
+  const foreign = join(cwd, CONFIG_DIR[host === "omp" ? "pi" : "omp"]);
+  if (existsSync(foreign)) return join(foreign, "settings.json");
+
+  return join(native, "settings.json");
+}
+
+/**
+ * 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

@@ -475,6 +475,8 @@ 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;
 }
 
 /**
@@ -496,6 +498,7 @@ export async function runIngestSynthesis(
     maxChars,
     signal,
     synthesisLanguage,
+    synthesisMaxTokens,
   } = args;
   const content = extracted.slice(0, maxChars ?? 24_000);
   if (!content.trim()) return undefined;
@@ -549,6 +552,7 @@ export async function runIngestSynthesis(
     systemPrompt,
     userPrompt,
     tools: [commitTool as AgentTool],
+    maxTokens: synthesisMaxTokens ?? 16384,
     signal,
   });
 

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

@@ -588,6 +588,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 +630,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 +659,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,