@zosmaai/pi-llm-wiki 0.7.4 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+### Fixed
+- **Personal wiki created at doubled path `~/.llm-wiki/.llm-wiki/…`**: `getPersonalWikiRoot()` returned the dot-dir itself (`~/.llm-wiki`) while `getVaultPaths()` then appended another `.llm-wiki/` segment, so the personal vault was written to `~/.llm-wiki/.llm-wiki/wiki/…`. Fixed by aligning `getPersonalWikiRoot()` with the same "root = parent of `.llm-wiki/`" contract used by project vaults. `WIKI_HOME` continues to override the parent.
+
+### Added
+- **`migrateDoubledPersonalVault()`** helper (`extensions/llm-wiki/lib/utils.ts`): Idempotent, in-place flatten of any vault that was already written to the broken doubled layout. Moves entries from `<root>/.llm-wiki/.llm-wiki/*` up to `<root>/.llm-wiki/*`, preserves outer entries on collision, removes the inner dir only when fully drained. Returns `null` when the layout is already correct, so it is safe to call on every session start.
+- **Auto-migration on `session_start`**: The extension now runs `migrateDoubledPersonalVault()` on the personal wiki at every session start. Existing broken vaults are flattened the next time the user opens or reloads pi — no manual step required. A one-line status message is shown when a flatten actually happens; otherwise the check is silent.
+- **`scripts/migrate-llm-wiki.js --fix-doubled`** flag: Manual recovery for arbitrary roots (`--fix-doubled ~/`, `--fix-doubled /some/project`). Supports `--dry-run` and `--force`.
+- **9 regression tests** (`test/personal-wiki-paths.test.ts`): pin `getPersonalWikiRoot()` to the parent-of-dotdir contract, exercise `WIKI_HOME`, and verify the migration helper across no-op, idempotent, and collision paths.
+
 ## [0.7.0] - 2026-05-13
 
 ### Added

package/README.md

@@ -120,6 +120,7 @@ The result is a wiki that **compounds** as you capture sources, ask questions, a
 | `/wiki-status` | Show a concise operational summary |
 | `/wiki-digest [--period daily\|weekly]` | Generate a digest of recent activity |
 | `/wiki-retro` | Save atomic insights from completed tasks |
+| `/wiki-req <concept>` | Decompose a concept into atomic, traceable requirement pages |
 
 ---
 

package/docs/api.md

@@ -1,105 +1,353 @@
 # API Reference
 
-## Extension Tools
+All 13 tools registered by the extension. Parameters marked `?` are optional.
 
-### wiki_bootstrap
+---
 
-Initialize a new LLM Wiki vault.
+## wiki_bootstrap
+
+Initialize a new LLM Wiki vault with the 4-layer architecture. Creates config, templates, schema,
+and metadata scaffolding.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `topic` | `string` | ✅ | Main topic of the wiki |
+| `mode` | `string` | — | `"personal"` or `"company"` (default: `"personal"`) |
+| `root` | `string` | — | Root directory to bootstrap in (default: current working directory) |
+
+**Returns**
 
 ```
-wiki_bootstrap(topic: string, mode?: "personal" | "company", root?: string)
+details: { root: string, mode: string, topic: string }
 ```
 
-### wiki_capture_source
+Confirmation text includes the vault path, directory layout, and a prompt to capture the first source.
+
+---
+
+## wiki_capture_source
 
-Capture a URL, file, or text into an immutable source packet.
+Capture a URL, local file, or pasted text into an immutable source packet and skeleton source page.
+Provide exactly one of `url`, `file_path`, or `text`.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` | — | URL to fetch and capture |
+| `file_path` | `string` | — | Absolute or relative path to a local file (PDF, md, txt, html, XML, JSON) |
+| `text` | `string` | — | Pasted text content to capture directly |
+| `title` | `string` | — | Title override (used for `text` captures; inferred from URL/file otherwise) |
+
+**Returns**
 
 ```
