skillwiki 0.2.0-beta.2 → 0.2.0-beta.20

package/dist/cli.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
+import {
+  semverGt
+} from "./chunk-XM5IYZX7.js";
 
 // src/cli.ts
+import { readFileSync as readFileSync4 } from "fs";
 import { Command } from "commander";
 
 // src/utils/output.ts
@@ -9,9 +13,14 @@ function printJson(r) {
 }
 function printHuman(r) {
   if (r.ok) {
-    process.stdout.write(`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" : ""}`);
@@ -53,7 +62,16 @@ var ExitCode = {
   LINT_HAS_WARNINGS: 22,
   LINT_HAS_ERRORS: 23,
   ENV_WRITE_CONFLICT: 24,
-  NO_VAULT_CONFIGURED: 25
+  NO_VAULT_CONFIGURED: 25,
+  INVALID_CONFIG_KEY: 26,
+  CONFIG_WRITE_FAILED: 27,
+  DOCTOR_HAS_WARNINGS: 28,
+  DOCTOR_HAS_ERRORS: 29,
+  ARCHIVE_TARGET_NOT_FOUND: 30,
+  ARCHIVE_ALREADY_ARCHIVED: 31,
+  DRIFT_DETECTED: 32,
+  RAW_DEDUP_DETECTED: 33,
+  MIGRATION_APPLIED: 34
 };
 
 // ../shared/src/json-output.ts
@@ -93,10 +111,10 @@ var TypedKnowledgeSchema = z.object({
 });
 var sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
 var RawSourceSchema = z.object({
-  title: z.string().min(1),
-  source_url: z.string().url().nullable(),
+  title: z.string().min(1).optional(),
+  source_url: z.string().nullable(),
   ingested: isoDate,
-  ingested_by: z.enum(["wiki-ingest", "proj-work", "manual"]),
+  ingested_by: z.enum(["wiki-ingest", "proj-work", "manual"]).optional(),
   sha256: sha256Hex,
   project: wikilink.optional(),
   work_item: wikilink.optional(),
@@ -231,7 +249,7 @@ async function runHash(input) {
   const sha256 = createHash("sha256").update(bodyBytes).digest("hex");
   return {
     exitCode: ExitCode.OK,
-    result: ok({ path: input.file, sha256, byte_count: bodyBytes.byteLength })
+    result: ok({ path: input.file, sha256, byte_count: bodyBytes.byteLength, humanHint: sha256 })
   };
 }
 
@@ -261,7 +279,7 @@ function runFetchGuardSync(input) {
       result: err("HOST_BLOCKED", { sanitized_url: sanitized, host: u.hostname })
     };
   }
-  return { exitCode: ExitCode.OK, result: ok({ allowed: true, sanitized_url: sanitized }) };
+  return { exitCode: ExitCode.OK, result: ok({ allowed: true, sanitized_url: sanitized, humanHint: `ALLOWED: ${sanitized}` }) };
 }
 function sanitizeUrl(u) {
   const clone = new URL(u.toString());
@@ -301,17 +319,18 @@ 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: [] }) };
+    return { exitCode: ExitCode.SCHEMA_NOT_DETECTED, result: ok({ schema: null, valid: false, errors: [], 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 })
+      result: ok({ schema: det.schema, valid: false, errors, 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: [] }) };
+  return { exitCode: ExitCode.OK, result: ok({ schema: det.schema, valid: true, errors: [], humanHint: `VALID (${det.schema})` }) };
 }
 
 // src/commands/graph.ts
@@ -397,7 +416,8 @@ async function runGraphBuild(input) {
   }
   return {
     exitCode: ExitCode.OK,
-    result: ok({ out_path: input.out, node_count: scan.data.typedKnowledge.length, edge_count })
+    result: ok({ out_path: input.out, node_count: scan.data.typedKnowledge.length, edge_count, humanHint: `nodes: ${scan.data.typedKnowledge.length}, edges: ${edge_count}
+written: ${input.out}` })
   };
 }
 function computeAdamicAdar(adj) {
@@ -472,22 +492,19 @@ async function runOverlap(input) {
       }
     return { id, members, score };
   });
-  return { exitCode: ExitCode.OK, result: ok({ clusters }) };
+  const humanHint = clusters.length === 0 ? "no overlap clusters found" : clusters.map((c) => `cluster (${c.members.length} pages, score ${c.score}): ${c.members.join(", ")}`).join("\n");
+  return { exitCode: ExitCode.OK, result: ok({ clusters, humanHint }) };
 }
 
 // src/utils/wiki-path.ts
 import { join as join2 } from "path";
 
 // src/utils/dotenv.ts
