skillwiki 0.5.1 → 0.5.4

package/dist/cli.js

@@ -9,7 +9,7 @@ import {
 
 // src/cli.ts
 import { readFileSync as readFileSync10 } from "fs";
-import { join as join38 } from "path";
+import { join as join39 } from "path";
 import { Command as Command2 } from "commander";
 
 // ../shared/src/exit-codes.ts
@@ -59,7 +59,9 @@ var ExitCode = {
   SYNC_PUSH_FAILED: 42,
   SYNC_PULL_FAILED: 43,
   BACKUP_SYNC_FAILED: 44,
-  BACKUP_RESTORE_CONFLICTS: 45
+  BACKUP_RESTORE_CONFLICTS: 45,
+  USAGE: 46,
+  BODY_TRUNCATION_GUARD: 47
 };
 
 // ../shared/src/json-output.ts
@@ -91,7 +93,8 @@ var TypedKnowledgeSchema = z.object({
   contradictions: z.array(z.string()).optional(),
   provenance: z.enum(["research", "project", "mixed"]).optional(),
   provenance_projects: z.array(wikilink).optional(),
-  work_items: z.array(wikilink).optional()
+  work_items: z.array(wikilink).optional(),
+  stale_ttl: z.number().int().positive().optional()
 }).superRefine((v, ctx) => {
   if (v.provenance && v.provenance !== "research" && (!v.provenance_projects || v.provenance_projects.length === 0)) {
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance_projects"], message: "required when provenance != research" });
@@ -305,11 +308,11 @@ async function runHash(input) {
   }
   const split = splitFrontmatter(text);
   if (!split.ok) return { exitCode: ExitCode.MISSING_CLOSING_DELIMITER, result: split };
-  const bodyBytes = Buffer.from(split.data.body, "utf8");
-  const sha256 = createHash("sha256").update(bodyBytes).digest("hex");
+  const bodyBytes2 = Buffer.from(split.data.body, "utf8");
+  const sha256 = createHash("sha256").update(bodyBytes2).digest("hex");
   return {
     exitCode: ExitCode.OK,
-    result: ok({ path: input.file, sha256, byte_count: bodyBytes.byteLength, humanHint: sha256 })
+    result: ok({ path: input.file, sha256, byte_count: bodyBytes2.byteLength, humanHint: sha256 })
   };
 }
 
@@ -1004,8 +1007,10 @@ function isLegacyCitationStyle(body) {
   return false;
 }
 function hasOrphanedCitations(body) {
-  const stripped = stripFences(body.replace(FRONTMATTER, ""));
+  const noFm = body.replace(FRONTMATTER, "");
+  const stripped = stripFences(noFm);
   const lines = stripped.split("\n");
+  const rawLines = noFm.split("\n");
   let inSources = false;
   let sourcesEnded = false;
   let sourcesStartLine = -1;
@@ -1025,10 +1030,13 @@ function hasOrphanedCitations(body) {
       }
       continue;
     }
-    const isListItem = /^\s*[-*]\s+/.test(line);
+    const isListItem = /^\s*(?:[-*]|\d+\.)\s+/.test(line);
     const hasMarker = /\^\[raw\//.test(line);
+    const hasBacktickRawPath = /`raw\/[^`]+`/.test(rawLines[i]);
     if (isListItem && hasMarker) {
       lastNonBlankInSources = i;
+    } else if (isListItem && hasBacktickRawPath) {
+      lastNonBlankInSources = i;
     } else if (hasMarker && !isListItem) {
       return true;
     } else {
@@ -1835,6 +1843,42 @@ async function runIndexCheck(input) {
 // src/commands/stale.ts
 import { readdir as readdir4, rename as rename2, mkdir as mkdir6, readFile as readFile10 } from "fs/promises";
 import { join as join13 } from "path";
+
+// src/parsers/expiry-annotations.ts
+var HEADING_RE = /^#{1,6}\s+(.+)$/;
+var ANNOTATION_RE = /^<!--\s*expires:\s*(\d{4}-\d{2}-\d{2})(?:\s+refresh:\s*(weekly|monthly|quarterly))?(?:\s+source:\s*(\S+))?\s*-->$/;
+var VALID_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function isValidDate(s) {
+  if (!VALID_DATE_RE.test(s)) return false;
+  const d = /* @__PURE__ */ new Date(s + "T00:00:00Z");
+  return !Number.isNaN(d.getTime()) && s === d.toISOString().slice(0, 10);
+}
+function parseExpiryAnnotations(content, pagePath) {
+  const lines = content.split("\n");
+  const annotations = [];
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(ANNOTATION_RE);
+    if (!match) continue;
+    const expires = match[1];
+    if (!isValidDate(expires)) continue;
+    if (i === 0) continue;
+    const prevLine = lines[i - 1];
+    const headingMatch = prevLine.match(HEADING_RE);
+    if (!headingMatch) continue;
+    annotations.push({
+      page: pagePath,
+      heading: headingMatch[1].trim(),
+      line: i + 1,
+      // 1-indexed
+      expires,
+      refresh: match[2],
+      source: match[3]
+    });
+  }
+  return annotations;
+}
+
+// src/commands/stale.ts
 function daysSince(isoDate2) {
   return Math.floor((Date.now() - Date.parse(isoDate2)) / 864e5);
 }
@@ -1852,6 +1896,12 @@ async function runStale(input) {
     projectSlugs = (await readdir4(projectsDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
   } catch {
   }
+  if (input.project) {
+    if (!projectSlugs.includes(input.project)) {
+      return { exitCode: ExitCode.USAGE, result: { ok: false, error: "UNKNOWN_PROJECT", detail: `Project "${input.project}" not found. Available: ${projectSlugs.join(", ") || "(none)"}` } };
+    }
+    projectSlugs = [input.project];
+  }
   for (const slug of projectSlugs) {
     const workPath = join13(projectsDir, slug, "work");
     let entries;
@@ -1893,9 +1943,10 @@ async function runStale(input) {
   function extractSlug(projectField) {
     return projectField.replace(/^\[\[/, "").replace(/\]\]$/, "").replace(/^"|"$/g, "");
   }
+  const TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "abandoned", "done", "invalid"]);
   const KIND_FROM_FILENAME = /^(?:\d{4}-\d{2}-\d{2})-(task|bug|idea|note|observation)-.+\.md$/;
   const LOOP_CYCLE_PATTERN = /loop-cycle-/;
-  const transcripts = scan.data.raw.filter((p) => p.relPath.startsWith("raw/transcripts/") && p.relPath.endsWith(".md"));
+  let transcripts = scan.data.raw.filter((p) => p.relPath.startsWith("raw/transcripts/") && p.relPath.endsWith(".md"));
   const claimedPaths = /* @__PURE__ */ new Set();
   const transcriptMeta = /* @__PURE__ */ new Map();
   for (const t of transcripts) {
@@ -1904,11 +1955,12 @@ async function runStale(input) {
       const fm = extractFrontmatter(content);
       let kind = fm.ok && typeof fm.data.kind === "string" ? fm.data.kind : "";
       let project = fm.ok && typeof fm.data.project === "string" ? fm.data.project : "";
+      if (input.project && !project.includes(input.project)) continue;
       let inferred = false;
       if (input.forceScan && !kind) {
-        const basename = t.relPath.split("/").pop();
-        if (!LOOP_CYCLE_PATTERN.test(basename)) {
-          const m = basename.match(KIND_FROM_FILENAME);
+        const basename2 = t.relPath.split("/").pop();
+        if (!LOOP_CYCLE_PATTERN.test(basename2)) {
+          const m = basename2.match(KIND_FROM_FILENAME);
           if (m) {
             kind = m[1];
             inferred = true;
@@ -1948,7 +2000,7 @@ async function runStale(input) {
         const overlap = wWords.filter((w) => tWords.has(w)).length;
         if (dirName.includes(tSlug) || tSlug.includes(wSlug) || overlap >= 1) {
           claimedPaths.add(t.relPath);
-          if (status === "done" || status === "invalid") {
+          if (TERMINAL_STATUSES.has(status)) {
             staleTranscripts.push({ path: t.relPath, reason: `work item projects/${slug}/work/${dirName} is ${status}` });
           }
           break;
@@ -1958,7 +2010,7 @@ async function runStale(input) {
       for (const [dir, status] of workDirs) {
         if (dir.split("/").pop().startsWith(datePrefix)) {
           claimedPaths.add(t.relPath);
-          if (status === "done" || status === "invalid") {
+          if (TERMINAL_STATUSES.has(status)) {
             staleTranscripts.push({ path: t.relPath, reason: `work item ${dir} is ${status}` });
           }
           break;
@@ -2003,10 +2055,8 @@ async function runStale(input) {
       continue;
     }
     const hasSpec = files.includes("spec.md"), hasPlan = files.includes("plan.md"), hasWI = files.includes("work-item.md");
-    if (status === "done") {
-      doneWorkItems.push({ path: relDir, reason: "completed \u2014 should be archived" });
-    } else if (status === "invalid") {
-      doneWorkItems.push({ path: relDir, reason: "invalid \u2014 should be archived" });
+    if (TERMINAL_STATUSES.has(status)) {
+      doneWorkItems.push({ path: relDir, reason: `${status || "completed"} \u2014 should be archived` });
     } else if (hasSpec && !hasPlan) {
       incompleteWorkItems.push({ path: relDir, reason: "has spec but no plan" });
     } else if (hasWI && !hasSpec && !hasPlan) {
@@ -2019,16 +2069,53 @@ async function runStale(input) {
       const text = await readFile10(join13(input.vault, page.relPath), "utf8");
       const fm = extractFrontmatter(text);
       if (fm.ok && typeof fm.data.updated === "string") {
+        if (input.project) {
+          const pp = fm.data.provenance_projects;
+          const linked = Array.isArray(pp) && pp.some((p) => String(p).includes(input.project));
+          if (!linked) continue;
+        }
         const age = daysSince(fm.data.updated);
-        if (age >= input.days) {
-          stale.push({ page: page.relPath, reason: `updated ${age} days ago (threshold: ${input.days})` });
+        const threshold = typeof fm.data.stale_ttl === "number" && fm.data.stale_ttl > 0 ? fm.data.stale_ttl : input.days;
+        if (age >= threshold) {
+          stale.push({ page: page.relPath, reason: `updated ${age} days ago (threshold: ${threshold})` });
         }
       }
     } catch {
     }
   }
+  const staleSections = [];
+  for (const page of scan.data.typedKnowledge) {
+    try {
+      const text = await readFile10(join13(input.vault, page.relPath), "utf8");
+      const projectFilter = input.project;
+      if (projectFilter) {
+        const fm = extractFrontmatter(text);
+        if (fm.ok) {
+          const pp = fm.data.provenance_projects;
+          const linked = Array.isArray(pp) && pp.some((p) => String(p).includes(projectFilter));
+          if (!linked) continue;
+        }
+      }
+      const annotations = parseExpiryAnnotations(text, page.relPath);
+      for (const ann of annotations) {
+        if (daysSince(ann.expires) >= 0) {
+          staleSections.push({
+            page: ann.page,
+            heading: ann.heading,
+            line: ann.line,
+            expires: ann.expires,
+            refresh: ann.refresh,
+            source: ann.source,
+            reason: `section "${ann.heading}" expired on ${ann.expires}`
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   if (input.archive) {
-    const archiveDir = join13(input.vault, "_archive", (/* @__PURE__ */ new Date()).toISOString().slice(0, 10));
+    const archiveDir = join13(input.vault, "_archive", today);
     await mkdir6(archiveDir, { recursive: true });
     const citedRawPaths = /* @__PURE__ */ new Set();
     for (const page of scan.data.typedKnowledge) {
@@ -2082,7 +2169,7 @@ async function runStale(input) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     });
   }
-  const total = stale.length + staleTranscripts.length + unclaimedTranscripts.length + incompleteWorkItems.length + doneWorkItems.length;
+  const total = stale.length + staleTranscripts.length + unclaimedTranscripts.length + incompleteWorkItems.length + doneWorkItems.length + staleSections.length;
   const hintLines = [];
   if (stale.length > 0) hintLines.push(`stale_pages: ${stale.length}`, ...stale.map((p) => `  ${p.page}: ${p.reason}`));
   if (staleTranscripts.length > 0) hintLines.push(`stale_transcripts: ${staleTranscripts.length}`, ...staleTranscripts.map((t) => `  ${t.path}: ${t.reason}`));
@@ -2090,6 +2177,7 @@ async function runStale(input) {
     hint: ${t.hint}` : ""}`));
   if (incompleteWorkItems.length > 0) hintLines.push(`incomplete_work_items: ${incompleteWorkItems.length}`, ...incompleteWorkItems.map((w) => `  ${w.path}: ${w.reason}`));
   if (doneWorkItems.length > 0) hintLines.push(`done_work_items: ${doneWorkItems.length}`, ...doneWorkItems.map((w) => `  ${w.path}: ${w.reason}`));
+  if (staleSections.length > 0) hintLines.push(`stale_sections: ${staleSections.length}`, ...staleSections.map((s) => `  ${s.page}#${s.heading}: ${s.reason}`));
   if (archived.length > 0) hintLines.push(`archived: ${archived.length}`, ...archived.map((a) => `  ${a}`));
   if (hintLines.length === 0) hintLines.push("no stale transcripts or incomplete work items");
   return { exitCode: total > 0 ? ExitCode.STALE_PAGE : ExitCode.OK, result: ok({
@@ -2098,6 +2186,7 @@ async function runStale(input) {
     unclaimed_transcripts: unclaimedTranscripts,
     incomplete_work_items: incompleteWorkItems,
     done_work_items: doneWorkItems,
+    stale_sections: staleSections,
     archived,
     humanHint: hintLines.join("\n")
   }) };
@@ -2274,8 +2363,8 @@ Chronological action log. Newest entries last. Skill writes append entries; lint
 
 // src/commands/lint.ts
 import { existsSync as existsSync3 } from "fs";
-import { readFile as readFile14, writeFile as writeFile8 } from "fs/promises";
-import { join as join18 } from "path";
+import { readFile as readFile15 } from "fs/promises";
+import { join as join19 } from "path";
 
 // src/commands/topic-map-check.ts
 var DEFAULT_THRESHOLD = 200;
@@ -2402,6 +2491,81 @@ async function runDedup(input) {
   };
 }
 
+// src/utils/safe-write.ts
+import { open, readFile as readFile14, rename as rename4, unlink as unlink2, writeFile as writeFile8 } from "fs/promises";
+import { randomBytes } from "crypto";
+import { dirname as dirname7, basename, join as join18 } from "path";
+var DEFAULT_MIN_BODY_RATIO = 0.5;
+var DEFAULT_MIN_OLD_BODY_BYTES = 200;
+function bodyBytes(text) {
+  const split = splitFrontmatter(text);
+  if (!split.ok) return Buffer.byteLength(text, "utf8");
+  return Buffer.byteLength(split.data.body, "utf8");
+}
+async function readIfExists(absPath) {
+  try {
+    return await readFile14(absPath, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+async function safeWritePage(absPath, newContent, opts = {}) {
+  const minRatio = opts.minBodyRatio === void 0 ? DEFAULT_MIN_BODY_RATIO : opts.minBodyRatio;
+  const minOldBytes = opts.minOldBodyBytes ?? DEFAULT_MIN_OLD_BODY_BYTES;
+  let oldContent;
+  try {
+    oldContent = await readIfExists(absPath);
+  } catch (e) {
+    return err("WRITE_FAILED", { path: absPath, phase: "read-existing", message: String(e) });
+  }
+  const isNew = oldContent === null;
+  const oldBodyBytes = isNew ? 0 : bodyBytes(oldContent);
+  const newBodyBytes = bodyBytes(newContent);
+  const bodyRatio = oldBodyBytes > 0 ? newBodyBytes / oldBodyBytes : null;
+  let guardSkippedSmall = false;
+  if (!isNew && minRatio !== null && bodyRatio !== null && bodyRatio < minRatio) {
+    if (oldBodyBytes < minOldBytes) {
+      guardSkippedSmall = true;
+    } else {
+      return err("BODY_TRUNCATION_GUARD", {
+        path: absPath,
+        oldBodyBytes,
+        newBodyBytes,
+        bodyRatio,
+        minBodyRatio: minRatio,
+        hint: "Refusing to write \u2014 new body lost too much content. Likely a parse-modify-serialize bug or a write race. Verify the page source before retrying."
+      });
+    }
+  }
+  if (!isNew && oldContent === newContent) {
+    return ok({ isNew: false, oldBodyBytes, newBodyBytes, bodyRatio, guardSkippedSmall });
+  }
+  const dir = dirname7(absPath);
+  const tmpName = `.${basename(absPath)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  const tmpPath = join18(dir, tmpName);
+  try {
+    const handle = await open(tmpPath, "w");
+    try {
+      await handle.writeFile(newContent, "utf8");
+      try {
+        await handle.sync();
+      } catch {
+      }
+    } finally {
+      await handle.close();
+    }
+    await rename4(tmpPath, absPath);
+    return ok({ isNew, oldBodyBytes, newBodyBytes, bodyRatio, guardSkippedSmall });
+  } catch (e) {
+    try {
+      await unlink2(tmpPath);
+    } catch {
+    }
+    return err("WRITE_FAILED", { path: absPath, phase: "atomic-write", message: String(e) });
+  }
+}
+
 // src/commands/raw-body-dedup.ts
 import { createHash as createHash2 } from "crypto";
 async function runRawBodyDedup(vault) {
@@ -2466,11 +2630,11 @@ function buildCliSurface() {
   program2.command("index-check").option("--wiki <name>");
   program2.command("index-link-format").option("--wiki <name>");
   program2.command("topic-map-check").option("--threshold <n>").option("--wiki <name>");
-  program2.command("stale").option("--archive").option("--days <n>").option("--force-scan").option("--wiki <name>");
+  program2.command("stale").option("--archive").option("--days <n>").option("--force-scan").option("--project <slug>").option("--refresh").option("--wiki <name>");
   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("lint").option("--days <n>").option("--lines <n>").option("--log-threshold <n>").option("--fix").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");
   program2.command("status").option("--wiki <name>");
@@ -2615,8 +2779,8 @@ function extractSourceEntries(rawFm) {
   return entries;
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "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"];
-var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "missing_diagram", "cli_refs"];
+var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "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"];
 async function runLint(input) {
   const buckets = {};
   const fixed = [];
@@ -2725,7 +2889,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 (!existsSync3(join18(input.vault, rawPath)) && !existsSync3(join18(input.vault, rawPath + ".md")) && !rawPath.startsWith("_archive/") && !existsSync3(join18(input.vault, "_archive", rawPath)) && !existsSync3(join18(input.vault, "_archive", rawPath + ".md"))) {
+        if (!existsSync3(join19(input.vault, rawPath)) && !existsSync3(join19(input.vault, rawPath + ".md")) && !rawPath.startsWith("_archive/") && !existsSync3(join19(input.vault, "_archive", rawPath)) && !existsSync3(join19(input.vault, "_archive", rawPath + ".md"))) {
           brokenSourceFlags.push(`${page.relPath}: ${rawPath}`);
         }
       }
@@ -2785,7 +2949,7 @@ async function runLint(input) {
         const text = await readPage(specPage);
         const fm = extractFrontmatter(text);
         if (fm.ok) {
-          specStatus = fm.data.status;
+          specStatus = typeof fm.data.status === "string" ? fm.data.status : void 0;
           specStarted = fm.data.started;
         }
       }
@@ -2816,11 +2980,11 @@ async function runLint(input) {
         const slugMatch = String(entry).match(/\[\[([^\]]+)\]\]/);
         if (!slugMatch) continue;
         const slug = slugMatch[1];
-        const knowledgePath = join18(input.vault, "projects", slug, "knowledge.md");
+        const knowledgePath = join19(input.vault, "projects", slug, "knowledge.md");
         if (!existsSync3(knowledgePath)) continue;
         const pageRef = page.relPath.replace(/\.md$/, "");
         try {
-          const knowledgeContent = await readFile14(knowledgePath, "utf8");
+          const knowledgeContent = await readFile15(knowledgePath, "utf8");
           if (!knowledgeContent.includes(`[[${pageRef}]]`)) {
             orphanedProjectPages.push(`${page.relPath}: not in projects/${slug}/knowledge.md`);
           }
@@ -2840,13 +3004,34 @@ async function runLint(input) {
       }
     }
     if (cliRefFlags.length > 0) buckets.cli_refs = cliRefFlags;
+    const staleSectionFlags = [];
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const approachingThreshold = 7;
+    for (const page of scan.data.typedKnowledge) {
+      try {
+        const text = await readPage(page);
+        const annotations = parseExpiryAnnotations(text, page.relPath);
+        for (const ann of annotations) {
+          if (ann.expires < today) {
+            staleSectionFlags.push(`${page.relPath}: section "${ann.heading}" expired on ${ann.expires}`);
+          } else {
+            const daysUntilExpiry = Math.floor((Date.parse(ann.expires) - Date.now()) / 864e5);
+            if (daysUntilExpiry <= approachingThreshold) {
+              staleSectionFlags.push(`${page.relPath}: section "${ann.heading}" expires in ${daysUntilExpiry} day(s) (${ann.expires})`);
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    if (staleSectionFlags.length > 0) buckets.stale_sections = staleSectionFlags;
     if (input.fix && 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 readFile14(absPath, "utf8");
+          const raw = await readFile15(absPath, "utf8");
           const split = splitFrontmatter(raw);
           if (!split.ok) {
             unresolved.push(relPath);
@@ -2924,7 +3109,11 @@ async function runLint(input) {
 ${rawFm}
 ---
 ${newBody}`;
-          await writeFile8(absPath, newContent, "utf8");
+          const w = await safeWritePage(absPath, newContent);
+          if (!w.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
           fixed.push(relPath);
         } catch {
           unresolved.push(relPath);
@@ -2941,7 +3130,7 @@ ${newBody}`;
       for (const relPath of noOverview) {
         try {
           const absPath = `${input.vault}/${relPath}`;
-          const raw = await readFile14(absPath, "utf8");
+          const raw = await readFile15(absPath, "utf8");
           const split = splitFrontmatter(raw);
           if (!split.ok) {
             unresolved.push(relPath);
@@ -2962,7 +3151,11 @@ ${rawFm}
 ${overviewSection}
 
 ${trimmedBody}`;
-          await writeFile8(absPath, newContent, "utf8");
+          const w = await safeWritePage(absPath, newContent);
+          if (!w.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
           fixed.push(relPath);
         } catch {
           unresolved.push(relPath);
@@ -2978,7 +3171,7 @@ ${trimmedBody}`;
       for (const relPath of missingTldrFlags) {
         try {
           const absPath = `${input.vault}/${relPath}`;
-          const raw = await readFile14(absPath, "utf8");
+          const raw = await readFile15(absPath, "utf8");
           const split = splitFrontmatter(raw);
           if (!split.ok) {
             unresolved.push(relPath);
@@ -3006,7 +3199,11 @@ ${trimmedBody}`;
           const newContent = `---
 ${trimmedFm}---
 ${lines.join("\n")}`;
-          await writeFile8(absPath, newContent, "utf8");
+          const w = await safeWritePage(absPath, newContent);
+          if (!w.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
           fixed.push(relPath);
         } catch {
           unresolved.push(relPath);
@@ -3024,7 +3221,7 @@ ${lines.join("\n")}`;
       for (const relPath of wikilinkCitationFlags) {
         try {
           const absPath = `${input.vault}/${relPath}`;
-          const raw = await readFile14(absPath, "utf8");
+          const raw = await readFile15(absPath, "utf8");
           const split = splitFrontmatter(raw);
           if (!split.ok) {
             unresolved.push(relPath);
@@ -3088,7 +3285,11 @@ ${lines.join("\n")}`;
 ${rawFm}
 ---
 ${newBody}`;
-          await writeFile8(absPath, newContent, "utf8");
+          const w = await safeWritePage(absPath, newContent);
+          if (!w.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
           wikilinkFixed.push(relPath);
         } catch {
           unresolved.push(relPath);
@@ -3106,6 +3307,38 @@ ${newBody}`;
   const errorOut = ERROR_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   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 };
+    const fSummary = {
+      errors: filtered.error.reduce((n, b) => n + b.items.length, 0),
+      warnings: filtered.warning.reduce((n, b) => n + b.items.length, 0),
+      info: filtered.info.reduce((n, b) => n + b.items.length, 0)
+    };
+    let fExit = ExitCode.OK;
+    if (fSummary.errors > 0) fExit = ExitCode.LINT_HAS_ERRORS;
+    else if (fSummary.warnings > 0 || fSummary.info > 0) fExit = ExitCode.LINT_HAS_WARNINGS;
+    return {
+      exitCode: fExit,
+      result: ok({
+        vault: { path: input.vault, source: input.source ?? "resolved" },
+        summary: fSummary,
+        by_severity: filtered,
+        fixed,
+        unresolved,
+        humanHint: `--only ${input.only}
+${match.length === 0 ? "0 violations" : match.map((b) => `  ${b.kind}: ${b.items.length}`).join("\n")}`
+      })
+    };
+  }
   const summary = {
     errors: errorOut.reduce((n, b) => n + b.items.length, 0),
     warnings: warningOut.reduce((n, b) => n + b.items.length, 0),
@@ -3145,14 +3378,14 @@ ${newBody}`;
 }
 
 // src/commands/config.ts
-import { readFile as readFile15 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
-import { join as join19 } from "path";
+import { join as join20 } from "path";
 function validateKey(key) {
   return CONFIG_KEYS.includes(key) || isValidWikiProfileKey(key);
 }
 function configPath(home) {
-  return join19(home, ".skillwiki", ".env");
+  return join20(home, ".skillwiki", ".env");
 }
 async function runConfigGet(input) {
   if (!validateKey(input.key)) {
@@ -3170,7 +3403,7 @@ async function runConfigSet(input) {
   try {
     let originalContent;
     try {
-      originalContent = await readFile15(filePath, "utf8");
+      originalContent = await readFile16(filePath, "utf8");
     } catch {
     }
     const existing = originalContent !== void 0 ? parseDotenvText(originalContent) : {};
@@ -3207,13 +3440,13 @@ async function runConfigPath(input) {
 
 // src/commands/doctor.ts
 import { existsSync as existsSync6, lstatSync, readlinkSync, readdirSync, readFileSync as readFileSync6, statSync as statSync2 } from "fs";
-import { join as join22, resolve as resolve4 } from "path";
+import { join as join23, resolve as resolve4 } from "path";
 import { execSync } from "child_process";
 import { platform } from "os";
 
 // src/utils/auto-update.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync5, mkdirSync as mkdirSync2 } from "fs";
-import { join as join20, dirname as dirname8 } from "path";
+import { join as join21, dirname as dirname8 } from "path";
 import { spawn } from "child_process";
 
 // src/utils/update-consts.ts
@@ -3224,7 +3457,7 @@ var CLI_DISABLE_FLAG = "--no-update-notifier";
 
 // src/utils/auto-update.ts
 function cachePath(home) {
-  return join20(home, ".skillwiki", CACHE_FILENAME);
+  return join21(home, ".skillwiki", CACHE_FILENAME);
 }
 function readCacheRaw(home) {
   try {
@@ -3274,12 +3507,12 @@ function triggerAutoUpdate(home, currentVersion) {
 
 // src/utils/plugin-registry.ts
 import { readFileSync as readFileSync5 } from "fs";
-import { join as join21 } from "path";
-var REGISTRY_PATH = join21(".claude", "plugins", "installed_plugins.json");
+import { join as join22 } from "path";
+var REGISTRY_PATH = join22(".claude", "plugins", "installed_plugins.json");
 var PLUGIN_KEY = "skillwiki@llm-wiki";
 function readInstalledPlugins(home) {
   try {
-    const raw = readFileSync5(join21(home, REGISTRY_PATH), "utf8");
+    const raw = readFileSync5(join22(home, REGISTRY_PATH), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -3322,12 +3555,12 @@ function detectCliChannels(argv, home) {
   }
   const plugin = findPlugin(home);
   if (plugin) {
-    const pluginBin = join22(plugin.installPath, "bin", "skillwiki");
+    const pluginBin = join23(plugin.installPath, "bin", "skillwiki");
     if (existsSync6(pluginBin)) {
       channels.push({ name: "plugin", path: pluginBin, isDevLink: false });
     }
   }
-  const installBin = join22(home, ".claude", "skills", "bin", "skillwiki");
+  const installBin = join23(home, ".claude", "skills", "bin", "skillwiki");
   if (existsSync6(installBin)) {
     channels.push({ name: "install", path: installBin, isDevLink: false });
   }
@@ -3408,9 +3641,9 @@ function checkVaultStructure(resolvedPath) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
   }
   const missing = [];
-  if (!existsSync6(join22(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  if (!existsSync6(join23(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
   for (const dir of ["raw", "entities", "concepts", "meta"]) {
-    if (!existsSync6(join22(resolvedPath, dir))) missing.push(dir + "/");
+    if (!existsSync6(join23(resolvedPath, dir))) missing.push(dir + "/");
   }
   if (missing.length === 0) {
     return check("pass", "vault_structure", "Vault structure valid", "All required files and directories present");
@@ -3418,7 +3651,7 @@ 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 ? join22(cwd, "packages", "skills") : void 0;
+  const srcDir = cwd ? join23(cwd, "packages", "skills") : void 0;
   if (srcDir && existsSync6(srcDir)) {
     const found = findSkillMd(srcDir);
     if (found.length > 0) {
@@ -3432,7 +3665,7 @@ function checkSkillsInstalled(home, cwd) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (plugin v${plugin.version})`);
     }
   }
-  const skillsDir = join22(home, ".claude", "skills");
+  const skillsDir = join23(home, ".claude", "skills");
   if (existsSync6(skillsDir)) {
     const found = findSkillMd(skillsDir);
     if (found.length > 0) {
@@ -3443,10 +3676,10 @@ function checkSkillsInstalled(home, cwd) {
 }
 function checkDuplicateSkills(home) {
   const plugin = findPlugin(home);
-  const skillsDir = join22(home, ".claude", "skills");
+  const skillsDir = join23(home, ".claude", "skills");
   const agentSkillDirs = [
-    { label: "~/.codex/skills/", path: join22(home, ".codex", "skills") },
-    { label: "~/.agents/skills/", path: join22(home, ".agents", "skills") }
+    { label: "~/.codex/skills/", path: join23(home, ".codex", "skills") },
+    { label: "~/.agents/skills/", path: join23(home, ".agents", "skills") }
   ];
   if (!plugin) {
     return check("pass", "skills_duplicate", "Skills not duplicated", "Single install channel");
@@ -3523,7 +3756,7 @@ async function checkProfiles(home) {
 }
 async function checkProjectLocalOverride(cwd) {
   const dir = cwd ?? process.cwd();
-  const envPath = join22(dir, ".skillwiki", ".env");
+  const envPath = join23(dir, ".skillwiki", ".env");
   if (existsSync6(envPath)) {
     return check("pass", "project_local", "Project-local config", `Found: ${envPath}`);
   }
@@ -3533,7 +3766,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 (!existsSync6(join22(resolvedPath, ".git"))) {
+  if (!existsSync6(join23(resolvedPath, ".git"))) {
     return check("warn", "vault_git_remote", "Vault git remote", "Vault is not a git repository \u2014 sync features unavailable");
   }
   try {
@@ -3556,9 +3789,9 @@ function checkObsidianTemplates(resolvedPath) {
     return check("error", "obsidian_templates", "Obsidian templates", "Cannot check \u2014 WIKI_PATH not resolved");
   }
   const missing = [];
-  if (!existsSync6(join22(resolvedPath, "_Templates"))) missing.push("_Templates/");
-  if (!existsSync6(join22(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
-  if (!existsSync6(join22(resolvedPath, ".obsidian", "app.json"))) missing.push(".obsidian/app.json");
+  if (!existsSync6(join23(resolvedPath, "_Templates"))) missing.push("_Templates/");
+  if (!existsSync6(join23(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
+  if (!existsSync6(join23(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");
   }
@@ -3568,7 +3801,7 @@ 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 = join22(resolvedPath, "raw");
+  const rawDir = join23(resolvedPath, "raw");
   if (!existsSync6(rawDir)) {
     return check("pass", "dsstore_clean", "No .DS_Store in raw/", "raw/ directory not found \u2014 check skipped");
   }
@@ -3584,7 +3817,7 @@ function checkDotStoreClean(resolvedPath) {
       if (entry.name === ".DS_Store") {
         found.push(rel ? `${rel}/.DS_Store` : ".DS_Store");
       } else if (entry.isDirectory()) {
-        walk2(join22(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
+        walk2(join23(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
       }
     }
   })(rawDir, "");
@@ -3597,7 +3830,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 (!existsSync6(join22(resolvedPath, ".git"))) {
+  if (!existsSync6(join23(resolvedPath, ".git"))) {
     return check("pass", "sync_last_push", "Vault sync recency", "No git repo \u2014 sync check skipped");
   }
   let timestamp;
@@ -3671,7 +3904,7 @@ function checkS3MountPerf(resolvedPath) {
   if (!mountPoint) {
     return check("pass", "s3_mount_perf", "S3 mount performance", "local disk");
   }
-  const conceptsDir = join22(resolvedPath, "concepts");
+  const conceptsDir = join23(resolvedPath, "concepts");
   if (!existsSync6(conceptsDir)) {
     return check("pass", "s3_mount_perf", "S3 mount performance", `S3 FUSE mount (${mountPoint}), no concepts/ to benchmark`);
   }
@@ -3721,9 +3954,9 @@ function findSkillMd(dir) {
   }
   for (const entry of entries) {
     if (entry.isFile() && entry.name === "SKILL.md") {
-      results.push(join22(dir, entry.name));
+      results.push(join23(dir, entry.name));
     } else if (entry.isDirectory()) {
-      results.push(...findSkillMd(join22(dir, entry.name)));
+      results.push(...findSkillMd(join23(dir, entry.name)));
     }
   }
   return results;
@@ -3737,7 +3970,7 @@ function findSkillNames(dir) {
     return results;
   }
   for (const entry of entries) {
-    if (entry.isDirectory() && existsSync6(join22(dir, entry.name, "SKILL.md"))) {
+    if (entry.isDirectory() && existsSync6(join23(dir, entry.name, "SKILL.md"))) {
       results.push(entry.name);
     }
   }
@@ -3791,8 +4024,8 @@ async function runDoctor(input) {
 }
 
 // src/commands/archive.ts
-import { rename as rename4, mkdir as mkdir8, readFile as readFile16, writeFile as writeFile9 } from "fs/promises";
-import { join as join23, dirname as dirname9 } from "path";
+import { rename as rename5, mkdir as mkdir8, readFile as readFile17, writeFile as writeFile9 } from "fs/promises";
+import { join as join24, dirname as dirname9 } from "path";
 async function runArchive(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -3808,13 +4041,13 @@ 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 archivePath = join23("_archive", relPath).replace(/\\/g, "/");
-  await mkdir8(dirname9(join23(input.vault, archivePath)), { recursive: true });
+  const archivePath = join24("_archive", relPath).replace(/\\/g, "/");
+  await mkdir8(dirname9(join24(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
   if (!isRaw) {
-    const indexPath = join23(input.vault, "index.md");
+    const indexPath = join24(input.vault, "index.md");
     try {
-      const idx = await readFile16(indexPath, "utf8");
+      const idx = await readFile17(indexPath, "utf8");
       const slug = relPath.replace(/\.md$/, "").split("/").pop();
       const originalLines = idx.split("\n");
       const filtered = originalLines.filter((l) => !l.includes(`[[${slug}]]`));
@@ -3826,7 +4059,7 @@ async function runArchive(input) {
       if (e instanceof Error && "code" in e && e.code !== "ENOENT") throw e;
     }
   }
-  await rename4(join23(input.vault, relPath), join23(input.vault, archivePath));
+  await rename5(join24(input.vault, relPath), join24(input.vault, archivePath));
   appendLastOp(input.vault, {
     operation: "archive",
     summary: `moved ${relPath} to ${archivePath}`,
@@ -3838,7 +4071,6 @@ async function runArchive(input) {
 
 // src/commands/drift.ts
 import { createHash as createHash3 } from "crypto";
-import { writeFile as writeFile10 } from "fs/promises";
 
 // src/utils/fetch.ts
 async function controlledFetch(url, opts) {
@@ -3925,7 +4157,7 @@ async function runDrift(input) {
 ${newFm}
 ---
 ${body}`;
-      await writeFile10(raw.absPath, newText, "utf8");
+      await safeWritePage(raw.absPath, newText);
       results.push({
         raw_path: raw.relPath,
         source_url: sourceUrl,
@@ -3968,7 +4200,6 @@ ${body}`;
 }
 
 // src/commands/migrate-citations.ts
-import { writeFile as writeFile11 } from "fs/promises";
 var MARKER_RE2 = /\^\[(raw\/[^\]]+)\]/g;
 function moveMarkersToParagraphEnd(body) {
   const lines = body.split("\n");
@@ -4091,7 +4322,11 @@ ${migratedBody}${newFooter}`;
       continue;
     }
     if (!input.dryRun) {
-      await writeFile11(page.absPath, newText, "utf8");
+      const w = await safeWritePage(page.absPath, newText);
+      if (!w.ok) {
+        skipped.push(page.relPath);
+        continue;
+      }
     }
     migrated.push(page.relPath);
   }
@@ -4121,7 +4356,6 @@ ${migratedBody}${newFooter}`;
 }
 
 // src/commands/frontmatter-fix.ts
-import { writeFile as writeFile12 } from "fs/promises";
 function isoToday() {
   return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 }
@@ -4163,7 +4397,11 @@ ${newBody}`;
       continue;
     }
     if (!input.dryRun) {
-      await writeFile12(page.absPath, newText, "utf8");
+      const w = await safeWritePage(page.absPath, newText);
+      if (!w.ok) {
+        skipped.push(page.relPath);
+        continue;
+      }
     }
     fixed.push(page.relPath);
   }
@@ -4196,14 +4434,14 @@ ${newBody}`;
 // src/commands/update.ts
 import { execSync as execSync2 } from "child_process";
 import { readFileSync as readFileSync7 } from "fs";
-import { join as join24 } from "path";
+import { join as join25 } from "path";
 function resolveGlobalSkillsRoot() {
   try {
     const globalRoot = execSync2("npm root -g", {
       encoding: "utf8",
       timeout: 5e3
     }).trim();
-    return join24(globalRoot, "skillwiki", "skills");
+    return join25(globalRoot, "skillwiki", "skills");
   } catch {
     return null;
   }
@@ -4229,7 +4467,7 @@ async function runUpdate(input) {
   );
   const currentVersion = pkg2.version;
   const tag = input.distTag ?? "latest";
-  const target = join24(input.home, ".claude", "skills");
+  const target = join25(input.home, ".claude", "skills");
   let latest;
   try {
     latest = execSync2(`npm view skillwiki@${tag} version`, {
@@ -4300,14 +4538,14 @@ async function runUpdate(input) {
 // src/commands/self-update.ts
 import { execSync as execSync3 } from "child_process";
 import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
-import { join as join25 } from "path";
+import { join as join26 } from "path";
 var DEFAULT_SOURCE_ROOT_SUFFIX = "/Desktop/code/llm-wiki";
 async function runSelfUpdate(input) {
   const currentVersion = JSON.parse(
     readFileSync8(new URL("../../package.json", import.meta.url), "utf8")
   ).version;
   const sourceRoot = input.sourceRoot ?? `${input.home}${DEFAULT_SOURCE_ROOT_SUFFIX}`;
-  const localPkgPath = join25(sourceRoot, "packages", "cli", "package.json");
+  const localPkgPath = join26(sourceRoot, "packages", "cli", "package.json");
   const hasLocalSource = existsSync7(localPkgPath);
   if (input.check) {
     let availableVersion = null;
@@ -4439,10 +4677,10 @@ async function runSelfUpdate(input) {
 }
 
 // src/commands/transcripts.ts
-import { readdir as readdir5, stat as stat6, readFile as readFile17 } from "fs/promises";
-import { join as join26 } from "path";
+import { readdir as readdir5, stat as stat6, readFile as readFile18 } from "fs/promises";
+import { join as join27 } from "path";
 async function runTranscripts(input) {
-  const dir = join26(input.vault, "raw", "transcripts");
+  const dir = join27(input.vault, "raw", "transcripts");
   let entries;
   try {
     entries = await readdir5(dir, { withFileTypes: true });
@@ -4452,8 +4690,8 @@ async function runTranscripts(input) {
   const transcripts = [];
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-    const filePath = join26(dir, entry.name);
-    const content = await readFile17(filePath, "utf8");
+    const filePath = join27(dir, entry.name);
+    const content = await readFile18(filePath, "utf8");
     const fm = extractFrontmatter(content);
     if (!fm.ok) continue;
     const ingested = typeof fm.data.ingested === "string" ? fm.data.ingested : "";
@@ -4470,12 +4708,12 @@ async function runTranscripts(input) {
 }
 
 // src/commands/project-index.ts
-import { readdir as readdir6, readFile as readFile18, writeFile as writeFile13, mkdir as mkdir9 } from "fs/promises";
-import { join as join27, dirname as dirname10 } from "path";
+import { readdir as readdir6, readFile as readFile19, writeFile as writeFile10, mkdir as mkdir9 } from "fs/promises";
+import { join as join28, dirname as dirname10 } from "path";
 var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
 async function runProjectIndex(input) {
   const slug = input.slug;
-  const projectDir = join27(input.vault, "projects", slug);
+  const projectDir = join28(input.vault, "projects", slug);
   try {
     await readdir6(projectDir);
   } catch {
@@ -4486,15 +4724,15 @@ async function runProjectIndex(input) {
   }
   const wikilinkPattern = `[[${slug}]]`;
   const entries = [];
-  const compoundDir = join27(input.vault, "projects", slug, "compound");
+  const compoundDir = join28(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 = join27(compoundDir, entry.name);
+      const filePath = join28(compoundDir, entry.name);
       let text;
       try {
-        text = await readFile18(filePath, "utf8");
+        text = await readFile19(filePath, "utf8");
       } catch {
         continue;
       }
@@ -4511,16 +4749,16 @@ async function runProjectIndex(input) {
   for (const dir of LAYER2_DIRS) {
     let files;
     try {
-      files = await readdir6(join27(input.vault, dir), { withFileTypes: true });
+      files = await readdir6(join28(input.vault, dir), { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of files) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-      const filePath = join27(input.vault, dir, entry.name);
+      const filePath = join28(input.vault, dir, entry.name);
       let text;
       try {
-        text = await readFile18(filePath, "utf8");
+        text = await readFile19(filePath, "utf8");
       } catch {
         continue;
       }
@@ -4541,11 +4779,11 @@ async function runProjectIndex(input) {
     const tb = typeOrder[b.type] ?? 99;
     return ta !== tb ? ta - tb : a.title.localeCompare(b.title);
   });
-  const indexPath = join27(projectDir, "knowledge.md");
+  const indexPath = join28(projectDir, "knowledge.md");
   let existing = false;
   let stale = false;
   try {
-    const existingText = await readFile18(indexPath, "utf8");
+    const existingText = await readFile19(indexPath, "utf8");
     existing = true;
     const existingEntries = existingText.split("\n").filter((l) => l.startsWith("- [["));
     const existingPages = new Set(existingEntries.map((l) => {
@@ -4586,7 +4824,7 @@ Autogenerated by \`skillwiki project-index\` on ${today}.
   if (input.apply) {
     try {
       await mkdir9(dirname10(indexPath), { recursive: true });
-      await writeFile13(indexPath, body, "utf8");
+      await writeFile10(indexPath, body, "utf8");
     } catch (e) {
       return {
         exitCode: ExitCode.WRITE_FAILED,
@@ -4614,10 +4852,10 @@ ${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e
 }
 
 // src/commands/compound.ts
-import { writeFile as writeFile14, mkdir as mkdir10, readdir as readdir7, unlink as unlink2 } from "fs/promises";
-import { join as join28 } from "path";
+import { writeFile as writeFile11, mkdir as mkdir10, readdir as readdir7, unlink as unlink3 } from "fs/promises";
+import { join as join29 } from "path";
 import { existsSync as existsSync8 } from "fs";
-import { readFile as readFile19 } from "fs/promises";
+import { readFile as readFile20 } 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,
@@ -4715,17 +4953,17 @@ function extractRetroFields(date, cycleName, block) {
   };
 }
 async function runCompound(input) {
-  const logPath = join28(input.vault, "log.md");
+  const logPath = join29(input.vault, "log.md");
   let logText;
   try {
-    logText = await readFile19(logPath, "utf8");
+    logText = await readFile20(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 = join28(input.vault, "projects", input.project, "compound");
+  const compoundDir = join29(input.vault, "projects", input.project, "compound");
   for (const entry of entries) {
     const generalizeValue = entry.generalize.trim();
     if (!/^yes/i.test(generalizeValue)) {
@@ -4733,7 +4971,7 @@ async function runCompound(input) {
       continue;
     }
     const slug = slugify(entry.cycleName);
-    const compoundPath = join28(compoundDir, `${slug}.md`);
+    const compoundPath = join29(compoundDir, `${slug}.md`);
     if (existsSync8(compoundPath)) {
       skipped.push(entry.date);
       continue;
@@ -4775,7 +5013,7 @@ async function runCompound(input) {
       if (!existsSync8(compoundDir)) {
         await mkdir10(compoundDir, { recursive: true });
       }
-      await writeFile14(compoundPath, content, "utf8");
+      await writeFile11(compoundPath, content, "utf8");
     }
     promoted.push(`${slug}.md`);
   }
@@ -4794,7 +5032,7 @@ async function runCompound(input) {
   };
 }
 async function runCompoundDelete(input) {
-  const projectDir = join28(input.vault, "projects", input.project);
+  const projectDir = join29(input.vault, "projects", input.project);
   if (!existsSync8(projectDir)) {
     return {
       exitCode: ExitCode.PROJECT_NOT_FOUND,
@@ -4802,7 +5040,7 @@ async function runCompoundDelete(input) {
     };
   }
   const entryName = input.entry.replace(/\.md$/, "");
-  const compoundPath = join28(projectDir, "compound", `${entryName}.md`);
+  const compoundPath = join29(projectDir, "compound", `${entryName}.md`);
   if (!existsSync8(compoundPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
@@ -4810,7 +5048,7 @@ async function runCompoundDelete(input) {
     };
   }
   try {
-    await unlink2(compoundPath);
+    await unlink3(compoundPath);
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -4836,7 +5074,7 @@ knowledge.md regenerated`
   };
 }
 async function runCompoundList(input) {
-  const compoundDir = join28(input.vault, "projects", input.project, "compound");
+  const compoundDir = join29(input.vault, "projects", input.project, "compound");
   if (!existsSync8(compoundDir)) {
     return {
       exitCode: ExitCode.OK,
@@ -4867,10 +5105,10 @@ could not read compound directory`
   const entries = [];
   for (const dirent of dirents) {
     if (!dirent.isFile() || !dirent.name.endsWith(".md")) continue;
-    const filePath = join28(compoundDir, dirent.name);
+    const filePath = join29(compoundDir, dirent.name);
     let text;
     try {
-      text = await readFile19(filePath, "utf8");
+      text = await readFile20(filePath, "utf8");
     } catch {
       continue;
     }
@@ -4899,9 +5137,9 @@ no compound entries found`;
 }
 
 // src/commands/observe.ts
-import { mkdir as mkdir11, writeFile as writeFile15 } from "fs/promises";
+import { mkdir as mkdir11, writeFile as writeFile12 } from "fs/promises";
 import { existsSync as existsSync9, statSync as statSync3 } from "fs";
-import { join as join29 } from "path";
+import { join as join30 } from "path";
 import { createHash as createHash4 } from "crypto";
 var ALLOWED_KINDS = /* @__PURE__ */ new Set(["note", "bug", "task", "idea", "session-log"]);
 function slugify2(text) {
@@ -4930,7 +5168,7 @@ async function runObserve(input) {
       result: err("VAULT_PATH_INVALID", { path: input.vault })
     };
   }
-  const transcriptsDir = join29(input.vault, "raw", "transcripts");
+  const transcriptsDir = join30(input.vault, "raw", "transcripts");
   try {
     await mkdir11(transcriptsDir, { recursive: true });
   } catch {
@@ -4942,7 +5180,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 = join29(transcriptsDir, fileName);
+  const filePath = join30(transcriptsDir, fileName);
   const body = `
 ${input.text.trim()}
 `;
@@ -4960,7 +5198,7 @@ ${input.text.trim()}
   frontmatterLines.push("---");
   const content = frontmatterLines.join("\n") + body;
   try {
-    await writeFile15(filePath, content, "utf8");
+    await writeFile12(filePath, content, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -4982,8 +5220,8 @@ ${input.text.trim()}
 }
 
 // src/commands/ingest.ts
-import { readFile as readFile20, writeFile as writeFile16, mkdir as mkdir12 } from "fs/promises";
-import { join as join30 } from "path";
+import { readFile as readFile21, writeFile as writeFile13, mkdir as mkdir12 } from "fs/promises";
+import { join as join31 } from "path";
 import { createHash as createHash5 } from "crypto";
 var ALLOWED_TYPES = /* @__PURE__ */ new Set(["entity", "concept", "comparison", "query"]);
 var TYPE_DIR = {
@@ -5142,7 +5380,7 @@ async function runIngest(input) {
     sourceContent = fetchResult.data.body;
   } else {
     try {
-      sourceContent = await readFile20(input.source, "utf8");
+      sourceContent = await readFile21(input.source, "utf8");
     } catch {
       return {
         exitCode: ExitCode.FILE_NOT_FOUND,
@@ -5157,8 +5395,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 = join30(input.vault, rawRelPath);
-  const typedAbsPath = join30(input.vault, typedRelPath);
+  const rawAbsPath = join31(input.vault, rawRelPath);
+  const typedAbsPath = join31(input.vault, typedRelPath);
   const rawContent = buildRawContent(sourceUrl, today, sha256, sourceContent);
   const typedContent = buildTypedContent(
     input.title,
@@ -5221,8 +5459,8 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir12(join30(input.vault, "raw", "articles"), { recursive: true });
-    await writeFile16(rawAbsPath, rawContent, "utf8");
+    await mkdir12(join31(input.vault, "raw", "articles"), { recursive: true });
+    await writeFile13(rawAbsPath, rawContent, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -5230,8 +5468,8 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir12(join30(input.vault, typedDir), { recursive: true });
-    await writeFile16(typedAbsPath, typedContent, "utf8");
+    await mkdir12(join31(input.vault, typedDir), { recursive: true });
+    await writeFile13(typedAbsPath, typedContent, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -5262,7 +5500,6 @@ async function runIngest(input) {
 }
 
 // src/commands/tag-sync.ts
-import { writeFile as writeFile17 } from "fs/promises";
 var ENUM_MIRRORS = {
   provenance: ["research", "project", "mixed"],
   confidence: ["high", "medium", "low"]
@@ -5377,7 +5614,11 @@ ${newFm}
 ---
 ${body}`;
     if (!input.dryRun) {
-      await writeFile17(page.absPath, newText, "utf8");
+      const w = await safeWritePage(page.absPath, newText);
+      if (!w.ok) {
+        unchanged++;
+        continue;
+      }
     }
     synced.push(page.relPath);
   }
@@ -5407,10 +5648,10 @@ ${body}`;
 
 // src/commands/sync.ts
 import { existsSync as existsSync10 } from "fs";
-import { join as join31 } from "path";
+import { join as join32 } from "path";
 function runSyncStatus(input) {
   const vault = input.vault;
-  if (!existsSync10(join31(vault, ".git"))) {
+  if (!existsSync10(join32(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: ok({
@@ -5479,7 +5720,7 @@ function runSyncStatus(input) {
 }
 async function runSyncPush(input) {
   const vault = input.vault;
-  if (!existsSync10(join31(vault, ".git"))) {
+  if (!existsSync10(join32(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -5564,7 +5805,7 @@ async function runSyncPush(input) {
 }
 async function runSyncPull(input) {
   const vault = input.vault;
-  if (!existsSync10(join31(vault, ".git"))) {
+  if (!existsSync10(join32(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -5640,7 +5881,7 @@ async function runSyncPull(input) {
 
 // src/commands/backup.ts
 import { statSync as statSync4, readdirSync as readdirSync2, readFileSync as readFileSync9, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
-import { join as join32, relative as relative3, dirname as dirname11 } from "path";
+import { join as join33, relative as relative3, dirname as dirname11 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
 // src/utils/s3-client.ts
@@ -5664,7 +5905,7 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([".git", ".obsidian", "_archive", "node_
 function* walkMarkdown(dir, base) {
   for (const entry of readdirSync2(dir, { withFileTypes: true })) {
     if (SKIP_DIRS.has(entry.name)) continue;
-    const full = join32(dir, entry.name);
+    const full = join33(dir, entry.name);
     if (entry.isDirectory()) {
       yield* walkMarkdown(full, base);
     } else if (entry.name.endsWith(".md")) {
@@ -5687,7 +5928,7 @@ async function runBackupSync(input) {
   let failed = 0;
   const files = [...walkMarkdown(input.vault, input.vault)];
   for (const relPath of files) {
-    const absPath = join32(input.vault, relPath);
+    const absPath = join33(input.vault, relPath);
     const localStat = statSync4(absPath);
     let needsUpload = true;
     try {
@@ -5763,7 +6004,7 @@ async function runBackupRestore(input) {
     const objects = list.Contents ?? [];
     for (const obj of objects) {
       if (!obj.Key) continue;
-      const localPath = join32(target, obj.Key);
+      const localPath = join33(target, obj.Key);
       try {
         const localStat = statSync4(localPath);
         if (obj.LastModified && localStat.mtime > obj.LastModified) {
@@ -5810,8 +6051,8 @@ async function runBackupRestore(input) {
 
 // src/commands/status.ts
 import { existsSync as existsSync11, statSync as statSync5 } from "fs";
-import { readFile as readFile21 } from "fs/promises";
-import { join as join33 } from "path";
+import { readFile as readFile22 } from "fs/promises";
+import { join as join34 } from "path";
 async function runStatus(input) {
   if (!existsSync11(input.vault)) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
@@ -5838,7 +6079,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile21(join33(input.vault, "SCHEMA.md"), "utf8");
+    const schemaContent = await readFile22(join34(input.vault, "SCHEMA.md"), "utf8");
     const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
     if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
@@ -5898,8 +6139,8 @@ async function runStatus(input) {
 }
 
 // src/commands/seed.ts
-import { mkdir as mkdir13, writeFile as writeFile18, stat as stat7 } from "fs/promises";
-import { join as join34 } from "path";
+import { mkdir as mkdir13, writeFile as writeFile14, stat as stat7 } from "fs/promises";
+import { join as join35 } from "path";
 var TODAY = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var EXAMPLE_PAGES = {
   "entities/example-project.md": `---
@@ -5968,30 +6209,30 @@ Real sources are immutable after ingestion \u2014 never edit them.
 `;
 async function runSeed(input) {
   try {
-    await stat7(join34(input.vault, "SCHEMA.md"));
+    await stat7(join35(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 = join34(input.vault, relPath);
+    const absPath = join35(input.vault, relPath);
     try {
       await stat7(absPath);
       skipped.push(relPath);
     } catch {
-      await mkdir13(join34(absPath, ".."), { recursive: true });
-      await writeFile18(absPath, content, "utf8");
+      await mkdir13(join35(absPath, ".."), { recursive: true });
+      await writeFile14(absPath, content, "utf8");
       created.push(relPath);
     }
   }
-  const rawPath = join34(input.vault, "raw", "articles", "example-source.md");
+  const rawPath = join35(input.vault, "raw", "articles", "example-source.md");
   try {
     await stat7(rawPath);
     skipped.push("raw/articles/example-source.md");
   } catch {
-    await mkdir13(join34(rawPath, ".."), { recursive: true });
-    await writeFile18(rawPath, EXAMPLE_RAW, "utf8");
+    await mkdir13(join35(rawPath, ".."), { recursive: true });
+    await writeFile14(rawPath, EXAMPLE_RAW, "utf8");
     created.push("raw/articles/example-source.md");
   }
   if (created.length > 0) {
@@ -6013,9 +6254,9 @@ async function runSeed(input) {
 }
 
 // src/commands/canvas.ts
-import { readFile as readFile22, writeFile as writeFile19 } from "fs/promises";
+import { readFile as readFile23, writeFile as writeFile15 } from "fs/promises";
 import { existsSync as existsSync12 } from "fs";
-import { join as join35 } from "path";
+import { join as join36 } from "path";
 var NODE_WIDTH = 240;
 var NODE_HEIGHT = 60;
 var COLUMN_SPACING = 400;
@@ -6093,7 +6334,7 @@ function buildCanvasEdges(adjacency) {
   return edges;
 }
 async function runCanvasGenerate(input) {
-  const graphPath = input.graphPath ?? join35(input.vault, ".skillwiki", "graph.json");
+  const graphPath = input.graphPath ?? join36(input.vault, ".skillwiki", "graph.json");
   if (!existsSync12(graphPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
@@ -6105,7 +6346,7 @@ async function runCanvasGenerate(input) {
   }
   let raw;
   try {
-    raw = await readFile22(graphPath, "utf8");
+    raw = await readFile23(graphPath, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
@@ -6131,9 +6372,9 @@ async function runCanvasGenerate(input) {
   const nodes = buildCanvasNodes(paths);
   const edges = buildCanvasEdges(graph.adjacency);
   const canvas = { nodes, edges };
-  const outPath = join35(input.vault, "vault-graph.canvas");
+  const outPath = join36(input.vault, "vault-graph.canvas");
   try {
-    await writeFile19(outPath, JSON.stringify(canvas, null, 2));
+    await writeFile15(outPath, JSON.stringify(canvas, null, 2));
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -6153,8 +6394,8 @@ written: ${outPath}`
 }
 
 // src/commands/query.ts
-import { readFile as readFile23, stat as stat8 } from "fs/promises";
-import { join as join36 } from "path";
+import { readFile as readFile24, stat as stat8 } from "fs/promises";
+import { join as join37 } from "path";
 var W_KEYWORD = 2;
 var W_SOURCE_OVERLAP = 4;
 var W_WIKILINK = 3;
@@ -6275,7 +6516,7 @@ function computeKeywordScore(terms, title, tags, body) {
   return score;
 }
 async function loadOrBuildGraph(vault) {
-  const graphPath = join36(vault, ".skillwiki", "graph.json");
+  const graphPath = join37(vault, ".skillwiki", "graph.json");
   let needsBuild = false;
   try {
     const fileStat = await stat8(graphPath);
@@ -6289,7 +6530,7 @@ async function loadOrBuildGraph(vault) {
     if (buildResult.exitCode !== 0) return null;
   }
   try {
-    const raw = await readFile23(graphPath, "utf8");
+    const raw = await readFile24(graphPath, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -6298,13 +6539,13 @@ async function loadOrBuildGraph(vault) {
 
 // src/utils/auto-commit.ts
 import { existsSync as existsSync13 } from "fs";
-import { join as join37 } from "path";
+import { join as join38 } 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 (!existsSync13(join37(vault, ".git"))) return;
+  if (!existsSync13(join38(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain"]);
@@ -6355,7 +6596,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 ?? join38(vault, ".skillwiki", "graph.json");
+  const out = opts.out ?? join39(vault, ".skillwiki", "graph.json");
   emit(await runGraphBuild({ vault, out }), vault);
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
@@ -6461,10 +6702,10 @@ program.command("topic-map-check [vault]").description("check whether a topic ma
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runTopicMapCheck({ vault: v.vault, threshold: opts.threshold }), v.vault);
 });
-program.command("stale [vault]").description("identify stale transcripts and incomplete work items").option("--archive", "move stale items to _archive/", false).option("--days <n>", "staleness threshold in days", (s) => parseInt(s, 10), 3).option("--force-scan", "infer kind/project from filename and content when frontmatter is missing", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("stale [vault]").description("identify stale transcripts and incomplete work items").option("--archive", "move stale items to _archive/", false).option("--days <n>", "staleness threshold in days", (s) => parseInt(s, 10), 3).option("--force-scan", "infer kind/project from filename and content when frontmatter is missing", false).option("--project <slug>", "scope to a single project").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runStale({ vault: v.vault, days: opts.days, archive: !!opts.archive, forceScan: !!opts.forceScan }), v.vault);
+  else emit(await runStale({ vault: v.vault, days: opts.days, archive: !!opts.archive, forceScan: !!opts.forceScan, project: opts.project }), v.vault);
 });
 program.command("claim <transcript> [vault]").description("claim an unclaimed transcript by creating a work item with source: link").option("--project <slug>", "project slug (overrides transcript frontmatter)").option("--slug <slug>", "work-item slug (defaults to transcript filename without date/kind prefix)").option("--wiki <name>", "wiki profile name").action(async (transcript, vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -6481,7 +6722,7 @@ program.command("log-rotate [vault]").description("rotate or trim the vault log
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runLogRotate({ vault: v.vault, threshold: opts.threshold, apply: !!opts.apply }), v.vault);
 });
-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 legacy_citation_style violations").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+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 legacy_citation_style violations").option("--only <bucket>", "run only the specified lint bucket").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runLint({
@@ -6490,7 +6731,8 @@ program.command("lint [vault]").description("run all vault health checks").optio
     days: opts.days,
     lines: opts.lines,
     logThreshold: opts.logThreshold,
-    fix: opts.fix ?? false
+    fix: opts.fix ?? false,
+    only: opts.only
   }), v.vault);
 });
 var configCmd = program.command("config").description("manage skillwiki configuration");
@@ -6597,7 +6839,10 @@ syncCmd.command("pull [vault]").description("pull remote vault changes and lint"
 var backupCmd = program.command("backup").description("manage S3-compatible remote backup");
 backupCmd.command("sync [vault]").description("sync vault to S3-compatible remote backup").option("--dry-run", "list actions without executing").option("--bucket <name>", "S3 bucket name").option("--endpoint <url>", "S3 endpoint URL").option("--region <region>", "S3 region", "us-east-1").option("--prune", "delete orphaned S3 objects not in vault", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
-  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  if (!v.ok) {
+    emit({ exitCode: v.exitCode, result: v.payload });
+    return;
+  }
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
   const dotenv = await parseDotenvFile(configPath(home));
   emit(await runBackupSync({
@@ -6613,7 +6858,10 @@ backupCmd.command("sync [vault]").description("sync vault to S3-compatible remot
 });
 backupCmd.command("restore [vault]").description("restore vault from S3-compatible remote backup").option("--bucket <name>", "S3 bucket name").option("--endpoint <url>", "S3 endpoint URL").option("--region <region>", "S3 region", "us-east-1").option("--target <dir>", "restore target directory (defaults to vault)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
-  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  if (!v.ok) {
+    emit({ exitCode: v.exitCode, result: v.payload });
+    return;
+  }
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
   const dotenv = await parseDotenvFile(configPath(home));
   emit(await runBackupRestore({