skillwiki 0.9.47 → 0.9.49

package/dist/{chunk-MI4BZI7Q.js → chunk-4Q7MANQI.js}

@@ -659,6 +659,7 @@ import { writeFile as writeFile2, mkdir } from "fs/promises";
 import { dirname } from "path";
 
 // src/utils/vault.ts
+import { existsSync, readFileSync } from "fs";
 import { readFile as readFile2, readdir, stat } from "fs/promises";
 import { join as join2, relative as relative2, sep as sep2 } from "path";
 var TYPED_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
@@ -668,6 +669,40 @@ function vaultIoConcurrency() {
   const raw = Number.parseInt(process.env.SKILLWIKI_VAULT_IO_CONCURRENCY ?? "", 10);
   return Number.isFinite(raw) && raw > 0 ? Math.min(raw, 64) : DEFAULT_IO_CONCURRENCY;
 }
+function decodeProcMountPath(value) {
+  return value.replace(/\\040/g, " ");
+}
+function isRcloneFuseVaultFromMounts(root, mounts) {
+  return mounts.split(/\r?\n/).some((line) => {
+    const parts = line.split(" ");
+    if (parts.length < 3) return false;
+    const mountPoint = decodeProcMountPath(parts[1]);
+    const fsType = parts[2];
+    return fsType === "fuse.rclone" && (root === mountPoint || root.startsWith(`${mountPoint}/`));
+  });
+}
+function resolveReadOnlyVaultRootWithMounts(root, mounts) {
+  if (/^(1|true|yes)$/i.test(process.env.SKILLWIKI_DISABLE_VAULT_READ_MIRROR ?? "")) {
+    return { root, mirrored: false };
+  }
+  const explicitMirror = process.env.SKILLWIKI_VAULT_READ_MIRROR;
+  if (explicitMirror && existsSync(join2(explicitMirror, "SCHEMA.md"))) {
+    return { root: explicitMirror, mirrored: explicitMirror !== root };
+  }
+  const siblingMirror = `${root}-git`;
+  if (isRcloneFuseVaultFromMounts(root, mounts) && existsSync(join2(siblingMirror, "SCHEMA.md"))) {
+    return { root: siblingMirror, mirrored: true };
+  }
+  return { root, mirrored: false };
+}
+function resolveReadOnlyVaultRoot(root) {
+  let mounts = "";
+  try {
+    mounts = readFileSync("/proc/mounts", "utf8");
+  } catch {
+  }
+  return resolveReadOnlyVaultRootWithMounts(root, mounts);
+}
 async function mapWithConcurrency(items, limit, mapper) {
   const out = new Array(items.length);
   let next = 0;
@@ -1334,7 +1369,7 @@ function hasWikilinkCitations(body) {
 }
 
 // src/utils/raw-source.ts
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { stat as stat2 } from "fs/promises";
 import { join as join4 } from "path";
 function normalizeRawSourceTarget(entry) {
@@ -1355,7 +1390,7 @@ function rawSourceTargetCandidates(vault, target) {
   return [...new Set(candidates)];
 }
 function rawSourceTargetExistsSync(vault, target) {
-  return rawSourceTargetCandidates(vault, target).some((candidate) => existsSync(candidate));
+  return rawSourceTargetCandidates(vault, target).some((candidate) => existsSync2(candidate));
 }
 async function rawSourceTargetExists(vault, target) {
   for (const candidate of rawSourceTargetCandidates(vault, target)) {
@@ -1666,7 +1701,7 @@ function parseExpiryAnnotations(content, pagePath) {
 }
 
 // src/utils/last-op.ts
-import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync, unlinkSync, existsSync as existsSync3 } from "fs";
 import { join as join8 } from "path";
 var LAST_OP_DIR = ".skillwiki";
 var LAST_OP_FILE = "last-op.json";
@@ -1675,9 +1710,9 @@ function lastOpPath(vault) {
 }
 function readLastOp(vault) {
   const p = lastOpPath(vault);
-  if (!existsSync2(p)) return [];
+  if (!existsSync3(p)) return [];
   try {
-    const raw = readFileSync(p, "utf8");
+    const raw = readFileSync2(p, "utf8");
     const parsed = JSON.parse(raw);
     if (!Array.isArray(parsed)) {
       unlinkSync(p);
@@ -1696,7 +1731,7 @@ function appendLastOp(vault, entry) {
   const existing = readLastOp(vault);
   existing.push(entry);
   const dir = join8(vault, LAST_OP_DIR);
-  if (!existsSync2(dir)) mkdirSync(dir, { recursive: true });
+  if (!existsSync3(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(lastOpPath(vault), JSON.stringify(existing, null, 2), "utf8");
 }
 function clearLastOp(vault) {
@@ -2142,7 +2177,7 @@ ${markdown_links.map((l) => `  line ${l.line}: ${l.text}`).join("\n")}`;
 
 // src/commands/dedup.ts
 import { createHash as createHash2 } from "crypto";
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2 } from "fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2 } from "fs";
 import { dirname as dirname4, join as join12, resolve as resolve3 } from "path";
 
 // src/utils/rclone.ts
@@ -2262,7 +2297,7 @@ async function runDedup(input) {
       }
     }
     for (const page of scan.allMarkdown.filter((p) => !p.relPath.startsWith("raw/"))) {
-      const text = readFileSync2(join12(input.vault, page.relPath), "utf-8");
+      const text = readFileSync3(join12(input.vault, page.relPath), "utf-8");
       let updated = text;
       let changed = false;
       for (const [oldPath, newPath] of replacements) {
@@ -2379,14 +2414,14 @@ function buildSafeEntries(vault, duplicates, unsafe) {
   return entries;
 }
 function hashRawBody(vault, relPath) {
-  const text = readFileSync2(join12(vault, relPath), "utf-8");
+  const text = readFileSync3(join12(vault, relPath), "utf-8");
   const split = splitFrontmatter(text);
   const body = split.ok ? split.data.body : text;
   return createHash2("sha256").update(body).digest("hex");
 }
 function readManifest(path) {
   try {
-    const parsed = JSON.parse(readFileSync2(path, "utf-8"));
+    const parsed = JSON.parse(readFileSync3(path, "utf-8"));
     if (parsed.version !== 1 || !Array.isArray(parsed.entries)) {
       return err("INVALID_FRONTMATTER", { message: "dedup manifest must have version 1 and entries[]" });
     }
@@ -2553,7 +2588,7 @@ ${newBody}`;
 }
 
 // src/commands/lint.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 import { readFile as readFile12, readdir as readdir3 } from "fs/promises";
 import { createHash as createHash4 } from "crypto";
 import { join as join15, relative as relative3, sep as sep3 } from "path";
@@ -2613,7 +2648,7 @@ async function runRawBodyDedup(vault, scan, pageTextCache) {
 }
 
 // src/commands/path-too-long.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { mkdir as mkdir4, readFile as readFile11, rename as rename4, unlink as unlink2 } from "fs/promises";
 import { dirname as dirname6, join as join14, posix, resolve as resolve4 } from "path";
 var MAX_PATH_LENGTH = 240;
@@ -2729,7 +2764,7 @@ async function resolveFixTarget(vault, original, preferred, maxLength) {
   for (const candidate of candidateRelPaths(preferred, maxLength)) {
     if (candidate === original || candidate.length > maxLength) continue;
     const candidatePath = join14(vault, candidate);
-    if (!existsSync3(candidatePath)) return { relPath: candidate, mode: "rename" };
+    if (!existsSync4(candidatePath)) return { relPath: candidate, mode: "rename" };
     if (await hasSameContent(join14(vault, original), candidatePath)) {
       return { relPath: candidate, mode: "dedupe" };
     }
@@ -3126,6 +3161,9 @@ ${match.length === 0 ? "0 violations" : match.map((b) => `  ${b.kind}: ${b.items
     result: ok(input.summary ? summarizeLintOutput(output, input.examplesLimit) : output)
   };
 }
+function lintReadVault(input) {
+  return input.fix ? input.vault : resolveReadOnlyVaultRoot(input.vault).root;
+}
 function recomputeRawSha256IfPresent(content) {
   const split = splitFrontmatter(content);
   if (!split.ok) return content;
@@ -3188,19 +3226,20 @@ async function walkMarkdownFiles(absDir, vaultRoot) {
   return pages;
 }
 async function collectCliRefsPages(vault) {
-  if (!existsSync4(join15(vault, "SCHEMA.md"))) {
+  if (!existsSync5(join15(vault, "SCHEMA.md"))) {
     return err("VAULT_PATH_INVALID", { root: vault, reason: "SCHEMA.md missing" });
   }
   const pages = [];
   for (const dir of CLI_REFS_TYPED_DIRS) {
     const absDir = join15(vault, dir);
-    if (!existsSync4(absDir)) continue;
+    if (!existsSync5(absDir)) continue;
     pages.push(...await walkMarkdownFiles(absDir, vault));
   }
   return ok(pages);
 }
 async function runCliRefsOnly(input) {
-  const pages = await collectCliRefsPages(input.vault);
+  const lintVault = lintReadVault(input);
+  const pages = await collectCliRefsPages(lintVault);
   if (!pages.ok) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: pages };
   }
@@ -3358,7 +3397,8 @@ async function applyFileSourceUrlFix(input, scan, fileSourceUrlFlags, fileSource
   return remaining;
 }
 async function runFileSourceUrlOnly(input) {
-  const scanResult = await scanVault(input.vault);
+  const lintVault = lintReadVault(input);
+  const scanResult = await scanVault(lintVault);
   if (!scanResult.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scanResult };
   const pageTextCache = /* @__PURE__ */ new Map();
   const fixed = [];
@@ -3389,10 +3429,11 @@ async function runLint(input) {
     return runFileSourceUrlOnly(input);
   }
   const shouldFix = (bucket) => !!input.fix && (!input.only || input.only === bucket);
+  const lintVault = lintReadVault(input);
   const buckets = {};
   const fixed = [];
   const unresolved = [];
-  const scanResult = await scanVault(input.vault);
+  const scanResult = await scanVault(lintVault);
   if (!scanResult.ok) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scanResult };
   }
@@ -3406,64 +3447,64 @@ async function runLint(input) {
       }
     });
   }
-  const links = await runLinks({ vault: input.vault, scan, pageTextCache });
+  const links = await runLinks({ vault: lintVault, scan, pageTextCache });
   if (links.result.ok && links.result.data.broken.length > 0) buckets.broken_wikilinks = links.result.data.broken;
   if (!links.result.ok && links.result.error === "INVALID_FRONTMATTER") {
     buckets.invalid_frontmatter = [links.result.detail ?? {}];
   }
-  const tags = await runTagAudit({ vault: input.vault, scan, pageTextCache });
+  const tags = await runTagAudit({ vault: lintVault, scan, pageTextCache });
   if (tags.result.ok && tags.result.data.violations.length > 0) buckets.tag_not_in_taxonomy = tags.result.data.violations;
   if (!tags.result.ok && tags.result.error === "INVALID_FRONTMATTER") {
     buckets.invalid_frontmatter = [...buckets.invalid_frontmatter ?? [], tags.result.detail ?? {}];
   }
-  const idx = await runIndexCheck({ vault: input.vault, scan });
+  const idx = await runIndexCheck({ vault: lintVault, scan });
   if (idx.result.ok && (idx.result.data.missing_from_index.length > 0 || idx.result.data.ghost_entries.length > 0)) {
     buckets.index_incomplete = [{
       missing_from_index: idx.result.data.missing_from_index,
       ghost_entries: idx.result.data.ghost_entries
     }];
   }
-  const linkFmt = await runIndexLinkFormat({ vault: input.vault });
+  const linkFmt = await runIndexLinkFormat({ vault: lintVault });
   if (linkFmt.result.ok && linkFmt.result.data.markdown_links.length > 0) {
     buckets.index_link_format = linkFmt.result.data.markdown_links;
   }
-  const staleResult = await runStale({ vault: input.vault, days: input.days, scan, pageTextCache });
+  const staleResult = await runStale({ vault: lintVault, days: input.days, scan, pageTextCache });
   if (staleResult.result.ok) {
     const st = staleResult.result.data;
     const staleList = [...st.stale_transcripts.map((t) => t.path), ...(st.unclaimed_transcripts ?? []).map((t) => t.path), ...st.incomplete_work_items.map((w) => w.path), ...(st.done_work_items ?? []).map((w) => w.path)];
     if (staleList.length > 0) buckets.stale_page = staleList;
   }
-  const pagesize = await runPagesize({ vault: input.vault, lines: input.lines, scan, pageTextCache });
+  const pagesize = await runPagesize({ vault: lintVault, lines: input.lines, scan, pageTextCache });
   if (pagesize.result.ok && pagesize.result.data.oversized.length > 0) buckets.page_too_large = pagesize.result.data.oversized;
-  const rotate = await runLogRotate({ vault: input.vault, threshold: input.logThreshold, apply: false });
+  const rotate = await runLogRotate({ vault: lintVault, threshold: input.logThreshold, apply: false });
   if (rotate.result.ok && rotate.exitCode === ExitCode.LOG_ROTATE_NEEDED) {
     buckets.log_rotate_needed = [{ entries: rotate.result.data.entries, threshold: rotate.result.data.threshold }];
   }
-  const orphans = await runOrphans({ vault: input.vault, scan, pageTextCache });
+  const orphans = await runOrphans({ vault: lintVault, scan, pageTextCache });
   if (orphans.result.ok) {
     if (orphans.result.data.orphans.length > 0) buckets.orphans = orphans.result.data.orphans;
     if (orphans.result.data.bridges.length > 0) buckets.bridges = orphans.result.data.bridges;
   }
-  const sparse = await runSparseCommunity({ vault: input.vault, scan, pageTextCache });
+  const sparse = await runSparseCommunity({ vault: lintVault, scan, pageTextCache });
   if (sparse.result.ok && sparse.result.data.communities.length > 0) {
     buckets.sparse_community = sparse.result.data.communities;
   }
-  const topicMap = await runTopicMapCheck({ vault: input.vault, scan });
+  const topicMap = await runTopicMapCheck({ vault: lintVault, scan });
   if (topicMap.result.ok && topicMap.result.data.recommended) {
     buckets.topic_map_recommended = [{ page_count: topicMap.result.data.page_count, threshold: topicMap.result.data.threshold }];
   }
-  const dedup = await runDedup({ vault: input.vault, scan, pageTextCache });
+  const dedup = await runDedup({ vault: lintVault, scan, pageTextCache });
   if (dedup.result.ok && dedup.result.data.duplicates.length > 0) buckets.raw_dedup = dedup.result.data.duplicates;
-  const bodyDedup = await runRawBodyDedup(input.vault, scan, pageTextCache);
+  const bodyDedup = await runRawBodyDedup(lintVault, scan, pageTextCache);
   if (bodyDedup.result.ok && bodyDedup.result.data.duplicates.length > 0) {
     buckets.raw_body_duplicate = bodyDedup.result.data.duplicates.map((d) => ({
       body_hash: d.bodyHash.slice(0, 12),
       files: d.files.map((f) => `${f.relPath} (sha256: ${f.sha256 ?? "none"})`)
     }));
   }
-  const compoundRefs = await validateCompoundReferences(input.vault, scan, pageTextCache);
+  const compoundRefs = await validateCompoundReferences(lintVault, scan, pageTextCache);
   if (compoundRefs.ok && compoundRefs.data.length > 0) buckets.compound_refs = compoundRefs.data;
-  const pathCheck = await runPathTooLong({ vault: input.vault, scan });
+  const pathCheck = await runPathTooLong({ vault: lintVault, scan });
   if (pathCheck.result.ok && pathCheck.result.data.violations.length > 0) buckets.path_too_long = pathCheck.result.data.violations;
   const allPages = [...scan.typedKnowledge, ...scan.raw, ...scan.workItems, ...scan.compound];
   const slugs = buildSlugMap(allPages);
@@ -3553,12 +3594,12 @@ async function runLint(input) {
         for (const entry of sourcesEntries) {
           const rawPath = normalizeRawSourceTarget(entry);
           if (!rawPath) continue;
-          if (!rawSourceTargetExistsSync(input.vault, rawPath)) {
+          if (!rawSourceTargetExistsSync(lintVault, rawPath)) {
             result.brokenSourceFlags.push(`${page.relPath}: ${rawPath}`);
           }
         }
         for (const marker of extractCitationMarkers(body)) {
-          if (!rawSourceTargetExistsSync(input.vault, marker.target)) {
+          if (!rawSourceTargetExistsSync(lintVault, marker.target)) {
             result.brokenSourceFlags.push(`${page.relPath}: ${marker.target}`);
           }
         }
@@ -3661,8 +3702,8 @@ async function runLint(input) {
     const readKnowledgeContent = (slug) => {
       const existing = knowledgeContentCache.get(slug);
       if (existing) return existing;
-      const knowledgePath = join15(input.vault, "projects", slug, "knowledge.md");
-      const pending = existsSync4(knowledgePath) ? readFile12(knowledgePath, "utf8").catch(() => null) : Promise.resolve(null);
+      const knowledgePath = join15(lintVault, "projects", slug, "knowledge.md");
+      const pending = existsSync5(knowledgePath) ? readFile12(knowledgePath, "utf8").catch(() => null) : Promise.resolve(null);
       knowledgeContentCache.set(slug, pending);
       return pending;
     };
@@ -4145,7 +4186,7 @@ ${split.data.body}`;
 
 // src/commands/config.ts
 import { readFile as readFile13 } from "fs/promises";
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import { join as join16 } from "path";
 function validateKey(key) {
   return CONFIG_KEYS.includes(key) || isValidWikiProfileKey(key);
@@ -4201,11 +4242,11 @@ async function runConfigList(input) {
 }
 async function runConfigPath(input) {
   const filePath = configPath(input.home);
-  return { exitCode: ExitCode.OK, result: ok({ path: filePath, exists: existsSync5(filePath), humanHint: filePath }) };
+  return { exitCode: ExitCode.OK, result: ok({ path: filePath, exists: existsSync6(filePath), humanHint: filePath }) };
 }
 
 // src/utils/auto-update.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync6, mkdirSync as mkdirSync3 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync7, mkdirSync as mkdirSync3 } from "fs";
 import { join as join17, dirname as dirname7 } from "path";
 import { spawn } from "child_process";
 function cachePath(home) {
@@ -4213,7 +4254,7 @@ function cachePath(home) {
 }
 function readCacheRaw(home) {
   try {
-    const raw = readFileSync3(cachePath(home), "utf8");
+    const raw = readFileSync4(cachePath(home), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -4253,7 +4294,7 @@ function triggerAutoUpdate(home, currentVersion) {
   if (!isStale) return;
   const distTag = distTagFromCache(home);
   const bgScript = new URL("../auto-update-bg.js", import.meta.url).pathname;
-  if (!existsSync6(bgScript)) return;
+  if (!existsSync7(bgScript)) return;
   const child = spawn(process.execPath, [bgScript, home, currentVersion, distTag], {
     detached: true,
     stdio: "ignore"
@@ -4717,20 +4758,20 @@ function safeUserName() {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync10, lstatSync, readlinkSync, readdirSync as readdirSync2, statSync, readFileSync as readFileSync7 } from "fs";
+import { existsSync as existsSync11, lstatSync, readlinkSync, readdirSync as readdirSync2, statSync, readFileSync as readFileSync8 } from "fs";
 import { join as join22, resolve as resolve5 } from "path";
 import { execSync as execSync2 } from "child_process";
 import { platform as platform2 } from "os";
 
 // src/utils/plugin-registry.ts
-import { existsSync as existsSync7, readdirSync, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync8, readdirSync, readFileSync as readFileSync5 } from "fs";
 import { join as join19 } from "path";
 var REGISTRY_PATH = join19(".claude", "plugins", "installed_plugins.json");
 var CODEX_CONFIG_PATH = join19(".codex", "config.toml");
 var PLUGIN_KEY = "skillwiki@llm-wiki";
 function readInstalledPlugins(home) {
   try {
-    const raw = readFileSync4(join19(home, REGISTRY_PATH), "utf8");
+    const raw = readFileSync5(join19(home, REGISTRY_PATH), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -4767,7 +4808,7 @@ function findCodexPlugin(home, key, pluginName, marketplace) {
   const config = readCodexPluginConfig(home, key, marketplace);
   if (!config?.enabled) return null;
   const cacheRoot = join19(home, ".codex", "plugins", "cache", marketplace, pluginName);
-  if (!existsSync7(cacheRoot)) return null;
+  if (!existsSync8(cacheRoot)) return null;
   let versions;
   try {
     versions = readdirSync(cacheRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
@@ -4799,7 +4840,7 @@ function parsePluginKey(key) {
 function readCodexPluginConfig(home, key, marketplace) {
   let raw;
   try {
-    raw = readFileSync4(join19(home, CODEX_CONFIG_PATH), "utf8");
+    raw = readFileSync5(join19(home, CODEX_CONFIG_PATH), "utf8");
   } catch {
     return null;
   }
@@ -4841,7 +4882,7 @@ function parseTomlScalar(rawValue) {
 }
 
 // src/utils/satellite-run-health.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "fs";
 import { join as join20 } from "path";
 var SATELLITE_STALE_MS = 26 * 60 * 60 * 1e3;
 function satelliteLatestRunPath(vault) {
@@ -4867,9 +4908,9 @@ function readSatelliteLatestRunFromText(text) {
 }
 function readSatelliteLatestRun(vault) {
   const latestPath = satelliteLatestRunPath(vault);
-  if (!existsSync8(latestPath)) return null;
+  if (!existsSync9(latestPath)) return null;
   try {
-    return parseLatestRunFile(readFileSync5(latestPath, "utf8"));
+    return parseLatestRunFile(readFileSync6(latestPath, "utf8"));
   } catch {
     return null;
   }
@@ -4898,7 +4939,7 @@ function evaluateSatelliteRunHealth(vault, now) {
 // src/utils/s3-mount-health.ts
 import { execSync } from "child_process";
 import { platform } from "os";
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync4, unlinkSync as unlinkSync3, readFileSync as readFile15 } from "fs";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync4, unlinkSync as unlinkSync3, readFileSync as readFile15 } from "fs";
 import { join as join21 } from "path";
 var OS = platform();
 function findRcloneMountPid() {
@@ -4983,7 +5024,7 @@ function extractRcloneFs(args) {
 function getRcloneArgs(pid) {
   try {
     if (OS === "linux") {
-      const raw = readFileSync6(`/proc/${pid}/cmdline`);
+      const raw = readFileSync7(`/proc/${pid}/cmdline`);
       return new TextDecoder().decode(raw).split("\0").filter(Boolean);
     } else {
       const out = execSync(`ps -o args= -p ${pid}`, {
@@ -5026,7 +5067,7 @@ function queryRcloneRC(rcAddr, fs) {
 function detectFuseMount(vaultPath) {
   try {
     if (OS === "linux") {
-      const mounts = readFileSync6("/proc/mounts", "utf8");
+      const mounts = readFileSync7("/proc/mounts", "utf8");
       let best = null;
       for (const line of mounts.split("\n")) {
         const parts = line.split(" ");
@@ -5158,12 +5199,12 @@ function detectCliChannels(argv, home) {
   const plugin = findPlugin(home);
   if (plugin) {
     const pluginBin = join22(plugin.installPath, "bin", "skillwiki");
-    if (existsSync10(pluginBin)) {
+    if (existsSync11(pluginBin)) {
       channels.push({ name: "plugin", path: pluginBin, isDevLink: false });
     }
   }
   const installBin = join22(home, ".claude", "skills", "bin", "skillwiki");
-  if (existsSync10(installBin)) {
+  if (existsSync11(installBin)) {
     channels.push({ name: "install", path: installBin, isDevLink: false });
   }
   return channels;
@@ -5224,7 +5265,7 @@ function isDevSourceRun(argv) {
 }
 async function checkConfigFile(home) {
   const cfgPath = configPath(home);
-  if (!existsSync10(cfgPath)) {
+  if (!existsSync11(cfgPath)) {
     return check("warn", "config_file", "Config file exists", `${cfgPath} not found`);
   }
   try {
@@ -5239,7 +5280,7 @@ function checkWikiPathExists(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "wiki_path_exists", "Vault directory exists", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (existsSync10(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+  if (existsSync11(resolvedPath) && statSync(resolvedPath).isDirectory()) {
     return check("pass", "wiki_path_exists", "Vault directory exists", resolvedPath);
   }
   return check("error", "wiki_path_exists", "Vault directory exists", `${resolvedPath} does not exist or is not a directory`);
@@ -5248,13 +5289,13 @@ function checkVaultStructure(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync10(resolvedPath)) {
+  if (!existsSync11(resolvedPath)) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
   }
   const missing = [];
-  if (!existsSync10(join22(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  if (!existsSync11(join22(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
   for (const dir of ["raw", "entities", "concepts", "meta"]) {
-    if (!existsSync10(join22(resolvedPath, dir))) missing.push(dir + "/");
+    if (!existsSync11(join22(resolvedPath, dir))) missing.push(dir + "/");
   }
   if (missing.length === 0) {
     return check("pass", "vault_structure", "Vault structure valid", "All required files and directories present");
@@ -5263,7 +5304,7 @@ function checkVaultStructure(resolvedPath) {
 }
 function checkSkillsInstalled(home, cwd) {
   const srcDir = cwd ? join22(cwd, "packages", "skills") : void 0;
-  if (srcDir && existsSync10(srcDir)) {
+  if (srcDir && existsSync11(srcDir)) {
     const found = findInstalledSkillMd(srcDir);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (source)`);
@@ -5277,7 +5318,7 @@ function checkSkillsInstalled(home, cwd) {
     }
   }
   const skillsDir = join22(home, ".claude", "skills");
-  if (existsSync10(skillsDir)) {
+  if (existsSync11(skillsDir)) {
     const found = findInstalledSkillMd(skillsDir);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (CLI install)`);
@@ -5394,7 +5435,7 @@ async function checkProfiles(home) {
 async function checkProjectLocalOverride(cwd) {
   const dir = cwd ?? process.cwd();
   const envPath = join22(dir, ".skillwiki", ".env");
-  if (existsSync10(envPath)) {
+  if (existsSync11(envPath)) {
     return check("pass", "project_local", "Project-local config", `Found: ${envPath}`);
   }
   return check("pass", "project_local", "Project-local config", "None");
@@ -5403,7 +5444,7 @@ function checkVaultGitRemote(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "vault_git_remote", "Vault git remote", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync10(join22(resolvedPath, ".git"))) {
+  if (!existsSync11(join22(resolvedPath, ".git"))) {
     return check("warn", "vault_git_remote", "Vault git remote", "Vault is not a git repository \u2014 sync features unavailable");
   }
   try {
@@ -5426,9 +5467,9 @@ function checkObsidianTemplates(resolvedPath) {
     return check("error", "obsidian_templates", "Obsidian templates", "Cannot check \u2014 WIKI_PATH not resolved");
   }
   const missing = [];
-  if (!existsSync10(join22(resolvedPath, "_Templates"))) missing.push("_Templates/");
-  if (!existsSync10(join22(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
-  if (!existsSync10(join22(resolvedPath, ".obsidian", "app.json"))) missing.push(".obsidian/app.json");
+  if (!existsSync11(join22(resolvedPath, "_Templates"))) missing.push("_Templates/");
+  if (!existsSync11(join22(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
+  if (!existsSync11(join22(resolvedPath, ".obsidian", "app.json"))) missing.push(".obsidian/app.json");
   if (missing.length === 0) {
     return check("pass", "obsidian_templates", "Obsidian templates", "Template folder and config present");
   }
@@ -5439,7 +5480,7 @@ function checkDotStoreClean(resolvedPath) {
     return check("error", "dsstore_clean", "No .DS_Store in raw/", "Cannot check \u2014 WIKI_PATH not resolved");
   }
   const rawDir = join22(resolvedPath, "raw");
-  if (!existsSync10(rawDir)) {
+  if (!existsSync11(rawDir)) {
     return check("pass", "dsstore_clean", "No .DS_Store in raw/", "raw/ directory not found \u2014 check skipped");
   }
   const found = [];
@@ -5467,7 +5508,7 @@ function checkSyncLastPush(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "sync_last_push", "Vault sync recency", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync10(join22(resolvedPath, ".git"))) {
+  if (!existsSync11(join22(resolvedPath, ".git"))) {
     return check("pass", "sync_last_push", "Vault sync recency", "No git repo \u2014 sync check skipped");
   }
   let timestamp;
@@ -5515,7 +5556,7 @@ function checkVaultGitDirty(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("pass", "vault_git_dirty", "Vault git dirty state", "No vault path \u2014 check skipped");
   }
-  if (!existsSync10(join22(resolvedPath, ".git"))) {
+  if (!existsSync11(join22(resolvedPath, ".git"))) {
     return check("pass", "vault_git_dirty", "Vault git dirty state", "No git repo \u2014 check skipped");
   }
   try {
@@ -5583,7 +5624,7 @@ function remoteMainHash(resolvedPath) {
 }
 function checkStaleRemoteMain(resolvedPath) {
   if (resolvedPath === void 0) return void 0;
-  if (!existsSync10(join22(resolvedPath, ".git"))) return void 0;
+  if (!existsSync11(join22(resolvedPath, ".git"))) return void 0;
   const localOrigin = gitRefHash(resolvedPath, "origin/main");
   if (!localOrigin) return void 0;
   const remoteMain = remoteMainHash(resolvedPath);
@@ -5599,7 +5640,7 @@ function checkVaultGitComparison(resolvedPath, id, label, range, nonZeroSuffix,
   if (resolvedPath === void 0) {
     return check("pass", id, label, "No vault path \u2014 check skipped");
   }
-  if (!existsSync10(join22(resolvedPath, ".git"))) {
+  if (!existsSync11(join22(resolvedPath, ".git"))) {
     return check("pass", id, label, "No git repo \u2014 check skipped");
   }
   if (!hasOriginMain(resolvedPath)) {
@@ -5627,7 +5668,7 @@ function checkSatelliteLastRun(vaultPath, satelliteExpected) {
     return check("pass", "satellite_job_last_run", "Satellite job last run", "No vault path \u2014 check skipped");
   }
   const latestPath = satelliteLatestRunPath(vaultPath);
-  if (!existsSync10(latestPath)) {
+  if (!existsSync11(latestPath)) {
     return check("pass", "satellite_job_last_run", "Satellite job last run", "No latest-run.json \u2014 satellite has not run yet");
   }
   try {
@@ -5731,12 +5772,12 @@ function isRecentLogLine(line, nowMs) {
   return nowMs - ts <= 24 * 60 * 60 * 1e3;
 }
 function checkVaultGitPullFailures(home) {
-  const path = pullLogPaths(home).find((p) => existsSync10(p));
+  const path = pullLogPaths(home).find((p) => existsSync11(p));
   if (!path) {
     return check("pass", "vault_git_pull_failures", "Vault pull failures", "No wiki-pull.log found \u2014 check skipped");
   }
   try {
-    const lines = readFileSync7(path, "utf8").split(/\r?\n/).filter(Boolean);
+    const lines = readFileSync8(path, "utf8").split(/\r?\n/).filter(Boolean);
     const now = Date.now();
     const failures = lines.filter(
       (line) => isRecentLogLine(line, now) && /(pre-push pull failed|FAIL .*pull|FAIL .*rebase|cannot pull with rebase|unstaged changes)/i.test(line)
@@ -5760,7 +5801,7 @@ function checkS3MountPerf(resolvedPath) {
   }
   const mountPoint = fuse.mountPoint;
   const conceptsDir = join22(resolvedPath, "concepts");
-  if (!existsSync10(conceptsDir)) {
+  if (!existsSync11(conceptsDir)) {
     return check("pass", "s3_mount_perf", "S3 mount performance", `S3 FUSE mount (${mountPoint}), no concepts/ to benchmark`);
   }
   const start = Date.now();
@@ -5943,7 +5984,7 @@ function checkWriteTest(resolvedPath) {
     return check("pass", "s3_write_test", "S3 write test", "local disk \u2014 check skipped");
   }
   const conceptsDir = join22(resolvedPath, "concepts");
-  if (!existsSync10(conceptsDir)) {
+  if (!existsSync11(conceptsDir)) {
     return check("pass", "s3_write_test", "S3 write test", "no concepts/ dir to test \u2014 check skipped");
   }
   const result = writeTest(conceptsDir);
@@ -6029,7 +6070,7 @@ function checkVfsCacheHealth(resolvedPath) {
 }
 function readVaultSyncConfig(home) {
   try {
-    const content = readFileSync7(join22(home, ".skillwiki", ".env"), "utf8");
+    const content = readFileSync8(join22(home, ".skillwiki", ".env"), "utf8");
     let installed = false;
     let role;
     let serviceScope;
@@ -6058,7 +6099,7 @@ function readVaultSyncConfig(home) {
 }
 function readKeyFromEnvFile(path, keys) {
   try {
-    const content = readFileSync7(path, "utf8");
+    const content = readFileSync8(path, "utf8");
     for (const line of content.split(/\r?\n/)) {
       const trimmed = line.trim();
       if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
@@ -6080,7 +6121,7 @@ function resolveSnapshotGitWorktree(config) {
     if (fromProfile) return fromProfile;
   }
   const defaultPath = "/root/wiki-git";
-  return existsSync10(defaultPath) ? defaultPath : void 0;
+  return existsSync11(defaultPath) ? defaultPath : void 0;
 }
 function vaultSyncChecks(input) {
   const os = input.os ?? platform2();
@@ -6102,11 +6143,11 @@ function vaultSyncChecks(input) {
   const filterPath = input.filterPath ?? join22(home, ".config", "rclone", "wiki-push-filters.txt");
   const packagedSnapshotPath = join22(shareDir, "wiki-snapshot.sh");
   const legacySnapshotPath = "/root/.hermes/scripts/wiki-snapshot-v3.sh";
-  const snapshotPath = input.snapshotScriptPath ?? (existsSync10(packagedSnapshotPath) ? packagedSnapshotPath : legacySnapshotPath);
+  const snapshotPath = input.snapshotScriptPath ?? (existsSync11(packagedSnapshotPath) ? packagedSnapshotPath : legacySnapshotPath);
   function snapshotLastStatusCheck() {
     const snapshotLog = join22(logDir, "wiki-snapshot.log");
     try {
-      const logContent = readFileSync7(snapshotLog, "utf8");
+      const logContent = readFileSync8(snapshotLog, "utf8");
       const lines = logContent.trim().split("\n").filter(Boolean);
       if (lines.length === 0) {
         return check(
@@ -6151,14 +6192,14 @@ function vaultSyncChecks(input) {
     }
   }
   if (input.vaultSyncRole === "snapshotter") {
-    const c12 = existsSync10(snapshotPath) ? check("pass", "vault_sync_installed", "Vault sync installed", `Found snapshot script: ${snapshotPath}`) : check("error", "vault_sync_installed", "Vault sync installed", `Snapshot script not found at ${snapshotPath}`);
+    const c12 = existsSync11(snapshotPath) ? check("pass", "vault_sync_installed", "Vault sync installed", `Found snapshot script: ${snapshotPath}`) : check("error", "vault_sync_installed", "Vault sync installed", `Snapshot script not found at ${snapshotPath}`);
     const serviceScope = input.vaultSyncServiceScope ?? "user";
     const userTimerPath = join22(home, ".config", "systemd", "user", "wiki-snapshot.timer");
     const systemTimerPath = "/etc/systemd/system/wiki-snapshot.timer";
     let c22;
-    if (serviceScope === "user" && existsSync10(userTimerPath)) {
+    if (serviceScope === "user" && existsSync11(userTimerPath)) {
       c22 = check("pass", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `Found: ${userTimerPath}`);
-    } else if (serviceScope === "system" && existsSync10(systemTimerPath)) {
+    } else if (serviceScope === "system" && existsSync11(systemTimerPath)) {
       c22 = check("pass", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `Found: ${systemTimerPath}`);
     } else if (os !== "linux") {
       c22 = check("warn", "vault_sync_jobs_enabled", "Vault sync jobs enabled", "Snapshotter scheduler is Linux-only and no wiki-snapshot.timer file was found");
@@ -6190,7 +6231,7 @@ function vaultSyncChecks(input) {
     );
     let c52;
     try {
-      if (!existsSync10(snapshotPath)) {
+      if (!existsSync11(snapshotPath)) {
         c52 = check(
           "error",
           "vault_sync_snapshot_guard",
@@ -6198,7 +6239,7 @@ function vaultSyncChecks(input) {
           `Snapshot script not found at ${snapshotPath}`
         );
       } else {
-        const content = readFileSync7(snapshotPath, "utf8");
+        const content = readFileSync8(snapshotPath, "utf8");
         if (!content.includes("--max-delete")) {
           c52 = check(
             "error",
@@ -6226,7 +6267,7 @@ function vaultSyncChecks(input) {
     return [c12, c22, c32, cFetch2, c42, c52];
   }
   const pushScriptPath = join22(shareDir, "wiki-push.sh");
-  const c1 = existsSync10(pushScriptPath) ? check("pass", "vault_sync_installed", "Vault sync installed", `Found: ${pushScriptPath}`) : check("error", "vault_sync_installed", "Vault sync installed", `Script not found at ${pushScriptPath} \u2014 run vault-sync-install`);
+  const c1 = existsSync11(pushScriptPath) ? check("pass", "vault_sync_installed", "Vault sync installed", `Found: ${pushScriptPath}`) : check("error", "vault_sync_installed", "Vault sync installed", `Script not found at ${pushScriptPath} \u2014 run vault-sync-install`);
   let c2;
   try {
     if (isMac) {
@@ -6280,7 +6321,7 @@ function vaultSyncChecks(input) {
   const logFile = join22(logDir, "wiki-push.log");
   let c3;
   try {
-    const logContent = readFileSync7(logFile, "utf8");
+    const logContent = readFileSync8(logFile, "utf8");
     const lines = logContent.trim().split("\n").filter(Boolean);
     if (lines.length === 0) {
       c3 = check(
@@ -6336,7 +6377,7 @@ function vaultSyncChecks(input) {
       }
     }
   } catch {
-    c3 = existsSync10(logDir) ? check(
+    c3 = existsSync11(logDir) ? check(
       "warn",
       "vault_sync_last_push_age",
       "Vault sync last push recency",
@@ -6351,7 +6392,7 @@ function vaultSyncChecks(input) {
   const fetchLogFile = join22(logDir, "wiki-fetch.log");
   let cFetch;
   try {
-    const logContent = readFileSync7(fetchLogFile, "utf8");
+    const logContent = readFileSync8(fetchLogFile, "utf8");
     const lines = logContent.trim().split("\n").filter(Boolean);
     if (lines.length === 0) {
       cFetch = check(
@@ -6395,7 +6436,7 @@ function vaultSyncChecks(input) {
   }
   let c4;
   try {
-    if (!existsSync10(filterPath)) {
+    if (!existsSync11(filterPath)) {
       c4 = check(
         "error",
         "vault_sync_filter_present",
@@ -6403,7 +6444,7 @@ function vaultSyncChecks(input) {
         `Filter file not found at ${filterPath}`
       );
     } else {
-      const content = readFileSync7(filterPath, "utf8");
+      const content = readFileSync8(filterPath, "utf8");
       const requiredExcludes = [
         "remotely-save/data.json",
         ".skillwiki/sync.lock",
@@ -6446,7 +6487,7 @@ function vaultSyncChecks(input) {
     );
   } else {
     try {
-      if (!existsSync10(snapshotPath)) {
+      if (!existsSync11(snapshotPath)) {
         c5 = check(
           "error",
           "vault_sync_snapshot_guard",
@@ -6454,7 +6495,7 @@ function vaultSyncChecks(input) {
           `Snapshot script not found at ${snapshotPath}`
         );
       } else {
-        const content = readFileSync7(snapshotPath, "utf8");
+        const content = readFileSync8(snapshotPath, "utf8");
         if (!content.includes("--max-delete")) {
           c5 = check(
             "error",
@@ -6512,7 +6553,7 @@ function findSkillNames(dir) {
     return results;
   }
   for (const entry of entries) {
-    if (entry.isDirectory() && existsSync10(join22(dir, entry.name, "SKILL.md"))) {
+    if (entry.isDirectory() && existsSync11(join22(dir, entry.name, "SKILL.md"))) {
       results.push(entry.name);
     }
   }
@@ -6556,7 +6597,7 @@ async function vaultMetrics(resolvedPath) {
   }
   let logLines = 0;
   try {
-    logLines = readFileSync7(join22(resolvedPath, "log.md"), "utf8").split("\n").length;
+    logLines = readFileSync8(join22(resolvedPath, "log.md"), "utf8").split("\n").length;
   } catch {
   }
   return [
@@ -6658,7 +6699,7 @@ async function runDoctor(input) {
 }
 
 // src/utils/package-info.ts
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 function packageJsonCandidateUrls(baseUrl = import.meta.url) {
   return [
     new URL("../package.json", baseUrl),
@@ -6668,7 +6709,7 @@ function packageJsonCandidateUrls(baseUrl = import.meta.url) {
 function readCliPackageJson(baseUrl = import.meta.url) {
   for (const url of packageJsonCandidateUrls(baseUrl)) {
     try {
-      const pkg = JSON.parse(readFileSync8(url, "utf8"));
+      const pkg = JSON.parse(readFileSync9(url, "utf8"));
       if (typeof pkg.version === "string") {
         return { ...pkg, version: pkg.version };
       }
@@ -6824,7 +6865,7 @@ ${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e
 
 // src/commands/observe.ts
 import { mkdir as mkdir6, writeFile as writeFile7 } from "fs/promises";
-import { existsSync as existsSync11, statSync as statSync2 } from "fs";
+import { existsSync as existsSync12, statSync as statSync2 } from "fs";
 import { join as join24 } from "path";
 import { createHash as createHash5 } from "crypto";
 var ALLOWED_KINDS = /* @__PURE__ */ new Set(["note", "bug", "task", "idea", "session-log"]);
@@ -6848,7 +6889,7 @@ async function runObserve(input) {
       result: err("SCHEME_REJECTED", { message: "Text must not be empty" })
     };
   }
-  if (!existsSync11(input.vault) || !statSync2(input.vault).isDirectory()) {
+  if (!existsSync12(input.vault) || !statSync2(input.vault).isDirectory()) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: input.vault })
@@ -8522,7 +8563,7 @@ async function fetchQueryPreview(input) {
 // src/mcp/graph-html.ts
 import { readFile as readFile19 } from "fs/promises";
 import { join as join29 } from "path";
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 var TYPE_COLORS = {
   entities: "#e74c3c",
   concepts: "#27ae60",
@@ -8592,7 +8633,7 @@ ${nodeSvg}
 async function fetchGraphHtmlReport(input) {
   const graphPath = input.graphPath ?? join29(input.vault, ".skillwiki", "graph.json");
   const maxNodes = Math.min(Math.max(10, input.maxNodes ?? 120), 500);
-  if (!existsSync12(graphPath)) {
+  if (!existsSync13(graphPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("GRAPH_MISSING", { path: graphPath, hint: "Run skillwiki.graph_build first." })

package/dist/cli.js

@@ -75,7 +75,7 @@ import {
   triggerAutoUpdate,
   writeCache,
   writeDotenv
-} from "./chunk-MI4BZI7Q.js";
+} from "./chunk-4Q7MANQI.js";
 import {
   normalizeDistTag
 } from "./chunk-E6UWZ3S3.js";
@@ -321,6 +321,8 @@ async function runInstall(input) {
     const hintLines2 = [
       `deferred to plugin: skillwiki@llm-wiki v${plugin.version}`,
       `plugin provides skills at ${plugin.installPath}`,
+      "Plugin-managed skills are not refreshed with `skillwiki install`.",
+      "Do not run `skillwiki install` just to refresh plugin-managed skills; update the active plugin channel instead.",
       `use --force to install CLI copies into ${input.target} anyway`
     ];
     return {

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-MI4BZI7Q.js";
+} from "./chunk-4Q7MANQI.js";
 import "./chunk-E6UWZ3S3.js";
 
 // src/mcp-entry.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.47",
+  "version": "0.9.49",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js",

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.47",
+  "version": "0.9.49",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.47",
+  "version": "0.9.49",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.9.47",
+  "version": "0.9.49",
   "private": true,
   "files": [
     "wiki-*",

package/skills/skills/using-skillwiki/SKILL.md

@@ -172,11 +172,13 @@ skillwiki has multiple distribution channels that can drift:
 | Channel | Location | Update Command |
 |---------|----------|----------------|
 | npm CLI | `/usr/local/bin/skillwiki` | `npm install -g skillwiki@latest` |
-| npm skills | `/usr/local/lib/node_modules/skillwiki/skills/` | `skillwiki install` (copies to `~/.claude/skills/`) |
+| npm skills | `/usr/local/lib/node_modules/skillwiki/skills/` | `skillwiki install` only for standalone CLI skill copies; defers when the plugin channel is active |
 | Claude plugin | `~/.claude/plugins/cache/llm-wiki/` | `claude plugin update skillwiki@llm-wiki` |
 | Codex plugin | `~/.codex/plugins/cache/llm-wiki/` | `codex plugin marketplace upgrade llm-wiki`, then reinstall or restart Codex as needed |
 | Local git dev | source repo checkout | `npm link ./packages/cli` (from repo root) |
 **Check versions:** `skillwiki doctor` reports Plugin/CLI version mismatch warnings when installed channels disagree.
+**Plugin channel rule:** Plugin-managed skills are not refreshed with `skillwiki install`. When Claude or Codex plugin is installed and enabled, the plugin cache is the skill provider; `skillwiki install` is only a legacy/standalone copier for `~/.claude/skills/`.
+**Agent update rule:** Do not run `skillwiki install` just to refresh plugin-managed skills. If `skillwiki install` reports `deferred_to_plugin: true`, stop there and update the active plugin channel instead: Claude uses `claude plugin update skillwiki@llm-wiki`; Codex uses `codex plugin marketplace upgrade llm-wiki`, then reinstall or restart Codex as needed. Only use `skillwiki install --force` when the user explicitly wants duplicate CLI-managed copies under `~/.claude/skills/` and accepts that `skillwiki doctor` may report overlap.
 **Authoring rule:** `SKILL.md` frontmatter follows the Agent Skills schema: top-level `name` and `description` plus optional schema fields such as `metadata`. Do not put release version fields at the top level of `SKILL.md`; plugin and package release versions live in `plugin.json` and `package.json`.
 **Fix:** If developing locally, use the repo source plus `npm link`. If using released versions, update the relevant plugin or npm channel; do not infer release freshness from `SKILL.md` frontmatter.
 

package/skills/using-skillwiki/SKILL.md

@@ -172,11 +172,13 @@ skillwiki has multiple distribution channels that can drift:
 | Channel | Location | Update Command |
 |---------|----------|----------------|
 | npm CLI | `/usr/local/bin/skillwiki` | `npm install -g skillwiki@latest` |
-| npm skills | `/usr/local/lib/node_modules/skillwiki/skills/` | `skillwiki install` (copies to `~/.claude/skills/`) |
+| npm skills | `/usr/local/lib/node_modules/skillwiki/skills/` | `skillwiki install` only for standalone CLI skill copies; defers when the plugin channel is active |
 | Claude plugin | `~/.claude/plugins/cache/llm-wiki/` | `claude plugin update skillwiki@llm-wiki` |
 | Codex plugin | `~/.codex/plugins/cache/llm-wiki/` | `codex plugin marketplace upgrade llm-wiki`, then reinstall or restart Codex as needed |
 | Local git dev | source repo checkout | `npm link ./packages/cli` (from repo root) |
 **Check versions:** `skillwiki doctor` reports Plugin/CLI version mismatch warnings when installed channels disagree.
+**Plugin channel rule:** Plugin-managed skills are not refreshed with `skillwiki install`. When Claude or Codex plugin is installed and enabled, the plugin cache is the skill provider; `skillwiki install` is only a legacy/standalone copier for `~/.claude/skills/`.
+**Agent update rule:** Do not run `skillwiki install` just to refresh plugin-managed skills. If `skillwiki install` reports `deferred_to_plugin: true`, stop there and update the active plugin channel instead: Claude uses `claude plugin update skillwiki@llm-wiki`; Codex uses `codex plugin marketplace upgrade llm-wiki`, then reinstall or restart Codex as needed. Only use `skillwiki install --force` when the user explicitly wants duplicate CLI-managed copies under `~/.claude/skills/` and accepts that `skillwiki doctor` may report overlap.
 **Authoring rule:** `SKILL.md` frontmatter follows the Agent Skills schema: top-level `name` and `description` plus optional schema fields such as `metadata`. Do not put release version fields at the top level of `SKILL.md`; plugin and package release versions live in `plugin.json` and `package.json`.
 **Fix:** If developing locally, use the repo source plus `npm link`. If using released versions, update the relevant plugin or npm channel; do not infer release freshness from `SKILL.md` frontmatter.