-import { readFile as readFile4 } from "fs/promises";
-var WHITELIST = /* @__PURE__ */ new Set(["WIKI_PATH", "WIKI_LANG"]);
-async function parseDotenvFile(path) {
-  let text;
-  try {
-    text = await readFile4(path, "utf8");
-  } catch {
-    return {};
-  }
+import { readFile as readFile4, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname2 } from "path";
+var CONFIG_KEYS = ["WIKI_PATH", "WIKI_LANG"];
+var _whitelist = new Set(CONFIG_KEYS);
+function parseDotenvText(text) {
   const out = {};
   for (const rawLine of text.split(/\r?\n/)) {
     const line = rawLine.trim();
@@ -496,12 +513,65 @@ async function parseDotenvFile(path) {
     if (eq <= 0) continue;
     const key = line.slice(0, eq).trim();
     const value = line.slice(eq + 1).trim();
-    if (!WHITELIST.has(key)) continue;
+    if (!_whitelist.has(key)) continue;
     if (value.length === 0) continue;
     out[key] = value;
   }
   return out;
 }
+async function parseDotenvFile(path) {
+  let text;
+  try {
+    text = await readFile4(path, "utf8");
+  } catch {
+    return {};
+  }
+  return parseDotenvText(text);
+}
+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");
+}
+function freshLines(entries) {
+  const out = [];
+  for (const [key, value] of Object.entries(entries)) {
+    if (value !== void 0) out.push(`${key}=${value}`);
+  }
+  return out;
+}
+function updateLines(originalContent, entries) {
+  let rawLines = originalContent.split(/\r?\n/);
+  if (rawLines.length > 0 && rawLines[rawLines.length - 1] === "") {
+    rawLines = rawLines.slice(0, -1);
+  }
+  const keysToWrite = new Set(Object.keys(entries));
+  const out = [];
+  for (const line of rawLines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) {
+      out.push(line);
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      out.push(line);
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    if (keysToWrite.has(key)) {
+      out.push(`${key}=${entries[key]}`);
+      keysToWrite.delete(key);
+    } else {
+      out.push(line);
+    }
+  }
+  for (const key of keysToWrite) {
+    const value = entries[key];
+    if (value !== void 0) out.push(`${key}=${value}`);
+  }
+  return out;
+}
 
 // src/utils/wiki-path.ts
 async function resolveInitTimePath(input) {
@@ -569,7 +639,10 @@ async function runOrphans(input) {
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
   const slugToPath = {};
   for (const p of scan.data.typedKnowledge) {
-    slugToPath[p.relPath.replace(/\.md$/, "").split("/").pop()] = p.relPath;
+    const rel = p.relPath.replace(/\.md$/, "");
+    slugToPath[rel] = p.relPath;
+    const filename = rel.split("/").pop();
+    if (!(filename in slugToPath)) slugToPath[filename] = p.relPath;
   }
   const adj = {};
   for (const p of scan.data.typedKnowledge) adj[p.relPath] = /* @__PURE__ */ new Set();
@@ -578,7 +651,7 @@ async function runOrphans(input) {
     const split = splitFrontmatter(text);
     const body = split.ok ? split.data.body : text;
     for (const slug of extractBodyWikilinks(body)) {
-      const tgt = slugToPath[slug.split("/").pop()];
+      const tgt = slugToPath[slug] ?? slugToPath[slug.split("/").pop()];
       if (tgt) {
         adj[p.relPath].add(tgt);
         adj[tgt].add(p.relPath);
@@ -609,7 +682,11 @@ async function runOrphans(input) {
       }
     }
   }
-  return { exitCode: ExitCode.OK, result: ok({ orphans, bridges }) };
+  const hintLines = [];
+  if (orphans.length > 0) hintLines.push(`orphans: ${orphans.length}`, ...orphans.map((o) => `  ${o}`));
+  if (bridges.length > 0) hintLines.push(`bridges: ${bridges.length}`, ...bridges.map((b) => `  ${b.path}`));
+  if (hintLines.length === 0) hintLines.push("no orphans or bridges");
+  return { exitCode: ExitCode.OK, result: ok({ orphans, bridges, humanHint: hintLines.join("\n") }) };
 }
 function simulateRemoval(adj, removed) {
   const seen = /* @__PURE__ */ new Set();
@@ -630,20 +707,92 @@ function simulateRemoval(adj, removed) {
 
 // src/commands/audit.ts
 import { readFile as readFile5, stat as stat2 } from "fs/promises";
-import { dirname as dirname2, resolve, join as join3 } from "path";
+import { dirname as dirname3, resolve, join as join3 } from "path";
 
 // src/parsers/citations.ts
 var FENCE2 = /```[\s\S]*?```/g;
+var MARKER_RE = /\^\[(raw\/[^\]]+)\]/g;
+function stripFences(body) {
+  return body.replace(FENCE2, "");
+}
 function extractCitationMarkers(body) {
-  const stripped = body.replace(FENCE2, "");
+  const stripped = stripFences(body);
   const out = [];
-  const re = /\^\[(raw\/[^\]]+)\]/g;
   let m;
-  while ((m = re.exec(stripped)) !== null) {
+  while ((m = MARKER_RE.exec(stripped)) !== null) {
     out.push({ marker: m[0], target: m[1] });
   }
   return out;
 }
+function hasSourcesFooter(body) {
+  return /^## Sources\s*$/m.test(stripFences(body));
+}
+function isLegacyCitationStyle(body) {
+  const markers = extractCitationMarkers(body);
+  if (markers.length === 0) return false;
+  if (!hasSourcesFooter(body)) return true;
+  const lines = stripFences(body).split("\n");
+  let inSources = false;
+  for (const line of lines) {
+    if (/^## Sources\b/.test(line.trim())) {
+      inSources = true;
+      continue;
+    }
+    if (inSources) continue;
+    const markerOnly = line.replace(MARKER_RE, "").trim();
+    if (markerOnly.length === 0 && /\^\[raw\//.test(line)) return true;
+    const lastMarkerIdx = line.lastIndexOf("^[raw/");
+    if (lastMarkerIdx >= 0) {
+      const afterLast = line.slice(lastMarkerIdx).replace(MARKER_RE, "").trim();
+      if (afterLast.length > 0) return true;
+      const beforeFirst = line.slice(0, line.indexOf("^[raw/")).trim();
+      if (beforeFirst.length > 0 && !/[.!?]\s*$/.test(beforeFirst)) return true;
+    }
+  }
+  return false;
+}
+function hasOrphanedCitations(body) {
+  const stripped = stripFences(body);
+  const lines = stripped.split("\n");
+  let inSources = false;
+  let sourcesEnded = false;
+  let sourcesStartLine = -1;
+  let lastNonBlankInSources = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (/^## Sources\b/.test(trimmed)) {
+      inSources = true;
+      sourcesStartLine = i;
+      continue;
+    }
+    if (!inSources || sourcesEnded) continue;
+    if (trimmed.length === 0) {
+      if (lastNonBlankInSources >= 0) {
+        sourcesEnded = true;
+      }
+      continue;
+    }
+    const isListItem = /^\s*[-*]\s+/.test(line);
+    const hasMarker = /\^\[raw\//.test(line);
+    if (isListItem && hasMarker) {
+      lastNonBlankInSources = i;
+    } else if (hasMarker && !isListItem) {
+      return true;
+    } else {
+      sourcesEnded = true;
+    }
+  }
+  if (sourcesStartLine === -1) return false;
+  if (sourcesEnded) {
+    for (let i = lastNonBlankInSources + 1; i < lines.length; i++) {
+      if (/\^\[raw\//.test(lines[i])) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 
 // src/commands/audit.ts
 async function runAudit(input) {
@@ -657,7 +806,7 @@ 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(dirname2(resolve(input.file)));
+  const vault = await findVaultRoot(dirname3(resolve(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) => {
@@ -672,13 +821,36 @@ async function runAudit(input) {
   const referenced = new Set(resolved.map((m) => m.target));
   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]*)$/);
+  let footer_consistency;
+  if (footerMatch) {
+    const footerTargets = /* @__PURE__ */ new Set();
+    const footerRe = /\^\[(raw\/[^\]]+)\]/g;
+    let mm;
+    while ((mm = footerRe.exec(footerMatch[1])) !== null) footerTargets.add(mm[1]);
+    const bodyTargets = new Set(resolved.map((m) => m.target));
+    const missing_from_footer = [...bodyTargets].filter((t) => !footerTargets.has(t));
+    const extra_in_footer = [...footerTargets].filter((t) => !bodyTargets.has(t));
+    footer_consistency = { missing_from_footer, extra_in_footer };
+  }
+  const hintLines = [];
+  hintLines.push(`markers: ${resolved.length}, broken: ${broken.length}`);
+  if (unused_sources.length > 0) hintLines.push(`unused_sources: ${unused_sources.length}`);
+  if (missing_from_sources.length > 0) hintLines.push(`missing_from_sources: ${missing_from_sources.length}`);
+  if (footer_consistency) {
+    if (footer_consistency.missing_from_footer.length > 0) hintLines.push(`missing_from_footer: ${footer_consistency.missing_from_footer.length}`);
+    if (footer_consistency.extra_in_footer.length > 0) hintLines.push(`extra_in_footer: ${footer_consistency.extra_in_footer.length}`);
+  }
+  if (broken.length === 0 && unused_sources.length === 0 && missing_from_sources.length === 0) hintLines.push("OK");
+  const humanHint = hintLines.join("\n");
   if (resolved.some((m) => !m.resolved)) {
-    return { exitCode: ExitCode.UNRESOLVED_MARKERS, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources } }) };
+    return { exitCode: ExitCode.UNRESOLVED_MARKERS, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, footer_consistency, humanHint }) };
   }
   if (unused_sources.length > 0 || missing_from_sources.length > 0) {
-    return { exitCode: ExitCode.SOURCES_INCONSISTENT, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources } }) };
+    return { exitCode: ExitCode.SOURCES_INCONSISTENT, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, footer_consistency, humanHint }) };
   }
-  return { exitCode: ExitCode.OK, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources } }) };
+  return { exitCode: ExitCode.OK, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, footer_consistency, humanHint }) };
 }
 async function findVaultRoot(start) {
   let cur = start;
@@ -688,7 +860,7 @@ async function findVaultRoot(start) {
       return cur;
     } catch {
     }
-    const parent = dirname2(cur);
+    const parent = dirname3(cur);
     if (parent === cur) return null;
     cur = parent;
   }
@@ -700,10 +872,10 @@ import { readdir as readdir2, stat as stat4 } from "fs/promises";
 import { join as join4 } from "path";
 
 // src/utils/install-fs.ts
-import { copyFile, mkdir as mkdir2, rename, writeFile as writeFile2, stat as stat3 } from "fs/promises";
-import { dirname as dirname3 } from "path";
+import { copyFile, mkdir as mkdir3, rename, writeFile as writeFile3, stat as stat3 } from "fs/promises";
+import { dirname as dirname4 } from "path";
 async function atomicCopyWithBackup(src, dst) {
-  await mkdir2(dirname3(dst), { recursive: true });
+  await mkdir3(dirname4(dst), { recursive: true });
   let backupPath = null;
   try {
     await stat3(dst);
@@ -721,9 +893,9 @@ async function atomicCopyWithBackup(src, dst) {
   return ok({ copied: true, backupPath });
 }
 async function writeManifest(path, m) {
-  await mkdir2(dirname3(path), { recursive: true });
+  await mkdir3(dirname4(path), { recursive: true });
   const enriched = { installed_at: (/* @__PURE__ */ new Date()).toISOString(), ...m };
-  await writeFile2(path, JSON.stringify(enriched, null, 2));
+  await writeFile3(path, JSON.stringify(enriched, null, 2));
 }
 
 // src/commands/install.ts
@@ -758,7 +930,12 @@ async function runInstall(input) {
   }
   const manifest_path = join4(input.target, "wiki-manifest.json");
   if (!input.dryRun) await writeManifest(manifest_path, { installed, backed_up });
-  return { exitCode: ExitCode.OK, result: ok({ installed, backed_up, manifest_path }) };
+  const hintLines = [
+    `installed: ${installed.length}`,
+    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") }) };
 }
 
 // src/commands/path.ts
@@ -770,7 +947,7 @@ async function runPath(input) {
       home: input.home,
       explain: input.explain
     });
-    return { exitCode: ExitCode.OK, result: ok({ path: r2.path, source: r2.source, ...r2.chain ? { chain: r2.chain } : {} }) };
+    return { exitCode: ExitCode.OK, result: ok({ path: r2.path, source: r2.source, ...r2.chain ? { chain: r2.chain } : {}, humanHint: `${r2.path} (via ${r2.source})` }) };
   }
   const r = await resolveRuntimePath({
     flag: input.flag,
@@ -779,7 +956,7 @@ async function runPath(input) {
     explain: input.explain
   });
   if (!r.ok) return { exitCode: ExitCode.NO_VAULT_CONFIGURED, result: r };
-  return { exitCode: ExitCode.OK, result: ok({ path: r.data.path, source: r.data.source, ...r.data.chain ? { chain: r.data.chain } : {} }) };
+  return { exitCode: ExitCode.OK, result: ok({ path: r.data.path, source: r.data.source, ...r.data.chain ? { chain: r.data.chain } : {}, humanHint: `${r.data.path} (via ${r.data.source})` }) };
 }
 
 // src/utils/lang.ts
