@zosmaai/pi-llm-wiki 0.6.6 → 0.7.1

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

@@ -28,8 +28,8 @@ import {
  * All LLM Wiki custom tools.
  */
 
-function getPaths(cwd = process.cwd()): VaultPaths {
-  return resolveVaultPaths(cwd);
+function getPaths(cwd?: string): VaultPaths {
+  return resolveVaultPaths(cwd ?? process.cwd());
 }
 
 function requireVault(paths: VaultPaths): { ok: true } | { ok: false; reason: string } {
@@ -58,7 +58,7 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const root = params.root ? params.root : (ctx.cwd ?? process.cwd());
+      const root = params.root ?? ctx.cwd ?? process.cwd();
       const mode = params.mode || "personal";
       const paths = getVaultPaths(root);
 
@@ -121,6 +121,7 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
             type: "text",
             text: [
               `✅ Wiki bootstrapped at \`${paths.root}\``,
+              "**Scope:** project-local",
               "",
               "**Structure:**",
               "- .llm-wiki/raw/sources/ — immutable source packets",
@@ -158,8 +159,8 @@ export function registerWikiCaptureSource(pi: ExtensionAPI): void {
       text: Type.Optional(Type.String({ description: "Pasted text content" })),
       title: Type.Optional(Type.String({ description: "Title for pasted text" })),
     }),
-    async execute(_toolCallId, params, signal) {
-      const paths = getPaths();
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
       const vaultCheck = requireVault(paths);
       if (!vaultCheck.ok) {
         return {
@@ -239,8 +240,8 @@ export function registerWikiIngest(pi: ExtensionAPI): void {
         Type.Number({ description: "Max sources to return (default: 3, max: 5)", default: 3 }),
       ),
     }),
-    async execute(_toolCallId, params) {
-      const paths = getPaths();
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
       const vaultCheck = requireVault(paths);
       if (!vaultCheck.ok) {
         return {
@@ -377,8 +378,8 @@ export function registerWikiEnsurePage(pi: ExtensionAPI): void {
         Type.String({ description: "Optional initial content (otherwise uses template)" }),
       ),
     }),
-    async execute(_toolCallId, params) {
-      const paths = getPaths();
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
       const vaultCheck = requireVault(paths);
       if (!vaultCheck.ok) {
         return {
@@ -523,8 +524,8 @@ export function registerWikiSearch(pi: ExtensionAPI): void {
       query: Type.String({ description: "Search term" }),
       type: Type.Optional(Type.String({ description: "Filter by page type" })),
     }),
-    async execute(_toolCallId, params) {
-      const paths = getPaths();
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
       const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
         version: "1.0",
         last_updated: "",
@@ -586,8 +587,8 @@ export function registerWikiLint(pi: ExtensionAPI): void {
         Type.Boolean({ description: "Auto-fix orphans and missing pages", default: false }),
       ),
     }),
-    async execute(_toolCallId, params) {
-      const paths = getPaths();
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
       const vaultCheck = requireVault(paths);
       if (!vaultCheck.ok) {
         return {
@@ -741,8 +742,8 @@ export function registerWikiStatus(pi: ExtensionAPI): void {
     promptSnippet: "Report wiki health and stats",
     promptGuidelines: ["Use wiki_status for a quick overview."],
     parameters: Type.Object({}),
-    async execute() {
-      const paths = getPaths();
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
       const vaultCheck = requireVault(paths);
       if (!vaultCheck.ok) {
         return {
@@ -818,8 +819,8 @@ export function registerWikiRebuildMeta(pi: ExtensionAPI): void {
     promptSnippet: "Rebuild all wiki metadata",
     promptGuidelines: ["Use wiki_rebuild_meta if metadata seems out of sync."],
     parameters: Type.Object({}),
-    async execute() {
-      const paths = getPaths();
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
       const vaultCheck = requireVault(paths);
       if (!vaultCheck.ok) {
         return {
@@ -864,8 +865,8 @@ export function registerWikiLogEvent(pi: ExtensionAPI): void {
       kind: Type.String({ description: "Event kind (e.g., ingest, query, decision)" }),
       details: Type.Optional(Type.Object({}, { description: "Additional event fields" })),
     }),
-    async execute(_toolCallId, params) {
-      const paths = getPaths();
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const paths = getPaths(ctx.cwd);
       const vaultCheck = requireVault(paths);
       if (!vaultCheck.ok) {
         return {
@@ -904,7 +905,7 @@ export function registerWikiWatch(pi: ExtensionAPI): void {
     parameters: Type.Object({
       interval: Type.String({ description: "daily, weekly, hourly, or stop" }),
     }),
-    async execute(_toolCallId, params) {
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       if (params.interval === "stop") {
         return {
           content: [

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.6.6",
+  "version": "0.7.1",
   "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-digest.md

@@ -15,13 +15,14 @@ $ARGUMENTS
 
 ## Steps
 
-1. Read `wiki/LOG.md` — filter entries since last digest
-2. Read pages created/updated in that period
+1. Call `wiki_status()` to get current stats (page count, orphans, gaps, health).
+2. Read `.llm-wiki/meta/log.md` for recent events since the last digest period.
 3. Summarize:
-   - New sources ingested
-   - New pages created
-   - Key insights or connections
+   - New sources captured
+   - New pages created or updated
+   - Key insights or connections made
    - Knowledge gaps identified
-   - Health trends
-4. Save → `outputs/digest-YYYY-MM-DD.md`
-5. Report concise digest
+   - Health trends (improving, stable, declining)
+4. Save the digest to `.llm-wiki/outputs/digest-YYYY-MM-DD.md` using the `write` tool.
+5. Call `wiki_log_event(kind=digest)` to record this digest was generated.
+6. Report a concise digest to the user.

package/prompts/wiki-discover.md

@@ -7,27 +7,24 @@ topLevelCli: true
 
 # /wiki-discover
 
-Find new source material for the wiki by searching the web.
+Find new source material for the wiki by searching the web and capturing them as source packets.
 
 ## User Arguments
 
 $ARGUMENTS
 
-Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first. Also read `config.yaml` for topics and feeds.
-
 ## Steps
 
-1. Read `.llm-wiki/config.yaml` → extract topics, keywords, feeds
-2. Read `.llm-wiki/.discoveries/gaps.json` → knowledge gaps to fill
-3. Read `.llm-wiki/.discoveries/history.json` → already-fetched URLs
-4. Search for new sources:
-   - Web search each topic + latest keywords
-   - Search for gaps from `.llm-wiki/.discoveries/gaps.json`
-   - If `--topic` specified, focus search on that topic
-5. For each promising result:
-   a. Fetch full content
-   b. Save to `.llm-wiki/raw/articles/YYYY-MM-DD-slug.md` with frontmatter (title, url, discovered, topic)
-6. Update `.llm-wiki/.discoveries/history.json`
-7. Report: "Discovered [N] new sources. Run `/wiki-ingest` to process them."
-
-**Rules:** Max 5-10 sources. Skip ads, listicles, duplicates. Prefer in-depth analysis.
+1. Call `wiki_status()` to get the current topic and mode from the wiki config.
+2. Use `wiki_search(query=<topic>)` to find existing pages and identify what's already covered.
+3. Search the web for new sources:
+   - If `--topic` is specified in `$ARGUMENTS`, focus on that topic
+   - Otherwise, search for the wiki's main topic + "latest", "news", "update"
+4. For each promising result (max 5-10):
+   a. Call `wiki_capture_source(url=<url>)` to capture it as an immutable source packet
+   b. Skip ads, listicles, and duplicates — prefer in-depth analysis
+5. Report: "Discovered [N] new sources captured as packets. Run `/wiki-ingest` to synthesize them into knowledge pages."
+
+**Rules:**
+- Do NOT manually save files to `raw/` — always use `wiki_capture_source`.
+- The extension handles manifest, extraction, and skeleton page creation automatically.

package/prompts/wiki-ingest.md

@@ -1,34 +1,33 @@
 ---
-description: Process new source files in raw/ and update the wiki. Creates summaries, entities, concepts, and cross-references.
-argument-hint: "[path]"
+description: Process new source packets and synthesize them into wiki knowledge pages.
+argument-hint: "[source_id]"
 section: LLM Wiki
 topLevelCli: true
 ---
 
 # /wiki-ingest
 
-Process new files in `.llm-wiki/raw/` and integrate them into the wiki.
+Process uningested source packets and synthesize them into wiki knowledge pages.
 
 ## User Arguments
 
 $ARGUMENTS
 
-Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the full schema, page formats, and conventions.
-
 ## Steps
 
-1. Read `.llm-wiki/config.yaml` and `.llm-wiki/.discoveries/history.json`
-2. If a specific path is given (e.g., `/wiki-ingest .llm-wiki/raw/articles/my-file.md`), process just that file
-3. If no path given, scan all files in `.llm-wiki/raw/` (respecting `.gitignore` — skip any matched files) and find ones not in history
-4. For each new source:
-   a. Read the full content
-   b. Briefly discuss with the user: "This is about [topic]. Key points: [summary]. Any specific emphasis?"
-   c. Create/update pages in `.llm-wiki/wiki/sources/`, `.llm-wiki/wiki/entities/`, `.llm-wiki/wiki/concepts/`
-   d. Add `[[wikilinks]]` cross-references between related pages
-   e. Flag any contradictions with existing wiki content
-5. Update `.llm-wiki/wiki/INDEX.md` with all new/updated pages
-6. Append to `.llm-wiki/wiki/LOG.md`
-7. Update `.llm-wiki/.discoveries/history.json`
-8. Report: "Ingested [N] sources → [M] pages created/updated. [X] contradictions flagged."
-
-**Rules:** Never modify raw/ files. Never fabricate information. Always cite sources.
+1. Call `wiki_ingest(source_id=<id if provided>, batch_size=3)` to get sources needing synthesis.
+2. If the tool reports "All sources ingested", inform the user and stop.
+3. For each source in the returned batch:
+   a. Read the extracted text from `raw/sources/<SOURCE_ID>/extracted.md`
+   b. Update the skeleton source page in `wiki/sources/` with a proper summary, key entities, and concepts
+   c. Use `wiki_ensure_page(type=entity, title=<name>)` for each new entity (people, orgs, tools, products)
+   d. Use `wiki_ensure_page(type=concept, title=<name>)` for each new concept (ideas, patterns, frameworks)
+   e. Add `[[wikilinks]]` cross-references between related pages
+   f. Flag any contradictions with existing wiki content using `⚠️ **Contradiction**` markers
+4. After processing the batch, call `wiki_rebuild_meta` to update metadata.
+5. Report: "Ingested [N] sources → [M] pages created/updated. [X] contradictions flagged."
+
+**Rules:**
+- Never modify files in `raw/` — source packets are immutable after capture.
+- Never fabricate information — always cite sources with `[[sources/SRC-...]]`.
+- The extension auto-updates metadata — you do NOT need to manually edit `meta/` files.

package/prompts/wiki-init.md

@@ -7,28 +7,24 @@ topLevelCli: true
 
 # /wiki-init
 
-Initialize a new LLM Wiki in the current directory.
+Initialize a new LLM Wiki vault using the `wiki_bootstrap` tool.
 
 ## User Arguments
 
 $ARGUMENTS
 
-Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` (or wherever the skill is installed) first to understand the full schema and conventions.
-
 ## Steps
 
-1. Ask the user for the wiki topic and mode (`personal` or `company`)
-2. Create the directory structure:
-   - `.llm-wiki/raw/articles/`, `.llm-wiki/raw/papers/`, `.llm-wiki/raw/notes/`, `.llm-wiki/raw/assets/`
-   - `.llm-wiki/wiki/entities/`, `.llm-wiki/wiki/concepts/`, `.llm-wiki/wiki/sources/`, `.llm-wiki/wiki/syntheses/`, `.llm-wiki/wiki/changes/`
-   - `.llm-wiki/outputs/`
-   - `.llm-wiki/.discoveries/`
-3. Create `.llm-wiki/config.yaml` with the topic, mode, and default settings
-4. Create `.llm-wiki/wiki/INDEX.md` with section headings organized by page type
-5. Create `.llm-wiki/wiki/LOG.md` with initial entry
-6. Create `.llm-wiki/wiki/DASHBOARD.md` with Dataview queries for Obsidian
-7. Create `.gitignore` to exclude `.llm-wiki/outputs/` from version control if desired
-8. Initialize git repo if not already present
-9. Report the structure and suggest first steps: "Drop sources into `.llm-wiki/raw/` and run `/wiki-ingest`"
-
-If `--mode company`, add the `change_detection: true` flag to config.yaml and add a `.llm-wiki/wiki/decisions/` folder.
+1. If the user provided a topic in `$ARGUMENTS`, use it. Otherwise, ask the user for the wiki **topic**.
+2. Determine mode: default to `personal`; use `company` if the user specifies `--mode company` or requests it.
+3. Call `wiki_bootstrap(topic=<topic>, mode=<mode>)` to create the vault.
+4. Report the result and suggest next steps:
+   - "Use `wiki_capture_source` to add your first source (URL, file, or text)."
+   - "Run `/wiki-ingest` after capturing sources to synthesize them into knowledge pages."
+
+**Do NOT manually create directories or files.** The `wiki_bootstrap` tool handles all scaffolding including:
+- `.llm-wiki/raw/sources/` — immutable source packets
+- `.llm-wiki/wiki/` — editable knowledge pages
+- `.llm-wiki/meta/` — auto-generated metadata
+- `.llm-wiki/config.json` — vault configuration
+- `.llm-wiki/WIKI_SCHEMA.md` — operating rules

package/prompts/wiki-lint.md

@@ -13,21 +13,13 @@ Run a comprehensive health check on the wiki.
 
 $ARGUMENTS
 
-Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the full schema and conventions.
-
 ## Steps
 
-1. Scan all files in `.llm-wiki/wiki/` (respecting `.gitignore` — skip any matched files)
-2. Check for:
-   - **Contradictions:** Conflicting claims between pages
-   - **Orphans:** Pages with zero inbound `[[wikilinks]]`
-   - **Missing pages:** `[[links]]` pointing to non-existent files
-   - **Stale claims:** Info superseded by newer sources
-   - **Broken raw links:** References to `.llm-wiki/raw/` files that don't exist
-   - **Knowledge gaps:** Topics mentioned but lacking their own page
-   - **Quality:** Pages under 3 lines, pages with no sources or cross-refs
-3. If `--fix` flag is present: auto-fix broken links, create missing pages for frequently-linked concepts, add cross-refs to orphans. Flag contradictions for human decision.
-4. Save report → `.llm-wiki/outputs/lint-YYYY-MM-DD.md`
-5. Update `.llm-wiki/.discoveries/gaps.json`
-6. Append to `.llm-wiki/wiki/LOG.md`
-7. Report key findings
+1. Determine if auto-fix is requested: set `auto_fix=true` if `$ARGUMENTS` contains `--fix`, otherwise `false`.
+2. Call `wiki_lint(auto_fix=<true/false>)` to run the health check.
+3. Present the lint report to the user, including:
+   - Page count, orphans, missing pages, contradictions
+   - Knowledge gaps found
+   - Any auto-fixes applied
+4. If contradictions are found, flag them for human review — do NOT auto-resolve contradictions.
+5. If knowledge gaps are identified, suggest creating pages for frequently-mentioned topics.

package/prompts/wiki-query.md

@@ -13,24 +13,25 @@ Ask a question and get an answer synthesized from wiki content.
 
 $ARGUMENTS
 
-Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the full schema and conventions.
-
 ## Steps
 
-1. Read `wiki/INDEX.md` to find pages relevant to the question
-2. Read those pages in full (don't stop at 1-2 pages — get thorough context)
-3. Synthesize an answer with `[[wikilink]]` citations to specific wiki pages
-4. If the answer reveals a new connection or analysis, save it as a synthesis page in `wiki/syntheses/`
-5. Append to `wiki/LOG.md`
+1. Call `wiki_recall(query=<question>)` to find relevant wiki pages.
+2. Read the full content of each matching page using the `read` tool.
+3. Synthesize an answer with `[[wikilink]]` citations to specific wiki pages.
+4. If the answer reveals a new connection or analysis worth preserving:
+   - Call `wiki_ensure_page(type=synthesis, title=<title>, content=<content>)` to save it
+5. Call `wiki_log_event(kind=query, details={question: <question>})` to log the query.
 
-**Rules:** Answer ONLY from wiki content, not from general knowledge. If the wiki lacks information, say so clearly and suggest what sources would help fill the gap.
+**Rules:**
+- Answer ONLY from wiki content, not from general knowledge.
+- If the wiki lacks information, say so clearly and suggest what sources would help fill the gap.
 
 **Example:**
 
 ```
 /wiki-query What are the key differences between RAG and LLM Wiki?
-→ Reads INDEX.md, finds pages on RAG and LLM Wiki patterns
-→ Reads both pages
-→ Synthesizes a comparison table with [[wikilink]] citations
-→ Saves as wiki/syntheses/rag-vs-llm-wiki.md
+→ Calls wiki_recall(query="RAG LLM Wiki differences")
+→ Reads matching pages
+→ Synthesizes a comparison with [[wikilink]] citations
+→ Saves as synthesis page via wiki_ensure_page(type=synthesis, ...)
 ```

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/prompts/wiki-run.md

@@ -13,27 +13,17 @@ Run the complete wiki maintenance cycle: discover new sources, ingest them, and
 
 $ARGUMENTS
 
-Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first.
-
 ## Steps
 
-1. Run `/wiki-discover` → find new sources
-2. Run `/wiki-ingest` → process all new files
-3. Run `/wiki-lint` → health check
-4. If critical gaps found → optionally one more discover+ingest cycle
-5. Save summary → `outputs/run-YYYY-MM-DD.md`
-6. Report final summary
+1. **Discover:** Use web search to find new sources on the wiki's topic, then capture each with `wiki_capture_source(url=<url>)` (max 5-10).
+2. **Ingest:** Call `wiki_ingest(batch_size=3)` and process returned sources — read extracted.md, update source pages, create entity/concept pages, add cross-references.
+3. **Lint:** Call `wiki_lint(auto_fix=false)` to run a health check.
+4. If critical gaps found → optionally run one more discover+ingest cycle.
+5. Save summary to `.llm-wiki/outputs/run-YYYY-MM-DD.md` using the `write` tool.
+6. Report final summary.
 
 ### Scheduling
 
-If `--schedule daily` is used, use `schedule_prompt` to set up daily runs:
-
-```
-schedule_prompt action=add schedule="0 0 8 * * *" prompt="Run /wiki-run for the LLM Wiki"
-```
-
-If `--schedule weekly` is used:
+If `--schedule` is provided, call `wiki_watch(interval=<daily|weekly>)` to set up automatic updates.
 
-```
-schedule_prompt action=add schedule="0 0 9 * * 1" prompt="Run /wiki-run for the LLM Wiki"
-```
+If `--schedule hourly` is provided, call `wiki_watch(interval=hourly)`.

package/prompts/wiki-status.md

@@ -11,23 +11,6 @@ Show a quick overview of wiki health and statistics.
 
 ## Steps
 
-1. Count sources in `.llm-wiki/raw/` (recursive, respecting `.gitignore`)
-2. Count pages in `.llm-wiki/wiki/` (by type: entities, concepts, sources, syntheses, respecting `.gitignore`)
-3. Check `.llm-wiki/wiki/LOG.md` for last ingest, lint, and discover dates
-4. Check for orphan pages (zero inbound links)
-5. Read `.llm-wiki/.discoveries/gaps.json` for known gaps
-6. Report:
-
-```
-📊 LLM Wiki Status
-══════════════════
-Wiki Root: [topic1], [topic2]
-Mode: Personal | Company
-Sources: [N] files
-Wiki Pages: [N] total ([E] entities, [C] concepts, [S] sources, [Y] syntheses)
-Last Ingest: YYYY-MM-DD
-Last Lint: YYYY-MM-DD
-Orphans: [N]
-Knowledge Gaps: [N]
-Health: ✅ Good | ⚠️ Warning | 🔴 Needs Attention
-```
+1. Call `wiki_status()` to get the current wiki health report.
+2. Present the results to the user.
+3. If health shows warnings (orphans > 5, many gaps), suggest running `/wiki-lint` for a detailed analysis.

package/skills/llm-wiki/SKILL.md

@@ -1,6 +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: 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
@@ -55,39 +56,53 @@ 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          |
 
-## 🔄 Auto-Recall (New)
+## 🔄 Wiki Usage
 
-**The extension now automatically searches the wiki before every user turn.**
+### At Start — Call wiki_recall
 
-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
+**Call `wiki_recall` at the START of every task** to find relevant wiki pages:
 
-**This means the wiki works as an automatic second brain.**
-You don't need to remember to search — relevant knowledge is surfaced automatically.
+```
+wiki_recall(query="key terms from the user's request", max_results=5)
+```
+
+This searches both your **personal wiki** (`~/.llm-wiki/`) and the **project wiki** (`.llm-wiki/` in the current directory), merging results.
+
+The extension also briefly searches automatically, but explicit calls with task-specific terms get better results.
+
+### At End — Save Insights with wiki_retro
 
-### Manual recall for deeper searches
+After completing any meaningful task, call `wiki_retro` to save key insights:
+- Non-obvious bug fixes or workarounds
+- Architectural decisions and their rationale
+- Tool/library gotchas you discovered
+- Patterns worth remembering for future sessions
 
-If the auto-recall doesn't find enough context, call `wiki_recall` explicitly:
+**Do not wait for the user to ask.** Save insights proactively — one atomic insight per call.
 
 ```
-wiki_recall(query="specific terms...", max_results=10)
+wiki_retro(slug="kebab-case-slug", title="Brief descriptive title", body="Insight in your own words with [[wikilinks]]")
 ```
 
-This gives you more control over the search terms and returns content previews.
+### Deeper Searches
 
-### No Wiki Yet
+For thorough research, also use `wiki_search` to browse the full registry:
 
-If the extension injects a "No LLM Wiki found" hint, use `ask_user` to offer creating one:
+```
+wiki_search(query="broad topic")
+```
+
+### Auto-Bootstrap (One-Time)
 
-> "No LLM Wiki found in this directory. Would you like to create one? It gives you a linked knowledge base with automatic recall."
+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")
+```
 
-If the user agrees, call `wiki_bootstrap(topic="...", mode="personal")`. Suggest only once per session.
+This is a one-time step.
 
 ## Available Tools
 
@@ -95,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
@@ -120,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