@zosmaai/pi-llm-wiki 0.11.2 → 0.11.4

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+### Added
+- **oh-my-pi (`omp`) host support** alongside pi, from one codebase and with no hard fork. `@oh-my-pi/pi-coding-agent` rewrites `@mariozechner/pi-*` and bare `typebox` specifiers onto its own bundled packages, so the extension module graph is unchanged; what differed was the on-disk config layout and slash-command discovery.
+  - **`extensions/llm-wiki/lib/host.ts`**: detects the host (`LLM_WIKI_HOST` override → agent-directory marker → `OMP_PROFILE` → `pi`) and enumerates every settings file both layouts use.
+  - **Dual-layout settings**: `loadTaskConfig` now merges `<agentDir>/{settings.json,config.yml,config.yaml}` and `<cwd>/{.pi,.omp}/{settings.json,config.yml,config.yaml}`, host-native project directory last. YAML is parsed for the `config.yml` files oh-my-pi migrates to. `/wiki-model` and `/wiki-trajectories` write JSON into whichever project config directory already exists, so a `.pi`-only repository never sprouts a second settings file and a hand-authored `config.yml` is never rewritten.
+  - **`commands/`**: a generated, committed mirror of `prompts/` (`npm run build:commands`, also run by `prepack`). pi finds slash-command templates through `pi.prompts`; oh-my-pi only turns `<package>/commands/*.md` into real `/wiki-*` commands.
+  - **Manifest**: added `package.json#omp.extensions`, naming the entry module rather than the `./extensions` directory — oh-my-pi reads `omp` before falling back to `pi`, and `omp -e <package-root>` imports a manifest entry verbatim, so a directory entry fails there. No new dependency: the host resolves its own bundled packages for the extension, so an `@oh-my-pi/pi-coding-agent` peer would be inert while dragging the whole host tree into `pnpm-lock.yaml`.
+  - **17 tests** (`test/host-compat.test.ts`, plus manifest/mirror assertions in `test/package-structure.test.ts`): host detection and its precedence, settings-file enumeration and ordering, write-target selection, cross-host config round-trips, YAML reads, corrupt-file tolerance, and `commands/`↔`prompts/` parity.
+  - **Ambient surfaces are gated on "does a wiki apply here"**: the session notice, the periodic observe/retro reminder, and the `before_agent_start` recall injection (with its `<wiki_status>` system-prompt footer) fire unprompted, and vault resolution falls back to the personal vault — so once `~/.llm-wiki/` existed they spoke up in EVERY directory, injecting reminders and unrelated cross-project recall hits into repositories that never ran `/wiki-init`. Harmless under pi, where extensions are opted into per project; under oh-my-pi the plugin is installed once and loads everywhere. New `resolveProjectVaultRoot()` answers the question the old `resolveVaultRoot()` could not — "does THIS project have a vault", with no personal fallback and no false positive from the personal vault sitting on the ancestor path of every project under `$HOME`. The new `llm-wiki.ambientPersonalVault` setting overrides the host-dependent default (`true` under pi, preserving historical behaviour; `false` under omp). Tools and slash commands are registered either way, so `/wiki-init` and `wiki_bootstrap` still work in any directory.
+  - **17 more tests** (`test/ambient-gate.test.ts`): project-vault resolution (own vault, ancestor walk, `WIKI_HOME`, personal-vault exclusion), the host-dependent default and its explicit override, the composed gate across four project states, and the reminder gate — including that a closed gate does not bank turns, so opening it later is not an instant nag, and that `display: false` is not a substitute because it still injects into model context.
+
 ### Fixed
 - **MCP server failed to start on `@modelcontextprotocol/server` 2.0.0** (Issue #128): `mcp/index.ts` imported `StdioServerTransport` from the package root, but SDK 2.0.0 (published 2026-07-27) moved that export to the `./stdio` subpath, so `node dist/mcp/index.js` died with `SyntaxError: The requested module '@modelcontextprotocol/server' does not provide an export named 'StdioServerTransport'` before the transport ever connected. The declared range `^2.0.0-alpha.2` is a caret range over a prerelease, so it permits `2.0.0`: every fresh consumer install resolved the stable SDK against the pre-stable import, while `pnpm-lock.yaml` pinned the `2.0.0-alpha.2` floor — so `test/mcp-package.test.ts`, which does spawn the published command and complete the stdio handshake, only ever exercised the alpha where the root export still existed. Fixed by importing `StdioServerTransport` from `@modelcontextprotocol/server/stdio` (the `./stdio` subpath does not exist in `2.0.0-alpha.2`, so the range, the lockfile and the import move together), raising the range to `^2.0.0`, and refreshing the lockfile so the existing smoke test now runs against the SDK consumers actually get.
 - **Packaged MCP server was never exercised with consumer-resolved dependencies**: a new `packaged-mcp-consumer` CI job packs the tarball, installs it into a directory with **no lockfile**, prints the resolved SDK version, and runs `scripts/mcp-smoke.mjs` — the stdio handshake (`initialize` → `tools/list`) — against that install. This closes the whole class of failure behind Issue #128: a dependency range that resolves differently for consumers than for this repo's lockfile can no longer break the published server undetected.
@@ -18,6 +28,7 @@
 - **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
+- **`wiki_bootstrap` over MCP, so MCP-only clients can create a vault** (Issue #130): the README aims the standalone MCP server at Claude Code, Cursor and Windsurf — clients with no access to the Pi extension — yet all five MCP tools failed closed with `No wiki vault found. Set WIKI_ROOT or run wiki_bootstrap first.`, naming a tool those clients did not have. Short of installing pi or hand-building the `.llm-wiki/` tree, there was no path to a working vault. `bootstrapVault()` is pure Node (`node:fs`, `node:path`, sibling lib modules) with no model and no credentials in play, so it is now exposed as a sixth MCP tool through a thin `bootstrapOperation` adapter, keeping Pi and MCP over one implementation. Bootstrap resolves its target with `getVaultPaths(WIKI_ROOT)` rather than the usual `resolveVaultPaths()`: resolution deliberately walks up to a parent vault and then falls back to the personal vault, which is right for reading and writing pages but would create the vault somewhere other than where the client pointed the server. There is no `root` parameter, so the server stays confined to its configured root, and `mode` accepts the same free-form `personal`/`company` string the Pi tool takes. Re-running is safe: an existing vault has its config updated and metadata rebuilt, and pages are untouched. The two guards on the MCP surface (`test/mcp-parity.test.ts` and `test/mcp-package.test.ts`) were deliberately widened from five tools to six, `scripts/mcp-smoke.mjs` now requires the tool on the packed artifact, and every README's MCP table lists it.
 - **Visible wiki activity + background/reported mutations** (Issue #77): the wiki was effectively invisible — recall was appended only to the **system prompt**, the observe/retro reminder was sent with `display: false`, and the lone user-facing cue was a static status line. The wiki now surfaces what it does, and mutating work is pushed off the agent's critical path.
   - **Visible surfaces**: a one-time **session notice** (`buildSessionNotice`) announces the full loop — retrieval (recall → `wiki_search` → `read`, all synchronous because the LLM consumes their output) and capture (`wiki_observe` → `wiki_retro`, background + reported); the periodic reminder is now `display: true` and names **both** capture tools (`buildReminderText`); and the status line becomes **recall-aware** (`🧠 LLM Wiki — recalled N page(s) for this task`) when auto-recall matches.
   - **Background + reported principle**: only `wiki_search` / `read` / `wiki_recall` stay synchronous. Heavy mutations — `wiki_rebuild_meta`, `wiki_reindex_embeddings`, `wiki_lint` — now dispatch to the background runtime and **report a visible completion message** instead of blocking the turn; `wiki_ingest` gained a persistent completion report alongside its toast. New `Runtime.report()` / `Runtime.launchReported()` primitives and a `dispatchReported()` tool helper (with a synchronous fallback when no runtime is available, preserving prior behavior and unit tests).

package/README.de.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 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:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.es.md

@@ -330,10 +330,11 @@ Esto preserva tanto el **artefacto original** como una **vista extraída normali
 
 Usa el wiki desde **cualquier herramienta compatible con MCP** — Claude Code, Cursor, Windsurf y otras.
 
-El paquete incluye un servidor MCP independiente que expone 5 herramientas de wiki por stdio:
+El paquete incluye un servidor MCP independiente que expone 6 herramientas de wiki por stdio:
 
 | Herramienta | Descripción |
 |-------------|-------------|
+| `wiki_bootstrap` | Inicializa un nuevo vault de wiki con configuración, plantillas, esquema y metadatos |
 | `wiki_recall` | Busca en el wiki páginas relevantes para la tarea |
 | `wiki_search` | Búsqueda completa del registro |
 | `wiki_status` | Estadísticas del wiki (conteos de páginas, desglose por tipo) |

package/README.fr.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 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:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.hi.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 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:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.ja.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 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:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.ko.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 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:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.md

@@ -47,10 +47,21 @@ Start with a new OKF vault, or point pi-llm-wiki at an existing vault and adopt
 
 ## Quick Start
 
+**pi** ([`@mariozechner/pi-coding-agent`](https://github.com/badlogic/pi-mono)):
+
 ```bash
 pi install npm:@zosmaai/pi-llm-wiki
 ```
 
+**oh-my-pi** ([`omp`](https://github.com/can1357/oh-my-pi)):
+
+```bash
+omp install @zosmaai/pi-llm-wiki
+```
+
+Both hosts load the same extension, skill, and `/wiki-*` slash commands — see
+[Dual-host support](#dual-host-support-pi--oh-my-pi) for what differs.
+
 The extension will proactively suggest creating a wiki on your first session. Alternatively:
 
 ```
@@ -342,10 +353,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 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:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |
@@ -384,6 +396,66 @@ The same server as an entry in `.mcp.json` (Claude Code) or `claude_desktop_conf
 
 ---
 
+## Dual-host support (pi + oh-my-pi)
+
+The package targets two hosts from a single codebase:
+
+| | **pi** (`@mariozechner/pi-coding-agent`) | **oh-my-pi** (`omp`) |
+|---|---|---|
+| Extension entry | `package.json#pi.extensions` | `package.json#omp.extensions` (falls back to `#pi`) |
+| Skill | `skills/llm-wiki/SKILL.md` via `pi.skills` | same file, found by directory convention |
+| Slash commands | `prompts/*.md` via `pi.prompts` | `commands/*.md` (generated mirror of `prompts/`) |
+| Project config | `<cwd>/.pi/settings.json` | `<cwd>/.omp/settings.json`, then `.omp/config.yml` |
+| User config | `~/.pi/agent/settings.json` | `~/.omp/agent/settings.json`, then `config.yml` |
+| MCP server | auto-registered via `pi.mcpservers` | register manually (see below) |
+| Ambient surfaces without a project wiki | on (personal vault) | off — see below |
+
+No source changes are needed for the imports: oh-my-pi rewrites
+`@mariozechner/pi-*` and bare `typebox` specifiers onto its own bundled
+packages when it loads a legacy extension.
+
+**Settings are read from both layouts.** `llm-wiki` config is merged from every
+file above, host-native directory last. A vault configured under pi keeps
+working after `omp` takes over the same repository, and writes land in whichever
+config directory already exists (so a `.pi`-only repo does not sprout a second
+settings file). Writes are always JSON — a hand-authored `config.yml` is read
+but never rewritten.
+
+Set `LLM_WIKI_HOST=pi|omp` to override host detection; by default it is derived
+from the resolved agent directory.
+
+**Ambient surfaces are gated under oh-my-pi.** The session notice, the periodic
+observe/retro reminder, and `before_agent_start` recall all fire unprompted, and
+vault resolution falls back to the personal vault — so once `~/.llm-wiki/`
+exists they would speak up in *every* directory. Under pi that is the historical
+behaviour and it is kept; under omp the plugin is installed once and loads in
+every project, so a repository that never ran `/wiki-init` stays quiet. Override
+either default with `llm-wiki.ambientPersonalVault`. The wiki tools and slash
+commands are registered regardless, so `/wiki-init` always works — and a project
+with its own `.llm-wiki/` gets every surface back.
+
+**MCP under oh-my-pi.** `pi.mcpservers` is a pi-only manifest key, and the
+server's vault auto-detection depends on the client's working directory, so it
+cannot be declared with a relative path. Register it explicitly instead:
+
+```jsonc
+// <cwd>/.omp/.mcp.json
+{
+  "mcpServers": {
+    "llm-wiki": {
+      "command": "node",
+      "args": ["/abs/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
+      "env": { "WIKI_ROOT": "/abs/path/to/your/wiki" }
+    }
+  }
+}
+```
+
+You rarely need it: under either host the extension already registers the same
+capabilities as native tools.
+
+---
+
 ## Skill Behavior
 
 The bundled `llm-wiki` skill teaches the model to:
@@ -480,6 +552,13 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>James Fraser</b></sub>
                 </a>
             </td>
+            <td align="center">
+                <a href="https://github.com/mkuhl">
+                    <img src="https://avatars.githubusercontent.com/u/61073?v=4" width="64;" alt="mkuhl"/>
+                    <br />
+                    <sub><b>Mike P. Kuhl</b></sub>
+                </a>
+            </td>
             <td align="center">
                 <a href="https://github.com/CelestialCreator">
                     <img src="https://avatars.githubusercontent.com/u/177931942?v=4" width="64;" alt="CelestialCreator"/>
@@ -487,6 +566,13 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>Akshay</b></sub>
                 </a>
             </td>
+            <td align="center">
+                <a href="https://github.com/prestalab">
+                    <img src="https://avatars.githubusercontent.com/u/2825421?v=4" width="64;" alt="prestalab"/>
+                    <br />
+                    <sub><b>PrestaLab</b></sub>
+                </a>
+            </td>
             <td align="center">
                 <a href="https://github.com/xcsf">
                     <img src="https://avatars.githubusercontent.com/u/43439835?v=4" width="64;" alt="xcsf"/>
@@ -501,13 +587,8 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>Daniel Naab</b></sub>
                 </a>
             </td>
-            <td align="center">
-                <a href="https://github.com/mkuhl">
-                    <img src="https://avatars.githubusercontent.com/u/61073?v=4" width="64;" alt="mkuhl"/>
-                    <br />
-                    <sub><b>Mike P. Kuhl</b></sub>
-                </a>
-            </td>
+		</tr>
+		<tr>
             <td align="center">
                 <a href="https://github.com/deestax">
                     <img src="https://avatars.githubusercontent.com/u/152369481?v=4" width="64;" alt="deestax"/>
@@ -515,8 +596,6 @@ Thanks to everyone who has contributed! This list is regenerated automatically b
                     <sub><b>Superdao</b></sub>
                 </a>
             </td>
-		</tr>
-		<tr>
             <td align="center">
                 <a href="https://github.com/mystery4f">
                     <img src="https://avatars.githubusercontent.com/u/40482524?v=4" width="64;" alt="mystery4f"/>

package/README.pt.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 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:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.ru.md

@@ -346,10 +346,11 @@ This preserves both the **original artifact** and a **normalized extracted view*
 
 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:
+The package ships a standalone MCP server exposing 6 wiki tools over stdio:
 
 | Tool | Description |
 |------|-------------|
+| `wiki_bootstrap` | Initialize a new wiki vault with config, templates, schema, and metadata |
 | `wiki_recall` | Search wiki for task-relevant pages |
 | `wiki_search` | Full registry search |
 | `wiki_status` | Wiki stats (page counts, type breakdown) |

package/README.zh.md

@@ -330,10 +330,11 @@ my-wiki/
 
 从 **任何 MCP 兼容工具** 使用 wiki——Claude Code、Cursor、Windsurf 等。
 
-包附带独立 MCP 服务器，通过 stdio 暴露 5 个 wiki 工具：
+包附带独立 MCP 服务器，通过 stdio 暴露 6 个 wiki 工具：
 
 | 工具 | 描述 |
 |------|------|
+| `wiki_bootstrap` | 用配置、模板、模式和元数据初始化新的 wiki vault |
 | `wiki_recall` | 搜索 wiki 中与任务相关的页面 |
 | `wiki_search` | 完整注册表搜索 |
 | `wiki_status` | Wiki 统计（页面计数、类型分解） |

package/commands/wiki-digest.md

@@ -0,0 +1,28 @@
+---
+description: Generate a daily or weekly digest of wiki changes — new sources, pages, insights, and gaps.
+argument-hint: "[--period daily|weekly]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-digest
+
+Generate a digest of recent wiki activity.
+
+## User Arguments
+
+$ARGUMENTS
+
+## Steps
+
+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 captured
+   - New pages created or updated
+   - Key insights or connections made
+   - Knowledge gaps identified
+   - 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/commands/wiki-discover.md

@@ -0,0 +1,30 @@
+---
+description: Auto-discover new sources from the web. Searches based on config topics and known knowledge gaps.
+argument-hint: "[--topic <topic>]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-discover
+
+Find new source material for the wiki by searching the web and capturing them as source packets.
+
+## User Arguments
+
+$ARGUMENTS
+
+## Steps
+
+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/commands/wiki-ingest.md

@@ -0,0 +1,36 @@
+---
+description: Process new source packets and synthesize them into wiki knowledge pages.
+argument-hint: "[source_id]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-ingest
+
+Process uningested source packets and synthesize them into wiki knowledge pages.
+
+## User Arguments
+
+$ARGUMENTS
+
+## Steps
+
+1. Call `wiki_ingest(source_id=<id if provided>, batch_size=3)`.
+2. If the tool reports "All sources ingested", inform the user and stop.
+3. **If the tool reports it is ingesting in the background**, the synthesis sub-agent is handling those sources on the configured task model. Do NOT synthesize them yourself — just report which sources were dispatched and stop. (You'll be notified as each completes.)
+4. **Otherwise** (the tool returned extracted content — background unavailable or `background=false`), for each source in the returned batch:
+   a. Read the extracted text from `.llm-wiki/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
+5. After processing a synchronous batch, call `wiki_rebuild_meta` to update metadata.
+6. Report: "Ingested [N] sources → [M] pages created/updated. [X] contradictions flagged."
+
+> **Background vs synchronous:** ingestion runs in the background by default (non-blocking) when a task model is available, so the main agent is never stalled. It falls back to the synchronous main-agent flow above when no model/API key is configured, or when called with `background=false`.
+
+**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/commands/wiki-init.md

@@ -0,0 +1,30 @@
+---
+description: Initialize a new LLM Wiki in the current directory. Creates the full directory structure, config, and template files.
+argument-hint: "<topic> [--mode personal|company]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-init
+
+Initialize a new LLM Wiki vault using the `wiki_bootstrap` tool.
+
+## User Arguments
+
+$ARGUMENTS
+
+## Steps
+
+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/commands/wiki-lint.md

@@ -0,0 +1,25 @@
+---
+description: Health check the wiki. Detects contradictions, orphans, missing pages, stale claims, and knowledge gaps.
+argument-hint: "[--fix]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-lint
+
+Run a comprehensive health check on the wiki.
+
+## User Arguments
+
+$ARGUMENTS
+
+## Steps
+
+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/commands/wiki-query.md

@@ -0,0 +1,37 @@
+---
+description: Ask questions against the wiki. Synthesizes answers from wiki pages with cross-reference citations.
+argument-hint: "<question>"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-query
+
+Ask a question and get an answer synthesized from wiki content.
+
+## User Question
+
+$ARGUMENTS
+
+## Steps
+
+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.
+
+**Example:**
+
+```
+/wiki-query What are the key differences between RAG and LLM Wiki?
+→ 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/commands/wiki-record.md

@@ -0,0 +1,36 @@
+---
+description: Capture the just-completed task's tool-call trajectory into the wiki as agent working-memory, then optionally distill it into a reusable skill.
+argument-hint: "<title> [--outcome success|failure|partial]"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-record
+
+Capture the trajectory of the task you just completed — the sequence of tool calls that solved it — into the wiki's working-memory layer.
+
+This is the counterpart to source capture: instead of recording what you *read*, it records what you *did*, so the wiki compounds over your own work.
+
+## User Arguments
+
+$ARGUMENTS
+
+Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the wiki conventions.
+
+## Steps
+
+1. Call `wiki_capture_trajectory` with:
+   - `title`: short descriptive phrase for the task (≤60 chars, noun phrase)
+   - `outcome`: optional — `success` (default), `failure`, or `partial`
+   - The extension auto-extracts the tool-call trajectory from the live session, so you usually do **not** pass `steps` manually.
+2. Open the generated skeleton case page in `wiki/cases/` and flesh out:
+   - **Task** — what was requested
+   - **Approach** — the key steps and decisions (not every tool call, just the meaningful ones)
+   - **Outcome** — the result, and anything worth reusing or avoiding next time
+3. If the task taught a reusable pattern, run `wiki_distill_skills` and create a `skill` page via `wiki_ensure_page(type="skill")` that cites `[[trajectories/TRJ-...]]`.
+4. Confirm the case (and any skill) will be surfaced by `wiki_recall` / `wiki_recall_skill` in future sessions.
+
+**Rules:**
+- Only record tasks worth learning from — non-trivial debugging, refactors, integrations, multi-step workflows. Skip trivial one-shot answers.
+- The raw trajectory packet under `raw/trajectories/` is immutable. Edit the `case`/`skill` pages, never the packet.
+- One trajectory per `wiki_capture_trajectory` call.

package/commands/wiki-req.md

@@ -0,0 +1,55 @@
+---
+description: Capture and decompose a concept into atomic, traceable wiki requirements. Clarifies ambiguous requirements, splits them into atomic pieces, and persists them as wiki/requirements/ pages with status tracking.
+argument-hint: "<concept description>"
+section: LLM Wiki
+topLevelCli: true
+---
+
+# /wiki-req
+
+Capture a concept and decompose it into atomic, traceable requirements in the wiki.
+
+Transforms natural language descriptions into structured `wiki/requirements/` pages, preserving the original clarified concept as an immutable source packet in `raw/sources/`.
+
+## User Arguments
+
+$ARGUMENTS
+
+Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the wiki conventions, architecture, and page type rules.
+
+## Steps
+
+1. **Clarify the concept**
+   - Discuss with the user: unpack ambiguous terms, surfaces implicit assumptions, identify scope boundaries
+   - Ask targeted questions to resolve unknowns (e.g., "Which providers?", "What's the fallback behavior?", "Who are the actors?")
+   - Reach mutual clarity before proceeding
+
+2. **Capture the clarified concept**
+   - Call `wiki_capture_source(text=...)` with the clarified conversation as markdown
+   - This creates an immutable record in `raw/sources/SRC-YYYY-MM-DD-NNN/`
+   - The source captures the original intent verbatim — no interpretation, no decomposition
+
+3. **Decompose into atomic requirements**
+   - Break the clarified concept into the smallest meaningful units of functionality
+   - Each requirement should represent one independently verifiable behavior
+   - For each atomic requirement, call `wiki_ensure_page(type="requirement", title="...", content="...")` where content includes:
+     - `type: requirement` and `status: draft` in frontmatter
+     - A clear `## Description` section
+     - `## Acceptance Criteria` as a checkbox list (the threshold for "done")
+     - `source_id` linking back to the source capture
+     - `depends_on` linking to any prerequisite requirements
+     - `[[wikilinks]]` to relevant entities, concepts, and other wiki pages
+   - Set priority based on user input: `p0` (blocking), `p1` (critical), `p2` (important), `p3` (nice-to-have)
+
+4. **Cross-link and finalize**
+   - Ensure each requirement page has bidirectional wikilinks to related pages
+   - Update any existing entity or concept pages that these requirements reference
+   - Report the results: how many requirements created, their priorities, and the source capture ID
+
+**Rules:**
+- One atomic requirement per `wiki_ensure_page` call — each must be independently testable
+- Always capture the clarified concept first via `wiki_capture_source` before decomposing
+- Requirements live in `wiki/requirements/` — they are editable wiki pages, not immutable sources
+- Use status values: `draft` → `clarified` → `active` → `implemented` → `deferred` → `rejected`
+- Use priority values: `p0` (blocking), `p1` (critical), `p2` (important), `p3` (nice-to-have)
+- Do not create requirements in `raw/` — that layer is for external source artifacts only

package/commands/wiki-retro.md

@@ -0,0 +1,34 @@
+---
+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
+---
+
+# /wiki-retro
+
+Save an atomic insight from a completed task into the wiki.
+
+Captures what you learned as a single markdown file so that layered recall surfaces it in future sessions.
+
+## User Arguments
+
+$ARGUMENTS
+
+Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the wiki conventions.
+
+## Steps
+
+1. Identify the key insight(s) from the current task — non-obvious learnings, patterns, or decisions worth preserving
+2. For each insight, call `wiki_retro` with:
+   - `slug`: unique kebab-case identifier (e.g., `jwt-revocation-pattern`)
+   - `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 surfaced by layered recall in future sessions
+4. If the insight relates to existing wiki pages, update those pages with cross-references
+
+**Rules:**
+- One atomic insight per `wiki_retro` call. Use multiple calls for multiple insights.
+- Don't save obvious things. Save non-obvious patterns, tradeoffs, and design decisions.
+- Always add `[[wikilinks]]` to connect the new insight with existing wiki knowledge.