@@ -833,14 +1010,42 @@ async function runLang(input) {
       value: resolved.value,
       source: resolved.source,
       canonical: resolved.canonical,
-      ...chain ? { chain } : {}
+      ...chain ? { chain } : {},
+      humanHint: `${resolved.value} (via ${resolved.source})`
     })
   };
 }
 
 // src/commands/init.ts
-import { mkdir as mkdir3, readFile as readFile6, stat as stat5, writeFile as writeFile3 } from "fs/promises";
-import { join as join7, dirname as dirname4 } from "path";
+import { mkdir as mkdir4, readFile as readFile6, readdir as readdir3, writeFile as writeFile4 } from "fs/promises";
+import { join as join7 } from "path";
+
+// src/parsers/taxonomy.ts
+import yaml2 from "js-yaml";
+var FENCE_RE = /^##\s+Tag Taxonomy\s*$[\s\S]*?```yaml\s*\n([\s\S]*?)\n```/m;
+function extractTaxonomy(schemaText) {
+  const m = schemaText.match(FENCE_RE);
+  if (!m) return err("NO_TAXONOMY_BLOCK", { message: "No fenced YAML taxonomy block found in SCHEMA.md" });
+  let parsed;
+  try {
+    parsed = yaml2.load(m[1], { schema: yaml2.JSON_SCHEMA });
+  } catch (e) {
+    return err("INVALID_FRONTMATTER", { message: e.message });
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy block is not an object" });
+  }
+  const tax = parsed.taxonomy;
+  if (!Array.isArray(tax)) {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy key missing or not an array" });
+  }
+  if (!tax.every((x) => typeof x === "string")) {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy must be a list of strings" });
+  }
+  return ok(tax);
+}
+
+// src/commands/init.ts
 var DEFAULT_TAXONOMY = [
   "research",
   "comparison",
@@ -865,25 +1070,59 @@ var VAULT_DIRS = [
   "meta",
   "projects"
 ];
+function extractDomainFromSchema(text) {
+  const m = text.match(/^##\s+Domain\s*\n([\s\S]*?)(?=\n\n|\n##|\s*$)/m);
+  if (!m) return "";
+  const d = m[1].trim();
+  return d.startsWith("##") ? "" : d;
+}
+async function discoverTagsFromPages(target, knownSlugs) {
+  const knownSet = new Set(knownSlugs);
+  const discovered = /* @__PURE__ */ new Set();
+  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);
+    } catch {
+      continue;
+    }
+    for (const file of entries) {
+      try {
+        const text = await readFile6(join7(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) {
+          if (typeof t === "string" && !knownSet.has(t)) discovered.add(t);
+        }
+      } catch {
+      }
+    }
+  }
+  return [...discovered].sort();
+}
 async function runInit(input) {
   const pathRes = await resolveInitTimePath({ flag: input.flag, envValue: input.envValue, home: input.home });
   const target = pathRes.path;
   const langRes = await resolveLang({ flag: input.lang, envValue: void 0, home: input.home });
   const canonicalLang = langRes.canonical;
-  let hasSchema = false;
+  let oldSchemaText;
   try {
-    await stat5(join7(target, "SCHEMA.md"));
-    hasSchema = true;
+    oldSchemaText = await readFile6(join7(target, "SCHEMA.md"), "utf8");
   } catch {
   }
-  if (hasSchema && !input.force) {
+  if (oldSchemaText && !input.force) {
     return {
       exitCode: ExitCode.INIT_TARGET_NOT_EMPTY,
       result: err("INIT_TARGET_NOT_EMPTY", { target })
     };
   }
   const envPath = join7(input.home, ".skillwiki", ".env");
-  const existingEnv = await parseDotenvFile(envPath);
+  let existingEnvRaw = "";
+  try {
+    existingEnvRaw = await readFile6(envPath, "utf8");
+  } catch {
+  }
+  const existingEnv = parseDotenvText(existingEnvRaw);
   const swDotenvHadPath = existingEnv.WIKI_PATH !== void 0;
   if (existingEnv.WIKI_PATH !== void 0 && existingEnv.WIKI_PATH !== target && !input.force) {
     return {
@@ -899,73 +1138,125 @@ async function runInit(input) {
   }
   const created = [];
   try {
-    await mkdir3(target, { recursive: true });
+    await mkdir4(target, { recursive: true });
     for (const d of VAULT_DIRS) {
-      await mkdir3(join7(target, d), { recursive: true });
+      await mkdir4(join7(target, d), { recursive: true });
       created.push(d + "/");
     }
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
   }
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  const taxonomy = input.taxonomy && input.taxonomy.length > 0 ? input.taxonomy : DEFAULT_TAXONOMY;
-  const taxonomyYaml = taxonomy.map((t) => `  - ${t}`).join("\n");
+  let taxonomy = input.taxonomy && input.taxonomy.length > 0 ? input.taxonomy : DEFAULT_TAXONOMY;
+  let domain = input.domain;
+  let oldTaxonomy = [];
+  if (oldSchemaText) {
+    if (!domain) {
+      const oldDomain = extractDomainFromSchema(oldSchemaText);
+      if (oldDomain) domain = oldDomain;
+    }
+    const oldTax = extractTaxonomy(oldSchemaText);
+    if (oldTax.ok) oldTaxonomy = oldTax.data;
+  }
+  const taxonomySet = new Set(taxonomy);
+  for (const t of oldTaxonomy) {
+    if (!taxonomySet.has(t)) {
+      taxonomy.push(t);
+      taxonomySet.add(t);
+    }
+  }
+  const discovered = await discoverTagsFromPages(target, taxonomy);
+  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 schema = schemaTpl.replace("{{DOMAIN}}", input.domain).replace("{{WIKI_LANG}}", canonicalLang).replace("{{TAXONOMY_YAML}}", taxonomyYaml);
-    await writeFile3(join7(target, "SCHEMA.md"), schema, "utf8");
+    const schema = schemaTpl.replace("{{DOMAIN}}", domain).replace("{{WIKI_LANG}}", canonicalLang).replace("{{TAXONOMY_YAML}}", fullTaxonomyYaml);
+    await writeFile4(join7(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) }) };
   }
-  try {
-    const idxTpl = await readFile6(join7(input.templates, "index.md"), "utf8");
-    const idx = idxTpl.replace("{{INIT_DATE}}", today);
-    await writeFile3(join7(target, "index.md"), idx, "utf8");
-    created.push("index.md");
-  } catch (e) {
-    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "index.md", message: String(e) }) };
-  }
-  try {
-    const logTpl = await readFile6(join7(input.templates, "log.md"), "utf8");
-    const log = logTpl.replace(/\{\{INIT_DATE\}\}/g, today).replace("{{DOMAIN}}", input.domain).replace("{{WIKI_LANG}}", canonicalLang);
-    await writeFile3(join7(target, "log.md"), log, "utf8");
-    created.push("log.md");
-  } catch (e) {
-    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "log.md", message: String(e) }) };
+  const preserved = [];
+  async function writeOrPreserve(fileName, render) {
+    try {
+      const existing = await readFile6(join7(target, fileName), "utf8");
+      if (existing.split("\n").length > 10) {
+        preserved.push(fileName);
+        return void 0;
+      }
+    } catch {
+    }
+    try {
+      await writeFile4(join7(target, fileName), await render(), "utf8");
+      created.push(fileName);
+      return void 0;
+    } catch (e) {
+      return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: fileName, message: String(e) }) };
+    }
   }
-  try {
-    await mkdir3(dirname4(envPath), { recursive: true });
-    const envBody = `WIKI_PATH=${target}
-WIKI_LANG=${canonicalLang}
-`;
-    await writeFile3(envPath, envBody, "utf8");
-  } catch (e) {
-    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: envPath, message: String(e) }) };
+  const err1 = await writeOrPreserve("index.md", async () => {
+    const tpl = await readFile6(join7(input.templates, "index.md"), "utf8");
+    return tpl.replace("{{INIT_DATE}}", today);
+  });
+  if (err1) return err1;
+  const err22 = await writeOrPreserve("log.md", async () => {
+    const tpl = await readFile6(join7(input.templates, "log.md"), "utf8");
+    return tpl.replace(/\{\{INIT_DATE\}\}/g, today).replace("{{DOMAIN}}", domain).replace("{{WIKI_LANG}}", canonicalLang);
+  });
+  if (err22) return err22;
+  const isTempPath = target.startsWith("/tmp/") || target === "/tmp" || target.startsWith("/var/tmp/") || target === "/var/tmp" || target.startsWith("/private/tmp/");
+  const skipEnv = !!input.noEnv || isTempPath;
+  let envWritten = "";
+  if (!skipEnv) {
+    try {
+      await writeDotenv(envPath, { WIKI_PATH: target, WIKI_LANG: canonicalLang }, existingEnvRaw);
+      envWritten = envPath;
+    } catch (e) {
+      return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: envPath, message: String(e) }) };
+    }
   }
   const importedFromHermes = pathRes.source === "hermes-dotenv" && !swDotenvHadPath;
