skillwiki 0.2.1-beta.16 → 0.2.1-beta.21

package/dist/cli.js

@@ -2,43 +2,20 @@
 import {
   semverGt
 } from "./chunk-XM5IYZX7.js";
+import {
+  git,
+  gitStrict
+} from "./chunk-TPS5XD2J.js";
 
 // src/cli.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
+import { join as join37 } from "path";
 import { Command } from "commander";
 
-// src/utils/output.ts
-function printJson(r) {
-  process.stdout.write(JSON.stringify(r) + "\n");
-}
-function printHuman(r) {
-  if (r.ok) {
-    if (typeof r.data === "object" && r.data !== null && "humanHint" in r.data) {
-      process.stdout.write(`${r.data.humanHint}
-`);
-    } else {
-      process.stdout.write(`OK
-${formatData(r.data)}
-`);
-    }
-  } else {
-    process.stdout.write(`ERR ${r.error}
-${r.detail !== void 0 ? formatData(r.detail) + "\n" : ""}`);
-  }
-}
-function formatData(d) {
-  if (d == null) return "";
-  if (typeof d === "string") return d;
-  return JSON.stringify(d, null, 2);
-}
-
-// src/commands/hash.ts
-import { readFile } from "fs/promises";
-import { createHash } from "crypto";
-
 // ../shared/src/exit-codes.ts
 var ExitCode = {
   OK: 0,
+  INTERNAL_ERROR: 1,
   FILE_NOT_FOUND: 2,
   MISSING_CLOSING_DELIMITER: 3,
   SCHEME_REJECTED: 4,
@@ -74,7 +51,15 @@ var ExitCode = {
   MIGRATION_APPLIED: 34,
   UNKNOWN_WIKI_PROFILE: 35,
   DEDUP_APPLIED: 36,
-  PROJECT_NOT_FOUND: 37
+  PROJECT_NOT_FOUND: 37,
+  SYMLINK_FAILED: 38,
+  COMPOUND_PROMOTED: 39,
+  SKILL_VERSION_MISMATCH: 40,
+  INGEST_VALIDATION_FAILED: 41,
+  SYNC_PUSH_FAILED: 42,
+  SYNC_PULL_FAILED: 43,
+  BACKUP_SYNC_FAILED: 44,
+  BACKUP_RESTORE_CONFLICTS: 45
 };
 
 // ../shared/src/json-output.ts
@@ -98,7 +83,7 @@ var TypedKnowledgeSchema = z.object({
   aliases: z.array(z.string()).optional(),
   created: isoDate,
   updated: isoDate,
-  type: z.enum(["entity", "concept", "comparison", "query", "summary"]),
+  type: z.enum(["entity", "concept", "comparison", "query"]),
   tags: z.array(z.string()),
   sources: z.array(z.string()).min(1),
   confidence: z.enum(["high", "medium", "low"]).optional(),
@@ -118,7 +103,7 @@ var RawSourceSchema = z.object({
   source_url: z.string().nullable(),
   ingested: isoDate,
   ingested_by: z.enum(["wiki-ingest", "proj-work", "manual"]).optional(),
-  sha256: sha256Hex,
+  sha256: sha256Hex.optional(),
   project: wikilink.optional(),
   work_item: wikilink.optional(),
   kind: z.enum(["postmortem", "session-log", "meeting-notes", "other", "idea", "bug", "task", "note"]).optional()
@@ -181,7 +166,9 @@ function detectSchema(fm) {
   if (typeof fm.type === "string" && COMPOUND_TYPES.has(fm.type) && "project" in fm) return { schema: "compound" };
   if (fm.type === "meta") return { schema: "meta" };
   if ("type" in fm && "sources" in fm) return { schema: "typed-knowledge" };
-  if (typeof fm.sha256 === "string" && "ingested" in fm) return { schema: "raw" };
+  if ("ingested" in fm && ("source_url" in fm || "sha256" in fm)) return { schema: "raw" };
+  const RAW_KINDS = /* @__PURE__ */ new Set(["postmortem", "session-log", "meeting-notes", "other", "idea", "bug", "task", "note"]);
+  if ("ingested" in fm && typeof fm.kind === "string" && RAW_KINDS.has(fm.kind)) return { schema: "raw" };
   if ("kind" in fm && "status" in fm) return { schema: "work-item" };
   return { schema: null };
 }
@@ -225,6 +212,56 @@ function isBlockedHost(host) {
   return false;
 }
 
+// src/utils/output.ts
+function printJson(r) {
+  process.stdout.write(JSON.stringify(r) + "\n");
+}
+function printHuman(r) {
+  if (r.ok) {
+    if (typeof r.data === "object" && r.data !== null && "humanHint" in r.data) {
+      process.stdout.write(`${r.data.humanHint}
+`);
+    } else {
+      process.stdout.write(`OK
+${formatData(r.data)}
+`);
+    }
+  } else {
+    process.stdout.write(`ERR ${r.error}
+${r.detail !== void 0 ? formatData(r.detail) + "\n" : ""}`);
+  }
+}
+function formatData(d) {
+  if (d == null) return "";
+  if (typeof d === "string") return d;
+  return JSON.stringify(d, null, 2);
+}
+
+// src/utils/deprecation.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+function getDeprecatedWarnings(home) {
+  const manifestPath = join(home, ".claude", "skills", "wiki-manifest.json");
+  try {
+    const raw = readFileSync(manifestPath, "utf8");
+    const manifest = JSON.parse(raw);
+    if (!manifest.skills) return [];
+    const warnings = [];
+    for (const [dirName, meta] of Object.entries(manifest.skills)) {
+      if (meta.deprecated) {
+        warnings.push(`\u26A0 Skill "${meta.name || dirName}" is deprecated. See SKILL.md for migration notes.`);
+      }
+    }
+    return warnings;
+  } catch {
+    return [];
+  }
+}
+
+// src/commands/hash.ts
+import { readFile } from "fs/promises";
+import { createHash } from "crypto";
+
 // src/parsers/frontmatter.ts
 import yaml from "js-yaml";
 var FM_OPEN = /^---\r?\n/;
@@ -313,7 +350,16 @@ function sanitizeUrl(u) {
 }
 
 // src/commands/validate.ts
-import { readFile as readFile2 } from "fs/promises";
+import { readFile as readFile2, writeFile } from "fs/promises";
+import { join as join2, resolve, relative, sep } from "path";
+var TYPE_TO_SECTION = {
+  entity: "Entities",
+  concept: "Concepts",
+  comparison: "Comparisons",
+  query: "Queries",
+  summary: "Summaries",
+  meta: "Meta"
+};
 var SCHEMAS = {
   "typed-knowledge": TypedKnowledgeSchema,
   "raw": RawSourceSchema,
@@ -337,36 +383,120 @@ async function runValidate(input) {
   }
   const det = detectSchema(fm.data);
   if (!det.schema) {
-    return { exitCode: ExitCode.SCHEMA_NOT_DETECTED, result: ok({ schema: null, valid: false, errors: [], humanHint: "schema not detected" }) };
+    return { exitCode: ExitCode.SCHEMA_NOT_DETECTED, result: ok({ schema: null, valid: false, errors: [], index_updated: false, log_updated: false, humanHint: "schema not detected" }) };
   }
   const parsed = SCHEMAS[det.schema].safeParse(fm.data);
   if (!parsed.success) {
     const errors = parsed.error.issues.map((i) => ({ path: i.path.join("."), message: i.message }));
     return {
       exitCode: ExitCode.INVALID_FRONTMATTER,
-      result: ok({ schema: det.schema, valid: false, errors, humanHint: `INVALID (${det.schema})
+      result: ok({ schema: det.schema, valid: false, errors, index_updated: false, log_updated: false, humanHint: `INVALID (${det.schema})
 ${errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}` })
     };
   }
-  return { exitCode: ExitCode.OK, result: ok({ schema: det.schema, valid: true, errors: [], humanHint: `VALID (${det.schema})` }) };
+  if (input.apply && !input.vault) {
+    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { reason: "--vault is required when --apply is set" }) };
+  }
+  let indexUpdated = false;
+  let logUpdated = false;
+  let applyHint = "";
+  if (input.apply && input.vault) {
+    const absFile = resolve(input.file);
+    const absVault = resolve(input.vault);
+    const relPath = relative(absVault, absFile).split(sep).join("/");
+    if (relPath.startsWith("..")) {
+      return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { reason: `file ${input.file} is not inside vault ${input.vault}` }) };
+    }
+    const pageType = "type" in parsed.data && typeof parsed.data.type === "string" ? parsed.data.type : "";
+    const title = typeof parsed.data.title === "string" ? parsed.data.title : relPath.replace(/\.md$/, "");
+    if (det.schema === "typed-knowledge" || det.schema === "meta") {
+      indexUpdated = await addToIndex(input.vault, relPath, title, pageType);
+    }
+    logUpdated = await appendToLog(input.vault, relPath);
+    if (indexUpdated) applyHint += `
+  index: added [[${relPath.replace(/\.md$/, "")}]]`;
+    if (logUpdated) applyHint += "\n  log: appended entry";
+  }
+  return { exitCode: ExitCode.OK, result: ok({
+    schema: det.schema,
+    valid: true,
+    errors: [],
+    index_updated: indexUpdated,
+    log_updated: logUpdated,
+    humanHint: `VALID (${det.schema})${applyHint}`
+  }) };
+}
+async function addToIndex(vault, relPath, title, pageType) {
+  const section = TYPE_TO_SECTION[pageType];
+  if (!section) return false;
+  const indexPath = join2(vault, "index.md");
+  let text;
+  try {
+    text = await readFile2(indexPath, "utf8");
+  } catch {
+    return false;
+  }
+  const ref = relPath.replace(/\.md$/, "");
+  if (text.includes(`[[${ref}]]`)) return false;
+  const entry = `- [[${ref}]] \u2014 ${title}`;
+  const lines = text.split("\n");
+  const sectionLine = `## ${section}`;
+  const sectionIdx = lines.findIndex((l) => l.trim() === sectionLine);
+  if (sectionIdx === -1) {
+    while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
+    lines.push("", sectionLine, entry);
+  } else {
+    let endIdx = sectionIdx + 1;
+    while (endIdx < lines.length) {
+      if (lines[endIdx].startsWith("## ")) break;
+      endIdx++;
+    }
+    let insertAt = endIdx;
+    while (insertAt > sectionIdx + 1 && lines[insertAt - 1].trim() === "") insertAt--;
+    lines.splice(insertAt, 0, entry);
+  }
+  try {
+    await writeFile(indexPath, lines.join("\n"), "utf8");
+  } catch {
+    return false;
+  }
+  return true;
+}
+async function appendToLog(vault, relPath) {
+  const logPath = join2(vault, "log.md");
+  let text;
+  try {
+    text = await readFile2(logPath, "utf8");
+  } catch {
+    return false;
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const entry = `
+## [${today}] validate | added: ${relPath}`;
+  try {
+    await writeFile(logPath, text.trimEnd() + entry, "utf8");
+  } catch {
+    return false;
+  }
+  return true;
 }
 
 // src/commands/graph.ts
-import { writeFile, mkdir } from "fs/promises";
+import { writeFile as writeFile2, mkdir } from "fs/promises";
 import { dirname } from "path";
 
 // src/utils/vault.ts
 import { readFile as readFile3, readdir, stat } from "fs/promises";
-import { join, relative, sep } from "path";
+import { join as join3, relative as relative2, sep as sep2 } from "path";
 var TYPED_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
 async function scanVault(root) {
   try {
-    await stat(join(root, "SCHEMA.md"));
+    await stat(join3(root, "SCHEMA.md"));
   } catch {
     return err("VAULT_PATH_INVALID", { root, reason: "SCHEMA.md missing" });
   }
   const all = await walk(root);
-  const rels = all.map((p) => ({ absPath: p, relPath: relative(root, p).split(sep).join("/") }));
+  const rels = all.map((p) => ({ absPath: p, relPath: relative2(root, p).split(sep2).join("/") }));
   return ok({
     root,
     typedKnowledge: rels.filter((p) => TYPED_DIRS.some((d) => p.relPath.startsWith(d + "/"))),
@@ -379,7 +509,7 @@ async function walk(dir) {
   const entries = await readdir(dir, { withFileTypes: true });
   const out = [];
   for (const e of entries) {
-    const p = join(dir, e.name);
+    const p = join3(dir, e.name);
     if (e.isDirectory()) out.push(...await walk(p));
     else if (e.isFile() && e.name.endsWith(".md")) out.push(p);
   }
@@ -390,7 +520,7 @@ async function readPage(p) {
 }
 
 // src/parsers/wikilinks.ts
-var FENCE = /`[^`]*`|```[\s\S]*?```/g;
+var FENCE = /```[\s\S]*?```|`[^`\n]*`/g;
 function extractBodyWikilinks(body) {
   const stripped = body.replace(FENCE, "");
   const seen = /* @__PURE__ */ new Set();
@@ -428,7 +558,7 @@ async function runGraphBuild(input) {
   const edge_count = Object.values(adjacency).reduce((acc, arr) => acc + arr.length, 0);
   try {
     await mkdir(dirname(input.out), { recursive: true });
-    await writeFile(input.out, JSON.stringify({ adjacency, adamicAdar }, null, 2));
+    await writeFile2(input.out, JSON.stringify({ adjacency, adamicAdar }, null, 2));
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
   }
@@ -515,12 +645,21 @@ async function runOverlap(input) {
 }
 
 // src/utils/wiki-path.ts
-import { join as join2 } from "path";
+import { join as join4 } from "path";
 
 // src/utils/dotenv.ts
-import { readFile as readFile4, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
+import { readFile as readFile4, writeFile as writeFile3, mkdir as mkdir2 } from "fs/promises";
 import { dirname as dirname2 } from "path";
-var CONFIG_KEYS = ["WIKI_PATH", "WIKI_LANG"];
+var CONFIG_KEYS = [
+  "WIKI_PATH",
+  "WIKI_LANG",
+  "AUTO_COMMIT",
+  "BACKUP_ENDPOINT",
+  "BACKUP_BUCKET",
+  "BACKUP_REGION",
+  "BACKUP_ACCESS_KEY_ID",
+  "BACKUP_SECRET_ACCESS_KEY"
+];
 var _whitelist = new Set(CONFIG_KEYS);
 var PROFILE_PATH_RE = /^WIKI_([A-Z][A-Z0-9_]{0,31})_PATH$/;
 var PROFILE_LANG_RE = /^WIKI_([A-Z][A-Z0-9_]{0,31})_LANG$/;
@@ -559,7 +698,7 @@ async function parseDotenvFile(path) {
 async function writeDotenv(filePath, entries, originalContent) {
   const lines = originalContent !== void 0 ? updateLines(originalContent, entries) : freshLines(entries);
   await mkdir2(dirname2(filePath), { recursive: true });
-  await writeFile2(filePath, lines.join("\n") + "\n", "utf8");
+  await writeFile3(filePath, lines.join("\n") + "\n", "utf8");
 }
 function freshLines(entries) {
   const out = [];
@@ -614,27 +753,27 @@ async function resolveInitTimePath(input) {
     return { path: input.envValue, source: "env", ...input.explain ? { chain } : {} };
   }
   if (input.explain) chain.push({ source: "env", matched: false });
-  const sw = await parseDotenvFile(join2(input.home, ".skillwiki", ".env"));
+  const sw = await parseDotenvFile(join4(input.home, ".skillwiki", ".env"));
   if (sw.WIKI_PATH !== void 0) {
     if (input.explain) chain.push({ source: "skillwiki-dotenv", matched: true, value: sw.WIKI_PATH });
     return { path: sw.WIKI_PATH, source: "skillwiki-dotenv", ...input.explain ? { chain } : {} };
   }
   if (input.explain) chain.push({ source: "skillwiki-dotenv", matched: false });
-  const hermes = await parseDotenvFile(join2(input.home, ".hermes", ".env"));
+  const hermes = await parseDotenvFile(join4(input.home, ".hermes", ".env"));
   if (hermes.WIKI_PATH !== void 0) {
     if (input.explain) chain.push({ source: "hermes-dotenv", matched: true, value: hermes.WIKI_PATH });
     return { path: hermes.WIKI_PATH, source: "hermes-dotenv", ...input.explain ? { chain } : {} };
   }
   if (input.explain) chain.push({ source: "hermes-dotenv", matched: false });
   if (input.cwd) {
-    const projCfg = await parseDotenvFile(join2(input.cwd, ".skillwiki", ".env"));
+    const projCfg = await parseDotenvFile(join4(input.cwd, ".skillwiki", ".env"));
     if (projCfg.WIKI_PATH !== void 0) {
       if (input.explain) chain.push({ source: "project-dotenv", matched: true, value: projCfg.WIKI_PATH });
       return { path: projCfg.WIKI_PATH, source: "project-dotenv", ...input.explain ? { chain } : {} };
     }
   }
   if (input.explain) chain.push({ source: "project-dotenv", matched: false });
-  const fallback = join2(input.home, "wiki");
+  const fallback = join4(input.home, "wiki");
   if (input.explain) chain.push({ source: "default", matched: true, value: fallback });
   return { path: fallback, source: "default", ...input.explain ? { chain } : {} };
 }
@@ -645,7 +784,7 @@ async function resolveRuntimePath(input) {
     return ok({ path: input.flag, source: "flag", ...input.explain ? { chain } : {} });
   }
   if (input.explain) chain.push({ source: "flag", matched: false });
-  const swGlobal = await parseDotenvFile(join2(input.home, ".skillwiki", ".env"));
+  const swGlobal = await parseDotenvFile(join4(input.home, ".skillwiki", ".env"));
   const wikiName = input.wiki;
   if (wikiName !== void 0 && wikiName.length > 0) {
     if (wikiName.toLowerCase() === "default") {
@@ -689,7 +828,7 @@ async function resolveRuntimePath(input) {
   }
   if (input.explain) chain.push({ source: "env", matched: false });
   if (input.cwd) {
-    const projCfg = await parseDotenvFile(join2(input.cwd, ".skillwiki", ".env"));
+    const projCfg = await parseDotenvFile(join4(input.cwd, ".skillwiki", ".env"));
     if (projCfg.WIKI_PATH !== void 0) {
       if (input.explain) chain.push({ source: "project-dotenv", matched: true, value: projCfg.WIKI_PATH });
       return ok({ path: projCfg.WIKI_PATH, source: "project-dotenv", ...input.explain ? { chain } : {} });
@@ -804,7 +943,7 @@ function simulateRemoval(adj, removed) {
 
 // src/commands/audit.ts
 import { readFile as readFile5, stat as stat2 } from "fs/promises";
-import { dirname as dirname3, resolve, join as join3 } from "path";
+import { dirname as dirname3, resolve as resolve2, join as join5 } from "path";
 
 // src/parsers/citations.ts
 var FENCE2 = /```[\s\S]*?```/g;
@@ -911,12 +1050,12 @@ async function runAudit(input) {
   if (!fm.ok) return { exitCode: ExitCode.INVALID_FRONTMATTER, result: fm };
   const split = splitFrontmatter(text);
   const body = split.ok ? split.data.body : text;
-  const vault = await findVaultRoot(dirname3(resolve(input.file)));
+  const vault = await findVaultRoot(dirname3(resolve2(input.file)));
   if (!vault) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID") };
   const markers = extractCitationMarkers(body);
   const resolved = await Promise.all(markers.map(async (m) => {
     try {
-      await stat2(join3(vault, m.target));
+      await stat2(join5(vault, m.target));
       return { ...m, resolved: true };
     } catch {
       return { ...m, resolved: false };
@@ -927,7 +1066,7 @@ async function runAudit(input) {
   const unused_sources = sources.filter((s) => !referenced.has(s));
   const missing_from_sources = [...referenced].filter((t) => !sources.includes(t));
   const broken = resolved.filter((m) => !m.resolved);
-  const footerMatch = body.match(/\n## Sources\n([\s\S]*)$/);
+  const footerMatch = body.match(/\r?\n## Sources\r?\n([\s\S]*)$/);
   let footer_consistency;
   if (footerMatch) {
     const footerTargets = /* @__PURE__ */ new Set();
@@ -961,7 +1100,7 @@ async function findVaultRoot(start) {
   let cur = start;
   for (let i = 0; i < 20; i++) {
     try {
-      await stat2(join3(cur, "SCHEMA.md"));
+      await stat2(join5(cur, "SCHEMA.md"));
       return cur;
     } catch {
     }
@@ -971,13 +1110,53 @@ async function findVaultRoot(start) {
   }
   return null;
 }
+function stripWikilink(s) {
+  return s.replace(/^\[\[/, "").replace(/(?:\|[^\[\]]*)?\]\]$/, "").trim();
+}
+async function validateCompoundReferences(vault) {
+  const scan = await scanVault(vault);
+  if (!scan.ok) return scan;
+  const slugToPage = /* @__PURE__ */ new Map();
+  const pathToPage = /* @__PURE__ */ new Map();
+  for (const p of scan.data.workItems) {
+    slugToPage.set(p.relPath.replace(/\.md$/, "").split("/").pop().toLowerCase(), p);
+    pathToPage.set(p.relPath, p);
+  }
+  const findings = [];
+  for (const cp of scan.data.compound) {
+    const text = await readPage(cp);
+    const fm = extractFrontmatter(text);
+    if (!fm.ok) continue;
+    const projectRaw = fm.data.project;
+    const workItems = fm.data.work_items;
+    if (!projectRaw || !workItems?.length) continue;
+    const projSlug = stripWikilink(String(projectRaw));
+    for (const wi of workItems) {
+      const target = stripWikilink(wi);
+      const withExt = target.endsWith(".md") ? target : target + ".md";
+      const resolved = pathToPage.get(withExt) ?? slugToPage.get(target.split("/").pop().replace(/\.md$/, "").toLowerCase());
+      if (!resolved) {
+        findings.push({ compound: cp.relPath, work_item: wi, kind: "missing", detail: `no work item found for [[${target}]]` });
+        continue;
+      }
+      const wiFm = extractFrontmatter(await readPage(resolved));
+      if (wiFm.ok && wiFm.data.project) {
+        const wiProj = stripWikilink(String(wiFm.data.project));
+        if (wiProj !== projSlug) {
+          findings.push({ compound: cp.relPath, work_item: wi, kind: "cross_project", detail: `compound project [[${projSlug}]] != work_item project [[${wiProj}]]` });
+        }
+      }
+    }
+  }
+  return ok(findings);
+}
 
 // src/commands/install.ts
-import { readdir as readdir2, stat as stat4 } from "fs/promises";
-import { join as join4 } from "path";
+import { readdir as readdir2, stat as stat4, symlink, unlink, mkdir as mkdir4, readFile as readFile6 } from "fs/promises";
+import { join as join6, resolve as resolve3, dirname as dirname5 } from "path";
 
 // src/utils/install-fs.ts
-import { copyFile, mkdir as mkdir3, rename, writeFile as writeFile3, stat as stat3 } from "fs/promises";
+import { copyFile, mkdir as mkdir3, rename, writeFile as writeFile4, stat as stat3 } from "fs/promises";
 import { dirname as dirname4 } from "path";
 async function atomicCopyWithBackup(src, dst) {
   await mkdir3(dirname4(dst), { recursive: true });
@@ -1000,10 +1179,36 @@ async function atomicCopyWithBackup(src, dst) {
 async function writeManifest(path, m) {
   await mkdir3(dirname4(path), { recursive: true });
   const enriched = { installed_at: (/* @__PURE__ */ new Date()).toISOString(), ...m };
-  await writeFile3(path, JSON.stringify(enriched, null, 2));
+  await writeFile4(path, JSON.stringify(enriched, null, 2));
 }
 
 // src/commands/install.ts
+function parseSkillMeta(content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  const meta = { name: "" };
+  if (!fmMatch) return meta;
+  const fm = fmMatch[1];
+  const nameMatch = fm.match(/^name:\s*(.+)$/m);
+  if (nameMatch) meta.name = nameMatch[1].trim();
+  const versionMatch = fm.match(/^version:\s*(.+)$/m);
+  if (versionMatch) meta.version = versionMatch[1].trim();
+  const depMatch = fm.match(/^deprecated:\s*(.+)$/m);
+  if (depMatch && /^(true|yes)$/i.test(depMatch[1].trim())) meta.deprecated = true;
+  return meta;
+}
+async function createSymlink(src, dst) {
+  await mkdir4(dirname5(dst), { recursive: true });
+  try {
+    await unlink(dst);
+  } catch {
+  }
+  try {
+    await symlink(resolve3(src), dst);
+  } catch (e) {
+    return err("SYMLINK_FAILED", { message: String(e) });
+  }
+  return ok({ linked: true });
+}
 async function runInstall(input) {
   let entries;
   try {
@@ -1016,45 +1221,85 @@ async function runInstall(input) {
   }
   const installed = [];
   const backed_up = [];
+  const version_warnings = [];
+  const skillMetas = {};
   for (const name of entries) {
-    const src = join4(input.skillsRoot, name, "SKILL.md");
-    const dst = join4(input.target, name, "SKILL.md");
+    const src = join6(input.skillsRoot, name, "SKILL.md");
+    const dst = join6(input.target, name, "SKILL.md");
     try {
       await stat4(src);
     } catch {
       return { exitCode: ExitCode.PREFLIGHT_FAILED, result: err("PREFLIGHT_FAILED", { missing: src }) };
     }
+    try {
+      const content = await readFile6(src, "utf8");
+      const meta = parseSkillMeta(content);
+      meta.name = meta.name || name;
+      skillMetas[name] = meta;
+      if (meta.deprecated) {
+        version_warnings.push(`${name}: DEPRECATED \u2014 will be removed in a future release`);
+      }
+      if (!input.dryRun) {
+        try {
+          const existingContent = await readFile6(dst, "utf8");
+          const existingMeta = parseSkillMeta(existingContent);
+          if (existingMeta.version && meta.version && existingMeta.version !== meta.version) {
+            version_warnings.push(`${name}: version changed ${existingMeta.version} \u2192 ${meta.version}`);
+          }
+        } catch {
+        }
+      }
+    } catch {
+    }
     if (input.dryRun) {
       installed.push(dst);
       continue;
     }
-    const r = await atomicCopyWithBackup(src, dst);
-    if (!r.ok) return { exitCode: ExitCode.ATOMIC_COPY_FAILED, result: r };
-    installed.push(dst);
-    if (r.data.backupPath) backed_up.push(r.data.backupPath);
+    if (input.symlink) {
+      const r = await createSymlink(src, dst);
+      if (!r.ok) return { exitCode: ExitCode.SYMLINK_FAILED, result: r };
+      installed.push(dst);
+    } else {
+      const r = await atomicCopyWithBackup(src, dst);
+      if (!r.ok) return { exitCode: ExitCode.ATOMIC_COPY_FAILED, result: r };
+      installed.push(dst);
+      if (r.data.backupPath) backed_up.push(r.data.backupPath);
+    }
   }
-  const binSrc = join4(input.skillsRoot, "bin", "skillwiki");
+  const binSrc = join6(input.skillsRoot, "bin", "skillwiki");
   try {
     await stat4(binSrc);
-    const binDst = join4(input.target, "bin", "skillwiki");
+    const binDst = join6(input.target, "bin", "skillwiki");
     if (!input.dryRun) {
-      const r = await atomicCopyWithBackup(binSrc, binDst);
-      if (!r.ok) return { exitCode: ExitCode.ATOMIC_COPY_FAILED, result: r };
-      installed.push(binDst);
-      if (r.data.backupPath) backed_up.push(r.data.backupPath);
+      if (input.symlink) {
+        const r = await createSymlink(binSrc, binDst);
+        if (!r.ok) return { exitCode: ExitCode.SYMLINK_FAILED, result: r };
+        installed.push(binDst);
+      } else {
+        const r = await atomicCopyWithBackup(binSrc, binDst);
+        if (!r.ok) return { exitCode: ExitCode.ATOMIC_COPY_FAILED, result: r };
+        installed.push(binDst);
+        if (r.data.backupPath) backed_up.push(r.data.backupPath);
+      }
     } else {
       installed.push(binDst);
     }
   } catch {
   }
-  const manifest_path = join4(input.target, "wiki-manifest.json");
-  if (!input.dryRun) await writeManifest(manifest_path, { installed, backed_up });
+  const manifest_path = join6(input.target, "wiki-manifest.json");
+  if (!input.dryRun) await writeManifest(manifest_path, { installed, backed_up, symlink: input.symlink || void 0, skills: skillMetas });
+  const mode = input.symlink ? "symlink (dev mode)" : "copy";
   const hintLines = [
-    `installed: ${installed.length}`,
+    `installed: ${installed.length} (${mode})`,
     input.dryRun ? "(dry run)" : `backed up: ${backed_up.length}`,
     `manifest: ${manifest_path}`
   ];
-  return { exitCode: ExitCode.OK, result: ok({ installed, backed_up, manifest_path, humanHint: hintLines.join("\n") }) };
+  if (version_warnings.length > 0) {
+    hintLines.push(`version warnings: ${version_warnings.length}`);
+    for (const w of version_warnings) hintLines.push(`  ${w}`);
+  }
+  const exitCode = version_warnings.length > 0 ? ExitCode.SKILL_VERSION_MISMATCH : ExitCode.OK;
+  return { exitCode, result: ok({ installed, backed_up, manifest_path, version_warnings, humanHint: hintLines.join("\n") }) };
 }
 
 // src/commands/path.ts
@@ -1083,7 +1328,7 @@ async function runPath(input) {
 }
 
 // src/utils/lang.ts
-import { join as join5 } from "path";
+import { join as join7 } from "path";
 var ALIASES = {
   english: "en",
   en: "en",
@@ -1106,7 +1351,7 @@ async function resolveLang(input) {
   if (input.envValue !== void 0 && input.envValue.length > 0) {
     return { value: input.envValue, source: "env", canonical: normalizeLang(input.envValue) };
   }
-  const dotenv = await parseDotenvFile(join5(input.home, ".skillwiki", ".env"));
+  const dotenv = await parseDotenvFile(join7(input.home, ".skillwiki", ".env"));
   if (dotenv.WIKI_LANG !== void 0) {
     return { value: dotenv.WIKI_LANG, source: "skillwiki-dotenv", canonical: normalizeLang(dotenv.WIKI_LANG) };
   }
@@ -1114,7 +1359,7 @@ async function resolveLang(input) {
 }
 
 // src/commands/lang.ts
-import { join as join6 } from "path";
+import { join as join8 } from "path";
 async function runLang(input) {
   const resolved = await resolveLang({ flag: input.flag, envValue: input.envValue, home: input.home });
   let chain;
@@ -1123,7 +1368,7 @@ async function runLang(input) {
       { source: "flag", matched: input.flag !== void 0 && input.flag.length > 0, value: input.flag },
       { source: "env", matched: input.envValue !== void 0 && input.envValue.length > 0, value: input.envValue }
     ];
-    const sw = await parseDotenvFile(join6(input.home, ".skillwiki", ".env"));
+    const sw = await parseDotenvFile(join8(input.home, ".skillwiki", ".env"));
     chain.push({ source: "skillwiki-dotenv", matched: sw.WIKI_LANG !== void 0, value: sw.WIKI_LANG });
     chain.push({ source: "default", matched: resolved.source === "default", value: "en" });
   }
@@ -1140,8 +1385,8 @@ async function runLang(input) {
 }
 
 // src/commands/init.ts
-import { mkdir as mkdir4, readFile as readFile6, readdir as readdir3, writeFile as writeFile4 } from "fs/promises";
-import { join as join7 } from "path";
+import { mkdir as mkdir5, readFile as readFile7, readdir as readdir3, writeFile as writeFile5 } from "fs/promises";
+import { join as join10 } from "path";
 
 // src/parsers/taxonomy.ts
 import yaml2 from "js-yaml";
@@ -1168,6 +1413,48 @@ function extractTaxonomy(schemaText) {
   return ok(tax);
 }
 
+// src/utils/last-op.ts
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync, unlinkSync, existsSync } from "fs";
+import { join as join9 } from "path";
+var LAST_OP_DIR = ".skillwiki";
+var LAST_OP_FILE = "last-op.json";
+function lastOpPath(vault) {
+  return join9(vault, LAST_OP_DIR, LAST_OP_FILE);
+}
+function readLastOp(vault) {
+  const p = lastOpPath(vault);
+  if (!existsSync(p)) return [];
+  try {
+    const raw = readFileSync2(p, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      unlinkSync(p);
+      return [];
+    }
+    return parsed;
+  } catch {
+    try {
+      unlinkSync(p);
+    } catch {
+    }
+    return [];
+  }
+}
+function appendLastOp(vault, entry) {
+  const existing = readLastOp(vault);
+  existing.push(entry);
+  const dir = join9(vault, LAST_OP_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(lastOpPath(vault), JSON.stringify(existing, null, 2), "utf8");
+}
+function clearLastOp(vault) {
+  const p = lastOpPath(vault);
+  try {
+    unlinkSync(p);
+  } catch {
+  }
+}
+
 // src/commands/init.ts
 var DEFAULT_TAXONOMY = [
   "research",
@@ -1210,13 +1497,13 @@ async function discoverTagsFromPages(target, knownSlugs) {
   for (const dir of ["entities", "concepts", "comparisons", "queries"]) {
     let entries;
     try {
-      entries = (await readdir3(join7(target, dir), { withFileTypes: true })).filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name);
+      entries = (await readdir3(join10(target, dir), { withFileTypes: true })).filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name);
     } catch {
       continue;
     }
     for (const file of entries) {
       try {
-        const text = await readFile6(join7(target, dir, file), "utf8");
+        const text = await readFile7(join10(target, dir, file), "utf8");
         const fm = extractFrontmatter(text);
         if (!fm.ok || !fm.data.tags || !Array.isArray(fm.data.tags)) continue;
         for (const t of fm.data.tags) {
@@ -1235,7 +1522,7 @@ async function runInit(input) {
   const canonicalLang = langRes.canonical;
   let oldSchemaText;
   try {
-    oldSchemaText = await readFile6(join7(target, "SCHEMA.md"), "utf8");
+    oldSchemaText = await readFile7(join10(target, "SCHEMA.md"), "utf8");
   } catch {
   }
   if (oldSchemaText && !input.force) {
@@ -1244,10 +1531,10 @@ async function runInit(input) {
       result: err("INIT_TARGET_NOT_EMPTY", { target })
     };
   }
-  const envPath = join7(input.home, ".skillwiki", ".env");
+  const envPath = join10(input.home, ".skillwiki", ".env");
   let existingEnvRaw = "";
   try {
-    existingEnvRaw = await readFile6(envPath, "utf8");
+    existingEnvRaw = await readFile7(envPath, "utf8");
   } catch {
   }
   const existingEnv = parseDotenvText(existingEnvRaw);
@@ -1268,9 +1555,9 @@ async function runInit(input) {
   }
   const created = [];
   try {
-    await mkdir4(target, { recursive: true });
+    await mkdir5(target, { recursive: true });
     for (const d of VAULT_DIRS) {
-      await mkdir4(join7(target, d), { recursive: true });
+      await mkdir5(join10(target, d), { recursive: true });
       created.push(d + "/");
     }
   } catch (e) {
@@ -1299,9 +1586,9 @@ async function runInit(input) {
   const discovered_tags = discovered.length;
   const fullTaxonomyYaml = discovered.length > 0 ? taxonomy.map((t) => `  - ${t}`).join("\n") + "\n  # --- Discovered from existing pages ---\n" + discovered.map((t) => `  - ${t}`).join("\n") : taxonomy.map((t) => `  - ${t}`).join("\n");
   try {
-    const schemaTpl = await readFile6(join7(input.templates, "SCHEMA.md"), "utf8");
+    const schemaTpl = await readFile7(join10(input.templates, "SCHEMA.md"), "utf8");
     const schema = schemaTpl.replace("{{DOMAIN}}", domain).replace("{{WIKI_LANG}}", canonicalLang).replace("{{TAXONOMY_YAML}}", fullTaxonomyYaml);
-    await writeFile4(join7(target, "SCHEMA.md"), schema, "utf8");
+    await writeFile5(join10(target, "SCHEMA.md"), schema, "utf8");
     created.push("SCHEMA.md");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "SCHEMA.md", message: String(e) }) };
@@ -1309,7 +1596,7 @@ async function runInit(input) {
   const preserved = [];
   async function writeOrPreserve(fileName, render) {
     try {
-      const existing = await readFile6(join7(target, fileName), "utf8");
+      const existing = await readFile7(join10(target, fileName), "utf8");
       if (existing.split("\n").length > 10) {
         preserved.push(fileName);
         return void 0;
@@ -1317,7 +1604,7 @@ async function runInit(input) {
     } catch {
     }
     try {
-      await writeFile4(join7(target, fileName), await render(), "utf8");
+      await writeFile5(join10(target, fileName), await render(), "utf8");
       created.push(fileName);
       return void 0;
     } catch (e) {
@@ -1325,7 +1612,7 @@ async function runInit(input) {
     }
   }
   const err1 = await writeOrPreserve("index.md", async () => {
-    const tpl = await readFile6(join7(input.templates, "index.md"), "utf8");
+    const tpl = await readFile7(join10(input.templates, "index.md"), "utf8");
     return tpl.replace("{{INIT_DATE}}", today);
   });
   if (err1) return err1;
@@ -1342,7 +1629,6 @@ async function runInit(input) {
       "---",
       "source_url:",
       "ingested: {{date:YYYY-MM-DD}}",
-      "sha256:          # run: skillwiki hash <this-file>",
       "kind:             # idea | bug | task | note | other",
       'project:          # optional: "[[slug]]"',
       "---",
@@ -1352,7 +1638,7 @@ async function runInit(input) {
   });
   if (errTemplate) return errTemplate;
   const err22 = await writeOrPreserve("log.md", async () => {
-    const tpl = await readFile6(join7(input.templates, "log.md"), "utf8");
+    const tpl = await readFile7(join10(input.templates, "log.md"), "utf8");
     return tpl.replace(/\{\{INIT_DATE\}\}/g, today).replace("{{DOMAIN}}", domain).replace("{{WIKI_LANG}}", canonicalLang);
   });
   if (err22) return err22;
@@ -1384,6 +1670,14 @@ async function runInit(input) {
     `discovered tags: ${discovered_tags}`,
     skipEnv ? "env: skipped" : `env: ${envWritten}`
   ].join("\n");
+  if (created.length > 0) {
+    appendLastOp(target, {
+      operation: "init",
+      summary: `initialized vault: ${domain}`,
+      files: created,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   return {
     exitCode: ExitCode.OK,
     result: ok({
@@ -1441,12 +1735,12 @@ ${broken.map((b) => `  ${b.page}:[[${b.slug}]] (line ${b.line})`).join("\n")}` }
 }
 
 // src/commands/tag-audit.ts
-import { readFile as readFile7 } from "fs/promises";
-import { join as join8 } from "path";
+import { readFile as readFile8 } from "fs/promises";
+import { join as join11 } from "path";
 async function runTagAudit(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const schemaText = await readFile7(join8(input.vault, "SCHEMA.md"), "utf8");
+  const schemaText = await readFile8(join11(input.vault, "SCHEMA.md"), "utf8");
   const tax = extractTaxonomy(schemaText);
   if (!tax.ok) return { exitCode: ExitCode.INVALID_FRONTMATTER, result: tax };
   const allowed = new Set(tax.data);
@@ -1470,14 +1764,14 @@ async function runTagAudit(input) {
 }
 
 // src/commands/index-check.ts
-import { readFile as readFile8 } from "fs/promises";
-import { join as join9 } from "path";
+import { readFile as readFile9 } from "fs/promises";
+import { join as join12 } from "path";
 async function runIndexCheck(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
   let indexText = "";
   try {
-    indexText = await readFile8(join9(input.vault, "index.md"), "utf8");
+    indexText = await readFile9(join12(input.vault, "index.md"), "utf8");
   } catch {
   }
   const indexSlugsLower = /* @__PURE__ */ new Map();
@@ -1486,12 +1780,18 @@ async function runIndexCheck(input) {
     indexSlugsLower.set(tail.toLowerCase(), tail);
   }
   const fileSlugs = /* @__PURE__ */ new Map();
+  const requiredSlugs = /* @__PURE__ */ new Map();
   for (const p of scan.data.typedKnowledge) {
     const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
     fileSlugs.set(slug, p.relPath);
+    requiredSlugs.set(slug, p.relPath);
+  }
+  for (const p of scan.data.compound) {
+    const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
+    fileSlugs.set(slug, p.relPath);
   }
   const missing_from_index = [];
-  for (const [slug, relPath] of fileSlugs.entries()) {
+  for (const [slug, relPath] of requiredSlugs.entries()) {
     if (!indexSlugsLower.has(slug.toLowerCase())) missing_from_index.push(relPath);
   }
   const fileSlugsLower = new Set([...fileSlugs.keys()].map((s) => s.toLowerCase()));
@@ -1510,44 +1810,176 @@ async function runIndexCheck(input) {
 }
 
 // src/commands/stale.ts
-import { readFile as readFile9 } from "fs/promises";
-import { join as join10 } from "path";
-function dayDiff(a, b) {
-  const da = Date.parse(a);
-  const db = Date.parse(b);
-  return Math.round((db - da) / 864e5);
+import { readdir as readdir4, rename as rename2, mkdir as mkdir6, readFile as readFile10 } from "fs/promises";
+import { join as join13 } from "path";
+function daysSince(isoDate2) {
+  return Math.floor((Date.now() - Date.parse(isoDate2)) / 864e5);
 }
 async function runStale(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const stale = [];
-  for (const p of scan.data.typedKnowledge) {
-    const fm = extractFrontmatter(await readPage(p));
-    if (!fm.ok) continue;
-    const updated = typeof fm.data.updated === "string" ? fm.data.updated : void 0;
-    const sources = Array.isArray(fm.data.sources) ? fm.data.sources.filter((s) => typeof s === "string") : [];
-    if (!updated || sources.length === 0) continue;
-    let newest;
-    for (const rel of sources) {
-      let raw;
+  const staleTranscripts = [];
+  const incompleteWorkItems = [];
+  const archived = [];
+  const workDirs = /* @__PURE__ */ new Map();
+  const projectsDir = join13(input.vault, "projects");
+  let projectSlugs = [];
+  try {
+    projectSlugs = (await readdir4(projectsDir, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch {
+  }
+  for (const slug of projectSlugs) {
+    const workPath = join13(projectsDir, slug, "work");
+    let entries;
+    try {
+      entries = await readdir4(workPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const relDir = `projects/${slug}/work/${e.name}`;
+      const absDir = join13(workPath, e.name);
+      let status = "";
+      let files;
       try {
-        raw = await readFile9(join10(input.vault, rel), "utf8");
+        files = await readdir4(absDir);
       } catch {
+        workDirs.set(relDir, "");
         continue;
       }
-      const rfm = extractFrontmatter(raw);
-      if (!rfm.ok) continue;
-      const ing = typeof rfm.data.ingested === "string" ? rfm.data.ingested : void 0;
-      if (ing && (!newest || Date.parse(ing) > Date.parse(newest))) newest = ing;
+      for (const f of files) {
+        if (!f.endsWith(".md")) continue;
+        try {
+          const fm = extractFrontmatter(await readFile10(join13(absDir, f), "utf8"));
+          if (fm.ok && typeof fm.data.status === "string") {
+            status = fm.data.status;
+            break;
+          }
+        } catch {
+        }
+      }
+      workDirs.set(relDir, status);
+    }
+  }
+  const transcripts = scan.data.raw.filter((p) => p.relPath.startsWith("raw/transcripts/") && p.relPath.endsWith(".md"));
+  for (const t of transcripts) {
+    const datePrefix = t.relPath.split("/").pop().slice(0, 10);
+    for (const [dir, status] of workDirs) {
+      if (dir.split("/").pop().startsWith(datePrefix) && (status === "done" || status === "invalid")) {
+        staleTranscripts.push({ path: t.relPath, reason: `work item ${dir} is ${status}` });
+        break;
+      }
+    }
+  }
+  const doneWorkItems = [];
+  for (const [relDir, status] of workDirs) {
+    const dirName = relDir.split("/").pop();
+    const dateStr = dirName.slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) continue;
+    if (daysSince(dateStr) < input.days) continue;
+    let files;
+    try {
+      files = await readdir4(join13(input.vault, relDir));
+    } catch {
+      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" });
+    } else if (hasSpec && !hasPlan) {
+      incompleteWorkItems.push({ path: relDir, reason: "has spec but no plan" });
+    } else if (hasWI && !hasSpec && !hasPlan) {
+      incompleteWorkItems.push({ path: relDir, reason: "only work-item.md, no spec or plan" });
+    }
+  }
+  const stale = [];
+  for (const page of scan.data.typedKnowledge) {
+    try {
+      const text = await readFile10(join13(input.vault, page.relPath), "utf8");
+      const fm = extractFrontmatter(text);
+      if (fm.ok && typeof fm.data.updated === "string") {
+        const age = daysSince(fm.data.updated);
+        if (age >= input.days) {
+          stale.push({ page: page.relPath, reason: `updated ${age} days ago (threshold: ${input.days})` });
+        }
+      }
+    } catch {
+    }
+  }
+  if (input.archive) {
+    const archiveDir = join13(input.vault, "_archive", (/* @__PURE__ */ new Date()).toISOString().slice(0, 10));
+    await mkdir6(archiveDir, { recursive: true });
+    const citedRawPaths = /* @__PURE__ */ new Set();
+    for (const page of scan.data.typedKnowledge) {
+      const text = await readFile10(join13(input.vault, page.relPath), "utf8").catch(() => "");
+      for (const line of text.split("\n")) {
+        for (const m of line.matchAll(/\^\[(raw\/[^\]]+)\]/g)) {
+          citedRawPaths.add(m[1]);
+        }
+        for (const m of line.matchAll(/raw\/[^\s,\]"]+\.md/g)) {
+          citedRawPaths.add(m[0]);
+        }
+      }
+    }
+    for (const t of staleTranscripts) {
+      if (citedRawPaths.has(t.path) || citedRawPaths.has(t.path.replace(/\.md$/, ""))) continue;
+      const dest = join13(archiveDir, t.path.split("/").pop());
+      try {
+        await rename2(join13(input.vault, t.path), dest);
+        archived.push(t.path);
+      } catch {
+      }
     }
-    if (!newest) continue;
-    const gap = dayDiff(updated, newest);
-    if (gap > input.days) {
-      stale.push({ page: p.relPath, page_updated: updated, newest_source_ingested: newest, gap_days: gap });
+    for (const w of [...incompleteWorkItems, ...doneWorkItems]) {
+      const parts = w.path.split("/");
+      if (parts.length >= 4 && parts[0] === "projects") {
+        const slug = parts[1];
+        const itemName = parts[3];
+        const histDir = join13(input.vault, "projects", slug, "history", "archived-work");
+        await mkdir6(histDir, { recursive: true });
+        const dest = join13(histDir, itemName);
+        try {
+          await rename2(join13(input.vault, w.path), dest);
+          archived.push(w.path);
+        } catch {
+        }
+      } else {
+        const dest = join13(archiveDir, w.path.replace(/\//g, "_"));
+        try {
+          await rename2(join13(input.vault, w.path), dest);
+          archived.push(w.path);
+        } catch {
+        }
+      }
     }
   }
-  if (stale.length > 0) return { exitCode: ExitCode.STALE_PAGE, result: ok({ stale, humanHint: stale.map((s) => `${s.page} (${s.gap_days}d stale)`).join("\n") }) };
-  return { exitCode: ExitCode.OK, result: ok({ stale, humanHint: "no stale pages" }) };
+  if (input.archive && archived.length > 0) {
+    appendLastOp(input.vault, {
+      operation: "stale-archive",
+      summary: `archived ${archived.length} stale items`,
+      files: archived,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  const total = stale.length + staleTranscripts.length + incompleteWorkItems.length + doneWorkItems.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}`));
+  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 (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({
+    stale: [...stale, ...staleTranscripts.map((t) => ({ page: t.path, reason: t.reason })), ...incompleteWorkItems.map((w) => ({ page: w.path, reason: w.reason })), ...doneWorkItems.map((w) => ({ page: w.path, reason: w.reason }))],
+    stale_transcripts: staleTranscripts,
+    incomplete_work_items: incompleteWorkItems,
+    done_work_items: doneWorkItems,
+    archived,
+    humanHint: hintLines.join("\n")
+  }) };
 }
 
 // src/commands/pagesize.ts
@@ -1567,19 +1999,19 @@ async function runPagesize(input) {
 }
 
 // src/commands/log-rotate.ts
-import { readFile as readFile10, rename as rename2, writeFile as writeFile5, stat as stat5 } from "fs/promises";
-import { join as join11 } from "path";
+import { readFile as readFile11, rename as rename3, writeFile as writeFile6, stat as stat5 } from "fs/promises";
+import { join as join14 } from "path";
 var ENTRY_RE = /^## \[(\d{4})-\d{2}-\d{2}\]/gm;
 async function runLogRotate(input) {
   try {
-    await stat5(join11(input.vault, "SCHEMA.md"));
+    await stat5(join14(input.vault, "SCHEMA.md"));
   } catch {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
-  const logPath = join11(input.vault, "log.md");
+  const logPath = join14(input.vault, "log.md");
   let logText;
   try {
-    logText = await readFile10(logPath, "utf8");
+    logText = await readFile11(logPath, "utf8");
   } catch {
     return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: logPath }) };
   }
@@ -1596,9 +2028,9 @@ async function runLogRotate(input) {
   }
   const newestYear = matches[matches.length - 1][1];
   const rotatedName = `log-${newestYear}.md`;
-  const rotatedPath = join11(input.vault, rotatedName);
+  const rotatedPath = join14(input.vault, rotatedName);
   try {
-    await rename2(logPath, rotatedPath);
+    await rename3(logPath, rotatedPath);
     const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
     const fresh = `# Vault Log
 
@@ -1608,15 +2040,23 @@ Chronological action log. Newest entries last. Skill writes append entries; lint
 
 - Previous log moved to ${rotatedName}
 `;
-    await writeFile5(logPath, fresh, "utf8");
+    await writeFile6(logPath, fresh, "utf8");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
   }
+  appendLastOp(input.vault, {
+    operation: "log-rotate",
+    summary: `rotated ${entries} entries to ${rotatedName}`,
+    files: ["log.md", rotatedName],
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
   return { exitCode: ExitCode.OK, result: ok({ entries, threshold: input.threshold, rotated: true, rotated_to: rotatedName, humanHint: `rotated ${entries} entries to ${rotatedName}` }) };
 }
 
 // src/commands/lint.ts
-import { readFile as readFile12, writeFile as writeFile6 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { readFile as readFile13, writeFile as writeFile7 } from "fs/promises";
+import { join as join17 } from "path";
 
 // src/commands/topic-map-check.ts
 var DEFAULT_THRESHOLD = 200;
@@ -1638,13 +2078,13 @@ async function runTopicMapCheck(input) {
 }
 
 // src/commands/index-link-format.ts
-import { readFile as readFile11 } from "fs/promises";
-import { join as join12 } from "path";
+import { readFile as readFile12 } from "fs/promises";
+import { join as join15 } from "path";
 var MD_LINK_RE = /\[[^\[\]]+\]\([^)]+\.md\)/;
 async function runIndexLinkFormat(input) {
   let text = "";
   try {
-    text = await readFile11(join12(input.vault, "index.md"), "utf8");
+    text = await readFile12(join15(input.vault, "index.md"), "utf8");
   } catch {
   }
   const markdown_links = [];
@@ -1657,8 +2097,8 @@ ${markdown_links.map((l) => `  line ${l.line}: ${l.text}`).join("\n")}`;
 }
 
 // src/commands/dedup.ts
-import { readFileSync, writeFileSync, unlinkSync } from "fs";
-import { join as join13 } from "path";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2 } from "fs";
+import { join as join16 } from "path";
 async function runDedup(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -1686,7 +2126,7 @@ async function runDedup(input) {
       }
     }
     for (const page of scan.data.typedKnowledge) {
-      const text = readFileSync(join13(input.vault, page.relPath), "utf-8");
+      const text = readFileSync3(join16(input.vault, page.relPath), "utf-8");
       let updated = text;
       let changed = false;
       for (const [oldPath, newPath] of replacements) {
@@ -1704,19 +2144,27 @@ async function runDedup(input) {
         }
       }
       if (changed) {
-        writeFileSync(join13(input.vault, page.relPath), updated);
+        writeFileSync2(join16(input.vault, page.relPath), updated);
         rewired.push(page.relPath);
       }
     }
     for (const [oldPath] of replacements) {
-      const fullPath = join13(input.vault, oldPath);
+      const fullPath = join16(input.vault, oldPath);
       try {
-        unlinkSync(fullPath);
+        unlinkSync2(fullPath);
         removed.push(oldPath);
       } catch {
       }
     }
   }
+  if (input.apply && (rewired.length > 0 || removed.length > 0)) {
+    appendLastOp(input.vault, {
+      operation: "dedup",
+      summary: `rewired ${rewired.length} pages, removed ${removed.length} duplicates`,
+      files: [...rewired, ...removed],
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   const exitCode = duplicates.length > 0 ? input.apply ? ExitCode.DEDUP_APPLIED : ExitCode.RAW_DEDUP_DETECTED : ExitCode.OK;
   const hintLines = [`scanned: ${totalFiles} raw files`];
   if (duplicates.length > 0) {
@@ -1749,8 +2197,25 @@ function hasDuplicateFrontmatter(body) {
   }
   return false;
 }
-var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "missing_overview"];
+function extractSourceEntries(rawFm) {
+  const lines = rawFm.split(/\r?\n/);
+  const sourcesLineIdx = lines.findIndex((l) => /^sources:/.test(l));
+  if (sourcesLineIdx === -1) return [];
+  const sourcesLine = lines[sourcesLineIdx].trim();
+  const inlineMatch = sourcesLine.match(/^sources:\s*\[(.+)]\s*$/);
+  if (inlineMatch) {
+    return [...inlineMatch[1].matchAll(/"[^"]*"|'[^']*'|[^,\s]\S*/g)].map((m) => m[0].replace(/,\s*$/, ""));
+  }
+  const entries = [];
+  for (let i = sourcesLineIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!/^\s+- /.test(line)) break;
+    entries.push(line.replace(/^\s+- /, "").trim());
+  }
+  return entries;
+}
+var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy"];
+var WARNING_ORDER = ["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"];
 async function runLint(input) {
   const buckets = {};
@@ -1777,8 +2242,12 @@ async function runLint(input) {
   if (linkFmt.result.ok && linkFmt.result.data.markdown_links.length > 0) {
     buckets.index_link_format = linkFmt.result.data.markdown_links;
   }
-  const stale = await runStale({ vault: input.vault, days: input.days });
-  if (stale.result.ok && stale.result.data.stale.length > 0) buckets.stale_page = stale.result.data.stale;
+  const staleResult = await runStale({ vault: input.vault, days: input.days });
+  if (staleResult.result.ok) {
+    const st = staleResult.result.data;
+    const staleList = [...st.stale_transcripts.map((t) => t.path), ...st.incomplete_work_items.map((w) => w.path), ...(st.done_work_items ?? []).map((w) => w.path)];
+    if (staleList.length > 0) buckets.stale_page = staleList;
+  }
   const pagesize = await runPagesize({ vault: input.vault, lines: input.lines });
   if (pagesize.result.ok && pagesize.result.data.oversized.length > 0) buckets.page_too_large = pagesize.result.data.oversized;
   const rotate = await runLogRotate({ vault: input.vault, threshold: input.logThreshold, apply: false });
@@ -1796,6 +2265,8 @@ async function runLint(input) {
   }
   const dedup = await runDedup({ vault: input.vault });
   if (dedup.result.ok && dedup.result.data.duplicates.length > 0) buckets.raw_dedup = dedup.result.data.duplicates;
+  const compoundRefs = await validateCompoundReferences(input.vault);
+  if (compoundRefs.ok && compoundRefs.data.length > 0) buckets.compound_refs = compoundRefs.data;
   const scan = await scanVault(input.vault);
   const allPages = scan.ok ? [...scan.data.typedKnowledge, ...scan.data.raw, ...scan.data.workItems, ...scan.data.compound] : [];
   const slugs = scan.ok ? buildSlugMap(allPages) : /* @__PURE__ */ new Map();
@@ -1807,6 +2278,7 @@ async function runLint(input) {
     const noOverview = [];
     const fmWikilinkFlags = [];
     const wikilinkCitationFlags = [];
+    const brokenSourceFlags = [];
     for (const page of scan.data.typedKnowledge) {
       const text = await readPage(page);
       const split = splitFrontmatter(text);
@@ -1817,6 +2289,15 @@ async function runLint(input) {
       if (isLegacyCitationStyle(body)) legacyPages.push(page.relPath);
       if (hasOrphanedCitations(body)) orphanedPages.push(page.relPath);
       if (hasWikilinkCitations(body)) wikilinkCitationFlags.push(page.relPath);
+      const sourcesEntries = extractSourceEntries(rawFm);
+      for (const entry of sourcesEntries) {
+        let rawPath = entry.replace(/^"/, "").replace(/"$/, "").replace(/^'/, "").replace(/'$/, "");
+        rawPath = rawPath.replace(/^\^\[/, "").replace(/\]$/, "");
+        if (!rawPath.startsWith("raw/") && !rawPath.startsWith("_archive/raw/")) continue;
+        if (!existsSync2(join17(input.vault, rawPath)) && !existsSync2(join17(input.vault, rawPath + ".md")) && !rawPath.startsWith("_archive/") && !existsSync2(join17(input.vault, "_archive", rawPath)) && !existsSync2(join17(input.vault, "_archive", rawPath + ".md"))) {
+          brokenSourceFlags.push(`${page.relPath}: ${rawPath}`);
+        }
+      }
       const fmLinks = rawFm.match(/\[\[([^\[\]|]+)(?:\|[^\[\]]*)?\]\]/g) ?? [];
       for (const link of fmLinks) {
         const target = link.replace(/^\[\[/, "").replace(/(?:\|[^\[\]]*)?\]\]$/, "").trim();
@@ -1846,19 +2327,75 @@ async function runLint(input) {
     if (noOverview.length > 0) buckets.missing_overview = noOverview;
     if (fmWikilinkFlags.length > 0) buckets.frontmatter_wikilink = fmWikilinkFlags;
     if (wikilinkCitationFlags.length > 0) buckets.wikilink_citation = wikilinkCitationFlags;
-    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 readFile12(absPath, "utf8");
-          const split = splitFrontmatter(raw);
-          if (!split.ok) {
-            unresolved.push(relPath);
-            continue;
+    if (brokenSourceFlags.length > 0) buckets.broken_sources = brokenSourceFlags;
+    const workItemHealth = [];
+    const workItemDirs = /* @__PURE__ */ new Map();
+    for (const page of scan.data.workItems) {
+      const dir = page.relPath.replace(/\/(spec|plan|log)\.md$/, "");
+      const pages = workItemDirs.get(dir) ?? [];
+      pages.push(page);
+      workItemDirs.set(dir, pages);
+    }
+    for (const [dir, pages] of workItemDirs) {
+      const hasSpec = pages.some((p) => p.relPath.endsWith("/spec.md"));
+      const hasPlan = pages.some((p) => p.relPath.endsWith("/plan.md"));
+      if (hasSpec && !hasPlan) {
+        const lastSegment = dir.split("/").pop();
+        const dateMatch = lastSegment.match(/^(\d{4}-\d{2}-\d{2})/);
+        if (dateMatch) {
+          const dirDate = Date.parse(dateMatch[1]);
+          if (!isNaN(dirDate) && Date.now() - dirDate > 24 * 60 * 60 * 1e3) {
+            workItemHealth.push(`${dir}/spec.md: has spec but no plan after 24h`);
           }
-          const body = split.data.body;
+        }
+      }
+      for (const page of pages) {
+        if (!page.relPath.endsWith("/spec.md")) continue;
+        const text = await readPage(page);
+        const fm = extractFrontmatter(text);
+        if (fm.ok && fm.data.status === "in-progress" && !fm.data.started) {
+          workItemHealth.push(`${page.relPath}: in-progress without started date`);
+        }
+      }
+    }
+    if (workItemHealth.length > 0) buckets.work_item_health = workItemHealth;
+    const orphanedProjectPages = [];
+    for (const page of scan.data.typedKnowledge) {
+      const text = await readPage(page);
+      const fm = extractFrontmatter(text);
+      if (!fm.ok) continue;
+      const pp = fm.data.provenance_projects;
+      if (!Array.isArray(pp)) continue;
+      for (const entry of pp) {
+        const slugMatch = String(entry).match(/\[\[([^\]]+)\]\]/);
+        if (!slugMatch) continue;
+        const slug = slugMatch[1];
+        const knowledgePath = join17(input.vault, "projects", slug, "knowledge.md");
+        if (!existsSync2(knowledgePath)) continue;
+        const pageRef = page.relPath.replace(/\.md$/, "");
+        try {
+          const knowledgeContent = await readFile13(knowledgePath, "utf8");
+          if (!knowledgeContent.includes(`[[${pageRef}]]`)) {
+            orphanedProjectPages.push(`${page.relPath}: not in projects/${slug}/knowledge.md`);
+          }
+        } catch {
+        }
+      }
+    }
+    if (orphanedProjectPages.length > 0) buckets.orphaned_project_pages = orphanedProjectPages;
+    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 readFile13(absPath, "utf8");
+          const split = splitFrontmatter(raw);
+          if (!split.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
+          const body = split.data.body;
           const rawFm = split.data.rawFrontmatter;
           const stripped = body.replace(FENCE_RE2, "");
           const lines = stripped.split("\n");
@@ -1932,7 +2469,7 @@ async function runLint(input) {
 ${rawFm}
 ---
 ${newBody}`;
-          await writeFile6(absPath, newContent, "utf8");
+          await writeFile7(absPath, newContent, "utf8");
           fixed.push(relPath);
         } catch {
           unresolved.push(relPath);
@@ -1945,6 +2482,128 @@ ${newBody}`;
         else delete buckets.legacy_citation_style;
       }
     }
+    if (input.fix && noOverview.length > 0) {
+      for (const relPath of noOverview) {
+        try {
+          const absPath = `${input.vault}/${relPath}`;
+          const raw = await readFile13(absPath, "utf8");
+          const split = splitFrontmatter(raw);
+          if (!split.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
+          const body = split.data.body;
+          const rawFm = split.data.rawFrontmatter;
+          const fm = extractFrontmatter(raw);
+          const title = fm.ok && typeof fm.data.title === "string" ? fm.data.title : "";
+          const overviewSection = `## Overview
+
+${title}`;
+          const trimmedBody = body.replace(/^\n+/, "");
+          const newContent = `---
+${rawFm}
+---
+
+${overviewSection}
+
+${trimmedBody}`;
+          await writeFile7(absPath, newContent, "utf8");
+          fixed.push(relPath);
+        } catch {
+          unresolved.push(relPath);
+        }
+      }
+      const fixedBeforeOverview = fixed.length;
+      const fixedSet = new Set(fixed);
+      const remaining = noOverview.filter((p) => !fixedSet.has(p));
+      if (remaining.length > 0) buckets.missing_overview = remaining;
+      else delete buckets.missing_overview;
+    }
+    if (input.fix && wikilinkCitationFlags.length > 0) {
+      const WIKILINK_RE = /\[\[raw\/([^\]|]+)(?:\|[^\]]*)?\]\]/g;
+      const FENCE_RE2 = /```[\s\S]*?```/g;
+      const wikilinkFixed = [];
+      for (const relPath of wikilinkCitationFlags) {
+        try {
+          const absPath = `${input.vault}/${relPath}`;
+          const raw = await readFile13(absPath, "utf8");
+          const split = splitFrontmatter(raw);
+          if (!split.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
+          const body = split.data.body;
+          const rawFm = split.data.rawFrontmatter;
+          const stripped = body.replace(FENCE_RE2, "");
+          const wikilinkMatches = [...stripped.matchAll(WIKILINK_RE)];
+          if (wikilinkMatches.length === 0) {
+            unresolved.push(relPath);
+            continue;
+          }
+          const wikilinkPaths = [...new Set(wikilinkMatches.map((m) => m[1]))];
+          const bodyLines = body.split("\n");
+          let inSrc = false;
+          const newBodyLines = [];
+          for (const line of bodyLines) {
+            if (/^## Sources\b/.test(line.trim())) {
+              inSrc = true;
+              newBodyLines.push(line);
+              continue;
+            }
+            if (inSrc) {
+              newBodyLines.push(line);
+              continue;
+            }
+            let cleaned = line.replace(/\[\[raw\/[^\]|]+(?:\|[^\]]*)?\]\]/g, "");
+            cleaned = cleaned.replace(/\s+\./g, ".").replace(/\s{2,}/g, " ").replace(/\s+$/, "");
+            if (cleaned.length > 0 || line.trim().length === 0) {
+              newBodyLines.push(cleaned);
+            }
+          }
+          let newBody = newBodyLines.join("\n");
+          const citationMarkers = wikilinkPaths.map((p) => `^[raw/${p}]`);
+          const sourceEntries = extractSourceEntries(rawFm);
+          const fmMarkers = [];
+          for (const entry of sourceEntries) {
+            let rawPath = entry.replace(/^"/, "").replace(/"$/, "").replace(/^'/, "").replace(/'$/, "");
+            rawPath = rawPath.replace(/^\^\[/, "").replace(/\]$/, "");
+            if (rawPath.startsWith("raw/")) {
+              fmMarkers.push(`^[${rawPath}]`);
+            }
+          }
+          const allMarkers = [.../* @__PURE__ */ new Set([...citationMarkers, ...fmMarkers])];
+          const hasSourcesSection = /^## Sources\b/m.test(newBody);
+          if (hasSourcesSection) {
+            const existingSources = new Set(
+              newBody.split("\n").filter((l) => /^- \^\[raw\//.test(l.trim())).map((l) => l.trim().replace(/^- /, ""))
+            );
+            const newMarkers = allMarkers.filter((m) => !existingSources.has(m));
+            const sourceLines = newMarkers.map((m) => `- ${m}`);
+            if (sourceLines.length > 0) {
+              newBody = newBody.trimEnd() + "\n" + sourceLines.join("\n") + "\n";
+            }
+          } else {
+            const sourceLines = allMarkers.map((m) => `- ${m}`);
+            newBody = newBody.trimEnd() + "\n\n## Sources\n\n" + sourceLines.join("\n") + "\n";
+          }
+          const newContent = `---
+${rawFm}
+---
+${newBody}`;
+          await writeFile7(absPath, newContent, "utf8");
+          wikilinkFixed.push(relPath);
+        } catch {
+          unresolved.push(relPath);
+        }
+      }
+      fixed.push(...wikilinkFixed);
+      if (wikilinkFixed.length > 0) {
+        const fixedSet = new Set(wikilinkFixed);
+        const remaining = wikilinkCitationFlags.filter((p) => !fixedSet.has(p));
+        if (remaining.length > 0) buckets.wikilink_citation = remaining;
+        else delete buckets.wikilink_citation;
+      }
+    }
   }
   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] }] : []);
@@ -1966,6 +2625,14 @@ ${newBody}`;
     hintLines.push(`  ${b.kind}: ${b.items.length}`);
   }
   if (hintLines.length === 0) hintLines.push("0 errors, 0 warnings, 0 info");
+  if (input.fix && fixed.length > 0) {
+    appendLastOp(input.vault, {
+      operation: "lint-fix",
+      summary: `fixed ${fixed.length} page(s)`,
+      files: fixed,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   return {
     exitCode,
     result: ok({
@@ -1980,14 +2647,14 @@ ${newBody}`;
 }
 
 // src/commands/config.ts
-import { readFile as readFile13 } from "fs/promises";
-import { existsSync } from "fs";
-import { join as join14 } from "path";
+import { readFile as readFile14 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import { join as join18 } from "path";
 function validateKey(key) {
   return CONFIG_KEYS.includes(key) || isValidWikiProfileKey(key);
 }
 function configPath(home) {
-  return join14(home, ".skillwiki", ".env");
+  return join18(home, ".skillwiki", ".env");
 }
 async function runConfigGet(input) {
   if (!validateKey(input.key)) {
@@ -2005,7 +2672,7 @@ async function runConfigSet(input) {
   try {
     let originalContent;
     try {
-      originalContent = await readFile13(filePath, "utf8");
+      originalContent = await readFile14(filePath, "utf8");
     } catch {
     }
     const existing = originalContent !== void 0 ? parseDotenvText(originalContent) : {};
@@ -2037,17 +2704,17 @@ async function runConfigList(input) {
 }
 async function runConfigPath(input) {
   const filePath = configPath(input.home);
-  return { exitCode: ExitCode.OK, result: ok({ path: filePath, exists: existsSync(filePath), humanHint: filePath }) };
+  return { exitCode: ExitCode.OK, result: ok({ path: filePath, exists: existsSync3(filePath), humanHint: filePath }) };
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync3, readdirSync, statSync } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync5, lstatSync, readlinkSync, readdirSync, statSync } from "fs";
+import { join as join21, resolve as resolve4 } from "path";
 import { execSync } from "child_process";
 
 // src/utils/auto-update.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync } from "fs";
-import { join as join15, dirname as dirname6 } from "path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync4, mkdirSync as mkdirSync2 } from "fs";
+import { join as join19, dirname as dirname8 } from "path";
 import { spawn } from "child_process";
 
 // src/utils/update-consts.ts
@@ -2058,11 +2725,11 @@ var CLI_DISABLE_FLAG = "--no-update-notifier";
 
 // src/utils/auto-update.ts
 function cachePath(home) {
-  return join15(home, ".skillwiki", CACHE_FILENAME);
+  return join19(home, ".skillwiki", CACHE_FILENAME);
 }
 function readCacheRaw(home) {
   try {
-    const raw = readFileSync2(cachePath(home), "utf8");
+    const raw = readFileSync4(cachePath(home), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -2077,8 +2744,8 @@ function readCache(home) {
 }
 function writeCache(home, cache) {
   const p = cachePath(home);
-  mkdirSync(dirname6(p), { recursive: true });
-  writeFileSync2(p, JSON.stringify(cache, null, 2));
+  mkdirSync2(dirname8(p), { recursive: true });
+  writeFileSync3(p, JSON.stringify(cache, null, 2));
 }
 function latestFromCache(home, currentVersion) {
   const { cache } = readCache(home);
@@ -2096,7 +2763,7 @@ function triggerAutoUpdate(home, currentVersion) {
   const { isStale } = readCache(home);
   if (!isStale) return;
   const bgScript = new URL("../auto-update-bg.js", import.meta.url).pathname;
-  if (!existsSync2(bgScript)) return;
+  if (!existsSync4(bgScript)) return;
   const child = spawn(process.execPath, [bgScript, home, currentVersion], {
     detached: true,
     stdio: "ignore"
@@ -2107,13 +2774,13 @@ function triggerAutoUpdate(home, currentVersion) {
 }
 
 // src/utils/plugin-registry.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { join as join16 } from "path";
-var REGISTRY_PATH = join16(".claude", "plugins", "installed_plugins.json");
+import { readFileSync as readFileSync5 } from "fs";
+import { join as join20 } from "path";
+var REGISTRY_PATH = join20(".claude", "plugins", "installed_plugins.json");
 var PLUGIN_KEY = "skillwiki@llm-wiki";
 function readInstalledPlugins(home) {
   try {
-    const raw = readFileSync3(join16(home, REGISTRY_PATH), "utf8");
+    const raw = readFileSync5(join20(home, REGISTRY_PATH), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -2138,23 +2805,79 @@ function checkNodeVersion() {
   }
   return check("error", "node_version", "Node.js version", `Node.js v${major} is below minimum v20`);
 }
-function checkCliOnPath(argv) {
+function detectCliChannels(argv, home) {
+  const channels = [];
   if (argv.length >= 2 && argv[1].endsWith("cli.js")) {
-    return check("warn", "cli_on_path", "skillwiki on PATH", "Running via node cli.js (dev mode) \u2014 PATH check skipped");
+    const devPath = resolve4(argv[1]);
+    channels.push({ name: "dev", path: devPath, isDevLink: true });
+  }
+  try {
+    const whichOut = execSync("which skillwiki 2>/dev/null", { encoding: "utf8" }).trim();
+    if (whichOut) {
+      const isDev = isDevSymlink(whichOut);
+      if (!channels.some((c) => c.path === resolve4(whichOut))) {
+        channels.push({ name: "npm", path: whichOut, isDevLink: isDev });
+      }
+    }
+  } catch {
   }
-  if (argv.length >= 2 && argv[1] === "skillwiki") {
-    return check("pass", "cli_on_path", "skillwiki on PATH", "Running as skillwiki \u2014 already on PATH");
+  const plugin = findPlugin(home);
+  if (plugin) {
+    const pluginBin = join21(plugin.installPath, "bin", "skillwiki");
+    if (existsSync5(pluginBin)) {
+      channels.push({ name: "plugin", path: pluginBin, isDevLink: false });
+    }
+  }
+  const installBin = join21(home, ".claude", "skills", "bin", "skillwiki");
+  if (existsSync5(installBin)) {
+    channels.push({ name: "install", path: installBin, isDevLink: false });
   }
+  return channels;
+}
+function isDevSymlink(binPath) {
   try {
-    execSync("which skillwiki 2>/dev/null", { encoding: "utf8" }).trim();
-    return check("pass", "cli_on_path", "skillwiki on PATH", "skillwiki found on PATH");
+    const st = lstatSync(binPath);
+    if (st.isSymbolicLink()) {
+      const target = resolve4(binPath, "..", readlinkSync(binPath));
+      return target.includes("packages/cli") || target.includes("packages\\cli");
+    }
   } catch {
-    return check("warn", "cli_on_path", "skillwiki on PATH", "skillwiki not found on PATH");
   }
+  return false;
+}
+function checkCliChannels(argv, home) {
+  const channels = detectCliChannels(argv, home);
+  if (channels.length === 0) {
+    return check("warn", "cli_channels", "CLI channels", "skillwiki not found on any channel");
+  }
+  if (channels.length === 1) {
+    const ch = channels[0];
+    const label = ch.isDevLink ? `${ch.name} (dev source)` : ch.name;
+    return check("pass", "cli_channels", "CLI channels", `Single channel: ${label}`);
+  }
+  const devChannels = channels.filter((c) => c.isDevLink);
+  const prodChannels = channels.filter((c) => !c.isDevLink);
+  if (devChannels.length > 0 && prodChannels.length > 0) {
+    const devNames = devChannels.map((c) => `${c.name}(dev)`);
+    const prodNames = prodChannels.map((c) => c.name);
+    return check(
+      "warn",
+      "cli_channels",
+      "CLI channels",
+      `${channels.length} channels: ${[...devNames, ...prodNames].join(", ")} \u2014 dev and prod binaries overlap; dev repo should use project-local settings only`
+    );
+  }
+  const names = channels.map((c) => c.name);
+  return check(
+    "warn",
+    "cli_channels",
+    "CLI channels",
+    `${channels.length} channels: ${names.join(", ")} \u2014 remove unused install with: rm ~/.claude/skills/bin/skillwiki`
+  );
 }
 async function checkConfigFile(home) {
   const cfgPath = configPath(home);
-  if (!existsSync3(cfgPath)) {
+  if (!existsSync5(cfgPath)) {
     return check("warn", "config_file", "Config file exists", `${cfgPath} not found`);
   }
   try {
@@ -2169,7 +2892,7 @@ function checkWikiPathExists(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "wiki_path_exists", "Vault directory exists", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (existsSync3(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+  if (existsSync5(resolvedPath) && statSync(resolvedPath).isDirectory()) {
     return check("pass", "wiki_path_exists", "Vault directory exists", resolvedPath);
   }
   return check("error", "wiki_path_exists", "Vault directory exists", `${resolvedPath} does not exist or is not a directory`);
@@ -2178,20 +2901,27 @@ function checkVaultStructure(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync3(resolvedPath)) {
+  if (!existsSync5(resolvedPath)) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
   }
   const missing = [];
-  if (!existsSync3(join17(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  if (!existsSync5(join21(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
   for (const dir of ["raw", "entities", "concepts", "meta"]) {
-    if (!existsSync3(join17(resolvedPath, dir))) missing.push(dir + "/");
+    if (!existsSync5(join21(resolvedPath, dir))) missing.push(dir + "/");
   }
   if (missing.length === 0) {
     return check("pass", "vault_structure", "Vault structure valid", "All required files and directories present");
   }
   return check("warn", "vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")} \u2014 run \`skillwiki init\` to add CodeWiki structure`);
 }
-function checkSkillsInstalled(home) {
+function checkSkillsInstalled(home, cwd) {
+  const srcDir = cwd ? join21(cwd, "packages", "skills") : void 0;
+  if (srcDir && existsSync5(srcDir)) {
+    const found = findSkillMd(srcDir);
+    if (found.length > 0) {
+      return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (source)`);
+    }
+  }
   const plugin = findPlugin(home);
   if (plugin) {
     const found = findSkillMd(plugin.installPath);
@@ -2199,8 +2929,8 @@ function checkSkillsInstalled(home) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (plugin v${plugin.version})`);
     }
   }
-  const skillsDir = join17(home, ".claude", "skills");
-  if (existsSync3(skillsDir)) {
+  const skillsDir = join21(home, ".claude", "skills");
+  if (existsSync5(skillsDir)) {
     const found = findSkillMd(skillsDir);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (CLI install)`);
@@ -2208,6 +2938,25 @@ function checkSkillsInstalled(home) {
   }
   return check("warn", "skills_installed", "Skills installed", "No SKILL.md files found");
 }
+function checkDuplicateSkills(home) {
+  const plugin = findPlugin(home);
+  const skillsDir = join21(home, ".claude", "skills");
+  if (!plugin || !existsSync5(skillsDir)) {
+    return check("pass", "skills_duplicate", "Skills not duplicated", "Single install channel");
+  }
+  const pluginSkills = findSkillNames(plugin.installPath);
+  const cliSkills = findSkillNames(skillsDir);
+  const duplicates = pluginSkills.filter((name) => cliSkills.includes(name));
+  if (duplicates.length === 0) {
+    return check("pass", "skills_duplicate", "Skills not duplicated", "No overlap between plugin and CLI install");
+  }
+  return check(
+    "warn",
+    "skills_duplicate",
+    "Skills not duplicated",
+    `${duplicates.length} skill(s) in both plugin and ~/.claude/skills/ \u2014 remove CLI copies: rm -r ~/.claude/skills/{${duplicates.slice(0, 3).join(",")}${duplicates.length > 3 ? ",\u2026" : ""}}`
+  );
+}
 function checkNpmUpdate(home, currentVersion) {
   const { hasUpdate, latest } = latestFromCache(home, currentVersion);
   if (!latest) {
@@ -2257,12 +3006,112 @@ async function checkProfiles(home) {
 }
 async function checkProjectLocalOverride(cwd) {
   const dir = cwd ?? process.cwd();
-  const envPath = join17(dir, ".skillwiki", ".env");
-  if (existsSync3(envPath)) {
+  const envPath = join21(dir, ".skillwiki", ".env");
+  if (existsSync5(envPath)) {
     return check("pass", "project_local", "Project-local config", `Found: ${envPath}`);
   }
   return check("pass", "project_local", "Project-local config", "None");
 }
+function checkVaultGitRemote(resolvedPath) {
+  if (resolvedPath === void 0) {
+    return check("error", "vault_git_remote", "Vault git remote", "Cannot check \u2014 WIKI_PATH not resolved");
+  }
+  if (!existsSync5(join21(resolvedPath, ".git"))) {
+    return check("warn", "vault_git_remote", "Vault git remote", "Vault is not a git repository \u2014 sync features unavailable");
+  }
+  try {
+    const remote = execSync("git remote", { cwd: resolvedPath, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    if (!remote) {
+      return check("warn", "vault_git_remote", "Vault git remote", "No remote configured \u2014 push/pull unavailable");
+    }
+    let branch = "(no commits yet)";
+    try {
+      branch = execSync("git rev-parse --abbrev-ref HEAD", { cwd: resolvedPath, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    } catch {
+    }
+    return check("pass", "vault_git_remote", "Vault git remote", `Remote: ${remote.split("\n")[0]}, branch: ${branch}`);
+  } catch {
+    return check("warn", "vault_git_remote", "Vault git remote", "Could not read git remote info");
+  }
+}
+function checkObsidianTemplates(resolvedPath) {
+  if (resolvedPath === void 0) {
+    return check("error", "obsidian_templates", "Obsidian templates", "Cannot check \u2014 WIKI_PATH not resolved");
+  }
+  const missing = [];
+  if (!existsSync5(join21(resolvedPath, "_Templates"))) missing.push("_Templates/");
+  if (!existsSync5(join21(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
+  if (!existsSync5(join21(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");
+  }
+  return check("warn", "obsidian_templates", "Obsidian templates", `Missing: ${missing.join(", ")} \u2014 run \`skillwiki init\` to create`);
+}
+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 = join21(resolvedPath, "raw");
+  if (!existsSync5(rawDir)) {
+    return check("pass", "dsstore_clean", "No .DS_Store in raw/", "raw/ directory not found \u2014 check skipped");
+  }
+  const found = [];
+  (function walk2(dir, rel) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === ".DS_Store") {
+        found.push(rel ? `${rel}/.DS_Store` : ".DS_Store");
+      } else if (entry.isDirectory()) {
+        walk2(join21(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
+      }
+    }
+  })(rawDir, "");
+  if (found.length === 0) {
+    return check("pass", "dsstore_clean", "No .DS_Store in raw/", "No .DS_Store files found");
+  }
+  return check("warn", "dsstore_clean", "No .DS_Store in raw/", `${found.length} .DS_Store file(s) found \u2014 remove with: find ${rawDir} -name .DS_Store -delete`);
+}
+function checkSyncLastPush(resolvedPath) {
+  if (resolvedPath === void 0) {
+    return check("error", "sync_last_push", "Vault sync recency", "Cannot check \u2014 WIKI_PATH not resolved");
+  }
+  if (!existsSync5(join21(resolvedPath, ".git"))) {
+    return check("pass", "sync_last_push", "Vault sync recency", "No git repo \u2014 sync check skipped");
+  }
+  let timestamp;
+  try {
+    const out = execSync("git log -1 --format=%ct origin/HEAD", {
+      cwd: resolvedPath,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    timestamp = parseInt(out, 10);
+  } catch {
+    try {
+      const out = execSync("git log -1 --format=%ct HEAD", {
+        cwd: resolvedPath,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      timestamp = parseInt(out, 10);
+    } catch {
+    }
+  }
+  if (timestamp === void 0 || isNaN(timestamp)) {
+    return check("warn", "sync_last_push", "Vault sync recency", "No commits found \u2014 consider running `skillwiki sync status`");
+  }
+  const daysSince2 = Math.floor((Date.now() / 1e3 - timestamp) / 86400);
+  const dateStr = new Date(timestamp * 1e3).toISOString().slice(0, 10);
+  if (daysSince2 > 7) {
+    return check("warn", "sync_last_push", "Vault sync recency", `Last push was ${daysSince2} days ago \u2014 consider running \`skillwiki sync status\``);
+  }
+  return check("pass", "sync_last_push", "Vault sync recency", `Last push: ${dateStr} (${daysSince2} day(s) ago)`);
+}
 function findSkillMd(dir) {
   const results = [];
   let entries;
@@ -2273,9 +3122,24 @@ function findSkillMd(dir) {
   }
   for (const entry of entries) {
     if (entry.isFile() && entry.name === "SKILL.md") {
-      results.push(join17(dir, entry.name));
+      results.push(join21(dir, entry.name));
     } else if (entry.isDirectory()) {
-      results.push(...findSkillMd(join17(dir, entry.name)));
+      results.push(...findSkillMd(join21(dir, entry.name)));
+    }
+  }
+  return results;
+}
+function findSkillNames(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory() && existsSync5(join21(dir, entry.name, "SKILL.md"))) {
+      results.push(entry.name);
     }
   }
   return results;
@@ -2283,7 +3147,7 @@ function findSkillMd(dir) {
 async function runDoctor(input) {
   const checks = [];
   checks.push(checkNodeVersion());
-  checks.push(checkCliOnPath(input.argv));
+  checks.push(checkCliChannels(input.argv, input.home));
   checks.push(await checkConfigFile(input.home));
   checks.push(await checkProfiles(input.home));
   checks.push(await checkProjectLocalOverride(input.cwd));
@@ -2296,7 +3160,12 @@ async function runDoctor(input) {
   const resolvedPath = resolved.ok ? resolved.data.path : void 0;
   checks.push(checkWikiPathExists(resolvedPath));
   checks.push(checkVaultStructure(resolvedPath));
-  checks.push(checkSkillsInstalled(input.home));
+  checks.push(checkObsidianTemplates(resolvedPath));
+  checks.push(checkVaultGitRemote(resolvedPath));
+  checks.push(checkSyncLastPush(resolvedPath));
+  checks.push(checkDotStoreClean(resolvedPath));
+  checks.push(checkSkillsInstalled(input.home, input.cwd));
+  checks.push(checkDuplicateSkills(input.home));
   checks.push(checkNpmUpdate(input.home, input.currentVersion));
   checks.push(checkPluginVersionDrift(input.home, input.currentVersion));
   const summary = {
@@ -2318,8 +3187,8 @@ async function runDoctor(input) {
 }
 
 // src/commands/archive.ts
-import { rename as rename3, mkdir as mkdir5, readFile as readFile14, writeFile as writeFile7 } from "fs/promises";
-import { join as join18, dirname as dirname7 } from "path";
+import { rename as rename4, mkdir as mkdir7, readFile as readFile15, writeFile as writeFile8 } from "fs/promises";
+import { join as join22, 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 };
@@ -2335,31 +3204,37 @@ 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 = join18("_archive", relPath);
-  await mkdir5(dirname7(join18(input.vault, archivePath)), { recursive: true });
+  const archivePath = join22("_archive", relPath).replace(/\\/g, "/");
+  await mkdir7(dirname9(join22(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
   if (!isRaw) {
-    const indexPath = join18(input.vault, "index.md");
+    const indexPath = join22(input.vault, "index.md");
     try {
-      const idx = await readFile14(indexPath, "utf8");
+      const idx = await readFile15(indexPath, "utf8");
       const slug = relPath.replace(/\.md$/, "").split("/").pop();
       const originalLines = idx.split("\n");
       const filtered = originalLines.filter((l) => !l.includes(`[[${slug}]]`));
       if (filtered.length !== originalLines.length) {
-        await writeFile7(indexPath, filtered.join("\n"), "utf8");
+        await writeFile8(indexPath, filtered.join("\n"), "utf8");
         indexUpdated = true;
       }
     } catch (e) {
       if (e?.code !== "ENOENT") throw e;
     }
   }
-  await rename3(join18(input.vault, relPath), join18(input.vault, archivePath));
+  await rename4(join22(input.vault, relPath), join22(input.vault, archivePath));
+  appendLastOp(input.vault, {
+    operation: "archive",
+    summary: `moved ${relPath} to ${archivePath}`,
+    files: [relPath],
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
   return { exitCode: ExitCode.OK, result: ok({ archived_from: relPath, archived_to: archivePath, index_updated: indexUpdated, humanHint: `${relPath} -> ${archivePath}${indexUpdated ? " (index updated)" : ""}` }) };
 }
 
 // src/commands/drift.ts
 import { createHash as createHash2 } from "crypto";
-import { writeFile as writeFile8 } from "fs/promises";
+import { writeFile as writeFile9 } from "fs/promises";
 
 // src/utils/fetch.ts
 async function controlledFetch(url, opts) {
@@ -2425,6 +3300,7 @@ async function runDrift(input) {
     const sourceUrl = sourceUrlMatch[1].trim();
     const storedHash = storedHashMatch[1];
     if (!sourceUrl.startsWith("http://") && !sourceUrl.startsWith("https://")) continue;
+    if (/^refreshable:\s*false\b/m.test(rawFrontmatter)) continue;
     const resp = await doFetch(sourceUrl, FETCH_OPTS);
     if (!resp.ok) {
       results.push({
@@ -2445,7 +3321,7 @@ async function runDrift(input) {
 ${newFm}
 ---
 ${body}`;
-      await writeFile8(raw.absPath, newText, "utf8");
+      await writeFile9(raw.absPath, newText, "utf8");
       results.push({
         raw_path: raw.relPath,
         source_url: sourceUrl,
@@ -2473,6 +3349,14 @@ ${body}`;
   if (drifted.length > 0) hintLines.push(`drifted: ${drifted.length}`, ...drifted.map((d) => `  ${d.raw_path}`));
   if (fetchFailed.length > 0) hintLines.push(`fetch_failed: ${fetchFailed.length}`, ...fetchFailed.map((f) => `  ${f.raw_path}: ${f.fetch_error}`));
   if (updated.length > 0) hintLines.push(`updated: ${updated.length}`, ...updated.map((u) => `  ${u.raw_path}`));
+  if (input.apply && updated.length > 0) {
+    appendLastOp(input.vault, {
+      operation: "drift-apply",
+      summary: `updated ${updated.length} raw sources`,
+      files: updated.map((u) => u.raw_path),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   return {
     exitCode,
     result: ok({ scanned: results.length, drifted, fetch_failed: fetchFailed, updated, newFiles: newResults, unchanged, humanHint: hintLines.join("\n") })
@@ -2480,7 +3364,7 @@ ${body}`;
 }
 
 // src/commands/migrate-citations.ts
-import { writeFile as writeFile9 } from "fs/promises";
+import { writeFile as writeFile10 } from "fs/promises";
 var MARKER_RE2 = /\^\[(raw\/[^\]]+)\]/g;
 function moveMarkersToParagraphEnd(body) {
   const lines = body.split("\n");
@@ -2603,7 +3487,7 @@ ${migratedBody}${newFooter}`;
       continue;
     }
     if (!input.dryRun) {
-      await writeFile9(page.absPath, newText, "utf8");
+      await writeFile10(page.absPath, newText, "utf8");
     }
     migrated.push(page.relPath);
   }
@@ -2612,6 +3496,14 @@ ${migratedBody}${newFooter}`;
   if (migrated.length > 0) hintLines.push(`migrated: ${migrated.length}`);
   if (skipped.length > 0) hintLines.push(`skipped (already clean): ${skipped.length}`);
   if (unchanged > 0) hintLines.push(`unchanged (no markers): ${unchanged}`);
+  if (!input.dryRun && migrated.length > 0) {
+    appendLastOp(input.vault, {
+      operation: "migrate-citations",
+      summary: `converted ${migrated.length} citation(s)`,
+      files: migrated,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   return {
     exitCode,
     result: ok({
@@ -2625,7 +3517,7 @@ ${migratedBody}${newFooter}`;
 }
 
 // src/commands/frontmatter-fix.ts
-import { writeFile as writeFile10 } from "fs/promises";
+import { writeFile as writeFile11 } from "fs/promises";
 function isoToday() {
   return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 }
@@ -2667,7 +3559,7 @@ ${newBody}`;
       continue;
     }
     if (!input.dryRun) {
-      await writeFile10(page.absPath, newText, "utf8");
+      await writeFile11(page.absPath, newText, "utf8");
     }
     fixed.push(page.relPath);
   }
@@ -2677,6 +3569,14 @@ ${newBody}`;
   if (skipped.length > 0) hintLines.push(`skipped (parse error): ${skipped.length}`);
   if (unchanged > 0) hintLines.push(`unchanged: ${unchanged}`);
   if (input.dryRun && fixed.length > 0) hintLines.push("(dry run \u2014 no files written)");
+  if (!input.dryRun && fixed.length > 0) {
+    appendLastOp(input.vault, {
+      operation: "frontmatter-fix",
+      summary: `normalized frontmatter on ${fixed.length} page(s)`,
+      files: fixed,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   return {
     exitCode,
     result: ok({
@@ -2691,13 +3591,41 @@ ${newBody}`;
 
 // src/commands/update.ts
 import { execSync as execSync2 } from "child_process";
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
+import { join as join23 } from "path";
+function resolveGlobalSkillsRoot() {
+  try {
+    const globalRoot = execSync2("npm root -g", {
+      encoding: "utf8",
+      timeout: 5e3
+    }).trim();
+    return join23(globalRoot, "skillwiki", "skills");
+  } catch {
+    return null;
+  }
+}
+async function refreshInstalledSkills(target) {
+  const skillsRoot = resolveGlobalSkillsRoot();
+  if (!skillsRoot) {
+    return { warnings: ["could not locate global skillwiki installation for skill refresh"], refreshed: false };
+  }
+  try {
+    const result = await runInstall({ skillsRoot, target, dryRun: false, symlink: false });
+    if (result.result.ok) {
+      return { warnings: result.result.data.version_warnings, refreshed: true };
+    }
+    return { warnings: [`skill refresh failed: ${result.result.error}`], refreshed: false };
+  } catch (e) {
+    return { warnings: [`skill refresh error: ${String(e)}`], refreshed: false };
+  }
+}
 async function runUpdate(input) {
   const pkg2 = JSON.parse(
-    readFileSync4(new URL("../../package.json", import.meta.url), "utf8")
+    readFileSync6(new URL("../../package.json", import.meta.url), "utf8")
   );
   const currentVersion = pkg2.version;
   const tag = input.distTag ?? "beta";
+  const target = join23(input.home, ".claude", "skills");
   let latest;
   try {
     latest = execSync2(`npm view skillwiki@${tag} version`, {
@@ -2723,6 +3651,8 @@ async function runUpdate(input) {
         previousVersion: currentVersion,
         newVersion: null,
         wasAlreadyLatest: true,
+        version_warnings: [],
+        skills_refreshed: false,
         humanHint: `Already on latest ${tag}: v${currentVersion}`
       })
     };
@@ -2739,78 +3669,254 @@ async function runUpdate(input) {
     };
   }
   writeCache(input.home, { ...cache, updateAppliedAt: Date.now() });
+  const installResult = await refreshInstalledSkills(target);
+  const version_warnings = installResult.warnings;
+  const skills_refreshed = installResult.refreshed;
+  const hintLines = [
+    `Updated skillwiki ${currentVersion} \u2192 ${latest}`,
+    `skills refreshed: ${skills_refreshed}`
+  ];
+  if (version_warnings.length > 0) {
+    hintLines.push(`version warnings: ${version_warnings.length}`);
+    for (const w of version_warnings) hintLines.push(`  ${w}`);
+  }
   return {
     exitCode: ExitCode.OK,
     result: ok({
       previousVersion: currentVersion,
       newVersion: latest,
       wasAlreadyLatest: false,
-      humanHint: `Updated skillwiki ${currentVersion} \u2192 ${latest}`
+      version_warnings,
+      skills_refreshed,
+      humanHint: hintLines.join("\n")
     })
   };
 }
 
-// src/commands/transcripts.ts
-import { readdir as readdir4, stat as stat6, readFile as readFile15 } from "fs/promises";
-import { join as join19 } from "path";
-async function runTranscripts(input) {
-  const dir = join19(input.vault, "raw", "transcripts");
-  let entries;
-  try {
-    entries = await readdir4(dir, { withFileTypes: true });
-  } catch {
-    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: { ok: false, error: "VAULT_PATH_INVALID", detail: `raw/transcripts/ not found: ${dir}` } };
-  }
-  const transcripts = [];
-  for (const entry of entries) {
-    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-    const filePath = join19(dir, entry.name);
-    const content = await readFile15(filePath, "utf8");
-    const fm = extractFrontmatter(content);
-    if (!fm.ok) continue;
-    const ingested = typeof fm.data.ingested === "string" ? fm.data.ingested : "";
-    if (input.since && ingested && ingested < input.since) continue;
-    const s = await stat6(filePath);
-    transcripts.push({
-      file: `raw/transcripts/${entry.name}`,
-      ingested,
-      size: s.size
-    });
-  }
-  const hint = transcripts.length > 0 ? transcripts.map((t) => `${t.file} (ingested: ${t.ingested || "unknown"}, ${t.size}B)`).join("\n") : "no transcript files found";
-  return { exitCode: ExitCode.OK, result: ok({ transcripts, humanHint: hint }) };
-}
-
-// src/commands/project-index.ts
-import { readdir as readdir5, readFile as readFile16, writeFile as writeFile11, mkdir as mkdir6 } from "fs/promises";
-import { join as join20, dirname as dirname8 } from "path";
-var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
-async function runProjectIndex(input) {
-  const slug = input.slug;
-  const projectDir = join20(input.vault, "projects", slug);
-  try {
-    await readdir5(projectDir);
-  } catch {
+// src/commands/self-update.ts
+import { execSync as execSync3 } from "child_process";
+import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
+import { join as join24 } from "path";
+var DEFAULT_SOURCE_ROOT_SUFFIX = "/Desktop/code/llm-wiki";
+async function runSelfUpdate(input) {
+  const currentVersion = JSON.parse(
+    readFileSync7(new URL("../../package.json", import.meta.url), "utf8")
+  ).version;
+  const sourceRoot = input.sourceRoot ?? `${input.home}${DEFAULT_SOURCE_ROOT_SUFFIX}`;
+  const localPkgPath = join24(sourceRoot, "packages", "cli", "package.json");
+  const hasLocalSource = existsSync6(localPkgPath);
+  if (input.check) {
+    let availableVersion = null;
+    let source;
+    if (hasLocalSource) {
+      source = "local";
+      try {
+        availableVersion = JSON.parse(readFileSync7(localPkgPath, "utf8")).version ?? null;
+      } catch {
+        availableVersion = null;
+      }
+    } else {
+      source = "npm";
+      try {
+        availableVersion = execSync3("npm view skillwiki@beta version", {
+          encoding: "utf8",
+          timeout: 15e3
+        }).trim();
+      } catch (e) {
+        return {
+          exitCode: ExitCode.INTERNAL_ERROR,
+          result: err("PREFLIGHT_FAILED", { message: `Failed to query npm registry: ${String(e)}` })
+        };
+      }
+    }
+    const updateAvailable = availableVersion !== null && availableVersion !== currentVersion;
+    const hint = updateAvailable ? `Update available: ${currentVersion} \u2192 ${availableVersion} (${source})` : `Already up to date: v${currentVersion} (${source})`;
     return {
-      exitCode: ExitCode.PROJECT_NOT_FOUND,
+      exitCode: ExitCode.OK,
+      result: ok({
+        source,
+        currentVersion,
+        availableVersion,
+        updateAvailable,
+        humanHint: hint
+      })
+    };
+  }
+  if (hasLocalSource) {
+    try {
+      execSync3("npm run build -w packages/cli", {
+        cwd: sourceRoot,
+        stdio: "pipe",
+        timeout: 6e4
+      });
+    } catch (e) {
+      return {
+        exitCode: ExitCode.INTERNAL_ERROR,
+        result: err("BUILD_FAILED", { message: `Build failed: ${String(e)}` })
+      };
+    }
+    try {
+      execSync3("npm link ./packages/cli", {
+        cwd: sourceRoot,
+        stdio: "pipe",
+        timeout: 3e4
+      });
+    } catch (e) {
+      return {
+        exitCode: ExitCode.INTERNAL_ERROR,
+        result: err("LINK_FAILED", { message: `npm link failed: ${String(e)}` })
+      };
+    }
+    const newVersion = (() => {
+      try {
+        return JSON.parse(readFileSync7(localPkgPath, "utf8")).version ?? "unknown";
+      } catch {
+        return "unknown";
+      }
+    })();
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        source: "local",
+        currentVersion,
+        availableVersion: newVersion,
+        updateAvailable: newVersion !== currentVersion,
+        newVersion,
+        humanHint: `Built and linked from local source: v${newVersion}`
+      })
+    };
+  }
+  let latestVersion;
+  try {
+    latestVersion = execSync3("npm view skillwiki@beta version", {
+      encoding: "utf8",
+      timeout: 15e3
+    }).trim();
+  } catch (e) {
+    return {
+      exitCode: ExitCode.INTERNAL_ERROR,
+      result: err("PREFLIGHT_FAILED", { message: `Failed to query npm registry: ${String(e)}` })
+    };
+  }
+  if (latestVersion === currentVersion) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        source: "npm",
+        currentVersion,
+        availableVersion: latestVersion,
+        updateAvailable: false,
+        humanHint: `Already on latest beta: v${currentVersion}`
+      })
+    };
+  }
+  try {
+    execSync3("npm install -g skillwiki@beta", {
+      stdio: "pipe",
+      timeout: 6e4
+    });
+  } catch (e) {
+    return {
+      exitCode: ExitCode.INTERNAL_ERROR,
+      result: err("INSTALL_FAILED", { message: `npm install failed: ${String(e)}` })
+    };
+  }
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      source: "npm",
+      currentVersion,
+      availableVersion: latestVersion,
+      updateAvailable: true,
+      newVersion: latestVersion,
+      humanHint: `Updated skillwiki ${currentVersion} \u2192 ${latestVersion} via npm@beta`
+    })
+  };
+}
+
+// src/commands/transcripts.ts
+import { readdir as readdir5, stat as stat6, readFile as readFile16 } from "fs/promises";
+import { join as join25 } from "path";
+async function runTranscripts(input) {
+  const dir = join25(input.vault, "raw", "transcripts");
+  let entries;
+  try {
+    entries = await readdir5(dir, { withFileTypes: true });
+  } catch {
+    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: { ok: false, error: "VAULT_PATH_INVALID", detail: `raw/transcripts/ not found: ${dir}` } };
+  }
+  const transcripts = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const filePath = join25(dir, entry.name);
+    const content = await readFile16(filePath, "utf8");
+    const fm = extractFrontmatter(content);
+    if (!fm.ok) continue;
+    const ingested = typeof fm.data.ingested === "string" ? fm.data.ingested : "";
+    if (input.since && ingested && ingested < input.since) continue;
+    const s = await stat6(filePath);
+    transcripts.push({
+      file: `raw/transcripts/${entry.name}`,
+      ingested,
+      size: s.size
+    });
+  }
+  const hint = transcripts.length > 0 ? transcripts.map((t) => `${t.file} (ingested: ${t.ingested || "unknown"}, ${t.size}B)`).join("\n") : "no transcript files found";
+  return { exitCode: ExitCode.OK, result: ok({ transcripts, humanHint: hint }) };
+}
+
+// src/commands/project-index.ts
+import { readdir as readdir6, readFile as readFile17, writeFile as writeFile12, mkdir as mkdir8 } from "fs/promises";
+import { join as join26, dirname as dirname10 } from "path";
+var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
+async function runProjectIndex(input) {
+  const slug = input.slug;
+  const projectDir = join26(input.vault, "projects", slug);
+  try {
+    await readdir6(projectDir);
+  } catch {
+    return {
+      exitCode: ExitCode.PROJECT_NOT_FOUND,
       result: err("PROJECT_NOT_FOUND", { slug, path: projectDir })
     };
   }
   const wikilinkPattern = `[[${slug}]]`;
   const entries = [];
+  const compoundDir = join26(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 = join26(compoundDir, entry.name);
+      let text;
+      try {
+        text = await readFile17(filePath, "utf8");
+      } catch {
+        continue;
+      }
+      const fm = extractFrontmatter(text);
+      if (!fm.ok) continue;
+      entries.push({
+        page: `projects/${slug}/compound/${entry.name}`,
+        type: typeof fm.data.type === "string" ? fm.data.type : "compound",
+        title: typeof fm.data.title === "string" ? fm.data.title : entry.name.replace(/\.md$/, "")
+      });
+    }
+  } catch {
+  }
   for (const dir of LAYER2_DIRS) {
     let files;
     try {
-      files = await readdir5(join20(input.vault, dir), { withFileTypes: true });
+      files = await readdir6(join26(input.vault, dir), { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of files) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-      const filePath = join20(input.vault, dir, entry.name);
+      const filePath = join26(input.vault, dir, entry.name);
       let text;
       try {
-        text = await readFile16(filePath, "utf8");
+        text = await readFile17(filePath, "utf8");
       } catch {
         continue;
       }
@@ -2820,117 +3926,1860 @@ async function runProjectIndex(input) {
       if (!Array.isArray(pp) || !pp.some((p) => String(p) === wikilinkPattern)) continue;
       entries.push({
         page: `${dir}/${entry.name}`,
-        type: fm.data.type ?? dir.slice(0, -1),
-        // singularize dir name
-        title: fm.data.title ?? entry.name.replace(/\.md$/, "")
+        type: typeof fm.data.type === "string" ? fm.data.type : dir.slice(0, -1),
+        title: typeof fm.data.title === "string" ? fm.data.title : entry.name.replace(/\.md$/, "")
       });
     }
   }
-  const typeOrder = { entity: 0, concept: 1, comparison: 2, query: 3, summary: 4, meta: 5 };
-  entries.sort((a, b) => {
-    const ta = typeOrder[a.type] ?? 99;
-    const tb = typeOrder[b.type] ?? 99;
-    return ta !== tb ? ta - tb : a.title.localeCompare(b.title);
-  });
-  const indexPath = join20(projectDir, "knowledge.md");
-  let existing = false;
-  let stale = false;
+  const typeOrder = { entity: 0, concept: 1, comparison: 2, query: 3, summary: 4, meta: 5, pattern: 6, gotcha: 7, lesson: 8, antipattern: 9, compound: 10 };
+  entries.sort((a, b) => {
+    const ta = typeOrder[a.type] ?? 99;
+    const tb = typeOrder[b.type] ?? 99;
+    return ta !== tb ? ta - tb : a.title.localeCompare(b.title);
+  });
+  const indexPath = join26(projectDir, "knowledge.md");
+  let existing = false;
+  let stale = false;
+  try {
+    const existingText = await readFile17(indexPath, "utf8");
+    existing = true;
+    const existingEntries = existingText.split("\n").filter((l) => l.startsWith("- [["));
+    const existingPages = new Set(existingEntries.map((l) => {
+      const m = l.match(/\[\[([^\]]+)\]\]/);
+      return m ? m[1] : "";
+    }));
+    const currentPages = new Set(entries.map((e) => e.page.replace(/\.md$/, "")));
+    stale = existingPages.size !== currentPages.size || [...currentPages].some((p) => !existingPages.has(p));
+  } catch {
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const grouped = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const group = e.type;
+    if (!grouped.has(group)) grouped.set(group, []);
+    grouped.get(group).push(e);
+  }
+  let body = `# Knowledge Index: ${slug}
+
+Autogenerated by \`skillwiki project-index\` on ${today}.
+
+`;
+  for (const [type, items] of grouped) {
+    body += `## ${type}
+
+`;
+    for (const item of items) {
+      const pageRef = item.page.replace(/\.md$/, "");
+      body += `- [[${pageRef}]] \u2014 ${item.title}
+`;
+    }
+    body += "\n";
+  }
+  if (entries.length === 0) {
+    body += `No Layer 2 pages reference \`[[${slug}]]\` in provenance_projects.
+`;
+  }
+  if (input.apply) {
+    try {
+      await mkdir8(dirname10(indexPath), { recursive: true });
+      await writeFile12(indexPath, body, "utf8");
+    } catch (e) {
+      return {
+        exitCode: ExitCode.WRITE_FAILED,
+        result: err("WRITE_FAILED", { file: indexPath, message: String(e) })
+      };
+    }
+  }
+  const action = input.apply ? `written ${entries.length} entries to ${indexPath}` : `${entries.length} entries found (use --apply to write)`;
+  const staleHint = stale ? " (STALE \u2014 existing index outdated)" : existing ? " (up to date)" : "";
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      slug,
+      entries,
+      existing,
+      stale,
+      index_path: `projects/${slug}/knowledge.md`,
+      humanHint: `project: ${slug}
+entries: ${entries.length}${staleHint}
+${action}
+
+${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e.title}`).join("\n")}`
+    })
+  };
+}
+
+// src/commands/compound.ts
+import { writeFile as writeFile13, mkdir as mkdir9, readdir as readdir7, unlink as unlink2 } from "fs/promises";
+import { join as join27 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { readFile as readFile18 } 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,
+  friction: /^-\s+\*?\*?Friction:?\*?\*?\s*(.+)$/m,
+  generalize: /^-\s+\*?\*?Generalize\?:?\*?\*?\s*(.+)$/m
+};
+function slugify(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+$/g, "");
+}
+function inferType(improve, friction) {
+  if (/\bshould\b/i.test(improve)) return "pattern";
+  if (/\bbug\b|\berror\b/i.test(friction)) return "gotcha";
+  return "lesson";
+}
+function extractTags(generalize) {
+  const tags = [];
+  const parenRe = /\(([^)]+)\)/g;
+  let match;
+  while ((match = parenRe.exec(generalize)) !== null) {
+    const words = match[1].trim().split(/\s+/);
+    for (const w of words) {
+      const cleaned = w.toLowerCase().replace(/[^a-z0-9-]/g, "").trim();
+      if (cleaned.length > 0) tags.push(cleaned);
+    }
+  }
+  const appliesRe = /applies to any\s+(.+?)(?:\.|,|$)/i;
+  const appliesMatch = generalize.match(appliesRe);
+  if (appliesMatch) {
+    const words = appliesMatch[1].trim().split(/\s+/);
+    for (const w of words) {
+      const cleaned = w.toLowerCase().replace(/[^a-z0-9-]/g, "").trim();
+      if (cleaned.length > 0) tags.push(cleaned);
+    }
+  }
+  if (tags.length === 0) {
+    tags.push("dev-loop");
+  }
+  return [...new Set(tags)];
+}
+function parseRationale(generalize) {
+  const yesMatch = generalize.match(/^yes[,:]\s*(.+)$/i);
+  if (yesMatch) return yesMatch[1].trim();
+  if (/^yes$/i.test(generalize.trim())) return "";
+  return generalize.trim();
+}
+function parseRetroEntries(logText) {
+  const entries = [];
+  const lines = logText.split("\n");
+  let currentDate = "";
+  let currentCycleName = "";
+  let currentBlock = [];
+  let foundHeading = false;
+  for (const line of lines) {
+    const headingMatch = line.match(RETRO_HEADING_RE);
+    if (headingMatch) {
+      if (foundHeading && currentBlock.length > 0) {
+        const entry = extractRetroFields(currentDate, currentCycleName, currentBlock);
+        if (entry) entries.push(entry);
+      }
+      currentDate = headingMatch[1];
+      currentCycleName = headingMatch[3];
+      currentBlock = [];
+      foundHeading = true;
+      continue;
+    }
+    if (foundHeading && /^## /.test(line)) {
+      const entry = extractRetroFields(currentDate, currentCycleName, currentBlock);
+      if (entry) entries.push(entry);
+      foundHeading = false;
+      currentBlock = [];
+      continue;
+    }
+    if (foundHeading) {
+      currentBlock.push(line);
+    }
+  }
+  if (foundHeading && currentBlock.length > 0) {
+    const entry = extractRetroFields(currentDate, currentCycleName, currentBlock);
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+function extractRetroFields(date, cycleName, block) {
+  const text = block.join("\n");
+  const improveMatch = text.match(FIELD_RE.improve);
+  const frictionMatch = text.match(FIELD_RE.friction);
+  const generalizeMatch = text.match(FIELD_RE.generalize);
+  if (!generalizeMatch) return null;
+  return {
+    date,
+    cycleName,
+    improve: improveMatch?.[1]?.trim() ?? "",
+    friction: frictionMatch?.[1]?.trim() ?? "",
+    generalize: generalizeMatch[1].trim()
+  };
+}
+async function runCompound(input) {
+  const logPath = join27(input.vault, "log.md");
+  let logText;
+  try {
+    logText = await readFile18(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 = join27(input.vault, "projects", input.project, "compound");
+  for (const entry of entries) {
+    const generalizeValue = entry.generalize.trim();
+    if (!/^yes/i.test(generalizeValue)) {
+      skipped.push(entry.date);
+      continue;
+    }
+    const slug = slugify(entry.cycleName);
+    const compoundPath = join27(compoundDir, `${slug}.md`);
+    if (existsSync7(compoundPath)) {
+      skipped.push(entry.date);
+      continue;
+    }
+    const type = inferType(entry.improve, entry.friction);
+    const rationale = parseRationale(generalizeValue);
+    const tags = extractTags(generalizeValue);
+    const tagsYaml = tags.map((t) => t).join(", ");
+    const title = entry.cycleName;
+    const typeLabel = type.charAt(0).toUpperCase() + type.slice(1);
+    const frontmatter = [
+      "---",
+      `title: ${title}`,
+      `created: ${entry.date}`,
+      `updated: ${entry.date}`,
+      `type: ${type}`,
+      `tags: [${tagsYaml}]`,
+      `confidence: medium`,
+      `project: "[[${input.project}]]"`,
+      `work_items: []`,
+      "---"
+    ].join("\n");
+    const body = [
+      `## ${typeLabel}`,
+      "",
+      entry.improve,
+      "",
+      "## Evidence",
+      "",
+      entry.friction,
+      "",
+      "## Source",
+      "",
+      `Retro from ${entry.date} | ${entry.cycleName}. Generalize rationale: ${rationale}`,
+      ""
+    ].join("\n");
+    const content = frontmatter + "\n" + body;
+    if (!input.dryRun) {
+      if (!existsSync7(compoundDir)) {
+        await mkdir9(compoundDir, { recursive: true });
+      }
+      await writeFile13(compoundPath, content, "utf8");
+    }
+    promoted.push(`${slug}.md`);
+  }
+  const exitCode = promoted.length > 0 ? ExitCode.COMPOUND_PROMOTED : ExitCode.OK;
+  const hintLines = [`scanned: ${entries.length}`];
+  if (promoted.length > 0) hintLines.push(`promoted: ${promoted.length}`);
+  if (skipped.length > 0) hintLines.push(`skipped (Generalize?: no): ${skipped.length}`);
+  return {
+    exitCode,
+    result: ok({
+      scanned: entries.length,
+      promoted,
+      skipped,
+      humanHint: hintLines.join("\n")
+    })
+  };
+}
+async function runCompoundDelete(input) {
+  const projectDir = join27(input.vault, "projects", input.project);
+  if (!existsSync7(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 = join27(projectDir, "compound", `${entryName}.md`);
+  if (!existsSync7(compoundPath)) {
+    return {
+      exitCode: ExitCode.FILE_NOT_FOUND,
+      result: err("FILE_NOT_FOUND", { path: compoundPath })
+    };
+  }
+  try {
+    await unlink2(compoundPath);
+  } catch (e) {
+    return {
+      exitCode: ExitCode.WRITE_FAILED,
+      result: err("WRITE_FAILED", { file: compoundPath, message: String(e) })
+    };
+  }
+  const indexResult = await runProjectIndex({ vault: input.vault, slug: input.project, apply: true });
+  if (!indexResult.result.ok) {
+    return {
+      exitCode: indexResult.exitCode,
+      result: err("INDEX_REGEN_FAILED", { detail: indexResult.result })
+    };
+  }
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      deleted: compoundPath,
+      project: input.project,
+      humanHint: `deleted: ${entryName}.md
+project: ${input.project}
+knowledge.md regenerated`
+    })
+  };
+}
+async function runCompoundList(input) {
+  const compoundDir = join27(input.vault, "projects", input.project, "compound");
+  if (!existsSync7(compoundDir)) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        project: input.project,
+        entries: [],
+        humanHint: `project: ${input.project}
+entries: 0
+no compound directory found`
+      })
+    };
+  }
+  let dirents;
+  try {
+    dirents = await readdir7(compoundDir, { withFileTypes: true });
+  } catch {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        project: input.project,
+        entries: [],
+        humanHint: `project: ${input.project}
+entries: 0
+could not read compound directory`
+      })
+    };
+  }
+  const entries = [];
+  for (const dirent of dirents) {
+    if (!dirent.isFile() || !dirent.name.endsWith(".md")) continue;
+    const filePath = join27(compoundDir, dirent.name);
+    let text;
+    try {
+      text = await readFile18(filePath, "utf8");
+    } catch {
+      continue;
+    }
+    const fm = extractFrontmatter(text);
+    if (!fm.ok) continue;
+    const tags = Array.isArray(fm.data.tags) ? fm.data.tags.map((t) => String(t)) : typeof fm.data.tags === "string" ? fm.data.tags.split(",").map((s) => s.trim()) : [];
+    entries.push({
+      file: dirent.name,
+      title: typeof fm.data.title === "string" ? fm.data.title : dirent.name.replace(/\.md$/, ""),
+      type: typeof fm.data.type === "string" ? fm.data.type : "lesson",
+      created: typeof fm.data.created === "string" ? fm.data.created : "",
+      tags
+    });
+  }
+  const hint = entries.length > 0 ? [`project: ${input.project}`, `entries: ${entries.length}`, "", ...entries.map((e) => `  ${e.file}: ${e.title} (${e.type}, created: ${e.created || "unknown"}, tags: ${e.tags.join(", ") || "none"})`)].join("\n") : `project: ${input.project}
+entries: 0
+no compound entries found`;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      project: input.project,
+      entries,
+      humanHint: hint
+    })
+  };
+}
+
+// src/commands/observe.ts
+import { mkdir as mkdir10, writeFile as writeFile14 } from "fs/promises";
+import { existsSync as existsSync8, statSync as statSync2 } from "fs";
+import { join as join28 } from "path";
+import { createHash as createHash3 } from "crypto";
+var ALLOWED_KINDS = /* @__PURE__ */ new Set(["note", "bug", "task", "idea", "session-log"]);
+function slugify2(text) {
+  const words = text.trim().split(/\s+/).slice(0, 6).join("-").toLowerCase().replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return words || "untitled";
+}
+async function runObserve(input) {
+  const kind = input.kind || "note";
+  if (!ALLOWED_KINDS.has(kind)) {
+    return {
+      exitCode: ExitCode.SCHEME_REJECTED,
+      result: err("SCHEME_REJECTED", {
+        message: `Invalid kind "${kind}". Allowed: ${[...ALLOWED_KINDS].join(", ")}`
+      })
+    };
+  }
+  if (!input.text || input.text.trim().length === 0) {
+    return {
+      exitCode: ExitCode.SCHEME_REJECTED,
+      result: err("SCHEME_REJECTED", { message: "Text must not be empty" })
+    };
+  }
+  if (!existsSync8(input.vault) || !statSync2(input.vault).isDirectory()) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("VAULT_PATH_INVALID", { path: input.vault })
+    };
+  }
+  const transcriptsDir = join28(input.vault, "raw", "transcripts");
+  try {
+    await mkdir10(transcriptsDir, { recursive: true });
+  } catch {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("VAULT_PATH_INVALID", { path: transcriptsDir })
+    };
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const slug = slugify2(input.text);
+  const fileName = `${today}-observation-${slug}.md`;
+  const filePath = join28(transcriptsDir, fileName);
+  const body = `
+${input.text.trim()}
+`;
+  const sha256 = createHash3("sha256").update(Buffer.from(body, "utf8")).digest("hex");
+  const frontmatterLines = [
+    "---",
+    "source_url:",
+    `ingested: ${today}`,
+    `sha256: ${sha256}`,
+    `kind: ${kind}`
+  ];
+  if (input.project) {
+    frontmatterLines.push(`project: "[[${input.project}]]"`);
+  }
+  frontmatterLines.push("---");
+  const content = frontmatterLines.join("\n") + body;
+  try {
+    await writeFile14(filePath, content, "utf8");
+  } catch (e) {
+    return {
+      exitCode: ExitCode.WRITE_FAILED,
+      result: err("WRITE_FAILED", { path: filePath, message: String(e) })
+    };
+  }
+  appendLastOp(input.vault, {
+    operation: "observe",
+    summary: `created observation: ${slug}`,
+    files: [`raw/transcripts/${fileName}`],
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const relPath = `raw/transcripts/${fileName}`;
+  const humanHint = `created ${relPath} (${sha256.slice(0, 12)}...)`;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({ path: relPath, sha256, humanHint })
+  };
+}
+
+// src/commands/ingest.ts
+import { readFile as readFile19, writeFile as writeFile15, mkdir as mkdir11 } from "fs/promises";
+import { join as join29 } from "path";
+import { createHash as createHash4 } from "crypto";
+var ALLOWED_TYPES = /* @__PURE__ */ new Set(["entity", "concept", "comparison", "query"]);
+var TYPE_DIR = {
+  entity: "entities",
+  concept: "concepts",
+  comparison: "comparisons",
+  query: "queries"
+};
+var ALLOWED_PROVENANCE = /* @__PURE__ */ new Set(["research", "project"]);
+function slugify3(text) {
+  return text.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 80) || "untitled";
+}
+function isUrl(source) {
+  try {
+    const u = new URL(source);
+    return u.protocol === "https:" || u.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+function todayIso() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+function buildRawContent(sourceUrl, ingested, sha256, body) {
+  const lines = [
+    "---",
+    sourceUrl !== null ? `source_url: "${sourceUrl}"` : "source_url:",
+    `ingested: ${ingested}`,
+    `sha256: ${sha256}`,
+    `ingested_by: wiki-ingest`,
+    "---",
+    "",
+    body
+  ];
+  return lines.join("\n");
+}
+function buildTypedContent(title, ingested, type, tags, rawRelPath, provenance) {
+  const aliases = [];
+  const sourcesYaml = `  - ${rawRelPath}`;
+  const tagsYaml = tags.length > 0 ? tags.map((t) => `  - ${t}`).join("\n") : "  []";
+  const fm = {
+    title,
+    aliases,
+    created: ingested,
+    updated: ingested,
+    type,
+    tags,
+    sources: [rawRelPath],
+    confidence: "medium"
+  };
+  if (provenance) {
+    fm.provenance = provenance;
+  }
+  const fmLines = ["---"];
+  fmLines.push(`title: "${title}"`);
+  if (aliases.length > 0) {
+    fmLines.push("aliases:");
+    for (const a of aliases) fmLines.push(`  - ${a}`);
+  } else {
+    fmLines.push("aliases: []");
+  }
+  fmLines.push(`created: ${ingested}`);
+  fmLines.push(`updated: ${ingested}`);
+  fmLines.push(`type: ${type}`);
+  fmLines.push("tags:");
+  fmLines.push(tagsYaml);
+  fmLines.push("sources:");
+  fmLines.push(sourcesYaml);
+  fmLines.push("confidence: medium");
+  if (provenance) {
+    fmLines.push(`provenance: ${provenance}`);
+  }
+  fmLines.push("---");
+  fmLines.push("");
+  const body = [
+    `# ${title}`,
+    "",
+    "## Overview",
+    "",
+    "## See also",
+    "",
+    "## Sources",
+    "",
+    `^[${rawRelPath}]`,
+    ""
+  ].join("\n");
+  return fmLines.join("\n") + body;
+}
+async function runIngest(input) {
+  if (!input.source || input.source.trim().length === 0) {
+    return {
+      exitCode: ExitCode.SCHEME_REJECTED,
+      result: err("SCHEME_REJECTED", { message: "source is required" })
+    };
+  }
+  if (!input.vault || input.vault.trim().length === 0) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("VAULT_PATH_INVALID", { message: "vault path is required" })
+    };
+  }
+  if (!input.type || !ALLOWED_TYPES.has(input.type)) {
+    return {
+      exitCode: ExitCode.SCHEME_REJECTED,
+      result: err("SCHEME_REJECTED", {
+        message: `Invalid type "${input.type}". Allowed: ${[...ALLOWED_TYPES].join(", ")}`
+      })
+    };
+  }
+  if (!input.title || input.title.trim().length === 0) {
+    return {
+      exitCode: ExitCode.SCHEME_REJECTED,
+      result: err("SCHEME_REJECTED", { message: "title is required" })
+    };
+  }
+  if (input.provenance && !ALLOWED_PROVENANCE.has(input.provenance)) {
+    return {
+      exitCode: ExitCode.SCHEME_REJECTED,
+      result: err("SCHEME_REJECTED", {
+        message: `Invalid provenance "${input.provenance}". Allowed: ${[...ALLOWED_PROVENANCE].join(", ")}`
+      })
+    };
+  }
+  let sourceContent;
+  let sourceUrl = null;
+  if (isUrl(input.source)) {
+    sourceUrl = input.source;
+    const guardResult = runFetchGuardSync({ url: input.source });
+    if (!guardResult.result.ok) {
+      return {
+        exitCode: ExitCode.INGEST_VALIDATION_FAILED,
+        result: err("INGEST_VALIDATION_FAILED", {
+          message: "source URL blocked by fetch-guard",
+          guardError: guardResult.result.error,
+          guardDetail: guardResult.result.detail
+        })
+      };
+    }
+    const fetchResult = await controlledFetch(input.source, {
+      timeoutMs: 15e3,
+      maxBytes: 1024 * 1024,
+      // 1 MB
+      maxRedirects: 5
+    });
+    if (!fetchResult.ok) {
+      return {
+        exitCode: ExitCode.INGEST_VALIDATION_FAILED,
+        result: err("INGEST_VALIDATION_FAILED", {
+          message: "failed to fetch source URL",
+          fetchError: fetchResult.error,
+          fetchDetail: fetchResult.detail
+        })
+      };
+    }
+    sourceContent = fetchResult.data.body;
+  } else {
+    try {
+      sourceContent = await readFile19(input.source, "utf8");
+    } catch {
+      return {
+        exitCode: ExitCode.FILE_NOT_FOUND,
+        result: err("FILE_NOT_FOUND", { path: input.source })
+      };
+    }
+  }
+  const sha256 = createHash4("sha256").update(Buffer.from(sourceContent, "utf8")).digest("hex");
+  const today = todayIso();
+  const slug = slugify3(input.title);
+  const tags = input.tags && input.tags.length > 0 ? input.tags : [];
+  const rawRelPath = `raw/articles/${slug}.md`;
+  const typedDir = TYPE_DIR[input.type] ?? `${input.type}s`;
+  const typedRelPath = `${typedDir}/${slug}.md`;
+  const rawAbsPath = join29(input.vault, rawRelPath);
+  const typedAbsPath = join29(input.vault, typedRelPath);
+  const rawContent = buildRawContent(sourceUrl, today, sha256, sourceContent);
+  const typedContent = buildTypedContent(
+    input.title,
+    today,
+    input.type,
+    tags,
+    rawRelPath,
+    input.provenance
+  );
+  if (input.dryRun) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        raw_path: rawRelPath,
+        typed_path: typedRelPath,
+        sha256,
+        dry_run: true,
+        humanHint: [
+          `DRY RUN \u2014 would create:`,
+          `  ${rawRelPath} (sha256: ${sha256.slice(0, 12)}...)`,
+          `  ${typedRelPath}`,
+          `  type: ${input.type}, tags: [${tags.join(", ")}]`,
+          input.provenance ? `  provenance: ${input.provenance}` : ""
+        ].filter(Boolean).join("\n")
+      })
+    };
+  }
+  const typedFm = {
+    title: input.title,
+    aliases: [],
+    created: today,
+    updated: today,
+    type: input.type,
+    tags,
+    sources: [rawRelPath],
+    confidence: "medium",
+    ...input.provenance ? { provenance: input.provenance } : {}
+  };
+  const det = detectSchema(typedFm);
+  if (!det.schema) {
+    return {
+      exitCode: ExitCode.INGEST_VALIDATION_FAILED,
+      result: err("INGEST_VALIDATION_FAILED", {
+        message: "generated typed-knowledge page could not be detected as a valid schema"
+      })
+    };
+  }
+  const parsed = TypedKnowledgeSchema.safeParse(typedFm);
+  if (!parsed.success) {
+    const errors = parsed.error.issues.map((i) => ({
+      path: i.path.join("."),
+      message: i.message
+    }));
+    return {
+      exitCode: ExitCode.INGEST_VALIDATION_FAILED,
+      result: err("INGEST_VALIDATION_FAILED", {
+        message: "generated typed-knowledge page failed schema validation",
+        errors
+      })
+    };
+  }
+  try {
+    await mkdir11(join29(input.vault, "raw", "articles"), { recursive: true });
+    await writeFile15(rawAbsPath, rawContent, "utf8");
+  } catch (e) {
+    return {
+      exitCode: ExitCode.WRITE_FAILED,
+      result: err("WRITE_FAILED", { path: rawAbsPath, message: String(e) })
+    };
+  }
+  try {
+    await mkdir11(join29(input.vault, typedDir), { recursive: true });
+    await writeFile15(typedAbsPath, typedContent, "utf8");
+  } catch (e) {
+    return {
+      exitCode: ExitCode.WRITE_FAILED,
+      result: err("WRITE_FAILED", { path: typedAbsPath, message: String(e) })
+    };
+  }
+  const humanHint = [
+    `created:`,
+    `  ${rawRelPath} (sha256: ${sha256.slice(0, 12)}...)`,
+    `  ${typedRelPath}`
+  ].join("\n");
+  appendLastOp(input.vault, {
+    operation: "ingest",
+    summary: `added ${slug}`,
+    files: [rawRelPath, typedRelPath],
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      raw_path: rawRelPath,
+      typed_path: typedRelPath,
+      sha256,
+      dry_run: false,
+      humanHint
+    })
+  };
+}
+
+// src/commands/tag-sync.ts
+import { writeFile as writeFile16 } from "fs/promises";
+var ENUM_MIRRORS = {
+  provenance: ["research", "project", "mixed"],
+  confidence: ["high", "medium", "low"]
+};
+function toNestedTag(field, value) {
+  return `${field}/${value}`;
+}
+function expectedNestedTags(fm) {
+  const expected = /* @__PURE__ */ new Set();
+  for (const [field, allowedValues] of Object.entries(ENUM_MIRRORS)) {
+    const value = fm[field];
+    if (typeof value === "string" && allowedValues.includes(value)) {
+      expected.add(toNestedTag(field, value));
+    }
+  }
+  return expected;
+}
+function parseTagsFromYaml(rawFm) {
+  const inlineMatch = rawFm.match(/^tags:\s*\[([^\]]*)\]/m);
+  if (inlineMatch) {
+    return inlineMatch[1].split(",").map((t) => t.trim().replace(/^['"]|['"]$/g, "")).filter((t) => t.length > 0);
+  }
+  const lines = rawFm.split("\n");
+  const tagItems = [];
+  let inTags = false;
+  for (const line of lines) {
+    if (/^tags:\s*$/.test(line)) {
+      inTags = true;
+      continue;
+    }
+    if (inTags) {
+      if (/^\s+-\s+/.test(line) && !/^\s+-\s+\[\[/.test(line)) {
+        const value = line.replace(/^\s+-\s+/, "").trim().replace(/^['"]|['"]$/g, "");
+        if (value.length > 0) tagItems.push(value);
+      } else {
+        break;
+      }
+    }
+  }
+  return tagItems;
+}
+function rebuildTagsSection(rawFm, existingTags, toAdd) {
+  const allTags = [...existingTags, ...toAdd];
+  const tagsLine = `tags: [${allTags.join(", ")}]`;
+  if (/^tags:\s*\[/m.test(rawFm)) {
+    return rawFm.replace(/^tags:\s*\[[^\]]*\]/m, tagsLine);
+  }
+  const lines = rawFm.split("\n");
+  const out = [];
+  let inTags = false;
+  let tagsReplaced = false;
+  for (const line of lines) {
+    if (/^tags:\s*$/.test(line)) {
+      inTags = true;
+      if (!tagsReplaced) {
+        out.push(tagsLine);
+        tagsReplaced = true;
+      }
+      continue;
+    }
+    if (inTags) {
+      if (/^\s+-\s+/.test(line) && !/^\s+-\s+\[\[/.test(line)) {
+        continue;
+      } else {
+        inTags = false;
+      }
+    }
+    out.push(line);
+  }
+  if (!tagsReplaced) {
+    out.push(tagsLine);
+  }
+  return out.join("\n");
+}
+async function runTagSync(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const synced = [];
+  let unchanged = 0;
+  for (const page of scan.data.typedKnowledge) {
+    const text = await readPage(page);
+    const split = splitFrontmatter(text);
+    if (!split.ok) {
+      unchanged++;
+      continue;
+    }
+    const { rawFrontmatter, body } = split.data;
+    const fm = {};
+    for (const [field, allowedValues] of Object.entries(ENUM_MIRRORS)) {
+      for (const v of allowedValues) {
+        if (rawFrontmatter.includes(`${field}: ${v}`)) {
+          fm[field] = v;
+          break;
+        }
+      }
+    }
+    const expected = expectedNestedTags(fm);
+    if (expected.size === 0) {
+      unchanged++;
+      continue;
+    }
+    const existingTags = parseTagsFromYaml(rawFrontmatter);
+    const existingSet = new Set(existingTags);
+    const toAdd = [...expected].filter((t) => !existingSet.has(t));
+    if (toAdd.length === 0) {
+      unchanged++;
+      continue;
+    }
+    const newFm = rebuildTagsSection(rawFrontmatter, existingTags, toAdd);
+    const newText = `---
+${newFm}
+---
+${body}`;
+    if (!input.dryRun) {
+      await writeFile16(page.absPath, newText, "utf8");
+    }
+    synced.push(page.relPath);
+  }
+  if (!input.dryRun && synced.length > 0) {
+    appendLastOp(input.vault, {
+      operation: "tag-sync",
+      summary: `synced tags on ${synced.length} pages`,
+      files: synced,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  const exitCode = synced.length > 0 ? ExitCode.MIGRATION_APPLIED : ExitCode.OK;
+  const hintLines = [`scanned: ${synced.length + unchanged}`];
+  if (synced.length > 0) hintLines.push(`synced: ${synced.length}`);
+  if (unchanged > 0) hintLines.push(`unchanged: ${unchanged}`);
+  if (input.dryRun && synced.length > 0) hintLines.push("(dry run \u2014 no files written)");
+  return {
+    exitCode,
+    result: ok({
+      scanned: synced.length + unchanged,
+      synced,
+      unchanged,
+      humanHint: hintLines.join("\n")
+    })
+  };
+}
+
+// src/commands/sync.ts
+import { existsSync as existsSync9 } from "fs";
+import { join as join30 } from "path";
+function runSyncStatus(input) {
+  const vault = input.vault;
+  if (!existsSync9(join30(vault, ".git"))) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: ok({
+        is_git_repo: false,
+        dirty: 0,
+        ahead: 0,
+        behind: 0,
+        last_commit: "never",
+        status: "not_a_repo",
+        humanHint: "not a git repository"
+      })
+    };
+  }
+  const porcelain = git(vault, ["status", "--porcelain"]);
+  const dirty = porcelain ? porcelain.split("\n").filter((l) => l.trim().length > 0).length : 0;
+  const revOutput = git(vault, ["rev-list", "--left-right", "--count", "origin/HEAD...HEAD"]);
+  let ahead = 0;
+  let behind = 0;
+  if (revOutput) {
+    const parts = revOutput.split(/\s+/);
+    behind = parseInt(parts[0], 10) || 0;
+    ahead = parseInt(parts[1], 10) || 0;
+  }
+  const tsRaw = git(vault, ["log", "-1", "--format=%ct"]);
+  let last_commit;
+  if (tsRaw) {
+    const ts = parseInt(tsRaw, 10);
+    if (!isNaN(ts) && ts > 0) {
+      last_commit = new Date(ts * 1e3).toISOString();
+    } else {
+      last_commit = "never";
+    }
+  } else {
+    last_commit = "never";
+  }
+  let status;
+  if (dirty > 0) {
+    status = "dirty";
+  } else if (ahead > 0) {
+    status = "ahead";
+  } else if (behind > 0) {
+    status = "behind";
+  } else {
+    status = "clean";
+  }
+  const hintLines = [
+    `status: ${status}`,
+    `dirty: ${dirty}`,
+    `ahead: ${ahead}`,
+    `behind: ${behind}`,
+    `last_commit: ${last_commit}`
+  ];
+  const exitCode = status === "clean" ? ExitCode.OK : ExitCode.LINT_HAS_WARNINGS;
+  return {
+    exitCode,
+    result: ok({
+      is_git_repo: true,
+      dirty,
+      ahead,
+      behind,
+      last_commit,
+      status,
+      humanHint: hintLines.join("\n")
+    })
+  };
+}
+async function runSyncPush(input) {
+  const vault = input.vault;
+  if (!existsSync9(join30(vault, ".git"))) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("NOT_A_GIT_REPO", { path: vault })
+    };
+  }
+  const porcelain = git(vault, ["status", "--porcelain"]);
+  const dirtyFiles = porcelain ? porcelain.split("\n").filter((l) => l.trim().length > 0) : [];
+  if (dirtyFiles.length === 0) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        files_committed: 0,
+        commit_message: "",
+        pushed: false,
+        humanHint: "nothing to commit, working tree clean"
+      })
+    };
+  }
+  const lintResult = await runLint({ vault, days: 90, lines: 200, logThreshold: 500 });
+  if (lintResult.result.ok && lintResult.result.data.summary.errors > 0) {
+    return {
+      exitCode: ExitCode.LINT_HAS_ERRORS,
+      result: err("LINT_ERRORS_BLOCK_PUSH", {
+        errors: lintResult.result.data.summary.errors,
+        buckets: lintResult.result.data.by_severity.error
+      })
+    };
+  }
+  try {
+    gitStrict(vault, ["add", "-A"]);
+    try {
+      gitStrict(vault, ["reset", "HEAD", "--", ".skillwiki/last-op.json"]);
+    } catch {
+    }
+  } catch (e) {
+    return {
+      exitCode: ExitCode.SYNC_PUSH_FAILED,
+      result: err("GIT_ADD_FAILED", { message: String(e) })
+    };
+  }
+  const lastOps = readLastOp(vault);
+  let commitMessage;
+  if (lastOps.length > 0) {
+    commitMessage = lastOps.map((op) => `${op.operation}: ${op.summary} (${op.files.length} files)`).join("; ");
+  } else {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+    commitMessage = `sync: vault update ${timestamp}`;
+  }
+  try {
+    gitStrict(vault, ["commit", "-m", commitMessage]);
+  } catch (e) {
+    return {
+      exitCode: ExitCode.SYNC_PUSH_FAILED,
+      result: err("GIT_COMMIT_FAILED", { message: String(e) })
+    };
+  }
+  clearLastOp(vault);
+  let pushed = false;
+  try {
+    gitStrict(vault, ["push", "origin", "HEAD"]);
+    pushed = true;
+  } catch (e) {
+    return {
+      exitCode: ExitCode.SYNC_PUSH_FAILED,
+      result: ok({
+        files_committed: dirtyFiles.length,
+        commit_message: commitMessage,
+        pushed: false,
+        humanHint: `committed ${dirtyFiles.length} file(s) but push failed: ${String(e)}`
+      })
+    };
+  }
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      files_committed: dirtyFiles.length,
+      commit_message: commitMessage,
+      pushed,
+      humanHint: `committed and pushed ${dirtyFiles.length} file(s)`
+    })
+  };
+}
+async function runSyncPull(input) {
+  const vault = input.vault;
+  if (!existsSync9(join30(vault, ".git"))) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("NOT_A_GIT_REPO", { path: vault })
+    };
+  }
+  let fetched = false;
+  try {
+    gitStrict(vault, ["fetch", "origin"]);
+    fetched = true;
+  } catch (e) {
+    return {
+      exitCode: ExitCode.SYNC_PULL_FAILED,
+      result: err("GIT_FETCH_FAILED", { message: String(e) })
+    };
+  }
+  let pulled = false;
+  let conflicts = 0;
+  let filesUpdated = 0;
+  try {
+    const pullOutput = gitStrict(vault, ["pull", "--rebase", "origin", "HEAD"]);
+    pulled = true;
+    const fileMatch = pullOutput.match(/(\d+) file[s]? changed/);
+    if (fileMatch) filesUpdated = parseInt(fileMatch[1], 10);
+  } catch (e) {
+    const errString = String(e);
+    if (errString.includes("conflict")) {
+      const porcelain = git(vault, ["diff", "--name-only", "--diff-filter=U"]);
+      conflicts = porcelain ? porcelain.split("\n").filter((l) => l.trim().length > 0).length : 0;
+      return {
+        exitCode: ExitCode.SYNC_PULL_FAILED,
+        result: ok({
+          fetched,
+          pulled: false,
+          files_updated: 0,
+          conflicts,
+          lint_errors: 0,
+          lint_warnings: 0,
+          humanHint: `pull failed with ${conflicts} conflict(s) \u2014 resolve manually`
+        })
+      };
+    }
+    return {
+      exitCode: ExitCode.SYNC_PULL_FAILED,
+      result: err("GIT_PULL_FAILED", { message: errString })
+    };
+  }
+  let lintErrors = 0;
+  let lintWarnings = 0;
+  const lintResult = await runLint({ vault, days: 90, lines: 200, logThreshold: 500 });
+  if (lintResult.result.ok) {
+    lintErrors = lintResult.result.data.summary.errors;
+    lintWarnings = lintResult.result.data.summary.warnings;
+  }
+  const hintParts = [];
+  if (filesUpdated > 0) hintParts.push(`updated ${filesUpdated} file(s)`);
+  else hintParts.push("already up to date");
+  if (lintErrors > 0) hintParts.push(`${lintErrors} lint error(s)`);
+  if (lintWarnings > 0) hintParts.push(`${lintWarnings} lint warning(s)`);
+  const exitCode = lintErrors > 0 ? ExitCode.LINT_HAS_ERRORS : lintWarnings > 0 ? ExitCode.LINT_HAS_WARNINGS : ExitCode.OK;
+  return {
+    exitCode,
+    result: ok({
+      fetched,
+      pulled,
+      files_updated: filesUpdated,
+      conflicts,
+      lint_errors: lintErrors,
+      lint_warnings: lintWarnings,
+      humanHint: hintParts.join(", ")
+    })
+  };
+}
+
+// src/commands/backup.ts
+import { statSync as statSync3, readdirSync as readdirSync2, readFileSync as readFileSync8, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { join as join31, relative as relative3, dirname as dirname11 } from "path";
+import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
+
+// src/utils/s3-client.ts
+import { S3Client } from "@aws-sdk/client-s3";
+function createS3Client(config) {
+  const clientConfig = {
+    endpoint: config.endpoint,
+    region: config.region,
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey
+    },
+    forcePathStyle: true
+    // Required for SeaweedFS / MinIO
+  };
+  return new S3Client(clientConfig);
+}
+
+// src/commands/backup.ts
+var SKIP_DIRS = /* @__PURE__ */ new Set([".git", ".obsidian", "_archive", "node_modules", ".skillwiki"]);
+function* walkMarkdown(dir, base) {
+  for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const full = join31(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkMarkdown(full, base);
+    } else if (entry.name.endsWith(".md")) {
+      yield relative3(base, full).replace(/\\/g, "/");
+    }
+  }
+}
+async function runBackupSync(input) {
+  if (!input.accessKeyId || !input.secretAccessKey) {
+    return {
+      exitCode: ExitCode.BACKUP_SYNC_FAILED,
+      result: err("BACKUP_SYNC_FAILED", {
+        message: "Backup credentials not configured. Run: skillwiki config set BACKUP_ACCESS_KEY_ID <key>"
+      })
+    };
+  }
+  const client = createS3Client(input);
+  let uploaded = 0;
+  let skipped = 0;
+  let failed = 0;
+  const files = [...walkMarkdown(input.vault, input.vault)];
+  for (const relPath of files) {
+    const absPath = join31(input.vault, relPath);
+    const localStat = statSync3(absPath);
+    let needsUpload = true;
+    try {
+      const head = await client.send(new HeadObjectCommand({ Bucket: input.bucket, Key: relPath }));
+      if (head.LastModified && head.LastModified >= localStat.mtime) {
+        needsUpload = false;
+      }
+    } catch {
+    }
+    if (!needsUpload) {
+      skipped++;
+      continue;
+    }
+    if (input.dryRun) {
+      uploaded++;
+      continue;
+    }
+    try {
+      const body = readFileSync8(absPath);
+      await client.send(new PutObjectCommand({ Bucket: input.bucket, Key: relPath, Body: body }));
+      uploaded++;
+    } catch {
+      failed++;
+    }
+  }
+  let pruned = 0;
+  if (input.prune && !input.dryRun) {
+    try {
+      const localSet = new Set(files);
+      const list = await client.send(new ListObjectsV2Command({ Bucket: input.bucket }));
+      const toDelete = (list.Contents ?? []).filter((obj) => obj.Key && !localSet.has(obj.Key)).map((obj) => ({ Key: obj.Key }));
+      if (toDelete.length > 0) {
+        await client.send(new DeleteObjectsCommand({ Bucket: input.bucket, Delete: { Objects: toDelete } }));
+        pruned = toDelete.length;
+      }
+    } catch {
+    }
+  }
+  const hintParts = [];
+  if (input.dryRun) hintParts.push("DRY RUN \u2014");
+  hintParts.push(`scanned: ${files.length}, uploaded: ${uploaded}, skipped: ${skipped}`);
+  if (failed > 0) hintParts.push(`failed: ${failed}`);
+  if (pruned > 0) hintParts.push(`pruned: ${pruned}`);
+  return {
+    exitCode: failed > 0 ? ExitCode.BACKUP_SYNC_FAILED : ExitCode.OK,
+    result: ok({
+      scanned: files.length,
+      uploaded,
+      skipped,
+      failed,
+      pruned,
+      dry_run: input.dryRun ?? false,
+      humanHint: hintParts.join(", ")
+    })
+  };
+}
+async function runBackupRestore(input) {
+  if (!input.accessKeyId || !input.secretAccessKey) {
+    return {
+      exitCode: ExitCode.BACKUP_SYNC_FAILED,
+      result: err("BACKUP_SYNC_FAILED", {
+        message: "Backup credentials not configured. Run: skillwiki config set BACKUP_ACCESS_KEY_ID <key>"
+      })
+    };
+  }
+  const client = createS3Client(input);
+  const target = input.target ?? input.vault;
+  let downloaded = 0;
+  let skipped = 0;
+  let conflicts = 0;
+  try {
+    const list = await client.send(new ListObjectsV2Command({ Bucket: input.bucket }));
+    const objects = list.Contents ?? [];
+    for (const obj of objects) {
+      if (!obj.Key) continue;
+      const localPath = join31(target, obj.Key);
+      try {
+        const localStat = statSync3(localPath);
+        if (obj.LastModified && localStat.mtime > obj.LastModified) {
+          conflicts++;
+          continue;
+        }
+      } catch {
+      }
+      try {
+        const resp = await client.send(new GetObjectCommand({ Bucket: input.bucket, Key: obj.Key }));
+        const body = await resp.Body?.transformToByteArray();
+        if (body) {
+          mkdirSync3(dirname11(localPath), { recursive: true });
+          writeFileSync4(localPath, Buffer.from(body));
+          downloaded++;
+        }
+      } catch {
+        skipped++;
+      }
+    }
+  } catch (e) {
+    return {
+      exitCode: ExitCode.BACKUP_SYNC_FAILED,
+      result: err("BACKUP_SYNC_FAILED", { message: `Failed to list bucket: ${String(e)}` })
+    };
+  }
+  const hintParts = [`downloaded: ${downloaded}`];
+  if (skipped > 0) hintParts.push(`skipped: ${skipped}`);
+  if (conflicts > 0) hintParts.push(`conflicts: ${conflicts} (local is newer)`);
+  if (downloaded > 0) {
+    appendLastOp(target, {
+      operation: "backup-restore",
+      summary: `restored ${downloaded} files from S3`,
+      files: [],
+      // Don't enumerate potentially hundreds of files
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  return {
+    exitCode: conflicts > 0 ? ExitCode.BACKUP_RESTORE_CONFLICTS : ExitCode.OK,
+    result: ok({ downloaded, skipped, conflicts, humanHint: hintParts.join(", ") })
+  };
+}
+
+// src/commands/status.ts
+import { existsSync as existsSync10, statSync as statSync4 } from "fs";
+import { readFile as readFile20 } from "fs/promises";
+import { join as join32 } from "path";
+async function runStatus(input) {
+  if (!existsSync10(input.vault)) {
+    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
+  }
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) {
+    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  }
+  const typedCounts = { entities: 0, concepts: 0, comparisons: 0, queries: 0, meta: 0 };
+  for (const page of scan.data.typedKnowledge) {
+    const segment = page.relPath.split("/")[0];
+    if (segment in typedCounts) {
+      typedCounts[segment]++;
+    }
+  }
+  let rawArticles = 0;
+  let rawTranscripts = 0;
+  for (const page of scan.data.raw) {
+    const parts = page.relPath.split("/");
+    if (parts[1] === "transcripts") rawTranscripts++;
+    else rawArticles++;
+  }
+  const workItems = scan.data.workItems.length;
+  const compound = scan.data.compound.length;
+  let schemaVersion = "v1";
   try {
-    const existingText = await readFile16(indexPath, "utf8");
-    existing = true;
-    const existingEntries = existingText.split("\n").filter((l) => l.startsWith("- [["));
-    const existingPages = new Set(existingEntries.map((l) => {
-      const m = l.match(/\[\[([^\]]+)\]\]/);
-      return m ? m[1] : "";
-    }));
-    const currentPages = new Set(entries.map((e) => e.page.replace(/\.md$/, "")));
-    stale = existingPages.size !== currentPages.size || [...currentPages].some((p) => !existingPages.has(p));
+    const schemaContent = await readFile20(join32(input.vault, "SCHEMA.md"), "utf8");
+    const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
+    if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
   }
-  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  const grouped = /* @__PURE__ */ new Map();
-  for (const e of entries) {
-    const group = e.type;
-    if (!grouped.has(group)) grouped.set(group, []);
-    grouped.get(group).push(e);
+  const langResult = await resolveLang({ flag: void 0, envValue: input.langEnvValue, home: input.home });
+  const allPages = [
+    ...scan.data.typedKnowledge,
+    ...scan.data.raw,
+    ...scan.data.workItems,
+    ...scan.data.compound
+  ];
+  let lastModified = "";
+  let maxTime = 0;
+  for (const page of allPages) {
+    try {
+      const st = statSync4(page.absPath);
+      if (st.mtimeMs > maxTime) {
+        maxTime = st.mtimeMs;
+        lastModified = st.mtime.toISOString();
+      }
+    } catch {
+    }
   }
-  let body = `# Knowledge Index: ${slug}
+  const pageCounts = {
+    entities: typedCounts.entities,
+    concepts: typedCounts.concepts,
+    comparisons: typedCounts.comparisons,
+    queries: typedCounts.queries,
+    meta: typedCounts.meta,
+    raw_articles: rawArticles,
+    raw_transcripts: rawTranscripts,
+    work_items: workItems,
+    compound
+  };
+  const totalPages = Object.values(pageCounts).reduce((a, b) => a + b, 0);
+  const rawTotal = rawArticles + rawTranscripts;
+  const humanHint = [
+    `vault: ${input.vault}`,
+    `lang: ${langResult.value}`,
+    `total: ${totalPages} pages`,
+    `  entities: ${pageCounts.entities}  concepts: ${pageCounts.concepts}  comparisons: ${pageCounts.comparisons}  queries: ${pageCounts.queries}  meta: ${pageCounts.meta}`,
+    `  raw: ${rawTotal}  work_items: ${workItems}  compound: ${compound}`,
+    `last modified: ${lastModified.slice(0, 10)}`
+  ].join("\n");
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      vault_path: input.vault,
+      schema_version: schemaVersion,
+      lang: langResult.canonical,
+      page_counts: pageCounts,
+      total_pages: totalPages,
+      last_modified: lastModified,
+      humanHint
+    })
+  };
+}
 
-Autogenerated by \`skillwiki project-index\` on ${today}.
+// src/commands/seed.ts
+import { mkdir as mkdir12, writeFile as writeFile17, stat as stat7 } from "fs/promises";
+import { join as join33 } from "path";
+var TODAY = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+var EXAMPLE_PAGES = {
+  "entities/example-project.md": `---
+title: Example Project
+aliases: [example-project]
+created: ${TODAY}
+updated: ${TODAY}
+type: entity
+tags: [research]
+sources: []
+confidence: medium
+provenance: research
+---
 
-`;
-  for (const [type, items] of grouped) {
-    body += `## ${type}
+# Example Project
 
+## Overview
+
+This is a seed entity page demonstrating the typed-knowledge format. Replace it with a real entity from your research.
+
+## Key Facts
+
+- This vault was seeded on ${TODAY}
+- Entity pages describe people, organizations, products, or projects
+- Each page should cite sources from the \`raw/\` directory
+`,
+  "concepts/example-concept.md": `---
+title: Example Concept
+aliases: [example-concept]
+created: ${TODAY}
+updated: ${TODAY}
+type: concept
+tags: [concept]
+sources: []
+confidence: medium
+provenance: research
+---
+
+# Example Concept
+
+## Overview
+
+This is a seed concept page. Concept pages capture topics, patterns, and ideas that span multiple sources.
+
+## Related
+
+- [[example-project]]
+
+## Sources
+
+(Add source citations here after ingesting raw material with \`wiki-ingest\`)
+`
+};
+var EXAMPLE_RAW = `---
+source_url: https://example.com
+ingested: ${TODAY}
+sha256: 0000000000000000000000000000000000000000000000000000000000000000
+---
+
+# Example Source Article
+
+This is a placeholder raw source. Replace it with real content ingested via \`skillwiki hash\` and the wiki-ingest skill.
+
+Real sources are immutable after ingestion \u2014 never edit them.
 `;
-    for (const item of items) {
-      const pageRef = item.page.replace(/\.md$/, "");
-      body += `- [[${pageRef}]] \u2014 ${item.title}
-`;
+async function runSeed(input) {
+  try {
+    await stat7(join33(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 = join33(input.vault, relPath);
+    try {
+      await stat7(absPath);
+      skipped.push(relPath);
+    } catch {
+      await mkdir12(join33(absPath, ".."), { recursive: true });
+      await writeFile17(absPath, content, "utf8");
+      created.push(relPath);
     }
-    body += "\n";
   }
-  if (entries.length === 0) {
-    body += `No Layer 2 pages reference \`[[${slug}]]\` in provenance_projects.
-`;
+  const rawPath = join33(input.vault, "raw", "articles", "example-source.md");
+  try {
+    await stat7(rawPath);
+    skipped.push("raw/articles/example-source.md");
+  } catch {
+    await mkdir12(join33(rawPath, ".."), { recursive: true });
+    await writeFile17(rawPath, EXAMPLE_RAW, "utf8");
+    created.push("raw/articles/example-source.md");
+  }
+  if (created.length > 0) {
+    appendLastOp(input.vault, {
+      operation: "seed",
+      summary: `seeded ${created.length} example pages`,
+      files: created,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
   }
-  if (input.apply) {
-    try {
-      await mkdir6(dirname8(indexPath), { recursive: true });
-      await writeFile11(indexPath, body, "utf8");
-    } catch (e) {
-      return {
-        exitCode: ExitCode.WRITE_FAILED,
-        result: err("WRITE_FAILED", { file: indexPath, message: String(e) })
-      };
+  const hintLines = [`seeded: ${created.length}`, `skipped (already exist): ${skipped.length}`];
+  if (created.length > 0) {
+    hintLines.push("next steps: ingest real sources with wiki-ingest, then cite them in concept/entity pages");
+  }
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({ created, skipped, humanHint: hintLines.join("\n") })
+  };
+}
+
+// src/commands/canvas.ts
+import { readFile as readFile21, writeFile as writeFile18 } from "fs/promises";
+import { existsSync as existsSync11 } from "fs";
+import { join as join34 } from "path";
+var NODE_WIDTH = 240;
+var NODE_HEIGHT = 60;
+var COLUMN_SPACING = 400;
+var ROW_SPACING = 80;
+var TYPE_COLUMNS = {
+  entities: 0,
+  concepts: 1,
+  comparisons: 2,
+  queries: 3,
+  meta: 3
+};
+var TYPE_COLORS = {
+  entities: "1",
+  // red
+  concepts: "4",
+  // green
+  comparisons: "2",
+  // orange
+  queries: "5",
+  // cyan
+  meta: "6"
+  // purple
+};
+var DEFAULT_COLOR = "3";
+var DEFAULT_COLUMN = 2;
+function inferNodeType(relPath) {
+  const segment = relPath.split("/")[0] ?? "";
+  return TYPE_COLUMNS[segment] !== void 0 ? segment : "";
+}
+function getColumnForType(nodeType) {
+  return TYPE_COLUMNS[nodeType] ?? DEFAULT_COLUMN;
+}
+function getColorForType(nodeType) {
+  return TYPE_COLORS[nodeType] ?? DEFAULT_COLOR;
+}
+function buildCanvasNodes(paths) {
+  const columnY = {};
+  const nodes = [];
+  for (const relPath of paths) {
+    const nodeType = inferNodeType(relPath);
+    const col = getColumnForType(nodeType);
+    const y = columnY[col] ?? 0;
+    columnY[col] = y + ROW_SPACING;
+    nodes.push({
+      id: relPath,
+      type: "file",
+      file: relPath,
+      x: col * COLUMN_SPACING,
+      y,
+      width: NODE_WIDTH,
+      height: NODE_HEIGHT,
+      color: getColorForType(nodeType)
+    });
+  }
+  return nodes;
+}
+function buildCanvasEdges(adjacency) {
+  const edges = [];
+  let edgeIndex = 0;
+  const seen = /* @__PURE__ */ new Set();
+  for (const [source, targets] of Object.entries(adjacency)) {
+    for (const target of targets) {
+      const key = `${source}->${target}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({
+        id: `edge-${edgeIndex++}`,
+        fromNode: source,
+        toNode: target,
+        fromSide: "right",
+        toSide: "left"
+      });
     }
   }
-  const action = input.apply ? `written ${entries.length} entries to ${indexPath}` : `${entries.length} entries found (use --apply to write)`;
-  const staleHint = stale ? " (STALE \u2014 existing index outdated)" : existing ? " (up to date)" : "";
+  return edges;
+}
+async function runCanvasGenerate(input) {
+  const graphPath = input.graphPath ?? join34(input.vault, ".skillwiki", "graph.json");
+  if (!existsSync11(graphPath)) {
+    return {
+      exitCode: ExitCode.FILE_NOT_FOUND,
+      result: err("FILE_NOT_FOUND", {
+        path: graphPath,
+        hint: "Run `skillwiki graph build` first to generate graph.json"
+      })
+    };
+  }
+  let raw;
+  try {
+    raw = await readFile21(graphPath, "utf8");
+  } catch (e) {
+    return {
+      exitCode: ExitCode.FILE_NOT_FOUND,
+      result: err("FILE_NOT_FOUND", { path: graphPath, message: String(e) })
+    };
+  }
+  let graph;
+  try {
+    graph = JSON.parse(raw);
+  } catch {
+    return {
+      exitCode: ExitCode.SCHEMA_NOT_DETECTED,
+      result: err("SCHEMA_NOT_DETECTED", { path: graphPath, reason: "Invalid JSON in graph.json" })
+    };
+  }
+  if (!graph.adjacency || typeof graph.adjacency !== "object") {
+    return {
+      exitCode: ExitCode.SCHEMA_NOT_DETECTED,
+      result: err("SCHEMA_NOT_DETECTED", { path: graphPath, reason: "graph.json missing adjacency field" })
+    };
+  }
+  const paths = Object.keys(graph.adjacency);
+  const nodes = buildCanvasNodes(paths);
+  const edges = buildCanvasEdges(graph.adjacency);
+  const canvas = { nodes, edges };
+  const outPath = join34(input.vault, "vault-graph.canvas");
+  try {
+    await writeFile18(outPath, JSON.stringify(canvas, null, 2));
+  } catch (e) {
+    return {
+      exitCode: ExitCode.WRITE_FAILED,
+      result: err("WRITE_FAILED", { message: String(e), path: outPath })
+    };
+  }
   return {
     exitCode: ExitCode.OK,
     result: ok({
-      slug,
-      entries,
-      existing,
-      stale,
-      index_path: `projects/${slug}/knowledge.md`,
-      humanHint: `project: ${slug}
-entries: ${entries.length}${staleHint}
-${action}
-
-${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e.title}`).join("\n")}`
+      out_path: outPath,
+      node_count: nodes.length,
+      edge_count: edges.length,
+      humanHint: `nodes: ${nodes.length}, edges: ${edges.length}
+written: ${outPath}`
     })
   };
 }
 
+// src/commands/query.ts
+import { readFile as readFile22, stat as stat8 } from "fs/promises";
+import { join as join35 } from "path";
+var W_KEYWORD = 2;
+var W_SOURCE_OVERLAP = 4;
+var W_WIKILINK = 3;
+var W_ADAMIC_ADAR = 1.5;
+var W_TYPE_AFFINITY = 1;
+var NON_SEED_FACTOR = 0.4;
+var CONCEPT_INDICATORS = /* @__PURE__ */ new Set([
+  "what",
+  "how",
+  "why",
+  "concept",
+  "idea",
+  "pattern",
+  "principle",
+  "theory",
+  "approach",
+  "method",
+  "framework",
+  "model",
+  "definition"
+]);
+async function runQuery(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const limit = input.limit ?? 10;
+  const queryTerms = tokenize(input.text);
+  if (queryTerms.length === 0) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({ results: [], humanHint: "no query terms" })
+    };
+  }
+  const graph = await loadOrBuildGraph(input.vault);
+  const pages = [];
+  for (const p of scan.data.typedKnowledge) {
+    const text = await readPage(p);
+    const fm = extractFrontmatter(text);
+    if (!fm.ok) continue;
+    const title = String(fm.data.title ?? "");
+    const type = String(fm.data.type ?? "");
+    const tags = Array.isArray(fm.data.tags) ? fm.data.tags.map(String) : [];
+    const sources = Array.isArray(fm.data.sources) ? fm.data.sources.map(String) : [];
+    const split = splitFrontmatter(text);
+    const body = split.ok ? split.data.body : text;
+    const keywordScore = computeKeywordScore(queryTerms, title, tags, body);
+    pages.push({ relPath: p.relPath, title, type, tags, sources, keywordScore });
+  }
+  const seedPaths = new Set(
+    pages.filter((p) => p.keywordScore > 0).map((p) => p.relPath)
+  );
+  const results = pages.map((page) => {
+    const sourceOverlap = scoreSourceOverlap(page, pages, seedPaths);
+    const wikilink2 = scoreWikilink(page.relPath, seedPaths, graph);
+    const aa = scoreAdamicAdar(page.relPath, seedPaths, graph);
+    const typeAffinity = scoreTypeAffinity(page.type, queryTerms);
+    const isSeed = page.keywordScore > 0;
+    const structuralBoost = sourceOverlap * W_SOURCE_OVERLAP + wikilink2 * W_WIKILINK + aa * W_ADAMIC_ADAR;
+    const composite = isSeed ? page.keywordScore * W_KEYWORD + structuralBoost + typeAffinity * W_TYPE_AFFINITY : structuralBoost * NON_SEED_FACTOR + typeAffinity * W_TYPE_AFFINITY;
+    return {
+      path: page.relPath,
+      score: Math.round(composite * 1e3) / 1e3,
+      title: page.title,
+      type: page.type
+    };
+  }).filter((r) => r.score > 0).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, limit);
+  const humanHint = results.length === 0 ? "no matching pages found" : results.map((r) => `${r.path} (score: ${r.score})`).join("\n");
+  return { exitCode: ExitCode.OK, result: ok({ results, humanHint }) };
+}
+function scoreSourceOverlap(page, allPages, seedPaths) {
+  if (page.sources.length === 0) return 0;
+  let total = 0;
+  for (const seed of allPages) {
+    if (seed.relPath === page.relPath || !seedPaths.has(seed.relPath)) continue;
+    const shared = page.sources.filter((s) => seed.sources.includes(s)).length;
+    total += shared;
+  }
+  return total;
+}
+function scoreWikilink(candidatePath, seedPaths, graph) {
+  if (!graph) return 0;
+  let count = 0;
+  for (const seedPath of seedPaths) {
+    const neighbors = graph.adjacency[seedPath];
+    if (neighbors && neighbors.includes(candidatePath)) count++;
+  }
+  return count;
+}
+function scoreAdamicAdar(candidatePath, seedPaths, graph) {
+  if (!graph) return 0;
+  let maxScore = 0;
+  const aaForCandidate = graph.adamicAdar[candidatePath];
+  if (!aaForCandidate) return 0;
+  for (const seedPath of seedPaths) {
+    const val = aaForCandidate[seedPath];
+    if (val !== void 0 && val > maxScore) maxScore = val;
+  }
+  return maxScore;
+}
+function scoreTypeAffinity(pageType, queryTerms) {
+  const hasConceptIntent = queryTerms.some((t) => CONCEPT_INDICATORS.has(t));
+  if (hasConceptIntent && pageType === "concept") return 1;
+  if (!hasConceptIntent && pageType === "entity") return 0.5;
+  return 0;
+}
+function tokenize(text) {
+  return text.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+}
+function computeKeywordScore(terms, title, tags, body) {
+  const lowerTitle = title.toLowerCase();
+  const lowerTags = tags.map((t) => t.toLowerCase());
+  const lowerBody = body.toLowerCase();
+  let score = 0;
+  for (const term of terms) {
+    if (lowerTitle.includes(term)) score += 3;
+    if (lowerTags.some((t) => t.includes(term))) score += 2;
+    if (lowerBody.includes(term)) score += 1;
+  }
+  return score;
+}
+async function loadOrBuildGraph(vault) {
+  const graphPath = join35(vault, ".skillwiki", "graph.json");
+  let needsBuild = false;
+  try {
+    const fileStat = await stat8(graphPath);
+    const ageHours = (Date.now() - fileStat.mtimeMs) / (1e3 * 60 * 60);
+    if (ageHours > 24) needsBuild = true;
+  } catch {
+    needsBuild = true;
+  }
+  if (needsBuild) {
+    const buildResult = await runGraphBuild({ vault, out: graphPath });
+    if (buildResult.exitCode !== 0) return null;
+  }
+  try {
+    const raw = await readFile22(graphPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// src/utils/auto-commit.ts
+import { existsSync as existsSync12 } from "fs";
+import { join as join36 } 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 (!existsSync12(join36(vault, ".git"))) return;
+  const lastOps = readLastOp(vault);
+  if (lastOps.length === 0) return;
+  const porcelain = git(vault, ["status", "--porcelain"]);
+  if (!porcelain || porcelain.trim().length === 0) return;
+  const { gitStrict: gitStrict2 } = await import("./git-M4WGJ5G3.js");
+  try {
+    gitStrict2(vault, ["add", "-A"]);
+    try {
+      gitStrict2(vault, ["reset", "HEAD", "--", ".skillwiki/last-op.json"]);
+    } catch {
+    }
+  } catch (e) {
+    process.stderr.write(`auto-commit: git add failed: ${String(e)}
+`);
+    return;
+  }
+  const commitMessage = lastOps.map((op) => `${op.operation}: ${op.summary} (${op.files.length} files)`).join("; ");
+  try {
+    gitStrict2(vault, ["commit", "-m", commitMessage]);
+  } catch (e) {
+    process.stderr.write(`auto-commit: git commit failed: ${String(e)}
+`);
+    return;
+  }
+  clearLastOp(vault);
+}
+
 // src/cli.ts
-var pkg = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8"));
+var pkg = JSON.parse(readFileSync9(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
 program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
-function emit(r) {
+async function emit(r, vault) {
   if (program.opts().human) printHuman(r.result);
   else printJson(r.result);
+  if (vault) await postCommit(vault, r.exitCode);
   process.exit(r.exitCode);
 }
-program.command("hash <file>").action(async (file) => emit(await runHash({ file })));
-program.command("fetch-guard <url>").action(async (url) => emit(await runFetchGuard({ url })));
-program.command("validate <file>").action(async (file) => emit(await runValidate({ file })));
-program.command("graph").description("graph subcommands").command("build <vault>").option("--out <path>", "graph output path", ".skillwiki/graph.json").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => emit(await runGraphBuild({ vault, out: opts.out })));
-program.command("overlap <vault>").action(async (vault) => emit(await runOverlap({ vault })));
-program.command("orphans [vault]").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => emit(await runOrphans({
+program.command("hash <file>").description("compute SHA-256 hash of a vault page body").action(async (file) => emit(await runHash({ file })));
+program.command("fetch-guard <url>").description("check if a URL passes fetch guard rules and sanitize secrets").action(async (url) => emit(await runFetchGuard({ url })));
+program.command("validate <file>").description("validate vault page frontmatter against its detected schema").option("--apply", "auto-update vault index.md and log.md after successful validation", false).option("--vault <dir>", "vault root directory (required with --apply)").option("--wiki <name>", "wiki profile name").action(async (file, opts) => {
+  let vault;
+  if (opts.apply) {
+    const v = await resolveVaultArg(opts.vault, opts.wiki);
+    if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+    else vault = v.vault;
+  }
+  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 ?? join37(vault, ".skillwiki", "graph.json");
+  emit(await runGraphBuild({ vault, out }), vault);
+});
+var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
+canvasCmd.command("generate [vault]").description("generate .canvas from graph.json").option("--graph-path <path>", "explicit path to graph.json").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 runCanvasGenerate({ vault: v.vault, graphPath: opts.graphPath }), v.vault);
+});
+program.command("overlap [vault]").description("detect typed-knowledge pages that share the same raw sources").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 runOverlap({ vault: v.vault }), v.vault);
+});
+program.command("query <text> [vault]").description("score and rank vault pages by relevance to a query").option("--limit <n>", "max results to return", (s) => parseInt(s, 10), 10).option("--wiki <name>", "wiki profile name").action(async (text, vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runQuery({ text, vault: v.vault, limit: opts.limit }), v.vault);
+});
+program.command("orphans [vault]").description("find pages not referenced by any other page").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => emit(await runOrphans({
   vault,
   envValue: process.env.WIKI_PATH,
   home: process.env.HOME ?? "",
   wiki: opts.wiki
 })));
-program.command("audit <file>").action(async (file) => emit(await runAudit({ file })));
-program.command("install").option("--target <dir>", "target install directory", `${process.env.HOME ?? ""}/.claude/skills/`).option("--dry-run", "preview only", false).option("--skills-root <dir>", "source skills directory (defaults to packaged)").action(async (opts) => {
+program.command("audit <file>").description("audit citation markers and source provenance for a vault page").action(async (file) => emit(await runAudit({ file })));
+program.command("install").description("install skillwiki SKILL.md files into ~/.claude/skills/").option("--target <dir>", "target install directory", `${process.env.HOME ?? ""}/.claude/skills/`).option("--dry-run", "preview only", false).option("--skills-root <dir>", "source skills directory (defaults to packaged)").option("--symlink", "create symlinks instead of copies (dev mode \u2014 edits to source are immediately visible)", false).action(async (opts) => {
   const skillsRoot = opts.skillsRoot ?? new URL("../skills/", import.meta.url).pathname;
-  emit(await runInstall({ skillsRoot, target: opts.target, dryRun: !!opts.dryRun }));
+  emit(await runInstall({ skillsRoot, target: opts.target, dryRun: !!opts.dryRun, symlink: !!opts.symlink }));
 });
-program.command("path").option("--vault <dir>", "explicit vault override (runtime)").option("--target <dir>", "explicit target override (init-time)").option("--wiki <name>", "wiki profile name").option("--init-time", "use init-time chain instead of runtime", false).option("--explain", "include resolution chain in output", false).action(async (opts) => {
+program.command("path").description("show the resolved vault path").option("--vault <dir>", "explicit vault override (runtime)").option("--target <dir>", "explicit target override (init-time)").option("--wiki <name>", "wiki profile name").option("--init-time", "use init-time chain instead of runtime", false).option("--explain", "include resolution chain in output", false).action(async (opts) => {
   const initTime = !!opts.initTime;
   const flag = initTime ? opts.target : opts.vault;
   emit(await runPath({
@@ -2942,7 +5791,7 @@ program.command("path").option("--vault <dir>", "explicit vault override (runtim
     explain: !!opts.explain
   }));
 });
-program.command("lang").option("--lang <code>", "explicit language override").option("--explain", "include resolution chain in output", false).action(async (opts) => {
+program.command("lang").description("get or set the vault language").option("--lang <code>", "explicit language override").option("--explain", "include resolution chain in output", false).action(async (opts) => {
   emit(await runLang({
     flag: opts.lang,
     envValue: process.env.WIKI_LANG,
@@ -2950,7 +5799,7 @@ program.command("lang").option("--lang <code>", "explicit language override").op
     explain: !!opts.explain
   }));
 });
-program.command("init").option("--target <dir>", "explicit target directory").requiredOption("--domain <text>", "knowledge domain seed").option("--taxonomy <csv>", "comma-separated tag list").option("--lang <code>", "output language (BCP 47 or alias)").option("--force", "override existing target / env conflict", false).option("--no-env", "skip writing ~/.skillwiki/.env").option("--profile <name>", "write as named wiki profile instead of WIKI_PATH").action(async (opts) => {
+program.command("init").description("bootstrap a new vault with SCHEMA.md, index.md, log.md").option("--target <dir>", "explicit target directory").requiredOption("--domain <text>", "knowledge domain seed").option("--taxonomy <csv>", "comma-separated tag list").option("--lang <code>", "output language (BCP 47 or alias)").option("--force", "override existing target / env conflict", false).option("--no-env", "skip writing ~/.skillwiki/.env").option("--profile <name>", "write as named wiki profile instead of WIKI_PATH").action(async (opts) => {
   const templates = new URL("../templates/", import.meta.url).pathname;
   const taxonomy = typeof opts.taxonomy === "string" ? opts.taxonomy.split(",").map((s) => s.trim()).filter((s) => s.length > 0) : void 0;
   emit(await runInit({
@@ -2981,37 +5830,47 @@ async function resolveVaultArg(arg, wiki) {
   }
   return { ok: true, vault: r.data.path };
 }
-program.command("links [vault]").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("links [vault]").description("check wikilink integrity across the 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 });
+  else emit(await runLinks({ vault: v.vault }), v.vault);
+});
+program.command("tag-audit [vault]").description("audit tag taxonomy consistency").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 runTagAudit({ vault: v.vault }), v.vault);
+});
+program.command("index-check [vault]").description("verify index.md entries match actual vault pages").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 runLinks({ vault: v.vault }));
+  else emit(await runIndexCheck({ vault: v.vault }), v.vault);
 });
-program.command("tag-audit [vault]").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("index-link-format [vault]").description("check index.md for markdown links that should be wikilinks").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 runTagAudit({ vault: v.vault }));
+  else emit(await runIndexLinkFormat({ vault: v.vault }), v.vault);
 });
-program.command("index-check [vault]").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("topic-map-check [vault]").description("check whether a topic map page is recommended based on page count").option("--threshold <n>", "page count threshold", (s) => parseInt(s, 10), 200).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 runIndexCheck({ vault: v.vault }));
+  else emit(await runTopicMapCheck({ vault: v.vault, threshold: opts.threshold }), v.vault);
 });
-program.command("stale [vault]").option("--days <n>", "staleness threshold in days", (s) => parseInt(s, 10), 90).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("--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 }));
+  else emit(await runStale({ vault: v.vault, days: opts.days, archive: !!opts.archive }), v.vault);
 });
-program.command("pagesize [vault]").option("--lines <n>", "max body lines", (s) => parseInt(s, 10), 200).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("pagesize [vault]").description("report page sizes and flag oversized pages").option("--lines <n>", "max body lines", (s) => parseInt(s, 10), 200).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 runPagesize({ vault: v.vault, lines: opts.lines }));
+  else emit(await runPagesize({ vault: v.vault, lines: opts.lines }), v.vault);
 });
-program.command("log-rotate [vault]").option("--threshold <n>", "entry count threshold", (s) => parseInt(s, 10), 500).option("--apply", "actually rotate", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("log-rotate [vault]").description("rotate or trim the vault log file").option("--threshold <n>", "entry count threshold", (s) => parseInt(s, 10), 500).option("--apply", "actually rotate", 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 });
-  else emit(await runLogRotate({ vault: v.vault, threshold: opts.threshold, apply: !!opts.apply }));
+  else emit(await runLogRotate({ vault: v.vault, threshold: opts.threshold, apply: !!opts.apply }), v.vault);
 });
-program.command("lint [vault]").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("--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({
@@ -3021,7 +5880,7 @@ program.command("lint [vault]").option("--days <n>", "stale threshold", (s) => p
     lines: opts.lines,
     logThreshold: opts.logThreshold,
     fix: opts.fix ?? false
-  }));
+  }), v.vault);
 });
 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 ?? "" })));
@@ -3035,47 +5894,159 @@ program.command("doctor").description("diagnose skillwiki setup issues").action(
   currentVersion: pkg.version,
   cwd: process.cwd()
 })));
+program.command("status [vault]").description("output vault diagnostics").option("--human", "render terminal-readable output instead of JSON").option("--json", "output as JSON (default)").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 runStatus({
+    vault: v.vault,
+    home: process.env.HOME ?? "",
+    langEnvValue: process.env.WIKI_LANG
+  }), v.vault);
+});
 program.command("archive <page> [vault]").description("archive a typed-knowledge or raw page").option("--wiki <name>", "wiki profile name").action(async (page, vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runArchive({ vault: v.vault, page }));
+  else emit(await runArchive({ vault: v.vault, page }), v.vault);
 });
 program.command("drift [vault]").description("detect content drift in raw sources").option("--apply", "update sha256 in drifted sources").option("--new <date>", "list raw files ingested on/after this date (YYYY-MM-DD)").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 runDrift({ vault: v.vault, apply: opts.apply, newSince: opts.new }));
+  else emit(await runDrift({ vault: v.vault, apply: opts.apply, newSince: opts.new }), v.vault);
 });
 program.command("dedup [vault]").description("detect duplicate raw sources by sha256").option("--apply", "rewire citations and remove duplicate raw files", 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 });
-  else emit(await runDedup({ vault: v.vault, apply: opts.apply }));
+  else emit(await runDedup({ vault: v.vault, apply: opts.apply }), v.vault);
 });
 program.command("migrate-citations [vault]").description("migrate ^[raw/...] markers to paragraph-end citations").option("--dry-run", "preview changes without writing", 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 });
-  else emit(await runMigrateCitations({ vault: v.vault, dryRun: !!opts.dryRun }));
+  else emit(await runMigrateCitations({ vault: v.vault, dryRun: !!opts.dryRun }), v.vault);
 });
 program.command("frontmatter-fix [vault]").description("fix common frontmatter issues on typed-knowledge pages").option("--dry-run", "preview changes without writing", 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 });
-  else emit(await runFrontmatterFix({ vault: v.vault, dryRun: !!opts.dryRun }));
+  else emit(await runFrontmatterFix({ vault: v.vault, dryRun: !!opts.dryRun }), v.vault);
 });
 program.command("update").description("update skillwiki CLI to the latest version").option("--tag <tag>", "npm dist-tag", "beta").action(async (opts) => emit(await runUpdate({
   home: process.env.HOME ?? "",
   distTag: opts.tag
 })));
+program.command("self-update").description("update skillwiki CLI from local source or npm@beta").option("--check", "check for updates without installing", false).action(async (opts) => emit(await runSelfUpdate({
+  home: process.env.HOME ?? "",
+  check: !!opts.check
+})));
 program.command("transcripts [vault]").description("list transcript files in raw/transcripts/").option("--since <date>", "only files ingested on or after this date (YYYY-MM-DD)").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 runTranscripts({ vault: v.vault, since: opts.since }));
+  else emit(await runTranscripts({ vault: v.vault, since: opts.since }), v.vault);
 });
 program.command("project-index <slug> [vault]").description("generate a knowledge index for a project workspace").option("--apply", "write knowledge.md to the project directory", false).option("--wiki <name>", "wiki profile name").action(async (slug, vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runProjectIndex({ vault: v.vault, slug, apply: !!opts.apply }));
+  else emit(await runProjectIndex({ vault: v.vault, slug, apply: !!opts.apply }), v.vault);
+});
+var compoundCmd = program.command("compound").description("manage project compound entries");
+compoundCmd.command("promote [vault]").description("promote retros with Generalize?: yes to compound entries").requiredOption("--project <slug>", "project slug (e.g., llm-wiki)").option("--dry-run", "preview promotions without writing files", 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 });
+  else emit(await runCompound({ vault: v.vault, project: opts.project, dryRun: !!opts.dryRun }), v.vault);
+});
+compoundCmd.command("list [vault]").description("list compound entries for a project").requiredOption("--project <slug>", "project slug (e.g., llm-wiki)").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 runCompoundList({ vault: v.vault, project: opts.project }));
 });
+compoundCmd.command("delete <entry> [vault]").description("delete a compound entry and regenerate knowledge index").requiredOption("--project <slug>", "project slug (e.g., llm-wiki)").option("--wiki <name>", "wiki profile name").action(async (entry, vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runCompoundDelete({ vault: v.vault, project: opts.project, entry }), v.vault);
+});
+program.command("tag-sync [vault]").description("mirror frontmatter enum values to nested Obsidian tags").option("--dry-run", "preview changes without writing", 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 });
+  else emit(await runTagSync({ vault: v.vault, dryRun: !!opts.dryRun }), v.vault);
+});
+var syncCmd = program.command("sync").description("manage vault sync");
+syncCmd.command("status [vault]").description("check vault git sync status").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(runSyncStatus({ vault: v.vault }));
+});
+syncCmd.command("push [vault]").description("lint, commit, and push vault changes to remote").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 runSyncPush({ vault: v.vault }));
+});
+syncCmd.command("pull [vault]").description("pull remote vault changes and lint").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 runSyncPull({ vault: v.vault }), v.vault);
+});
+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 });
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+  const dotenv = await parseDotenvFile(configPath(home));
+  emit(await runBackupSync({
+    vault: v.vault,
+    bucket: opts.bucket ?? dotenv["BACKUP_BUCKET"] ?? "",
+    endpoint: opts.endpoint ?? dotenv["BACKUP_ENDPOINT"] ?? "",
+    region: opts.region ?? dotenv["BACKUP_REGION"] ?? "us-east-1",
+    accessKeyId: dotenv["BACKUP_ACCESS_KEY_ID"] ?? "",
+    secretAccessKey: dotenv["BACKUP_SECRET_ACCESS_KEY"] ?? "",
+    dryRun: opts.dryRun,
+    prune: opts.prune
+  }), v.vault);
+});
+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 });
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+  const dotenv = await parseDotenvFile(configPath(home));
+  emit(await runBackupRestore({
+    vault: v.vault,
+    bucket: opts.bucket ?? dotenv["BACKUP_BUCKET"] ?? "",
+    endpoint: opts.endpoint ?? dotenv["BACKUP_ENDPOINT"] ?? "",
+    region: opts.region ?? dotenv["BACKUP_REGION"] ?? "us-east-1",
+    accessKeyId: dotenv["BACKUP_ACCESS_KEY_ID"] ?? "",
+    secretAccessKey: dotenv["BACKUP_SECRET_ACCESS_KEY"] ?? "",
+    target: opts.target
+  }), v.vault);
+});
+program.command("seed [vault]").description("populate a vault with example content").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 runSeed({ vault: v.vault }), v.vault);
+});
+program.command("observe [vault]").description("create a raw transcript observation entry").requiredOption("--text <text>", "observation text").option("--kind <kind>", "observation kind (note|bug|task|idea|session-log)", "note").option("--project <slug>", "associated project slug").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 runObserve({
+    vault: v.vault,
+    text: opts.text,
+    kind: opts.kind,
+    project: opts.project
+  }), v.vault);
+});
+program.command("ingest <source>").description("ingest a source URL or local file into the vault").requiredOption("--vault <path>", "vault root directory").requiredOption("--type <type>", "typed-knowledge type (entity|concept|comparison|query)").requiredOption("--title <title>", "page title").option("--tags <csv>", "comma-separated tags").option("--provenance <provenance>", "provenance (research|project)").option("--dry-run", "preview without writing files", false).action(async (source, opts) => {
+  const tags = typeof opts.tags === "string" ? opts.tags.split(",").map((s) => s.trim()).filter((s) => s.length > 0) : [];
+  emit(await runIngest({
+    source,
+    vault: opts.vault,
+    type: opts.type,
+    title: opts.title,
+    tags,
+    provenance: opts.provenance,
+    dryRun: !!opts.dryRun
+  }), opts.vault);
+});
+for (const w of getDeprecatedWarnings(process.env.HOME ?? "")) {
+  process.stderr.write(w + "\n");
+}
 triggerAutoUpdate(process.env.HOME ?? "", pkg.version);
 program.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
-  process.exit(1);
+  process.exit(ExitCode.INTERNAL_ERROR);
 });