skillwiki 0.8.5-beta.3 → 0.8.5-beta.5

package/dist/cli.js

@@ -14,8 +14,7 @@ import {
 } from "./chunk-TPS5XD2J.js";
 
 // src/cli.ts
-import { readFileSync as readFileSync12 } from "fs";
-import { join as join44 } from "path";
+import { join as join45 } from "path";
 import { Command as Command2 } from "commander";
 
 // ../shared/src/exit-codes.ts
@@ -3048,8 +3047,9 @@ function buildCliSurface() {
   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("lint").option("--days <n>").option("--lines <n>").option("--log-threshold <n>").option("--fix").option("--only <bucket>").option("--summary").option("--examples <n>").option("--wiki <name>");
   program2.command("config");
+  program2.command("health").option("--wiki <name>").option("--sync <mode>").option("--no-fail").option("--out <path>").option("--examples <n>");
   program2.command("doctor");
   program2.command("status").option("--wiki <name>");
   program2.command("archive").option("--wiki <name>").option("--cascade").option("--apply");
@@ -3272,6 +3272,58 @@ var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_source_identi
 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", "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];
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function formatExample(item) {
+  if (typeof item === "string") return item;
+  if (item === null || item === void 0) return String(item);
+  try {
+    return JSON.stringify(item);
+  } catch {
+    return String(item);
+  }
+}
+function summarizeBucket(bucket, severity, vaultPath, examplesLimit) {
+  const safeLimit = Math.max(0, Math.min(examplesLimit, 10));
+  const examples = bucket.items.slice(0, safeLimit).map(formatExample);
+  return {
+    kind: bucket.kind,
+    severity,
+    count: bucket.items.length,
+    examples,
+    examples_limit: safeLimit,
+    sample_truncated: bucket.items.length > examples.length,
+    details_command: `skillwiki lint ${shellQuote(vaultPath)} --only ${bucket.kind}`
+  };
+}
+function summarizeLintOutput(output, examplesLimit = 3) {
+  const buckets = [
+    ...output.by_severity.error.map((bucket) => summarizeBucket(bucket, "error", output.vault.path, examplesLimit)),
+    ...output.by_severity.warning.map((bucket) => summarizeBucket(bucket, "warning", output.vault.path, examplesLimit)),
+    ...output.by_severity.info.map((bucket) => summarizeBucket(bucket, "info", output.vault.path, examplesLimit))
+  ];
+  const lines = [];
+  lines.push(`errors: ${output.summary.errors}`);
+  lines.push(`warnings: ${output.summary.warnings}`);
+  lines.push(`info: ${output.summary.info}`);
+  for (const bucket of buckets) {
+    lines.push(`  ${bucket.kind}: ${bucket.count}`);
+    if (bucket.examples.length > 0) {
+      lines.push(`    e.g. ${bucket.examples[0]}`);
+    }
+  }
+  return {
+    vault: output.vault,
+    summary: output.summary,
+    buckets,
+    details_included: false,
+    truncated: false,
+    fixed: output.fixed,
+    unresolved: output.unresolved,
+    humanHint: lines.join("\n")
+  };
+}
 async function runLint(input) {
   if (input.only && !KNOWN_BUCKETS.includes(input.only)) {
     return {
@@ -3904,17 +3956,18 @@ ${newBody}`;
     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;
+    const output2 = {
+      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")}`
+    };
     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")}`
-      })
+      result: ok(input.summary ? summarizeLintOutput(output2, input.examplesLimit) : output2)
     };
   }
   const summary = {
@@ -3942,19 +3995,31 @@ ${match.length === 0 ? "0 violations" : match.map((b) => `  ${b.kind}: ${b.items
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     });
   }
+  const output = {
+    vault: { path: input.vault, source: input.source ?? "resolved" },
+    summary,
+    by_severity: { error: errorOut, warning: warningOut, info: infoOut },
+    fixed,
+    unresolved,
+    humanHint: hintLines.join("\n")
+  };
   return {
     exitCode,
-    result: ok({
-      vault: { path: input.vault, source: input.source ?? "resolved" },
-      summary,
-      by_severity: { error: errorOut, warning: warningOut, info: infoOut },
-      fixed,
-      unresolved,
-      humanHint: hintLines.join("\n")
-    })
+    result: ok(input.summary ? summarizeLintOutput(output, input.examplesLimit) : output)
   };
 }
 
+// src/commands/health.ts
+import { existsSync as existsSync11, mkdirSync as mkdirSync4, readFileSync as readFileSync8, renameSync, writeFileSync as writeFileSync6 } from "fs";
+import { dirname as dirname10, join as join28, resolve as resolve6 } from "path";
+import { platform as platform3 } from "os";
+
+// src/commands/doctor.ts
+import { existsSync as existsSync10, lstatSync, readlinkSync, readdirSync as readdirSync2, 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/commands/config.ts
 import { readFile as readFile18 } from "fs/promises";
 import { existsSync as existsSync6 } from "fs";
@@ -4016,12 +4081,6 @@ async function runConfigPath(input) {
   return { exitCode: ExitCode.OK, result: ok({ path: filePath, exists: existsSync6(filePath), humanHint: filePath }) };
 }
 
-// src/commands/doctor.ts
-import { existsSync as existsSync10, lstatSync, readlinkSync, readdirSync as readdirSync2, 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 existsSync7, mkdirSync as mkdirSync3 } from "fs";
 import { join as join24, dirname as dirname9 } from "path";
@@ -5624,9 +5683,383 @@ async function runDoctor(input) {
   return { exitCode, result: ok({ checks, summary, humanHint }) };
 }
 
+// src/commands/health.ts
+function statusFromCounts(counts) {
+  if ((counts.error ?? 0) > 0) return "error";
+  if ((counts.warn ?? counts.warnings ?? 0) > 0) return "warn";
+  if ((counts.info ?? 0) > 0) return "info";
+  return "pass";
+}
+function maxStatus(statuses) {
+  const order = { pass: 0, info: 1, warn: 2, error: 3, unknown: 4 };
+  return statuses.reduce((max, status) => order[status] > order[max] ? status : max, "pass");
+}
+function bucketCount(buckets, kind) {
+  return buckets.find((bucket) => bucket.kind === kind)?.count ?? 0;
+}
+function bucketEvidence(prefix, buckets, kinds) {
+  return kinds.map((kind) => ({ kind, count: bucketCount(buckets, kind) })).filter((item) => item.count > 0).map((item) => `${prefix}.${item.kind}: ${item.count}`);
+}
+function shellQuote2(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function lintCommand(vaultPath, args) {
+  return `skillwiki lint ${shellQuote2(vaultPath)} ${args}`;
+}
+function deriveRiskFlags(lint, vaultSync, syncMode) {
+  const flags = [];
+  const integrityEvidence = bucketEvidence("lint", lint.buckets, [
+    "broken_sources",
+    "invalid_frontmatter",
+    "broken_wikilinks",
+    "raw_source_identity_conflict"
+  ]);
+  if (integrityEvidence.length > 0) {
+    flags.push({
+      id: "content_integrity_risk",
+      status: "error",
+      blocking: true,
+      evidence: integrityEvidence,
+      suggested_commands: [
+        lintCommand(lint.vault.path, "--summary"),
+        lintCommand(lint.vault.path, "--only broken_sources")
+      ]
+    });
+  }
+  const retrievalEvidence = bucketEvidence("lint", lint.buckets, [
+    "tag_not_in_taxonomy",
+    "orphans",
+    "orphaned_project_pages",
+    "missing_overview"
+  ]);
+  if (retrievalEvidence.length > 0) {
+    const hasError = bucketCount(lint.buckets, "tag_not_in_taxonomy") > 0;
+    flags.push({
+      id: "retrieval_quality_risk",
+      status: hasError ? "error" : "warn",
+      blocking: hasError,
+      evidence: retrievalEvidence,
+      suggested_commands: [lintCommand(lint.vault.path, "--summary")]
+    });
+  }
+  const duplicationEvidence = bucketEvidence("lint", lint.buckets, [
+    "raw_dedup",
+    "raw_body_duplicate",
+    "raw_subdirectory_duplicate"
+  ]);
+  if (duplicationEvidence.length > 0) {
+    flags.push({
+      id: "content_duplication_risk",
+      status: "warn",
+      blocking: false,
+      evidence: duplicationEvidence,
+      suggested_commands: [lintCommand(lint.vault.path, "--only raw_dedup")]
+    });
+  }
+  const syncEvidence = vaultSync.checks.filter((check2) => check2.status === "error" || check2.status === "warn").map((check2) => `vault_sync.${check2.id}: ${check2.status}`);
+  if (syncEvidence.length > 0) {
+    flags.push({
+      id: "sync_visibility_risk",
+      status: vaultSync.status === "error" ? "error" : "warn",
+      blocking: syncMode === "required",
+      evidence: syncEvidence,
+      suggested_commands: ["vault-sync-install"]
+    });
+  }
+  const backlogEvidence = bucketEvidence("lint", lint.buckets, [
+    "stale_page",
+    "page_too_large",
+    "work_item_health",
+    "log_rotate_needed"
+  ]);
+  if (backlogEvidence.length > 0) {
+    flags.push({
+      id: "maintenance_backlog",
+      status: "warn",
+      blocking: false,
+      evidence: backlogEvidence,
+      suggested_commands: [lintCommand(lint.vault.path, "--summary")]
+    });
+  }
+  return flags;
+}
+function summarizeChecks(checks) {
+  return {
+    pass: checks.filter((check2) => check2.status === "pass").length,
+    info: checks.filter((check2) => check2.status === "info").length,
+    warn: checks.filter((check2) => check2.status === "warn").length,
+    error: checks.filter((check2) => check2.status === "error").length,
+    skipped: checks.filter((check2) => /skipped/i.test(check2.detail)).length
+  };
+}
+function classifyLog(path, id, label, okPattern) {
+  if (!existsSync11(path)) return { id, label, status: "warn", detail: `log file missing: ${path}` };
+  const lines = readFileSync8(path, "utf8").split(/\r?\n/).filter(Boolean);
+  const last = lines[lines.length - 1] ?? "";
+  if (!last) return { id, label, status: "warn", detail: `log file empty: ${path}` };
+  if (/fail|error/i.test(last)) return { id, label, status: "error", detail: last.slice(0, 120) };
+  if (okPattern.test(last)) return { id, label, status: "pass", detail: last.slice(0, 120) };
+  return { id, label, status: "warn", detail: last.slice(0, 120) };
+}
+function runVaultSyncHealth(home, syncMode) {
+  if (syncMode === "off") {
+    return {
+      status: "pass",
+      blocking: false,
+      installed: false,
+      summary: { pass: 0, info: 0, warn: 0, error: 0, skipped: 1 },
+      checks: [{ id: "vault_sync_skipped", status: "pass", detail: "vault-sync checks skipped by --sync off" }]
+    };
+  }
+  const isMac = platform3() === "darwin";
+  const shareDir = isMac ? join28(home, "Library", "Application Support", "vault-sync", "bin") : join28(home, ".local", "share", "vault-sync", "bin");
+  const logDir = isMac ? join28(home, "Library", "Logs") : join28(home, ".local", "state", "vault-sync", "log");
+  const filterPath = join28(home, ".config", "rclone", "wiki-push-filters.txt");
+  const checks = [];
+  const pushScript = join28(shareDir, "wiki-push.sh");
+  checks.push(existsSync11(pushScript) ? { id: "vault_sync_installed", label: "Vault sync installed", status: "pass", detail: `Found: ${pushScript}` } : { id: "vault_sync_installed", label: "Vault sync installed", status: "error", detail: `Script missing: ${pushScript}` });
+  if (isMac) {
+    const pushPlist = join28(home, "Library", "LaunchAgents", "com.karlchow.wiki-push.plist");
+    const fetchPlist = join28(home, "Library", "LaunchAgents", "com.karlchow.wiki-fetch.plist");
+    checks.push(existsSync11(pushPlist) && existsSync11(fetchPlist) ? { id: "vault_sync_jobs_enabled", label: "Vault sync jobs enabled", status: "pass", detail: "launchd unit files present (read-only mode)" } : { id: "vault_sync_jobs_enabled", label: "Vault sync jobs enabled", status: "warn", detail: "launchd unit files missing (read-only mode)" });
+    checks.push({ id: "vault_sync_fuse_refresh_job", label: "Vault sync fuse refresh job", status: "pass", detail: "macOS host \u2014 check skipped" });
+  } else {
+    const pushTimer = join28(home, ".config", "systemd", "user", "wiki-push.timer");
+    const fetchTimer = join28(home, ".config", "systemd", "user", "wiki-fetch.timer");
+    const fuseTimer = join28(home, ".config", "systemd", "user", "wiki-fuse-refresh.timer");
+    const fuseService = join28(home, ".config", "systemd", "user", "wiki-fuse-refresh.service");
+    checks.push(existsSync11(pushTimer) && existsSync11(fetchTimer) ? { id: "vault_sync_jobs_enabled", label: "Vault sync jobs enabled", status: "pass", detail: "systemd timer unit files present (read-only mode)" } : { id: "vault_sync_jobs_enabled", label: "Vault sync jobs enabled", status: "warn", detail: "systemd timer unit files missing (read-only mode)" });
+    checks.push(existsSync11(fuseTimer) && existsSync11(fuseService) ? { id: "vault_sync_fuse_refresh_job", label: "Vault sync fuse refresh job", status: "pass", detail: "wiki-fuse-refresh unit files present (read-only mode)" } : { id: "vault_sync_fuse_refresh_job", label: "Vault sync fuse refresh job", status: "warn", detail: "wiki-fuse-refresh unit files missing (read-only mode)" });
+  }
+  checks.push(classifyLog(join28(logDir, "wiki-push.log"), "vault_sync_last_push_age", "Vault sync last push recency", /OK push/));
+  checks.push(classifyLog(join28(logDir, "wiki-fetch.log"), "vault_sync_last_fetch_status", "Vault sync last fetch status", /NOTIFY|OK behind|OK/));
+  if (!existsSync11(filterPath)) {
+    checks.push({ id: "vault_sync_filter_present", label: "Vault sync filter file present", status: "error", detail: `Filter missing: ${filterPath}` });
+  } else {
+    const content = readFileSync8(filterPath, "utf8");
+    const missing = ["remotely-save/data.json", ".skillwiki/sync.lock", ".claude/settings.local.json"].filter((item) => !content.includes(item));
+    checks.push(missing.length > 0 ? { id: "vault_sync_filter_present", label: "Vault sync filter file present", status: "warn", detail: `Missing excludes: ${missing.join(", ")}` } : { id: "vault_sync_filter_present", label: "Vault sync filter file present", status: "pass", detail: "Required excludes present" });
+  }
+  checks.push({ id: "vault_sync_snapshot_guard", label: "Snapshot script guard", status: "pass", detail: "Not a snapshotter host \u2014 check skipped" });
+  const summary = summarizeChecks(checks);
+  return {
+    status: statusFromCounts(summary),
+    blocking: syncMode === "required",
+    installed: checks.find((check2) => check2.id === "vault_sync_installed")?.status === "pass",
+    summary,
+    checks: checks.map((check2) => ({ id: check2.id, status: check2.status, detail: check2.detail }))
+  };
+}
+function deriveQueryReadiness(lint) {
+  const taxonomyErrors = bucketCount(lint.buckets, "tag_not_in_taxonomy");
+  const brokenLinks = bucketCount(lint.buckets, "broken_wikilinks") + bucketCount(lint.buckets, "broken_sources");
+  const orphanCount = bucketCount(lint.buckets, "orphans") + bucketCount(lint.buckets, "orphaned_project_pages");
+  const missingOverview = bucketCount(lint.buckets, "missing_overview");
+  const missingTldr = bucketCount(lint.buckets, "missing_tldr");
+  let score = 100;
+  score -= Math.min(40, taxonomyErrors * 2);
+  score -= Math.min(30, brokenLinks * 10);
+  score -= Math.min(20, orphanCount * 3);
+  score -= Math.min(15, missingOverview);
+  score -= Math.min(5, missingTldr);
+  score = Math.max(0, score);
+  const status = taxonomyErrors > 0 || brokenLinks > 0 ? "error" : score < 80 ? "warn" : "pass";
+  return {
+    status,
+    blocking: false,
+    summary: { score },
+    signals: [
+      { id: "taxonomy_errors", status: taxonomyErrors > 0 ? "error" : "pass", value: taxonomyErrors },
+      { id: "broken_links", status: brokenLinks > 0 ? "error" : "pass", value: brokenLinks },
+      { id: "orphan_count", status: orphanCount > 0 ? "warn" : "pass", value: orphanCount },
+      { id: "missing_overview", status: missingOverview > 0 ? "warn" : "pass", value: missingOverview },
+      { id: "missing_tldr", status: missingTldr > 0 ? "info" : "pass", value: missingTldr }
+    ]
+  };
+}
+function selfCheckReport(report) {
+  const errors = [];
+  const lint = report.components.lint;
+  const sumBySeverity = (severity) => lint.buckets.filter((bucket) => bucket.severity === severity).reduce((sum, bucket) => sum + bucket.count, 0);
+  if (lint.summary.errors !== sumBySeverity("error")) {
+    errors.push(`lint.summary.errors=${lint.summary.errors} but error bucket counts sum to ${sumBySeverity("error")}`);
+  }
+  if (lint.summary.warnings !== sumBySeverity("warning")) {
+    errors.push(`lint.summary.warnings=${lint.summary.warnings} but warning bucket counts sum to ${sumBySeverity("warning")}`);
+  }
+  if (lint.summary.info !== sumBySeverity("info")) {
+    errors.push(`lint.summary.info=${lint.summary.info} but info bucket counts sum to ${sumBySeverity("info")}`);
+  }
+  for (const component of ["doctor", "lint", "vault_sync", "query_readiness", "source_freshness"]) {
+    if (!report.coverage[component]) errors.push(`missing coverage entry for ${component}`);
+  }
+  for (const flag of report.risk_flags) {
+    if (flag.evidence.length === 0) errors.push(`risk flag ${flag.id} has no evidence`);
+  }
+  return { status: errors.length > 0 ? "error" : "pass", errors };
+}
+function buildHumanHint(report) {
+  const lines = [
+    `vault: ${report.vault.path} (via ${report.vault.source})`,
+    `overall: ${report.overall_status}`,
+    `doctor: ${report.components.doctor.summary.pass} pass, ${report.components.doctor.summary.info} info, ${report.components.doctor.summary.warn} warn, ${report.components.doctor.summary.error} error`,
+    `lint: ${report.components.lint.summary.errors} errors, ${report.components.lint.summary.warnings} warnings, ${report.components.lint.summary.info} info`
+  ];
+  for (const bucket of report.components.lint.buckets) {
+    lines.push(`  ${bucket.severity} ${bucket.kind}: ${bucket.count}`);
+  }
+  lines.push(`vault_sync: ${report.components.vault_sync.summary.pass} pass, ${report.components.vault_sync.summary.warn} warn, ${report.components.vault_sync.summary.error} error`);
+  lines.push(`query_readiness: ${report.components.query_readiness.status} (${report.components.query_readiness.summary.score}/100)`);
+  if (report.risk_flags.length > 0) {
+    lines.push("risk flags:");
+    for (const flag of report.risk_flags) {
+      lines.push(`  ${flag.id}: ${flag.status}${flag.blocking ? " (blocking)" : ""}`);
+    }
+  }
+  if (report.self_check.status === "error") {
+    lines.push("self-check: error");
+    for (const error of report.self_check.errors) lines.push(`  ${error}`);
+  }
+  return lines.join("\n");
+}
+function writeReport(out, report) {
+  mkdirSync4(dirname10(out), { recursive: true });
+  const tmp = `${out}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync6(tmp, JSON.stringify(ok(report), null, 2) + "\n", "utf8");
+  renameSync(tmp, out);
+}
+async function runHealth(input) {
+  const syncMode = input.sync ?? "optional";
+  const doctor = await runDoctor({
+    home: input.home,
+    envValue: input.envValue,
+    argv: input.argv,
+    currentVersion: input.currentVersion,
+    cwd: input.cwd
+  });
+  const lint = await runLint({
+    vault: input.vault,
+    source: input.vaultSource ?? "resolved",
+    days: 90,
+    lines: 200,
+    logThreshold: 500,
+    summary: true,
+    examplesLimit: input.examplesLimit ?? 3
+  });
+  if (!doctor.result.ok) return { exitCode: doctor.exitCode, result: doctor.result };
+  if (!lint.result.ok) return { exitCode: lint.exitCode, result: lint.result };
+  const doctorStatus = statusFromCounts(doctor.result.data.summary);
+  const vaultSync = runVaultSyncHealth(input.home, syncMode);
+  const queryReadiness = deriveQueryReadiness(lint.result.data);
+  const sourceFreshness = {
+    status: bucketCount(lint.result.data.buckets, "stale_page") > 0 || bucketCount(lint.result.data.buckets, "file_source_url") > 0 ? "warn" : "pass",
+    blocking: false,
+    summary: {
+      stale_pages: bucketCount(lint.result.data.buckets, "stale_page"),
+      file_source_url: bucketCount(lint.result.data.buckets, "file_source_url"),
+      stale_sections: bucketCount(lint.result.data.buckets, "stale_sections")
+    }
+  };
+  const doctorComponent = {
+    status: doctorStatus,
+    blocking: false,
+    summary: doctor.result.data.summary,
+    checks: doctor.result.data.checks.map((check2) => ({ id: check2.id, status: check2.status, detail: check2.detail }))
+  };
+  const lintComponent = {
+    status: statusFromCounts({ error: lint.result.data.summary.errors, warnings: lint.result.data.summary.warnings, info: lint.result.data.summary.info }),
+    blocking: true,
+    summary: lint.result.data.summary,
+    buckets: lint.result.data.buckets,
+    details_included: false,
+    truncated: false
+  };
+  const riskFlags = deriveRiskFlags(lint.result.data, vaultSync, syncMode);
+  const blockingStatuses = [
+    lintComponent.blocking ? lintComponent.status : "pass",
+    vaultSync.blocking ? vaultSync.status : "pass",
+    ...riskFlags.filter((flag) => flag.blocking).map((flag) => flag.status)
+  ];
+  const advisoryStatuses = [
+    doctorComponent.status,
+    vaultSync.status,
+    queryReadiness.status,
+    sourceFreshness.status,
+    ...riskFlags.filter((flag) => !flag.blocking).map((flag) => flag.status)
+  ];
+  const blockingStatus = maxStatus(blockingStatuses);
+  const advisoryStatus = maxStatus(advisoryStatuses);
+  const baseReport = {
+    schema_version: 1,
+    policy_version: 1,
+    tool: { name: "skillwiki", version: input.currentVersion },
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    command_kind: "diagnostic",
+    vault: { path: input.vault, source: input.vaultSource ?? "resolved" },
+    overall_status: maxStatus([blockingStatus, advisoryStatus]),
+    blocking_status: blockingStatus,
+    advisory_status: advisoryStatus,
+    coverage: {
+      doctor: { state: "checked", status: doctorStatus },
+      lint: { state: "checked", status: lintComponent.status },
+      vault_sync: syncMode === "off" ? { state: "skipped", status: "pass", reason: "--sync off" } : { state: "checked", status: vaultSync.status },
+      query_readiness: { state: "checked", status: queryReadiness.status },
+      source_freshness: { state: "checked", status: sourceFreshness.status }
+    },
+    components: {
+      doctor: doctorComponent,
+      lint: lintComponent,
+      vault_sync: vaultSync,
+      query_readiness: queryReadiness,
+      source_freshness: sourceFreshness
+    },
+    risk_flags: riskFlags,
+    details_included: false,
+    truncated: false,
+    mutated: false,
+    post_commit_ran: false,
+    report_complete: true,
+    report_written: false,
+    warnings: []
+  };
+  if (input.out) {
+    baseReport.report_path = input.out;
+  }
+  if (input.out && resolve6(input.out).startsWith(resolve6(input.vault) + "/")) {
+    baseReport.warnings.push({
+      id: "report_inside_vault",
+      message: "health report was written inside the vault; this may create sync churn"
+    });
+  }
+  const self_check = selfCheckReport(baseReport);
+  const reportWithoutHint = {
+    ...baseReport,
+    self_check,
+    overall_status: self_check.status === "error" ? "unknown" : baseReport.overall_status,
+    report_complete: self_check.status === "error" ? false : baseReport.report_complete
+  };
+  const report = {
+    ...reportWithoutHint,
+    humanHint: buildHumanHint(reportWithoutHint)
+  };
+  if (input.out) {
+    report.report_written = true;
+    writeReport(input.out, report);
+  }
+  let exitCode = ExitCode.OK;
+  if (!input.noFail) {
+    if (report.self_check.status === "error") exitCode = ExitCode.INTERNAL_ERROR;
+    else if (report.blocking_status === "error") exitCode = ExitCode.LINT_HAS_ERRORS;
+    else if (report.blocking_status === "warn" || report.advisory_status === "warn" || report.advisory_status === "error") {
+      exitCode = ExitCode.LINT_HAS_WARNINGS;
+    }
+  }
+  return { exitCode, result: ok(report) };
+}
+
 // src/commands/archive.ts
 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";
+import { join as join29, dirname as dirname11 } from "path";
 function countWikilinks(body, slug) {
   const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const re = new RegExp(`\\[\\[${escaped}(?:[|#][^\\]]*)?\\]\\]`, "g");
@@ -5654,7 +6087,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 = join28("_archive", relPath).replace(/\\/g, "/");
+  const archivePath = join29("_archive", relPath).replace(/\\/g, "/");
   let cascade;
   if (input.cascade) {
     const wikilinkRefs = [];
@@ -5678,7 +6111,7 @@ async function runArchive(input) {
     const indexRefs = [];
     if (!isRaw) {
       try {
-        const idx = await readFile20(join28(input.vault, "index.md"), "utf8");
+        const idx = await readFile20(join29(input.vault, "index.md"), "utf8");
         idx.split("\n").forEach((line, i) => {
           if (line.includes(`[[${slug}]]`)) indexRefs.push({ line: i + 1, text: line });
         });
@@ -5704,7 +6137,7 @@ async function runArchive(input) {
   }
   if (input.cascade && input.apply && cascade) {
     for (const ref of cascade.source_array_refs) {
-      const absPath = join28(input.vault, ref.page);
+      const absPath = join29(input.vault, ref.page);
       const text = await readFile20(absPath, "utf8");
       const split = splitFrontmatter(text);
       if (!split.ok) continue;
@@ -5722,10 +6155,10 @@ ${fmRewritten}
       }
     }
   }
-  await mkdir9(dirname10(join28(input.vault, archivePath)), { recursive: true });
+  await mkdir9(dirname11(join29(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
   if (!isRaw) {
-    const indexPath = join28(input.vault, "index.md");
+    const indexPath = join29(input.vault, "index.md");
     try {
       const idx = await readFile20(indexPath, "utf8");
       const originalLines = idx.split("\n");
@@ -5738,7 +6171,7 @@ ${fmRewritten}
       if (e instanceof Error && "code" in e && e.code !== "ENOENT") throw e;
     }
   }
-  await rename7(join28(input.vault, relPath), join28(input.vault, archivePath));
+  await rename7(join29(input.vault, relPath), join29(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)` : ""}`,
@@ -6147,15 +6580,37 @@ ${newBody}`;
 
 // src/commands/update.ts
 import { execSync as execSync3 } from "child_process";
-import { readFileSync as readFileSync8 } from "fs";
-import { join as join29 } from "path";
+import { join as join30 } from "path";
+
+// src/utils/package-info.ts
+import { readFileSync as readFileSync9 } from "fs";
+function packageJsonCandidateUrls(baseUrl = import.meta.url) {
+  return [
+    new URL("../package.json", baseUrl),
+    new URL("../../package.json", baseUrl)
+  ];
+}
+function readCliPackageJson(baseUrl = import.meta.url) {
+  for (const url of packageJsonCandidateUrls(baseUrl)) {
+    try {
+      const pkg2 = JSON.parse(readFileSync9(url, "utf8"));
+      if (typeof pkg2.version === "string") {
+        return { ...pkg2, version: pkg2.version };
+      }
+    } catch {
+    }
+  }
+  throw new Error(`Could not locate skillwiki package.json from ${baseUrl}`);
+}
+
+// src/commands/update.ts
 function resolveGlobalSkillsRoot() {
   try {
     const globalRoot = execSync3("npm root -g", {
       encoding: "utf8",
       timeout: 5e3
     }).trim();
-    return join29(globalRoot, "skillwiki", "skills");
+    return join30(globalRoot, "skillwiki", "skills");
   } catch {
     return null;
   }
@@ -6176,12 +6631,10 @@ async function refreshInstalledSkills(target) {
   }
 }
 async function runUpdate(input) {
-  const pkg2 = JSON.parse(
-    readFileSync8(new URL("../../package.json", import.meta.url), "utf8")
-  );
+  const pkg2 = readCliPackageJson();
   const currentVersion = pkg2.version;
   const tag = normalizeDistTag(input.distTag);
-  const target = join29(input.home, ".claude", "skills");
+  const target = join30(input.home, ".claude", "skills");
   let latest;
   try {
     latest = execSync3(`npm view skillwiki@${tag} version`, {
@@ -6252,24 +6705,22 @@ async function runUpdate(input) {
 
 // src/commands/self-update.ts
 import { execSync as execSync4 } from "child_process";
-import { existsSync as existsSync11, readFileSync as readFileSync9 } from "fs";
-import { join as join30 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync10 } from "fs";
+import { join as join31 } 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 currentVersion = readCliPackageJson().version;
   const sourceRoot = input.sourceRoot ?? `${input.home}${DEFAULT_SOURCE_ROOT_SUFFIX}`;
   const distTag = normalizeDistTag(input.distTag);
-  const localPkgPath = join30(sourceRoot, "packages", "cli", "package.json");
-  const hasLocalSource = existsSync11(localPkgPath);
+  const localPkgPath = join31(sourceRoot, "packages", "cli", "package.json");
+  const hasLocalSource = existsSync12(localPkgPath);
   if (input.check) {
     let availableVersion = null;
     let source;
     if (hasLocalSource) {
       source = "local";
       try {
-        availableVersion = JSON.parse(readFileSync9(localPkgPath, "utf8")).version ?? null;
+        availableVersion = JSON.parse(readFileSync10(localPkgPath, "utf8")).version ?? null;
       } catch {
         availableVersion = null;
       }
@@ -6327,7 +6778,7 @@ async function runSelfUpdate(input) {
     }
     const newVersion = (() => {
       try {
-        return JSON.parse(readFileSync9(localPkgPath, "utf8")).version ?? "unknown";
+        return JSON.parse(readFileSync10(localPkgPath, "utf8")).version ?? "unknown";
       } catch {
         return "unknown";
       }
@@ -6394,9 +6845,9 @@ async function runSelfUpdate(input) {
 
 // src/commands/transcripts.ts
 import { readdir as readdir5, stat as stat7, readFile as readFile21 } from "fs/promises";
-import { join as join31 } from "path";
+import { join as join32 } from "path";
 async function runTranscripts(input) {
-  const dir = join31(input.vault, "raw", "transcripts");
+  const dir = join32(input.vault, "raw", "transcripts");
   let entries;
   try {
     entries = await readdir5(dir, { withFileTypes: true });
@@ -6406,7 +6857,7 @@ async function runTranscripts(input) {
   const transcripts = [];
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-    const filePath = join31(dir, entry.name);
+    const filePath = join32(dir, entry.name);
     const content = await readFile21(filePath, "utf8");
     const fm = extractFrontmatter(content);
     if (!fm.ok) continue;
@@ -6425,11 +6876,11 @@ async function runTranscripts(input) {
 
 // src/commands/project-index.ts
 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";
+import { join as join33, dirname as dirname12 } from "path";
 var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
 async function runProjectIndex(input) {
   const slug = input.slug;
-  const projectDir = join32(input.vault, "projects", slug);
+  const projectDir = join33(input.vault, "projects", slug);
   try {
     await readdir6(projectDir);
   } catch {
@@ -6440,12 +6891,12 @@ async function runProjectIndex(input) {
   }
   const wikilinkPattern = `[[${slug}]]`;
   const entries = [];
-  const compoundDir = join32(input.vault, "projects", slug, "compound");
+  const compoundDir = join33(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 = join32(compoundDir, entry.name);
+      const filePath = join33(compoundDir, entry.name);
       let text;
       try {
         text = await readFile22(filePath, "utf8");
@@ -6465,13 +6916,13 @@ async function runProjectIndex(input) {
   for (const dir of LAYER2_DIRS) {
     let files;
     try {
-      files = await readdir6(join32(input.vault, dir), { withFileTypes: true });
+      files = await readdir6(join33(input.vault, dir), { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of files) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-      const filePath = join32(input.vault, dir, entry.name);
+      const filePath = join33(input.vault, dir, entry.name);
       let text;
       try {
         text = await readFile22(filePath, "utf8");
@@ -6495,7 +6946,7 @@ async function runProjectIndex(input) {
     const tb = typeOrder[b.type] ?? 99;
     return ta !== tb ? ta - tb : a.title.localeCompare(b.title);
   });
-  const indexPath = join32(projectDir, "knowledge.md");
+  const indexPath = join33(projectDir, "knowledge.md");
   let existing = false;
   let stale = false;
   try {
@@ -6539,7 +6990,7 @@ Autogenerated by \`skillwiki project-index\` on ${today}.
   }
   if (input.apply) {
     try {
-      await mkdir10(dirname11(indexPath), { recursive: true });
+      await mkdir10(dirname12(indexPath), { recursive: true });
       await writeFile11(indexPath, body, "utf8");
     } catch (e) {
       return {
@@ -6569,8 +7020,8 @@ ${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e
 
 // src/commands/compound.ts
 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 existsSync12 } from "fs";
+import { join as join34 } from "path";
+import { existsSync as existsSync13 } 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 = {
@@ -6669,7 +7120,7 @@ function extractRetroFields(date, cycleName, block) {
   };
 }
 async function runCompound(input) {
-  const logPath = join33(input.vault, "log.md");
+  const logPath = join34(input.vault, "log.md");
   let logText;
   try {
     logText = await readFile23(logPath, "utf8");
@@ -6679,7 +7130,7 @@ async function runCompound(input) {
   const entries = parseRetroEntries(logText);
   const promoted = [];
   const skipped = [];
-  const compoundDir = join33(input.vault, "projects", input.project, "compound");
+  const compoundDir = join34(input.vault, "projects", input.project, "compound");
   for (const entry of entries) {
     const generalizeValue = entry.generalize.trim();
     if (!/^yes/i.test(generalizeValue)) {
@@ -6687,8 +7138,8 @@ async function runCompound(input) {
       continue;
     }
     const slug = slugify(entry.cycleName);
-    const compoundPath = join33(compoundDir, `${slug}.md`);
-    if (existsSync12(compoundPath)) {
+    const compoundPath = join34(compoundDir, `${slug}.md`);
+    if (existsSync13(compoundPath)) {
       skipped.push(entry.date);
       continue;
     }
@@ -6726,7 +7177,7 @@ async function runCompound(input) {
     ].join("\n");
     const content = frontmatter + "\n" + body;
     if (!input.dryRun) {
-      if (!existsSync12(compoundDir)) {
+      if (!existsSync13(compoundDir)) {
         await mkdir11(compoundDir, { recursive: true });
       }
       await writeFile12(compoundPath, content, "utf8");
@@ -6748,16 +7199,16 @@ async function runCompound(input) {
   };
 }
 async function runCompoundDelete(input) {
-  const projectDir = join33(input.vault, "projects", input.project);
-  if (!existsSync12(projectDir)) {
+  const projectDir = join34(input.vault, "projects", input.project);
+  if (!existsSync13(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 = join33(projectDir, "compound", `${entryName}.md`);
-  if (!existsSync12(compoundPath)) {
+  const compoundPath = join34(projectDir, "compound", `${entryName}.md`);
+  if (!existsSync13(compoundPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("FILE_NOT_FOUND", { path: compoundPath })
@@ -6790,8 +7241,8 @@ knowledge.md regenerated`
   };
 }
 async function runCompoundList(input) {
-  const compoundDir = join33(input.vault, "projects", input.project, "compound");
-  if (!existsSync12(compoundDir)) {
+  const compoundDir = join34(input.vault, "projects", input.project, "compound");
+  if (!existsSync13(compoundDir)) {
     return {
       exitCode: ExitCode.OK,
       result: ok({
@@ -6821,7 +7272,7 @@ could not read compound directory`
   const entries = [];
   for (const dirent of dirents) {
     if (!dirent.isFile() || !dirent.name.endsWith(".md")) continue;
-    const filePath = join33(compoundDir, dirent.name);
+    const filePath = join34(compoundDir, dirent.name);
     let text;
     try {
       text = await readFile23(filePath, "utf8");
@@ -6854,8 +7305,8 @@ no compound entries found`;
 
 // src/commands/observe.ts
 import { mkdir as mkdir12, writeFile as writeFile13 } from "fs/promises";
-import { existsSync as existsSync13, statSync as statSync4 } from "fs";
-import { join as join34 } from "path";
+import { existsSync as existsSync14, statSync as statSync4 } from "fs";
+import { join as join35 } from "path";
 import { createHash as createHash4 } from "crypto";
 var ALLOWED_KINDS = /* @__PURE__ */ new Set(["note", "bug", "task", "idea", "session-log"]);
 function slugify2(text) {
@@ -6878,13 +7329,13 @@ async function runObserve(input) {
       result: err("SCHEME_REJECTED", { message: "Text must not be empty" })
     };
   }
-  if (!existsSync13(input.vault) || !statSync4(input.vault).isDirectory()) {
+  if (!existsSync14(input.vault) || !statSync4(input.vault).isDirectory()) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: input.vault })
     };
   }
-  const transcriptsDir = join34(input.vault, "raw", "transcripts");
+  const transcriptsDir = join35(input.vault, "raw", "transcripts");
   try {
     await mkdir12(transcriptsDir, { recursive: true });
   } catch {
@@ -6896,7 +7347,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 = join34(transcriptsDir, fileName);
+  const filePath = join35(transcriptsDir, fileName);
   const body = `
 ${input.text.trim()}
 `;
@@ -6937,7 +7388,7 @@ ${input.text.trim()}
 
 // src/commands/ingest.ts
 import { readFile as readFile24, writeFile as writeFile14, mkdir as mkdir13 } from "fs/promises";
-import { join as join35 } from "path";
+import { join as join36 } from "path";
 import { createHash as createHash5 } from "crypto";
 var ALLOWED_TYPES = /* @__PURE__ */ new Set(["entity", "concept", "comparison", "query"]);
 var TYPE_DIR = {
@@ -7111,8 +7562,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 = join35(input.vault, rawRelPath);
-  const typedAbsPath = join35(input.vault, typedRelPath);
+  const rawAbsPath = join36(input.vault, rawRelPath);
+  const typedAbsPath = join36(input.vault, typedRelPath);
   const identity = assessSourceIdentity({
     rawPath: rawRelPath,
     sourceUrl: sourceUrl ?? void 0,
@@ -7194,7 +7645,7 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir13(join35(input.vault, "raw", "articles"), { recursive: true });
+    await mkdir13(join36(input.vault, "raw", "articles"), { recursive: true });
     await writeFile14(rawAbsPath, rawContent, "utf8");
   } catch (e) {
     return {
@@ -7203,7 +7654,7 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir13(join35(input.vault, typedDir), { recursive: true });
+    await mkdir13(join36(input.vault, typedDir), { recursive: true });
     await writeFile14(typedAbsPath, typedContent, "utf8");
   } catch (e) {
     return {
@@ -7382,12 +7833,12 @@ ${body}`;
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync15 } from "fs";
-import { join as join37 } from "path";
+import { existsSync as existsSync16 } from "fs";
+import { join as join38 } from "path";
 
 // src/utils/sync-lock.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync4, readFileSync as readFileSync10, renameSync, unlinkSync as unlinkSync5, writeFileSync as writeFileSync6 } from "fs";
-import { join as join36 } from "path";
+import { existsSync as existsSync15, mkdirSync as mkdirSync5, readFileSync as readFileSync11, renameSync as renameSync2, unlinkSync as unlinkSync5, writeFileSync as writeFileSync7 } from "fs";
+import { join as join37 } from "path";
 import { createHash as createHash6 } from "crypto";
 function getSessionId() {
   if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
@@ -7395,13 +7846,13 @@ function getSessionId() {
   return process.pid.toString();
 }
 function lockPath(vault) {
-  return join36(vault, ".skillwiki", "sync.lock");
+  return join37(vault, ".skillwiki", "sync.lock");
 }
 function readLock(vault) {
   const path = lockPath(vault);
-  if (!existsSync14(path)) return null;
+  if (!existsSync15(path)) return null;
   try {
-    const raw = readFileSync10(path, "utf8");
+    const raw = readFileSync11(path, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -7414,9 +7865,9 @@ function isStale(lock, now) {
 }
 function acquireLock(vault, opts = {}) {
   const path = lockPath(vault);
-  const dir = join36(vault, ".skillwiki");
-  if (!existsSync14(dir)) {
-    mkdirSync4(dir, { recursive: true });
+  const dir = join37(vault, ".skillwiki");
+  if (!existsSync15(dir)) {
+    mkdirSync5(dir, { recursive: true });
   }
   const sessionId = opts.sessionId ?? getSessionId();
   const summary = opts.summary ?? "skillwiki sync";
@@ -7435,7 +7886,7 @@ function acquireLock(vault, opts = {}) {
   };
   try {
     const content = JSON.stringify(lock, null, 2) + "\n";
-    writeFileSync6(path, content, { flag: "wx" });
+    writeFileSync7(path, content, { flag: "wx" });
     return { ok: true, lock };
   } catch (e) {
     const err3 = e;
@@ -7455,12 +7906,12 @@ function acquireLock(vault, opts = {}) {
 function writeLockedFile(path, lock) {
   const tmp = path + ".tmp";
   const content = JSON.stringify(lock, null, 2) + "\n";
-  writeFileSync6(tmp, content);
-  renameSync(tmp, path);
+  writeFileSync7(tmp, content);
+  renameSync2(tmp, path);
 }
 function releaseLock(vault, opts = {}) {
   const path = lockPath(vault);
-  if (!existsSync14(path)) {
+  if (!existsSync15(path)) {
     return { released: false };
   }
   const sessionId = opts.sessionId ?? getSessionId();
@@ -7489,7 +7940,7 @@ function releaseLock(vault, opts = {}) {
 function runSyncStatus(input) {
   const vault = input.vault;
   const includeStashes = input.includeStashes ?? false;
-  if (!existsSync15(join37(vault, ".git"))) {
+  if (!existsSync16(join38(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: ok({
@@ -7567,7 +8018,7 @@ function runSyncStatus(input) {
 }
 async function runSyncPush(input) {
   const vault = input.vault;
-  if (!existsSync15(join37(vault, ".git"))) {
+  if (!existsSync16(join38(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -7690,7 +8141,7 @@ function enableGitLongPathsOnWindows(vault) {
 }
 async function runSyncPull(input) {
   const vault = input.vault;
-  if (!existsSync15(join37(vault, ".git"))) {
+  if (!existsSync16(join38(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -7862,7 +8313,7 @@ function runSyncPeers(input) {
 }
 function runSyncLock(input) {
   const vault = input.vault;
-  if (!existsSync15(vault)) {
+  if (!existsSync16(vault)) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: vault })
@@ -7897,7 +8348,7 @@ function runSyncLock(input) {
 }
 function runSyncUnlock(input) {
   const vault = input.vault;
-  if (!existsSync15(vault)) {
+  if (!existsSync16(vault)) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: vault })
@@ -7930,8 +8381,8 @@ function runSyncUnlock(input) {
 }
 
 // src/commands/backup.ts
-import { statSync as statSync5, readdirSync as readdirSync3, readFileSync as readFileSync11, mkdirSync as mkdirSync5, writeFileSync as writeFileSync7 } from "fs";
-import { join as join38, relative as relative3, dirname as dirname12 } from "path";
+import { statSync as statSync5, readdirSync as readdirSync3, readFileSync as readFileSync12, mkdirSync as mkdirSync6, writeFileSync as writeFileSync8 } from "fs";
+import { join as join39, relative as relative3, dirname as dirname13 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
 // src/utils/s3-client.ts
@@ -7955,7 +8406,7 @@ var SKIP_DIRS2 = /* @__PURE__ */ new Set([".git", ".obsidian", "_archive", "node
 function* walkMarkdown(dir, base) {
   for (const entry of readdirSync3(dir, { withFileTypes: true })) {
     if (SKIP_DIRS2.has(entry.name)) continue;
-    const full = join38(dir, entry.name);
+    const full = join39(dir, entry.name);
     if (entry.isDirectory()) {
       yield* walkMarkdown(full, base);
     } else if (entry.name.endsWith(".md")) {
@@ -7978,7 +8429,7 @@ async function runBackupSync(input) {
   let failed = 0;
   const files = [...walkMarkdown(input.vault, input.vault)];
   for (const relPath of files) {
-    const absPath = join38(input.vault, relPath);
+    const absPath = join39(input.vault, relPath);
     const localStat = statSync5(absPath);
     let needsUpload = true;
     try {
@@ -7997,7 +8448,7 @@ async function runBackupSync(input) {
       continue;
     }
     try {
-      const body = readFileSync11(absPath);
+      const body = readFileSync12(absPath);
       await client.send(new PutObjectCommand({ Bucket: input.bucket, Key: relPath, Body: body }));
       uploaded++;
     } catch {
@@ -8054,7 +8505,7 @@ async function runBackupRestore(input) {
     const objects = list.Contents ?? [];
     for (const obj of objects) {
       if (!obj.Key) continue;
-      const localPath = join38(target, obj.Key);
+      const localPath = join39(target, obj.Key);
       try {
         const localStat = statSync5(localPath);
         if (obj.LastModified && localStat.mtime > obj.LastModified) {
@@ -8067,8 +8518,8 @@ 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(dirname12(localPath), { recursive: true });
-          writeFileSync7(localPath, Buffer.from(body));
+          mkdirSync6(dirname13(localPath), { recursive: true });
+          writeFileSync8(localPath, Buffer.from(body));
           downloaded++;
         }
       } catch {
@@ -8100,11 +8551,11 @@ async function runBackupRestore(input) {
 }
 
 // src/commands/status.ts
-import { existsSync as existsSync16, statSync as statSync6 } from "fs";
+import { existsSync as existsSync17, statSync as statSync6 } from "fs";
 import { readFile as readFile25 } from "fs/promises";
-import { join as join39 } from "path";
+import { join as join40 } from "path";
 async function runStatus(input) {
-  if (!existsSync16(input.vault)) {
+  if (!existsSync17(input.vault)) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
   const scan = await scanVault(input.vault);
@@ -8129,7 +8580,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile25(join39(input.vault, "SCHEMA.md"), "utf8");
+    const schemaContent = await readFile25(join40(input.vault, "SCHEMA.md"), "utf8");
     const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
     if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
@@ -8190,7 +8641,7 @@ async function runStatus(input) {
 
 // src/commands/seed.ts
 import { mkdir as mkdir14, writeFile as writeFile15, stat as stat8 } from "fs/promises";
-import { join as join40 } from "path";
+import { join as join41 } from "path";
 var TODAY = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var EXAMPLE_PAGES = {
   "entities/example-project.md": `---
@@ -8259,29 +8710,29 @@ Real sources are immutable after ingestion \u2014 never edit them.
 `;
 async function runSeed(input) {
   try {
-    await stat8(join40(input.vault, "SCHEMA.md"));
+    await stat8(join41(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 = join40(input.vault, relPath);
+    const absPath = join41(input.vault, relPath);
     try {
       await stat8(absPath);
       skipped.push(relPath);
     } catch {
-      await mkdir14(join40(absPath, ".."), { recursive: true });
+      await mkdir14(join41(absPath, ".."), { recursive: true });
       await writeFile15(absPath, content, "utf8");
       created.push(relPath);
     }
   }
-  const rawPath = join40(input.vault, "raw", "articles", "example-source.md");
+  const rawPath = join41(input.vault, "raw", "articles", "example-source.md");
   try {
     await stat8(rawPath);
     skipped.push("raw/articles/example-source.md");
   } catch {
-    await mkdir14(join40(rawPath, ".."), { recursive: true });
+    await mkdir14(join41(rawPath, ".."), { recursive: true });
     await writeFile15(rawPath, EXAMPLE_RAW, "utf8");
     created.push("raw/articles/example-source.md");
   }
@@ -8305,8 +8756,8 @@ async function runSeed(input) {
 
 // src/commands/canvas.ts
 import { readFile as readFile26, writeFile as writeFile16 } from "fs/promises";
-import { existsSync as existsSync17 } from "fs";
-import { join as join41 } from "path";
+import { existsSync as existsSync18 } from "fs";
+import { join as join42 } from "path";
 var NODE_WIDTH = 240;
 var NODE_HEIGHT = 60;
 var COLUMN_SPACING = 400;
@@ -8384,8 +8835,8 @@ function buildCanvasEdges(adjacency) {
   return edges;
 }
 async function runCanvasGenerate(input) {
-  const graphPath = input.graphPath ?? join41(input.vault, ".skillwiki", "graph.json");
-  if (!existsSync17(graphPath)) {
+  const graphPath = input.graphPath ?? join42(input.vault, ".skillwiki", "graph.json");
+  if (!existsSync18(graphPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("FILE_NOT_FOUND", {
@@ -8422,7 +8873,7 @@ async function runCanvasGenerate(input) {
   const nodes = buildCanvasNodes(paths);
   const edges = buildCanvasEdges(graph.adjacency);
   const canvas = { nodes, edges };
-  const outPath = join41(input.vault, "vault-graph.canvas");
+  const outPath = join42(input.vault, "vault-graph.canvas");
   try {
     await writeFile16(outPath, JSON.stringify(canvas, null, 2));
   } catch (e) {
@@ -8445,7 +8896,7 @@ written: ${outPath}`
 
 // src/commands/query.ts
 import { readFile as readFile27, stat as stat9 } from "fs/promises";
-import { join as join42 } from "path";
+import { join as join43 } from "path";
 var W_KEYWORD = 2;
 var W_SOURCE_OVERLAP = 4;
 var W_WIKILINK = 3;
@@ -8566,7 +9017,7 @@ function computeKeywordScore(terms, title, tags, body) {
   return score;
 }
 async function loadOrBuildGraph(vault) {
-  const graphPath = join42(vault, ".skillwiki", "graph.json");
+  const graphPath = join43(vault, ".skillwiki", "graph.json");
   let needsBuild = false;
   try {
     const fileStat = await stat9(graphPath);
@@ -8588,14 +9039,14 @@ async function loadOrBuildGraph(vault) {
 }
 
 // src/utils/auto-commit.ts
-import { existsSync as existsSync18 } from "fs";
-import { join as join43 } from "path";
+import { existsSync as existsSync19 } from "fs";
+import { join as join44 } 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 (!existsSync18(join43(vault, ".git"))) return;
+  if (!existsSync19(join44(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain"]);
@@ -8624,14 +9075,14 @@ async function postCommit(vault, exitCode) {
 }
 
 // src/cli.ts
-var pkg = JSON.parse(readFileSync12(new URL("../package.json", import.meta.url), "utf8"));
+var pkg = readCliPackageJson();
 var program = new Command2();
 program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
-async function emit(r, vault) {
+async function emit(r, vault, opts) {
   if (program.opts().human) printHuman(r.result);
   else printJson(r.result);
-  if (vault) await postCommit(vault, r.exitCode);
+  if (vault && opts?.postCommit !== false) await postCommit(vault, r.exitCode);
   process.exit(r.exitCode);
 }
 program.command("hash <file>").description("compute SHA-256 hash of a vault page body").action(async (file) => emit(await runHash({ file })));
@@ -8646,7 +9097,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 ?? join44(vault, ".skillwiki", "graph.json");
+  const out = opts.out ?? join45(vault, ".skillwiki", "graph.json");
   emit(await runGraphBuild({ vault, out }), vault);
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
@@ -8777,9 +9228,20 @@ program.command("log-append [vault]").description("append a single entry to the
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runLogAppend({ vault: v.vault, content: opts.content }), 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 supported lint violations").option("--only <bucket>", "run only the specified lint bucket").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 supported lint violations").option("--only <bucket>", "run only the specified lint bucket").option("--summary", "emit bounded bucket counts instead of full item arrays", false).option("--examples <n>", "example count per bucket in summary mode", (s) => parseInt(s, 10), 3).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else if (opts.summary) emit(await runLint({
+    vault: v.vault,
+    source: vault ? "flag" : void 0,
+    days: opts.days,
+    lines: opts.lines,
+    logThreshold: opts.logThreshold,
+    fix: opts.fix ?? false,
+    only: opts.only,
+    summary: true,
+    examplesLimit: opts.examples
+  }), v.vault);
   else emit(await runLint({
     vault: v.vault,
     source: vault ? "flag" : void 0,
@@ -8790,6 +9252,27 @@ program.command("lint [vault]").description("run all vault health checks").optio
     only: opts.only
   }), v.vault);
 });
+program.command("health [vault]").description("bounded whole-system wiki health report").option("--wiki <name>", "wiki profile name").option("--sync <mode>", "vault-sync policy: optional|required|off", "optional").option("--no-fail", "always exit 0 while reporting status in JSON").option("--out <path>", "write JSON result envelope to this path").option("--examples <n>", "example count per lint bucket", (s) => parseInt(s, 10), 3).action(async (vault, opts) => {
+  const sync = String(opts.sync ?? "optional");
+  if (!["optional", "required", "off"].includes(sync)) {
+    emit({ exitCode: ExitCode.USAGE, result: { ok: false, error: "USAGE", detail: "--sync must be optional, required, or off" } });
+  }
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runHealth({
+    vault: v.vault,
+    vaultSource: vault ? "flag" : "resolved",
+    home: process.env.HOME ?? "",
+    envValue: process.env.WIKI_PATH,
+    argv: process.argv,
+    currentVersion: pkg.version,
+    cwd: process.cwd(),
+    sync,
+    noFail: opts.fail === false,
+    out: opts.out,
+    examplesLimit: opts.examples
+  }), void 0, { postCommit: false });
+});
 var configCmd = program.command("config").description("manage skillwiki configuration");
 configCmd.command("get <key>").description("print the value of a config key").action(async (key) => emit(await runConfigGet({ key, home: process.env.HOME ?? "" })));
 configCmd.command("set <key> <value>").description("set a config key value").action(async (key, value) => emit(await runConfigSet({ key, value, home: process.env.HOME ?? "" })));