+  const humanHint = [
+    `vault: ${target}`,
+    `domain: ${domain}`,
+    `lang: ${canonicalLang}`,
+    `created: ${created.length}, preserved: ${preserved.length}`,
+    `discovered tags: ${discovered_tags}`,
+    skipEnv ? "env: skipped" : `env: ${envWritten}`
+  ].join("\n");
   return {
     exitCode: ExitCode.OK,
     result: ok({
       vault: target,
-      domain: input.domain,
+      domain,
       taxonomy,
       lang: canonicalLang,
       created,
-      env_written: envPath,
-      imported_from_hermes: importedFromHermes
+      preserved,
+      env_written: envWritten,
+      env_skipped: skipEnv,
+      imported_from_hermes: importedFromHermes,
+      discovered_tags,
+      humanHint
     })
   };
 }
 
+// src/utils/slug.ts
+function buildSlugMap(pages) {
+  const map = /* @__PURE__ */ new Map();
+  for (const p of pages) {
+    const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
+    map.set(slug.toLowerCase(), slug);
+  }
+  return map;
+}
+
 // src/commands/links.ts
 async function runLinks(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const slugs = /* @__PURE__ */ new Set();
-  for (const p of scan.data.typedKnowledge) {
-    slugs.add(p.relPath.replace(/\.md$/, "").split("/").pop());
-  }
+  const slugs = buildSlugMap(scan.data.typedKnowledge);
   const broken = [];
   for (const p of scan.data.typedKnowledge) {
     const text = await readPage(p);
@@ -974,48 +1265,22 @@ async function runLinks(input) {
     const lines = body.split("\n");
     for (const slug of extractBodyWikilinks(body)) {
       const tail = slug.split("/").pop();
-      if (!slugs.has(tail)) {
+      if (!slugs.has(tail.toLowerCase())) {
         const line = lines.findIndex((l) => l.includes(`[[${slug}`));
         broken.push({ page: p.relPath, slug, line: line >= 0 ? line + 1 : 0 });
       }
     }
   }
   if (broken.length > 0) {
-    return { exitCode: ExitCode.BROKEN_WIKILINKS, result: ok({ broken }) };
+    return { exitCode: ExitCode.BROKEN_WIKILINKS, result: ok({ broken, humanHint: `broken: ${broken.length}
+${broken.map((b) => `  ${b.page}:[[${b.slug}]] (line ${b.line})`).join("\n")}` }) };
   }
-  return { exitCode: ExitCode.OK, result: ok({ broken }) };
+  return { exitCode: ExitCode.OK, result: ok({ broken, humanHint: "no broken wikilinks" }) };
 }
 
 // src/commands/tag-audit.ts
 import { readFile as readFile7 } from "fs/promises";
 import { join as join8 } from "path";
-
-// src/parsers/taxonomy.ts
-import yaml2 from "js-yaml";
-var FENCE_RE = /^##\s+Tag Taxonomy\s*$[\s\S]*?```yaml\s*\n([\s\S]*?)\n```/m;
-function extractTaxonomy(schemaText) {
-  const m = schemaText.match(FENCE_RE);
-  if (!m) return ok([]);
-  let parsed;
-  try {
-    parsed = yaml2.load(m[1], { schema: yaml2.JSON_SCHEMA });
-  } catch (e) {
-    return err("INVALID_FRONTMATTER", { message: e.message });
-  }
-  if (parsed === null || typeof parsed !== "object") {
-    return err("INVALID_FRONTMATTER", { message: "taxonomy block is not an object" });
-  }
-  const tax = parsed.taxonomy;
-  if (!Array.isArray(tax)) {
-    return err("INVALID_FRONTMATTER", { message: "taxonomy key missing or not an array" });
-  }
-  if (!tax.every((x) => typeof x === "string")) {
-    return err("INVALID_FRONTMATTER", { message: "taxonomy must be a list of strings" });
-  }
-  return ok(tax);
-}
-
-// src/commands/tag-audit.ts
 async function runTagAudit(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -1037,9 +1302,9 @@ async function runTagAudit(input) {
     }
   }
   if (violations.length > 0) {
-    return { exitCode: ExitCode.TAG_NOT_IN_TAXONOMY, result: ok({ violations, taxonomy: tax.data }) };
+    return { exitCode: ExitCode.TAG_NOT_IN_TAXONOMY, result: ok({ violations, taxonomy: tax.data, humanHint: violations.map((v) => `${v.page}: "${v.tag}" not in taxonomy`).join("\n") }) };
   }
-  return { exitCode: ExitCode.OK, result: ok({ violations, taxonomy: tax.data }) };
+  return { exitCode: ExitCode.OK, result: ok({ violations, taxonomy: tax.data, humanHint: "all tags valid" }) };
 }
 
 // src/commands/index-check.ts
@@ -1053,7 +1318,11 @@ async function runIndexCheck(input) {
     indexText = await readFile8(join9(input.vault, "index.md"), "utf8");
   } catch {
   }
-  const indexSlugs = new Set(extractBodyWikilinks(indexText).map((s) => s.split("/").pop()));
+  const indexSlugsLower = /* @__PURE__ */ new Map();
+  for (const s of extractBodyWikilinks(indexText)) {
+    const tail = s.split("/").pop();
+    indexSlugsLower.set(tail.toLowerCase(), tail);
+  }
   const fileSlugs = /* @__PURE__ */ new Map();
   for (const p of scan.data.typedKnowledge) {
     const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
@@ -1061,16 +1330,21 @@ async function runIndexCheck(input) {
   }
   const missing_from_index = [];
   for (const [slug, relPath] of fileSlugs.entries()) {
-    if (!indexSlugs.has(slug)) missing_from_index.push(relPath);
+    if (!indexSlugsLower.has(slug.toLowerCase())) missing_from_index.push(relPath);
   }
+  const fileSlugsLower = new Set([...fileSlugs.keys()].map((s) => s.toLowerCase()));
   const ghost_entries = [];
-  for (const slug of indexSlugs) {
-    if (!fileSlugs.has(slug)) ghost_entries.push(slug);
+  for (const [lower, orig] of indexSlugsLower) {
+    if (!fileSlugsLower.has(lower)) ghost_entries.push(orig);
   }
+  const hintLines = [];
+  if (missing_from_index.length > 0) hintLines.push(`missing from index: ${missing_from_index.length}`, ...missing_from_index.map((p) => `  ${p}`));
+  if (ghost_entries.length > 0) hintLines.push(`ghost entries: ${ghost_entries.length}`, ...ghost_entries.map((g) => `  ${g}`));
+  if (hintLines.length === 0) hintLines.push("index OK");
   if (missing_from_index.length > 0 || ghost_entries.length > 0) {
-    return { exitCode: ExitCode.INDEX_INCOMPLETE, result: ok({ missing_from_index, ghost_entries }) };
+    return { exitCode: ExitCode.INDEX_INCOMPLETE, result: ok({ missing_from_index, ghost_entries, humanHint: hintLines.join("\n") }) };
   }
-  return { exitCode: ExitCode.OK, result: ok({ missing_from_index, ghost_entries }) };
+  return { exitCode: ExitCode.OK, result: ok({ missing_from_index, ghost_entries, humanHint: hintLines.join("\n") }) };
 }
 
 // src/commands/stale.ts
@@ -1110,8 +1384,8 @@ async function runStale(input) {
       stale.push({ page: p.relPath, page_updated: updated, newest_source_ingested: newest, gap_days: gap });
     }
   }
-  if (stale.length > 0) return { exitCode: ExitCode.STALE_PAGE, result: ok({ stale }) };
-  return { exitCode: ExitCode.OK, result: ok({ stale }) };
+  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" }) };
 }
 
 // src/commands/pagesize.ts
@@ -1126,17 +1400,17 @@ async function runPagesize(input) {
     const count = body.split("\n").length;
     if (count > input.lines) oversized.push({ page: p.relPath, lines: count });
   }
-  if (oversized.length > 0) return { exitCode: ExitCode.PAGE_TOO_LARGE, result: ok({ oversized }) };
-  return { exitCode: ExitCode.OK, result: ok({ oversized }) };
+  if (oversized.length > 0) return { exitCode: ExitCode.PAGE_TOO_LARGE, result: ok({ oversized, humanHint: oversized.map((p) => `${p.page}: ${p.lines} lines`).join("\n") }) };
+  return { exitCode: ExitCode.OK, result: ok({ oversized, humanHint: "all pages within size limit" }) };
 }
 
 // src/commands/log-rotate.ts
