@zosmaai/pi-llm-wiki 0.11.4 → 0.11.6

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

@@ -11,12 +11,16 @@ import {
   serializeKnowledgeDocument,
   writeKnowledgeDocumentFile,
 } from "./knowledge-document.js";
-import { buildResolvedBacklinks } from "./knowledge-links.js";
+import {
+  applyWikilinkGate,
+  buildResolvedBacklinks,
+  buildWikilinkIndex,
+} from "./knowledge-links.js";
 import { repairLegacyKnowledgeDocuments } from "./legacy-repair.js";
 import { type Registry, appendEvent, rebuildMetadata, rebuildMetadataLight } from "./metadata.js";
 import type { Runtime } from "./runtime.js";
 import { captureFile, captureText, captureUrl } from "./source-packet.js";
-import { parseModelRef } from "./task-config.js";
+import { loadTaskConfig, parseModelRef, resolveWikilinkValidation } from "./task-config.js";
 import {
   type VaultPaths,
   detectVaultFormat,
@@ -415,6 +419,7 @@ export function registerWikiIngest(pi: ExtensionAPI, runtime?: Runtime): void {
                 manifest: s.manifest,
                 extracted: s.extracted,
                 synthesisLanguage: runtime.config.synthesisLanguage,
+                wikilinkValidation: runtime.config.wikilinkValidation,
               });
               if (committed) {
                 // Background semantic embeddings (#66): embed the pages this
@@ -428,8 +433,10 @@ export function registerWikiIngest(pi: ExtensionAPI, runtime?: Runtime): void {
                 ];
                 launchEmbedPages(runtime, launchCtx, paths, pageIds, `embed:ingest:${s.id}`);
               }
+              const wl = committed?.wikilinkDiagnostics?.length ?? 0;
+              const wlNote = wl > 0 ? `, ${wl} wikilink issue${wl === 1 ? "" : "s"}` : "";
               const summary = committed
-                ? `LLM Wiki: ingested ${s.id} → ${committed.entitiesCreated.length} entit${committed.entitiesCreated.length === 1 ? "y" : "ies"}, ${committed.conceptsCreated.length} concept${committed.conceptsCreated.length === 1 ? "" : "s"}`
+                ? `LLM Wiki: ingested ${s.id} → ${committed.entitiesCreated.length} entit${committed.entitiesCreated.length === 1 ? "y" : "ies"}, ${committed.conceptsCreated.length} concept${committed.conceptsCreated.length === 1 ? "" : "s"}${wlNote}`
                 : `LLM Wiki: ${s.id} produced no synthesis`;
               if (ctx.hasUI) {
                 ctx.ui.notify(summary, committed ? "info" : "warning");
@@ -565,7 +572,42 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
       }
 
       const today = fmtDate();
-      const body = params.content ?? buildPageBody(type, params.title);
+      let body = params.content ?? buildPageBody(type, params.title);
+
+      // Pre-write wikilink gate (#172): validate/normalize caller-supplied content.
+      const mode = resolveWikilinkValidation(loadTaskConfig(ctx.cwd));
+      let wikilinkIssues: string[] = [];
+      if (mode !== "off") {
+        const registry = readJson<{ pages: Record<string, unknown> }>(
+          join(paths.meta, "registry.json"),
+          { pages: {} },
+        );
+        const gate = applyWikilinkGate(
+          body,
+          buildWikilinkIndex(Object.keys(registry.pages)),
+          `${folder}/${slug}`,
+          mode,
+        );
+        wikilinkIssues = gate.diagnostics.map((d) => d.message);
+        if (!gate.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Rejected write — unresolved/ambiguous wikilinks:\n${wikilinkIssues
+                  .map((m) => `- ${m}`)
+                  .join("\n")}`,
+              },
+            ],
+            details: { error: "link_validation", issues: wikilinkIssues } as Record<
+              string,
+              unknown
+            >,
+            isError: true,
+          };
+        }
+        if (mode === "normalize") body = gate.body;
+      }
       const doc = createKnowledgeDocument(
         `${folder}/${slug}.md`,
         {
@@ -595,9 +637,16 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
         rebuildMetadataLight(paths);
       }
 
+      const gateNote = wikilinkIssues.length
+        ? `\n\n⚠️ ${wikilinkIssues.length} wikilink issue(s):\n${wikilinkIssues.map((m) => `- ${m}`).join("\n")}`
+        : "";
       return {
-        content: [{ type: "text", text: `✅ Created ${type} page: \`${pagePath}\`` }],
-        details: { path: pagePath, created: true } as Record<string, unknown>,
+        content: [{ type: "text", text: `✅ Created ${type} page: \`${pagePath}\`${gateNote}` }],
+        details: {
+          path: pagePath,
+          created: true,
+          wikilinkIssues,
+        } as Record<string, unknown>,
       };
     },
   });
