@zosmaai/pi-llm-wiki 0.11.4 → 0.11.6

package/dist/mcp/operations.js

@@ -5,11 +5,15 @@
  * used by Pi tools. No operation parses YAML, scans files, scores
  * registry entries, or builds page strings itself.
  */
+import { join } from "node:path";
 import { bootstrapVault } from "../extensions/llm-wiki/lib/bootstrap.js";
+import { applyWikilinkGate, buildWikilinkIndex, } from "../extensions/llm-wiki/lib/knowledge-links.js";
 import { rebuildMetadata } from "../extensions/llm-wiki/lib/metadata.js";
 import { searchWikiLayered } from "../extensions/llm-wiki/lib/recall.js";
 import { saveInsight } from "../extensions/llm-wiki/lib/retro.js";
 import { captureFile, captureText, captureUrl } from "../extensions/llm-wiki/lib/source-packet.js";
+import { resolveWikilinkValidation } from "../extensions/llm-wiki/lib/task-config.js";
+import { readJson } from "../extensions/llm-wiki/lib/utils.js";
 import { VaultWriteError, inspectVaultFormat, inspectWritableVault, } from "../extensions/llm-wiki/lib/vault-format.js";
 import { getWikiStatus, searchRegistry } from "../extensions/llm-wiki/lib/wiki-service.js";
 function projectionOutcome(projection) {
@@ -87,7 +91,7 @@ export async function statusOperation(paths) {
     };
 }
 /** Shared retro operation: validates vault then delegates to saveInsight. */
