skillwiki 0.10.36 → 0.10.39

package/dist/{chunk-WJVG3DD5.js → chunk-NDR2OY4K.js}

@@ -5968,6 +5968,7 @@ export {
   isFailedRunStatus,
   readSatelliteLatestRunFromText,
   evaluateSatelliteRunHealth,
+  detectFuseMount,
   snapshotterHealthChecks,
   runDoctor,
   readCliPackageJson,

package/dist/cli.js

@@ -7,6 +7,7 @@ import {
   GateError,
   SATELLITE_STALE_MS,
   configPath,
+  detectFuseMount,
   evaluateDirtyVolumeGate,
   evaluateSatelliteRunHealth,
   findPlugin,
@@ -38,7 +39,7 @@ import {
   scanConflictMarkerBlocksInText,
   snapshotterHealthChecks,
   upsertIndexEntry
-} from "./chunk-WJVG3DD5.js";
+} from "./chunk-NDR2OY4K.js";
 import {
   normalizeDistTag,
   readCache,
@@ -168,6 +169,7 @@ import {
   ok,
   readPage,
   redactSensitiveContent,
+  resolveReadOnlyVaultRoot,
   scanSensitiveContent,
   scanVault,
   splitFrontmatter
@@ -181,11 +183,19 @@ import { Command } from "commander";
 function printJson(r) {
   process.stdout.write(JSON.stringify(r) + "\n");
 }
-function printHuman(r) {
+function printHuman(r, opts = {}) {
   if (r.ok) {
     if (typeof r.data === "object" && r.data !== null && "humanHint" in r.data) {
-      process.stdout.write(`${r.data.humanHint}
+      const humanHint = r.data.humanHint;
+      if (!opts.detailHints?.length) {
+        process.stdout.write(`${humanHint}
 `);
+      } else {
+        const existingLines = new Set(humanHint.split("\n"));
+        const detailLines2 = opts.detailHints.filter((line) => !existingLines.has(line));
+        process.stdout.write(`${[humanHint, ...detailLines2].join("\n")}
+`);
+      }
     } else {
       process.stdout.write(`OK
 ${formatData(r.data)}
@@ -202,6 +212,45 @@ function formatData(d) {
   return JSON.stringify(d, null, 2);
 }
 
+// src/utils/lint-detail-hints.ts
+function lintDetailHints(data) {
+  const record = asRecord(data);
+  if (!record) return [];
+  const bySeverity = asRecord(record.by_severity);
+  if (bySeverity && Array.isArray(bySeverity.error)) {
+    return detailLines(bySeverity.error, false);
+  }
+  return Array.isArray(record.buckets) ? detailLines(record.buckets, true) : [];
+}
+function healthLintDetailHints(data) {
+  const record = asRecord(data);
+  const components = asRecord(record?.components);
+  const lint = asRecord(components?.lint);
+  return Array.isArray(lint?.buckets) ? detailLines(lint.buckets, true) : [];
+}
+function detailLines(buckets, requireErrorSeverity) {
+  const seen = /* @__PURE__ */ new Set();
+  const lines = [];
+  for (const bucket of buckets) {
+    const record = asRecord(bucket);
+    if (!record || requireErrorSeverity && record.severity !== "error") continue;
+    const name = nonEmptyBucketName(record);
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    lines.push(`detail: skillwiki lint --only ${name} --examples 3`);
+  }
+  return lines;
+}
+function nonEmptyBucketName(bucket) {
+  if (typeof bucket.kind !== "string" || !/^[a-z0-9_]+$/.test(bucket.kind)) return null;
+  if (typeof bucket.count === "number") return bucket.count > 0 ? bucket.kind : null;
+  if (Array.isArray(bucket.items)) return bucket.items.length > 0 ? bucket.kind : null;
+  return null;
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : null;
+}
+
 // src/utils/deprecation.ts
 import { readFileSync } from "fs";
 import { join } from "path";
@@ -4424,7 +4473,8 @@ import { mkdir as mkdir8, readFile as readFile11, writeFile as writeFile7 } from
 import { join as join24, relative, sep } from "path";
 var MAX_WORDS = 900;
 async function runSessionBrief(input) {
-  const scan = await scanVault(input.vault);
+  const { root: scanRoot } = resolveReadOnlyVaultRoot(input.vault);
+  const scan = await scanVault(scanRoot);
   if (!scan.ok) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
   }
@@ -4450,7 +4500,7 @@ async function runSessionBrief(input) {
       loadSatelliteHealth(input.vault),
       loadSessionPins(input.vault, project),
       project ? loadMemoryTopics(input.vault, project) : Promise.resolve([]),
-      loadPendingSources(input.vault, today)
+      loadPendingSources(scanRoot, today)
     ]);
     const healthWarnings = [
       ...baseHealthWarnings,
@@ -8357,11 +8407,23 @@ async function runBackupRestore(input) {
 import { existsSync as existsSync10, statSync as statSync4 } from "fs";
 import { readFile as readFile16 } from "fs/promises";
 import { join as join32 } from "path";
+var FUSE_NO_MIRROR_NOTE = "FUSE vault with no read mirror - status scan may be slow";
 async function runStatus(input) {
   if (!existsSync10(input.vault)) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
-  const scan = await scanVault(input.vault);
+  const { root: scanRoot, mirrored } = resolveReadOnlyVaultRoot(input.vault);
+  let readSource = "live";
+  if (mirrored) {
+    readSource = "mirror";
+  } else if (detectFuseMount(input.vault)) {
+    readSource = "fuse-no-mirror";
+  }
+  if (readSource === "fuse-no-mirror") {
+    process.stderr.write(`warning: ${FUSE_NO_MIRROR_NOTE}
+`);
+  }
+  const scan = await scanVault(scanRoot);
   if (!scan.ok) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
   }
@@ -8383,7 +8445,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile16(join32(input.vault, "SCHEMA.md"), "utf8");
+    const schemaContent = await readFile16(join32(scanRoot, "SCHEMA.md"), "utf8");
     const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
     if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
@@ -8420,14 +8482,20 @@ async function runStatus(input) {
   };
   const totalPages = Object.values(pageCounts).reduce((a, b) => a + b, 0);
   const rawTotal = rawArticles + rawTranscripts;
-  const humanHint = [
+  const hintLines = [
     `vault: ${input.vault}`,
     `lang: ${langResult.value}`,
     `total: ${totalPages} pages`,
     `  entities: ${pageCounts.entities}  concepts: ${pageCounts.concepts}  comparisons: ${pageCounts.comparisons}  queries: ${pageCounts.queries}  meta: ${pageCounts.meta}`,
     `  raw: ${rawTotal}  work_items: ${workItems}  compound: ${compound}`,
     `last modified: ${lastModified.slice(0, 10)}`
-  ].join("\n");
+  ];
+  if (readSource === "mirror") {
+    hintLines.push(`read source: mirror (${scanRoot}) - page counts may lag up to 30m`);
+  } else if (readSource === "fuse-no-mirror") {
+    hintLines.push(FUSE_NO_MIRROR_NOTE);
+  }
+  const humanHint = hintLines.join("\n");
   return {
     exitCode: ExitCode.OK,
     result: ok({
@@ -8437,6 +8505,7 @@ async function runStatus(input) {
       page_counts: pageCounts,
       total_pages: totalPages,
       last_modified: lastModified,
+      read_source: readSource,
       humanHint
     })
   };
@@ -9354,9 +9423,16 @@ var program = new Command();
 program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
 async function emit(r, vault, opts) {
-  if (program.opts().human) printHuman(r.result);
-  else printJson(r.result);
+  if (program.opts().human) {
+    const detailHints = r.result.ok ? opts?.humanDetailHints?.(r.result.data) : void 0;
+    printHuman(r.result, { detailHints });
+  } else {
+    printJson(r.result);
+  }
   if (vault && opts?.postCommit !== false) await postCommit(vault, r.exitCode);
+  await new Promise((resolve6, reject) => {
+    process.stdout.write("", (error) => error ? reject(error) : resolve6());
+  });
   process.exit(r.exitCode);
 }
 function dirtyVolumeBlock(vault, command) {
@@ -9835,6 +9911,7 @@ projectionsCmd.command("repair-legacy [vault]").description("repair one supporte
 });
 program.command("lint [vault]").description("run all vault health checks").option("--days <n>", "stale threshold", (s) => parseInt(s, 10), 90).option("--lines <n>", "pagesize threshold", (s) => parseInt(s, 10), 200).option("--log-threshold <n>", "log rotation threshold", (s) => parseInt(s, 10), 500).option("--fix", "auto-fix supported lint violations").option("--only <bucket>", "run only the specified lint bucket").option("--summary", "emit bounded bucket counts instead of full item arrays", false).option("--examples <n>", "example count per bucket in summary mode", (s) => parseInt(s, 10), 3).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
+  const humanDetailHints = opts.only ? void 0 : lintDetailHints;
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else if (opts.fix && opts.summary) return emitGuardedVaultWrite(
     v.vault,
@@ -9849,7 +9926,8 @@ program.command("lint [vault]").description("run all vault health checks").optio
       only: opts.only,
       summary: true,
       examplesLimit: opts.examples
-    })
+    }),
+    { humanDetailHints }
   );
   else if (opts.fix) return emitGuardedVaultWrite(
     v.vault,
@@ -9863,7 +9941,8 @@ program.command("lint [vault]").description("run all vault health checks").optio
       fix: true,
       only: opts.only,
       summary: false
-    })
+    }),
+    { humanDetailHints }
   );
   else if (opts.summary) emit(await runLint({
     vault: v.vault,
@@ -9875,7 +9954,7 @@ program.command("lint [vault]").description("run all vault health checks").optio
     only: opts.only,
     summary: true,
     examplesLimit: opts.examples
-  }), v.vault);
+  }), v.vault, { humanDetailHints });
   else emit(await runLint({
     vault: v.vault,
     source: vault ? "flag" : void 0,
@@ -9884,7 +9963,7 @@ program.command("lint [vault]").description("run all vault health checks").optio
     logThreshold: opts.logThreshold,
     fix: false,
     only: opts.only
-  }), v.vault);
+  }), v.vault, { humanDetailHints });
 });
 program.command("health [vault]").description("bounded whole-system wiki health report").option("--wiki <name>", "wiki profile name").option("--sync <mode>", "vault-sync policy: optional|required|off", "optional").option("--no-fail", "always exit 0 while reporting status in JSON").option("--out <path>", "write JSON result envelope to this path").option("--examples <n>", "example count per lint bucket", (s) => parseInt(s, 10), 3).action(async (vault, opts) => {
   const sync = String(opts.sync ?? "optional");
@@ -9905,7 +9984,7 @@ program.command("health [vault]").description("bounded whole-system wiki health
     noFail: opts.fail === false,
     out: opts.out,
     examplesLimit: opts.examples
-  }), void 0, { postCommit: false });
+  }), void 0, { postCommit: false, humanDetailHints: healthLintDetailHints });
 });
 var configCmd = program.command("config").description("manage skillwiki configuration");
 configCmd.command("get <key>").description("print the value of a config key").action(async (key) => emit(await runConfigGet({ key, home: process.env.HOME ?? "" })));

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-WJVG3DD5.js";
+} from "./chunk-NDR2OY4K.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-QVO332CT.js";
 import "./chunk-XRBUABGE.js";

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.36",
+  "version": "0.10.39",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 19 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.10.36",
+  "version": "0.10.39",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 19 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.10.36",
+  "version": "0.10.39",
   "private": true,
   "files": [
     "wiki-*",