@zosmaai/pi-llm-wiki 0.11.5 → 0.11.7

package/extensions/llm-wiki/lib/task-config.ts

@@ -9,6 +9,7 @@ import {
   resolveGlobalSettingsPath,
   resolveProjectSettingsPath,
 } from "./host.js";
+import type { WikilinkValidationMode } from "./knowledge-links.js";
 
 /**
  * Configuration for the background-task lane (issue #64, part of #63).
@@ -147,6 +148,27 @@ export interface TaskConfig {
    * response truncates before commit_synthesis can be called.
    */
   synthesisMaxTokens?: number;
+
+  /**
+   * Wikilink gate applied to the ingested source body before pages are
+   * written (issue #172, Layer 2). Reuses the Layer 1 resolver.
+   *   - "off"       : no-op.
+   *   - "warn"      : write proceeds; unresolved/ambiguous links are reported.
+   *   - "strict"    : block the write (commit returns ok:false) if any link is unresolvable.
+   *   - "normalize" : rewrite resolvable links to their canonical id, then write.
+   * Default "warn". See `resolveWikilinkValidation`.
+   */
+  wikilinkValidation?: WikilinkValidationMode;
+
+  /**
+   * User-defined page types for wiki_ensure_page (issue #169). Merges with
+   * the 7 built-in types (entity, concept, synthesis, analysis, requirement,
+   * skill, case). Each key is the type name; each value is the folder name
+   * inside wiki/. Example: { "decision": "decisions", "metric": "metrics" }
+   * → wiki_ensure_page(type="decision") creates wiki/decisions/<slug>.md.
+   * Custom types use a generic page template (no per-type templates).
+   */
+  customTypes?: Record<string, string>;
 }
 
 export const TASK_DEFAULTS: TaskConfig = {};
@@ -159,6 +181,24 @@ export function noticesEnabled(config: TaskConfig | undefined): boolean {
   return config?.notices !== false;
 }
 
+const WIKILINK_VALIDATION_MODES: readonly WikilinkValidationMode[] = [
+  "off",
+  "warn",
+  "strict",
+  "normalize",
+];
+
+/**
+ * Resolve the wikilink write-gate mode (issue #172, Layer 2). Defaults to
+ * `warn` — ingest always writes and reports; only an explicit `strict` blocks.
+ * Unknown values fall back to `warn` rather than failing the ingest.
+ */
+export function resolveWikilinkValidation(config: TaskConfig | undefined): WikilinkValidationMode {
+  const v = config?.wikilinkValidation;
+  if (v && (WIKILINK_VALIDATION_MODES as readonly string[]).includes(v)) return v;
+  return "warn";
+}
+
 /**
  * Resolve whether the personal vault may serve as this project's ambient
  * vault. Explicit `ambientPersonalVault` wins; otherwise the host decides
@@ -251,6 +291,23 @@ function readNamespacedConfig(path: string): Partial<TaskConfig> {
       out.synthesisMaxTokens = Math.floor(maxTokens);
     }
 
+    const wl = section.wikilinkValidation;
+    if (typeof wl === "string" && (WIKILINK_VALIDATION_MODES as readonly string[]).includes(wl)) {
+      out.wikilinkValidation = wl as WikilinkValidationMode;
+    }
+
+    const ct = section.customTypes;
+    if (ct && typeof ct === "object" && !Array.isArray(ct)) {
+      const entries = Object.entries(ct as Record<string, unknown>);
+      const valid: Record<string, string> = {};
+      for (const [k, v] of entries) {
+        if (typeof k === "string" && typeof v === "string" && k && v) {
+          valid[k] = v;
+        }
+      }
+      if (Object.keys(valid).length) out.customTypes = valid;
+    }
+
     return out;
   } catch {
     return {};
@@ -438,6 +495,8 @@ const KNOWN_KEYS = [
   "trajectories",
   "synthesisLanguage",
   "synthesisMaxTokens",
+  "wikilinkValidation",
+  "customTypes",
 ] as const;
 
 export function loadTaskConfigSources(

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");
@@ -512,7 +519,7 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
     parameters: Type.Object({
       type: Type.String({
         description:
-          "Page type: entity | concept | synthesis | analysis | requirement | skill | case",
+          "Page type: entity | concept | synthesis | analysis | requirement | skill | case (built-in) or any user-defined type from llm-wiki.customTypes config",
       }),
       title: Type.String({ description: "Page title" }),
       content: Type.Optional(
@@ -535,17 +542,8 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
         };
       }
 
-      const type = params.type as
-        | "entity"
-        | "concept"
-        | "synthesis"
-        | "analysis"
-        | "requirement"
-        | "skill"
-        | "case";
-      const slug = slugify(params.title);
-
-      const folderMap: Record<string, string> = {
+      const config = loadTaskConfig(ctx.cwd);
+      const builtInFolderMap: Record<string, string> = {
         entity: "entities",
         concept: "concepts",
         synthesis: "syntheses",
@@ -554,6 +552,9 @@ export function registerWikiEnsurePage(pi: ExtensionAPI, runtime?: Runtime): voi
         skill: "skills",
         case: "cases",
       };
+      const folderMap = { ...builtInFolderMap, ...config.customTypes };
+      const type = params.type as string;
+      const slug = slugify(params.title);
       const folder = folderMap[type] || "concepts";
       const pagePath = join(paths.wiki, folder, `${slug}.md`);
 
@@ -565,7 +566,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 +631,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 +914,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 +922,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 +931,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.5",
+  "version": "0.11.7",
   "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",
@@ -91,6 +91,7 @@
     "zod": "^4.0"
   },
   "devDependencies": {
+    "@astrojs/starlight": "^0.41.10",
     "@biomejs/biome": "^1.9.4",
     "@mariozechner/pi-agent-core": "^0.70.2",
     "@mariozechner/pi-ai": "^0.70.2",
@@ -99,6 +100,7 @@
     "@types/mdast": "^4.0.4",
     "@types/node": "^22",
     "@vitest/coverage-v8": "^3.2.4",
+    "astro": "^7.2.9",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
@@ -110,10 +112,13 @@
     "build:mcp": "node scripts/build-mcp.js",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
-    "lint:fix": "biome check --apply .",
+    "lint:fix": "biome check --write .",
     "release:patch": "node scripts/release.js patch",
     "release:minor": "node scripts/release.js minor",
     "release:major": "node scripts/release.js major",
-    "release:push": "git push origin main --tags"
+    "release:push": "git push origin main --tags",
+    "docs:sync": "node scripts/sync-docs.js",
+    "docs:dev": "astro dev",
+    "docs:build": "node scripts/sync-docs.js && astro build"
   }
 }