skillwiki 0.2.0-beta.7 → 0.2.0-beta.8

package/dist/cli.js

@@ -63,7 +63,10 @@ var ExitCode = {
   INVALID_CONFIG_KEY: 26,
   CONFIG_WRITE_FAILED: 27,
   DOCTOR_HAS_WARNINGS: 28,
-  DOCTOR_HAS_ERRORS: 29
+  DOCTOR_HAS_ERRORS: 29,
+  ARCHIVE_TARGET_NOT_FOUND: 30,
+  ARCHIVE_ALREADY_ARCHIVED: 31,
+  DRIFT_DETECTED: 32
 };
 
 // ../shared/src/json-output.ts
@@ -241,7 +244,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 })
   };
 }
 
@@ -271,7 +274,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());
@@ -311,17 +314,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
@@ -407,7 +411,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) {
@@ -482,7 +487,8 @@ 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
@@ -668,7 +674,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();
@@ -731,13 +741,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;
@@ -817,7 +834,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
@@ -829,7 +851,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,
@@ -838,7 +860,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
@@ -892,7 +914,8 @@ async function runLang(input) {
       value: resolved.value,
       source: resolved.source,
       canonical: resolved.canonical,
-      ...chain ? { chain } : {}
+      ...chain ? { chain } : {},
+      humanHint: `${resolved.value} (via ${resolved.source})`
     })
   };
 }
@@ -1097,6 +1120,14 @@ async function runInit(input) {
     }
   }
   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({
@@ -1109,7 +1140,8 @@ async function runInit(input) {
       env_written: envWritten,
       env_skipped: skipEnv,
       imported_from_hermes: importedFromHermes,
-      discovered_tags
+      discovered_tags,
+      humanHint
     })
   };
 }
@@ -1144,9 +1176,10 @@ async function runLinks(input) {
     }
   }
   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
@@ -1173,9 +1206,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
@@ -1208,10 +1241,14 @@ async function runIndexCheck(input) {
   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
@@ -1251,8 +1288,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
@@ -1267,8 +1304,8 @@ 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
@@ -1291,12 +1328,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];
@@ -1317,13 +1354,51 @@ Chronological action log. Newest entries last. Skill writes append entries; lint
   } 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/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 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 });
