@zosmaai/pi-llm-wiki 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-13
+
+### Added
+- **Wiki vault restructured under `.llm-wiki/`** (Issue #22, PR #23 by @arjun-zosma): All wiki content now lives in a single `.llm-wiki/` subdirectory — cleaner repo isolation, easier gitignore, zero directory name collisions.
+- **Backward compatibility**: Old vaults (`.wiki/config.json` sentinel) are auto-detected and continue to work. New vaults use `.llm-wiki/config.json`.
+- **`detectVaultFormat()`** utility: Returns `"new"`, `"legacy"`, or `"none"` for any directory.
+- **`resolveVaultPaths()`** utility: Auto-detects vault format and returns correct paths.
+- **`getLegacyVaultPaths()`** utility: Returns old-style paths for migration support.
+- **Migration script** (`scripts/migrate-llm-wiki.js`): One-time tool to move old vaults to new layout. Supports `--dry-run` and `--force` flags.
+- **5 new backward-compatibility tests**: Verify new format detection, legacy format detection, auto-resolution, and no-vault handling.
+
+### Changed
+- `resolveVaultRoot()` now checks for `.llm-wiki/config.json` first, then falls back to `.wiki/config.json`.
+- `getVaultPaths()` returns paths under `.llm-wiki/`:
+  - `raw/` → `.llm-wiki/raw/`, `wiki/` → `.llm-wiki/wiki/`, `meta/` → `.llm-wiki/meta/`
+  - `.wiki/` → `.llm-wiki/` (config directly in the dot-dir)
+  - `outputs/` → `.llm-wiki/outputs/`, `.discoveries/` → `.llm-wiki/.discoveries/`
+- `isProtectedPath()` now takes `VaultPaths` instead of `root` string.
+- `wiki_bootstrap` creates new `.llm-wiki/` layout by default.
+- MCP server updated with own copy of path detection logic.
+- All templates, prompts, documentation, and tests updated to reflect new layout.
+
+### Migration
+- Run `node scripts/migrate-llm-wiki.js` in your wiki root to migrate from the old layout.
+- Old `.wiki/` directory is preserved as a forwarding marker (`.wiki/MIGRATED_TO_LLM_WIKI.md`).
+- No data loss — all content is moved, nothing deleted.
+
 ## [0.6.0] - 2026-05-11
 
 ### Added

package/README.md

@@ -53,6 +53,9 @@ The result is a wiki that **compounds** as you capture sources, ask questions, a
 | 🩺 **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 |
+| 💾 **Auto-capture** | `wiki_retro` — save atomic insights from completed tasks with one call |
+| 🌐 **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 |
 | 🔧 **Configurable PDF extraction** | MarkItDown timeout via `WIKI_MARKITDOWN_TIMEOUT_MS` env var |
@@ -66,6 +69,8 @@ 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_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 |
 | `wiki_search` | Search the generated wiki registry |
@@ -104,11 +109,13 @@ Initialize an llm wiki here for AI research.
 This calls `wiki_bootstrap` and creates:
 
 ```
-raw/
-wiki/
-meta/
-.wiki/
-WIKI_SCHEMA.md
+.llm-wiki/
+├── config.json
+├── templates/
+├── raw/
+├── wiki/
+├── meta/
+└── WIKI_SCHEMA.md
 ```
 
 ### 2) Capture a source
@@ -128,7 +135,7 @@ Capture these notes into the wiki: ...pasted text...
 ### 3) Integrate the source
 
 1. Capture the source
-2. Read `wiki/sources/SRC-*.md`
+2. Read `.llm-wiki/wiki/sources/SRC-*.md`
 3. Update that source page
 4. Search for impacted canonical pages with `wiki_search`
 5. Create missing pages with `wiki_ensure_page`
@@ -153,45 +160,47 @@ Answer the question and file the result as an analysis page.
 
 ```
 my-wiki/
-├─ raw/
-│  └─ sources/
-│     └─ SRC-2026-05-11-001/
-│        ├─ manifest.json
-│        ├─ original/           # Original artifact
-│        ├─ extracted.md        # Normalized text
-│        └─ attachments/
-├─ wiki/
-│  ├─ sources/                  # Source pages (what each source says)
-│  ├─ concepts/                 # Concepts and recurring ideas
-│  ├─ entities/                 # People, orgs, products, papers, systems
-│  ├─ syntheses/                # Cross-source theses and tensions
-│  └─ analyses/                 # Durable filed answers from queries
-├─ meta/
-│  ├─ registry.json             # Auto-generated search index
-│  ├─ backlinks.json
-│  ├─ index.md
-│  ├─ events.jsonl              # Append-only event log
-│  ├─ log.md
-│  └─ lint-report.md
-├─ .wiki/
-│  ├─ config.json
-│  └─ templates/
-└─ WIKI_SCHEMA.md
+└─ .llm-wiki/
+   ├─ config.json               # Vault config
+   ├─ templates/                 # Page templates
+   ├─ raw/
+   │  └─ sources/
+   │     └─ SRC-2026-05-11-001/
+   │        ├─ manifest.json
+   │        ├─ original/           # Original artifact
+   │        ├─ extracted.md        # Normalized text
+   │        └─ attachments/
+   ├─ wiki/
+   │  ├─ sources/                  # Source pages (what each source says)
+   │  ├─ concepts/                 # Concepts and recurring ideas
+   │  ├─ entities/                 # People, orgs, products, papers, systems
+   │  ├─ syntheses/                # Cross-source theses and tensions
+   │  └─ analyses/                 # Durable filed answers from queries
+   ├─ meta/
+   │  ├─ registry.json             # Auto-generated search index
+   │  ├─ backlinks.json
+   │  ├─ index.md
+   │  ├─ events.jsonl              # Append-only event log
+   │  ├─ log.md
+   │  └─ lint-report.md
+   └─ WIKI_SCHEMA.md               # Operating manual
 ```
 
 ### Ownership Model
 
 | Path | Owner | Rule |
 |------|-------|------|
-| `raw/**` | Extension tools | Immutable after capture |
-| `wiki/**` | Model + user | Editable knowledge pages |
-| `meta/registry.json` | Extension | Generated |
-| `meta/backlinks.json` | Extension | Generated |
-| `meta/index.md` | Extension | Generated |
-| `meta/events.jsonl` | Extension / tool | Append-only |
-| `meta/log.md` | Extension | Generated from events |
-| `meta/lint-report.md` | Extension | Generated |
-| `WIKI_SCHEMA.md` | Human + explicit request | Operating manual |
+| Path | Owner | Rule |
+|------|-------|------|
+| `.llm-wiki/raw/**` | Extension tools | Immutable after capture |
+| `.llm-wiki/wiki/**` | Model + user | Editable knowledge pages |
+| `.llm-wiki/meta/registry.json` | Extension | Generated |
+| `.llm-wiki/meta/backlinks.json` | Extension | Generated |
+| `.llm-wiki/meta/index.md` | Extension | Generated |
+| `.llm-wiki/meta/events.jsonl` | Extension / tool | Append-only |
+| `.llm-wiki/meta/log.md` | Extension | Generated from events |
+| `.llm-wiki/meta/lint-report.md` | Extension | Generated |
+| `.llm-wiki/WIKI_SCHEMA.md` | Human + explicit request | Operating manual |
 
 ---
 
@@ -219,15 +228,15 @@ Stable source-page IDs keep provenance stable even if titles change.
 
 The extension **blocks** direct tool-call edits to:
 
-- `raw/**` — immutable source artifacts
-- `meta/registry.json`
-- `meta/backlinks.json`
-- `meta/events.jsonl`
-- `meta/index.md`
-- `meta/log.md`
-- `meta/lint-report.md`
+- `.llm-wiki/raw/**` — immutable source artifacts
+- `.llm-wiki/meta/registry.json`
+- `.llm-wiki/meta/backlinks.json`
+- `.llm-wiki/meta/events.jsonl`
+- `.llm-wiki/meta/index.md`
+- `.llm-wiki/meta/log.md`
+- `.llm-wiki/meta/lint-report.md`
 
-If the model directly edits `wiki/**` using Pi's built-in `write` or `edit` tools, the extension **automatically rebuilds** generated metadata at the end of the agent turn.
+If the model directly edits `.llm-wiki/wiki/**` using Pi's built-in `write` or `edit` tools, the extension **automatically rebuilds** generated metadata at the end of the agent turn.
 
 ---
 
@@ -236,7 +245,7 @@ If the model directly edits `wiki/**` using Pi's built-in `write` or `edit` tool
 Each captured source is stored as a structured packet:
 
 ```
-raw/sources/SRC-YYYY-MM-DD-NNN/
+.llm-wiki/raw/sources/SRC-YYYY-MM-DD-NNN/
 ├─ manifest.json     # Capture metadata (title, URL, format, timestamp)
 ├─ original/         # Original artifact (preserved as-is)
 ├─ extracted.md      # Normalized text (PDF→md, XML→md, JSON→md, etc.)
@@ -247,6 +256,34 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 ---
 
+## MCP Server
+
+Use the wiki from **any MCP-compatible tool** — Claude Code, Cursor, Windsurf, and others.
+
+The package ships a standalone MCP server exposing 5 wiki tools over stdio:
+
+| Tool | Description |
+|------|-------------|
+| `wiki_recall` | Search wiki for task-relevant pages |
+| `wiki_search` | Full registry search |
+| `wiki_status` | Wiki stats (page counts, type breakdown) |
+| `wiki_retro` | Save atomic insights |
+| `wiki_capture_source` | Capture text as a source packet |
+
+### Usage
+
+```bash
+# Auto-discovered by pi:
+pi install npm:@zosmaai/pi-llm-wiki
+
+# Standalone with any MCP client:
+WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/mcp/index.js
+```
+
+Set `WIKI_ROOT` to your wiki vault directory. If unset, the server auto-detects from the current working directory.
+
+---
+
 ## Skill Behavior
 
 The bundled `llm-wiki` skill teaches the model to:
@@ -266,10 +303,10 @@ The bundled `llm-wiki` skill teaches the model to:
 Four layers with clear ownership:
 
 ```
-raw/sources/SRC-*/     # Immutable source packets (extension-owned)
-wiki/                   # Editable knowledge pages (you + LLM)
-meta/                   # Auto-generated registry, backlinks, index, log
-.wiki/                  # Config and templates
+.llm-wiki/raw/sources/SRC-*/     # Immutable source packets (extension-owned)
+.llm-wiki/wiki/                   # Editable knowledge pages (you + LLM)
+.llm-wiki/meta/                   # Auto-generated registry, backlinks, index, log
+.llm-wiki/                        # Config and templates
 ```
 
 Read [docs/architecture.md](docs/architecture.md) for the full design document.

package/docs/architecture.md

@@ -4,43 +4,47 @@
 
 ```
 WIKI_ROOT/
-├── raw/sources/SRC-*/       # Immutable source packets (extension-owned)
-│   ├── manifest.json         # Capture metadata
-│   ├── original/             # Original artifact
-│   ├── extracted.md          # Normalized markdown
-│   └── attachments/          # Downloaded images, PDFs
-├── wiki/                     # Editable knowledge pages (you + LLM)
-│   ├── sources/              # One summary per source
-│   ├── entities/             # People, orgs, tools, products
-│   ├── concepts/             # Ideas, patterns, frameworks
-│   ├── syntheses/            # Cross-cutting analyses
-│   └── analyses/             # Durable query answers
-├── meta/                     # Auto-generated (extension-owned)
-│   ├── registry.json         # Master page catalog
-│   ├── backlinks.json        # Inbound link map
-│   ├── index.md              # Human-readable catalog
-│   ├── log.md                # Activity log
-│   └── events.jsonl          # Structured event stream
-└── .wiki/                    # Config and templates
-    ├── config.json
-    └── templates/
+└── .llm-wiki/                 # All wiki content under one dot-dir
+    ├── config.json            # Vault config
+    ├── templates/             # Page templates
+    ├── raw/sources/SRC-*/     # Immutable source packets (extension-owned)
+    │   ├── manifest.json      # Capture metadata
+    │   ├── original/          # Original artifact
+    │   ├── extracted.md       # Normalized markdown
+    │   └── attachments/       # Downloaded images, PDFs
+    ├── wiki/                  # Editable knowledge pages (you + LLM)
+    │   ├── sources/           # One summary per source
+    │   ├── entities/          # People, orgs, tools, products
+    │   ├── concepts/          # Ideas, patterns, frameworks
+    │   ├── syntheses/         # Cross-cutting analyses
+    │   └── analyses/          # Durable query answers
+    ├── meta/                  # Auto-generated (extension-owned)
+    │   ├── registry.json      # Master page catalog
+    │   ├── backlinks.json     # Inbound link map
+    │   ├── index.md           # Human-readable catalog
+    │   ├── log.md             # Activity log
+    │   └── events.jsonl       # Structured event stream
+    ├── outputs/               # Generated artifacts
+    └── .discoveries/          # Discovery tracking
 ```
 
 ## Ownership Rules
 
 | Path      | Owner                    | Rule                     |
 | --------- | ------------------------ | ------------------------ |
-| `raw/**`  | Extension                | Immutable after capture  |
-| `wiki/**` | Model + user             | Editable knowledge pages |
-| `meta/*`  | Extension                | Auto-generated           |
-| `.wiki/*` | Human + explicit request | Operating rules          |
+| Path                  | Owner                    | Rule                     |
+| --------------------- | ------------------------ | ------------------------ |
+| `.llm-wiki/raw/**`    | Extension                | Immutable after capture  |
+| `.llm-wiki/wiki/**`   | Model + user             | Editable knowledge pages |
+| `.llm-wiki/meta/**`   | Extension                | Auto-generated           |
+| `.llm-wiki/` | Human + explicit request | Operating rules          |
 
 ## Source Packet Format
 
 Each captured source becomes a packet:
 
 ```
-raw/sources/SRC-YYYY-MM-DD-NNN/
+.llm-wiki/raw/sources/SRC-YYYY-MM-DD-NNN/
   manifest.json
   original/
   extracted.md
@@ -62,4 +66,4 @@ raw/sources/SRC-YYYY-MM-DD-NNN/
 
 ## Guardrails
 
-The extension blocks direct edits to `raw/**` and `meta/**`. Metadata rebuilds automatically after `wiki/**` edits.
+The extension blocks direct edits to `.llm-wiki/raw/**` and `.llm-wiki/meta/**`. Metadata rebuilds automatically after `.llm-wiki/wiki/**` edits.

package/docs/commands.md

@@ -36,7 +36,7 @@ The extension registers 10 tools the LLM can call directly:
 
 1. `wiki_capture_source(url="...")` — creates packet + skeleton
 2. `wiki_ingest()` — get batch of sources needing synthesis
-3. Read `raw/sources/SRC-*/extracted.md`
+3. Read `.llm-wiki/raw/sources/SRC-*/extracted.md`
 4. Update skeleton source page with summary, entities, concepts
 5. `wiki_ensure_page(type="entity", title="...")` for each entity
 6. Add `[[wikilinks]]` between related pages

package/docs/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-Wiki configuration lives in `.wiki/config.json`.
+Wiki configuration lives in `.llm-wiki/config.json`.
 
 ## Modes
 

package/docs/obsidian.md

@@ -2,9 +2,9 @@
 
 ## Setup
 
-1. Open `wiki/` as an Obsidian vault
-2. The extension generates `meta/index.md` as a browsable catalog
-3. `meta/backlinks.json` is available for graph plugins
+1. Open `.llm-wiki/wiki/` as an Obsidian vault
+2. The extension generates `.llm-wiki/meta/index.md` as a browsable catalog
+3. `.llm-wiki/meta/backlinks.json` is available for graph plugins
 
 ## Recommended Plugins
 
@@ -14,8 +14,8 @@
 
 ## Web Clipper
 
-Use [Obsidian Web Clipper](https://obsidian.md/clipper) to save articles directly into `raw/articles/`.
+Use [Obsidian Web Clipper](https://obsidian.md/clipper) to save articles directly into `.llm-wiki/raw/articles/`.
 
 ## Dataview Dashboard
 
-The extension creates `meta/index.md` with page listings. For custom dashboards, use Dataview queries against frontmatter fields like `type`, `domain`, `category`, `sources`.
+The extension creates `.llm-wiki/meta/index.md` with page listings. For custom dashboards, use Dataview queries against frontmatter fields like `type`, `domain`, `category`, `sources`.

package/extensions/llm-wiki/index.ts

@@ -16,7 +16,7 @@ import {
   registerWikiStatus,
   registerWikiWatch,
 } from "./lib/tools.js";
-import { getVaultPaths, resolveVaultRoot } from "./lib/utils.js";
+import { resolveVaultPaths } from "./lib/utils.js";
 
 /**
  * @zosmaai/pi-llm-wiki — LLM Wiki extension for Pi
@@ -58,12 +58,11 @@ export default function (pi: ExtensionAPI) {
   // Before each agent turn, search the wiki for pages relevant
   // to the user's prompt and inject them as system context.
   pi.on("before_agent_start", async (event, _ctx) => {
-    const root = resolveVaultRoot(process.cwd());
-    if (!existsSync(join(root, ".wiki", "config.json"))) {
+    const paths = resolveVaultPaths(process.cwd());
+    if (!existsSync(join(paths.dotWiki, "config.json"))) {
       return; // No wiki vault — nothing to recall
     }
 
-    const paths = getVaultPaths(root);
     const prompt = event.prompt || "";
     if (!prompt.trim()) return;
 

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

@@ -1,7 +1,7 @@
 import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { rebuildMetadataLight } from "./metadata.js";
-import { isProtectedPath, resolveVaultRoot } from "./utils.js";
+import { isProtectedPath, resolveVaultPaths } from "./utils.js";
 
 /**
  * Guardrails and auto-rebuild hooks for the LLM Wiki extension.
@@ -15,8 +15,8 @@ export function installGuardrails(pi: ExtensionAPI): void {
   pi.on("tool_call", async (event) => {
     if (isToolCallEventType("write", event)) {
       const path = event.input.path as string;
-      const root = resolveVaultRoot(process.cwd());
-      const check = isProtectedPath(path, root);
+      const paths = resolveVaultPaths(process.cwd());
+      const check = isProtectedPath(path, paths);
       if (check.protected) {
         return { block: true, reason: check.reason };
       }
@@ -24,8 +24,8 @@ export function installGuardrails(pi: ExtensionAPI): void {
 
     if (isToolCallEventType("edit", event)) {
       const path = event.input.path as string;
-      const root = resolveVaultRoot(process.cwd());
-      const check = isProtectedPath(path, root);
+      const paths = resolveVaultPaths(process.cwd());
+      const check = isProtectedPath(path, paths);
       if (check.protected) {
         return { block: true, reason: check.reason };
       }
@@ -36,8 +36,8 @@ export function installGuardrails(pi: ExtensionAPI): void {
   pi.on("tool_result", async (event) => {
     if (event.toolName === "write" || event.toolName === "edit") {
       const path = event.input.path as string;
-      const root = resolveVaultRoot(process.cwd());
-      const wikiPath = `${root}/wiki/`;
+      const paths = resolveVaultPaths(process.cwd());
+      const wikiPath = `${paths.wiki}/`;
       if (path?.startsWith(wikiPath)) {
         pendingRebuild = true;
       }
@@ -49,17 +49,7 @@ export function installGuardrails(pi: ExtensionAPI): void {
     if (pendingRebuild) {
       pendingRebuild = false;
       try {
-        const root = resolveVaultRoot(process.cwd());
-        const paths = {
-          root,
-          raw: `${root}/raw`,
-          rawSources: `${root}/raw/sources`,
-          wiki: `${root}/wiki`,
-          meta: `${root}/meta`,
-          dotWiki: `${root}/.wiki`,
-          outputs: `${root}/outputs`,
-          discoveries: `${root}/.discoveries`,
-        };
+        const paths = resolveVaultPaths(process.cwd());
         rebuildMetadataLight(paths);
       } catch {
         // Silently fail — metadata rebuild is best-effort

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

@@ -3,7 +3,7 @@ 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, getVaultPaths, readJson, readText, resolveVaultRoot } from "./utils.js";
+import { type VaultPaths, readJson, resolveVaultPaths } from "./utils.js";
 
 // ─── Public API ────────────────────────────────────────
 
@@ -148,10 +148,9 @@ export function registerWikiRecall(pi: ExtensionAPI): void {
       ),
     }),
     async execute(_toolCallId, params) {
-      const root = resolveVaultRoot(process.cwd());
-      const paths = getVaultPaths(root);
+      const paths = resolveVaultPaths(process.cwd());
 
-      if (!existsSync(join(root, ".wiki", "config.json"))) {
+      if (!existsSync(join(paths.dotWiki, "config.json"))) {
         return {
           content: [
             {

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

@@ -3,13 +3,7 @@ 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,
-  getVaultPaths,
-  nextSourceId,
-  resolveVaultRoot,
-} from "./utils.js";
+import { type VaultPaths, fmtDate, nextSourceId, resolveVaultPaths } from "./utils.js";
 
 // ─── Public API ────────────────────────────────────────
 
@@ -158,10 +152,9 @@ export function registerWikiRetro(pi: ExtensionAPI): void {
       ),
     }),
     async execute(_toolCallId, params) {
-      const root = resolveVaultRoot(process.cwd());
-      const paths = getVaultPaths(root);
+      const paths = resolveVaultPaths(process.cwd());
 
-      if (!existsSync(join(root, ".wiki", "config.json"))) {
+      if (!existsSync(join(paths.dotWiki, "config.json"))) {
         return {
           content: [
             {

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

@@ -13,13 +13,14 @@ import {
 import { captureFile, captureText, captureUrl } from "./source-packet.js";
 import {
   type VaultPaths,
+  detectVaultFormat,
   ensureVaultStructure,
   extractWikilinks,
   findWikiPages,
   fmtDate,
   getVaultPaths,
   readJson,
-  resolveVaultRoot,
+  resolveVaultPaths,
   writeJson,
 } from "./utils.js";
 
@@ -28,12 +29,11 @@ import {
  */
 
 function getPaths(cwd = process.cwd()): VaultPaths {
-  const root = resolveVaultRoot(cwd);
-  return getVaultPaths(root);
+  return resolveVaultPaths(cwd);
 }
 
 function requireVault(paths: VaultPaths): { ok: true } | { ok: false; reason: string } {
-  if (!existsSync(join(paths.root, ".wiki", "config.json"))) {
+  if (detectVaultFormat(paths.root) === "none") {
     return { ok: false, reason: `No wiki found at ${paths.root}. Run wiki_bootstrap first.` };
   }
   return { ok: true };
@@ -83,7 +83,7 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
         "| raw/** | extension | immutable after capture |",
         "| wiki/** | model + user | editable knowledge pages |",
         "| meta/* | extension | auto-generated |",
-        "| .wiki/* | human + explicit request | operating rules |",
+        "| . | human + explicit request | operating rules |",
         "",
         "## Source Packet Format",
         "",
@@ -109,7 +109,7 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
         "- Citation: [[sources/SRC-YYYY-MM-DD-NNN]]",
         "",
       ].join("\n");
-      writeFileSync(join(paths.root, "WIKI_SCHEMA.md"), schema, "utf-8");
+      writeFileSync(join(paths.dotWiki, "WIKI_SCHEMA.md"), schema, "utf-8");
 
       rebuildMetadata(paths);
       appendEvent(paths, { kind: "bootstrap", topic: params.topic, mode });
@@ -122,10 +122,11 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
               `✅ Wiki bootstrapped at \`${paths.root}\``,
               "",
               "**Structure:**",
-              "- raw/sources/ — immutable source packets",
-              "- wiki/ — editable knowledge pages",
-              "- meta/ — auto-generated metadata",
-              "- .wiki/ — config and templates",
+              "- .llm-wiki/raw/sources/ — immutable source packets",
+              "- .llm-wiki/wiki/ — editable knowledge pages",
+              "- .llm-wiki/meta/ — auto-generated metadata",
+              "- .llm-wiki/ — config and templates",
+              "- .llm-wiki/WIKI_SCHEMA.md — operating rules",
               "",
               "Next: Use wiki_capture_source to add your first source.",
             ].join("\n"),

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

