@zosmaai/pi-llm-wiki 0.11.3 → 0.11.4

package/extensions/llm-wiki/lib/task-config.ts

@@ -1,6 +1,13 @@
 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 {
+  type HostKind,
+  detectHost,
+  listGlobalSettingsFiles,
+  listProjectSettingsFiles,
+  resolveProjectSettingsPath,
+} from "./host.js";
 
 /**
  * Configuration for the background-task lane (issue #64, part of #63).
@@ -12,8 +19,11 @@ import { getAgentDir } from "@mariozechner/pi-coding-agent";
  *
  * Resolution order (later wins):
  *   1. built-in DEFAULTS
- *   2. global settings:  <agentDir>/settings.json  → { "llm-wiki": { ... } }
- *   3. project settings: <cwd>/.pi/settings.json    → { "llm-wiki": { ... } }
+ *   2. global settings:  <agentDir>/{settings.json,config.yml}
+ *   3. project settings: <cwd>/{.pi,.omp}/{settings.json,config.yml}
+ *
+ * Both host layouts are read (see ./host.ts): pi uses `.pi`, oh-my-pi uses
+ * `.omp`, and each file is keyed by the namespaced `llm-wiki` section.
  *
  * When `taskModel` is unset, the background lane falls back to the session
  * model (see Runtime.resolveModel), so the feature is zero-config by default.
@@ -93,6 +103,27 @@ export interface TaskConfig {
    */
   notices?: boolean;
 
+  /**
+   * Let the PERSONAL wiki act as this project's ambient vault when the project
+   * has no wiki of its own.
+   *
+   * Ambient surfaces are the ones that fire without the user asking: the
+   * session notice, the periodic observe/retro reminder, and `before_agent_start`
+   * recall injection. `resolveVaultRoot` falls back to the personal vault when
+   * a project has none, so with this on those surfaces speak up in EVERY
+   * directory once a personal vault exists — injecting reminders and unrelated
+   * cross-project recall hits into repositories where no wiki was initialized.
+   *
+   * Host-dependent default, because the two hosts disagree on what silence
+   * means for a globally installed plugin:
+   *   - pi  → `true`  (historical behavior, unchanged)
+   *   - omp → `false` (a repository without a wiki stays quiet)
+   *
+   * The wiki TOOLS are registered either way, so `/wiki-init` and
+   * `wiki_bootstrap` always work; only the unprompted injections are gated.
+   */
+  ambientPersonalVault?: boolean;
+
   /**
    * Agent-trajectory working-memory (capture → distill → recall), issue #80.
    * OPT-IN, default OFF: only an explicit `trajectories: true` enables it.
@@ -120,6 +151,19 @@ export function noticesEnabled(config: TaskConfig | undefined): boolean {
   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: TaskConfig | undefined,
+  host: HostKind = detectHost(),
+): boolean {
+  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
@@ -180,6 +224,10 @@ function readNamespacedConfig(path: string): Partial<TaskConfig> {
       out.notices = section.notices;
     }
 
+    if (typeof section.ambientPersonalVault === "boolean") {
+      out.ambientPersonalVault = section.ambientPersonalVault;
+    }
+
     if (typeof section.trajectories === "boolean") {
       out.trajectories = section.trajectories;
     }
@@ -235,14 +283,20 @@ export function validateSynthesisLanguage(tag: string): string | undefined {
 }
 
 /**
- * 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: string): Record<string, unknown> {
   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 as Record<string, unknown>;
   } catch {
     // Missing or corrupt settings file: start from an empty object.
@@ -251,30 +305,25 @@ function readSettingsObject(path: string): Record<string, unknown> {
 }
 
 /**
- * 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 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 persistTaskModel(
+function updateProjectSection(
   cwd: string,
-  model: { provider: string; id: string } | undefined,
+  mutate: (section: Record<string, unknown>) => void,
 ): void {
-  const settingsPath = join(cwd, ".pi", "settings.json");
+  const settingsPath = resolveProjectSettingsPath(cwd);
   const raw = readSettingsObject(settingsPath);
 
   const existing = raw[SETTINGS_KEY];
   const section: Record<string, unknown> =
     existing && typeof existing === "object" ? { ...(existing as Record<string, unknown>) } : {};
 
-  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 });
@@ -282,44 +331,55 @@ export function persistTaskModel(
 }
 
 /**
- * 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).
+ * 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 persistTrajectoriesEnabled(cwd: string, enabled: boolean): void {
-  const settingsPath = join(cwd, ".pi", "settings.json");
-  const raw = readSettingsObject(settingsPath);
-
-  const existing = raw[SETTINGS_KEY];
-  const section: Record<string, unknown> =
-    existing && typeof existing === "object" ? { ...(existing as Record<string, unknown>) } : {};
-
-  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;
-  }
-  raw[SETTINGS_KEY] = section;
+export function persistTaskModel(
+  cwd: string,
+  model: { provider: string; id: string } | undefined,
+): void {
+  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;
+    }
+  });
+}
 
-  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 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: string, enabled: boolean): void {
+  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: string): TaskConfig {
-  let globalPath: string;
-  try {
-    globalPath = join(getAgentDir(), "settings.json");
-  } catch {
-    globalPath = "";
+  const config: TaskConfig = { ...TASK_DEFAULTS };
+  for (const path of listGlobalSettingsFiles()) {
+    Object.assign(config, readNamespacedConfig(path));
   }
-  const projectPath = join(cwd, ".pi", "settings.json");
-
-  return {
-    ...TASK_DEFAULTS,
-    ...(globalPath ? readNamespacedConfig(globalPath) : {}),
-    ...readNamespacedConfig(projectPath),
-  };
+  for (const path of listProjectSettingsFiles(cwd)) {
+    Object.assign(config, readNamespacedConfig(path));
+  }
+  return config;
 }

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

@@ -120,21 +120,45 @@ export function migrateDoubledPersonalVault(
 /**
  * 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: VaultPaths): boolean {
-  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: string): string {
+export function resolveProjectVaultRoot(cwd: string): string | null {
   // A vault rooted at cwd is always the project-local choice.
   if (detectVaultFormat(cwd) !== "none") return cwd;
 
@@ -142,19 +166,36 @@ export function resolveVaultRoot(cwd: string): string {
   // 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;
+  return null;
+}
 
-  // Fallback: personal wiki
-  return personalRoot;
+/**
+ * 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: string): string {
+  // 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. */

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "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",
     "pi-package",
     "pi-extension",
     "pi-skill",
+    "omp",
+    "oh-my-pi",
+    "omp-plugin",
+    "omp-extension",
     "llm-wiki",
     "karpathy",
     "knowledge-base",
@@ -37,6 +41,7 @@
     "extensions",
     "skills",
     "prompts",
+    "commands",
     "scripts/migrate-llm-wiki.js",
     "mcp",
     "dist",
@@ -64,6 +69,11 @@
       "llm-wiki": "node ./dist/mcp/index.js"
     }
   },
+  "omp": {
+    "extensions": [
+      "./extensions/llm-wiki/index.ts"
+    ]
+  },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "typebox": "*"
@@ -96,6 +106,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "build:commands": "node scripts/build-commands.js",
     "build:mcp": "node scripts/build-mcp.js",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",