-export async function retroOperation(paths, slug, title, body, category) {
+export async function retroOperation(paths, slug, title, body, category, wikilinkValidation) {
     const vaultCheck = inspectWritableVault(paths);
     if (!vaultCheck.ok) {
         return {
@@ -95,8 +99,23 @@ export async function retroOperation(paths, slug, title, body, category) {
             diagnostics: vaultCheck.diagnostics.map((d) => ({ code: d.code, message: d.message })),
         };
     }
+    // Pre-write wikilink gate (#172): validate/normalize caller-supplied body.
+    const mode = resolveWikilinkValidation({ wikilinkValidation });
+    let gateBody = body;
+    if (mode !== "off") {
+        const registry = readJson(join(paths.meta, "registry.json"), { pages: {} });
+        const gate = applyWikilinkGate(body, buildWikilinkIndex(Object.keys(registry.pages)), `sources/${slug}`, mode);
+        if (!gate.ok) {
+            return {
+                ok: false,
+                diagnostics: gate.diagnostics.map((d) => ({ code: "link_validation", message: d.message })),
+            };
+        }
+        if (mode === "normalize")
+            gateBody = gate.body;
+    }
     try {
-        const result = saveInsight(paths, slug, title, body, category, { rebuild: false });
+        const result = saveInsight(paths, slug, title, gateBody, category, { rebuild: false });
         const projection = projectionOutcome(rebuildMetadata(paths));
         if (!projection.ok)
             return projection;

package/docs/api.md

@@ -2,7 +2,7 @@
 
 All tools registered by the extension. Parameters marked `?` are optional.
 
-13 tools are always registered. The 3 agent-trajectory tools
+14 tools are always registered. The 3 agent-trajectory tools
 (`wiki_capture_trajectory`, `wiki_distill_skills`, `wiki_recall_skill`) are **opt-in,
 off by default** (issue #80) — they are only registered when `llm-wiki.trajectories`
 is `true`; enable with `/wiki-trajectories on`.
@@ -458,6 +458,29 @@ Returns empty `matches: []` with a hint to capture work via `wiki_capture_trajec
 
 ---
 
+## wiki_reindex_embeddings
+
+Backfill or refresh semantic embeddings for the vault. Embeds pages that are new or stale
+(content changed); pass `force` to re-embed everything. No-op when no embedding provider is
+configured — set `llm-wiki.embeddingProvider` first (see `docs/configuration.md`).
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `force` | `boolean` | — | Re-embed every page, ignoring staleness (default: `false`) |
+
+**Returns**
+
+```
+details: { enabled: true, model: string, embedded: number, skipped: number, pruned: number }
+```
+
+Fails soft with `details: { enabled: false }` plus a hint to configure `embeddingProvider` when
+no embedding provider is set.
+
+---
+
 ## Error Shape
 
 All tools return `isError: true` in their result when a hard error occurs (no vault found, missing

package/docs/commands.md

@@ -17,10 +17,13 @@
 | `/wiki-trajectories` | Enable/disable agent working-memory (`on`/`off`, opt-in) |
 | `/wiki-record`   | Capture the completed task's trajectory (requires trajectories enabled) |
 | `/wiki-skills`   | Search distilled skills + past cases (requires trajectories enabled) |
+| `/wiki-req` | Decompose a concept into atomic requirement pages |
+| `/wiki-settings` | Browse or change all `llm-wiki` settings (project or global scope) |
+| `/wiki-dashboard` | Read-only vault health: pages, freshness, activity, ingest queue, backlinks, embeddings |
 
 ## Extension Tools
 
-The extension always registers 13 tools the LLM can call directly. The 3 agent-trajectory
+The extension always registers 14 tools the LLM can call directly. The 3 agent-trajectory
 tools (`wiki_capture_trajectory`, `wiki_distill_skills`, `wiki_recall_skill`) are **opt-in,
 off by default** (issue #80) — registered only when `llm-wiki.trajectories` is enabled
 (`/wiki-trajectories on`).
@@ -36,7 +39,9 @@ off by default** (issue #80) — registered only when `llm-wiki.trajectories` is
 | `wiki_search`         | Search the wiki registry                    |
 | `wiki_lint`           | Health check with auto-fix                  |
 | `wiki_status`         | Instant stats                               |
+| `wiki_observe` | Record a timestamped observation from the current session |
 | `wiki_rebuild_meta`   | Force metadata rebuild                      |
+| `wiki_reindex_embeddings` | Refresh semantic embeddings (no-op when no embedding provider) |
 | `wiki_log_event`      | Record custom event                         |
 | `wiki_watch`          | Schedule auto-updates                       |
 | `wiki_capture_trajectory` | Capture the completed task's tool-call trajectory |

package/docs/configuration.md

@@ -53,12 +53,23 @@ config directory already exists (host-native first, created if neither is
 present). A hand-authored `config.yml` is read but never rewritten.
 
 | Setting                | Default    | Description                                                  |
+All of the above are viewable and editable in the `/wiki-settings` TUI (persists to project or global settings).
 | ---------------------- | ---------- | ------------------------------------------------------------ |
 | `taskModel`            | —          | Model for background tasks (`{ provider: "openai", id: "gpt-4o" }`) |
 | `synthesisLanguage`    | —          | BCP 47 language tag for ingest synthesis (e.g. `"ru"`, `"fr"`). When unset, synthesis defaults to English. |
+| `synthesisMaxTokens`     | 16384    | Max output tokens for ingest/synthesis runs (stored as a plain number)                        |
+| `wikilinkValidation`   | warn       | Pre-write wikilink gate for page writes (ingest, `wiki_ensure_page`, `wiki_retro`, MCP `wiki_retro`). `off` ignore, `warn` report, `normalize` rewrite resolvable links, `strict` block writes with unresolved/ambiguous links |
 | `trajectories`         | false      | Enable agent-trajectory working-memory                       |
 | `notices`              | true       | Show wiki activity notices in chat                           |
 | `ambientPersonalVault` | host-dependent | Let the personal vault act as the ambient vault in projects that have no wiki. `true` under pi, `false` under oh-my-pi — see below. |
+| `semanticWeight`       | 0.5      | Weight of the semantic sub-score in hybrid recall (clamped 0–1)                               |
+| `recallLinksThreshold` | 50       | Page-count gate for two-stage links-first recall (0 = always links-first, issue #68)          |
+| `recallSkillInlineMax` | 1600     | Max chars of a skill/case body inlined into recall output (0 = links only)                    |
+| `embeddingProvider`    | —        | Embedding provider (e.g. `openai`); embeddings stay off until this is set                     |
+| `embeddingModel`       | —        | Embedding model name (provider-specific)                                                      |
+| `embeddingBaseUrl`     | —        | Optional API base URL override for the embedding provider                                     |
+| `embeddingApiKey`      | —        | API key literal — prefer `embeddingApiKeyEnv` so no secret lands in settings                  |
+| `embeddingApiKeyEnv`   | —        | Name of the environment variable holding the embedding API key                                |
 
 Example:
 

package/docs/obsidian.md

@@ -2,20 +2,20 @@
 
 ## Setup
 
-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
+1. Open `.llm-wiki/` as an Obsidian vault
+2. Your wiki pages live in `wiki/` — Graph View and Backlinks work on these automatically
+3. The extension generates `meta/index.md` (browsable catalog) and `meta/backlinks.json` (link map) — both are read-only, regenerated on each rebuild
 
 ## Recommended Plugins
 
 - [Dataview](https://github.com/blacksmithgu/obsidian-dataview) — Query pages by frontmatter
-- [Graph View](https://obsidian.md) (built-in) — Visualize `[[wikilink]]` connections
+- [Graph View](https://obsidian.md) (built-in) — Visualize `[[wikilink]]` connections in `wiki/`
 - [Backlinks](https://obsidian.md) (built-in) — See inbound links
 
 ## Web Clipper
 
-Use [Obsidian Web Clipper](https://obsidian.md/clipper) to save articles directly into `.llm-wiki/raw/articles/`.
+Use [Obsidian Web Clipper](https://obsidian.md/clipper) to save articles directly into `raw/articles/`.
 
 ## Dataview Dashboard
 
-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`.
+For custom dashboards, use Dataview queries against frontmatter fields like `type`, `domain`, `category`, `sources`. Query the `wiki/` directory for knowledge pages.