@@ -17,24 +17,53 @@ export interface VaultPaths {
   discoveries: string;
 }
 
+/** Detect whether a vault root uses new (.llm-wiki) or legacy (.wiki) layout. */
+export type VaultFormat = "new" | "legacy" | "none";
+
+/**
+ * Detect the vault format at a given directory.
+ * Returns "new" if .llm-wiki/config.json exists,
+ * "legacy" if .wiki/config.json exists,
+ * "none" otherwise.
+ */
+export function detectVaultFormat(dir: string): VaultFormat {
+  if (existsSync(join(dir, ".llm-wiki", "config.json"))) return "new";
+  if (existsSync(join(dir, ".wiki", "config.json"))) return "legacy";
+  return "none";
+}
+
 /** Resolve vault root from cwd or find nearest wiki root. */
 export function resolveVaultRoot(cwd: string): string {
-  // If cwd has .wiki/config.json, it's the root
-  if (existsSync(join(cwd, ".wiki", "config.json"))) return cwd;
+  // Check for any vault format at cwd
+  if (detectVaultFormat(cwd) !== "none") return cwd;
 
-  // Walk up looking for .wiki/config.json
+  // Walk up looking for a vault sentinel (new or legacy)
   let dir = cwd;
   while (dir !== dirname(dir)) {
-    if (existsSync(join(dir, ".wiki", "config.json"))) return dir;
     dir = dirname(dir);
+    if (detectVaultFormat(dir) !== "none") return dir;
   }
 
   // Fallback: cwd itself
   return cwd;
 }
 