-wiki_capture_source(
-  inputType: "url" | "file" | "text",
-  value: string,
-  title?: string,
-  kind?: string,
-  tags?: string[],
-  createSourcePage?: boolean
-)
+details: {
+  sourceId: string,          // e.g. "SRC-2026-06-03-001"
+  packetPath: string,        // path to raw/sources/SRC-.../
+  sourcePagePath: string,    // path to wiki/sources/SRC-....md (skeleton)
+  extractedPreview: string   // first 300 chars of extracted content
+}
 ```
 
-### wiki_ingest
+Errors with `isError: true` if no vault exists or no source input is provided.
+
+---
+
+## wiki_ingest
+
+Return a batch of uningested source packets for the LLM to synthesize. Does not write anything
+itself — the model reads the returned extracted content, fills in the skeleton source page,
+and creates entity/concept pages.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `source_id` | `string` | — | Process a specific source ID only; leave empty to get the next unprocessed batch |
+| `batch_size` | `number` | — | Max sources to return (default: `3`, max: `5`) |
+
+**Returns**
+
+```
+details: {
+  batch: string[],    // source IDs in this batch, e.g. ["SRC-2026-06-03-001"]
+  remaining: number   // sources still waiting after this batch
+}
+```
+
+Each batch entry includes the source title, char count, and the path to read (`raw/sources/{id}/extracted.md`).
+Returns a "all sources ingested" message with `{ ingested, total }` when nothing is pending.
+
+---
+
+## wiki_ensure_page
+
+Resolve or safely create a canonical wiki page. Returns immediately if the page already exists
+(no overwrite). Uses a built-in template when `content` is not provided.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `type` | `string` | ✅ | Page type: `"entity"`, `"concept"`, `"synthesis"`, `"analysis"`, or `"requirement"` |
+| `title` | `string` | ✅ | Human-readable page title; auto-slugified to a kebab-case filename |
+| `content` | `string` | — | Full markdown content for the page; if omitted, the type-appropriate template is used |
+
+**Returns**
+
+```
+details: { path: string, created: boolean }
+```
+
+`created: false` means the page already existed and was not modified.
+
+---
+
+## wiki_recall
+
+Search both the personal (`~/.llm-wiki/`) and project (`.llm-wiki/`) vaults for pages relevant to
+a query. Uses chunk-level scoring, weighted field matching, and pseudo-relevance feedback. Also
+called automatically before every agent turn.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✅ | Search query — use the user's full request or key terms |
+| `max_results` | `number` | — | Maximum pages to return (default: `5`, max: `10`) |
+
+**Returns**
+
+```
+details: {
+  query: string,
+  matches: Array<{
+    id: string,           // folder-qualified page ID, e.g. "concepts/rag"
+    title: string,
+    type: string,         // "source" | "entity" | "concept" | "synthesis" | "analysis"
+    preview: string,      // best-matching chunk or page intro (~200 chars)
+    path: string,         // absolute filesystem path to the .md file
+    score: number,        // relevance score (higher = better)
+    vaultLabel?: string   // "📓 personal" when result is from the personal vault
+  }>
+}
+```
+
+Returns empty `matches: []` with a hint to use `wiki_retro` when the wiki has no matching pages.
+
+---
+
+## wiki_search
 
-Get a batch of sources needing synthesis.
+Exact keyword search across the generated registry. Faster and simpler than `wiki_recall` — no
+scoring, no PRF, no vault layering. Use for lookups when you already know what you're looking for.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✅ | Search term matched against page IDs, titles, and types |
+| `type` | `string` | — | Filter results to a specific page type (e.g. `"concept"`, `"entity"`) |
+
+**Returns**
 
 ```
-wiki_ingest(batch_size?: number)
+details: {
+  query: string,
+  matches: Array<{ id: string, title: string, type: string }>
+}
 ```
 
-### wiki_ensure_page
+---
+
+## wiki_retro
+
+Save an atomic insight from a completed task as a single lightweight markdown file in
+`wiki/sources/`. Does not create a full source packet. Rebuilds metadata immediately so the
+insight is searchable in the same session.
+
+**Parameters**
 
-Create or resolve a canonical page.
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `slug` | `string` | ✅ | Unique kebab-case identifier (e.g. `"jwt-revocation-pattern"`). Used as the filename and for lookups. |
+| `title` | `string` | ✅ | Short descriptive title, 60 chars max. Noun phrase, not a sentence. |
+| `body` | `string` | ✅ | Markdown content explaining what was learned. Include `[[wikilinks]]` to related pages. |
+| `category` | `string` | — | Optional grouping label (e.g. `"frontend"`, `"architecture"`, `"devops"`, `"bugfix"`) |
+
+**Returns**
 
 ```
