skillwiki 0.8.1-beta.1 → 0.8.1-beta.11

package/dist/cli.js

@@ -9,7 +9,7 @@ import {
 
 // src/cli.ts
 import { readFileSync as readFileSync12 } from "fs";
-import { join as join43 } from "path";
+import { join as join44 } from "path";
 import { Command as Command2 } from "commander";
 
 // ../shared/src/exit-codes.ts
@@ -500,6 +500,7 @@ import { dirname } from "path";
 import { readFile as readFile3, readdir, stat } from "fs/promises";
 import { join as join3, relative as relative2, sep as sep2 } from "path";
 var TYPED_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
+var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
 async function scanVault(root) {
   try {
     await stat(join3(root, "SCHEMA.md"));
@@ -510,6 +511,7 @@ async function scanVault(root) {
   const rels = all.map((p) => ({ absPath: p, relPath: relative2(root, p).split(sep2).join("/") }));
   return ok({
     root,
+    allMarkdown: rels,
     typedKnowledge: rels.filter((p) => TYPED_DIRS.some((d) => p.relPath.startsWith(d + "/"))),
     raw: rels.filter((p) => p.relPath.startsWith("raw/")),
     workItems: rels.filter((p) => /^projects\/[^/]+\/work\/[^/]+\/(spec|plan|log)\.md$/.test(p.relPath)),
@@ -521,8 +523,10 @@ async function walk(dir) {
   const out = [];
   for (const e of entries) {
     const p = join3(dir, e.name);
-    if (e.isDirectory()) out.push(...await walk(p));
-    else if (e.isFile() && e.name.endsWith(".md")) out.push(p);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      out.push(...await walk(p));
+    } else if (e.isFile() && e.name.endsWith(".md")) out.push(p);
   }
   return out;
 }
@@ -548,23 +552,137 @@ function extractBodyWikilinks(body) {
   return out;
 }
 
-// src/commands/graph.ts
-async function runGraphBuild(input) {
-  const scan = await scanVault(input.vault);
-  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+// src/utils/community.ts
+async function buildWikilinkAdjacency(typedKnowledge) {
   const adjacency = {};
   const slugToPath = {};
-  for (const p of scan.data.typedKnowledge) {
+  for (const p of typedKnowledge) {
     const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
     slugToPath[slug] = p.relPath;
   }
-  for (const p of scan.data.typedKnowledge) {
+  for (const p of typedKnowledge) {
     const text = await readPage(p);
     const split = splitFrontmatter(text);
     const body = split.ok ? split.data.body : text;
     const links = extractBodyWikilinks(body);
     adjacency[p.relPath] = links.map((slug) => slugToPath[slug.split("/").pop()]).filter((x) => Boolean(x));
   }
+  return adjacency;
+}
+function toUndirectedWeighted(adj) {
+  const g = /* @__PURE__ */ new Map();
+  const ensure = (n) => {
+    let m = g.get(n);
+    if (!m) {
+      m = /* @__PURE__ */ new Map();
+      g.set(n, m);
+    }
+    return m;
+  };
+  for (const node of Object.keys(adj)) ensure(node);
+  for (const [a, nbrs] of Object.entries(adj)) {
+    for (const b of nbrs) {
+      if (a === b) continue;
+      ensure(a).set(b, 1);
+      ensure(b).set(a, 1);
+    }
+  }
+  return g;
+}
+function louvain(g) {
+  const nodes = [...g.keys()].sort();
+  const comm = /* @__PURE__ */ new Map();
+  nodes.forEach((n, i) => comm.set(n, i));
+  const k = /* @__PURE__ */ new Map();
+  let m2 = 0;
+  for (const n of nodes) {
+    let deg = 0;
+    for (const w of g.get(n).values()) deg += w;
+    k.set(n, deg);
+    m2 += deg;
+  }
+  if (m2 === 0) return comm;
+  const sumTot = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    const c = comm.get(n);
+    sumTot.set(c, (sumTot.get(c) ?? 0) + k.get(n));
+  }
+  let improved = true;
+  while (improved) {
+    improved = false;
+    for (const n of nodes) {
+      const cur = comm.get(n);
+      const kn = k.get(n);
+      sumTot.set(cur, sumTot.get(cur) - kn);
+      const wToComm = /* @__PURE__ */ new Map();
+      for (const [nb, w] of g.get(n)) {
+        if (nb === n) continue;
+        const c = comm.get(nb);
+        wToComm.set(c, (wToComm.get(c) ?? 0) + w);
+      }
+      const gainFor = (c) => (wToComm.get(c) ?? 0) - (sumTot.get(c) ?? 0) * kn / m2;
+      const curGain = gainFor(cur);
+      let bestComm = cur;
+      let bestDelta = 0;
+      for (const c of wToComm.keys()) {
+        const delta = gainFor(c) - curGain;
+        if (delta > bestDelta) {
+          bestDelta = delta;
+          bestComm = c;
+        }
+      }
+      comm.set(n, bestComm);
+      sumTot.set(bestComm, (sumTot.get(bestComm) ?? 0) + kn);
+      if (bestComm !== cur) improved = true;
+    }
+  }
+  return comm;
+}
+function communityCohesion(members, g) {
+  const n = members.length;
+  if (n < 2) return 1;
+  const set = new Set(members);
+  let internal = 0;
+  for (const a of members) {
+    for (const [b, w] of g.get(a) ?? /* @__PURE__ */ new Map()) {
+      if (a < b && set.has(b)) internal += w;
+    }
+  }
+  return internal / (n * (n - 1) / 2);
+}
+function findSparseCommunities(adj, opts = {}) {
+  const minSize = opts.minSize ?? 3;
+  const maxCohesion = opts.maxCohesion ?? 0.15;
+  const g = toUndirectedWeighted(adj);
+  const comm = louvain(g);
+  const groups = /* @__PURE__ */ new Map();
+  for (const [node, c] of comm) {
+    const arr = groups.get(c);
+    if (arr) arr.push(node);
+    else groups.set(c, [node]);
+  }
+  const out = [];
+  for (const members of groups.values()) {
+    if (members.length < minSize) continue;
+    const cohesion = communityCohesion(members, g);
+    if (cohesion < maxCohesion) {
+      out.push({
+        members: [...members].sort(),
+        size: members.length,
+        cohesion: Math.round(cohesion * 1e3) / 1e3,
+        action: members.length <= 5 ? "merge into adjacent community" : "split into smaller topics"
+      });
+    }
+  }
+  out.sort((a, b) => a.cohesion - b.cohesion);
+  return out;
+}
+
+// src/commands/graph.ts
+async function runGraphBuild(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const adjacency = await buildWikilinkAdjacency(scan.data.typedKnowledge);
   const adamicAdar = computeAdamicAdar(adjacency);
   const edge_count = Object.values(adjacency).reduce((acc, arr) => acc + arr.length, 0);
   try {
@@ -2465,9 +2583,22 @@ ${content}
 }
 
 // src/commands/lint.ts
-import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile16, rename as rename6 } from "fs/promises";
-import { join as join21 } from "path";
+import { existsSync as existsSync5 } from "fs";
+import { readFile as readFile17 } from "fs/promises";
+import { join as join22 } from "path";
+
+// src/commands/sparse-community.ts
+async function runSparseCommunity(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const adjacency = await buildWikilinkAdjacency(scan.data.typedKnowledge);
+  const communities = findSparseCommunities(adjacency, {
+    minSize: input.minSize,
+    maxCohesion: input.maxCohesion
+  });
+  const humanHint = communities.length === 0 ? "no sparse communities" : communities.map((c) => `  cohesion ${c.cohesion} (${c.size} pages): ${c.action}`).join("\n");
+  return { exitCode: ExitCode.OK, result: ok({ communities, humanHint }) };
+}
 
 // src/commands/topic-map-check.ts
 var DEFAULT_THRESHOLD = 200;
@@ -2710,28 +2841,100 @@ async function runRawBodyDedup(vault) {
 }
 
 // src/commands/path-too-long.ts
+import { existsSync as existsSync4 } from "fs";
+import { mkdir as mkdir8, readFile as readFile16, rename as rename6, unlink as unlink3 } from "fs/promises";
+import { dirname as dirname8, join as join21, posix, resolve as resolve4 } from "path";
 var MAX_PATH_LENGTH = 240;
+var WINDOWS_ABSOLUTE_PATH_LIMIT = 259;
 async function runPathTooLong(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const allPages = [...scan.data.typedKnowledge, ...scan.data.raw, ...scan.data.workItems, ...scan.data.compound];
-  const violations = [];
-  for (const page of allPages) {
-    if (page.relPath.length > MAX_PATH_LENGTH) {
-      violations.push({ relPath: page.relPath, length: page.relPath.length });
-    }
-  }
+  const violations = findPathTooLongViolations(scan.data.allMarkdown, MAX_PATH_LENGTH);
   if (violations.length > 0) {
     return {
       exitCode: ExitCode.LINT_HAS_ERRORS,
       result: ok({
         violations,
-        humanHint: violations.map((v) => `${v.relPath}: ${v.length} chars (max ${MAX_PATH_LENGTH})`).join("\n")
+        humanHint: violations.map((v) => `${v.relPath}: ${v.length} chars (max ${MAX_PATH_LENGTH}) -> ${v.suggestedRelPath}`).join("\n")
       })
     };
   }
   return { exitCode: ExitCode.OK, result: ok({ violations, humanHint: "all paths within length limit" }) };
 }
+async function fixPathTooLong(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const maxFixLength = maxFixPathLength(input.vault);
+  const violations = findPathTooLongViolations(scan.data.allMarkdown, maxFixLength);
+  const fixed = [];
+  const unresolved = [];
+  for (const violation of violations) {
+    const target = await resolveFixTarget(input.vault, violation.relPath, violation.suggestedRelPath, maxFixLength);
+    if (!target || target.relPath === violation.relPath || target.relPath.length > maxFixLength) {
+      unresolved.push(violation.relPath);
+      continue;
+    }
+    try {
+      if (target.mode === "dedupe") {
+        await unlink3(join21(input.vault, violation.relPath));
+      } else {
+        await mkdir8(dirname8(join21(input.vault, target.relPath)), { recursive: true });
+        await rename6(join21(input.vault, violation.relPath), join21(input.vault, target.relPath));
+      }
+      fixed.push({ from: violation.relPath, to: target.relPath });
+    } catch {
+      unresolved.push(violation.relPath);
+    }
+  }
+  const rewired = [];
+  if (fixed.length > 0) {
+    const afterScan = await scanVault(input.vault);
+    if (afterScan.ok) {
+      for (const page of afterScan.data.allMarkdown) {
+        if (!shouldRewriteReferences(page.relPath)) continue;
+        try {
+          const original = await readFile16(page.absPath, "utf8");
+          let updated = original;
+          for (const fix of fixed) {
+            updated = replacePathReferences(updated, fix.from, fix.to);
+          }
+          if (updated !== original) {
+            const write = await safeWritePage(page.absPath, updated);
+            if (write.ok) rewired.push(page.relPath);
+            else unresolved.push(`${page.relPath} (rewire)`);
+          }
+        } catch {
+          unresolved.push(`${page.relPath} (rewire)`);
+        }
+      }
+    }
+  }
+  const hintLines = [
+    `fixed: ${fixed.length}`,
+    `rewired: ${rewired.length}`,
+    `unresolved: ${unresolved.length}`
+  ];
+  for (const f of fixed) hintLines.push(`  ${f.from} -> ${f.to}`);
+  for (const u of unresolved) hintLines.push(`  unresolved: ${u}`);
+  return {
+    exitCode: unresolved.length > 0 ? ExitCode.LINT_HAS_ERRORS : ExitCode.OK,
+    result: ok({ fixed, unresolved, rewired, humanHint: hintLines.join("\n") })
+  };
+}
+function findPathTooLongViolations(pages, maxLength) {
+  return pages.filter((page) => page.relPath.length > maxLength).map((page) => ({
+    relPath: page.relPath,
+    length: page.relPath.length,
+    suggestedRelPath: truncateFilename(page.relPath, maxLength)
+  }));
+}
+function maxFixPathLength(vault) {
+  if (process.platform !== "win32") return MAX_PATH_LENGTH;
+  const root = resolve4(vault);
+  const separatorBudget = root.endsWith("\\") || root.endsWith("/") ? 0 : 1;
+  const absoluteSafeRelLength = WINDOWS_ABSOLUTE_PATH_LIMIT - root.length - separatorBudget;
+  return Math.max(1, Math.min(MAX_PATH_LENGTH, absoluteSafeRelLength));
+}
 function truncateFilename(relPath, maxLength = MAX_PATH_LENGTH) {
   if (relPath.length <= maxLength) return relPath;
   const lastSlash = relPath.lastIndexOf("/");
@@ -2745,15 +2948,62 @@ function truncateFilename(relPath, maxLength = MAX_PATH_LENGTH) {
   const maxPrefixLen = maxLength - dirPrefix.length - suffix.length;
   if (maxPrefixLen <= 0) {
     const fallback = dirPrefix + hash + ext;
-    if (fallback.length > maxLength) {
-      const dirBudget = maxLength - suffix.length;
-      return dirPrefix.slice(0, Math.max(0, dirBudget)) + suffix;
-    }
-    return fallback;
+    return fallback.length <= maxLength ? fallback : relPath;
   }
   const prefix = base.slice(0, maxPrefixLen).replace(/[-_\s]+$/, "");
   return dirPrefix + prefix + suffix;
 }
+async function resolveFixTarget(vault, original, preferred, maxLength) {
+  for (const candidate of candidateRelPaths(preferred, maxLength)) {
+    if (candidate === original || candidate.length > maxLength) continue;
+    const candidatePath = join21(vault, candidate);
+    if (!existsSync4(candidatePath)) return { relPath: candidate, mode: "rename" };
+    if (await hasSameContent(join21(vault, original), candidatePath)) {
+      return { relPath: candidate, mode: "dedupe" };
+    }
+  }
+  return null;
+}
+function candidateRelPaths(preferred, maxLength) {
+  const candidates = [preferred];
+  if (preferred.length > maxLength) return candidates;
+  const dir = posix.dirname(preferred) === "." ? "" : posix.dirname(preferred);
+  const filename = posix.basename(preferred);
+  const ext = filename.endsWith(".md") ? ".md" : "";
+  const base = ext ? filename.slice(0, -3) : filename;
+  const dirPrefix = dir ? `${dir}/` : "";
+  for (let i = 2; i < 100; i++) {
+    const suffix = `-${i}${ext}`;
+    const prefixBudget = maxLength - dirPrefix.length - suffix.length;
+    if (prefixBudget <= 0) break;
+    candidates.push(`${dirPrefix}${base.slice(0, prefixBudget).replace(/[-_\s]+$/, "")}${suffix}`);
+  }
+  return candidates;
+}
+async function hasSameContent(a, b) {
+  try {
+    const [left, right] = await Promise.all([readFile16(a), readFile16(b)]);
+    return left.equals(right);
+  } catch {
+    return false;
+  }
+}
+function shouldRewriteReferences(relPath) {
+  if (relPath.startsWith("raw/")) return false;
+  if (relPath.startsWith("_archive/")) return false;
+  return true;
+}
+function replacePathReferences(content, oldRelPath, newRelPath) {
+  let updated = content.replaceAll(oldRelPath, newRelPath);
+  const oldStem = posix.basename(oldRelPath).replace(/\.md$/, "");
+  const newStem = posix.basename(newRelPath).replace(/\.md$/, "");
+  if (oldStem !== newStem) {
+    const oldStemEscaped = oldStem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const stemWikilinkRe = new RegExp(`\\[\\[${oldStemEscaped}(\\|[^\\]]*)?\\]\\]`, "g");
+    updated = updated.replace(stemWikilinkRe, (_match, alias) => `[[${newStem}${alias ?? ""}]]`);
+  }
+  return updated;
+}
 function computeShortHash(input) {
   let hash = 2166136261;
   for (let i = 0; i < input.length; i++) {
@@ -2791,6 +3041,7 @@ function buildCliSurface() {
   program2.command("claim").option("--project <slug>").option("--slug <slug>").option("--wiki <name>");
   program2.command("pagesize").option("--lines <n>").option("--wiki <name>");
   program2.command("log-rotate").option("--threshold <n>").option("--apply").option("--wiki <name>");
+  program2.command("log-append").requiredOption("--content <text>").option("--wiki <name>");
   program2.command("lint").option("--days <n>").option("--lines <n>").option("--log-threshold <n>").option("--fix").option("--only <bucket>").option("--wiki <name>");
   program2.command("config");
   program2.command("doctor");
@@ -2940,8 +3191,16 @@ function extractSourceEntries(rawFm) {
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy", "path_too_long"];
 var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "file_source_url", "index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview", "missing_diagram"];
-var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "stale_sections", "cli_refs"];
+var INFO_ORDER = ["bridges", "sparse_community", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "stale_sections", "cli_refs"];
+var KNOWN_BUCKETS = [...ERROR_ORDER, ...WARNING_ORDER, ...INFO_ORDER];
 async function runLint(input) {
+  if (input.only && !KNOWN_BUCKETS.includes(input.only)) {
+    return {
+      exitCode: ExitCode.USAGE,
+      result: { ok: false, error: "UNKNOWN_BUCKET", detail: `Unknown bucket "${input.only}". Valid: ${KNOWN_BUCKETS.join(", ")}` }
+    };
+  }
+  const shouldFix = (bucket) => !!input.fix && (!input.only || input.only === bucket);
   const buckets = {};
   const fixed = [];
   const unresolved = [];
@@ -2983,6 +3242,10 @@ async function runLint(input) {
     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 });
+  if (sparse.result.ok && sparse.result.data.communities.length > 0) {
+    buckets.sparse_community = sparse.result.data.communities;
+  }
   const topicMap = await runTopicMapCheck({ vault: input.vault });
   if (topicMap.result.ok && topicMap.result.data.recommended) {
     buckets.topic_map_recommended = [{ page_count: topicMap.result.data.page_count, threshold: topicMap.result.data.threshold }];
@@ -3061,7 +3324,7 @@ async function runLint(input) {
         let rawPath = entry.replace(/^"/, "").replace(/"$/, "").replace(/^'/, "").replace(/'$/, "");
         rawPath = rawPath.replace(/^\^\[/, "").replace(/\]$/, "");
         if (!rawPath.startsWith("raw/") && !rawPath.startsWith("_archive/raw/")) continue;
-        if (!existsSync4(join21(input.vault, rawPath)) && !existsSync4(join21(input.vault, rawPath + ".md")) && !rawPath.startsWith("_archive/") && !existsSync4(join21(input.vault, "_archive", rawPath)) && !existsSync4(join21(input.vault, "_archive", rawPath + ".md"))) {
+        if (!existsSync5(join22(input.vault, rawPath)) && !existsSync5(join22(input.vault, rawPath + ".md")) && !rawPath.startsWith("_archive/") && !existsSync5(join22(input.vault, "_archive", rawPath)) && !existsSync5(join22(input.vault, "_archive", rawPath + ".md"))) {
           brokenSourceFlags.push(`${page.relPath}: ${rawPath}`);
         }
       }
@@ -3152,11 +3415,11 @@ async function runLint(input) {
         const slugMatch = String(entry).match(/\[\[([^\]]+)\]\]/);
         if (!slugMatch) continue;
         const slug = slugMatch[1];
-        const knowledgePath = join21(input.vault, "projects", slug, "knowledge.md");
-        if (!existsSync4(knowledgePath)) continue;
+        const knowledgePath = join22(input.vault, "projects", slug, "knowledge.md");
+        if (!existsSync5(knowledgePath)) continue;
         const pageRef = page.relPath.replace(/\.md$/, "");
         try {
-          const knowledgeContent = await readFile16(knowledgePath, "utf8");
+          const knowledgeContent = await readFile17(knowledgePath, "utf8");
           if (!knowledgeContent.includes(`[[${pageRef}]]`)) {
             orphanedProjectPages.push(`${page.relPath}: not in projects/${slug}/knowledge.md`);
           }
@@ -3197,13 +3460,13 @@ async function runLint(input) {
       }
     }
     if (staleSectionFlags.length > 0) buckets.stale_sections = staleSectionFlags;
-    if (input.fix && legacyPages.length > 0) {
+    if (shouldFix("legacy_citation_style") && legacyPages.length > 0) {
       const FENCE_RE2 = /```[\s\S]*?```/g;
       const INLINE_MARKER = /\^\[raw\/[^\]]+\]/g;
       for (const relPath of legacyPages) {
         try {
           const absPath = `${input.vault}/${relPath}`;
-          const raw = await readFile16(absPath, "utf8");
+          const raw = await readFile17(absPath, "utf8");
           const split = splitFrontmatter(raw);
           if (!split.ok) {
             unresolved.push(relPath);
@@ -3298,11 +3561,11 @@ ${newBody}`;
         else delete buckets.legacy_citation_style;
       }
     }
-    if (input.fix && noOverview.length > 0) {
+    if (shouldFix("missing_overview") && noOverview.length > 0) {
       for (const relPath of noOverview) {
         try {
           const absPath = `${input.vault}/${relPath}`;
-          const raw = await readFile16(absPath, "utf8");
+          const raw = await readFile17(absPath, "utf8");
           const split = splitFrontmatter(raw);
           if (!split.ok) {
             unresolved.push(relPath);
@@ -3339,11 +3602,11 @@ ${trimmedBody}`;
       if (remaining.length > 0) buckets.missing_overview = remaining;
       else delete buckets.missing_overview;
     }
-    if (input.fix && missingTldrFlags.length > 0) {
+    if (shouldFix("missing_tldr") && missingTldrFlags.length > 0) {
       for (const relPath of missingTldrFlags) {
         try {
           const absPath = `${input.vault}/${relPath}`;
-          const raw = await readFile16(absPath, "utf8");
+          const raw = await readFile17(absPath, "utf8");
           const split = splitFrontmatter(raw);
           if (!split.ok) {
             unresolved.push(relPath);
@@ -3386,14 +3649,14 @@ ${lines.join("\n")}`;
       if (remaining.length > 0) buckets.missing_tldr = remaining;
       else delete buckets.missing_tldr;
     }
-    if (input.fix && wikilinkCitationFlags.length > 0) {
+    if (shouldFix("wikilink_citation") && wikilinkCitationFlags.length > 0) {
       const WIKILINK_RE = /\[\[raw\/([^\]|]+)(?:\|[^\]]*)?\]\]/g;
       const FENCE_RE2 = /```[\s\S]*?```/g;
       const wikilinkFixed = [];
       for (const relPath of wikilinkCitationFlags) {
         try {
           const absPath = `${input.vault}/${relPath}`;
-          const raw = await readFile16(absPath, "utf8");
+          const raw = await readFile17(absPath, "utf8");
           const split = splitFrontmatter(raw);
           if (!split.ok) {
             unresolved.push(relPath);
@@ -3475,12 +3738,12 @@ ${newBody}`;
         else delete buckets.wikilink_citation;
       }
     }
-    if (input.fix && fileSourceUrlFlags.length > 0) {
+    if (shouldFix("file_source_url") && fileSourceUrlFlags.length > 0) {
       const FILE_FIXED = [];
       for (const relPath of fileSourceUrlFlags) {
         try {
           const absPath = `${input.vault}/${relPath}`;
-          const raw = await readFile16(absPath, "utf8");
+          const raw = await readFile17(absPath, "utf8");
           const parts = raw.split("---", 3);
           if (parts.length < 3) {
             unresolved.push(relPath);
@@ -3515,36 +3778,11 @@ ${newBody}`;
       }
     }
     const pathViolations = buckets.path_too_long;
-    if (input.fix && pathViolations && pathViolations.length > 0) {
-      const pathFixed = [];
-      for (const v of pathViolations) {
-        try {
-          const absPath = `${input.vault}/${v.relPath}`;
-          const newRelPath = truncateFilename(v.relPath);
-          const newAbsPath = `${input.vault}/${newRelPath}`;
-          await rename6(absPath, newAbsPath);
-          const oldPathEscaped = v.relPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-          for (const page of allPages) {
-            if (page.relPath === v.relPath) continue;
-            const content = await readFile16(page.absPath, "utf8");
-            if (!content.includes(v.relPath)) continue;
-            let updated = content;
-            const citationRe = new RegExp(`\\^\\[${oldPathEscaped}\\]`, "g");
-            updated = updated.replace(citationRe, `^[${newRelPath}]`);
-            const wikilinkRe = new RegExp(`\\[\\[${oldPathEscaped}(\\|[^\\]]*)?\\]\\]`, "g");
-            updated = updated.replace(wikilinkRe, (_m, alias) => `[[${newRelPath}${alias ?? ""}]]`);
-            if (updated !== content) {
-              const w = await safeWritePage(page.absPath, updated);
-              if (!w.ok) {
-                unresolved.push(`${page.relPath} (rewire)`);
-              }
-            }
-          }
-          pathFixed.push(v.relPath);
-        } catch {
-          unresolved.push(v.relPath);
-        }
-      }
+    if (shouldFix("path_too_long") && pathViolations && pathViolations.length > 0) {
+      const pathFix = await fixPathTooLong({ vault: input.vault });
+      const pathFixed = pathFix.result.ok ? pathFix.result.data.fixed.map((f) => f.from) : [];
+      if (pathFix.result.ok) unresolved.push(...pathFix.result.data.unresolved);
+      else unresolved.push(...pathViolations.map((v) => v.relPath));
       fixed.push(...pathFixed);
       if (pathFixed.length > 0) {
         const fixedSet = new Set(pathFixed);
@@ -3558,13 +3796,6 @@ ${newBody}`;
   const warningOut = WARNING_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const infoOut = INFO_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   if (input.only) {
-    const allKnown = [...ERROR_ORDER, ...WARNING_ORDER, ...INFO_ORDER];
-    if (!allKnown.includes(input.only)) {
-      return {
-        exitCode: ExitCode.USAGE,
-        result: { ok: false, error: "UNKNOWN_BUCKET", detail: `Unknown bucket "${input.only}". Valid: ${allKnown.join(", ")}` }
-      };
-    }
     const match = [...errorOut, ...warningOut, ...infoOut].filter((b) => b.kind === input.only);
     const severity = ERROR_ORDER.includes(input.only) ? "error" : WARNING_ORDER.includes(input.only) ? "warning" : "info";
     const filtered = severity === "error" ? { error: match, warning: [], info: [] } : severity === "warning" ? { error: [], warning: match, info: [] } : { error: [], warning: [], info: match };
@@ -3628,14 +3859,14 @@ ${match.length === 0 ? "0 violations" : match.map((b) => `  ${b.kind}: ${b.items
 }
 
 // src/commands/config.ts
-import { readFile as readFile17 } from "fs/promises";
-import { existsSync as existsSync5 } from "fs";
-import { join as join22 } from "path";
+import { readFile as readFile18 } from "fs/promises";
+import { existsSync as existsSync6 } from "fs";
+import { join as join23 } from "path";
 function validateKey(key) {
   return CONFIG_KEYS.includes(key) || isValidWikiProfileKey(key);
 }
 function configPath(home) {
-  return join22(home, ".skillwiki", ".env");
+  return join23(home, ".skillwiki", ".env");
 }
 async function runConfigGet(input) {
   if (!validateKey(input.key)) {
@@ -3653,7 +3884,7 @@ async function runConfigSet(input) {
   try {
     let originalContent;
     try {
-      originalContent = await readFile17(filePath, "utf8");
+      originalContent = await readFile18(filePath, "utf8");
     } catch {
     }
     const existing = originalContent !== void 0 ? parseDotenvText(originalContent) : {};
@@ -3685,18 +3916,18 @@ 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/commands/doctor.ts
-import { existsSync as existsSync8, lstatSync, readlinkSync, readdirSync, statSync as statSync3, readFileSync as readFileSync7 } from "fs";
-import { join as join26, resolve as resolve4 } from "path";
+import { existsSync as existsSync9, lstatSync, readlinkSync, readdirSync, statSync as statSync3, readFileSync as readFileSync7 } from "fs";
+import { join as join27, resolve as resolve5 } from "path";
 import { execSync as execSync2 } from "child_process";
 import { platform as platform2 } from "os";
 
 // src/utils/auto-update.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync6, mkdirSync as mkdirSync3 } from "fs";
-import { join as join23, dirname as dirname8 } from "path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync7, mkdirSync as mkdirSync3 } from "fs";
+import { join as join24, dirname as dirname9 } from "path";
 import { spawn } from "child_process";
 
 // src/utils/update-consts.ts
@@ -3707,7 +3938,7 @@ var CLI_DISABLE_FLAG = "--no-update-notifier";
 
 // src/utils/auto-update.ts
 function cachePath(home) {
-  return join23(home, ".skillwiki", CACHE_FILENAME);
+  return join24(home, ".skillwiki", CACHE_FILENAME);
 }
 function readCacheRaw(home) {
   try {
@@ -3726,7 +3957,7 @@ function readCache(home) {
 }
 function writeCache(home, cache) {
   const p = cachePath(home);
-  mkdirSync3(dirname8(p), { recursive: true });
+  mkdirSync3(dirname9(p), { recursive: true });
   writeFileSync4(p, JSON.stringify(cache, null, 2));
 }
 function latestFromCache(home, currentVersion) {
@@ -3745,7 +3976,7 @@ function triggerAutoUpdate(home, currentVersion) {
   const { isStale: isStale2 } = readCache(home);
   if (!isStale2) return;
   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], {
     detached: true,
     stdio: "ignore"
@@ -3757,12 +3988,12 @@ function triggerAutoUpdate(home, currentVersion) {
 
 // src/utils/plugin-registry.ts
 import { readFileSync as readFileSync5 } from "fs";
-import { join as join24 } from "path";
-var REGISTRY_PATH = join24(".claude", "plugins", "installed_plugins.json");
+import { join as join25 } from "path";
+var REGISTRY_PATH = join25(".claude", "plugins", "installed_plugins.json");
 var PLUGIN_KEY = "skillwiki@llm-wiki";
 function readInstalledPlugins(home) {
   try {
-    const raw = readFileSync5(join24(home, REGISTRY_PATH), "utf8");
+    const raw = readFileSync5(join25(home, REGISTRY_PATH), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -3779,8 +4010,8 @@ function findPlugin(home, key = PLUGIN_KEY) {
 // src/utils/s3-mount-health.ts
 import { execSync } from "child_process";
 import { platform } from "os";
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, unlinkSync as unlinkSync4, readFileSync as readFile18 } from "fs";
-import { join as join25 } from "path";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, unlinkSync as unlinkSync4, readFileSync as readFile19 } from "fs";
+import { join as join26 } from "path";
 var OS = platform();
 function findRcloneMountPid() {
   try {
@@ -3938,7 +4169,7 @@ function detectFuseMount(vaultPath) {
   return null;
 }
 function writeTest(dir) {
-  const testFile = join25(dir, `.doctor-write-test-${process.pid}.tmp`);
+  const testFile = join26(dir, `.doctor-write-test-${process.pid}.tmp`);
   const payload = `skillwiki doctor write test \u2014 ${Date.now()} \u2014 ${Math.random().toString(36).slice(2)}`;
   const start = Date.now();
   try {
@@ -3949,7 +4180,7 @@ function writeTest(dir) {
   const writeMs = Date.now() - start;
   const readStart = Date.now();
   try {
-    const back = readFile18(testFile, "utf8");
+    const back = readFile19(testFile, "utf8");
     const readMs = Date.now() - readStart;
     if (back !== payload) {
       try {
@@ -3971,6 +4202,37 @@ function writeTest(dir) {
   }
   return { success: true, writeMs, readMs: Date.now() - readStart, size: Buffer.byteLength(payload, "utf8") };
 }
+var DURATION_UNIT_SECONDS = {
+  ms: 1 / 1e3,
+  s: 1,
+  m: 60,
+  h: 3600,
+  d: 86400,
+  w: 604800
+};
+function parseDurationSeconds(raw) {
+  const input = raw.trim().toLowerCase();
+  if (!input) return null;
+  if (/^\d+(?:\.\d+)?$/.test(input)) {
+    const num = parseFloat(input);
+    return Number.isFinite(num) ? num : null;
+  }
+  const re = /(\d+(?:\.\d+)?)(ms|s|m|h|d|w)/g;
+  let total = 0;
+  let consumed = 0;
+  for (const match of input.matchAll(re)) {
+    const full = match[0];
+    const value = parseFloat(match[1]);
+    const unit = match[2];
+    if (!Number.isFinite(value)) return null;
+    const factor = DURATION_UNIT_SECONDS[unit];
+    if (factor === void 0) return null;
+    total += value * factor;
+    consumed += full.length;
+  }
+  if (consumed !== input.length) return null;
+  return total;
+}
 var FLAG_THRESHOLDS = {
   "--vfs-write-back": { min: 15, unit: "s", label: "VFS write-back window" },
   "--vfs-write-wait": { min: 10, unit: "s", label: "VFS write-wait" },
@@ -3992,14 +4254,14 @@ function checkNodeVersion() {
 function detectCliChannels(argv, home) {
   const channels = [];
   if (argv.length >= 2 && argv[1].endsWith("cli.js")) {
-    const devPath = resolve4(argv[1]);
+    const devPath = resolve5(argv[1]);
     channels.push({ name: "dev", path: devPath, isDevLink: true });
   }
   try {
     const whichOut = execSync2("which skillwiki 2>/dev/null", { encoding: "utf8" }).trim();
     if (whichOut) {
       const isDev = isDevSymlink(whichOut);
-      if (!channels.some((c) => c.path === resolve4(whichOut))) {
+      if (!channels.some((c) => c.path === resolve5(whichOut))) {
         channels.push({ name: "npm", path: whichOut, isDevLink: isDev });
       }
     }
@@ -4007,13 +4269,13 @@ function detectCliChannels(argv, home) {
   }
   const plugin = findPlugin(home);
   if (plugin) {
-    const pluginBin = join26(plugin.installPath, "bin", "skillwiki");
-    if (existsSync8(pluginBin)) {
+    const pluginBin = join27(plugin.installPath, "bin", "skillwiki");
+    if (existsSync9(pluginBin)) {
       channels.push({ name: "plugin", path: pluginBin, isDevLink: false });
     }
   }
-  const installBin = join26(home, ".claude", "skills", "bin", "skillwiki");
-  if (existsSync8(installBin)) {
+  const installBin = join27(home, ".claude", "skills", "bin", "skillwiki");
+  if (existsSync9(installBin)) {
     channels.push({ name: "install", path: installBin, isDevLink: false });
   }
   return channels;
@@ -4022,7 +4284,7 @@ function isDevSymlink(binPath) {
   try {
     const st = lstatSync(binPath);
     if (st.isSymbolicLink()) {
-      const target = resolve4(binPath, "..", readlinkSync(binPath));
+      const target = resolve5(binPath, "..", readlinkSync(binPath));
       return target.includes("packages/cli") || target.includes("packages\\cli");
     }
   } catch {
@@ -4065,7 +4327,7 @@ function checkCliChannels(argv, home) {
 }
 async function checkConfigFile(home) {
   const cfgPath = configPath(home);
-  if (!existsSync8(cfgPath)) {
+  if (!existsSync9(cfgPath)) {
     return check("warn", "config_file", "Config file exists", `${cfgPath} not found`);
   }
   try {
@@ -4080,7 +4342,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 (existsSync8(resolvedPath) && statSync3(resolvedPath).isDirectory()) {
+  if (existsSync9(resolvedPath) && statSync3(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`);
@@ -4089,13 +4351,13 @@ function checkVaultStructure(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync8(resolvedPath)) {
+  if (!existsSync9(resolvedPath)) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
   }
   const missing = [];
-  if (!existsSync8(join26(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  if (!existsSync9(join27(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
   for (const dir of ["raw", "entities", "concepts", "meta"]) {
-    if (!existsSync8(join26(resolvedPath, dir))) missing.push(dir + "/");
+    if (!existsSync9(join27(resolvedPath, dir))) missing.push(dir + "/");
   }
   if (missing.length === 0) {
     return check("pass", "vault_structure", "Vault structure valid", "All required files and directories present");
@@ -4103,23 +4365,23 @@ function checkVaultStructure(resolvedPath) {
   return check("warn", "vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")} \u2014 run \`skillwiki init\` to add CodeWiki structure`);
 }
 function checkSkillsInstalled(home, cwd) {
-  const srcDir = cwd ? join26(cwd, "packages", "skills") : void 0;
-  if (srcDir && existsSync8(srcDir)) {
-    const found = findSkillMd(srcDir);
+  const srcDir = cwd ? join27(cwd, "packages", "skills") : void 0;
+  if (srcDir && existsSync9(srcDir)) {
+    const found = findInstalledSkillMd(srcDir);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (source)`);
     }
   }
   const plugin = findPlugin(home);
   if (plugin) {
-    const found = findSkillMd(plugin.installPath);
+    const found = findInstalledSkillMd(plugin.installPath);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (plugin v${plugin.version})`);
     }
   }
-  const skillsDir = join26(home, ".claude", "skills");
-  if (existsSync8(skillsDir)) {
-    const found = findSkillMd(skillsDir);
+  const skillsDir = join27(home, ".claude", "skills");
+  if (existsSync9(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)`);
     }
@@ -4128,10 +4390,10 @@ function checkSkillsInstalled(home, cwd) {
 }
 function checkDuplicateSkills(home) {
   const plugin = findPlugin(home);
-  const skillsDir = join26(home, ".claude", "skills");
+  const skillsDir = join27(home, ".claude", "skills");
   const agentSkillDirs = [
-    { label: "~/.codex/skills/", path: join26(home, ".codex", "skills") },
-    { label: "~/.agents/skills/", path: join26(home, ".agents", "skills") }
+    { label: "~/.codex/skills/", path: join27(home, ".codex", "skills") },
+    { label: "~/.agents/skills/", path: join27(home, ".agents", "skills") }
   ];
   if (!plugin) {
     return check("pass", "skills_duplicate", "Skills not duplicated", "Single install channel");
@@ -4208,8 +4470,8 @@ async function checkProfiles(home) {
 }
 async function checkProjectLocalOverride(cwd) {
   const dir = cwd ?? process.cwd();
-  const envPath = join26(dir, ".skillwiki", ".env");
-  if (existsSync8(envPath)) {
+  const envPath = join27(dir, ".skillwiki", ".env");
+  if (existsSync9(envPath)) {
     return check("pass", "project_local", "Project-local config", `Found: ${envPath}`);
   }
   return check("pass", "project_local", "Project-local config", "None");
@@ -4218,7 +4480,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 (!existsSync8(join26(resolvedPath, ".git"))) {
+  if (!existsSync9(join27(resolvedPath, ".git"))) {
     return check("warn", "vault_git_remote", "Vault git remote", "Vault is not a git repository \u2014 sync features unavailable");
   }
   try {
@@ -4241,9 +4503,9 @@ function checkObsidianTemplates(resolvedPath) {
     return check("error", "obsidian_templates", "Obsidian templates", "Cannot check \u2014 WIKI_PATH not resolved");
   }
   const missing = [];
-  if (!existsSync8(join26(resolvedPath, "_Templates"))) missing.push("_Templates/");
-  if (!existsSync8(join26(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
-  if (!existsSync8(join26(resolvedPath, ".obsidian", "app.json"))) missing.push(".obsidian/app.json");
+  if (!existsSync9(join27(resolvedPath, "_Templates"))) missing.push("_Templates/");
+  if (!existsSync9(join27(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
+  if (!existsSync9(join27(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");
   }
@@ -4253,8 +4515,8 @@ function checkDotStoreClean(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "dsstore_clean", "No .DS_Store in raw/", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  const rawDir = join26(resolvedPath, "raw");
-  if (!existsSync8(rawDir)) {
+  const rawDir = join27(resolvedPath, "raw");
+  if (!existsSync9(rawDir)) {
     return check("pass", "dsstore_clean", "No .DS_Store in raw/", "raw/ directory not found \u2014 check skipped");
   }
   const found = [];
@@ -4269,7 +4531,7 @@ function checkDotStoreClean(resolvedPath) {
       if (entry.name === ".DS_Store") {
         found.push(rel ? `${rel}/.DS_Store` : ".DS_Store");
       } else if (entry.isDirectory()) {
-        walk2(join26(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
+        walk2(join27(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
       }
     }
   })(rawDir, "");
@@ -4282,7 +4544,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 (!existsSync8(join26(resolvedPath, ".git"))) {
+  if (!existsSync9(join27(resolvedPath, ".git"))) {
     return check("pass", "sync_last_push", "Vault sync recency", "No git repo \u2014 sync check skipped");
   }
   let timestamp;
@@ -4323,8 +4585,8 @@ function checkS3MountPerf(resolvedPath) {
     return check("pass", "s3_mount_perf", "S3 mount performance", "local disk");
   }
   const mountPoint = fuse.mountPoint;
-  const conceptsDir = join26(resolvedPath, "concepts");
-  if (!existsSync8(conceptsDir)) {
+  const conceptsDir = join27(resolvedPath, "concepts");
+  if (!existsSync9(conceptsDir)) {
     return check("pass", "s3_mount_perf", "S3 mount performance", `S3 FUSE mount (${mountPoint}), no concepts/ to benchmark`);
   }
   const start = Date.now();
@@ -4363,6 +4625,73 @@ function checkS3MountPerf(resolvedPath) {
     `S3 FUSE mount, cache warm (rg scan: ${elapsed.toFixed(3)}s)`
   );
 }
+var MAX_DIR_CACHE_TIME_SECONDS = 15 * 60;
+function formatDurationForHumans(seconds) {
+  if (!Number.isFinite(seconds)) return `${seconds}s`;
+  if (seconds >= 3600) return `${(seconds / 3600).toFixed(1)}h`;
+  if (seconds >= 60) return `${(seconds / 60).toFixed(1)}m`;
+  if (seconds >= 1) return `${seconds.toFixed(1)}s`;
+  return `${Math.round(seconds * 1e3)}ms`;
+}
+function checkS3MountFreshness(resolvedPath) {
+  if (!resolvedPath) {
+    return check("pass", "s3_mount_freshness", "S3 visibility freshness", "No vault path \u2014 check skipped");
+  }
+  const fuse = detectFuseMount(resolvedPath);
+  if (!fuse) {
+    return check("pass", "s3_mount_freshness", "S3 visibility freshness", "local disk \u2014 check skipped");
+  }
+  const pid = findRcloneMountPid();
+  if (pid === null) {
+    return check(
+      "warn",
+      "s3_mount_freshness",
+      "S3 visibility freshness",
+      `S3 FUSE mount (${fuse.mountPoint}) but no rclone process found \u2014 cannot audit --dir-cache-time`
+    );
+  }
+  const flags = parseRcloneFlags(pid);
+  if (flags.size === 0) {
+    return check(
+      "warn",
+      "s3_mount_freshness",
+      "S3 visibility freshness",
+      `rclone PID ${pid} found but could not parse flags`
+    );
+  }
+  const raw = flags.get("--dir-cache-time");
+  if (!raw) {
+    return check(
+      "pass",
+      "s3_mount_freshness",
+      "S3 visibility freshness",
+      "PID " + pid + ": --dir-cache-time not set (rclone default 5m, within <=15m SLA)"
+    );
+  }
+  const seconds = parseDurationSeconds(raw);
+  if (seconds === null) {
+    return check(
+      "warn",
+      "s3_mount_freshness",
+      "S3 visibility freshness",
+      `PID ${pid}: could not parse --dir-cache-time=${raw}`
+    );
+  }
+  if (seconds > MAX_DIR_CACHE_TIME_SECONDS) {
+    return check(
+      "warn",
+      "s3_mount_freshness",
+      "S3 visibility freshness",
+      `PID ${pid}: --dir-cache-time=${raw} (${formatDurationForHumans(seconds)}) exceeds 15m SLA \u2014 external S3 changes may remain invisible`
+    );
+  }
+  return check(
+    "pass",
+    "s3_mount_freshness",
+    "S3 visibility freshness",
+    `PID ${pid}: --dir-cache-time=${raw} (${formatDurationForHumans(seconds)}), within <=15m SLA`
+  );
+}
 function checkRcloneFlagAudit(resolvedPath) {
   if (!resolvedPath) {
     return check("pass", "rclone_flags", "rclone VFS flags", "No vault path \u2014 check skipped");
@@ -4386,11 +4715,8 @@ function checkRcloneFlagAudit(resolvedPath) {
       warnings.push(`${flag} not set (default may be unsafe)`);
       continue;
     }
-    const value = parseFloat(raw);
-    if (isNaN(value)) continue;
-    let inSeconds = value;
-    if (raw.endsWith("h")) inSeconds = value * 3600;
-    else if (raw.endsWith("m")) inSeconds = value * 60;
+    const inSeconds = parseDurationSeconds(raw);
+    if (inSeconds === null) continue;
     const thresholdSec = threshold.unit === "h" ? threshold.min * 3600 : threshold.unit === "m" ? threshold.min * 60 : threshold.min;
     if (inSeconds < thresholdSec) {
       warnings.push(`${flag}=${raw} (recommended \u2265${threshold.min}${threshold.unit})`);
@@ -4442,8 +4768,8 @@ function checkWriteTest(resolvedPath) {
   if (!fuse) {
     return check("pass", "s3_write_test", "S3 write test", "local disk \u2014 check skipped");
   }
-  const conceptsDir = join26(resolvedPath, "concepts");
-  if (!existsSync8(conceptsDir)) {
+  const conceptsDir = join27(resolvedPath, "concepts");
+  if (!existsSync9(conceptsDir)) {
     return check("pass", "s3_write_test", "S3 write test", "no concepts/ dir to test \u2014 check skipped");
   }
   const result = writeTest(conceptsDir);
@@ -4529,7 +4855,7 @@ function checkVfsCacheHealth(resolvedPath) {
 }
 function readVaultSyncConfig(home) {
   try {
-    const content = readFileSync7(join26(home, ".skillwiki", ".env"), "utf8");
+    const content = readFileSync7(join27(home, ".skillwiki", ".env"), "utf8");
     let installed = false;
     let role;
     for (const line of content.split(/\r?\n/)) {
@@ -4563,12 +4889,12 @@ function vaultSyncChecks(input) {
     ];
   }
   const isMac = os === "darwin";
-  const logDir = input.logDir ?? (isMac ? join26(home, "Library", "Logs") : join26(home, ".local", "state", "vault-sync", "log"));
-  const shareDir = input.shareDir ?? (isMac ? join26(home, "Library", "Application Support", "vault-sync", "bin") : join26(home, ".local", "share", "vault-sync", "bin"));
-  const filterPath = input.filterPath ?? join26(home, ".config", "rclone", "wiki-push-filters.txt");
+  const logDir = input.logDir ?? (isMac ? join27(home, "Library", "Logs") : join27(home, ".local", "state", "vault-sync", "log"));
+  const shareDir = input.shareDir ?? (isMac ? join27(home, "Library", "Application Support", "vault-sync", "bin") : join27(home, ".local", "share", "vault-sync", "bin"));
+  const filterPath = input.filterPath ?? join27(home, ".config", "rclone", "wiki-push-filters.txt");
   const snapshotPath = input.snapshotScriptPath ?? "/root/.hermes/scripts/wiki-snapshot-v3.sh";
-  const pushScriptPath = join26(shareDir, "wiki-push.sh");
-  const c1 = existsSync8(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 pushScriptPath = join27(shareDir, "wiki-push.sh");
+  const c1 = existsSync9(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) {
@@ -4619,7 +4945,7 @@ function vaultSyncChecks(input) {
       "Scheduler check failed \u2014 run vault-sync-install"
     );
   }
-  const logFile = join26(logDir, "wiki-push.log");
+  const logFile = join27(logDir, "wiki-push.log");
   let c3;
   try {
     const logContent = readFileSync7(logFile, "utf8");
@@ -4678,7 +5004,7 @@ function vaultSyncChecks(input) {
       }
     }
   } catch {
-    c3 = existsSync8(logDir) ? check(
+    c3 = existsSync9(logDir) ? check(
       "warn",
       "vault_sync_last_push_age",
       "Vault sync last push recency",
@@ -4690,7 +5016,7 @@ function vaultSyncChecks(input) {
       `Log directory not found at ${logDir}`
     );
   }
-  const fetchLogFile = join26(logDir, "wiki-fetch.log");
+  const fetchLogFile = join27(logDir, "wiki-fetch.log");
   let cFetch;
   try {
     const logContent = readFileSync7(fetchLogFile, "utf8");
@@ -4737,7 +5063,7 @@ function vaultSyncChecks(input) {
   }
   let c4;
   try {
-    if (!existsSync8(filterPath)) {
+    if (!existsSync9(filterPath)) {
       c4 = check(
         "error",
         "vault_sync_filter_present",
@@ -4786,7 +5112,7 @@ function vaultSyncChecks(input) {
     );
   } else {
     try {
-      if (!existsSync8(snapshotPath)) {
+      if (!existsSync9(snapshotPath)) {
         c5 = check(
           "error",
           "vault_sync_snapshot_guard",
@@ -4832,13 +5158,17 @@ function findSkillMd(dir) {
   }
   for (const entry of entries) {
     if (entry.isFile() && entry.name === "SKILL.md") {
-      results.push(join26(dir, entry.name));
+      results.push(join27(dir, entry.name));
     } else if (entry.isDirectory()) {
-      results.push(...findSkillMd(join26(dir, entry.name)));
+      results.push(...findSkillMd(join27(dir, entry.name)));
     }
   }
   return results;
 }
+function findInstalledSkillMd(dir) {
+  const directSkills = findSkillNames(dir).map((name) => join27(dir, name, "SKILL.md"));
+  return directSkills.length > 0 ? directSkills : findSkillMd(dir);
+}
 function findSkillNames(dir) {
   const results = [];
   let entries;
@@ -4848,12 +5178,61 @@ function findSkillNames(dir) {
     return results;
   }
   for (const entry of entries) {
-    if (entry.isDirectory() && existsSync8(join26(dir, entry.name, "SKILL.md"))) {
+    if (entry.isDirectory() && existsSync9(join27(dir, entry.name, "SKILL.md"))) {
       results.push(entry.name);
     }
   }
   return results;
 }
+var METRIC_TYPES = ["entities", "concepts", "comparisons", "queries", "meta"];
+async function vaultMetrics(resolvedPath) {
+  const ids = [
+    ["vault_metric_pages", "Vault pages by type"],
+    ["vault_metric_orphans", "Vault orphan rate"],
+    ["vault_metric_bridges", "Vault bridge count"],
+    ["vault_metric_cohesion", "Mean community cohesion"],
+    ["vault_metric_log_size", "Vault log size"]
+  ];
+  const noVault = () => ids.map(([id, label]) => check("info", id, label, "no vault configured"));
+  if (!resolvedPath) return noVault();
+  const scan = await scanVault(resolvedPath);
+  if (!scan.ok) return noVault();
+  const tk = scan.data.typedKnowledge;
+  const perType = METRIC_TYPES.map((d) => `${d} ${tk.filter((p) => p.relPath.startsWith(d + "/")).length}`).join(", ");
+  const adj = await buildWikilinkAdjacency(tk);
+  const g = toUndirectedWeighted(adj);
+  const nodes = [...g.keys()];
+  const total = nodes.length;
+  const orphanCount = nodes.filter((n) => g.get(n).size === 0).length;
+  const orphanRate = total > 0 ? Math.round(orphanCount / total * 1e3) / 10 : 0;
+  const comm = louvain(g);
+  const groups = /* @__PURE__ */ new Map();
+  for (const [node, c] of comm) {
+    const arr = groups.get(c);
+    if (arr) arr.push(node);
+    else groups.set(c, [node]);
+  }
+  const cohesions = [...groups.values()].filter((m) => m.length >= 2).map((m) => communityCohesion(m, g));
+  const meanCohesion = cohesions.length > 0 ? Math.round(cohesions.reduce((a, b) => a + b, 0) / cohesions.length * 1e3) / 1e3 : 0;
+  let bridges = 0;
+  for (const n of nodes) {
+    const nbrComms = /* @__PURE__ */ new Set();
+    for (const nb of g.get(n).keys()) nbrComms.add(comm.get(nb));
+    if (nbrComms.size >= 3) bridges++;
+  }
+  let logLines = 0;
+  try {
+    logLines = readFileSync7(join27(resolvedPath, "log.md"), "utf8").split("\n").length;
+  } catch {
+  }
+  return [
+    check("info", "vault_metric_pages", "Vault pages by type", `${total} typed (${perType})`),
+    check("info", "vault_metric_orphans", "Vault orphan rate", `${orphanRate}% (${orphanCount}/${total} degree-0)`),
+    check("info", "vault_metric_bridges", "Vault bridge count", `${bridges} page(s) link >= 3 communities`),
+    check("info", "vault_metric_cohesion", "Mean community cohesion", `${meanCohesion} across ${cohesions.length} communities (size >= 2)`),
+    check("info", "vault_metric_log_size", "Vault log size", `${logLines} lines`)
+  ];
+}
 async function runDoctor(input) {
   const checks = [];
   const vsConfig = readVaultSyncConfig(input.home);
@@ -4876,6 +5255,7 @@ async function runDoctor(input) {
   checks.push(checkSyncLastPush(resolvedPath));
   checks.push(checkDotStoreClean(resolvedPath));
   checks.push(checkS3MountPerf(resolvedPath));
+  checks.push(checkS3MountFreshness(resolvedPath));
   checks.push(checkRcloneFlagAudit(resolvedPath));
   checks.push(checkRcloneVersion(resolvedPath, vsConfig.installed));
   checks.push(checkWriteTest(resolvedPath));
@@ -4889,6 +5269,7 @@ async function runDoctor(input) {
     vaultSyncInstalled: vsConfig.installed,
     vaultSyncRole: vsConfig.role
   }));
+  checks.push(...await vaultMetrics(resolvedPath));
   const summary = {
     pass: checks.filter((c) => c.status === "pass").length,
     info: checks.filter((c) => c.status === "info").length,
@@ -4912,8 +5293,8 @@ async function runDoctor(input) {
 }
 
 // src/commands/archive.ts
-import { rename as rename7, mkdir as mkdir8, readFile as readFile19, writeFile as writeFile10 } from "fs/promises";
-import { join as join27, dirname as dirname9 } from "path";
+import { rename as rename7, mkdir as mkdir9, readFile as readFile20, writeFile as writeFile10 } from "fs/promises";
+import { join as join28, dirname as dirname10 } from "path";
 function countWikilinks(body, slug) {
   const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const re = new RegExp(`\\[\\[${escaped}(?:[|#][^\\]]*)?\\]\\]`, "g");
@@ -4941,7 +5322,7 @@ async function runArchive(input) {
   if (!relPath) return { exitCode: ExitCode.ARCHIVE_TARGET_NOT_FOUND, result: err("ARCHIVE_TARGET_NOT_FOUND", { page: input.page }) };
   if (relPath.startsWith("_archive/")) return { exitCode: ExitCode.ARCHIVE_ALREADY_ARCHIVED, result: err("ARCHIVE_ALREADY_ARCHIVED", { page: relPath }) };
   const slug = relPath.replace(/\.md$/, "").split("/").pop();
-  const archivePath = join27("_archive", relPath).replace(/\\/g, "/");
+  const archivePath = join28("_archive", relPath).replace(/\\/g, "/");
   let cascade;
   if (input.cascade) {
     const wikilinkRefs = [];
@@ -4965,7 +5346,7 @@ async function runArchive(input) {
     const indexRefs = [];
     if (!isRaw) {
       try {
-        const idx = await readFile19(join27(input.vault, "index.md"), "utf8");
+        const idx = await readFile20(join28(input.vault, "index.md"), "utf8");
         idx.split("\n").forEach((line, i) => {
           if (line.includes(`[[${slug}]]`)) indexRefs.push({ line: i + 1, text: line });
         });
@@ -4991,8 +5372,8 @@ async function runArchive(input) {
   }
   if (input.cascade && input.apply && cascade) {
     for (const ref of cascade.source_array_refs) {
-      const absPath = join27(input.vault, ref.page);
-      const text = await readFile19(absPath, "utf8");
+      const absPath = join28(input.vault, ref.page);
+      const text = await readFile20(absPath, "utf8");
       const split = splitFrontmatter(text);
       if (!split.ok) continue;
       const before = split.data.rawFrontmatter;
@@ -5009,12 +5390,12 @@ ${fmRewritten}
       }
     }
   }
-  await mkdir8(dirname9(join27(input.vault, archivePath)), { recursive: true });
+  await mkdir9(dirname10(join28(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
   if (!isRaw) {
-    const indexPath = join27(input.vault, "index.md");
+    const indexPath = join28(input.vault, "index.md");
     try {
-      const idx = await readFile19(indexPath, "utf8");
+      const idx = await readFile20(indexPath, "utf8");
       const originalLines = idx.split("\n");
       const filtered = originalLines.filter((l) => !l.includes(`[[${slug}]]`));
       if (filtered.length !== originalLines.length) {
@@ -5025,7 +5406,7 @@ ${fmRewritten}
       if (e instanceof Error && "code" in e && e.code !== "ENOENT") throw e;
     }
   }
-  await rename7(join27(input.vault, relPath), join27(input.vault, archivePath));
+  await rename7(join28(input.vault, relPath), join28(input.vault, archivePath));
   appendLastOp(input.vault, {
     operation: input.cascade ? "archive-cascade" : "archive",
     summary: `moved ${relPath} to ${archivePath}${input.cascade ? ` (cascade: ${cascade?.source_array_refs.length ?? 0} source arrays updated)` : ""}`,
@@ -5412,14 +5793,14 @@ ${newBody}`;
 // src/commands/update.ts
 import { execSync as execSync3 } from "child_process";
 import { readFileSync as readFileSync8 } from "fs";
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 function resolveGlobalSkillsRoot() {
   try {
     const globalRoot = execSync3("npm root -g", {
       encoding: "utf8",
       timeout: 5e3
     }).trim();
-    return join28(globalRoot, "skillwiki", "skills");
+    return join29(globalRoot, "skillwiki", "skills");
   } catch {
     return null;
   }
@@ -5445,7 +5826,7 @@ async function runUpdate(input) {
   );
   const currentVersion = pkg2.version;
   const tag = input.distTag ?? "latest";
-  const target = join28(input.home, ".claude", "skills");
+  const target = join29(input.home, ".claude", "skills");
   let latest;
   try {
     latest = execSync3(`npm view skillwiki@${tag} version`, {
@@ -5515,16 +5896,16 @@ async function runUpdate(input) {
 
 // src/commands/self-update.ts
 import { execSync as execSync4 } from "child_process";
-import { existsSync as existsSync9, readFileSync as readFileSync9 } from "fs";
-import { join as join29 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
+import { join as join30 } from "path";
 var DEFAULT_SOURCE_ROOT_SUFFIX = "/Desktop/code/llm-wiki";
 async function runSelfUpdate(input) {
   const currentVersion = JSON.parse(
     readFileSync9(new URL("../../package.json", import.meta.url), "utf8")
   ).version;
   const sourceRoot = input.sourceRoot ?? `${input.home}${DEFAULT_SOURCE_ROOT_SUFFIX}`;
-  const localPkgPath = join29(sourceRoot, "packages", "cli", "package.json");
-  const hasLocalSource = existsSync9(localPkgPath);
+  const localPkgPath = join30(sourceRoot, "packages", "cli", "package.json");
+  const hasLocalSource = existsSync10(localPkgPath);
   if (input.check) {
     let availableVersion = null;
     let source;
@@ -5655,10 +6036,10 @@ async function runSelfUpdate(input) {
 }
 
 // src/commands/transcripts.ts
-import { readdir as readdir5, stat as stat7, readFile as readFile20 } from "fs/promises";
-import { join as join30 } from "path";
+import { readdir as readdir5, stat as stat7, readFile as readFile21 } from "fs/promises";
+import { join as join31 } from "path";
 async function runTranscripts(input) {
-  const dir = join30(input.vault, "raw", "transcripts");
+  const dir = join31(input.vault, "raw", "transcripts");
   let entries;
   try {
     entries = await readdir5(dir, { withFileTypes: true });
@@ -5668,8 +6049,8 @@ async function runTranscripts(input) {
   const transcripts = [];
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-    const filePath = join30(dir, entry.name);
-    const content = await readFile20(filePath, "utf8");
+    const filePath = join31(dir, entry.name);
+    const content = await readFile21(filePath, "utf8");
     const fm = extractFrontmatter(content);
     if (!fm.ok) continue;
     const ingested = typeof fm.data.ingested === "string" ? fm.data.ingested : "";
@@ -5686,12 +6067,12 @@ async function runTranscripts(input) {
 }
 
 // src/commands/project-index.ts
-import { readdir as readdir6, readFile as readFile21, writeFile as writeFile11, mkdir as mkdir9 } from "fs/promises";
-import { join as join31, dirname as dirname10 } from "path";
+import { readdir as readdir6, readFile as readFile22, writeFile as writeFile11, mkdir as mkdir10 } from "fs/promises";
+import { join as join32, dirname as dirname11 } from "path";
 var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
 async function runProjectIndex(input) {
   const slug = input.slug;
-  const projectDir = join31(input.vault, "projects", slug);
+  const projectDir = join32(input.vault, "projects", slug);
   try {
     await readdir6(projectDir);
   } catch {
@@ -5702,15 +6083,15 @@ async function runProjectIndex(input) {
   }
   const wikilinkPattern = `[[${slug}]]`;
   const entries = [];
-  const compoundDir = join31(input.vault, "projects", slug, "compound");
+  const compoundDir = join32(input.vault, "projects", slug, "compound");
   try {
     const compoundFiles = await readdir6(compoundDir, { withFileTypes: true });
     for (const entry of compoundFiles) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-      const filePath = join31(compoundDir, entry.name);
+      const filePath = join32(compoundDir, entry.name);
       let text;
       try {
-        text = await readFile21(filePath, "utf8");
+        text = await readFile22(filePath, "utf8");
       } catch {
         continue;
       }
@@ -5727,16 +6108,16 @@ async function runProjectIndex(input) {
   for (const dir of LAYER2_DIRS) {
     let files;
     try {
-      files = await readdir6(join31(input.vault, dir), { withFileTypes: true });
+      files = await readdir6(join32(input.vault, dir), { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of files) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-      const filePath = join31(input.vault, dir, entry.name);
+      const filePath = join32(input.vault, dir, entry.name);
       let text;
       try {
-        text = await readFile21(filePath, "utf8");
+        text = await readFile22(filePath, "utf8");
       } catch {
         continue;
       }
@@ -5757,11 +6138,11 @@ async function runProjectIndex(input) {
     const tb = typeOrder[b.type] ?? 99;
     return ta !== tb ? ta - tb : a.title.localeCompare(b.title);
   });
-  const indexPath = join31(projectDir, "knowledge.md");
+  const indexPath = join32(projectDir, "knowledge.md");
   let existing = false;
   let stale = false;
   try {
-    const existingText = await readFile21(indexPath, "utf8");
+    const existingText = await readFile22(indexPath, "utf8");
     existing = true;
     const existingEntries = existingText.split("\n").filter((l) => l.startsWith("- [["));
     const existingPages = new Set(existingEntries.map((l) => {
@@ -5801,7 +6182,7 @@ Autogenerated by \`skillwiki project-index\` on ${today}.
   }
   if (input.apply) {
     try {
-      await mkdir9(dirname10(indexPath), { recursive: true });
+      await mkdir10(dirname11(indexPath), { recursive: true });
       await writeFile11(indexPath, body, "utf8");
     } catch (e) {
       return {
@@ -5830,10 +6211,10 @@ ${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e
 }
 
 // src/commands/compound.ts
-import { writeFile as writeFile12, mkdir as mkdir10, readdir as readdir7, unlink as unlink3 } from "fs/promises";
-import { join as join32 } from "path";
-import { existsSync as existsSync10 } from "fs";
-import { readFile as readFile22 } from "fs/promises";
+import { writeFile as writeFile12, mkdir as mkdir11, readdir as readdir7, unlink as unlink4 } from "fs/promises";
+import { join as join33 } from "path";
+import { existsSync as existsSync11 } from "fs";
+import { readFile as readFile23 } from "fs/promises";
 var RETRO_HEADING_RE = /^## \[(\d{4}-\d{2}-\d{2})(?:\s+[^\]]+)?\] retro \| loop cycle(?: (\d+))?: (.+)$/;
 var FIELD_RE = {
   improve: /^-\s+\*?\*?Improve:?\*?\*?\s*(.+)$/m,
@@ -5931,17 +6312,17 @@ function extractRetroFields(date, cycleName, block) {
   };
 }
 async function runCompound(input) {
-  const logPath = join32(input.vault, "log.md");
+  const logPath = join33(input.vault, "log.md");
   let logText;
   try {
-    logText = await readFile22(logPath, "utf8");
+    logText = await readFile23(logPath, "utf8");
   } catch {
     return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: logPath }) };
   }
   const entries = parseRetroEntries(logText);
   const promoted = [];
   const skipped = [];
-  const compoundDir = join32(input.vault, "projects", input.project, "compound");
+  const compoundDir = join33(input.vault, "projects", input.project, "compound");
   for (const entry of entries) {
     const generalizeValue = entry.generalize.trim();
     if (!/^yes/i.test(generalizeValue)) {
@@ -5949,8 +6330,8 @@ async function runCompound(input) {
       continue;
     }
     const slug = slugify(entry.cycleName);
-    const compoundPath = join32(compoundDir, `${slug}.md`);
-    if (existsSync10(compoundPath)) {
+    const compoundPath = join33(compoundDir, `${slug}.md`);
+    if (existsSync11(compoundPath)) {
       skipped.push(entry.date);
       continue;
     }
@@ -5988,8 +6369,8 @@ async function runCompound(input) {
     ].join("\n");
     const content = frontmatter + "\n" + body;
     if (!input.dryRun) {
-      if (!existsSync10(compoundDir)) {
-        await mkdir10(compoundDir, { recursive: true });
+      if (!existsSync11(compoundDir)) {
+        await mkdir11(compoundDir, { recursive: true });
       }
       await writeFile12(compoundPath, content, "utf8");
     }
@@ -6010,23 +6391,23 @@ async function runCompound(input) {
   };
 }
 async function runCompoundDelete(input) {
-  const projectDir = join32(input.vault, "projects", input.project);
-  if (!existsSync10(projectDir)) {
+  const projectDir = join33(input.vault, "projects", input.project);
+  if (!existsSync11(projectDir)) {
     return {
       exitCode: ExitCode.PROJECT_NOT_FOUND,
       result: err("PROJECT_NOT_FOUND", { slug: input.project, path: projectDir })
     };
   }
   const entryName = input.entry.replace(/\.md$/, "");
-  const compoundPath = join32(projectDir, "compound", `${entryName}.md`);
-  if (!existsSync10(compoundPath)) {
+  const compoundPath = join33(projectDir, "compound", `${entryName}.md`);
+  if (!existsSync11(compoundPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("FILE_NOT_FOUND", { path: compoundPath })
     };
   }
   try {
-    await unlink3(compoundPath);
+    await unlink4(compoundPath);
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -6052,8 +6433,8 @@ knowledge.md regenerated`
   };
 }
 async function runCompoundList(input) {
-  const compoundDir = join32(input.vault, "projects", input.project, "compound");
-  if (!existsSync10(compoundDir)) {
+  const compoundDir = join33(input.vault, "projects", input.project, "compound");
+  if (!existsSync11(compoundDir)) {
     return {
       exitCode: ExitCode.OK,
       result: ok({
@@ -6083,10 +6464,10 @@ could not read compound directory`
   const entries = [];
   for (const dirent of dirents) {
     if (!dirent.isFile() || !dirent.name.endsWith(".md")) continue;
-    const filePath = join32(compoundDir, dirent.name);
+    const filePath = join33(compoundDir, dirent.name);
     let text;
     try {
-      text = await readFile22(filePath, "utf8");
+      text = await readFile23(filePath, "utf8");
     } catch {
       continue;
     }
@@ -6115,9 +6496,9 @@ no compound entries found`;
 }
 
 // src/commands/observe.ts
-import { mkdir as mkdir11, writeFile as writeFile13 } from "fs/promises";
-import { existsSync as existsSync11, statSync as statSync4 } from "fs";
-import { join as join33 } from "path";
+import { mkdir as mkdir12, writeFile as writeFile13 } from "fs/promises";
+import { existsSync as existsSync12, statSync as statSync4 } from "fs";
+import { join as join34 } from "path";
 import { createHash as createHash4 } from "crypto";
 var ALLOWED_KINDS = /* @__PURE__ */ new Set(["note", "bug", "task", "idea", "session-log"]);
 function slugify2(text) {
@@ -6140,15 +6521,15 @@ async function runObserve(input) {
       result: err("SCHEME_REJECTED", { message: "Text must not be empty" })
     };
   }
-  if (!existsSync11(input.vault) || !statSync4(input.vault).isDirectory()) {
+  if (!existsSync12(input.vault) || !statSync4(input.vault).isDirectory()) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: input.vault })
     };
   }
-  const transcriptsDir = join33(input.vault, "raw", "transcripts");
+  const transcriptsDir = join34(input.vault, "raw", "transcripts");
   try {
-    await mkdir11(transcriptsDir, { recursive: true });
+    await mkdir12(transcriptsDir, { recursive: true });
   } catch {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
@@ -6158,7 +6539,7 @@ async function runObserve(input) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const slug = slugify2(input.text);
   const fileName = `${today}-observation-${slug}.md`;
-  const filePath = join33(transcriptsDir, fileName);
+  const filePath = join34(transcriptsDir, fileName);
   const body = `
 ${input.text.trim()}
 `;
@@ -6198,8 +6579,8 @@ ${input.text.trim()}
 }
 
 // src/commands/ingest.ts
-import { readFile as readFile23, writeFile as writeFile14, mkdir as mkdir12 } from "fs/promises";
-import { join as join34 } from "path";
+import { readFile as readFile24, writeFile as writeFile14, mkdir as mkdir13 } from "fs/promises";
+import { join as join35 } from "path";
 import { createHash as createHash5 } from "crypto";
 var ALLOWED_TYPES = /* @__PURE__ */ new Set(["entity", "concept", "comparison", "query"]);
 var TYPE_DIR = {
@@ -6358,7 +6739,7 @@ async function runIngest(input) {
     sourceContent = fetchResult.data.body;
   } else {
     try {
-      sourceContent = await readFile23(input.source, "utf8");
+      sourceContent = await readFile24(input.source, "utf8");
     } catch {
       return {
         exitCode: ExitCode.FILE_NOT_FOUND,
@@ -6373,8 +6754,8 @@ async function runIngest(input) {
   const rawRelPath = `raw/articles/${slug}.md`;
   const typedDir = TYPE_DIR[input.type] ?? `${input.type}s`;
   const typedRelPath = `${typedDir}/${slug}.md`;
-  const rawAbsPath = join34(input.vault, rawRelPath);
-  const typedAbsPath = join34(input.vault, typedRelPath);
+  const rawAbsPath = join35(input.vault, rawRelPath);
+  const typedAbsPath = join35(input.vault, typedRelPath);
   const rawContent = buildRawContent(sourceUrl, today, sha256, sourceContent);
   const typedContent = buildTypedContent(
     input.title,
@@ -6437,7 +6818,7 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir12(join34(input.vault, "raw", "articles"), { recursive: true });
+    await mkdir13(join35(input.vault, "raw", "articles"), { recursive: true });
     await writeFile14(rawAbsPath, rawContent, "utf8");
   } catch (e) {
     return {
@@ -6446,7 +6827,7 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir12(join34(input.vault, typedDir), { recursive: true });
+    await mkdir13(join35(input.vault, typedDir), { recursive: true });
     await writeFile14(typedAbsPath, typedContent, "utf8");
   } catch (e) {
     return {
@@ -6625,12 +7006,12 @@ ${body}`;
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync13 } from "fs";
-import { join as join36 } from "path";
+import { existsSync as existsSync14 } from "fs";
+import { join as join37 } from "path";
 
 // src/utils/sync-lock.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync4, readFileSync as readFileSync10, renameSync, unlinkSync as unlinkSync5, writeFileSync as writeFileSync6 } from "fs";
-import { join as join35 } from "path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync4, readFileSync as readFileSync10, renameSync, unlinkSync as unlinkSync5, writeFileSync as writeFileSync6 } from "fs";
+import { join as join36 } from "path";
 import { createHash as createHash6 } from "crypto";
 function getSessionId() {
   if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
@@ -6638,11 +7019,11 @@ function getSessionId() {
   return process.pid.toString();
 }
 function lockPath(vault) {
-  return join35(vault, ".skillwiki", "sync.lock");
+  return join36(vault, ".skillwiki", "sync.lock");
 }
 function readLock(vault) {
   const path = lockPath(vault);
-  if (!existsSync12(path)) return null;
+  if (!existsSync13(path)) return null;
   try {
     const raw = readFileSync10(path, "utf8");
     return JSON.parse(raw);
@@ -6657,8 +7038,8 @@ function isStale(lock, now) {
 }
 function acquireLock(vault, opts = {}) {
   const path = lockPath(vault);
-  const dir = join35(vault, ".skillwiki");
-  if (!existsSync12(dir)) {
+  const dir = join36(vault, ".skillwiki");
+  if (!existsSync13(dir)) {
     mkdirSync4(dir, { recursive: true });
   }
   const sessionId = opts.sessionId ?? getSessionId();
@@ -6703,7 +7084,7 @@ function writeLockedFile(path, lock) {
 }
 function releaseLock(vault, opts = {}) {
   const path = lockPath(vault);
-  if (!existsSync12(path)) {
+  if (!existsSync13(path)) {
     return { released: false };
   }
   const sessionId = opts.sessionId ?? getSessionId();
@@ -6732,7 +7113,7 @@ function releaseLock(vault, opts = {}) {
 function runSyncStatus(input) {
   const vault = input.vault;
   const includeStashes = input.includeStashes ?? false;
-  if (!existsSync13(join36(vault, ".git"))) {
+  if (!existsSync14(join37(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: ok({
@@ -6746,6 +7127,7 @@ function runSyncStatus(input) {
       })
     };
   }
+  enableGitLongPathsOnWindows(vault);
   const porcelain = git(vault, ["status", "--porcelain"]);
   const dirty = porcelain ? porcelain.split("\n").filter((l) => l.trim().length > 0).length : 0;
   const revOutput = git(vault, ["rev-list", "--left-right", "--count", "origin/HEAD...HEAD"]);
@@ -6809,12 +7191,24 @@ function runSyncStatus(input) {
 }
 async function runSyncPush(input) {
   const vault = input.vault;
-  if (!existsSync13(join36(vault, ".git"))) {
+  if (!existsSync14(join37(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
     };
   }
+  enableGitLongPathsOnWindows(vault);
+  let pathFixes = 0;
+  const pathFix = await fixPathTooLong({ vault });
+  if (pathFix.result.ok && pathFix.result.data.fixed.length > 0) {
+    pathFixes = pathFix.result.data.fixed.length;
+    appendLastOp(vault, {
+      operation: "lint-fix",
+      summary: `fixed ${pathFixes} long path(s)`,
+      files: pathFix.result.data.fixed.flatMap((f) => [f.from, f.to]),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   const porcelain = git(vault, ["status", "--porcelain"]);
   const dirtyFiles = porcelain ? porcelain.split("\n").filter((l) => l.trim().length > 0) : [];
   if (dirtyFiles.length === 0) {
@@ -6824,6 +7218,7 @@ async function runSyncPush(input) {
         files_committed: 0,
         commit_message: "",
         pushed: false,
+        path_fixes: pathFixes,
         humanHint: "nothing to commit, working tree clean"
       })
     };
@@ -6878,7 +7273,8 @@ async function runSyncPush(input) {
         files_committed: dirtyFiles.length,
         commit_message: commitMessage,
         pushed: false,
-        humanHint: `committed ${dirtyFiles.length} file(s) but push failed: ${String(e)}`
+        path_fixes: pathFixes,
+        humanHint: `committed ${dirtyFiles.length} file(s)${pathFixes > 0 ? ` after ${pathFixes} long-path fix(es)` : ""} but push failed: ${String(e)}`
       })
     };
   }
@@ -6888,7 +7284,8 @@ async function runSyncPush(input) {
       files_committed: dirtyFiles.length,
       commit_message: commitMessage,
       pushed,
-      humanHint: `committed and pushed ${dirtyFiles.length} file(s)`
+      path_fixes: pathFixes,
+      humanHint: `committed and pushed ${dirtyFiles.length} file(s)${pathFixes > 0 ? ` after ${pathFixes} long-path fix(es)` : ""}`
     })
   };
 }
@@ -6911,14 +7308,19 @@ function enumerateStashes(vault) {
   }
   return stashes;
 }
+function enableGitLongPathsOnWindows(vault) {
+  if (process.platform !== "win32") return;
+  git(vault, ["config", "core.longpaths", "true"]);
+}
 async function runSyncPull(input) {
   const vault = input.vault;
-  if (!existsSync13(join36(vault, ".git"))) {
+  if (!existsSync14(join37(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
     };
   }
+  enableGitLongPathsOnWindows(vault);
   let fetched = false;
   try {
     gitStrict(vault, ["fetch", "origin"]);
@@ -7007,6 +7409,8 @@ async function runSyncPull(input) {
       };
     }
   }
+  const pathFix = await fixPathTooLong({ vault });
+  const pathFixCount = pathFix.result.ok ? pathFix.result.data.fixed.length : 0;
   let lintErrors = 0;
   let lintWarnings = 0;
   const lintResult = await runLint({ vault, days: 90, lines: 200, logThreshold: 500 });
@@ -7018,6 +7422,7 @@ async function runSyncPull(input) {
   if (filesUpdated > 0) hintParts.push(`updated ${filesUpdated} file(s)`);
   else hintParts.push("already up to date");
   if (autoResolved > 0) hintParts.push(`${autoResolved} conflict(s) auto-resolved`);
+  if (pathFixCount > 0) hintParts.push(`${pathFixCount} long path(s) fixed`);
   if (lintErrors > 0) hintParts.push(`${lintErrors} lint error(s)`);
   if (lintWarnings > 0) hintParts.push(`${lintWarnings} lint warning(s)`);
   const exitCode = lintErrors > 0 ? ExitCode.LINT_HAS_ERRORS : lintWarnings > 0 ? ExitCode.LINT_HAS_WARNINGS : ExitCode.OK;
@@ -7081,7 +7486,7 @@ function runSyncPeers(input) {
 }
 function runSyncLock(input) {
   const vault = input.vault;
-  if (!existsSync13(vault)) {
+  if (!existsSync14(vault)) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: vault })
@@ -7116,7 +7521,7 @@ function runSyncLock(input) {
 }
 function runSyncUnlock(input) {
   const vault = input.vault;
-  if (!existsSync13(vault)) {
+  if (!existsSync14(vault)) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: vault })
@@ -7150,7 +7555,7 @@ function runSyncUnlock(input) {
 
 // src/commands/backup.ts
 import { statSync as statSync5, readdirSync as readdirSync2, readFileSync as readFileSync11, mkdirSync as mkdirSync5, writeFileSync as writeFileSync7 } from "fs";
-import { join as join37, relative as relative3, dirname as dirname11 } from "path";
+import { join as join38, relative as relative3, dirname as dirname12 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
 // src/utils/s3-client.ts
@@ -7170,11 +7575,11 @@ function createS3Client(config) {
 }
 
 // src/commands/backup.ts
-var SKIP_DIRS = /* @__PURE__ */ new Set([".git", ".obsidian", "_archive", "node_modules", ".skillwiki"]);
+var SKIP_DIRS2 = /* @__PURE__ */ new Set([".git", ".obsidian", "_archive", "node_modules", ".skillwiki"]);
 function* walkMarkdown(dir, base) {
   for (const entry of readdirSync2(dir, { withFileTypes: true })) {
-    if (SKIP_DIRS.has(entry.name)) continue;
-    const full = join37(dir, entry.name);
+    if (SKIP_DIRS2.has(entry.name)) continue;
+    const full = join38(dir, entry.name);
     if (entry.isDirectory()) {
       yield* walkMarkdown(full, base);
     } else if (entry.name.endsWith(".md")) {
@@ -7197,7 +7602,7 @@ async function runBackupSync(input) {
   let failed = 0;
   const files = [...walkMarkdown(input.vault, input.vault)];
   for (const relPath of files) {
-    const absPath = join37(input.vault, relPath);
+    const absPath = join38(input.vault, relPath);
     const localStat = statSync5(absPath);
     let needsUpload = true;
     try {
@@ -7273,7 +7678,7 @@ async function runBackupRestore(input) {
     const objects = list.Contents ?? [];
     for (const obj of objects) {
       if (!obj.Key) continue;
-      const localPath = join37(target, obj.Key);
+      const localPath = join38(target, obj.Key);
       try {
         const localStat = statSync5(localPath);
         if (obj.LastModified && localStat.mtime > obj.LastModified) {
@@ -7286,7 +7691,7 @@ async function runBackupRestore(input) {
         const resp = await client.send(new GetObjectCommand({ Bucket: input.bucket, Key: obj.Key }));
         const body = await resp.Body?.transformToByteArray();
         if (body) {
-          mkdirSync5(dirname11(localPath), { recursive: true });
+          mkdirSync5(dirname12(localPath), { recursive: true });
           writeFileSync7(localPath, Buffer.from(body));
           downloaded++;
         }
@@ -7319,11 +7724,11 @@ async function runBackupRestore(input) {
 }
 
 // src/commands/status.ts
-import { existsSync as existsSync14, statSync as statSync6 } from "fs";
-import { readFile as readFile24 } from "fs/promises";
-import { join as join38 } from "path";
+import { existsSync as existsSync15, statSync as statSync6 } from "fs";
+import { readFile as readFile25 } from "fs/promises";
+import { join as join39 } from "path";
 async function runStatus(input) {
-  if (!existsSync14(input.vault)) {
+  if (!existsSync15(input.vault)) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
   const scan = await scanVault(input.vault);
@@ -7348,7 +7753,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile24(join38(input.vault, "SCHEMA.md"), "utf8");
+    const schemaContent = await readFile25(join39(input.vault, "SCHEMA.md"), "utf8");
     const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
     if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
@@ -7408,8 +7813,8 @@ async function runStatus(input) {
 }
 
 // src/commands/seed.ts
-import { mkdir as mkdir13, writeFile as writeFile15, stat as stat8 } from "fs/promises";
-import { join as join39 } from "path";
+import { mkdir as mkdir14, writeFile as writeFile15, stat as stat8 } from "fs/promises";
+import { join as join40 } from "path";
 var TODAY = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var EXAMPLE_PAGES = {
   "entities/example-project.md": `---
@@ -7478,29 +7883,29 @@ Real sources are immutable after ingestion \u2014 never edit them.
 `;
 async function runSeed(input) {
   try {
-    await stat8(join39(input.vault, "SCHEMA.md"));
+    await stat8(join40(input.vault, "SCHEMA.md"));
   } catch {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { root: input.vault, reason: "SCHEMA.md missing \u2014 run `skillwiki init` first" }) };
   }
   const created = [];
   const skipped = [];
   for (const [relPath, content] of Object.entries(EXAMPLE_PAGES)) {
-    const absPath = join39(input.vault, relPath);
+    const absPath = join40(input.vault, relPath);
     try {
       await stat8(absPath);
       skipped.push(relPath);
     } catch {
-      await mkdir13(join39(absPath, ".."), { recursive: true });
+      await mkdir14(join40(absPath, ".."), { recursive: true });
       await writeFile15(absPath, content, "utf8");
       created.push(relPath);
     }
   }
-  const rawPath = join39(input.vault, "raw", "articles", "example-source.md");
+  const rawPath = join40(input.vault, "raw", "articles", "example-source.md");
   try {
     await stat8(rawPath);
     skipped.push("raw/articles/example-source.md");
   } catch {
-    await mkdir13(join39(rawPath, ".."), { recursive: true });
+    await mkdir14(join40(rawPath, ".."), { recursive: true });
     await writeFile15(rawPath, EXAMPLE_RAW, "utf8");
     created.push("raw/articles/example-source.md");
   }
@@ -7523,9 +7928,9 @@ async function runSeed(input) {
 }
 
 // src/commands/canvas.ts
-import { readFile as readFile25, writeFile as writeFile16 } from "fs/promises";
-import { existsSync as existsSync15 } from "fs";
-import { join as join40 } from "path";
+import { readFile as readFile26, writeFile as writeFile16 } from "fs/promises";
+import { existsSync as existsSync16 } from "fs";
+import { join as join41 } from "path";
 var NODE_WIDTH = 240;
 var NODE_HEIGHT = 60;
 var COLUMN_SPACING = 400;
@@ -7603,8 +8008,8 @@ function buildCanvasEdges(adjacency) {
   return edges;
 }
 async function runCanvasGenerate(input) {
-  const graphPath = input.graphPath ?? join40(input.vault, ".skillwiki", "graph.json");
-  if (!existsSync15(graphPath)) {
+  const graphPath = input.graphPath ?? join41(input.vault, ".skillwiki", "graph.json");
+  if (!existsSync16(graphPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("FILE_NOT_FOUND", {
@@ -7615,7 +8020,7 @@ async function runCanvasGenerate(input) {
   }
   let raw;
   try {
-    raw = await readFile25(graphPath, "utf8");
+    raw = await readFile26(graphPath, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
@@ -7641,7 +8046,7 @@ async function runCanvasGenerate(input) {
   const nodes = buildCanvasNodes(paths);
   const edges = buildCanvasEdges(graph.adjacency);
   const canvas = { nodes, edges };
-  const outPath = join40(input.vault, "vault-graph.canvas");
+  const outPath = join41(input.vault, "vault-graph.canvas");
   try {
     await writeFile16(outPath, JSON.stringify(canvas, null, 2));
   } catch (e) {
@@ -7663,8 +8068,8 @@ written: ${outPath}`
 }
 
 // src/commands/query.ts
-import { readFile as readFile26, stat as stat9 } from "fs/promises";
-import { join as join41 } from "path";
+import { readFile as readFile27, stat as stat9 } from "fs/promises";
+import { join as join42 } from "path";
 var W_KEYWORD = 2;
 var W_SOURCE_OVERLAP = 4;
 var W_WIKILINK = 3;
@@ -7785,7 +8190,7 @@ function computeKeywordScore(terms, title, tags, body) {
   return score;
 }
 async function loadOrBuildGraph(vault) {
-  const graphPath = join41(vault, ".skillwiki", "graph.json");
+  const graphPath = join42(vault, ".skillwiki", "graph.json");
   let needsBuild = false;
   try {
     const fileStat = await stat9(graphPath);
@@ -7799,7 +8204,7 @@ async function loadOrBuildGraph(vault) {
     if (buildResult.exitCode !== 0) return null;
   }
   try {
-    const raw = await readFile26(graphPath, "utf8");
+    const raw = await readFile27(graphPath, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -7807,14 +8212,14 @@ async function loadOrBuildGraph(vault) {
 }
 
 // src/utils/auto-commit.ts
-import { existsSync as existsSync16 } from "fs";
-import { join as join42 } from "path";
+import { existsSync as existsSync17 } from "fs";
+import { join as join43 } from "path";
 async function postCommit(vault, exitCode) {
   if (exitCode !== 0) return;
   const home = process.env.HOME ?? "";
   const dotenv = await parseDotenvFile(configPath(home));
   if (dotenv["AUTO_COMMIT"] === "false") return;
-  if (!existsSync16(join42(vault, ".git"))) return;
+  if (!existsSync17(join43(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain"]);
@@ -7865,7 +8270,7 @@ program.command("validate <file>").description("validate vault page frontmatter
   emit(await runValidate({ file, apply: !!opts.apply, vault }), vault);
 });
 program.command("graph").description("graph subcommands").command("build <vault>").option("--out <path>", "graph output path (default: <vault>/.skillwiki/graph.json)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
-  const out = opts.out ?? join43(vault, ".skillwiki", "graph.json");
+  const out = opts.out ?? join44(vault, ".skillwiki", "graph.json");
   emit(await runGraphBuild({ vault, out }), vault);
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");