skillwiki 0.0.1 → 0.2.0-beta.2

package/dist/cli.js

@@ -0,0 +1,1350 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/utils/output.ts
+function printJson(r) {
+  process.stdout.write(JSON.stringify(r) + "\n");
+}
+function printHuman(r) {
+  if (r.ok) {
+    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
+};
+
+// ../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 })
+  };
+}
+
+// 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 }) };
+}
+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: [] }) };
+  }
+  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 })
+    };
+  }
+  return { exitCode: ExitCode.OK, result: ok({ schema: det.schema, valid: true, errors: [] }) };
+}
+
+// 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 })
+  };
+}
+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 };
+  });
+  return { exitCode: ExitCode.OK, result: ok({ clusters }) };
+}
+
+// src/utils/wiki-path.ts
+import { join as join2 } from "path";
+
+// src/utils/dotenv.ts
+import { readFile as readFile4 } from "fs/promises";
+var WHITELIST = /* @__PURE__ */ new Set(["WIKI_PATH", "WIKI_LANG"]);
+async function parseDotenvFile(path) {
+  let text;
+  try {
+    text = await readFile4(path, "utf8");
+  } catch {
+    return {};
+  }
+  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;
+}
+
+// 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]] });
+      }
+    }
+  }
+  return { exitCode: ExitCode.OK, result: ok({ orphans, bridges }) };
+}
+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 dirname2, 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(dirname2(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));
+  if (resolved.some((m) => !m.resolved)) {
+    return { exitCode: ExitCode.UNRESOLVED_MARKERS, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources } }) };
+  }
+  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.OK, result: ok({ markers: resolved, sources_consistency: { unused_sources, missing_from_sources } }) };
+}
+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 = dirname2(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 mkdir2, rename, writeFile as writeFile2, stat as stat3 } from "fs/promises";
+import { dirname as dirname3 } from "path";
+async function atomicCopyWithBackup(src, dst) {
+  await mkdir2(dirname3(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 mkdir2(dirname3(path), { recursive: true });
+  const enriched = { installed_at: (/* @__PURE__ */ new Date()).toISOString(), ...m };
+  await writeFile2(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 });
+  return { exitCode: ExitCode.OK, result: ok({ installed, backed_up, manifest_path }) };
+}
+
+// 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 } : {} }) };
+  }
+  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 } : {} }) };
+}
+
+// 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 } : {}
+    })
+  };
+}
+
+// src/commands/init.ts
+import { mkdir as mkdir3, readFile as readFile6, stat as stat5, writeFile as writeFile3 } from "fs/promises";
+import { join as join7, dirname as dirname4 } from "path";
+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"
+];
+async function runInit(input) {
+  const pathRes = await resolveInitTimePath({ flag: input.flag, envValue: input.envValue, home: input.home });
+  const target = pathRes.path;
+  const langRes = await resolveLang({ flag: input.lang, envValue: void 0, home: input.home });
+  const canonicalLang = langRes.canonical;
+  let hasSchema = false;
+  try {
+    await stat5(join7(target, "SCHEMA.md"));
+    hasSchema = true;
+  } catch {
+  }
+  if (hasSchema && !input.force) {
+    return {
+      exitCode: ExitCode.INIT_TARGET_NOT_EMPTY,
+      result: err("INIT_TARGET_NOT_EMPTY", { target })
+    };
+  }
+  const envPath = join7(input.home, ".skillwiki", ".env");
+  const existingEnv = await parseDotenvFile(envPath);
+  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 mkdir3(target, { recursive: true });
+    for (const d of VAULT_DIRS) {
+      await mkdir3(join7(target, d), { recursive: true });
+      created.push(d + "/");
+    }
+  } catch (e) {
+    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const taxonomy = input.taxonomy && input.taxonomy.length > 0 ? input.taxonomy : DEFAULT_TAXONOMY;
+  const taxonomyYaml = taxonomy.map((t) => `  - ${t}`).join("\n");
+  try {
+    const schemaTpl = await readFile6(join7(input.templates, "SCHEMA.md"), "utf8");
+    const schema = schemaTpl.replace("{{DOMAIN}}", input.domain).replace("{{WIKI_LANG}}", canonicalLang).replace("{{TAXONOMY_YAML}}", taxonomyYaml);
+    await writeFile3(join7(target, "SCHEMA.md"), schema, "utf8");
+    created.push("SCHEMA.md");
+  } catch (e) {
+    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "SCHEMA.md", message: String(e) }) };
+  }
+  try {
+    const idxTpl = await readFile6(join7(input.templates, "index.md"), "utf8");
+    const idx = idxTpl.replace("{{INIT_DATE}}", today);
+    await writeFile3(join7(target, "index.md"), idx, "utf8");
+    created.push("index.md");
+  } catch (e) {
+    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "index.md", message: String(e) }) };
+  }
+  try {
+    const logTpl = await readFile6(join7(input.templates, "log.md"), "utf8");
+    const log = logTpl.replace(/\{\{INIT_DATE\}\}/g, today).replace("{{DOMAIN}}", input.domain).replace("{{WIKI_LANG}}", canonicalLang);
+    await writeFile3(join7(target, "log.md"), log, "utf8");
+    created.push("log.md");
+  } catch (e) {
+    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "log.md", message: String(e) }) };
+  }
+  try {
+    await mkdir3(dirname4(envPath), { recursive: true });
+    const envBody = `WIKI_PATH=${target}
+WIKI_LANG=${canonicalLang}
+`;
+    await writeFile3(envPath, envBody, "utf8");
+  } catch (e) {
+    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: envPath, message: String(e) }) };
+  }
+  const importedFromHermes = pathRes.source === "hermes-dotenv" && !swDotenvHadPath;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      vault: target,
+      domain: input.domain,
+      taxonomy,
+      lang: canonicalLang,
+      created,
+      env_written: envPath,
+      imported_from_hermes: importedFromHermes
+    })
+  };
+}
+
+// src/commands/links.ts
+async function runLinks(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const slugs = /* @__PURE__ */ new Set();
+  for (const p of scan.data.typedKnowledge) {
+    slugs.add(p.relPath.replace(/\.md$/, "").split("/").pop());
+  }
+  const 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)) {
+        const line = lines.findIndex((l) => l.includes(`[[${slug}`));
+        broken.push({ page: p.relPath, slug, line: line >= 0 ? line + 1 : 0 });
+      }
+    }
+  }
+  if (broken.length > 0) {
+    return { exitCode: ExitCode.BROKEN_WIKILINKS, result: ok({ broken }) };
+  }
+  return { exitCode: ExitCode.OK, result: ok({ broken }) };
+}
+
+// src/commands/tag-audit.ts
+import { readFile as readFile7 } from "fs/promises";
+import { join as join8 } from "path";
+
+// src/parsers/taxonomy.ts
+import yaml2 from "js-yaml";
+var FENCE_RE = /^##\s+Tag Taxonomy\s*$[\s\S]*?```yaml\s*\n([\s\S]*?)\n```/m;
+function extractTaxonomy(schemaText) {
+  const m = schemaText.match(FENCE_RE);
+  if (!m) return ok([]);
+  let parsed;
+  try {
+    parsed = yaml2.load(m[1], { schema: yaml2.JSON_SCHEMA });
+  } catch (e) {
+    return err("INVALID_FRONTMATTER", { message: e.message });
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy block is not an object" });
+  }
+  const tax = parsed.taxonomy;
+  if (!Array.isArray(tax)) {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy key missing or not an array" });
+  }
+  if (!tax.every((x) => typeof x === "string")) {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy must be a list of strings" });
+  }
+  return ok(tax);
+}
+
+// src/commands/tag-audit.ts
+async function runTagAudit(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  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 }) };
+  }
+  return { exitCode: ExitCode.OK, result: ok({ violations, taxonomy: tax.data }) };
+}
+
+// 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 indexSlugs = new Set(extractBodyWikilinks(indexText).map((s) => s.split("/").pop()));
+  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 (!indexSlugs.has(slug)) missing_from_index.push(relPath);
+  }
+  const ghost_entries = [];
+  for (const slug of indexSlugs) {
+    if (!fileSlugs.has(slug)) ghost_entries.push(slug);
+  }
+  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.OK, result: ok({ missing_from_index, ghost_entries }) };
+}
+
+// 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 }) };
+  return { exitCode: ExitCode.OK, result: ok({ stale }) };
+}
+
+// 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 }) };
+  return { exitCode: ExitCode.OK, result: ok({ oversized }) };
+}
+
+// src/commands/log-rotate.ts
+import { readFile as readFile10, rename as rename2, writeFile as writeFile4, stat as stat6 } from "fs/promises";
+import { join as join11 } from "path";
+var ENTRY_RE = /^## \[(\d{4})-\d{2}-\d{2}\]/gm;
+async function runLogRotate(input) {
+  try {
+    await stat6(join11(input.vault, "SCHEMA.md"));
+  } 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 }) };
+  }
+  if (!input.apply) {
+    return {
+      exitCode: ExitCode.LOG_ROTATE_NEEDED,
+      result: ok({ entries, threshold: input.threshold, rotated: false })
+    };
+  }
+  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 writeFile4(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 }) };
+}
+
+// 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"];
+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 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 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;
+  return {
+    exitCode,
+    result: ok({
+      vault: { path: input.vault, source: input.source ?? "resolved" },
+      summary,
+      by_severity: { error: errorOut, warning: warningOut, info: infoOut }
+    })
+  };
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version("0.2.0-beta.2");
+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).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
+  }));
+});
+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
+  }));
+});
+program.parseAsync(process.argv).catch((e) => {
+  process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
+  process.exit(1);
+});