-wiki_ensure_page(
-  type: "concept" | "entity" | "synthesis" | "analysis",
-  title: string,
-  aliases?: string[],
-  tags?: string[],
-  summary?: string,
-  createIfMissing?: boolean
-)
+details: { slug: string, title: string, category: string | null }
 ```
 
-### wiki_search
+---
+
+## wiki_observe
+
+Record a timestamped, relevance-rated observation during a session. Saved to `wiki/sources/` with
+`status: observation`. Immediately searchable via `wiki_recall`. Intended for mid-session capture;
+use `wiki_retro` for end-of-task summaries.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `title` | `string` | ✅ | Short descriptive title, ≤80 chars. Noun phrase, not a sentence. |
+| `content` | `string` | ✅ | Plain prose: what happened, was decided, or was learned. Preserve specifics (file paths, function names, error messages, numbers). |
+| `relevance` | `"low" \| "medium" \| "high" \| "critical"` | ✅ | Retention priority. `low` = routine; `medium` = task context; `high` = non-trivial decisions; `critical` = persistent identity/preference or completed work that must not be redone. |
+| `tags` | `string` | — | Space-separated tags for categorisation (e.g. `"auth backend migration"`) |
+| `source_context` | `string` | — | What was being worked on (e.g. `"Adding authentication module"`) |
 
-Search the wiki registry.
+**Returns**
 
 ```
-wiki_search(query: string, type?: string, limit?: number)
+details: { slug: string, title: string, relevance: string, tags: string | null }
 ```
 
-### wiki_lint
+The slug is auto-generated as `obs-YYYY-MM-DD-{title-slug}`.
 
-Health check the wiki.
+---
+
+## wiki_lint
+
+Deterministic health check of the wiki. Scans for orphan pages (no inbound links), missing pages
+(linked but not created), and contradiction markers. Optionally auto-creates stub pages for
+knowledge gaps cited in two or more pages.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `auto_fix` | `boolean` | — | When `true`, auto-creates stub concept pages for gaps mentioned in ≥2 pages (default: `false`) |
+
+**Returns**
 
 ```
-wiki_lint(mode?: string, writeReport?: boolean, limit?: number)
+details: {
+  pages: number,
+  orphans: number,
+  missingPages: number,
+  contradictions: number,
+  reportPath: string,   // path to the generated lint report .md file
+  gaps: number          // knowledge gaps tracked in .discoveries/gaps.json
+}
 ```
 
-### wiki_status
+The lint report is written to `.llm-wiki/outputs/lint-YYYY-MM-DD.md`.
+Contradictions are flagged by the presence of `⚠️ **Contradiction` markers in page content and
+always require human review.
+
+---
+
+## wiki_status
+
+Report wiki health and statistics from the generated registry. Reads pre-built metadata — does not
+scan files directly.
+
+**Parameters**
+
+None.
 
-Show wiki statistics.
+**Returns**
 
 ```
-wiki_status()
+details: {
+  topic: string,
+  mode: string,               // "personal" or "company"
+  totalPages: number,
+  byType: Record<string, number>,  // e.g. { concept: 4, entity: 2, source: 7 }
+  orphans: number,
+  gaps: number,
+  health: "✅ Good" | "⚠️ Warning" | "🔴 Empty"
+}
 ```
 
-### wiki_rebuild_meta
+Health is `"⚠️ Warning"` when orphan count exceeds 5, `"🔴 Empty"` when the registry has no pages.
 
-Force metadata rebuild.
+---
+
+## wiki_rebuild_meta
+
+Force a full synchronous rebuild of all generated metadata: `registry.json`, `backlinks.json`,
+`index.md`, `log.md`. Use when metadata appears out of sync with actual wiki files.
+
+**Parameters**
+
+None.
+
+**Returns**
 
 ```
-wiki_rebuild_meta()
+details: { pageCount: number }
 ```
 
-### wiki_log_event
+---
 
-Record a structured event.
+## wiki_log_event
+
+Append a structured event to `meta/events.jsonl` and regenerate `meta/log.md`. Every event is
+timestamped automatically.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `kind` | `string` | ✅ | Event kind label (e.g. `"ingest"`, `"query"`, `"decision"`, `"integrate"`) |
+| `details` | `object` | — | Arbitrary additional fields to store alongside the event |
+
+**Returns**
 
 ```
-wiki_log_event(
-  kind: string,
-  title: string,
-  summary?: string,
-  sourceIds?: string[],
-  pagePaths?: string[],
-  notes?: string[],
-  actor?: "agent" | "user" | "extension"
-)
+details: { kind: string }
 ```
 
-### wiki_watch
+---
+
+## wiki_watch
 
-Schedule auto-updates.
+Output the shell command needed to schedule automatic wiki updates (discover → ingest → lint) via
+pi's `schedule_prompt` cron system. Does not schedule anything directly — it returns the command
+for the user to run.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `interval` | `string` | ✅ | `"daily"` (8:00 AM), `"weekly"` (Monday 9:00 AM), `"hourly"`, or `"stop"` (prints removal instructions) |
+
+**Returns**
 
 ```