-import { readFile as readFile10, rename as rename2, writeFile as writeFile4, stat as stat6 } from "fs/promises";
+import { readFile as readFile10, rename as rename2, writeFile as writeFile5, stat as stat5 } from "fs/promises";
 import { join as join11 } from "path";
 var ENTRY_RE = /^## \[(\d{4})-\d{2}-\d{2}\]/gm;
 async function runLogRotate(input) {
   try {
-    await stat6(join11(input.vault, "SCHEMA.md"));
+    await stat5(join11(input.vault, "SCHEMA.md"));
   } catch {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
@@ -1150,12 +1424,12 @@ async function runLogRotate(input) {
   const matches = [...logText.matchAll(ENTRY_RE)];
   const entries = matches.length;
   if (entries < input.threshold) {
-    return { exitCode: ExitCode.OK, result: ok({ entries, threshold: input.threshold, rotated: false }) };
+    return { exitCode: ExitCode.OK, result: ok({ entries, threshold: input.threshold, rotated: false, humanHint: `${entries}/${input.threshold} entries \u2014 no rotation needed` }) };
   }
   if (!input.apply) {
     return {
       exitCode: ExitCode.LOG_ROTATE_NEEDED,
-      result: ok({ entries, threshold: input.threshold, rotated: false })
+      result: ok({ entries, threshold: input.threshold, rotated: false, humanHint: `${entries}/${input.threshold} entries \u2014 rotation needed (use --apply)` })
     };
   }
   const newestYear = matches[matches.length - 1][1];
@@ -1172,17 +1446,88 @@ Chronological action log. Newest entries last. Skill writes append entries; lint
 
 - Previous log moved to ${rotatedName}
 `;
-    await writeFile4(logPath, fresh, "utf8");
+    await writeFile5(logPath, fresh, "utf8");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
   }
-  return { exitCode: ExitCode.OK, result: ok({ entries, threshold: input.threshold, rotated: true, rotated_to: rotatedName }) };
+  return { exitCode: ExitCode.OK, result: ok({ entries, threshold: input.threshold, rotated: true, rotated_to: rotatedName, humanHint: `rotated ${entries} entries to ${rotatedName}` }) };
+}
+
+// src/commands/topic-map-check.ts
+var DEFAULT_THRESHOLD = 200;
+async function runTopicMapCheck(input) {
+  const threshold = input.threshold ?? DEFAULT_THRESHOLD;
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const page_count = scan.data.typedKnowledge.length;
+  const recommended = page_count >= threshold;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      recommended,
+      page_count,
+      threshold,
+      humanHint: recommended ? `topic map recommended (${page_count} pages >= ${threshold} threshold)` : `topic map not needed (${page_count} pages < ${threshold} threshold)`
+    })
+  };
+}
+
+// src/commands/index-link-format.ts
+import { readFile as readFile11 } from "fs/promises";
+import { join as join12 } from "path";
+var MD_LINK_RE = /\[[^\[\]]+\]\([^)]+\.md\)/;
+async function runIndexLinkFormat(input) {
+  let text = "";
+  try {
+    text = await readFile11(join12(input.vault, "index.md"), "utf8");
+  } catch {
+  }
+  const markdown_links = [];
+  for (const [i, line] of text.split("\n").entries()) {
+    if (MD_LINK_RE.test(line)) markdown_links.push({ line: i + 1, text: line.trim() });
+  }
+  const humanHint = markdown_links.length === 0 ? "all index links use wikilink format" : `markdown links found: ${markdown_links.length}
+${markdown_links.map((l) => `  line ${l.line}: ${l.text}`).join("\n")}`;
+  return { exitCode: ExitCode.OK, result: ok({ markdown_links, humanHint }) };
+}
+
+// src/commands/dedup.ts
+async function runDedup(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const hashMap = /* @__PURE__ */ new Map();
+  let totalFiles = 0;
+  for (const raw of scan.data.raw) {
+    const fm = extractFrontmatter(await readPage(raw));
+    if (!fm.ok) continue;
+    const sha = typeof fm.data.sha256 === "string" ? fm.data.sha256 : null;
+    if (!sha || sha.length !== 64) continue;
+    totalFiles++;
+    const existing = hashMap.get(sha);
+    if (existing) existing.push(raw.relPath);
+    else hashMap.set(sha, [raw.relPath]);
+  }
+  const duplicates = [...hashMap.entries()].filter(([, files]) => files.length > 1).map(([sha256, files]) => ({ sha256, files }));
+  const exitCode = duplicates.length > 0 ? ExitCode.RAW_DEDUP_DETECTED : ExitCode.OK;
+  const hintLines = [`scanned: ${totalFiles} raw files`];
+  if (duplicates.length > 0) {
+    hintLines.push(`duplicates: ${duplicates.length}`);
+    for (const d of duplicates) hintLines.push(`  ${d.sha256.slice(0, 12)}... \u2192 ${d.files.join(", ")}`);
+  } else {
+    hintLines.push("0 duplicates");
+  }
+  return {
+    exitCode,
+    result: ok({ scanned: totalFiles, duplicates, humanHint: hintLines.join("\n") })
+  };
 }
 
 // src/commands/lint.ts
-var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_drift", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["index_incomplete", "stale_page", "page_too_large", "log_rotate_needed", "contested", "orphans"];
-var INFO_ORDER = ["bridges", "low_confidence_single_source"];
+var STRUCT_MIN_BODY_LINES = 60;
+var STRUCT_MIN_SECTIONS = 3;
+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", "contested", "orphans", "legacy_citation_style", "orphaned_citations"];
+var INFO_ORDER = ["bridges", "low_confidence_single_source", "page_structure", "topic_map_recommended"];
 async function runLint(input) {
   const buckets = {};
   const links = await runLinks({ vault: input.vault });
@@ -1202,6 +1547,10 @@ async function runLint(input) {
       ghost_entries: idx.result.data.ghost_entries
     }];
   }
+  const linkFmt = await runIndexLinkFormat({ vault: input.vault });
+  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 pagesize = await runPagesize({ vault: input.vault, lines: input.lines });
@@ -1215,6 +1564,42 @@ async function runLint(input) {
     if (orphans.result.data.orphans.length > 0) buckets.orphans = orphans.result.data.orphans;
     if (orphans.result.data.bridges.length > 0) buckets.bridges = orphans.result.data.bridges;
   }
+  const topicMap = await runTopicMapCheck({ vault: input.vault });
+  if (topicMap.result.ok && topicMap.result.data.recommended) {
+    buckets.topic_map_recommended = [{ page_count: topicMap.result.data.page_count, threshold: topicMap.result.data.threshold }];
+  }
+  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 scan = await scanVault(input.vault);
+  if (scan.ok) {
+    const legacyPages = [];
+    const orphanedPages = [];
+    const structFlags = [];
+    for (const page of scan.data.typedKnowledge) {
+      const text = await readPage(page);
+      const split = splitFrontmatter(text);
+      if (!split.ok) continue;
+      const body = split.data.body;
+      if (isLegacyCitationStyle(body)) legacyPages.push(page.relPath);
+      if (hasOrphanedCitations(body)) orphanedPages.push(page.relPath);
+      const bodyLines = body.split("\n").filter((l) => l.trim().length > 0).length;
+      if (bodyLines < STRUCT_MIN_BODY_LINES) {
+        const hasOverview = /^## Overview/m.test(body);
+        const hasRelated = /^## (Related|Relationships)/m.test(body);
+        const sectionCount = (body.match(/^## /gm) ?? []).length;
+        if (!hasOverview || !hasRelated || sectionCount < STRUCT_MIN_SECTIONS) {
+          const reasons = [];
+          if (!hasOverview) reasons.push("no Overview");
+          if (!hasRelated) reasons.push("no Related or Relationships");
+          if (sectionCount < STRUCT_MIN_SECTIONS) reasons.push(`only ${sectionCount} sections`);
+          structFlags.push(`${page.relPath}: ${bodyLines} lines, ${reasons.join(", ")}`);
+        }
+      }
+    }
+    if (legacyPages.length > 0) buckets.legacy_citation_style = legacyPages;
+    if (orphanedPages.length > 0) buckets.orphaned_citations = orphanedPages;
+    if (structFlags.length > 0) buckets.page_structure = structFlags;
+  }
   const errorOut = ERROR_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const warningOut = WARNING_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const infoOut = INFO_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
@@ -1226,19 +1611,629 @@ async function runLint(input) {
   let exitCode = ExitCode.OK;
   if (summary.errors > 0) exitCode = ExitCode.LINT_HAS_ERRORS;
   else if (summary.warnings > 0 || summary.info > 0) exitCode = ExitCode.LINT_HAS_WARNINGS;
+  const hintLines = [];
+  if (summary.errors > 0) hintLines.push(`errors: ${summary.errors}`);
+  if (summary.warnings > 0) hintLines.push(`warnings: ${summary.warnings}`);
+  if (summary.info > 0) hintLines.push(`info: ${summary.info}`);
+  const allBuckets = [...errorOut, ...warningOut, ...infoOut];
+  for (const b of allBuckets) {
+    hintLines.push(`  ${b.kind}: ${b.items.length}`);
+  }
+  if (hintLines.length === 0) hintLines.push("0 errors, 0 warnings, 0 info");
   return {
     exitCode,
     result: ok({
       vault: { path: input.vault, source: input.source ?? "resolved" },
       summary,
-      by_severity: { error: errorOut, warning: warningOut, info: infoOut }
+      by_severity: { error: errorOut, warning: warningOut, info: infoOut },
+      humanHint: hintLines.join("\n")
+    })
+  };
+}
+
+// src/commands/config.ts
+import { readFile as readFile12 } from "fs/promises";
+import { existsSync } from "fs";
+import { join as join13 } from "path";
+function validateKey(key) {
+  return CONFIG_KEYS.includes(key);
+}
+function configPath(home) {
+  return join13(home, ".skillwiki", ".env");
+}
+async function runConfigGet(input) {
+  if (!validateKey(input.key)) {
+    return { exitCode: ExitCode.INVALID_CONFIG_KEY, result: err("INVALID_CONFIG_KEY", { key: input.key }) };
+  }
+  const map = await parseDotenvFile(configPath(input.home));
+  const value = map[input.key] ?? "";
+  return { exitCode: ExitCode.OK, result: ok({ key: input.key, value, humanHint: value }) };
+}
+async function runConfigSet(input) {
+  if (!validateKey(input.key)) {
+    return { exitCode: ExitCode.INVALID_CONFIG_KEY, result: err("INVALID_CONFIG_KEY", { key: input.key }) };
+  }
+  const filePath = configPath(input.home);
+  try {
+    let originalContent;
+    try {
+      originalContent = await readFile12(filePath, "utf8");
+    } catch {
+    }
+    const existing = originalContent !== void 0 ? parseDotenvText(originalContent) : {};
+    const merged = { ...existing, [input.key]: input.value };
+    await writeDotenv(filePath, merged, originalContent);
+    return { exitCode: ExitCode.OK, result: ok({ key: input.key, value: input.value, written: true, humanHint: `${input.key}=${input.value}` }) };
+  } catch (e) {
+    return { exitCode: ExitCode.CONFIG_WRITE_FAILED, result: err("CONFIG_WRITE_FAILED", { key: input.key, error: String(e) }) };
+  }
+}
+async function runConfigList(input) {
+  const map = await parseDotenvFile(configPath(input.home));
+  const entries = Object.entries(map).map(([key, value]) => ({ key, value: value ?? "" }));
+  return { exitCode: ExitCode.OK, result: ok({ entries, humanHint: entries.map((e) => `${e.key}=${e.value}`).join("\n") }) };
+}
+async function runConfigPath(input) {
+  const filePath = configPath(input.home);
+  return { exitCode: ExitCode.OK, result: ok({ path: filePath, exists: existsSync(filePath), humanHint: filePath }) };
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync2, statSync } from "fs";
+import { join as join15 } from "path";
+import { execSync } from "child_process";
+
+// src/utils/auto-update.ts
+import { readFileSync, writeFileSync, existsSync as existsSync2, mkdirSync } from "fs";
+import { join as join14, dirname as dirname6 } from "path";
+import { spawn } from "child_process";
+
+// src/utils/update-consts.ts
+var CACHE_FILENAME = ".update-cache.json";
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var ENV_DISABLE_KEY = "NO_UPDATE_NOTIFIER";
+var CLI_DISABLE_FLAG = "--no-update-notifier";
+
+// src/utils/auto-update.ts
+function cachePath(home) {
+  return join14(home, ".skillwiki", CACHE_FILENAME);
+}
+function readCacheRaw(home) {
+  try {
+    const raw = readFileSync(cachePath(home), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function readCache(home) {
+  const cache = readCacheRaw(home);
+  if (!cache) return { cache: null, hasUpdate: false, isStale: true };
+  const isStale = Date.now() - cache.lastCheck >= CHECK_INTERVAL_MS;
+  const hasUpdate = !!cache.latestVersion && semverGt(cache.latestVersion, cache.currentVersion);
+  return { cache, hasUpdate, isStale };
+}
+function writeCache(home, cache) {
+  const p = cachePath(home);
+  mkdirSync(dirname6(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(cache, null, 2));
+}
+function latestFromCache(home, currentVersion) {
+  const { cache } = readCache(home);
+  if (!cache || !cache.latestVersion) return { hasUpdate: false, latest: null };
+  return {
+    hasUpdate: semverGt(cache.latestVersion, currentVersion),
+    latest: cache.latestVersion
+  };
+}
+function isDisabled() {
+  return !!(process.env[ENV_DISABLE_KEY] || process.env.NODE_ENV === "test" || process.argv.includes(CLI_DISABLE_FLAG));
+}
+function triggerAutoUpdate(home, currentVersion) {
+  if (isDisabled()) return;
+  const { isStale } = readCache(home);
+  if (!isStale) return;
+  const bgScript = new URL("../auto-update-bg.js", import.meta.url).pathname;
+  if (!existsSync2(bgScript)) return;
+  const child = spawn(process.execPath, [bgScript, home, currentVersion], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.on("error", () => {
+  });
+  child.unref();
+}
+
+// src/commands/doctor.ts
+function check(status, id, label, detail) {
+  return { id, label, status, detail };
+}
+function checkNodeVersion() {
+  const major = parseInt(process.version.slice(1).split(".")[0], 10);
+  if (major >= 20) {
+    return check("pass", "node_version", "Node.js version", `v${major} >= 20`);
+  }
+  return check("error", "node_version", "Node.js version", `Node.js v${major} is below minimum v20`);
+}
+function checkCliOnPath(argv) {
+  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");
+  }
+  if (argv.length >= 2 && argv[1] === "skillwiki") {
+    return check("pass", "cli_on_path", "skillwiki on PATH", "Running as skillwiki \u2014 already on PATH");
+  }
+  try {
+    execSync("which skillwiki 2>/dev/null", { encoding: "utf8" }).trim();
+    return check("pass", "cli_on_path", "skillwiki on PATH", "skillwiki found on PATH");
+  } catch {
+    return check("warn", "cli_on_path", "skillwiki on PATH", "skillwiki not found on PATH");
+  }
+}
+async function checkConfigFile(home) {
+  const cfgPath = configPath(home);
+  if (!existsSync3(cfgPath)) {
+    return check("warn", "config_file", "Config file exists", `${cfgPath} not found`);
+  }
+  try {
+    const map = await parseDotenvFile(cfgPath);
+    const keys = Object.keys(map);
+    return check("pass", "config_file", "Config file exists", `Found with keys: ${keys.length > 0 ? keys.join(", ") : "(none set)"}`);
+  } catch (e) {
+    return check("warn", "config_file", "Config file exists", `Failed to parse ${cfgPath}: ${String(e)}`);
+  }
+}
+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()) {
+    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`);
+}
+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)) {
+    return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
+  }
+  const missing = [];
+  if (!existsSync3(join15(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  for (const dir of ["raw", "entities", "concepts", "meta"]) {
+    if (!existsSync3(join15(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("error", "vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")}`);
+}
+function checkSkillsInstalled(home) {
+  const skillsDir = join15(home, ".claude", "skills");
+  if (!existsSync3(skillsDir)) {
+    return check("warn", "skills_installed", "Skills installed", `${skillsDir} not found`);
+  }
+  const found = findSkillMd(skillsDir);
+  if (found.length > 0) {
+    return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found`);
+  }
+  return check("warn", "skills_installed", "Skills installed", "No SKILL.md files found in ~/.claude/skills/");
+}
+function checkNpmUpdate(home, currentVersion) {
+  const { hasUpdate, latest } = latestFromCache(home, currentVersion);
+  if (!latest) {
+    return check("pass", "npm_update", "npm CLI version", `v${currentVersion} (no cache yet)`);
+  }
+  if (hasUpdate) {
+    return check("warn", "npm_update", "npm CLI version", `v${currentVersion} \u2014 update available: v${latest}. Run \`skillwiki update\`.`);
+  }
+  return check("pass", "npm_update", "npm CLI version", `v${currentVersion} (latest: v${latest})`);
+}
+function checkPluginVersionDrift(home, currentVersion) {
+  const pluginJsonPath = join15(home, ".claude", "plugins", "cache", "llm-wiki", "plugin.json");
+  if (!existsSync3(pluginJsonPath)) {
+    return check("pass", "plugin_version_drift", "Plugin/CLI version", "Plugin cache not found \u2014 plugin not installed");
+  }
+  try {
+    const content = readFileSync2(pluginJsonPath, { encoding: "utf8" });
+    const pluginData = JSON.parse(content);
+    const pluginVersion = pluginData.version;
+    if (!pluginVersion) {
+      return check("pass", "plugin_version_drift", "Plugin/CLI version", "Plugin version not found in cache");
+    }
+    if (pluginVersion === currentVersion) {
+      return check("pass", "plugin_version_drift", "Plugin/CLI version", `Both at v${currentVersion}`);
+    }
+    const updateCmd = semverGt(pluginVersion, currentVersion) ? "npm install -g skillwiki@beta" : "claude plugin update skillwiki@llm-wiki";
+    return check(
+      "warn",
+      "plugin_version_drift",
+      "Plugin/CLI version",
+      `Plugin v${pluginVersion} \u2260 CLI v${currentVersion} \u2014 run \`${updateCmd}\``
+    );
+  } catch {
+    return check("pass", "plugin_version_drift", "Plugin/CLI version", "Could not read plugin cache");
+  }
+}
+function findSkillMd(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name === "SKILL.md") {
+      results.push(join15(dir, entry.name));
+    } else if (entry.isDirectory()) {
+      results.push(...findSkillMd(join15(dir, entry.name)));
+    }
+  }
+  return results;
+}
+async function runDoctor(input) {
+  const checks = [];
+  checks.push(checkNodeVersion());
+  checks.push(checkCliOnPath(input.argv));
+  checks.push(await checkConfigFile(input.home));
+  const resolved = await resolveRuntimePath({ flag: void 0, envValue: input.envValue, home: input.home });
+  if (resolved.ok) {
+    checks.push(check("pass", "wiki_path_set", "WIKI_PATH configured", `Resolved via ${resolved.data.source}: ${resolved.data.path}`));
+  } else {
+    checks.push(check("error", "wiki_path_set", "WIKI_PATH configured", "No vault configured. Run `skillwiki init` or pass --vault."));
+  }
+  const resolvedPath = resolved.ok ? resolved.data.path : void 0;
+  checks.push(checkWikiPathExists(resolvedPath));
+  checks.push(checkVaultStructure(resolvedPath));
+  checks.push(checkSkillsInstalled(input.home));
+  checks.push(checkNpmUpdate(input.home, input.currentVersion));
+  checks.push(checkPluginVersionDrift(input.home, input.currentVersion));
+  const summary = {
+    pass: checks.filter((c) => c.status === "pass").length,
+    warn: checks.filter((c) => c.status === "warn").length,
+    error: checks.filter((c) => c.status === "error").length
+  };
+  const exitCode = summary.error > 0 ? ExitCode.DOCTOR_HAS_ERRORS : summary.warn > 0 ? ExitCode.DOCTOR_HAS_WARNINGS : ExitCode.OK;
+  const statusIcon = { pass: "\u2713", warn: "\u26A0", error: "\u2717" };
+  const lines = checks.map((c) => {
+    const icon = statusIcon[c.status];
+    const padded = c.label.padEnd(24);
+    return `  ${icon} ${padded} ${c.detail}`;
+  });
+  lines.push("");
+  lines.push(`${summary.pass} pass \xB7 ${summary.warn} warn \xB7 ${summary.error} error`);
+  const humanHint = lines.join("\n");
+  return { exitCode, result: ok({ checks, summary, humanHint }) };
+}
+
+// src/commands/archive.ts
+import { rename as rename3, mkdir as mkdir5, readFile as readFile13, writeFile as writeFile6 } from "fs/promises";
+import { join as join16, dirname as dirname7 } from "path";
+async function runArchive(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  let relPath;
+  if (input.page.includes("/")) {
+    relPath = scan.data.typedKnowledge.find((p) => p.relPath === input.page)?.relPath;
+  } else {
+    relPath = scan.data.typedKnowledge.find((p) => p.relPath.replace(/\.md$/, "").split("/").pop() === input.page)?.relPath;
+  }
+  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 = join16("_archive", relPath);
+  await mkdir5(dirname7(join16(input.vault, archivePath)), { recursive: true });
+  let indexUpdated = false;
+  const indexPath = join16(input.vault, "index.md");
+  try {
+    const idx = await readFile13(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 writeFile6(indexPath, filtered.join("\n"), "utf8");
+      indexUpdated = true;
+    }
+  } catch (e) {
+    if (e?.code !== "ENOENT") throw e;
+  }
+  await rename3(join16(input.vault, relPath), join16(input.vault, archivePath));
+  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";
+
+// src/utils/fetch.ts
+async function controlledFetch(url, opts) {
+  let current = url;
+  for (let hop = 0; hop <= opts.maxRedirects; hop++) {
+    const guard = runFetchGuardSync({ url: current });
+    if (!guard.result.ok) return guard.result;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs);
+    let res;
+    try {
+      res = await fetch(current, { redirect: "manual", signal: ctrl.signal });
+    } catch (e) {
+      clearTimeout(timer);
+      if (e?.name === "AbortError") return err("FETCH_TIMEOUT", { url: current });
+      return err("FETCH_FAILED", { message: String(e) });
+    }
+    clearTimeout(timer);
+    if (res.status >= 300 && res.status < 400) {
+      const loc = res.headers.get("location");
+      if (!loc) return err("FETCH_FAILED", { reason: "redirect without Location" });
+      current = new URL(loc, current).toString();
+      continue;
+    }
+    const declared = Number(res.headers.get("content-length") ?? "0");
+    if (declared > opts.maxBytes) return err("FETCH_TOO_LARGE", { declared, limit: opts.maxBytes });
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength > opts.maxBytes) return err("FETCH_TOO_LARGE", { actual: buf.byteLength, limit: opts.maxBytes });
+    return ok({ url: current, status: res.status, body: new TextDecoder().decode(buf), bytes: buf.byteLength });
+  }
+  return err("FETCH_FAILED", { reason: "too many redirects", limit: opts.maxRedirects });
+}
+
+// src/commands/drift.ts
+var FETCH_OPTS = { timeoutMs: 1e4, maxBytes: 5e6, maxRedirects: 5 };
+async function runDrift(input) {
+  const doFetch = input.fetchFn ?? controlledFetch;
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const results = [];
+  for (const raw of scan.data.raw) {
+    const fm = extractFrontmatter(await readPage(raw));
+    if (!fm.ok) continue;
+    const sourceUrl = typeof fm.data.source_url === "string" ? fm.data.source_url : null;
+    const storedHash = typeof fm.data.sha256 === "string" ? fm.data.sha256 : null;
+    if (!sourceUrl || !storedHash) continue;
+    const resp = await doFetch(sourceUrl, FETCH_OPTS);
+    if (!resp.ok) {
+      results.push({
+        raw_path: raw.relPath,
+        source_url: sourceUrl,
+        stored_sha256: storedHash,
+        current_sha256: null,
+        status: "fetch_failed",
+        fetch_error: resp.error
+      });
+      continue;
+    }
+    const currentHash = createHash2("sha256").update(Buffer.from(resp.data.body, "utf8")).digest("hex");
+    const drifted2 = currentHash !== storedHash;
+    results.push({
+      raw_path: raw.relPath,
+      source_url: sourceUrl,
+      stored_sha256: storedHash,
+      current_sha256: currentHash,
+      status: drifted2 ? "drifted" : "unchanged"
+    });
+  }
+  const drifted = results.filter((r) => r.status === "drifted");
+  const fetchFailed = results.filter((r) => r.status === "fetch_failed");
+  const unchanged = results.filter((r) => r.status === "unchanged").length;
+  const exitCode = drifted.length > 0 ? ExitCode.DRIFT_DETECTED : ExitCode.OK;
+  const hintLines = [`scanned: ${results.length}, unchanged: ${unchanged}`];
+  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}`));
+  return {
+    exitCode,
+    result: ok({ scanned: results.length, drifted, fetch_failed: fetchFailed, unchanged, humanHint: hintLines.join("\n") })
+  };
+}
+
+// src/commands/migrate-citations.ts
+import { writeFile as writeFile7 } from "fs/promises";
+var MARKER_RE2 = /\^\[(raw\/[^\]]+)\]/g;
+function moveMarkersToParagraphEnd(body) {
+  const lines = body.split("\n");
+  const result = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trimStart().startsWith("```")) {
+      result.push(line);
+      if (!line.trimEnd().endsWith("```") || line.trim() === "```") {
+        for (let j = i + 1; j < lines.length; j++) {
+          result.push(lines[j]);
+          if (lines[j].trimStart().startsWith("```")) {
+            i = j;
+            break;
+          }
+        }
+      }
+      continue;
+    }
+    if (/^## Sources\b/.test(line.trim())) {
+      result.push(line);
+      continue;
+    }
+    const markers = [...line.matchAll(MARKER_RE2)];
+    if (markers.length === 0) {
+      result.push(line);
+      continue;
+    }
+    const proseOnly = line.replace(MARKER_RE2, "").trim();
+    if (proseOnly.length === 0) {
+      const markerStr = " " + markers.map((m) => m[0]).join(" ");
+      let merged = false;
+      for (let k = result.length - 1; k >= 0; k--) {
+        if (result[k].trim().length > 0) {
+          result[k] = result[k].trimEnd() + markerStr;
+          merged = true;
+          break;
+        }
+      }
+      if (!merged) result.push(line);
+      continue;
+    }
+    const lastMarkerIdx = line.lastIndexOf("^[raw/");
+    const afterLast = line.slice(lastMarkerIdx).replace(MARKER_RE2, "").trim();
+    const firstMarkerIdx = line.indexOf("^[raw/");
+    const beforeFirst = line.slice(0, firstMarkerIdx).trim();
+    const alreadyAtEnd = afterLast.length === 0 && (beforeFirst.length === 0 || /[.!?]\s*$/.test(beforeFirst));
+    if (alreadyAtEnd) {
+      result.push(line);
+      continue;
+    }
+    let cleaned = line.replace(/\s*\^\[raw\/[^\]]+\]\s*/g, " ").trimEnd();
+    cleaned = cleaned.replace(/  +/g, " ").trimEnd();
+    const markerStrings = markers.map((m) => m[0]);
+    if (cleaned.length > 0 && /[.!?]$/.test(cleaned)) {
+      cleaned += " " + markerStrings.join(" ");
+    } else if (cleaned.length > 0) {
+      cleaned += ". " + markerStrings.join(" ");
+    } else {
+      cleaned = markerStrings.join(" ");
+    }
+    result.push(cleaned);
+  }
+  return result.join("\n");
+}
+function buildSourcesFooter(targets) {
+  return "\n## Sources\n" + targets.map((t) => `- ^[${t}]`).join("\n") + "\n";
+}
+function reorderSourcesFm(rawFm, targets) {
+  const sourcesLineRe = /^sources:\s*\[([^\]]*)\]\s*$/m;
+  const match = rawFm.match(sourcesLineRe);
+  if (!match) return rawFm;
+  const existing = match[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter((s) => s.length > 0);
+  const targetSet = new Set(targets);
+  const reordered = [
+    ...targets,
+    ...existing.filter((s) => !targetSet.has(s))
+  ];
+  const newLine = `sources: [${reordered.join(", ")}]`;
+  return rawFm.replace(sourcesLineRe, newLine);
+}
+function removeExistingFooter(body) {
+  const footerRe = /\n## Sources\n[\s\S]*$/;
+  return body.replace(footerRe, "");
+}
+async function runMigrateCitations(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const migrated = [];
+  const skipped = [];
+  let unchanged = 0;
+  for (const page of scan.data.typedKnowledge) {
+    const text = await readPage(page);
+    const split = splitFrontmatter(text);
+    if (!split.ok) continue;
+    const { rawFrontmatter, body } = split.data;
+    const markers = extractCitationMarkers(body);
+    if (markers.length === 0) {
+      unchanged++;
+      continue;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const uniqueTargets = [];
+    for (const m of markers) {
+      if (!seen.has(m.target)) {
+        seen.add(m.target);
+        uniqueTargets.push(m.target);
+      }
+    }
+    const bodyWithoutFooter = removeExistingFooter(body);
+    const migratedBody = moveMarkersToParagraphEnd(bodyWithoutFooter);
+    const newFooter = buildSourcesFooter(uniqueTargets);
+    const newFm = reorderSourcesFm(rawFrontmatter, uniqueTargets);
+    const newText = `---
+${newFm}
+---
+${migratedBody}${newFooter}`;
+    if (newText === text) {
+      skipped.push(page.relPath);
+      continue;
+    }
+    if (!input.dryRun) {
+      await writeFile7(page.absPath, newText, "utf8");
+    }
+    migrated.push(page.relPath);
+  }
+  const exitCode = migrated.length > 0 ? ExitCode.MIGRATION_APPLIED : ExitCode.OK;
+  const hintLines = [`scanned: ${migrated.length + skipped.length + unchanged}`];
+  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}`);
+  return {
+    exitCode,
+    result: ok({
+      scanned: migrated.length + skipped.length + unchanged,
+      migrated,
+      skipped,
+      unchanged,
+      humanHint: hintLines.join("\n")
+    })
+  };
+}
+
+// src/commands/update.ts
+import { execSync as execSync2 } from "child_process";
+import { readFileSync as readFileSync3 } from "fs";
+async function runUpdate(input) {
+  const pkg2 = JSON.parse(
+    readFileSync3(new URL("../../package.json", import.meta.url), "utf8")
+  );
+  const currentVersion = pkg2.version;
+  const tag = input.distTag ?? "beta";
+  let latest;
+  try {
+    latest = execSync2(`npm view skillwiki@${tag} version`, {
+      encoding: "utf8",
+      timeout: 15e3
+    }).trim();
+  } catch (e) {
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err("PREFLIGHT_FAILED", { message: `Failed to query npm registry: ${String(e)}` })
+    };
+  }
+  const cache = {
+    lastCheck: Date.now(),
+    latestVersion: latest,
+    currentVersion
+  };
+  if (latest === currentVersion) {
+    writeCache(input.home, cache);
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        previousVersion: currentVersion,
+        newVersion: null,
+        wasAlreadyLatest: true,
+        humanHint: `Already on latest ${tag}: v${currentVersion}`
+      })
+    };
+  }
+  try {
+    execSync2(`npm install -g skillwiki@${tag}`, {
+      stdio: "pipe",
+      timeout: 6e4
+    });
+  } catch (e) {
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err("PREFLIGHT_FAILED", { message: `npm install failed: ${String(e)}` })
+    };
+  }
+  writeCache(input.home, { ...cache, updateAppliedAt: Date.now() });
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      previousVersion: currentVersion,
+      newVersion: latest,
+      wasAlreadyLatest: false,
+      humanHint: `Updated skillwiki ${currentVersion} \u2192 ${latest}`
     })
   };
 }
 
 // src/cli.ts
+var pkg = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
-program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version("0.2.0-beta.2");
+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) {
   if (program.opts().human) printHuman(r.result);
@@ -1257,7 +2252,7 @@ program.command("orphans [vault]").action(async (vault) => emit(await runOrphans
 })));
 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) => {
-  const skillsRoot = opts.skillsRoot ?? new URL("../../skills/", import.meta.url).pathname;
+  const skillsRoot = opts.skillsRoot ?? new URL("../skills/", import.meta.url).pathname;
   emit(await runInstall({ skillsRoot, target: opts.target, dryRun: !!opts.dryRun }));
 });
 program.command("path").option("--vault <dir>", "explicit vault override (runtime)").option("--target <dir>", "explicit target override (init-time)").option("--init-time", "use init-time chain instead of runtime", false).option("--explain", "include resolution chain in output", false).action(async (opts) => {
@@ -1279,7 +2274,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).action(async (opts) => {
+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").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({
@@ -1290,7 +2285,8 @@ program.command("init").option("--target <dir>", "explicit target directory").re
     domain: opts.domain,
     taxonomy,
     lang: opts.lang,
-    force: !!opts.force
+    force: !!opts.force,
+    noEnv: opts.env === false
   }));
 });
 async function resolveVaultArg(arg) {
@@ -1344,6 +2340,42 @@ program.command("lint [vault]").option("--days <n>", "stale threshold", (s) => p
     logThreshold: opts.logThreshold
   }));
 });
+var configCmd = program.command("config").description("manage skillwiki configuration");
+configCmd.command("get <key>").description("print the value of a config key").action(async (key) => emit(await runConfigGet({ key, home: process.env.HOME ?? "" })));
+configCmd.command("set <key> <value>").description("set a config key value").action(async (key, value) => emit(await runConfigSet({ key, value, home: process.env.HOME ?? "" })));
+configCmd.command("list").description("list all config key=value pairs").action(async () => emit(await runConfigList({ home: process.env.HOME ?? "" })));
+configCmd.command("path").description("print the config file path").action(async () => emit(await runConfigPath({ home: process.env.HOME ?? "" })));
+program.command("doctor").description("diagnose skillwiki setup issues").action(async () => emit(await runDoctor({
+  home: process.env.HOME ?? "",
+  envValue: process.env.WIKI_PATH,
+  argv: process.argv,
+  currentVersion: pkg.version
+})));
+program.command("archive <page> [vault]").description("archive a typed-knowledge page").action(async (page, vault) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runArchive({ vault: v.vault, page }));
+});
+program.command("drift [vault]").description("detect content drift in raw sources").action(async (vault) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runDrift({ vault: v.vault }));
+});
+program.command("dedup [vault]").description("detect duplicate raw sources by sha256").action(async (vault) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runDedup({ vault: v.vault }));
+});
+program.command("migrate-citations [vault]").description("migrate ^[raw/...] markers to paragraph-end citations").option("--dry-run", "preview changes without writing", false).action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runMigrateCitations({ vault: v.vault, dryRun: !!opts.dryRun }));
+});
+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
+})));
+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);