-/** Get all vault paths. */
+/** Get all vault paths for the new (.llm-wiki) layout. */
 export function getVaultPaths(root: string): VaultPaths {
+  return {
+    root,
+    raw: join(root, ".llm-wiki", "raw"),
+    rawSources: join(root, ".llm-wiki", "raw", "sources"),
+    wiki: join(root, ".llm-wiki", "wiki"),
+    meta: join(root, ".llm-wiki", "meta"),
+    dotWiki: join(root, ".llm-wiki"),
+    outputs: join(root, ".llm-wiki", "outputs"),
+    discoveries: join(root, ".llm-wiki", ".discoveries"),
+  };
+}
+
+/** Get all vault paths for the legacy (.wiki) layout. */
+export function getLegacyVaultPaths(root: string): VaultPaths {
   return {
     root,
     raw: join(root, "raw"),
@@ -47,6 +76,17 @@ export function getVaultPaths(root: string): VaultPaths {
   };
 }
 
+/**
+ * Resolve vault paths, auto-detecting new vs legacy layout.
+ * This is the main entry point: use this instead of resolveVaultRoot + getVaultPaths.
+ */
+export function resolveVaultPaths(cwd: string): VaultPaths {
+  const root = resolveVaultRoot(cwd);
+  const format = detectVaultFormat(root);
+  if (format === "legacy") return getLegacyVaultPaths(root);
+  return getVaultPaths(root);
+}
+
 /** Ensure all vault directories exist. */
 export function ensureVaultStructure(paths: VaultPaths): void {
   const dirs = [
@@ -199,10 +239,10 @@ export async function exec(
 /** Check if a path is inside a protected directory. */
 export function isProtectedPath(
   absPath: string,
-  root: string,
+  paths: VaultPaths,
 ): { protected: boolean; reason?: string } {
-  const rawPath = resolve(root, "raw");
-  const metaPath = resolve(root, "meta");
+  const rawPath = resolve(paths.raw);
+  const metaPath = resolve(paths.meta);
   const norm = resolve(absPath);
 
   if (norm.startsWith(`${rawPath}/`) || norm === rawPath) {

package/mcp/index.ts

@@ -22,33 +22,72 @@ import * as z from "zod/v4";
 
 interface VaultPaths {
   root: string;
+  raw: string;
   rawSources: string;
   wiki: string;
   meta: string;
+  dotWiki: string;
+  outputs: string;
+  discoveries: string;
+}
+
+/** Detect vault format at a directory. */
+function detectFormat(dir: string): "new" | "legacy" | "none" {
+  if (existsSync(join(dir, ".llm-wiki", "config.json"))) return "new";
+  if (existsSync(join(dir, ".wiki", "config.json"))) return "legacy";
+  return "none";
 }
 
 function resolveVaultRoot(cwd: string): string | null {
-  if (existsSync(join(cwd, ".wiki", "config.json"))) return cwd;
+  // Check cwd first
+  if (detectFormat(cwd) !== "none") return cwd;
+
+  // Walk up
   const parts = cwd.split("/");
   for (let i = parts.length - 1; i >= 0; i--) {
     const dir = parts.slice(0, i + 1).join("/") || "/";
-    if (existsSync(join(dir, ".wiki", "config.json"))) return dir;
+    if (detectFormat(dir) !== "none") return dir;
   }
   return null;
 }
 
 function getPaths(): VaultPaths {
-  const root = process.env.WIKI_ROOT || resolveVaultRoot(process.cwd()) || process.cwd();
+  const detectedRoot = resolveVaultRoot(process.cwd());
+  const root = process.env.WIKI_ROOT || detectedRoot || process.cwd();
+  const format = process.env.WIKI_ROOT
+    ? detectFormat(root) // Use format detection even with explicit WIKI_ROOT
+    : detectedRoot
+      ? detectFormat(root)
+      : "none";
+
+  if (format === "legacy") {
+    return {
+      root,
+      raw: join(root, "raw"),
+      rawSources: join(root, "raw", "sources"),
+      wiki: join(root, "wiki"),
+      meta: join(root, "meta"),
+      dotWiki: join(root, ".wiki"),
+      outputs: join(root, "outputs"),
+      discoveries: join(root, ".discoveries"),
+    };
+  }
+
   return {
     root,
-    rawSources: join(root, "raw", "sources"),
-    wiki: join(root, "wiki"),
-    meta: join(root, "meta"),
+    raw: join(root, ".llm-wiki", "raw"),
+    rawSources: join(root, ".llm-wiki", "raw", "sources"),
+    wiki: join(root, ".llm-wiki", "wiki"),
+    meta: join(root, ".llm-wiki", "meta"),
+    dotWiki: join(root, ".llm-wiki"),
+    outputs: join(root, ".llm-wiki", "outputs"),
+    discoveries: join(root, ".llm-wiki", ".discoveries"),
   };
 }
 
 function hasVault(): boolean {
-  return existsSync(join(getPaths().root, ".wiki", "config.json"));
+  const paths = getPaths();
+  return existsSync(join(paths.dotWiki, "config.json"));
 }
 
 // ─── Helpers ────────────────────────────────────────────
@@ -259,7 +298,7 @@ server.registerTool(
       pages: {},
     });
 
-    const config = readJson<Record<string, unknown>>(join(paths.root, ".wiki", "config.json"), {});
+    const config = readJson<Record<string, unknown>>(join(paths.dotWiki, "config.json"), {});
 
     const byType: Record<string, number> = {};
     for (const entry of Object.values(registry.pages)) {
@@ -331,14 +370,7 @@ server.registerTool(
       ) => { sourceId: string; packetPath: string; sourcePagePath: string };
     };
 
-    const vaultPaths = {
-      ...getPaths(),
-      raw: join(getPaths().root, "raw"),
-      dotWiki: join(getPaths().root, ".wiki"),
-      outputs: join(getPaths().root, "outputs"),
-      discoveries: join(getPaths().root, ".discoveries"),
-    };
-
+    const vaultPaths = getPaths();
     const result = saveInsight(vaultPaths, slug, title, body, category);
 
     return {
@@ -378,18 +410,10 @@ server.registerTool(
       };
     }
 
-    const vaultPaths = {
-      ...getPaths(),
-      raw: join(getPaths().root, "raw"),
-      dotWiki: join(getPaths().root, ".wiki"),
-      outputs: join(getPaths().root, "outputs"),
-      discoveries: join(getPaths().root, ".discoveries"),
-    };
-
+    const vaultPaths = getPaths();
     let result: { sourceId: string };
 
     if (urlParam) {
-      // For MCP, use simple curl-based capture
       const { captureUrl } = (await import("../extensions/llm-wiki/lib/source-packet.js")) as {
         captureUrl: (
           pi: never,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.6.0",
+  "version": "0.6.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-discover.md

@@ -17,17 +17,17 @@ Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first. Also read `conf
 
 ## Steps
 
-1. Read `config.yaml` → extract topics, keywords, feeds
-2. Read `.discoveries/gaps.json` → knowledge gaps to fill
-3. Read `.discoveries/history.json` → already-fetched URLs
+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 `.discoveries/gaps.json`
+   - 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 `raw/articles/YYYY-MM-DD-slug.md` with frontmatter (title, url, discovered, topic)
-6. Update `.discoveries/history.json`
+   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.

package/prompts/wiki-ingest.md

@@ -7,7 +7,7 @@ topLevelCli: true
 
 # /wiki-ingest
 
-Process new files in `raw/` and integrate them into the wiki.
+Process new files in `.llm-wiki/raw/` and integrate them into the wiki.
 
 ## User Arguments
 
@@ -17,18 +17,18 @@ Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand th
 
 ## Steps
 
-1. Read `config.yaml` and `.discoveries/history.json`
-2. If a specific path is given (e.g., `/wiki-ingest raw/articles/my-file.md`), process just that file
-3. If no path given, scan all files in `raw/` and find ones not in history
+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 `wiki/sources/`, `wiki/entities/`, `wiki/concepts/`
+   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 `wiki/INDEX.md` with all new/updated pages
-6. Append to `wiki/LOG.md`
-7. Update `.discoveries/history.json`
+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.

package/prompts/wiki-init.md

@@ -19,16 +19,16 @@ Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` (or wherever the skill
 
 1. Ask the user for the wiki topic and mode (`personal` or `company`)
 2. Create the directory structure:
-   - `raw/articles/`, `raw/papers/`, `raw/notes/`, `raw/assets/`
-   - `wiki/entities/`, `wiki/concepts/`, `wiki/sources/`, `wiki/syntheses/`, `wiki/changes/`
-   - `outputs/`
-   - `.discoveries/`
-3. Create `config.yaml` with the topic, mode, and default settings
-4. Create `wiki/INDEX.md` with section headings organized by page type
-5. Create `wiki/LOG.md` with initial entry
-6. Create `wiki/DASHBOARD.md` with Dataview queries for Obsidian
-7. Create `.gitignore` to exclude `outputs/` from version control if desired
+   - `.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 `raw/` and run `/wiki-ingest`"
+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 `wiki/decisions/` folder.
+If `--mode company`, add the `change_detection: true` flag to config.yaml and add a `.llm-wiki/wiki/decisions/` folder.

package/prompts/wiki-lint.md

@@ -17,17 +17,17 @@ Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand th
 
 ## Steps
 
-1. Scan all files in `wiki/`
+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 `raw/` files that don't exist
+   - **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 → `outputs/lint-YYYY-MM-DD.md`
-5. Update `.discoveries/gaps.json`
-6. Append to `wiki/LOG.md`
+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

package/prompts/wiki-status.md

@@ -11,11 +11,11 @@ Show a quick overview of wiki health and statistics.
 
 ## Steps
 
-1. Count sources in `raw/` (recursive)
-2. Count pages in `wiki/` (by type: entities, concepts, sources, syntheses)
-3. Check `wiki/LOG.md` for last ingest, lint, and discover dates
+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 `.discoveries/gaps.json` for known gaps
+5. Read `.llm-wiki/.discoveries/gaps.json` for known gaps
 6. Report:
 
 ```

package/skills/llm-wiki/SKILL.md

@@ -11,26 +11,28 @@ You are a disciplined wiki maintainer. The extension handles all mechanical work
 
 ```
 WIKI_ROOT/
-├── raw/sources/SRC-*/       # Immutable source packets (extension-owned)
-│   ├── manifest.json
-│   ├── original/
-│   ├── extracted.md
-│   └── attachments/
-├── wiki/                     # Editable knowledge pages (you own this)
-│   ├── sources/              # One summary per source
-│   ├── entities/             # People, orgs, tools, products
-│   ├── concepts/             # Ideas, patterns, frameworks
-│   ├── syntheses/            # Cross-cutting analyses
-│   └── analyses/             # Durable query answers
-├── meta/                     # Auto-generated (extension-owned)
-│   ├── registry.json         # Master page catalog
-│   ├── backlinks.json        # Inbound link map
-│   ├── index.md              # Human-readable catalog
-│   ├── log.md                # Activity log
-│   └── events.jsonl          # Structured event stream
-└── .wiki/                    # Config and templates
-    ├── config.json
-    └── templates/
+└── .llm-wiki/                 # All wiki content (one dot-dir)
+    ├── config.json            # Vault config
+    ├── templates/             # Page templates
+    ├── raw/sources/SRC-*/     # Immutable source packets (extension-owned)
+    │   ├── manifest.json
+    │   ├── original/
+    │   ├── extracted.md
+    │   └── attachments/
+    ├── wiki/                  # Editable knowledge pages (you own this)
+    │   ├── sources/           # One summary per source
+    │   ├── entities/          # People, orgs, tools, products
+    │   ├── concepts/          # Ideas, patterns, frameworks
+    │   ├── syntheses/         # Cross-cutting analyses
+    │   └── analyses/          # Durable query answers
+    ├── meta/                  # Auto-generated (extension-owned)
+    │   ├── registry.json      # Master page catalog
+    │   ├── backlinks.json     # Inbound link map
+    │   ├── index.md           # Human-readable catalog
+    │   ├── log.md             # Activity log
+    │   └── events.jsonl       # Structured event stream
+    ├── outputs/               # Generated artifacts
+    └── .discoveries/          # Discovery tracking
 ```
 
 ## Golden Rules

package/skills/llm-wiki/templates/pages/source.md

@@ -1,7 +1,7 @@
 ---
 type: source
 format: article # article | paper | note | video | podcast | slack | email
-raw_path: raw/articles/filename.md
+raw_path: .llm-wiki/raw/articles/filename.md
 ingested: YYYY-MM-DD
 topics:
   - topic-name
@@ -42,4 +42,4 @@ topics:
 
 ## Source
 
-- [raw/articles/filename.md](../raw/articles/filename.md)
+- [.llm-wiki/raw/articles/filename.md](../.llm-wiki/raw/articles/filename.md)