-wiki_watch(schedule: string, command: string)
+details: {
+  interval: string,
+  cronSchedule: string,   // e.g. "0 0 8 * * *"
+  label: string           // e.g. "Daily at 8:00 AM"
+}
+```
+
+When `interval` is `"stop"`, returns `details: { action: "stop_instructions" }` with instructions
+for removing existing jobs via `schedule_prompt action=remove`.
+
+---
+
+## Error Shape
+
+All tools return `isError: true` in their result when a hard error occurs (no vault found, missing
+required input). The `text` content will contain a human-readable explanation. Check for `isError`
+before using `details`.
+
+```ts
+{
+  content: [{ type: "text", text: string }],
+  details: { error: string },
+  isError: true
+}
 ```
+
+The most common error is **"No wiki found — run wiki_bootstrap first"**, returned by every tool
+except `wiki_bootstrap` itself when `.llm-wiki/config.json` does not exist in the resolved vault
+root.

package/extensions/llm-wiki/index.ts

@@ -25,6 +25,7 @@ import {
   ensureVaultStructure,
   fmtDate,
   getVaultPaths,
+  migrateDoubledPersonalVault,
   resolveVaultPaths,
   writeJson,
 } from "./lib/utils.js";
@@ -70,6 +71,22 @@ export default function (pi: ExtensionAPI) {
   let needsTopicInference = false;
 
   pi.on("session_start", async (_event, ctx) => {
+    // One-shot recovery for vaults created with the broken personal-root
+    // (~/.llm-wiki/.llm-wiki/… doubled layout). Runs on every session start
+    // because it is a cheap existence-check no-op when the layout is correct.
+    try {
+      const migration = migrateDoubledPersonalVault();
+      if (migration && migration.moved.length > 0) {
+        ctx.ui.setStatus(
+          "llm-wiki",
+          `🧠 Personal wiki layout fixed: flattened ${migration.moved.length} entries out of ${migration.from} (see CHANGELOG)`,
+        );
+      }
+    } catch (err) {
+      // Never let migration crash session start.
+      console.warn(`[llm-wiki] doubled-dotdir migration skipped: ${(err as Error).message}`);
+    }
+
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
       // Silently create the wiki vault — no UI prompts

package/extensions/llm-wiki/lib/source-extractors.ts

@@ -1,14 +1,21 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { exec } from "./utils.js";
 
+export type ExtractionStatus = "success" | "failed" | "unsupported";
+
 export interface ExtractedContent {
   extracted: string;
   title?: string;
+  extractor?: string;
+  extraction_status?: ExtractionStatus;
+  content_type?: string;
 }
 
 export interface FileExtractor {
   format: string;
   shouldReadText: boolean;
+  extractorName?: string;
+  content_type?: string;
   matches(filePath: string): boolean;
   extract(args: FileExtractArgs): Promise<string> | string;
 }
@@ -38,25 +45,38 @@ const FILE_EXTRACTORS: FileExtractor[] = [
   {
     format: "pdf",
     shouldReadText: false,
+    extractorName: "markitdown",
+    content_type: "application/pdf",
     matches: hasExtension(".pdf"),
     extract: ({ pi, filePath, signal }) => extractPdf(pi, filePath, signal),
   },
-  textFileExtractor("markdown", [".md"]),
-  textFileExtractor("text", [".txt"]),
-  textFileExtractor("html", [".html", ".htm"]),
+  textFileExtractor("markdown", [".md"], "text/markdown"),
+  textFileExtractor("text", [".txt"], "text/plain"),
+  textFileExtractor("html", [".html", ".htm"], "text/html"),
   {
     format: "xml",
     shouldReadText: true,
+    extractorName: "xmlToMarkdown",
+    content_type: "application/xml",
     matches: hasExtension(".xml"),
     extract: ({ content }) => xmlToMarkdown(content),
   },
   {
     format: "json",
     shouldReadText: true,
+    extractorName: "jsonToMarkdown",
+    content_type: "application/json",
     matches: hasExtension(".json"),
     extract: ({ content }) => jsonToMarkdown(content),
   },
-  textFileExtractor("docx", [".docx"]),
+  {
+    format: "docx",
+    shouldReadText: false,
+    extractorName: "markitdown",
+    content_type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    matches: hasExtension(".docx"),
+    extract: ({ pi, filePath, signal }) => extractDocx(pi, filePath, signal),
+  },
   textFileExtractor("file", []),
 ];
 
@@ -91,10 +111,16 @@ export function pdfExtractionFailureMessage(source: string): string {
   return `_PDF content could not be converted to markdown from ${source}. Try increasing WIKI_MARKITDOWN_TIMEOUT_MS._\n`;
 }
 
-function textFileExtractor(format: string, extensions: string[]): FileExtractor {
+function textFileExtractor(
+  format: string,
+  extensions: string[],
+  contentType?: string,
+): FileExtractor {
   return {
     format,
     shouldReadText: true,
+    extractorName: "passthrough",
+    content_type: contentType,
     matches: extensions.length ? hasAnyExtension(extensions) : () => true,
     extract: ({ content }) => content,
   };
@@ -113,13 +139,33 @@ async function extractPdf(pi: ExtensionAPI, source: string, signal?: AbortSignal
   return extracted || pdfExtractionFailureMessage(source);
 }
 
+export function docxExtractionFailureMessage(source: string): string {
+  return `_DOCX content could not be converted to markdown from ${source}. Ensure uvx and markitdown are installed._\n`;
+}
+
+async function extractDocx(
+  pi: ExtensionAPI,
+  source: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const extracted = await extractWithMarkItDown(pi, source, signal);
+  return extracted || docxExtractionFailureMessage(source);
+}
+
 async function extractPdfUrl(
   pi: ExtensionAPI,
   url: string,
   signal?: AbortSignal,
 ): Promise<ExtractedContent> {
   const extracted = await extractPdf(pi, url, signal);
-  return { extracted, title: titleFromMarkdown(extracted) };
+  const failed = extracted.includes("could not be converted");
+  return {
+    extracted,
+    title: titleFromMarkdown(extracted),
+    extractor: "markitdown",
+    extraction_status: failed ? "failed" : "success",
+    content_type: "application/pdf",
+  };
 }
 
 async function extractTextUrl(
@@ -129,13 +175,30 @@ async function extractTextUrl(
 ): Promise<ExtractedContent> {
   const markitdownExtracted = await extractWithMarkItDown(pi, url, signal);
   if (markitdownExtracted) {
-    return { extracted: markitdownExtracted, title: titleFromMarkdown(markitdownExtracted) };
+    return {
+      extracted: markitdownExtracted,
+      title: titleFromMarkdown(markitdownExtracted),
+      extractor: "markitdown",
+      extraction_status: "success",
+    };
   }
 
   const curlExtracted = await fetchTextUrl(pi, url, signal);
-  if (!curlExtracted) return { extracted: "" };
-  if (looksLikePdf(curlExtracted)) return { extracted: pdfExtractionFailureMessage(url) };
-  return { extracted: curlExtracted, title: titleFromHtml(curlExtracted) };
+  if (!curlExtracted) return { extracted: "", extractor: "none", extraction_status: "failed" };
+  if (looksLikePdf(curlExtracted)) {
+    return {
+      extracted: pdfExtractionFailureMessage(url),
+      extractor: "curl",
+      extraction_status: "failed",
+      content_type: "application/pdf",
+    };
+  }
+  return {
+    extracted: curlExtracted,
+    title: titleFromHtml(curlExtracted),
+    extractor: "curl",
+    extraction_status: "success",
+  };
 }
 
 async function extractWithMarkItDown(
@@ -149,7 +212,7 @@ async function extractWithMarkItDown(
     const mdResult = await exec(
       pi,
       "sh",
-      ["-c", `uvx --from 'markitdown[pdf]' markitdown "${source}" 2>/dev/null || echo ""`],
+      ["-c", `uvx --from 'markitdown[docx,pdf]' markitdown "${source}" 2>/dev/null || echo ""`],
       { signal, timeout: markitdownTimeoutMs() },
     );
     return mdResult.stdout.trim() ? mdResult.stdout : "";

package/extensions/llm-wiki/lib/source-packet.ts

@@ -106,9 +106,16 @@ function fileCaptureSource(
     fallbackText: "",
     preserveOriginal: (packetPath) =>
       preserveFileOriginal(pi, packetPath, filePath, fileName, content, signal),
-    extract: async () => ({
-      extracted: await extractor.extract({ pi, filePath, content, signal }),
-    }),
+    extract: async () => {
+      const extractedStr = await extractor.extract({ pi, filePath, content, signal });
+      const failed = extractedStr.includes("could not be converted");
+      return {
+        extracted: extractedStr,
+        extractor: extractor.extractorName ?? "passthrough",
+        extraction_status: (failed ? "failed" : "success") as "failed" | "success",
+        ...(extractor.content_type ? { content_type: extractor.content_type } : {}),
+      };
+    },
     manifest: () => ({
       title: fileName,
       file_path: filePath,
@@ -152,6 +159,9 @@ function finalizeCapture(
     captured: fmtDate(),
     packet_version: "1.0",
     ...source.manifest({ ...content, extracted }),
+    extractor: content.extractor ?? "passthrough",
+    extraction_status: content.extraction_status ?? "success",
+    ...(content.content_type ? { content_type: content.content_type } : {}),
   };
 
   writeFileSync(join(packet.packetPath, "extracted.md"), extracted, "utf-8");

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

@@ -1,4 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmdirSync,
+  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";
@@ -33,11 +42,24 @@ export function detectVaultFormat(dir: string): VaultFormat {
   return "none";
 }
 
-/** Get the personal wiki root directory (~/.llm-wiki/). */
+/**
+ * Get the personal wiki root directory.
+ *
+ * The "root" follows the same contract as project wikis: it is the directory
+ * that *contains* the `.llm-wiki/` dot-dir, NOT the dot-dir itself.
+ * So the personal vault lives at `<root>/.llm-wiki/`.
+ *
+ * Default root: `homedir()` → personal vault at `~/.llm-wiki/`.
+ * Override:     `WIKI_HOME` env var → personal vault at `$WIKI_HOME/.llm-wiki/`.
+ *
+ * NOTE: Previously this returned `~/.llm-wiki` (the dot-dir itself), which
+ * caused `getVaultPaths()` to compose paths like `~/.llm-wiki/.llm-wiki/raw`.
+ * See `migrateDoubledPersonalVault()` for the one-shot recovery.
+ */
 export function getPersonalWikiRoot(): string {
   const envWiki = process.env.WIKI_HOME;
   if (envWiki) return envWiki;
-  return join(homedir(), ".llm-wiki");
+  return homedir();
 }
 
 /** Get VaultPaths for the personal wiki. */
@@ -45,6 +67,54 @@ export function getPersonalWikiPaths(): VaultPaths {
   return getVaultPaths(getPersonalWikiRoot());
 }
 
+/**
+ * One-shot, idempotent migration for vaults that were created with the broken
+ * `getPersonalWikiRoot()` (returned the dot-dir itself, so `getVaultPaths()`
+ * composed `<root>/.llm-wiki/.llm-wiki/...`).
+ *
+ * Detects a doubled layout at `<root>/.llm-wiki/.llm-wiki/config.json` and
+ * flattens it up by one level. Safe to call on every session start: if the
+ * doubled sentinel is absent, this is a no-op.
+ *
+ * Returns a description of the action taken (or `null` if no migration was
+ * needed) so callers can surface a one-line status message.
+ */
+export function migrateDoubledPersonalVault(
+  parentRoot: string = getPersonalWikiRoot(),
+): { moved: string[]; from: string; to: string; skipped: string[] } | null {
+  const outerDotWiki = join(parentRoot, ".llm-wiki");
+  const innerDotWiki = join(outerDotWiki, ".llm-wiki");
+  const innerSentinel = join(innerDotWiki, "config.json");
+
+  if (!existsSync(innerSentinel)) return null;
+
+  const moved: string[] = [];
+  const skipped: string[] = [];
+
+  for (const entry of readdirSync(innerDotWiki)) {
+    const src = join(innerDotWiki, entry);
+    const dest = join(outerDotWiki, entry);
+    if (existsSync(dest)) {
+      // Collision — leave the inner copy in place rather than clobber.
+      skipped.push(entry);
+      continue;
+    }
+    renameSync(src, dest);
+    moved.push(entry);
+  }
+
+  // Only remove the inner dir if it is fully drained.
+  if (skipped.length === 0) {
+    try {
+      rmdirSync(innerDotWiki);
+    } catch {
+      // Leave behind if something raced us; harmless.
+    }
+  }
+
+  return { moved, from: innerDotWiki, to: outerDotWiki, skipped };
+}
+
 /**
  * Check if a vault is the personal wiki location.
  * Used in layered recall to avoid double-counting.

package/package.json

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