@zosmaai/pi-llm-wiki 0.7.0 → 0.7.2

package/README.md

@@ -49,15 +49,16 @@ The result is a wiki that **compounds** as you capture sources, ask questions, a
 
 | Capability | Description |
 |------------|-------------|
+| 🏠 **Personal fallback** | Always-on `~/.llm-wiki/` vault — knowledge compounds across projects even when no project wiki exists |
 | 🔗 **Immutable source capture** | URLs, local files (PDF/md/txt/html/XML/JSON), or pasted text → structured source packets |
 | 🧠 **Automated ingestion** | `wiki_ingest` batch-processes sources into concept, entity, synthesis & analysis pages |
 | 🔍 **Full-text search** | Generated registry with keyword lookup across all pages and sources |
 | 🩺 **Mechanical linting** | Orphans, broken links, duplicate aliases, coverage gaps, stale captures |
 | 📊 **Dashboard** | `wiki_status` — counts, source states, recent activity |
 | 🤖 **Auto-update watch** | `wiki_watch` — schedule periodic discovery + ingest |
-| 🧠 **Auto-recall** | Wiki searched automatically before every turn — relevant pages injected into context |
+| 🧠 **Layered recall** | Searches both personal (`~/.llm-wiki/`) and project (`.llm-wiki/`) vaults — personal knowledge follows you everywhere |
 | 📝 **Auto-bootstrap** | Extension suggests creating a wiki when none exists in the current directory |
-| 💾 **Auto-capture** | `wiki_retro` — save atomic insights from completed tasks with one call |
+| 💾 **Lightweight capture** | `wiki_retro` — save atomic insights as a single markdown file; full 4-layer pipeline also available via `wiki_capture_source` |
 | 🌐 **MCP Server** | Use with Claude Code, Cursor, Windsurf via stdio MCP transport |
 | 📝 **Obsidian-friendly** | Folder-qualified wikilinks, stable source-ID citations, compatible vault |
 | 🛡️ **Guardrails** | Blocks direct edits to raw sources and generated metadata |
@@ -72,7 +73,7 @@ The result is a wiki that **compounds** as you capture sources, ask questions, a
 |------|-------------|
 | `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_capture_source` | Capture a URL, local file, or pasted text into an immutable source packet |
-| `wiki_recall` | 🔄 **Auto-called at turn start** — search wiki for task-relevant pages |
+| `wiki_recall` | Search wiki for task-relevant pages — searches both personal (`~/.llm-wiki/`) and project (`.llm-wiki/`) vaults, deduplicated |
 | `wiki_retro` | Save atomic insights from completed tasks into the wiki |
 | `wiki_ingest` | Process uningested source packets into wiki pages (batch) |
 | `wiki_ensure_page` | Resolve or safely create entity / concept / synthesis / analysis pages |
@@ -99,6 +100,28 @@ The result is a wiki that **compounds** as you capture sources, ask questions, a
 
 ---
 
+## Layered Vault Architecture
+
+Knowledge follows you everywhere. pi-llm-wiki uses a layered vault system:
+
+| Layer | Location | Purpose |
+|-------|----------|---------|
+| 🏠 **Personal** | `~/.llm-wiki/` | Always active. Zero setup. Knowledge compounds across all your sessions — regardless of which project you're in. |
+| 📁 **Project** | `{project}/.llm-wiki/` | Explicit opt-in. Dedicated wiki per project, sharing personal knowledge when relevant. |
+| 🏢 **Company** (future) | git-tracked | Shared wiki across a team. `wiki_publish` promotes personal/project pages to the company wiki. |
+
+**How it works:**
+
+1. `resolveVaultRoot()` checks: cwd → walk up for `.llm-wiki/` → `~/.llm-wiki/`
+2. `wiki_recall` (layered) searches **both** personal and project vaults, merging results with vault labels
+3. Personal results are shown first in recall output, tagged as "📓 personal"
+4. `wiki_retro` writes to whichever vault is active (project takes priority)
+5. Set `WIKI_HOME` env var to override the personal wiki location
+
+This means: you can have a project wiki for team documentation **and** a personal wiki for your own notes, and recall searches both simultaneously.
+
+---
+
 ## Quick Start (Detailed)
 
 ### 1) Create a new wiki
