skillwiki 0.0.1 → 0.2.0-beta.10

package/dist/cli.js

@@ -0,0 +1,1937 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync } from "fs";
+import { Command } from "commander";
+
+// src/utils/output.ts
+function printJson(r) {
+  process.stdout.write(JSON.stringify(r) + "\n");
+}
+function printHuman(r) {
+  if (r.ok) {
+    if (typeof r.data === "object" && r.data !== null && "humanHint" in r.data) {
+      process.stdout.write(`${r.data.humanHint}
+`);
+    } else {
+      process.stdout.write(`OK
+${formatData(r.data)}
+`);
+    }
+  } else {
+    process.stdout.write(`ERR ${r.error}
+${r.detail !== void 0 ? formatData(r.detail) + "\n" : ""}`);
+  }
+}
+function formatData(d) {
+  if (d == null) return "";
+  if (typeof d === "string") return d;
+  return JSON.stringify(d, null, 2);
+}
+
+// src/commands/hash.ts
+import { readFile } from "fs/promises";
+import { createHash } from "crypto";
+
+// ../shared/src/exit-codes.ts
+var ExitCode = {
+  OK: 0,
+  FILE_NOT_FOUND: 2,
+  MISSING_CLOSING_DELIMITER: 3,
+  SCHEME_REJECTED: 4,
+  HOST_BLOCKED: 5,
+  MALFORMED_URL: 6,
+  INVALID_FRONTMATTER: 7,
+  SCHEMA_NOT_DETECTED: 8,
+  VAULT_PATH_INVALID: 9,
+  WRITE_FAILED: 10,
+  UNRESOLVED_MARKERS: 11,
+  SOURCES_INCONSISTENT: 12,
+  PREFLIGHT_FAILED: 13,
+  ATOMIC_COPY_FAILED: 14,
+  INIT_TARGET_NOT_EMPTY: 15,
+  BROKEN_WIKILINKS: 16,
+  TAG_NOT_IN_TAXONOMY: 17,
+  INDEX_INCOMPLETE: 18,
+  STALE_PAGE: 19,
+  PAGE_TOO_LARGE: 20,
+  LOG_ROTATE_NEEDED: 21,
+  LINT_HAS_WARNINGS: 22,
+  LINT_HAS_ERRORS: 23,
+  ENV_WRITE_CONFLICT: 24,
+  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
+function ok(data) {
+  return { ok: true, data };
+}
+function err(error, detail) {
+  return detail === void 0 ? { ok: false, error } : { ok: false, error, detail };
+}
+
+// ../shared/src/schemas.ts
+import { z } from "zod";
+var isoDate = z.string().refine((s) => {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) return false;
+  const d = /* @__PURE__ */ new Date(s + "T00:00:00Z");
+  return !Number.isNaN(d.getTime()) && s === d.toISOString().slice(0, 10);
+}, { message: "must be YYYY-MM-DD" });
+var wikilink = z.string().regex(/^\[\[[^\[\]]+\]\]$/, 'must be "[[name]]"');
+var TypedKnowledgeSchema = z.object({
+  title: z.string().min(1),
+  aliases: z.array(z.string()).optional(),
+  created: isoDate,
+  updated: isoDate,
+  type: z.enum(["entity", "concept", "comparison", "query", "summary"]),
+  tags: z.array(z.string()),
+  sources: z.array(z.string()).min(1),
+  confidence: z.enum(["high", "medium", "low"]).optional(),
+  contested: z.boolean().optional(),
+  contradictions: z.array(z.string()).optional(),
+  provenance: z.enum(["research", "project", "mixed"]).optional(),
+  provenance_projects: z.array(wikilink).optional(),
+  work_items: z.array(wikilink).optional()
+}).superRefine((v, ctx) => {
+  if (v.provenance && v.provenance !== "research" && (!v.provenance_projects || v.provenance_projects.length === 0)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance_projects"], message: "required when provenance != research" });
+  }
+});
+var sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
+var RawSourceSchema = z.object({
+  title: z.string().min(1),
+  source_url: z.string().url().nullable(),
+  ingested: isoDate,
+  ingested_by: z.enum(["wiki-ingest", "proj-work", "manual"]),
+  sha256: sha256Hex,
+  project: wikilink.optional(),
+  work_item: wikilink.optional(),
+  kind: z.enum(["postmortem", "session-log", "meeting-notes", "other"]).optional()
+}).superRefine((v, ctx) => {
+  const projectFields = [v.project, v.work_item, v.kind];
+  const present = projectFields.filter((x) => x !== void 0).length;
+  if (present !== 0 && present !== 3) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "project, work_item, kind must all be set together" });
+  }
+});
+var WorkItemSchema = z.object({
+  title: z.string().min(1),
+  aliases: z.array(z.string()).optional(),
+  created: isoDate,
+  updated: isoDate,
+  started: isoDate,
+  completed: isoDate.optional(),
+  kind: z.enum(["feature", "issue", "refactor", "decision"]),
+  status: z.enum(["planned", "in-progress", "completed", "abandoned"]),
+  priority: z.enum(["high", "medium", "low"]),
+  project: wikilink,
+  owner: wikilink.optional(),
+  parent: wikilink.optional(),
+  related: z.array(wikilink).optional(),
+  sources: z.array(z.string()).optional()
+}).superRefine((v, ctx) => {
+  if (v.status === "completed" && !v.completed) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["completed"], message: "required when status is completed" });
+  }
+});
+var CompoundSchema = z.object({
+  title: z.string().min(1),
+  aliases: z.array(z.string()).optional(),
+  created: isoDate,
+  updated: isoDate,
+  type: z.enum(["lesson", "pattern", "antipattern", "gotcha"]),
+  tags: z.array(z.string()),
+  confidence: z.enum(["high", "medium", "low"]),
+  contradicts: z.array(z.string()).optional(),
+  project: wikilink,
+  work_items: z.array(wikilink).min(1),
+  promoted_to: wikilink.optional(),
+  cssclasses: z.array(z.string()).optional()
+});
+function detectSchema(fm) {
+  const COMPOUND_TYPES = /* @__PURE__ */ new Set(["lesson", "pattern", "antipattern", "gotcha"]);
+  if (typeof fm.type === "string" && COMPOUND_TYPES.has(fm.type) && "project" in fm) return { schema: "compound" };
+  if ("type" in fm && "sources" in fm) return { schema: "typed-knowledge" };
+  if (typeof fm.sha256 === "string" && "ingested" in fm) return { schema: "raw" };
+  if ("kind" in fm && "status" in fm) return { schema: "work-item" };
+  return { schema: null };
+}
+
+// ../shared/src/blocked-hosts.ts
+var METADATA_HOSTS = [
+  "metadata.google.internal",
+  "metadata"
+];
+var METADATA_IPS = /* @__PURE__ */ new Set(["169.254.169.254"]);
+function ipv4ToInt(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let n = 0;
+  for (const p of parts) {
+    const v = Number(p);
+    if (!Number.isInteger(v) || v < 0 || v > 255) return null;
+    n = (n << 8) + v;
+  }
+  return n >>> 0;
+}
+function inRange(ip, baseStr, prefix) {
+  const ipN = ipv4ToInt(ip);
+  const baseN = ipv4ToInt(baseStr);
+  if (ipN === null || baseN === null) return false;
+  const mask = prefix === 0 ? 0 : ~0 << 32 - prefix >>> 0;
+  return (ipN & mask) === (baseN & mask);
+}
+function isBlockedHost(host) {
+  const lower = host.toLowerCase();
+  if (METADATA_HOSTS.includes(lower)) return true;
+  if (METADATA_IPS.has(host)) return true;
+  if (lower === "::1") return true;
+  if (lower.startsWith("fe80:")) return true;
+  if (ipv4ToInt(host) === null) return false;
+  if (inRange(host, "10.0.0.0", 8)) return true;
+  if (inRange(host, "172.16.0.0", 12)) return true;
+  if (inRange(host, "192.168.0.0", 16)) return true;
+  if (inRange(host, "169.254.0.0", 16)) return true;
+  if (inRange(host, "127.0.0.0", 8)) return true;
+  return false;
+}
+
+// src/parsers/frontmatter.ts
+import yaml from "js-yaml";
+var FM_OPEN = /^---\r?\n/;
+function splitFrontmatter(text) {
+  if (!FM_OPEN.test(text)) return ok({ rawFrontmatter: "", body: text, bodyStart: 0 });
+  const afterOpen = text.replace(FM_OPEN, "");
+  const closeIdx = afterOpen.search(/\r?\n---\r?\n/);
+  if (closeIdx === -1) return err("MISSING_CLOSING_DELIMITER");
+  const rawFrontmatter = afterOpen.slice(0, closeIdx);
+  const closeMatch = afterOpen.slice(closeIdx).match(/\r?\n---\r?\n/);
+  const bodyStart = text.length - (afterOpen.length - closeIdx - closeMatch[0].length);
+  const body = text.slice(bodyStart);
+  return ok({ rawFrontmatter, body, bodyStart });
+}
+function extractFrontmatter(text) {
+  const split = splitFrontmatter(text);
+  if (!split.ok) return split;
+  if (!split.data.rawFrontmatter) return ok({});
+  try {
+    const parsed = yaml.load(split.data.rawFrontmatter, { schema: yaml.JSON_SCHEMA });
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return ok({});
+    return ok(parsed);
+  } catch (e) {
+    return err("INVALID_FRONTMATTER", { message: e.message });
+  }
+}
+
+// src/commands/hash.ts
+async function runHash(input) {
+  let text;
+  try {
+    text = await readFile(input.file, "utf8");
+  } catch {
+    return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: input.file }) };
+  }
+  const split = splitFrontmatter(text);
+  if (!split.ok) return { exitCode: ExitCode.MISSING_CLOSING_DELIMITER, result: split };
+  const bodyBytes = Buffer.from(split.data.body, "utf8");
+  const sha256 = createHash("sha256").update(bodyBytes).digest("hex");
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({ path: input.file, sha256, byte_count: bodyBytes.byteLength, humanHint: sha256 })
+  };
+}
+
+// src/commands/fetch-guard.ts
+var REDACT_PARAMS = /* @__PURE__ */ new Set(["api_key", "token", "key", "auth", "password", "secret", "access_token"]);
+var PATH_TOKEN_RE = /[A-Fa-f0-9]{32,}|[A-Za-z0-9_\-]{40,}/g;
+function runFetchGuard(input) {
+  return Promise.resolve(runFetchGuardSync(input));
+}
+function runFetchGuardSync(input) {
+  let u;
+  try {
+    u = new URL(input.url);
+  } catch {
+    return { exitCode: ExitCode.MALFORMED_URL, result: err("MALFORMED_URL", { url: input.url }) };
+  }
+  const sanitized = sanitizeUrl(u);
+  if (u.protocol !== "https:") {
+    return {
+      exitCode: ExitCode.SCHEME_REJECTED,
+      result: err("SCHEME_REJECTED", { sanitized_url: sanitized, scheme: u.protocol })
+    };
+  }
+  if (isBlockedHost(u.hostname)) {
+    return {
+      exitCode: ExitCode.HOST_BLOCKED,
+      result: err("HOST_BLOCKED", { sanitized_url: sanitized, host: u.hostname })
+    };
+  }
+  return { exitCode: ExitCode.OK, result: ok({ allowed: true, sanitized_url: sanitized, humanHint: `ALLOWED: ${sanitized}` }) };
+}
+function sanitizeUrl(u) {
+  const clone = new URL(u.toString());
+  if (clone.username || clone.password) {
+    clone.username = "";
+    clone.password = "";
+  }
+  for (const k of Array.from(clone.searchParams.keys())) {
+    if (REDACT_PARAMS.has(k.toLowerCase())) clone.searchParams.set(k, "REDACTED");
+  }
+  let s = clone.toString();
+  s = s.replace(PATH_TOKEN_RE, "REDACTED");
+  return s;
+}
+
+// src/commands/validate.ts
+import { readFile as readFile2 } from "fs/promises";
+var SCHEMAS = {
+  "typed-knowledge": TypedKnowledgeSchema,
+  "raw": RawSourceSchema,
+  "work-item": WorkItemSchema,
+  "compound": CompoundSchema
+};
+async function runValidate(input) {
+  let text;
+  try {
+    text = await readFile2(input.file, "utf8");
+  } catch {
+    return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: input.file }) };
+  }
+  const fm = extractFrontmatter(text);
+  if (!fm.ok) {
+    if (fm.error === "MISSING_CLOSING_DELIMITER") {
+      return { exitCode: ExitCode.MISSING_CLOSING_DELIMITER, result: fm };
+    }
+    return { exitCode: ExitCode.INVALID_FRONTMATTER, result: fm };
+  }
+  const det = detectSchema(fm.data);
+  if (!det.schema) {
+    return { exitCode: ExitCode.SCHEMA_NOT_DETECTED, result: ok({ schema: null, valid: false, errors: [], humanHint: "schema not detected" }) };
+  }
+  const parsed = SCHEMAS[det.schema].safeParse(fm.data);
+  if (!parsed.success) {
+    const errors = parsed.error.issues.map((i) => ({ path: i.path.join("."), message: i.message }));
+    return {
+      exitCode: ExitCode.INVALID_FRONTMATTER,
+      result: ok({ schema: det.schema, valid: false, errors, humanHint: `INVALID (${det.schema})
+${errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}` })
+    };
+  }
+  return { exitCode: ExitCode.OK, result: ok({ schema: det.schema, valid: true, errors: [], humanHint: `VALID (${det.schema})` }) };
+}
+
+// src/commands/graph.ts
+import { writeFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+
+// src/utils/vault.ts
+import { readFile as readFile3, readdir, stat } from "fs/promises";
+import { join, relative, sep } from "path";
+var TYPED_DIRS = ["entities", "concepts", "comparisons", "queries"];
+async function scanVault(root) {
+  try {
+    await stat(join(root, "SCHEMA.md"));
+  } catch {
+    return err("VAULT_PATH_INVALID", { root, reason: "SCHEMA.md missing" });
+  }
+  const all = await walk(root);
+  const rels = all.map((p) => ({ absPath: p, relPath: relative(root, p).split(sep).join("/") }));
+  return ok({
+    root,
+    typedKnowledge: rels.filter((p) => TYPED_DIRS.some((d) => p.relPath.startsWith(d + "/"))),
+    raw: rels.filter((p) => p.relPath.startsWith("raw/")),
+    workItems: rels.filter((p) => /^projects\/[^/]+\/work\/[^/]+\/(spec|plan|log)\.md$/.test(p.relPath)),
+    compound: rels.filter((p) => /^projects\/[^/]+\/compound\//.test(p.relPath))
+  });
+}
+async function walk(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...await walk(p));
+    else if (e.isFile() && e.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+async function readPage(p) {
+  return readFile3(p.absPath, "utf8");
+}
+
+// src/parsers/wikilinks.ts
+var FENCE = /`[^`]*`|```[\s\S]*?```/g;
+function extractBodyWikilinks(body) {
+  const stripped = body.replace(FENCE, "");
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const re = /\[\[([^\[\]|]+)(?:\|[^\[\]]*)?\]\]/g;
+  let m;
+  while ((m = re.exec(stripped)) !== null) {
+    const target = m[1].trim();
+    if (!seen.has(target)) {
+      seen.add(target);
+      out.push(target);
+    }
+  }
+  return out;
+}
+
+// src/commands/graph.ts
+async function runGraphBuild(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const adjacency = {};
+  const slugToPath = {};
+  for (const p of scan.data.typedKnowledge) {
+    const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
+    slugToPath[slug] = p.relPath;
+  }
+  for (const p of scan.data.typedKnowledge) {
+    const text = await readPage(p);
+    const split = splitFrontmatter(text);
+    const body = split.ok ? split.data.body : text;
+    const links = extractBodyWikilinks(body);
+    adjacency[p.relPath] = links.map((slug) => slugToPath[slug.split("/").pop()]).filter((x) => Boolean(x));
+  }
+  const adamicAdar = computeAdamicAdar(adjacency);
+  const edge_count = Object.values(adjacency).reduce((acc, arr) => acc + arr.length, 0);
+  try {
+    await mkdir(dirname(input.out), { recursive: true });
+    await writeFile(input.out, JSON.stringify({ adjacency, adamicAdar }, null, 2));
+  } catch (e) {
+    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
+  }
+  return {
+    exitCode: ExitCode.OK,
+    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) {
+  const undirected = {};
+  for (const [a, neighbors] of Object.entries(adj)) {
+    undirected[a] ??= /* @__PURE__ */ new Set();
+    for (const b of neighbors) {
+      undirected[a].add(b);
+      undirected[b] ??= /* @__PURE__ */ new Set();
+      undirected[b].add(a);
+    }
+  }
+  const nodes = Object.keys(undirected);
+  const out = {};
+  for (let i = 0; i < nodes.length; i++) {
+    for (let j = i + 1; j < nodes.length; j++) {
+      const a = nodes[i], b = nodes[j];
+      const common = [...undirected[a]].filter((x) => undirected[b].has(x));
+      let score = 0;
+      for (const c of common) {
+        const deg = undirected[c].size;
+        if (deg > 1) score += 1 / Math.log(deg);
+      }
+      if (score > 0) {
+        out[a] ??= {};
+        out[a][b] = score;
+        out[b] ??= {};
+        out[b][a] = score;
+      }
+    }
+  }
+  return out;
+}
+
+// src/commands/overlap.ts
+async function runOverlap(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const sourcesByPage = {};
+  for (const p of scan.data.typedKnowledge) {
+    const fm = extractFrontmatter(await readPage(p));
+    if (!fm.ok) continue;
+    const srcs = fm.data.sources ?? [];
+    sourcesByPage[p.relPath] = new Set(srcs);
+  }
+  const parent = {};
+  for (const k of Object.keys(sourcesByPage)) parent[k] = k;
+  const find = (x) => parent[x] === x ? x : parent[x] = find(parent[x]);
+  const union = (a, b) => {
+    const ra = find(a), rb = find(b);
+    if (ra !== rb) parent[ra] = rb;
+  };
+  const pages = Object.keys(sourcesByPage);
+  for (let i = 0; i < pages.length; i++) {
+    for (let j = i + 1; j < pages.length; j++) {
+      const sa = sourcesByPage[pages[i]], sb = sourcesByPage[pages[j]];
+      const shared = [...sa].filter((x) => sb.has(x)).length;
+      if (shared > 0) union(pages[i], pages[j]);
+    }
+  }
+  const groups = {};
+  for (const p of pages) {
+    const r = find(p);
+    (groups[r] ??= []).push(p);
+  }
+  const clusters = Object.entries(groups).filter(([, m]) => m.length > 1).map(([id, members]) => {
+    let score = 0;
+    for (let i = 0; i < members.length; i++)
+      for (let j = i + 1; j < members.length; j++) {
+        const sa = sourcesByPage[members[i]], sb = sourcesByPage[members[j]];
+        score += [...sa].filter((x) => sb.has(x)).length;
+      }
+    return { id, members, score };
+  });
+  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, 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();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    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) {
+  const chain = [];
+  if (input.flag !== void 0 && input.flag.length > 0) {
+    if (input.explain) chain.push({ source: "flag", matched: true, value: input.flag });
+    return { path: input.flag, source: "flag", ...input.explain ? { chain } : {} };
+  }
+  if (input.explain) chain.push({ source: "flag", matched: false });
+  if (input.envValue !== void 0 && input.envValue.length > 0) {
+    if (input.explain) chain.push({ source: "env", matched: true, value: input.envValue });
+    return { path: input.envValue, source: "env", ...input.explain ? { chain } : {} };
+  }
+  if (input.explain) chain.push({ source: "env", matched: false });
+  const sw = await parseDotenvFile(join2(input.home, ".skillwiki", ".env"));
+  if (sw.WIKI_PATH !== void 0) {
+    if (input.explain) chain.push({ source: "skillwiki-dotenv", matched: true, value: sw.WIKI_PATH });
+    return { path: sw.WIKI_PATH, source: "skillwiki-dotenv", ...input.explain ? { chain } : {} };
+  }
+  if (input.explain) chain.push({ source: "skillwiki-dotenv", matched: false });
+  const hermes = await parseDotenvFile(join2(input.home, ".hermes", ".env"));
+  if (hermes.WIKI_PATH !== void 0) {
+    if (input.explain) chain.push({ source: "hermes-dotenv", matched: true, value: hermes.WIKI_PATH });
+    return { path: hermes.WIKI_PATH, source: "hermes-dotenv", ...input.explain ? { chain } : {} };
+  }
+  if (input.explain) chain.push({ source: "hermes-dotenv", matched: false });
+  const fallback = join2(input.home, "wiki");
+  if (input.explain) chain.push({ source: "default", matched: true, value: fallback });
+  return { path: fallback, source: "default", ...input.explain ? { chain } : {} };
+}
+async function resolveRuntimePath(input) {
+  const chain = [];
+  if (input.flag !== void 0 && input.flag.length > 0) {
+    if (input.explain) chain.push({ source: "flag", matched: true, value: input.flag });
+    return ok({ path: input.flag, source: "flag", ...input.explain ? { chain } : {} });
+  }
+  if (input.explain) chain.push({ source: "flag", matched: false });
+  if (input.envValue !== void 0 && input.envValue.length > 0) {
+    if (input.explain) chain.push({ source: "env", matched: true, value: input.envValue });
+    return ok({ path: input.envValue, source: "env", ...input.explain ? { chain } : {} });
+  }
+  if (input.explain) chain.push({ source: "env", matched: false });
+  const sw = await parseDotenvFile(join2(input.home, ".skillwiki", ".env"));
+  if (sw.WIKI_PATH !== void 0) {
+    if (input.explain) chain.push({ source: "skillwiki-dotenv", matched: true, value: sw.WIKI_PATH });
+    return ok({ path: sw.WIKI_PATH, source: "skillwiki-dotenv", ...input.explain ? { chain } : {} });
+  }
+  if (input.explain) chain.push({ source: "skillwiki-dotenv", matched: false });
+  return err("NO_VAULT_CONFIGURED", {
+    message: "No vault configured. Run `skillwiki init` to bootstrap one, or pass `--vault <dir>`."
+  });
+}
+
+// src/commands/orphans.ts
+async function runOrphans(input) {
+  let vault;
+  if (input.vault) {
+    vault = input.vault;
+  } else {
+    const r = await resolveRuntimePath({ flag: void 0, envValue: input.envValue, home: input.home ?? "" });
+    if (!r.ok) return { exitCode: ExitCode.NO_VAULT_CONFIGURED, result: r };
+    vault = r.data.path;
+  }
+  const scan = await scanVault(vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const slugToPath = {};
+  for (const p of scan.data.typedKnowledge) {
+    slugToPath[p.relPath.replace(/\.md$/, "").split("/").pop()] = p.relPath;
+  }
+  const adj = {};
+  for (const p of scan.data.typedKnowledge) adj[p.relPath] = /* @__PURE__ */ new Set();
+  for (const p of scan.data.typedKnowledge) {
+    const text = await readPage(p);
+    const split = splitFrontmatter(text);
+    const body = split.ok ? split.data.body : text;
+    for (const slug of extractBodyWikilinks(body)) {
+      const tgt = slugToPath[slug.split("/").pop()];
+      if (tgt) {
+        adj[p.relPath].add(tgt);
+        adj[tgt].add(p.relPath);
+      }
+    }
+  }
+  const orphans = Object.keys(adj).filter((k) => adj[k].size === 0);
+  const componentOf = {};
+  let cid = 0;
+  for (const node of Object.keys(adj)) {
+    if (componentOf[node] !== void 0) continue;
+    const stack = [node];
+    while (stack.length) {
+      const n = stack.pop();
+      if (componentOf[n] !== void 0) continue;
+      componentOf[n] = cid;
+      for (const nb of adj[n]) stack.push(nb);
+    }
+    cid++;
+  }
+  const bridges = [];
+  for (const node of Object.keys(adj)) {
+    const neighborComps = new Set([...adj[node]].map((n) => componentOf[n]));
+    if (adj[node].size >= 2 && neighborComps.size === 1) {
+      const without = simulateRemoval(adj, node);
+      if (without > Object.values(componentOf).filter((v, i, a) => a.indexOf(v) === i).length) {
+        bridges.push({ path: node, connects: [...adj[node]] });
+      }
+    }
+  }
+  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();
+  let comps = 0;
+  for (const start of Object.keys(adj)) {
+    if (start === removed || seen.has(start)) continue;
+    comps++;
+    const stack = [start];
+    while (stack.length) {
+      const n = stack.pop();
+      if (seen.has(n) || n === removed) continue;
+      seen.add(n);
+      for (const nb of adj[n]) if (nb !== removed) stack.push(nb);
+    }
+  }
+  return comps;
+}
+
+// src/commands/audit.ts
+import { readFile as readFile5, stat as stat2 } from "fs/promises";
+import { dirname as dirname3, resolve, join as join3 } from "path";
+
+// src/parsers/citations.ts
+var FENCE2 = /```[\s\S]*?```/g;
+function extractCitationMarkers(body) {
+  const stripped = body.replace(FENCE2, "");
+  const out = [];
+  const re = /\^\[(raw\/[^\]]+)\]/g;
+  let m;
+  while ((m = re.exec(stripped)) !== null) {
+    out.push({ marker: m[0], target: m[1] });
+  }
+  return out;
+}
+
+// src/commands/audit.ts
+async function runAudit(input) {
+  let text;
+  try {
+    text = await readFile5(input.file, "utf8");
+  } catch {
+    return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: input.file }) };
+  }
+  const fm = extractFrontmatter(text);
+  if (!fm.ok) return { exitCode: ExitCode.INVALID_FRONTMATTER, result: fm };
+  const split = splitFrontmatter(text);
+  const body = split.ok ? split.data.body : text;
+  const vault = await findVaultRoot(dirname3(resolve(input.file)));
+  if (!vault) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID") };
+  const markers = extractCitationMarkers(body);
+  const resolved = await Promise.all(markers.map(async (m) => {
+    try {
+      await stat2(join3(vault, m.target));
+      return { ...m, resolved: true };
+    } catch {
+      return { ...m, resolved: false };
+    }
+  }));
+  const sources = fm.data.sources ?? [];
+  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 }, 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 }, humanHint }) };
+  }
+  return { exitCode: ExitCode.OK, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources }, humanHint }) };
+}
+async function findVaultRoot(start) {
+  let cur = start;
+  for (let i = 0; i < 20; i++) {
+    try {
+      await stat2(join3(cur, "SCHEMA.md"));
+      return cur;
+    } catch {
+    }
+    const parent = dirname3(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+  return null;
+}
+
+// src/commands/install.ts
+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 mkdir3, rename, writeFile as writeFile3, stat as stat3 } from "fs/promises";
+import { dirname as dirname4 } from "path";
+async function atomicCopyWithBackup(src, dst) {
+  await mkdir3(dirname4(dst), { recursive: true });
+  let backupPath = null;
+  try {
+    await stat3(dst);
+    backupPath = `${dst}.bak`;
+    await copyFile(dst, backupPath);
+  } catch {
+  }
+  const tmp = `${dst}.tmp.${process.pid}`;
+  try {
+    await copyFile(src, tmp);
+    await rename(tmp, dst);
+  } catch (e) {
+    return err("ATOMIC_COPY_FAILED", { message: String(e) });
+  }
+  return ok({ copied: true, backupPath });
+}
+async function writeManifest(path, m) {
+  await mkdir3(dirname4(path), { recursive: true });
+  const enriched = { installed_at: (/* @__PURE__ */ new Date()).toISOString(), ...m };
+  await writeFile3(path, JSON.stringify(enriched, null, 2));
+}
+
+// src/commands/install.ts
+async function runInstall(input) {
+  let entries;
+  try {
+    entries = (await readdir2(input.skillsRoot, { withFileTypes: true })).filter((d) => d.isDirectory() && (d.name.startsWith("wiki-") || d.name.startsWith("proj-"))).map((d) => d.name);
+  } catch (e) {
+    return { exitCode: ExitCode.PREFLIGHT_FAILED, result: err("PREFLIGHT_FAILED", { message: String(e) }) };
+  }
+  if (entries.length === 0) {
+    return { exitCode: ExitCode.PREFLIGHT_FAILED, result: err("PREFLIGHT_FAILED", { reason: "no skills found" }) };
+  }
+  const installed = [];
+  const backed_up = [];
+  for (const name of entries) {
+    const src = join4(input.skillsRoot, name, "SKILL.md");
+    const dst = join4(input.target, name, "SKILL.md");
+    try {
+      await stat4(src);
+    } catch {
+      return { exitCode: ExitCode.PREFLIGHT_FAILED, result: err("PREFLIGHT_FAILED", { missing: src }) };
+    }
+    if (input.dryRun) {
+      installed.push(dst);
+      continue;
+    }
+    const r = await atomicCopyWithBackup(src, dst);
+    if (!r.ok) return { exitCode: ExitCode.ATOMIC_COPY_FAILED, result: r };
+    installed.push(dst);
+    if (r.data.backupPath) backed_up.push(r.data.backupPath);
+  }
+  const manifest_path = join4(input.target, "wiki-manifest.json");
+  if (!input.dryRun) await writeManifest(manifest_path, { installed, backed_up });
+  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
+async function runPath(input) {
+  if (input.initTime) {
+    const r2 = await resolveInitTimePath({
+      flag: input.flag,
+      envValue: input.envValue,
+      home: input.home,
+      explain: input.explain
+    });
+    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,
+    envValue: input.envValue,
+    home: input.home,
+    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 } : {}, humanHint: `${r.data.path} (via ${r.data.source})` }) };
+}
+
+// src/utils/lang.ts
+import { join as join5 } from "path";
+var ALIASES = {
+  english: "en",
+  en: "en",
+  "chinese-traditional": "zh-Hant",
+  "zh-hant": "zh-Hant",
+  "zh-tw": "zh-Hant",
+  "chinese-simplified": "zh-Hans",
+  "zh-hans": "zh-Hans",
+  "zh-cn": "zh-Hans"
+};
+function normalizeLang(input) {
+  const trimmed = input.trim();
+  const key = trimmed.toLowerCase();
+  return ALIASES[key] ?? trimmed;
+}
+async function resolveLang(input) {
+  if (input.flag !== void 0 && input.flag.length > 0) {
+    return { value: input.flag, source: "flag", canonical: normalizeLang(input.flag) };
+  }
+  if (input.envValue !== void 0 && input.envValue.length > 0) {
+    return { value: input.envValue, source: "env", canonical: normalizeLang(input.envValue) };
+  }
+  const dotenv = await parseDotenvFile(join5(input.home, ".skillwiki", ".env"));
+  if (dotenv.WIKI_LANG !== void 0) {
+    return { value: dotenv.WIKI_LANG, source: "skillwiki-dotenv", canonical: normalizeLang(dotenv.WIKI_LANG) };
+  }
+  return { value: "en", source: "default", canonical: "en" };
+}
+
+// src/commands/lang.ts
+import { join as join6 } from "path";
+async function runLang(input) {
+  const resolved = await resolveLang({ flag: input.flag, envValue: input.envValue, home: input.home });
+  let chain;
+  if (input.explain) {
+    chain = [
+      { source: "flag", matched: input.flag !== void 0 && input.flag.length > 0, value: input.flag },
+      { source: "env", matched: input.envValue !== void 0 && input.envValue.length > 0, value: input.envValue }
+    ];
+    const sw = await parseDotenvFile(join6(input.home, ".skillwiki", ".env"));
+    chain.push({ source: "skillwiki-dotenv", matched: sw.WIKI_LANG !== void 0, value: sw.WIKI_LANG });
+    chain.push({ source: "default", matched: resolved.source === "default", value: "en" });
+  }
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      value: resolved.value,
+      source: resolved.source,
+      canonical: resolved.canonical,
+      ...chain ? { chain } : {},
+      humanHint: `${resolved.value} (via ${resolved.source})`
+    })
+  };
+}
+
+// src/commands/init.ts
+import { mkdir as mkdir4, readFile as readFile6, readdir as readdir3, writeFile as writeFile4 } from "fs/promises";
+import { join as join7 } from "path";
+
+// 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",
+  "timeline",
+  "summary",
+  "person",
+  "organization",
+  "concept",
+  "technique",
+  "tool",
+  "model"
+];
+var VAULT_DIRS = [
+  "raw/articles",
+  "raw/papers",
+  "raw/transcripts",
+  "raw/assets",
+  "entities",
+  "concepts",
+  "comparisons",
+  "queries",
+  "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 oldSchemaText;
+  try {
+    oldSchemaText = await readFile6(join7(target, "SCHEMA.md"), "utf8");
+  } catch {
+  }
+  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");
+  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 {
+      exitCode: ExitCode.ENV_WRITE_CONFLICT,
+      result: err("ENV_WRITE_CONFLICT", { key: "WIKI_PATH", existing: existingEnv.WIKI_PATH, attempted: target })
+    };
+  }
+  if (existingEnv.WIKI_LANG !== void 0 && existingEnv.WIKI_LANG !== canonicalLang && !input.force) {
+    return {
+      exitCode: ExitCode.ENV_WRITE_CONFLICT,
+      result: err("ENV_WRITE_CONFLICT", { key: "WIKI_LANG", existing: existingEnv.WIKI_LANG, attempted: canonicalLang })
+    };
+  }
+  const created = [];
+  try {
+    await mkdir4(target, { recursive: true });
+    for (const d of VAULT_DIRS) {
+      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);
+  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}}", 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) }) };
+  }
+  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) }) };
+    }
+  }
+  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,
+      taxonomy,
+      lang: canonicalLang,
+      created,
+      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 = buildSlugMap(scan.data.typedKnowledge);
+  const broken = [];
+  for (const p of scan.data.typedKnowledge) {
+    const text = await readPage(p);
+    const split = splitFrontmatter(text);
+    const body = split.ok ? split.data.body : text;
+    const lines = body.split("\n");
+    for (const slug of extractBodyWikilinks(body)) {
+      const tail = slug.split("/").pop();
+      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, humanHint: `broken: ${broken.length}
+${broken.map((b) => `  ${b.page}:[[${b.slug}]] (line ${b.line})`).join("\n")}` }) };
+  }
+  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";
+async function runTagAudit(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const schemaText = await readFile7(join8(input.vault, "SCHEMA.md"), "utf8");
+  const tax = extractTaxonomy(schemaText);
+  if (!tax.ok) return { exitCode: ExitCode.INVALID_FRONTMATTER, result: tax };
+  const allowed = new Set(tax.data);
+  const violations = [];
+  for (const p of scan.data.typedKnowledge) {
+    const text = await readPage(p);
+    const fm = extractFrontmatter(text);
+    if (!fm.ok) return { exitCode: ExitCode.INVALID_FRONTMATTER, result: fm };
+    const tags = fm.data.tags;
+    if (!Array.isArray(tags)) continue;
+    for (const t of tags) {
+      if (typeof t === "string" && !allowed.has(t)) {
+        violations.push({ page: p.relPath, tag: t });
+      }
+    }
+  }
+  if (violations.length > 0) {
+    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, humanHint: "all tags valid" }) };
+}
+
+// src/commands/index-check.ts
+import { readFile as readFile8 } from "fs/promises";
+import { join as join9 } from "path";
+async function runIndexCheck(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  let indexText = "";
+  try {
+    indexText = await readFile8(join9(input.vault, "index.md"), "utf8");
+  } catch {
+  }
+  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();
+    fileSlugs.set(slug, p.relPath);
+  }
+  const missing_from_index = [];
+  for (const [slug, relPath] of fileSlugs.entries()) {
+    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 [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, humanHint: hintLines.join("\n") }) };
+  }
+  return { exitCode: ExitCode.OK, result: ok({ missing_from_index, ghost_entries, humanHint: hintLines.join("\n") }) };
+}
+
+// src/commands/stale.ts
+import { readFile as readFile9 } from "fs/promises";
+import { join as join10 } from "path";
+function dayDiff(a, b) {
+  const da = Date.parse(a);
+  const db = Date.parse(b);
+  return Math.round((db - da) / 864e5);
+}
+async function runStale(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const stale = [];
+  for (const p of scan.data.typedKnowledge) {
+    const fm = extractFrontmatter(await readPage(p));
+    if (!fm.ok) continue;
+    const updated = typeof fm.data.updated === "string" ? fm.data.updated : void 0;
+    const sources = Array.isArray(fm.data.sources) ? fm.data.sources.filter((s) => typeof s === "string") : [];
+    if (!updated || sources.length === 0) continue;
+    let newest;
+    for (const rel of sources) {
+      let raw;
+      try {
+        raw = await readFile9(join10(input.vault, rel), "utf8");
+      } catch {
+        continue;
+      }
+      const rfm = extractFrontmatter(raw);
+      if (!rfm.ok) continue;
+      const ing = typeof rfm.data.ingested === "string" ? rfm.data.ingested : void 0;
+      if (ing && (!newest || Date.parse(ing) > Date.parse(newest))) newest = ing;
+    }
+    if (!newest) continue;
+    const gap = dayDiff(updated, newest);
+    if (gap > input.days) {
+      stale.push({ page: p.relPath, page_updated: updated, newest_source_ingested: newest, gap_days: gap });
+    }
+  }
+  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
+async function runPagesize(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const oversized = [];
+  for (const p of scan.data.typedKnowledge) {
+    const text = await readPage(p);
+    const split = splitFrontmatter(text);
+    const body = split.ok ? split.data.body : text;
+    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, 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 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 stat5(join11(input.vault, "SCHEMA.md"));
+  } catch {
+    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
+  }
+  const logPath = join11(input.vault, "log.md");
+  let logText;
+  try {
+    logText = await readFile10(logPath, "utf8");
+  } catch {
+    return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: logPath }) };
+  }
+  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, 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, humanHint: `${entries}/${input.threshold} entries \u2014 rotation needed (use --apply)` })
+    };
+  }
+  const newestYear = matches[matches.length - 1][1];
+  const rotatedName = `log-${newestYear}.md`;
+  const rotatedPath = join11(input.vault, rotatedName);
+  try {
+    await rename2(logPath, rotatedPath);
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const fresh = `# Vault Log
+
+Chronological action log. Newest entries last. Skill writes append entries; lint may rotate.
+
+## [${today}] rotate | Log rotated from ${entries} entries
+
+- Previous log moved to ${rotatedName}
+`;
+    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, 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_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 });
+  if (links.result.ok && links.result.data.broken.length > 0) buckets.broken_wikilinks = links.result.data.broken;
+  if (!links.result.ok && links.result.error === "INVALID_FRONTMATTER") {
+    buckets.invalid_frontmatter = [links.result.detail ?? {}];
+  }
+  const tags = await runTagAudit({ vault: input.vault });
+  if (tags.result.ok && tags.result.data.violations.length > 0) buckets.tag_not_in_taxonomy = tags.result.data.violations;
+  if (!tags.result.ok && tags.result.error === "INVALID_FRONTMATTER") {
+    buckets.invalid_frontmatter = [...buckets.invalid_frontmatter ?? [], tags.result.detail ?? {}];
+  }
+  const idx = await runIndexCheck({ vault: input.vault });
+  if (idx.result.ok && (idx.result.data.missing_from_index.length > 0 || idx.result.data.ghost_entries.length > 0)) {
+    buckets.index_incomplete = [{
+      missing_from_index: idx.result.data.missing_from_index,
+      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 });
+  if (pagesize.result.ok && pagesize.result.data.oversized.length > 0) buckets.page_too_large = pagesize.result.data.oversized;
+  const rotate = await runLogRotate({ vault: input.vault, threshold: input.logThreshold, apply: false });
+  if (rotate.result.ok && rotate.exitCode === ExitCode.LOG_ROTATE_NEEDED) {
+    buckets.log_rotate_needed = [{ entries: rotate.result.data.entries, threshold: rotate.result.data.threshold }];
+  }
+  const orphans = await runOrphans({ vault: input.vault });
+  if (orphans.result.ok) {
+    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] }] : []);
+  const summary = {
+    errors: errorOut.reduce((n, b) => n + b.items.length, 0),
+    warnings: warningOut.reduce((n, b) => n + b.items.length, 0),
+    info: infoOut.reduce((n, b) => n + b.items.length, 0)
+  };
+  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 },
+      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(pkg.version);
+program.option("--human", "render terminal-readable output instead of JSON");
+function emit(r) {
+  if (program.opts().human) printHuman(r.result);
+  else printJson(r.result);
+  process.exit(r.exitCode);
+}
+program.command("hash <file>").action(async (file) => emit(await runHash({ file })));
+program.command("fetch-guard <url>").action(async (url) => emit(await runFetchGuard({ url })));
+program.command("validate <file>").action(async (file) => emit(await runValidate({ file })));
+program.command("graph").description("graph subcommands").command("build <vault>").option("--out <path>", "graph output path", ".skillwiki/graph.json").action(async (vault, opts) => emit(await runGraphBuild({ vault, out: opts.out })));
+program.command("overlap <vault>").action(async (vault) => emit(await runOverlap({ vault })));
+program.command("orphans [vault]").action(async (vault) => emit(await runOrphans({
+  vault,
+  envValue: process.env.WIKI_PATH,
+  home: process.env.HOME ?? ""
+})));
+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;
+  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) => {
+  const initTime = !!opts.initTime;
+  const flag = initTime ? opts.target : opts.vault;
+  emit(await runPath({
+    flag,
+    envValue: process.env.WIKI_PATH,
+    home: process.env.HOME ?? "",
+    initTime,
+    explain: !!opts.explain
+  }));
+});
+program.command("lang").option("--lang <code>", "explicit language override").option("--explain", "include resolution chain in output", false).action(async (opts) => {
+  emit(await runLang({
+    flag: opts.lang,
+    envValue: process.env.WIKI_LANG,
+    home: process.env.HOME ?? "",
+    explain: !!opts.explain
+  }));
+});
+program.command("init").option("--target <dir>", "explicit target directory").requiredOption("--domain <text>", "knowledge domain seed").option("--taxonomy <csv>", "comma-separated tag list").option("--lang <code>", "output language (BCP 47 or alias)").option("--force", "override existing target / env conflict", false).option("--no-env", "skip writing ~/.skillwiki/.env").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({
+    flag: opts.target,
+    envValue: process.env.WIKI_PATH,
+    home: process.env.HOME ?? "",
+    templates,
+    domain: opts.domain,
+    taxonomy,
+    lang: opts.lang,
+    force: !!opts.force,
+    noEnv: opts.env === false
+  }));
+});
+async function resolveVaultArg(arg) {
+  if (arg) return { ok: true, vault: arg };
+  const r = await resolveRuntimePath({
+    flag: void 0,
+    envValue: process.env.WIKI_PATH,
+    home: process.env.HOME ?? ""
+  });
+  if (!r.ok) return { ok: false, exitCode: 25, payload: r };
+  return { ok: true, vault: r.data.path };
+}
+program.command("links [vault]").action(async (vault) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runLinks({ vault: v.vault }));
+});
+program.command("tag-audit [vault]").action(async (vault) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runTagAudit({ vault: v.vault }));
+});
+program.command("index-check [vault]").action(async (vault) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runIndexCheck({ vault: v.vault }));
+});
+program.command("stale [vault]").option("--days <n>", "staleness threshold in days", (s) => parseInt(s, 10), 90).action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runStale({ vault: v.vault, days: opts.days }));
+});
+program.command("pagesize [vault]").option("--lines <n>", "max body lines", (s) => parseInt(s, 10), 200).action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runPagesize({ vault: v.vault, lines: opts.lines }));
+});
+program.command("log-rotate [vault]").option("--threshold <n>", "entry count threshold", (s) => parseInt(s, 10), 500).option("--apply", "actually rotate", false).action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runLogRotate({ vault: v.vault, threshold: opts.threshold, apply: !!opts.apply }));
+});
+program.command("lint [vault]").option("--days <n>", "stale threshold", (s) => parseInt(s, 10), 90).option("--lines <n>", "pagesize threshold", (s) => parseInt(s, 10), 200).option("--log-threshold <n>", "log rotation threshold", (s) => parseInt(s, 10), 500).action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runLint({
+    vault: v.vault,
+    source: vault ? "flag" : void 0,
+    days: opts.days,
+    lines: opts.lines,
+    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);
+});