skillwiki 0.2.0-beta.1 → 0.2.0-beta.11

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { readFileSync } from "fs";
 import { Command } from "commander";
 
 // src/utils/output.ts
@@ -9,9 +10,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 +59,15 @@ 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
 };
 
 // ../shared/src/json-output.ts
@@ -231,7 +245,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 +275,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 +315,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 +412,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 +488,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 +509,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) {
@@ -609,7 +675,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,7 +700,7 @@ 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;
@@ -657,7 +727,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 +742,20 @@ 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 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 (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 }, 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 }, 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 }, humanHint }) };
 }
 async function findVaultRoot(start) {
   let cur = start;
@@ -688,7 +765,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 +777,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 +798,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 +835,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 +852,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 +861,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 +915,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 +975,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 +1043,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 +1170,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 +1207,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 +1223,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 +1235,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 +1289,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 +1305,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 +1329,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 +1351,86 @@ 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 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"];
+var INFO_ORDER = ["bridges", "low_confidence_single_source", "topic_map_recommended"];
 async function runLint(input) {
   const buckets = {};
   const links = await runLinks({ vault: input.vault });
@@ -1202,6 +1450,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 +1467,12 @@ 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 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 +1484,322 @@ 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 existsSync2, readdirSync, statSync } from "fs";
+import { join as join14 } from "path";
+import { execSync } from "child_process";
+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 (!existsSync2(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 (existsSync2(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 (!existsSync2(resolvedPath)) {
+    return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
+  }
+  const missing = [];
+  if (!existsSync2(join14(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  for (const dir of ["raw", "entities", "concepts", "meta"]) {
+    if (!existsSync2(join14(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 = join14(home, ".claude", "skills");
+  if (!existsSync2(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 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(join14(dir, entry.name));
+    } else if (entry.isDirectory()) {
+      results.push(...findSkillMd(join14(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));
+  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 join15, dirname as dirname6 } 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 = join15("_archive", relPath);
+  await mkdir5(dirname6(join15(input.vault, archivePath)), { recursive: true });
+  let indexUpdated = false;
+  const indexPath = join15(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(join15(input.vault, relPath), join15(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/cli.ts
+var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
-program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version("0.1.0");
+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 +1818,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 +1840,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 +1851,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 +1906,31 @@ 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
+})));
+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.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
   process.exit(1);