@@ -309,7 +332,13 @@ The bundled `llm-wiki` skill teaches the model to:
 
 ## Architecture
 
-Four layers with clear ownership:
+### Vault Layers
+
+See the [Layered Vault Architecture](#layered-vault-architecture) section above for the personal/project/company layering.
+
+### Four-Layer Page Model
+
+Each wiki vault has four layers with clear ownership:
 
 ```
 .llm-wiki/raw/sources/SRC-*/     # Immutable source packets (extension-owned)

package/docs/architecture.md

@@ -1,6 +1,37 @@
 # Architecture
 
-## Four Layers
+## Layered Vault Architecture
+
+pi-llm-wiki supports multiple vault layers that are searched together:
+
+| Layer | Location | Resolution | Searched by recall |
+|-------|----------|------------|-------------------|
+| **Personal** | `~/.llm-wiki/` | Fallback when no project wiki found | ✅ Always |
+| **Project** | `{project}/.llm-wiki/` | Walk up from cwd | ✅ When present |
+
+### Resolution Order
+
+1. Check current directory for `.llm-wiki/` → use as project wiki
+2. Walk up parent directories looking for `.llm-wiki/` → use as project wiki
+3. Check `WIKI_HOME` env var → use as personal wiki
+4. Fall back to `~/.llm-wiki/` → create if doesn't exist
+
+This means a project wiki is always preferred when you're inside a project that has one, but your personal wiki is always available as the fallback.
+
+### Dual-Vault Recall
+
+`wiki_recall` uses `searchWikiLayered()` which:
+1. Searches the **project vault** (if one exists in cwd)
+2. Searches the **personal vault** (`~/.llm-wiki/` or `WIKI_HOME`)
+3. Deduplicates results by page ID (project takes priority on duplicates)
+4. Tags personal results with "📓 personal" label
+5. Merges results: personal first, then project
+
+Results are injected into the context with vault source tags so the model can distinguish between personal and project knowledge.
+
+---
+
+## Four-Layer Page Model (within each vault)
 
 ```
 WIKI_ROOT/

package/docs/commands.md

@@ -22,7 +22,7 @@ The extension registers 12 tools the LLM can call directly:
 | --------------------- | ------------------------------------------- |
 | `wiki_bootstrap`      | Initialize a new vault                      |
 | `wiki_capture_source` | Capture URL/file/text into immutable packet |
-| `wiki_recall`         | 🔄 Auto-called at turn start — search wiki  |
+| `wiki_recall`         | Search personal + project wikis for task-relevant pages (layered) |
 | `wiki_retro`          | Save atomic insights from completed tasks   |
 | `wiki_ingest`         | Get batch of uningested sources             |
 | `wiki_ensure_page`    | Create canonical page from template         |

package/docs/configuration.md

@@ -6,6 +6,8 @@ Wiki configuration lives in `.llm-wiki/config.json`.
 
 ### Personal
 
+The personal vault lives at `~/.llm-wiki/` (or `$WIKI_HOME`) and is always available as a fallback when no project wiki exists. It accumulates knowledge across all your sessions.
+
 - Extra folders: `wiki/journal/`, `wiki/goals/`
 - Track: learning, books, health, reflections
 
@@ -25,9 +27,19 @@ Wiki configuration lives in `.llm-wiki/config.json`.
 
 ## Environment Variables
 
-| Variable                      | Default | Description                                     |
-| ----------------------------- | ------- | ----------------------------------------------- |
-| `WIKI_MARKITDOWN_TIMEOUT_MS` | 180000  | Timeout (ms) for MarkItDown PDF/text extraction |
+| Variable                      | Default     | Description                                     |
+| ----------------------------- | ----------- | ----------------------------------------------- |
+| `WIKI_HOME`                   | `~/.llm-wiki` | Override the personal wiki vault location     |
+| `WIKI_MARKITDOWN_TIMEOUT_MS` | 180000      | Timeout (ms) for MarkItDown PDF/text extraction |
+
+## Vault Resolution
+
+The vault root is resolved in this priority order:
+
+1. **Project vault**: walk up from current directory looking for `.llm-wiki/`
+2. **Personal vault**: fall back to `$WIKI_HOME` or `~/.llm-wiki/`
+
+This means when you're in a project with its own `.llm-wiki/`, that project wiki is active. When you're outside any project wiki, your personal `~/.llm-wiki/` takes over automatically.
 
 ## Page Frontmatter
 

package/extensions/llm-wiki/index.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { installGuardrails } from "./lib/guardrails.js";
-import { formatRecallContext, registerWikiRecall, searchWiki } from "./lib/recall.js";
+import { formatRecallContext, registerWikiRecall, searchWikiLayered } from "./lib/recall.js";
 import { registerWikiRetro } from "./lib/retro.js";
 import {
   registerWikiBootstrap,
@@ -27,17 +27,19 @@ import {
 /**
  * @zosmaai/pi-llm-wiki — LLM Wiki extension for Pi
  *
- * Registers 11 custom tools and installs guardrails:
- * All 10 original tools + wiki_recall (auto-recall at session start)
+ * Registers 12 custom tools and installs guardrails:
+ * - wiki_recall (layered: personal + project vaults)
+ * - wiki_retro (lightweight: single markdown file)
+ * - wiki_capture_source (full 4-layer pipeline)
  *
  * Guardrails:
  * - Blocks direct edits to raw/** and meta/**
  * - Auto-rebuilds metadata after wiki/** edits
  *
- * Auto-recall:
- * - before_agent_start hook searches wiki for pages relevant to user prompt
- * - Injects matching knowledge as system context
- * - wiki_recall tool available for explicit deep searches
+ * Layered recall:
+ * - before_agent_start hook searches personal + project vaults
+ * - Injects matching knowledge as system context with vault labels
+ * - wiki_recall tool available for explicit task-specific searches
  */
 
 export default function (pi: ExtensionAPI) {
@@ -95,14 +97,14 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    ctx.ui.setStatus("llm-wiki", "🧠 LLM Wiki (12 tools, auto-recall active)");
+    ctx.ui.setStatus("llm-wiki", "🧠 LLM Wiki (12 tools, layered recall active)");
   });
 
-  // ─── Auto-recall + topic inference hook ─────────────
+  // ─── Layered recall + topic inference hook ──────────
   // Before each agent turn:
   // 1. If wiki was just auto-created, inject a directive to infer topic/mode
   //    from the user's first prompt and update config via wiki_bootstrap.
-  // 2. Search wiki for relevant pages and inject as system context.
+  // 2. Search both personal + project vaults for relevant pages.
   pi.on("before_agent_start", async (event, _ctx) => {
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
@@ -145,9 +147,9 @@ ${projectHints}
 Then call wiki_bootstrap with the inferred topic and mode to finalize the setup. This is a one-time step.`;
     }
 
-    // Auto-recall: search wiki for relevant pages
+    // Layered recall: search personal + project vaults for relevant pages
     if (prompt.trim()) {
-      const results = searchWiki(paths, prompt);
+      const results = searchWikiLayered(paths, prompt);
       if (results.length > 0) {
         const recallContext = formatRecallContext(results);
         if (recallContext) {
@@ -156,6 +158,11 @@ Then call wiki_bootstrap with the inferred topic and mode to finalize the setup.
       }
     }
 
+    // Always inject a visible wiki status footer, even when empty
+    // This ensures the model knows the wiki is active and can use it
+    injectedContext +=
+      "\n\n<wiki_status>LLM Wiki active — use wiki_recall for deeper search, wiki_retro to save new knowledge.</wiki_status>";
+
     if (injectedContext === event.systemPrompt) return;
     return { systemPrompt: injectedContext };
   });

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

@@ -3,7 +3,13 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import type { Registry } from "./metadata.js";
-import { type VaultPaths, readJson, resolveVaultPaths } from "./utils.js";
+import {
+  type VaultPaths,
+  getPersonalWikiPaths,
+  isPersonalVault,
+  readJson,
+  resolveVaultPaths,
+} from "./utils.js";
 
 // ─── Public API ────────────────────────────────────────
 
@@ -18,10 +24,12 @@ export interface RecallResult {
   preview: string;
   /** Relative path from wiki root */
   path: string;
+  /** Vault source label for dual-vault results */
+  vaultLabel?: string;
 }
 
 /**
- * Search the wiki registry for pages matching a query.
+ * Search a single vault's registry for pages matching a query.
  * Returns up to `maxResults` matches, each with a content preview.
  */
 export function searchWiki(paths: VaultPaths, query: string, maxResults = 5): RecallResult[] {
@@ -88,21 +96,68 @@ export function searchWiki(paths: VaultPaths, query: string, maxResults = 5): Re
   });
 }
 
+/**
+ * Format recall results as a compact system-prompt section.
+ */
+/**
+ * Search both project/primary vault and personal vault, merging results.
+ * Personal results are appended after primary results, deduplicated by page ID.
+ */
+export function searchWikiLayered(
+  primaryPaths: VaultPaths,
+  query: string,
+  maxResults = 5,
+): RecallResult[] {
+  // Search primary vault
+  const primaryResults = searchWiki(primaryPaths, query, maxResults);
+
+  // If primary is already the personal vault, no layered search needed
+  if (isPersonalVault(primaryPaths)) return primaryResults;
+
+  // Search personal vault as secondary layer
+  const personalPaths = getPersonalWikiPaths();
+  if (!existsSync(join(personalPaths.dotWiki, "config.json"))) return primaryResults;
+
+  const personalResults = searchWiki(personalPaths, query, maxResults);
+
+  // Merge: personal results first (they're the user's accumulated knowledge),
+  // then primary results (project-specific). Deduplicate by page ID.
+  const seen = new Set<string>();
+  const merged: RecallResult[] = [];
+
+  for (const r of [...personalResults, ...primaryResults]) {
+    if (seen.has(r.id)) continue;
+    seen.add(r.id);
+    // If it's from personal vault, tag it
+    if (personalResults.includes(r)) {
+      merged.push({ ...r, vaultLabel: "📓 personal" });
+    } else {
+      merged.push(r);
+    }
+  }
+
+  return merged.slice(0, maxResults);
+}
+
 /**
  * Format recall results as a compact system-prompt section.
  */
 export function formatRecallContext(results: RecallResult[]): string {
   if (results.length === 0) return "";
 
+  const hasLayered = results.some((r) => r.vaultLabel);
+  const label = hasLayered ? " (personal + project)" : "";
+
   const lines: string[] = [
     "## Relevant Wiki Knowledge",
     "",
-    `_${results.length} page(s) matched your query — reviewed automatically by LLM Wiki._`,
+    `_${results.length} page(s) matched your query${label}._`,
     "",
   ];
 
   for (const r of results) {
-    lines.push(`- **[[${r.id}]]** — *${r.type}* — ${r.title}`);
+    const vaultTag = r.vaultLabel ? ` ${r.vaultLabel}` : "";
+    lines.push(`- **[[${r.id}]]** — *${r.type}* — ${r.title}${vaultTag}`);
     if (r.preview) {
       // Truncate preview to one line
       const preview = r.preview.length > 120 ? `${r.preview.slice(0, 120)}…` : r.preview;
@@ -164,30 +219,34 @@ export function registerWikiRecall(pi: ExtensionAPI): void {
       }
 
       const maxResults = Math.min(params.max_results ?? 5, 10);
-      const results = searchWiki(paths, params.query, maxResults);
+      // Use layered search: personal vault + project vault
+      const results = searchWikiLayered(paths, params.query, maxResults);
 
       if (results.length === 0) {
         return {
           content: [
             {
               type: "text",
-              text: `No wiki pages found matching "${params.query}". Use wiki_search for broader results.`,
+              text: `No wiki pages found matching "${params.query}". The wiki is empty — use wiki_retro to start building knowledge.`,
             },
           ],
           details: { query: params.query, matches: [] } as Record<string, unknown>,
         };
       }
 
+      const hasPersonal = results.some((r) => r.vaultLabel);
+      const layerTag = hasPersonal ? " (personal + project)" : "";
+
       return {
         content: [
           {
             type: "text",
             text: [
-              `🧠 **${results.length} wiki page(s) relevant** to "${params.query}":`,
+              `🧠 **${results.length} wiki page(s) relevant** to "${params.query}"${layerTag}:`,
               "",
               ...results.map(
                 (r) =>
-                  `- [[${r.id}]] — *${r.type}* — ${r.title}${
+                  `- ${r.vaultLabel || "📁"} [[${r.id}]] — *${r.type}* — ${r.title}${
                     r.preview ? `\n  > ${r.preview.slice(0, 150)}` : ""
                   }`,
               ),

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

@@ -3,19 +3,24 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { appendEvent, rebuildMetadataLight } from "./metadata.js";
-import { type VaultPaths, fmtDate, nextSourceId, resolveVaultPaths } from "./utils.js";
+import { type VaultPaths, fmtDate, resolveVaultPaths } from "./utils.js";
 
 // ─── Public API ────────────────────────────────────────
 
 export interface RetroResult {
-  sourceId: string;
-  packetPath: string;
+  slug: string;
   sourcePagePath: string;
 }
 
 /**
- * Save an atomic insight into the wiki as a source packet + source page.
- * Returns the source ID, packet path, and source page path.
+ * Save an atomic insight into the wiki as a single markdown file.
+ *
+ * Unlike wiki_capture_source (which creates a full source packet with
+ * manifest.json, extracted.md, and attachments), this is a lightweight
+ * path for quick knowledge capture — one file, one call.
+ *
+ * The 4-layer pipeline (raw → source pages → canonical pages → metadata)
+ * is still available via wiki_capture_source → wiki_ingest for deep research.
  */
 export function saveInsight(
   paths: VaultPaths,
@@ -24,92 +29,54 @@ export function saveInsight(
   body: string,
   category?: string,
 ): RetroResult {
-  const sourceId = nextSourceId(paths);
-  const packetPath = join(paths.rawSources, sourceId);
-  mkdirSync(packetPath, { recursive: true });
-  mkdirSync(join(packetPath, "attachments"), { recursive: true });
-
   const today = fmtDate();
 
-  // Write manifest
-  const manifest = {
-    id: sourceId,
-    title,
-    slug,
-    category: category || "uncategorized",
-    captured: today,
-    format: "insight",
-    packet_version: "1.0",
-  };
-  writeFileSync(
-    join(packetPath, "manifest.json"),
-    `${JSON.stringify(manifest, null, 2)}\n`,
-    "utf-8",
-  );
-
-  // Write extracted text (the insight body in markdown)
-  const extracted = [
-    `# ${title}`,
-    "",
-    body,
-    "",
-    "---",
-    `*Captured: ${today}*`,
-    category ? `*Category: ${category}*` : "",
-  ]
-    .filter(Boolean)
-    .join("\n");
-  writeFileSync(join(packetPath, "extracted.md"), extracted, "utf-8");
-
-  // Create source page
+  // Write a single markdown file to wiki/sources/{slug}.md
   const sourcePageDir = join(paths.wiki, "sources");
   mkdirSync(sourcePageDir, { recursive: true });
-  const sourcePagePath = join(sourcePageDir, `${sourceId}.md`);
+  const sourcePagePath = join(sourcePageDir, `${slug}.md`);
 
-  const tagLine = category ? `category: ${category}` : "";
-  const sourcePageContent = [
+  const pageContent = [
     "---",
     "type: source",
     `title: "${title}"`,
-    `source_id: ${sourceId}`,
+    `slug: ${slug}`,
     "status: insight",
     `created: ${today}`,
     `updated: ${today}`,
-    tagLine,
+    category ? `category: ${category}` : "",
     "---",
     "",
     `# ${title}`,
     "",
     body,
     "",
-    "## Source",
+    category ? `*Category: ${category}*` : "",
     "",
-    `- **Packet:** \`${packetPath}\``,
-    `- **Captured:** ${today}`,
-    category ? `- **Category:** ${category}` : "",
+    "---",
+    `*Captured: ${today}*`,
     "",
     "## Related",
     "",
-    "_(Add [[wikilinks]] to related pages)_",
+    "_Add links to related pages._",
     "",
   ]
     .filter((l) => l !== "")
     .join("\n");
-  writeFileSync(sourcePagePath, sourcePageContent, "utf-8");
+  writeFileSync(sourcePagePath, pageContent, "utf-8");
 
   // Log event
   appendEvent(paths, {
     kind: "retro",
-    source_id: sourceId,
-    title,
     slug,
+    title,
     category: category || "uncategorized",
   });
 
-  // Rebuild metadata
+  // Rebuild metadata so the insight is immediately searchable
   rebuildMetadataLight(paths);
 
-  return { sourceId, packetPath, sourcePagePath };
+  return { slug, sourcePagePath };
 }
 
 // ─── Tool Registration ──────────────────────────────────
@@ -176,8 +143,6 @@ export function registerWikiRetro(pi: ExtensionAPI): void {
             text: [
               `🧠 **Insight saved**: ${params.title}`,
               "",
-              `- Source: \`${result.sourceId}\``,
-              `- Packet: \`${result.packetPath}\``,
               `- Page: \`${result.sourcePagePath}\``,
               "",
               "This insight will be auto-surfaced by wiki_recall in future sessions.",
@@ -185,7 +150,6 @@ export function registerWikiRetro(pi: ExtensionAPI): void {
           },
         ],
         details: {
-          sourceId: result.sourceId,
           slug: params.slug,
           title: params.title,
           category: params.category || null,

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

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
@@ -32,7 +33,35 @@ export function detectVaultFormat(dir: string): VaultFormat {
   return "none";
 }
 
-/** Resolve vault root from cwd or find nearest wiki root. */
+/** Get the personal wiki root directory (~/.llm-wiki/). */
+export function getPersonalWikiRoot(): string {
+  const envWiki = process.env.WIKI_HOME;
+  if (envWiki) return envWiki;
+  return join(homedir(), ".llm-wiki");
+}
+
+/** Get VaultPaths for the personal wiki. */
+export function getPersonalWikiPaths(): VaultPaths {
+  return getVaultPaths(getPersonalWikiRoot());
+}
+
+/**
+ * Check if a vault is the personal wiki location.
+ * Used in layered recall to avoid double-counting.
+ */
+export function isPersonalVault(paths: VaultPaths): boolean {
+  return paths.root === getPersonalWikiRoot();
+}
+
+/**
+ * Resolve vault root from cwd with personal fallback.
+ *
+ * Priority:
+ * 1. cwd has .llm-wiki/ → project wiki (explicit)
+ * 2. Walk up from cwd → parent project wiki
+ * 3. ~/.llm-wiki/ exists → personal wiki
+ * 4. Fallback: ~/.llm-wiki/ (create personal wiki)
+ */
 export function resolveVaultRoot(cwd: string): string {
   // Check for any vault format at cwd
   if (detectVaultFormat(cwd) !== "none") return cwd;
@@ -44,8 +73,12 @@ export function resolveVaultRoot(cwd: string): string {
     if (detectVaultFormat(dir) !== "none") return dir;
   }
 
-  // Fallback: cwd itself
-  return cwd;
+  // Check personal wiki at ~/.llm-wiki/
+  const personalRoot = getPersonalWikiRoot();
+  if (detectVaultFormat(personalRoot) !== "none") return personalRoot;
+
+  // Fallback: personal wiki
+  return personalRoot;
 }
 
 /** Get all vault paths for the new (.llm-wiki) layout. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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",

package/prompts/wiki-retro.md

@@ -1,5 +1,5 @@
 ---
-description: Save an atomic insight from the current task into the wiki. Creates a source packet and source page for future auto-recall.
+description: Save an atomic insight from the current task into the wiki. Creates a single markdown file that layered recall surfaces in future sessions.
 argument-hint: "<title> [--category <category>]"
 section: LLM Wiki
 topLevelCli: true
@@ -9,7 +9,7 @@ topLevelCli: true
 
 Save an atomic insight from a completed task into the wiki.
 
-Captures what you learned as an immutable source packet + wiki source page so that `wiki_recall` automatically surfaces it in future sessions.
+Captures what you learned as a single markdown file so that layered recall surfaces it in future sessions.
 
 ## User Arguments
 
@@ -25,7 +25,7 @@ Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand th
    - `title`: short descriptive phrase, ≤60 chars, noun phrase not a sentence
    - `body`: markdown explanation with `[[wikilinks]]` to related wiki pages
    - `category`: optional (frontend, architecture, devops, bugfix, design, etc.)
-3. Confirm the insight was saved and will be auto-surfaced in future sessions
+3. Confirm the insight was saved and will be surfaced by layered recall in future sessions
 4. If the insight relates to existing wiki pages, update those pages with cross-references
 
 **Rules:**

package/skills/llm-wiki/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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 12 custom tools.
-whenToUse: At the START of every task, the extension auto-recalls relevant wiki pages — no manual action needed. After completing any meaningful task, call wiki_retro to save insights for future sessions. Invoke proactively — do not wait for the user to ask.
+whenToUse: Call wiki_recall at task start to find relevant wiki pages. Call wiki_retro at task end to save new insights. The extension injects a brief status line, but explicit wiki_recall calls with task-specific terms get better results.
 ---
 
 # LLM Wiki for Pi
@@ -56,25 +56,24 @@ WIKI_ROOT/
 | Find orphans                | Shell `grep` scans           | Instant from `backlinks.json`         |
 | Block raw edits             | Skill says "don't"           | Extension **enforces** immutability   |
 | Create source page          | 8 tool calls                 | `wiki_capture_source` + LLM synthesis |
-| **Recall wiki knowledge**   | Never happens                | **Auto-search before every turn**     |
+| **Recall wiki knowledge**   | Never happens                | **Layered search before every turn (personal + project)** |
 | **Save task insights**      | Manual capture               | `wiki_retro` — one tool call          |
 
-## 🔄 Proactive Wiki Usage
+## 🔄 Wiki Usage
 
-### At Task Start — Auto-Recall (Automatic)
+### At Start — Call wiki_recall
 
-**The extension automatically searches the wiki before every user turn.**
+**Call `wiki_recall` at the START of every task** to find relevant wiki pages:
 
-When you send a prompt, the extension:
-1. Extracts key terms from your request
-2. Searches the wiki registry for matching pages
-3. Injects matching page titles + summaries into context
-4. You see this as "Relevant Wiki Knowledge" in your system prompt
+```
+wiki_recall(query="key terms from the user's request", max_results=5)
+```
 
-**This means the wiki works as an automatic second brain.**
-You don't need to remember to search — relevant knowledge is surfaced automatically.
+This searches both your **personal wiki** (`~/.llm-wiki/`) and the **project wiki** (`.llm-wiki/` in the current directory), merging results.
 
-### At Task End — Save Insights (Proactive)
+The extension also briefly searches automatically, but explicit calls with task-specific terms get better results.
+
+### At End — Save Insights with wiki_retro
 
 After completing any meaningful task, call `wiki_retro` to save key insights:
 - Non-obvious bug fixes or workarounds
@@ -84,29 +83,26 @@ After completing any meaningful task, call `wiki_retro` to save key insights:
 
 **Do not wait for the user to ask.** Save insights proactively — one atomic insight per call.
 
-```wiki_retro(slug="kebab-case-slug", title="Brief descriptive title", body="Insight in your own words with [[wikilinks]]")
+```
+wiki_retro(slug="kebab-case-slug", title="Brief descriptive title", body="Insight in your own words with [[wikilinks]]")
 ```
 
-### Manual Recall for Deeper Searches
+### Deeper Searches
 
-If the auto-recall doesn't find enough context, call `wiki_recall` explicitly:
+For thorough research, also use `wiki_search` to browse the full registry:
 
 ```
-wiki_recall(query="specific terms...", max_results=10)
+wiki_search(query="broad topic")
 ```
 
-This gives you more control over the search terms and returns content previews.
+### Auto-Bootstrap (One-Time)
 
-### Auto-Bootstrap (New)
-
-**The extension now creates the wiki vault automatically on startup — no user prompt needed.**
-
-When you start in a directory without a wiki, the extension silently creates `.llm-wiki/` with placeholder config. On your first turn, it injects a directive asking you to:
-1. Analyze the user's prompt and project context
-2. Infer a topic (e.g. "React app", "startup finances")
-3. Call `wiki_bootstrap(topic="...", mode="personal|company")` to finalize setup
+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:
+```
+wiki_bootstrap(topic="...", mode="personal|company")
+```
 
-This is a one-time step — after bootstrap, normal auto-recall takes over.
+This is a one-time step.
 
 ## Available Tools
 
@@ -114,7 +110,7 @@ Use these directly — they handle scaffolding, bookkeeping, recall, and capture
 
 - `wiki_bootstrap` — Initialize a new vault
 - `wiki_capture_source` — Capture URL/file/text into immutable packet + skeleton page
-- `wiki_recall` — **Auto-called at turn start.** Search wiki for task-relevant pages
+- `wiki_recall` — Search both personal + project wikis for task-relevant pages
 - `wiki_retro` — Save an atomic insight from a completed task into the wiki
 - `wiki_ingest` — Get batch of uningested sources with extracted text
 - `wiki_ensure_page` — Create entity/concept/synthesis/analysis page from template
@@ -139,19 +135,20 @@ Use these directly — they handle scaffolding, bookkeeping, recall, and capture
 
 ### Query → Answer → File
 
-1. **Auto-recall**: Extension surfaces relevant wiki pages automatically
-2. Read those pages
-3. Synthesize answer with `[[wikilink]]` citations
-4. If novel: create analysis page via `wiki_ensure_page(type="analysis")`
-5. Extension auto-updates metadata
+1. **Layered recall**: Extension searches personal + project vaults, injects matching pages with vault labels
+2. For better results: call `wiki_recall` explicitly with task-specific terms
+3. Read those pages
+4. Synthesize answer with `[[wikilink]]` citations
+5. If novel: create analysis page via `wiki_ensure_page(type="analysis")`
+6. Extension auto-updates metadata
 
 ### Task → Capture → Retro
 
 1. Complete a meaningful task
 2. Call `wiki_retro` to save key insights
-3. The insight is captured as a source packet
+3. The insight is saved as a single markdown file
 4. Extension auto-updates metadata
-5. Next time, auto-recall surfaces your saved insight
+5. Next time, layered recall surfaces your saved insight
 
 ## Page Conventions