@@ -1343,6 +1418,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 });
@@ -1356,6 +1435,10 @@ 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 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] }] : []);
@@ -1367,25 +1450,35 @@ 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 readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 import { existsSync } from "fs";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 function validateKey(key) {
   return CONFIG_KEYS.includes(key);
 }
 function configPath(home) {
-  return join12(home, ".skillwiki", ".env");
+  return join13(home, ".skillwiki", ".env");
 }
 async function runConfigGet(input) {
   if (!validateKey(input.key)) {
@@ -1403,7 +1496,7 @@ async function runConfigSet(input) {
   try {
     let originalContent;
     try {
-      originalContent = await readFile11(filePath, "utf8");
+      originalContent = await readFile12(filePath, "utf8");
     } catch {
     }
     const existing = originalContent !== void 0 ? parseDotenvText(originalContent) : {};
@@ -1426,7 +1519,7 @@ async function runConfigPath(input) {
 
 // src/commands/doctor.ts
 import { existsSync as existsSync2, readdirSync, statSync } from "fs";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 import { execSync } from "child_process";
 function check(status, id, label, detail) {
   return { id, label, status, detail };
@@ -1482,9 +1575,9 @@ function checkVaultStructure(resolvedPath) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
   }
   const missing = [];
-  if (!existsSync2(join13(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  if (!existsSync2(join14(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
   for (const dir of ["raw", "entities", "concepts", "meta"]) {
-    if (!existsSync2(join13(resolvedPath, dir))) missing.push(dir + "/");
+    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");
@@ -1492,7 +1585,7 @@ function checkVaultStructure(resolvedPath) {
   return check("error", "vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")}`);
 }
 function checkSkillsInstalled(home) {
-  const skillsDir = join13(home, ".claude", "skills");
+  const skillsDir = join14(home, ".claude", "skills");
   if (!existsSync2(skillsDir)) {
     return check("warn", "skills_installed", "Skills installed", `${skillsDir} not found`);
   }
@@ -1512,9 +1605,9 @@ function findSkillMd(dir) {
   }
   for (const entry of entries) {
     if (entry.isFile() && entry.name === "SKILL.md") {
-      results.push(join13(dir, entry.name));
+      results.push(join14(dir, entry.name));
     } else if (entry.isDirectory()) {
-      results.push(...findSkillMd(join13(dir, entry.name)));
+      results.push(...findSkillMd(join14(dir, entry.name)));
     }
   }
   return results;
@@ -1552,6 +1645,123 @@ async function runDoctor(input) {
   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();
@@ -1672,6 +1882,16 @@ program.command("doctor").description("diagnose skillwiki setup issues").action(
   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.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.8",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.8",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 11 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI (8 subcommands, JSON-by-default).",
   "author": {

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.8",
   "private": true,
   "files": [
     "wiki-*",

package/skills/proj-distill/SKILL.md

@@ -12,10 +12,32 @@ description: 2-step distillation (E4) — analyze project compound entry, then g
 Standard four + project context.
 
 ## Steps (E4 — 2-step pattern)
-1. **Step 1 — Analyze.** Read the source compound entry + linked work items. Output a candidate concept outline. STOP if no clear universal pattern is found — surface the reasoning instead of forcing a page.
-2. **Step 2 — Generate.** Compose the vault concept page with `provenance: project` and `provenance_projects: ["[[slug]]"]`. Validate with `npx skillwiki validate`.
-3. **Backlink.** Set `promoted_to: "[[concept-slug]]"` on the source compound entry.
-4. **Apply writes in order.** Vault concept page → backlink update → project `log.md` → vault `index.md` → vault `log.md`.
+
+### Source selection
+
+Check `projects/{slug}/compound/` first. If empty, fall back to retro
+entries in vault `log.md` (lines matching `## [YYYY-MM-DD] retro`).
+
+When reading retros as source material:
+- Collect all retros for the project, focusing on entries with
+  `Generalize?: yes`.
+- Group by recurring theme (≥2 occurrences across cycles).
+- Each group becomes a candidate concept outline.
+
+1. **Step 1 — Analyze.** Read the source compound entry + linked work
+   items (or retro groups from log.md). Output a candidate concept
+   outline. STOP if no clear universal pattern is found — surface the
+   reasoning instead of forcing a page.
+2. **Step 2 — Generate.** Compose the vault concept page with
+   `provenance: project` and
+   `provenance_projects: ["[[slug]]"]`. Validate with
+   `npx skillwiki validate`.
+3. **Backlink.** Set `promoted_to: "[[concept-slug]]"` on the source
+   compound entry. For retro-sourced distillation, skip backlink (log.md
+   entries are append-only) and instead add `sources:` citing the vault
+   log with date range.
+4. **Apply writes in order.** Vault concept page → backlink update →
+   project `log.md` → vault `index.md` → vault `log.md`.
 
 ## Stop conditions
 - No clear universal pattern.

package/skills/proj-work/SKILL.md

@@ -20,6 +20,25 @@ Standard four + project context (project README, last ~5 work logs).
 5. Manage status transitions: `planned` → `in-progress` → `completed` (set `completed:` date) or `abandoned`.
 6. Append vault `log.md` entry on creation and on each status transition.
 
+## Redirect Output
+
+After step 3 (output path override), emit redirect paths for the active PRD skill:
+
+> Work item created: projects/{slug}/work/YYYY-MM-DD-{work-slug}/
+>
+> Redirect paths for PRD skills:
+>   spec → <vault-root>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/spec.md
+>   plan → <vault-root>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/plan.md
+>
+> Pass these paths to your PRD skill (superpowers:brainstorming, superpowers:writing-plans,
+> CodeStable, or any other). Files land in the vault natively — no separate ingest needed.
+
+Rules:
+- Emit redirect paths as the first output after folder creation, before any PRD skill runs.
+- Resolve `<vault-root>` via `skillwiki path` (never hardcode).
+- proj-work does NOT invoke any PRD skill — it provides paths only.
+- If the PRD skill cannot accept custom save paths, fall back to manual `wiki-ingest`.
+
 ## Stop conditions
 - `validate` non-zero.
 - Conflicting work folder name.

package/skills/using-skillwiki/SKILL.md

@@ -20,6 +20,9 @@ Invoke a skillwiki skill when the user:
 - Wants a health check or lint on their vault
 - Mentions crystallizing a session into a note
 - Talks about project workspaces, ADRs, or distillation
+- Wants to archive or clean up old vault pages
+- Needs to detect source drift or re-ingest updated content
+- Has a spec/plan in a non-skillwiki format (CodeStable, RFC, AIDE)
 - Asks about their skillwiki configuration or setup health
 
 ## Skill Map
@@ -32,6 +35,9 @@ Invoke a skillwiki skill when the user:
 | `wiki-lint` | Vault health check (stale pages, oversized pages, log rotation) |
 | `wiki-crystallize` | Distill the current working session into a typed-knowledge page |
 | `wiki-audit` | Verify raw provenance references and source frontmatter integrity |
+| `wiki-archive` | Archive a typed-knowledge page — move to `_archive/`, remove from index |
+| `wiki-reingest` | Detect drift in raw sources (sha256 comparison) and re-ingest updated content |
+| `wiki-adapter-prd` | Map foreign PRD formats (CodeStable, RFC, AIDE, Hermes) into vault pages |
 | `proj-init` | Bootstrap a project workspace (README, requirements, architecture) |
 | `proj-work` | Open or run a work item under a project's work/ directory |
 | `proj-distill` | Distill project compound entries into vault concept pages |
@@ -41,7 +47,7 @@ Invoke a skillwiki skill when the user:
 
 All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
 
-Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`.
+Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`.
 
 Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to see current configuration.
 
@@ -55,3 +61,5 @@ Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to
 6. **Audit** (`wiki-audit`) — verify source integrity
 
 For longer-running project work, use `proj-init` → `proj-work` → `proj-distill` / `proj-decide`.
+
+Maintenance: **Archive** (`wiki-archive`) superseded pages, **Drift** (`wiki-reingest`) to detect stale sources, **Adapter** (`wiki-adapter-prd`) for foreign PRD format ingestion.

package/skills/wiki-adapter-prd/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: wiki-adapter-prd
+description: Map foreign PRD formats (CodeStable, RFCs, structured markdown) into skillwiki raw + typed-knowledge pages.
+---
+
+# wiki-adapter-prd
+
+## When This Skill Activates
+
+- User provides a document or URL in a non-skillwiki PRD format and wants it captured in the vault.
+- User mentions CodeStable, RFC, AIDE, or another structured design document format.
+- A foreign spec/plan needs to be normalized into the vault's raw + concept structure.
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate page prose in the resolved language. Frontmatter keys, file names, and structural markers stay English.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Recognized PRD Formats
+
+| Format | Structural cues |
+|--------|----------------|
+| CodeStable | `REQ-NNN` requirement IDs, `## Requirements` / `## Architecture` headers |
+| RFC | `## Motivation` / `## Proposal` / `## Drawbacks` headers |
+| AIDE directives | Specific YAML frontmatter keys (`aide-*`) |
+| Hermes spec | `N1`–`N18` normative requirement markers |
+| Generic structured | Clear `##` section hierarchy with requirements, decisions, or designs |
+
+If the format is unrecognized, treat as generic structured markdown and map by section hierarchy.
+
+## Mapping Strategy
+
+### Raw capture (verbatim)
+
+- Write the full source document to `raw/articles/<slug>.md` with RawSourceSchema frontmatter (`sha256`, `source_url`, `ingested`, `ingested_by: "wiki-ingest"`).
+- If the source is a URL, run `skillwiki fetch-guard <url>` first.
+- Run `skillwiki hash <raw-file>` to compute sha256.
+
+### Knowledge extraction
+
+Map source sections to typed-knowledge pages:
+
+| Source section | Target type | Notes |
+|----------------|-------------|-------|
+| Requirements list | `concepts/` or `entities/` | Each major requirement becomes its own page or a section in a compound page |
+| Architecture decisions | `concepts/` | Map to concept pages with `tags: [architecture]` |
+| Motivation / context | `entities/` | Capture as entity pages describing the system or component |
+| Trade-offs / comparisons | `comparisons/` | Create comparison pages when the source weighs alternatives |
+| Action items / next steps | Skip | Not knowledge — track in project work items instead |
+
+### Cross-reference handling
+
+- Requirement IDs (`REQ-NNN`, `N1`–`N18`) → preserve as frontmatter tags or inline references.
+- Internal links within the source → convert to `[[wikilinks]]` where corresponding pages exist.
+- External URLs → keep as-is in body text.
+
+## Steps
+
+0. Resolve vault and language: `skillwiki path` and `skillwiki lang`.
+1. Classify the input format using the structural cues above.
+2. If URL source: run `skillwiki fetch-guard <url>`, then fetch.
+3. Write raw capture: frontmatter + full body → `raw/articles/<slug>.md`.
+4. Run `skillwiki hash <raw-file>`, embed sha256.
+5. Generate typed-knowledge pages following the mapping strategy.
+6. For each page: run `skillwiki validate <page>`. If any fails, STOP.
+7. Write pages, then update `index.md` and `log.md`.
+
+## Provenance defaults
+
+- `provenance: research` (external PRD sources).
+- `sources: ["^[raw/articles/<slug>.md]"]` on every generated page.
+
+## Stop conditions
+
+- `fetch-guard` non-zero.
+- `validate` non-zero on any page.
+- sha256 already exists for the same source (skip — already ingested).
+
+## Forbidden
+
+- Skipping `fetch-guard` for URL sources.
+- Writing index/log before all pages validate.
+- Modifying existing raw files (N9).
+- Auto-generating pages for action items, timelines, or process steps — those are project management, not knowledge.

package/skills/wiki-archive/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: wiki-archive
+description: Archive a superseded typed-knowledge page. Moves page to _archive/, removes from index.md, logs the action.
+---
+
+# wiki-archive
+
+## When This Skill Activates
+
+- User wants to retire, supersede, or remove a typed-knowledge page from active use.
+- A page has been replaced by a newer version and should be kept for reference but excluded from lint and queries.
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate log entries in the resolved language.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Steps
+
+0. Resolve vault: `skillwiki path` and `skillwiki lang`.
+1. Identify the target page. Confirm with the user which page to archive (show full relPath).
+2. Run `skillwiki archive <page> [vault]`. Read the JSON output.
+3. Verify with `skillwiki index-check [vault]` — confirm no ghost entries remain.
+4. Append a `log.md` entry: `## [{date}] archive | {relPath} → _archive/{subdir}/`.
+
+## Reversibility
+
+Archiving is reversible: move the file back from `_archive/` to its original directory and re-add the wikilink entry to `index.md`. No data is deleted.
+
+## Stop conditions
+
+- `skillwiki archive` returns non-zero exit code (page not found, already archived, invalid vault).
+- User declines to proceed.
+
+## Forbidden
+
+- Archiving `raw/` files (N9 — raw is immutable).
+- Archiving without user confirmation.
+- Deleting files (archive moves, never deletes).

package/skills/wiki-ingest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiki-ingest
-description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Single-pass v1.
+description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Supports single and batch mode.
 ---
 
 # wiki-ingest
@@ -45,3 +45,14 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 - Skipping `fetch-guard`.
 - Updating `index.md` or `log.md` before all pages validate.
 - Modifying any existing file in `raw/`.
+
+## Batch Mode
+
+When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):
+
+1. **Loop per source.** Execute steps 1–5 for each source individually (guard → fetch → hash → generate → validate).
+2. **Accumulate, don't write yet.** Collect all raw files and pages in memory. Do not write `index.md` or `log.md` until every source has validated.
+3. **Fail fast.** If any page fails validation, STOP. Report all failures. Do not write index/log for any source.
+4. **Deduplication.** Before writing each raw file, check `sha256` against existing vault raw sources. Skip sources whose content is already present.
+5. **Single index/log update.** After all sources validate, write all raw files and pages, then update `index.md` and `log.md` once.
+6. **Progress.** After each source completes validation, report progress (e.g., "Validated 3/10 sources").

package/skills/wiki-reingest/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: wiki-reingest
+description: Detect and act on source drift. Runs skillwiki drift, reviews changes, archives old raw + ingests new content.
+---
+
+# wiki-reingest
+
+## When This Skill Activates
+
+- User wants to check if any vault sources have changed since ingestion.
+- Periodic drift check during lint or maintenance cycles.
+- User explicitly asks to re-ingest a specific source.
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate log entries in the resolved language.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Steps
+
+0. Resolve vault: `skillwiki path` and `skillwiki lang`.
+1. Run `skillwiki drift [vault]`. Read the JSON output.
+2. Present findings grouped by status:
+   - **drifted:** Source content has changed. Show stored vs current sha256.
+   - **fetch_failed:** Could not re-fetch. Show error details.
+   - **unchanged:** No action needed.
+3. For each drifted source, ask the user: archive old + ingest new, or skip?
+4. If the user approves re-ingest for a source:
+   a. Run `skillwiki archive <raw-path>` to archive the old raw file.
+   b. Follow the `wiki-ingest` skill to ingest the updated content as a new raw file.
+   c. Update any concept/entity pages that cite the old source to reference the new one.
+5. Append a `log.md` entry summarizing: scanned, drifted, re-ingested, skipped.
+
+## N9 Compliance
+
+Raw files are immutable (N9). Re-ingest never modifies an existing raw file. Instead:
+- Archive the old raw file (moves to `_archive/raw/`).
+- Create a new raw file with updated content and new sha256.
+- This preserves full provenance history.
+
+## Stop conditions
+
+- `skillwiki drift` returns non-zero exit code other than DRIFT_DETECTED.
+- User declines all re-ingest actions.
+- No raw sources have `source_url` (nothing to check).
+
+## Forbidden
+
+- Modifying files in `raw/` directly (N9).
+- Re-ingesting without user approval for each drifted source.
+- Skipping the drift check and assuming sources have changed.

package/templates/SCHEMA.md

@@ -51,3 +51,19 @@ Rule: every tag on every page MUST appear in this taxonomy. Add new tags here fi
 - Wikilinks in YAML: quoted, `"[[name]]"`. Body wikilinks: unquoted `[[name]]`.
 - Citations in body: `^[raw/...]` markers; every entry in `sources:` MUST appear in body.
 - sha256 in `raw/` frontmatter is computed by `skillwiki hash` over body bytes after closing `---`.
+
+## Obsidian Integration
+
+- **Attachment folder:** `raw/assets/` — binary assets (images, diagrams) live here.
+  Set Obsidian's "Attachment folder path" to `raw/assets` for automatic filing.
+- **Dataview queries** (read-only; do not replace index.md):
+
+```dataview
+LIST WHERE type = "concept" AND contains(tags, "architecture")
+```
+
+```dataview
+TABLE updated, length(sources) AS sources
+WHERE file.folder = "concepts"
+SORT updated DESC
+```