skillwiki 0.9.48 → 0.9.50

package/dist/{chunk-UCTLPX3M.js → chunk-O3WK7GBV.js}

@@ -672,13 +672,7 @@ function vaultIoConcurrency() {
 function decodeProcMountPath(value) {
   return value.replace(/\\040/g, " ");
 }
-function isRcloneFuseVault(root) {
-  let mounts;
-  try {
-    mounts = readFileSync("/proc/mounts", "utf8");
-  } catch {
-    return false;
-  }
+function isRcloneFuseVaultFromMounts(root, mounts) {
   return mounts.split(/\r?\n/).some((line) => {
     const parts = line.split(" ");
     if (parts.length < 3) return false;
@@ -687,7 +681,7 @@ function isRcloneFuseVault(root) {
     return fsType === "fuse.rclone" && (root === mountPoint || root.startsWith(`${mountPoint}/`));
   });
 }
-function resolveReadOnlyVaultRoot(root) {
+function resolveReadOnlyVaultRootWithMounts(root, mounts) {
   if (/^(1|true|yes)$/i.test(process.env.SKILLWIKI_DISABLE_VAULT_READ_MIRROR ?? "")) {
     return { root, mirrored: false };
   }
@@ -696,11 +690,19 @@ function resolveReadOnlyVaultRoot(root) {
     return { root: explicitMirror, mirrored: explicitMirror !== root };
   }
   const siblingMirror = `${root}-git`;
-  if (isRcloneFuseVault(root) && existsSync(join2(siblingMirror, "SCHEMA.md"))) {
+  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;
@@ -3133,7 +3135,7 @@ function severityForBucket(kind) {
   if (WARNING_ORDER.includes(kind)) return "warning";
   return "info";
 }
-function outputForOnlyBucket(input, match, fixed, unresolved) {
+function outputForOnlyBucket(input, match, fixed, unresolved, readVault = lintReadVault(input)) {
   const severity = severityForBucket(input.only);
   const filtered = severity === "error" ? { error: match, warning: [], info: [] } : severity === "warning" ? { error: [], warning: match, info: [] } : { error: [], warning: [], info: match };
   const summary = {
@@ -3144,14 +3146,19 @@ function outputForOnlyBucket(input, match, fixed, unresolved) {
   let exitCode = ExitCode.OK;
   if (summary.errors > 0) exitCode = ExitCode.LINT_HAS_ERRORS;
   else if (summary.warnings > 0 || summary.info > 0) exitCode = ExitCode.LINT_HAS_WARNINGS;
+  const vault = lintVaultOutput(input, readVault);
+  const hintLines = [
+    ...readMirrorHintLines(vault),
+    `--only ${input.only}`,
+    match.length === 0 ? "0 violations" : match.map((b) => `  ${b.kind}: ${b.items.length}`).join("\n")
+  ];
   const output = {
-    vault: { path: input.vault, source: input.source ?? "resolved" },
+    vault,
     summary,
     by_severity: filtered,
     fixed,
     unresolved,
-    humanHint: `--only ${input.only}
-${match.length === 0 ? "0 violations" : match.map((b) => `  ${b.kind}: ${b.items.length}`).join("\n")}`
+    humanHint: hintLines.join("\n")
   };
   if (input.fix) appendLintFixLastOp(input.vault, fixed);
   return {
@@ -3160,7 +3167,27 @@ ${match.length === 0 ? "0 violations" : match.map((b) => `  ${b.kind}: ${b.items
   };
 }
 function lintReadVault(input) {
-  return input.fix ? input.vault : resolveReadOnlyVaultRoot(input.vault).root;
+  if (input.fix) {
+    return { readPath: input.vault, readMirror: false };
+  }
+  const resolved = resolveReadOnlyVaultRoot(input.vault);
+  return { readPath: resolved.root, readMirror: resolved.mirrored };
+}
+function lintVaultOutput(input, readVault) {
+  return {
+    path: input.vault,
+    source: input.source ?? "resolved",
+    read_path: readVault.readPath,
+    read_mirror: readVault.readMirror
+  };
+}
+function readMirrorHintLines(vault) {
+  if (!vault.read_mirror) return [];
+  return [
+    `read mirror: ${vault.read_path}`,
+    `requested vault: ${vault.path}`,
+    "if results look stale, refresh the read mirror or rerun with SKILLWIKI_DISABLE_VAULT_READ_MIRROR=1 for a live scan; live scans may be slower"
+  ];
 }
 function recomputeRawSha256IfPresent(content) {
   const split = splitFrontmatter(content);
@@ -3189,6 +3216,7 @@ function summarizeLintOutput(output, examplesLimit = 3) {
     ...output.by_severity.info.map((bucket) => summarizeBucket(bucket, "info", output.vault.path, examplesLimit))
   ];
   const lines = [];
+  lines.push(...readMirrorHintLines(output.vault));
   lines.push(`errors: ${output.summary.errors}`);
   lines.push(`warnings: ${output.summary.warnings}`);
   lines.push(`info: ${output.summary.info}`);
@@ -3236,7 +3264,8 @@ async function collectCliRefsPages(vault) {
   return ok(pages);
 }
 async function runCliRefsOnly(input) {
-  const lintVault = lintReadVault(input);
+  const readVault = lintReadVault(input);
+  const lintVault = readVault.readPath;
   const pages = await collectCliRefsPages(lintVault);
   if (!pages.ok) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: pages };
@@ -3253,14 +3282,19 @@ async function runCliRefsOnly(input) {
   const infoOut = cliRefFlags.length > 0 ? [{ kind: "cli_refs", items: cliRefFlags }] : [];
   const summary = { errors: 0, warnings: 0, info: cliRefFlags.length };
   const exitCode = cliRefFlags.length > 0 ? ExitCode.LINT_HAS_WARNINGS : ExitCode.OK;
+  const vault = lintVaultOutput(input, readVault);
+  const hintLines = [
+    ...readMirrorHintLines(vault),
+    `--only cli_refs`,
+    cliRefFlags.length === 0 ? "0 violations" : `  cli_refs: ${cliRefFlags.length}`
+  ];
   const output = {
-    vault: { path: input.vault, source: input.source ?? "resolved" },
+    vault,
     summary,
     by_severity: { error: [], warning: [], info: infoOut },
     fixed: [],
     unresolved: [],
-    humanHint: `--only cli_refs
-${cliRefFlags.length === 0 ? "0 violations" : `  cli_refs: ${cliRefFlags.length}`}`
+    humanHint: hintLines.join("\n")
   };
   return {
     exitCode,
@@ -3395,7 +3429,8 @@ async function applyFileSourceUrlFix(input, scan, fileSourceUrlFlags, fileSource
   return remaining;
 }
 async function runFileSourceUrlOnly(input) {
-  const lintVault = lintReadVault(input);
+  const readVault = lintReadVault(input);
+  const lintVault = readVault.readPath;
   const scanResult = await scanVault(lintVault);
   if (!scanResult.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scanResult };
   const pageTextCache = /* @__PURE__ */ new Map();
@@ -3411,7 +3446,7 @@ async function runFileSourceUrlOnly(input) {
     unresolved
   );
   const match = remaining.size > 0 ? [{ kind: "file_source_url", items: [...remaining] }] : [];
-  return outputForOnlyBucket(input, match, fixed, unresolved);
+  return outputForOnlyBucket(input, match, fixed, unresolved, readVault);
 }
 async function runLint(input) {
   if (input.only && !KNOWN_BUCKETS.includes(input.only)) {
@@ -3427,7 +3462,8 @@ async function runLint(input) {
     return runFileSourceUrlOnly(input);
   }
   const shouldFix = (bucket) => !!input.fix && (!input.only || input.only === bucket);
-  const lintVault = lintReadVault(input);
+  const readVault = lintReadVault(input);
+  const lintVault = readVault.readPath;
   const buckets = {};
   const fixed = [];
   const unresolved = [];
@@ -4148,7 +4184,7 @@ ${split.data.body}`;
   const infoOut = INFO_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   if (input.only) {
     const match = [...errorOut, ...warningOut, ...infoOut].filter((b) => b.kind === input.only);
-    return outputForOnlyBucket(input, match, fixed, unresolved);
+    return outputForOnlyBucket(input, match, fixed, unresolved, readVault);
   }
   const summary = {
     errors: errorOut.reduce((n, b) => n + b.items.length, 0),
@@ -4158,7 +4194,9 @@ ${split.data.body}`;
   let exitCode = ExitCode.OK;
   if (summary.errors > 0) exitCode = ExitCode.LINT_HAS_ERRORS;
   else if (summary.warnings > 0 || summary.info > 0) exitCode = ExitCode.LINT_HAS_WARNINGS;
+  const vault = lintVaultOutput(input, readVault);
   const hintLines = [];
+  hintLines.push(...readMirrorHintLines(vault));
   if (summary.errors > 0) hintLines.push(`errors: ${summary.errors}`);
   if (summary.warnings > 0) hintLines.push(`warnings: ${summary.warnings}`);
   if (summary.info > 0) hintLines.push(`info: ${summary.info}`);
@@ -4169,7 +4207,7 @@ ${split.data.body}`;
   if (hintLines.length === 0) hintLines.push("0 errors, 0 warnings, 0 info");
   if (input.fix) appendLintFixLastOp(input.vault, fixed);
   const output = {
-    vault: { path: input.vault, source: input.source ?? "resolved" },
+    vault,
     summary,
     by_severity: { error: errorOut, warning: warningOut, info: infoOut },
     fixed,

package/dist/cli.js

@@ -75,7 +75,7 @@ import {
   triggerAutoUpdate,
   writeCache,
   writeDotenv
-} from "./chunk-UCTLPX3M.js";
+} from "./chunk-O3WK7GBV.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-UCTLPX3M.js";
+} from "./chunk-O3WK7GBV.js";
 import "./chunk-E6UWZ3S3.js";
 
 // src/mcp-entry.ts

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.48",
+  "version": "0.9.50",
   "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.48",
+  "version": "0.9.50",
   "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.48",
+  "version": "0.9.50",
   "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.