@@ -871,7 +920,7 @@ function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
 
   const discovery = discoverKnowledgeDocuments(paths);
   const pages = discovery.documents;
-  const knownIds = new Set(pages.map((page) => page.id));
+  const wikilinkIndex = buildWikilinkIndex(pages.map((page) => page.id));
   const inbound = Object.fromEntries(pages.map((page) => [page.id, 0]));
   const gapSources = new Map<string, Set<string>>();
   const findings: string[] = [];
@@ -879,7 +928,7 @@ function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
   let contradictions = 0;
 
   for (const page of pages) {
-    const resolved = buildResolvedBacklinks(page.id, page.body, knownIds);
+    const resolved = buildResolvedBacklinks(page.id, page.body, wikilinkIndex);
     for (const target of resolved.targets) inbound[target]++;
     for (const unresolved of resolved.unresolved) {
       const sources = gapSources.get(unresolved.target) ?? new Set<string>();
@@ -888,6 +937,11 @@ function runWikiLint(paths: VaultPaths, autoFix: boolean): string {
       missingPages++;
       findings.push(`Missing page: ${unresolved.target} (in ${page.id})`);
     }
+    for (const d of resolved.diagnostics) {
+      if (d.code === "link_ambiguous") {
+        findings.push(d.message.replace("Ambiguous wikilink: ", "Ambiguous: "));
+      }
+    }
   }
 
   let orphans = 0;

package/mcp/index.ts

@@ -15,6 +15,10 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
+import {
+  loadTaskConfig,
+  resolveWikilinkValidation,
+} from "../extensions/llm-wiki/lib/task-config.js";
 import { getVaultPaths, resolveVaultPaths } from "../extensions/llm-wiki/lib/utils.js";
 import { createExecApi } from "./exec.js";
 import {
@@ -265,7 +269,14 @@ server.registerTool(
     }
 
     const paths = getPaths();
-    const result = await retroOperation(paths, slug, title, body, category);
+    const result = await retroOperation(
+      paths,
+      slug,
+      title,
+      body,
+      category,
+      resolveWikilinkValidation(loadTaskConfig(process.cwd())),
+    );
 
     if (!result.ok) {
       return {

package/mcp/operations.ts

@@ -6,13 +6,20 @@
  * registry entries, or builds page strings itself.
  */
 
+import { join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { bootstrapVault } from "../extensions/llm-wiki/lib/bootstrap.js";
+import {
+  type WikilinkValidationMode,
+  applyWikilinkGate,
+  buildWikilinkIndex,
+} from "../extensions/llm-wiki/lib/knowledge-links.js";
 import { type ProjectionResult, rebuildMetadata } from "../extensions/llm-wiki/lib/metadata.js";
 import { type RecallResult, searchWikiLayered } from "../extensions/llm-wiki/lib/recall.js";
 import { saveInsight } from "../extensions/llm-wiki/lib/retro.js";
 import { captureFile, captureText, captureUrl } from "../extensions/llm-wiki/lib/source-packet.js";
-import type { VaultPaths } from "../extensions/llm-wiki/lib/utils.js";
+import { resolveWikilinkValidation } from "../extensions/llm-wiki/lib/task-config.js";
+import { type VaultPaths, readJson } from "../extensions/llm-wiki/lib/utils.js";
 import {
   VaultWriteError,
   inspectVaultFormat,
@@ -134,6 +141,7 @@ export async function retroOperation(
   title: string,
   body: string,
   category?: string,
+  wikilinkValidation?: WikilinkValidationMode,
 ): Promise<
   | { ok: true; slug: string; sourcePagePath: string }
   | { ok: false; diagnostics: Array<{ code: string; message: string }> }
@@ -145,8 +153,30 @@ export async function retroOperation(
       diagnostics: vaultCheck.diagnostics.map((d) => ({ code: d.code, message: d.message })),
     };
   }
+  // Pre-write wikilink gate (#172): validate/normalize caller-supplied body.
+  const mode = resolveWikilinkValidation({ wikilinkValidation });
+  let gateBody = body;
+  if (mode !== "off") {
+    const registry = readJson<{ pages: Record<string, unknown> }>(
+      join(paths.meta, "registry.json"),
+      { pages: {} },
+    );
+    const gate = applyWikilinkGate(
+      body,
+      buildWikilinkIndex(Object.keys(registry.pages)),
+      `sources/${slug}`,
+      mode,
+    );
+    if (!gate.ok) {
+      return {
+        ok: false,
+        diagnostics: gate.diagnostics.map((d) => ({ code: "link_validation", message: d.message })),
+      };
+    }
+    if (mode === "normalize") gateBody = gate.body;
+  }
   try {
-    const result = saveInsight(paths, slug, title, body, category, { rebuild: false });
+    const result = saveInsight(paths, slug, title, gateBody, category, { rebuild: false });
     const projection = projectionOutcome(rebuildMetadata(paths));
     if (!projection.ok) return projection;
     return { ok: true, slug: result.slug, sourcePagePath: result.sourcePagePath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Self-maintaining LLM Wiki for Pi — Karpathy-pattern knowledge base with immutable source capture, automated ingestion, search, linting, and Obsidian-compatible vault. auto-updating personal & company wiki.",
   "keywords": [
     "pi",
@@ -75,17 +75,18 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "typebox": "*"
+    "@mariozechner/pi-coding-agent": "*"
   },
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
+    "@mariozechner/pi-tui": "0.70.6",
     "@modelcontextprotocol/server": "^2.0.0",
     "mdast-util-from-markdown": "^2.0.3",
     "node-html-markdown": "^2.0.0",
+    "typebox": "^1.1.34",
     "yaml": "^2.9.0",
     "zod": "^4.0"
   },
@@ -98,7 +99,6 @@
     "@types/mdast": "^4.0.4",
     "@types/node": "^22",
     "@vitest/coverage-v8": "^3.2.4",
-    "typebox": "^1.1.34",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },

package/prompts/wiki-ingest.md

@@ -33,4 +33,5 @@ $ARGUMENTS
 **Rules:**
 - Never modify files in `raw/` — source packets are immutable after capture.
 - Never fabricate information — always cite sources with `[[sources/SRC-...]]`.
+- Inside Markdown table cells, write aliased wikilinks as `[[target\|alias]]`, never `[[target|alias]]`.
 - The extension auto-updates metadata — you do NOT need to manually edit `meta/` files.

package/prompts/wiki-req.md

@@ -53,3 +53,4 @@ Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand th
 - Use status values: `draft` → `clarified` → `active` → `implemented` → `deferred` → `rejected`
 - Use priority values: `p0` (blocking), `p1` (critical), `p2` (important), `p3` (nice-to-have)
 - Do not create requirements in `raw/` — that layer is for external source artifacts only
+- Inside Markdown table cells, write aliased wikilinks as `[[target\|alias]]`, never `[[target|alias]]`.

package/prompts/wiki-retro.md

@@ -32,3 +32,4 @@ Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand th
 - One atomic insight per `wiki_retro` call. Use multiple calls for multiple insights.
 - Don't save obvious things. Save non-obvious patterns, tradeoffs, and design decisions.
 - Always add `[[wikilinks]]` to connect the new insight with existing wiki knowledge.
+- Inside Markdown table cells, write aliased wikilinks as `[[target\|alias]]`, never `[[target|alias]]`.

package/skills/llm-wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: llm-wiki
-description: Build and maintain a persistent, interlinked Obsidian-compatible markdown wiki using Karpathy's LLM Wiki pattern. Extension-backed with auto-generated metadata, guardrails, and 13 custom tools (+3 opt-in agent-trajectory tools).
+description: Build and maintain a persistent, interlinked Obsidian-compatible markdown wiki using Karpathy's LLM Wiki pattern. Extension-backed with auto-generated metadata, guardrails, and 14 custom tools (+3 opt-in agent-trajectory tools).
 whenToUse: Call wiki_recall at task start to find relevant wiki pages. Call wiki_retro at task end to save new insights. When agent-trajectory working-memory is enabled (opt-in, /wiki-trajectories on), also call wiki_recall_skill at task start to find reusable skills / past cases ("have I done this before?") and wiki_capture_trajectory after non-trivial tasks to record how you solved them. The extension injects a brief status line, but explicit calls with task-specific terms get better results.
 ---
 
@@ -178,6 +178,16 @@ The choice is persisted to project settings (`.pi/settings.json` under `llm-wiki
 wiki_ingest(model="anthropic/claude-haiku")
 ```
 
+### Settings Screen (`/wiki-settings`)
+
+**Interactive settings:** run `/wiki-settings` to open a persistent settings screen. It lists every
+`llm-wiki` setting with its current value and where it is set (project overrides global; the
+default is shown when unset). Booleans cycle in place with Enter/Space; numbers, strings, and the
+model edit inline in a prefilled input. Every change persists immediately to the chosen scope
+(project or global). Setting the model to `session` clears `llm-wiki.taskModel` (back to the session model).
+
+### Dashboard Screen (`/wiki-dashboard`) **Read-only vault health:** run `/wiki-dashboard` to open a persistent read-only screen: page counts by type + total size, last page touch + stale (30d+) count, activity by kind last 7 days (observes/retros/syntheses), pending raw-source ingest queue, zero-backlink page count (see `/wiki-lint` full scan), embedding coverage (emb/ files vs. pages). All values computed from existing on-disk state — no writes, no LLM calls. Esc closes.
+
 ### Auto-Bootstrap (One-Time)
 
 The extension creates the wiki vault automatically on startup. On the first turn, it injects a directive asking you to infer topic and mode, then call: