@zosmaai/pi-llm-wiki 0.11.3 → 0.11.5

package/dist/extensions/llm-wiki/lib/task-config.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { dirname } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { detectHost, listGlobalSettingsFiles, listProjectSettingsFiles, resolveGlobalSettingsPath, resolveProjectSettingsPath, } from "./host.js";
 export const TASK_DEFAULTS = {};
 /**
  * Resolve whether user-facing wiki notices are enabled (issue #77). Defaults
@@ -9,6 +10,16 @@ export const TASK_DEFAULTS = {};
 export function noticesEnabled(config) {
     return config?.notices !== false;
 }
+/**
+ * Resolve whether the personal vault may serve as this project's ambient
+ * vault. Explicit `ambientPersonalVault` wins; otherwise the host decides
+ * (see the field docs on {@link TaskConfig.ambientPersonalVault}).
+ */
+export function personalVaultIsAmbient(config, host = detectHost()) {
+    if (typeof config?.ambientPersonalVault === "boolean")
+        return config.ambientPersonalVault;
+    return host === "pi";
+}
 /**
  * Resolve whether agent-trajectory working-memory is enabled (issue #80).
  * INVERSE polarity of `noticesEnabled`: defaults to `false`; only an explicit
@@ -64,6 +75,9 @@ function readNamespacedConfig(path) {
         if (typeof section.notices === "boolean") {
             out.notices = section.notices;
         }
+        if (typeof section.ambientPersonalVault === "boolean") {
+            out.ambientPersonalVault = section.ambientPersonalVault;
+        }
         if (typeof section.trajectories === "boolean") {
             out.trajectories = section.trajectories;
         }
@@ -73,6 +87,10 @@ function readNamespacedConfig(path) {
             if (canonical)
                 out.synthesisLanguage = canonical;
         }
+        const maxTokens = section.synthesisMaxTokens;
+        if (typeof maxTokens === "number" && Number.isFinite(maxTokens) && maxTokens > 0) {
+            out.synthesisMaxTokens = Math.floor(maxTokens);
+        }
         return out;
     }
     catch {
@@ -121,14 +139,19 @@ export function validateSynthesisLanguage(tag) {
     return canonical[0];
 }
 /**
- * Read a settings JSON file as a plain object, or `{}` when it is absent or
+ * Read a settings file as a plain object, or `{}` when it is absent or
  * corrupt. Reads directly (no `existsSync` pre-check) so there is no
  * check-then-use race: a missing file throws ENOENT, which the catch treats
  * the same as an empty file.
+ *
+ * `config.yml` / `config.yaml` are parsed as YAML — that is the format oh-my-pi
+ * migrates its settings to. Everything else is JSON. JSON is a YAML subset, so
+ * the YAML parser also accepts a `.yml` file that actually holds JSON.
  */
 function readSettingsObject(path) {
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        const text = readFileSync(path, "utf-8");
+        const parsed = path.endsWith(".yml") || path.endsWith(".yaml") ? parseYaml(text) : JSON.parse(text);
         if (parsed && typeof parsed === "object")
             return parsed;
     }
@@ -138,64 +161,143 @@ function readSettingsObject(path) {
     return {};
 }
 /**
- * Persist (or clear) the wiki background `taskModel` in the PROJECT settings
- * file `<cwd>/.pi/settings.json` under the namespaced `llm-wiki` key (issue
- * #69). Project settings win over global in `loadTaskConfig`, so this takes
- * effect immediately on the next config load. Other top-level keys and other
- * `llm-wiki` settings are preserved; passing `undefined` removes the key
- * (reverting to the session model).
+ * Rewrite the `llm-wiki` section of the global settings file.
  */
-export function persistTaskModel(cwd, model) {
-    const settingsPath = join(cwd, ".pi", "settings.json");
+function updateGlobalSection(mutate) {
+    const settingsPath = resolveGlobalSettingsPath();
     const raw = readSettingsObject(settingsPath);
     const existing = raw[SETTINGS_KEY];
     const section = existing && typeof existing === "object" ? { ...existing } : {};
-    if (model) {
-        section.taskModel = { provider: model.provider, id: model.id };
-    }
-    else {
-        // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key (vs setting undefined) keeps the JSON clean
-        delete section.taskModel;
-    }
+    mutate(section);
     raw[SETTINGS_KEY] = section;
     mkdirSync(dirname(settingsPath), { recursive: true });
     writeFileSync(settingsPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
 }
 /**
- * Persist the agent-trajectory flag in the PROJECT settings file
- * `<cwd>/.pi/settings.json` under the namespaced `llm-wiki` key (issue #80).
- * Mirrors `persistTaskModel`: project settings win in `loadTaskConfig`, other
- * keys are preserved. `true` writes `trajectories: true`; `false` removes the
- * key (reverting to the default-off behavior).
+ * Rewrite the `llm-wiki` section of the project settings file, preserving every
+ * other top-level key and every other setting in the section.
+ *
+ * The target file is chosen by `resolveProjectSettingsPath` — `.pi/settings.json`
+ * or `.omp/settings.json` depending on host and on what already exists — and is
+ * always JSON, which both hosts read.
  */
-export function persistTrajectoriesEnabled(cwd, enabled) {
-    const settingsPath = join(cwd, ".pi", "settings.json");
+function updateProjectSection(cwd, mutate) {
+    const settingsPath = resolveProjectSettingsPath(cwd);
     const raw = readSettingsObject(settingsPath);
     const existing = raw[SETTINGS_KEY];
     const section = existing && typeof existing === "object" ? { ...existing } : {};
-    if (enabled) {
-        section.trajectories = true;
-    }
-    else {
-        // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key keeps the JSON clean (default is off)
-        delete section.trajectories;
-    }
+    mutate(section);
     raw[SETTINGS_KEY] = section;
     mkdirSync(dirname(settingsPath), { recursive: true });
     writeFileSync(settingsPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
 }
+/**
+ * Persist (or clear) the wiki background `taskModel` in the PROJECT settings
+ * file under the namespaced `llm-wiki` key (issue #69). Project settings win
+ * over global in `loadTaskConfig`, so this takes effect immediately on the next
+ * config load. Passing `undefined` removes the key (reverting to the session
+ * model).
+ */
+export function persistTaskModel(cwd, model) {
+    updateProjectSection(cwd, (section) => {
+        if (model) {
+            section.taskModel = { provider: model.provider, id: model.id };
+        }
+        else {
+            // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key (vs setting undefined) keeps the JSON clean
+            delete section.taskModel;
+        }
+    });
+}
+/**
+ * Persist the agent-trajectory flag in the PROJECT settings file under the
+ * namespaced `llm-wiki` key (issue #80). Mirrors `persistTaskModel`: `true`
+ * writes `trajectories: true`; `false` removes the key (reverting to the
+ * default-off behavior).
+ */
+export function persistTrajectoriesEnabled(cwd, enabled) {
+    updateProjectSection(cwd, (section) => {
+        if (enabled) {
+            section.trajectories = true;
+        }
+        else {
+            // biome-ignore lint/performance/noDelete: one-off settings rewrite, not a hot path; removing the key keeps the JSON clean (default is off)
+            delete section.trajectories;
+        }
+    });
+}
+/**
+ * Merge the `llm-wiki` section from every settings file both hosts may use,
+ * lowest precedence first: built-in defaults, then user-level files, then
+ * project-level files. Absent files contribute nothing.
+ */
 export function loadTaskConfig(cwd) {
-    let globalPath;
-    try {
-        globalPath = join(getAgentDir(), "settings.json");
+    const config = { ...TASK_DEFAULTS };
+    for (const path of listGlobalSettingsFiles()) {
+        Object.assign(config, readNamespacedConfig(path));
     }
-    catch {
-        globalPath = "";
+    for (const path of listProjectSettingsFiles(cwd)) {
+        Object.assign(config, readNamespacedConfig(path));
     }
-    const projectPath = join(cwd, ".pi", "settings.json");
-    return {
-        ...TASK_DEFAULTS,
-        ...(globalPath ? readNamespacedConfig(globalPath) : {}),
-        ...readNamespacedConfig(projectPath),
+    return config;
+}
+/**
+ * Resolve where each setting is defined: project > global > default.
+ */
+/** All known setting keys — needed because TASK_DEFAULTS is {} (zero-config). */
+const KNOWN_KEYS = [
+    "taskModel",
+    "embeddingProvider",
+    "embeddingModel",
+    "embeddingBaseUrl",
+    "embeddingApiKey",
+    "embeddingApiKeyEnv",
+    "semanticWeight",
+    "recallLinksThreshold",
+    "recallSkillInlineMax",
+    "notices",
+    "ambientPersonalVault",
+    "trajectories",
+    "synthesisLanguage",
+    "synthesisMaxTokens",
+];
+export function loadTaskConfigSources(cwd) {
+    const globalResult = {};
+    for (const path of listGlobalSettingsFiles()) {
+        Object.assign(globalResult, readNamespacedConfig(path));
+    }
+    const projectResult = {};
+    for (const path of listProjectSettingsFiles(cwd)) {
+        Object.assign(projectResult, readNamespacedConfig(path));
+    }
+    const effective = loadTaskConfig(cwd);
+    const out = {};
+    for (const key of KNOWN_KEYS) {
+        if (key in projectResult)
+            out[key] = { value: projectResult[key], source: "project" };
+        else if (key in globalResult)
+            out[key] = { value: globalResult[key], source: "global" };
+        else
+            out[key] = { value: effective[key], source: "default" };
+    }
+    return out;
+}
+/**
+ * Generic setting persist: writes any single setting to the chosen scope.
+ */
+export function persistSetting(cwd, scope, key, value) {
+    const mutate = (section) => {
+        if (value === undefined || value === null) {
+            delete section[key];
+        }
+        else {
+            section[key] = value;
+        }
     };
+    if (scope === "project") {
+        updateProjectSection(cwd, mutate);
+    }
+    else if (scope === "global") {
+        updateGlobalSection(mutate);
+    }
 }

package/dist/extensions/llm-wiki/lib/utils.js

@@ -82,20 +82,46 @@ export function migrateDoubledPersonalVault(parentRoot = getPersonalWikiRoot())
 /**
  * Check if a vault is the personal wiki location.
  * Used in layered recall to avoid double-counting.
+ *
+ * Compares PHYSICAL paths, not strings. On image-based ("atomic") Linux
+ * distributions `/home` is a symlink to `var/home`, so `homedir()` yields the
+ * `$HOME` string (`/home/u`) while `process.cwd()` — and therefore the root
+ * `resolveVaultRoot()` walks up to — yields `/var/home/u`. A string compare
+ * calls the personal vault a project vault, which makes layered recall search
+ * the same vault twice and `vaultPageCount()` double-count it.
+ *
+ * Exact equality, NOT containment: a vault nested under the home directory
+ * (`~/projects/foo/.llm-wiki`) is a project vault and must stay one.
  */
 export function isPersonalVault(paths) {
-    return paths.root === getPersonalWikiRoot();
+    const personalRoot = getPersonalWikiRoot();
+    // Fast path: identical strings need no filesystem syscalls.
+    if (paths.root === personalRoot)
+        return true;
+    try {
+        return relativePhysicalPath(personalRoot, paths.root) === "";
+    }
+    catch {
+        // Unresolvable path (permissions, symlink cycle): fall back to "not
+        // personal" so layered recall degrades to searching both vaults rather
+        // than silently dropping the personal layer.
+        return false;
+    }
 }
 /**
- * Resolve vault root from cwd with personal fallback.
+ * Resolve the vault root that belongs to THIS project, or `null` when the
+ * project has none.
  *
  * Priority:
- * 1. cwd has .llm-wiki/ → project wiki (explicit)
- * 2. Walk up from cwd → parent project wiki
- * 3. ~/.llm-wiki/ exists → personal wiki
- * 4. Fallback: ~/.llm-wiki/ (create personal wiki)
+ * 1. cwd has `.llm-wiki/` (or legacy `.wiki/`) → project wiki (explicit)
+ * 2. `WIKI_HOME` → user-selected root, explicit enough to count as the project's
+ * 3. Walk up from cwd → parent project wiki (monorepo / nested workspace)
+ *
+ * Deliberately does NOT fall back to the personal wiki: callers that need the
+ * fallback use {@link resolveVaultRoot}, callers that must distinguish "this
+ * project has a wiki" from "some wiki exists somewhere" use this.
  */
-export function resolveVaultRoot(cwd) {
+export function resolveProjectVaultRoot(cwd) {
     // A vault rooted at cwd is always the project-local choice.
     if (detectVaultFormat(cwd) !== "none")
         return cwd;
@@ -103,19 +129,36 @@ export function resolveVaultRoot(cwd) {
     // over an unrelated personal vault found while walking parent directories.
     if (process.env.WIKI_HOME)
         return process.env.WIKI_HOME;
-    // Walk up looking for a vault sentinel (new or legacy)
+    // Walk up looking for a vault sentinel (new or legacy).
     let dir = cwd;
     while (dir !== dirname(dir)) {
         dir = dirname(dir);
-        if (detectVaultFormat(dir) !== "none")
-            return dir;
+        if (detectVaultFormat(dir) === "none")
+            continue;
+        // Skip the personal vault: it is an ancestor of EVERY project under the
+        // home directory (`~/projects/foo`, and on Windows even the temp dir), so
+        // counting it here would report a project vault for directories that have
+        // none. `resolveVaultRoot` still falls back to it explicitly.
+        if (isPersonalVault(getVaultPaths(dir)))
+            continue;
+        return dir;
     }
-    // Check personal wiki at ~/.llm-wiki/
-    const personalRoot = getPersonalWikiRoot();
-    if (detectVaultFormat(personalRoot) !== "none")
-        return personalRoot;
-    // Fallback: personal wiki
-    return personalRoot;
+    return null;
+}
+/**
+ * Resolve vault root from cwd with personal fallback.
+ *
+ * Priority:
+ * 1-3. {@link resolveProjectVaultRoot}
+ * 4. Personal wiki root (`~`, or `WIKI_HOME`) — used whether or not it already
+ *    holds a vault, so first-run bootstrap has somewhere to write.
+ */
+export function resolveVaultRoot(cwd) {
+    // Realpath the personal fallback so a symlinked `$HOME` (atomic-OS layouts)
+    // yields the PHYSICAL root the ancestor walk used to return — the #145
+    // regression guard pins that. `realpathWithMissingTail` also covers first-run
+    // bootstrap, where the personal root does not exist on disk yet.
+    return resolveProjectVaultRoot(cwd) ?? realpathWithMissingTail(getPersonalWikiRoot());
 }
 /** Get all vault paths for the new (.llm-wiki) layout. */
 export function getVaultPaths(root) {

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

@@ -31,17 +31,44 @@ The personal vault lives at `~/.llm-wiki/` (or `$WIKI_HOME`) and is always avail
 | ----------------------------- | ----------- | ----------------------------------------------- |
 | `WIKI_HOME`                   | `~/.llm-wiki` | Override the personal wiki vault location     |
 | `WIKI_MARKITDOWN_TIMEOUT_MS` | 180000      | Timeout (ms) for MarkItDown PDF/text extraction |
-
-## Pi Agent Settings
-
-Runtime settings for the wiki's background tasks live in `.pi/settings.json` under the `llm-wiki` namespace. These can be set globally (`~/.pi/agent/settings.json`) or per-project (`<cwd>/.pi/settings.json`).
-
-| Setting               | Default | Description                                                  |
-| --------------------- | ------- | ------------------------------------------------------------ |
-| `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. |
-| `trajectories`        | false   | Enable agent-trajectory working-memory                       |
-| `notices`             | true    | Show wiki activity notices in chat                           |
+| `LLM_WIKI_HOST`              | auto        | Force the host layout: `pi` or `omp`            |
+
+## Agent Settings
+
+Runtime settings for the wiki's background tasks live under the `llm-wiki`
+namespace of the host's settings file. Both host layouts are read and merged,
+lowest precedence first:
+
+1. `<agentDir>/settings.json`, then `config.yml` / `config.yaml`
+   — `~/.pi/agent` under pi, `~/.omp/agent` under oh-my-pi
+2. `<cwd>/.pi/{settings.json,config.yml,config.yaml}`
+3. `<cwd>/.omp/{settings.json,config.yml,config.yaml}`
+
+The **host-native** project directory is applied last, so it wins: `.omp` under
+oh-my-pi, `.pi` under pi. Reading the other host's directory means a vault
+configured under pi keeps working after `omp` takes over the repository.
+
+`/wiki-model` and `/wiki-trajectories` write JSON only, into whichever project
+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)                        |
+| `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:
 
@@ -66,6 +93,30 @@ The vault root is resolved in this priority order:
 
 This means when you're in a project with its own `.llm-wiki/`, that project wiki is active. When you're outside any project wiki, your personal `~/.llm-wiki/` takes over automatically.
 
+### Ambient surfaces in projects without a wiki
+
+Three surfaces fire without being asked: the session notice, the periodic
+observe/retro reminder, and the `before_agent_start` recall injection (plus its
+`<wiki_status>` system-prompt footer).
+
+Because vault resolution falls back to the personal vault, those surfaces would
+otherwise speak up in *every* directory as soon as `~/.llm-wiki/` exists —
+injecting reminders and unrelated cross-project recall hits into repositories
+where no wiki was ever initialized. Under oh-my-pi the plugin is installed once
+and loads in every project, so that fallback is **off** by default there; under
+pi the historical behaviour is kept.
+
+`ambientPersonalVault` overrides the host default in either direction:
+
+```json
+{ "llm-wiki": { "ambientPersonalVault": true } }
+```
+
+The gate only affects unprompted injections. Tools and slash commands are
+always registered, so `/wiki-init` and `wiki_bootstrap` work in any directory —
+and once a project has its own `.llm-wiki/`, every ambient surface turns back on
+for it.
+
 ## Page Frontmatter
 
 ```yaml