skillwiki 0.2.0-beta.4 → 0.2.0-beta.7

package/dist/cli.js

@@ -70,8 +70,8 @@ var ExitCode = {
 function ok(data) {
   return { ok: true, data };
 }
-function err(error2, detail) {
-  return detail === void 0 ? { ok: false, error: error2 } : { ok: false, error: error2, detail };
+function err(error, detail) {
+  return detail === void 0 ? { ok: false, error } : { ok: false, error, detail };
 }
 
 // ../shared/src/schemas.ts
@@ -491,14 +491,9 @@ 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 WHITELIST = /* @__PURE__ */ new Set(["WIKI_PATH", "WIKI_LANG"]);
-async function parseDotenvFile(path) {
-  let text;
-  try {
-    text = await readFile4(path, "utf8");
-  } catch {
-    return {};
-  }
+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();
@@ -507,12 +502,21 @@ async function parseDotenvFile(path) {
     if (eq <= 0) continue;
     const key = line.slice(0, eq).trim();
     const value = line.slice(eq + 1).trim();
-    if (!WHITELIST.has(key)) continue;
+    if (!_whitelist.has(key)) continue;
     if (value.length === 0) continue;
     out[key] = value;
   }
   return out;
 }
+async function parseDotenvFile(path) {
+  let text;
+  try {
+    text = await readFile4(path, "utf8");
+  } catch {
+    return {};
+  }
+  return parseDotenvText(text);
+}
 async function writeDotenv(filePath, entries, originalContent) {
   const lines = originalContent !== void 0 ? updateLines(originalContent, entries) : freshLines(entries);
   await mkdir2(dirname2(filePath), { recursive: true });
@@ -894,8 +898,35 @@ async function runLang(input) {
 }
 
 // src/commands/init.ts
-import { mkdir as mkdir4, readFile as readFile6, stat as stat5, writeFile as writeFile4 } from "fs/promises";
-import { join as join7, dirname as dirname5 } from "path";
+import { mkdir as mkdir4, readFile as readFile6, readdir as readdir3, writeFile as writeFile4 } from "fs/promises";
+import { join as join7 } from "path";
+
+// src/parsers/taxonomy.ts
+import yaml2 from "js-yaml";
+var FENCE_RE = /^##\s+Tag Taxonomy\s*$[\s\S]*?```yaml\s*\n([\s\S]*?)\n```/m;
+function extractTaxonomy(schemaText) {
+  const m = schemaText.match(FENCE_RE);
+  if (!m) return err("NO_TAXONOMY_BLOCK", { message: "No fenced YAML taxonomy block found in SCHEMA.md" });
+  let parsed;
+  try {
+    parsed = yaml2.load(m[1], { schema: yaml2.JSON_SCHEMA });
+  } catch (e) {
+    return err("INVALID_FRONTMATTER", { message: e.message });
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy block is not an object" });
+  }
+  const tax = parsed.taxonomy;
+  if (!Array.isArray(tax)) {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy key missing or not an array" });
+  }
+  if (!tax.every((x) => typeof x === "string")) {
+    return err("INVALID_FRONTMATTER", { message: "taxonomy must be a list of strings" });
+  }
+  return ok(tax);
+}
+
+// src/commands/init.ts
 var DEFAULT_TAXONOMY = [
   "research",
   "comparison",
@@ -920,25 +951,59 @@ var VAULT_DIRS = [
   "meta",
   "projects"
 ];
+function extractDomainFromSchema(text) {
+  const m = text.match(/^##\s+Domain\s*\n([\s\S]*?)(?=\n\n|\n##|\s*$)/m);
+  if (!m) return "";
+  const d = m[1].trim();
+  return d.startsWith("##") ? "" : d;
+}
+async function discoverTagsFromPages(target, knownSlugs) {
+  const knownSet = new Set(knownSlugs);
+  const discovered = /* @__PURE__ */ new Set();
+  for (const dir of ["entities", "concepts", "comparisons", "queries"]) {
+    let entries;
+    try {
+      entries = (await readdir3(join7(target, dir), { withFileTypes: true })).filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name);
+    } catch {
+      continue;
+    }
+    for (const file of entries) {
+      try {
+        const text = await readFile6(join7(target, dir, file), "utf8");
+        const fm = extractFrontmatter(text);
+        if (!fm.ok || !fm.data.tags || !Array.isArray(fm.data.tags)) continue;
+        for (const t of fm.data.tags) {
+          if (typeof t === "string" && !knownSet.has(t)) discovered.add(t);
+        }
+      } catch {
+      }
+    }
+  }
+  return [...discovered].sort();
+}
 async function runInit(input) {
   const pathRes = await resolveInitTimePath({ flag: input.flag, envValue: input.envValue, home: input.home });
   const target = pathRes.path;
   const langRes = await resolveLang({ flag: input.lang, envValue: void 0, home: input.home });
   const canonicalLang = langRes.canonical;
-  let hasSchema = false;
+  let oldSchemaText;
   try {
-    await stat5(join7(target, "SCHEMA.md"));
-    hasSchema = true;
+    oldSchemaText = await readFile6(join7(target, "SCHEMA.md"), "utf8");
   } catch {
   }
-  if (hasSchema && !input.force) {
+  if (oldSchemaText && !input.force) {
     return {
       exitCode: ExitCode.INIT_TARGET_NOT_EMPTY,
       result: err("INIT_TARGET_NOT_EMPTY", { target })
     };
   }
   const envPath = join7(input.home, ".skillwiki", ".env");
-  const existingEnv = await parseDotenvFile(envPath);
+  let existingEnvRaw = "";
+  try {
+    existingEnvRaw = await readFile6(envPath, "utf8");
+  } catch {
+  }
+  const existingEnv = parseDotenvText(existingEnvRaw);
   const swDotenvHadPath = existingEnv.WIKI_PATH !== void 0;
   if (existingEnv.WIKI_PATH !== void 0 && existingEnv.WIKI_PATH !== target && !input.force) {
     return {
@@ -963,64 +1028,107 @@ async function runInit(input) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
   }
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  const taxonomy = input.taxonomy && input.taxonomy.length > 0 ? input.taxonomy : DEFAULT_TAXONOMY;
-  const taxonomyYaml = taxonomy.map((t) => `  - ${t}`).join("\n");
+  let taxonomy = input.taxonomy && input.taxonomy.length > 0 ? input.taxonomy : DEFAULT_TAXONOMY;
+  let domain = input.domain;
+  let oldTaxonomy = [];
+  if (oldSchemaText) {
+    if (!domain) {
+      const oldDomain = extractDomainFromSchema(oldSchemaText);
+      if (oldDomain) domain = oldDomain;
+    }
+    const oldTax = extractTaxonomy(oldSchemaText);
+    if (oldTax.ok) oldTaxonomy = oldTax.data;
+  }
+  const taxonomySet = new Set(taxonomy);
+  for (const t of oldTaxonomy) {
+    if (!taxonomySet.has(t)) {
+      taxonomy.push(t);
+      taxonomySet.add(t);
+    }
+  }
+  const discovered = await discoverTagsFromPages(target, taxonomy);
+  const discovered_tags = discovered.length;
+  const fullTaxonomyYaml = discovered.length > 0 ? taxonomy.map((t) => `  - ${t}`).join("\n") + "\n  # --- Discovered from existing pages ---\n" + discovered.map((t) => `  - ${t}`).join("\n") : taxonomy.map((t) => `  - ${t}`).join("\n");
   try {
     const schemaTpl = await readFile6(join7(input.templates, "SCHEMA.md"), "utf8");
-    const schema = schemaTpl.replace("{{DOMAIN}}", input.domain).replace("{{WIKI_LANG}}", canonicalLang).replace("{{TAXONOMY_YAML}}", taxonomyYaml);
+    const schema = schemaTpl.replace("{{DOMAIN}}", domain).replace("{{WIKI_LANG}}", canonicalLang).replace("{{TAXONOMY_YAML}}", fullTaxonomyYaml);
     await writeFile4(join7(target, "SCHEMA.md"), schema, "utf8");
     created.push("SCHEMA.md");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "SCHEMA.md", message: String(e) }) };
   }
-  try {
-    const idxTpl = await readFile6(join7(input.templates, "index.md"), "utf8");
-    const idx = idxTpl.replace("{{INIT_DATE}}", today);
-    await writeFile4(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 writeFile4(join7(target, "log.md"), log, "utf8");
-    created.push("log.md");
-  } catch (e) {
-    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: "log.md", message: String(e) }) };
+  const preserved = [];
+  async function writeOrPreserve(fileName, render) {
+    try {
+      const existing = await readFile6(join7(target, fileName), "utf8");
+      if (existing.split("\n").length > 10) {
+        preserved.push(fileName);
+        return void 0;
+      }
+    } catch {
+    }
+    try {
+      await writeFile4(join7(target, fileName), await render(), "utf8");
+      created.push(fileName);
+      return void 0;
+    } catch (e) {
+      return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: fileName, message: String(e) }) };
+    }
   }
-  try {
-    await mkdir4(dirname5(envPath), { recursive: true });
-    const envBody = `WIKI_PATH=${target}
-WIKI_LANG=${canonicalLang}
-`;
-    await writeFile4(envPath, envBody, "utf8");
-  } catch (e) {
-    return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: envPath, message: String(e) }) };
+  const err1 = await writeOrPreserve("index.md", async () => {
+    const tpl = await readFile6(join7(input.templates, "index.md"), "utf8");
+    return tpl.replace("{{INIT_DATE}}", today);
+  });
+  if (err1) return err1;
+  const err2 = 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 (err2) return err2;
+  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;
   return {
     exitCode: ExitCode.OK,
     result: ok({
       vault: target,
-      domain: input.domain,
+      domain,
       taxonomy,
       lang: canonicalLang,
       created,
-      env_written: envPath,
-      imported_from_hermes: importedFromHermes
+      preserved,
+      env_written: envWritten,
+      env_skipped: skipEnv,
+      imported_from_hermes: importedFromHermes,
+      discovered_tags
     })
   };
 }
 
+// src/utils/slug.ts
+function buildSlugMap(pages) {
+  const map = /* @__PURE__ */ new Map();
+  for (const p of pages) {
+    const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
+    map.set(slug.toLowerCase(), slug);
+  }
+  return map;
+}
+
 // src/commands/links.ts
 async function runLinks(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const slugs = /* @__PURE__ */ new Set();
-  for (const p of scan.data.typedKnowledge) {
-    slugs.add(p.relPath.replace(/\.md$/, "").split("/").pop());
-  }
+  const slugs = buildSlugMap(scan.data.typedKnowledge);
   const broken = [];
   for (const p of scan.data.typedKnowledge) {
     const text = await readPage(p);
@@ -1029,7 +1137,7 @@ async function runLinks(input) {
     const lines = body.split("\n");
     for (const slug of extractBodyWikilinks(body)) {
       const tail = slug.split("/").pop();
-      if (!slugs.has(tail)) {
+      if (!slugs.has(tail.toLowerCase())) {
         const line = lines.findIndex((l) => l.includes(`[[${slug}`));
         broken.push({ page: p.relPath, slug, line: line >= 0 ? line + 1 : 0 });
       }
@@ -1044,33 +1152,6 @@ async function runLinks(input) {
 // 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 };
@@ -1108,7 +1189,11 @@ async function runIndexCheck(input) {
     indexText = await readFile8(join9(input.vault, "index.md"), "utf8");
   } catch {
   }
-  const indexSlugs = new Set(extractBodyWikilinks(indexText).map((s) => s.split("/").pop()));
+  const indexSlugsLower = /* @__PURE__ */ new Map();
+  for (const s of extractBodyWikilinks(indexText)) {
+    const tail = s.split("/").pop();
+    indexSlugsLower.set(tail.toLowerCase(), tail);
+  }
   const fileSlugs = /* @__PURE__ */ new Map();
   for (const p of scan.data.typedKnowledge) {
     const slug = p.relPath.replace(/\.md$/, "").split("/").pop();
@@ -1116,11 +1201,12 @@ async function runIndexCheck(input) {
   }
   const missing_from_index = [];
   for (const [slug, relPath] of fileSlugs.entries()) {
-    if (!indexSlugs.has(slug)) missing_from_index.push(relPath);
+    if (!indexSlugsLower.has(slug.toLowerCase())) missing_from_index.push(relPath);
   }
+  const fileSlugsLower = new Set([...fileSlugs.keys()].map((s) => s.toLowerCase()));
   const ghost_entries = [];
-  for (const slug of indexSlugs) {
-    if (!fileSlugs.has(slug)) ghost_entries.push(slug);
+  for (const [lower, orig] of indexSlugsLower) {
+    if (!fileSlugsLower.has(lower)) ghost_entries.push(orig);
   }
   if (missing_from_index.length > 0 || ghost_entries.length > 0) {
     return { exitCode: ExitCode.INDEX_INCOMPLETE, result: ok({ missing_from_index, ghost_entries }) };
@@ -1186,12 +1272,12 @@ async function runPagesize(input) {
 }
 
 // src/commands/log-rotate.ts
-import { readFile as readFile10, rename as rename2, writeFile as writeFile5, stat as stat6 } from "fs/promises";
+import { readFile as readFile10, rename as rename2, writeFile as writeFile5, stat as stat5 } from "fs/promises";
 import { join as join11 } from "path";
 var ENTRY_RE = /^## \[(\d{4})-\d{2}-\d{2}\]/gm;
 async function runLogRotate(input) {
   try {
-    await stat6(join11(input.vault, "SCHEMA.md"));
+    await stat5(join11(input.vault, "SCHEMA.md"));
   } catch {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
@@ -1296,7 +1382,7 @@ import { readFile as readFile11 } from "fs/promises";
 import { existsSync } from "fs";
 import { join as join12 } from "path";
 function validateKey(key) {
-  return key === "WIKI_PATH" || key === "WIKI_LANG";
+  return CONFIG_KEYS.includes(key);
 }
 function configPath(home) {
   return join12(home, ".skillwiki", ".env");
@@ -1320,7 +1406,7 @@ async function runConfigSet(input) {
       originalContent = await readFile11(filePath, "utf8");
     } catch {
     }
-    const existing = originalContent !== void 0 ? await parseDotenvFile(filePath) : {};
+    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}` }) };
@@ -1342,71 +1428,58 @@ async function runConfigPath(input) {
 import { existsSync as existsSync2, readdirSync, statSync } from "fs";
 import { join as join13 } from "path";
 import { execSync } from "child_process";
-function pass(id, label, detail) {
-  return { id, label, status: "pass", detail };
-}
-function warn(id, label, detail) {
-  return { id, label, status: "warn", detail };
-}
-function error(id, label, detail) {
-  return { id, label, status: "error", detail };
+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 pass("node_version", "Node.js version", `v${major} >= 20`);
+    return check("pass", "node_version", "Node.js version", `v${major} >= 20`);
   }
-  return error("node_version", "Node.js version", `Node.js v${major} is below minimum v20`);
+  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 warn("cli_on_path", "skillwiki on PATH", "Running via node cli.js (dev mode) \u2014 PATH check skipped");
+    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 pass("cli_on_path", "skillwiki on PATH", "Running as skillwiki \u2014 already on PATH");
+    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 pass("cli_on_path", "skillwiki on PATH", "skillwiki found on PATH");
+    return check("pass", "cli_on_path", "skillwiki on PATH", "skillwiki found on PATH");
   } catch {
-    return warn("cli_on_path", "skillwiki on PATH", "skillwiki not found on PATH");
+    return check("warn", "cli_on_path", "skillwiki on PATH", "skillwiki not found on PATH");
   }
 }
 async function checkConfigFile(home) {
-  const cfgPath = join13(home, ".skillwiki", ".env");
+  const cfgPath = configPath(home);
   if (!existsSync2(cfgPath)) {
-    return warn("config_file", "Config file exists", `${cfgPath} not found`);
+    return check("warn", "config_file", "Config file exists", `${cfgPath} not found`);
   }
   try {
     const map = await parseDotenvFile(cfgPath);
     const keys = Object.keys(map);
-    return pass("config_file", "Config file exists", `Found with keys: ${keys.length > 0 ? keys.join(", ") : "(none set)"}`);
+    return check("pass", "config_file", "Config file exists", `Found with keys: ${keys.length > 0 ? keys.join(", ") : "(none set)"}`);
   } catch (e) {
-    return warn("config_file", "Config file exists", `Failed to parse ${cfgPath}: ${String(e)}`);
+    return check("warn", "config_file", "Config file exists", `Failed to parse ${cfgPath}: ${String(e)}`);
   }
 }
-async function checkWikiPathSet(input) {
-  const r = await resolveRuntimePath({ flag: void 0, envValue: input.envValue, home: input.home });
-  if (r.ok) {
-    return pass("wiki_path_set", "WIKI_PATH configured", `Resolved via ${r.data.source}: ${r.data.path}`);
-  }
-  return error("wiki_path_set", "WIKI_PATH configured", "No vault configured. Run `skillwiki init` or pass --vault.");
-}
 function checkWikiPathExists(resolvedPath) {
   if (resolvedPath === void 0) {
-    return error("wiki_path_exists", "Vault directory exists", "Cannot check \u2014 WIKI_PATH not resolved");
+    return check("error", "wiki_path_exists", "Vault directory exists", "Cannot check \u2014 WIKI_PATH not resolved");
   }
   if (existsSync2(resolvedPath) && statSync(resolvedPath).isDirectory()) {
-    return pass("wiki_path_exists", "Vault directory exists", resolvedPath);
+    return check("pass", "wiki_path_exists", "Vault directory exists", resolvedPath);
   }
-  return error("wiki_path_exists", "Vault directory exists", `${resolvedPath} does not exist or is not a directory`);
+  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 error("vault_structure", "Vault structure valid", "Cannot check \u2014 WIKI_PATH not resolved");
+    return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 WIKI_PATH not resolved");
   }
   if (!existsSync2(resolvedPath)) {
-    return error("vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
+    return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
   }
   const missing = [];
   if (!existsSync2(join13(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
@@ -1414,20 +1487,20 @@ function checkVaultStructure(resolvedPath) {
     if (!existsSync2(join13(resolvedPath, dir))) missing.push(dir + "/");
   }
   if (missing.length === 0) {
-    return pass("vault_structure", "Vault structure valid", "All required files and directories present");
+    return check("pass", "vault_structure", "Vault structure valid", "All required files and directories present");
   }
-  return error("vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")}`);
+  return check("error", "vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")}`);
 }
 function checkSkillsInstalled(home) {
   const skillsDir = join13(home, ".claude", "skills");
   if (!existsSync2(skillsDir)) {
-    return warn("skills_installed", "Skills installed", `${skillsDir} not found`);
+    return check("warn", "skills_installed", "Skills installed", `${skillsDir} not found`);
   }
   const found = findSkillMd(skillsDir);
   if (found.length > 0) {
-    return pass("skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found`);
+    return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found`);
   }
-  return warn("skills_installed", "Skills installed", "No SKILL.md files found in ~/.claude/skills/");
+  return check("warn", "skills_installed", "Skills installed", "No SKILL.md files found in ~/.claude/skills/");
 }
 function findSkillMd(dir) {
   const results = [];
@@ -1451,9 +1524,12 @@ async function runDoctor(input) {
   checks.push(checkNodeVersion());
   checks.push(checkCliOnPath(input.argv));
   checks.push(await checkConfigFile(input.home));
-  const wikiPathCheck = await checkWikiPathSet(input);
-  checks.push(wikiPathCheck);
   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));
@@ -1520,7 +1596,7 @@ program.command("lang").option("--lang <code>", "explicit language override").op
     explain: !!opts.explain
   }));
 });
-program.command("init").option("--target <dir>", "explicit target directory").requiredOption("--domain <text>", "knowledge domain seed").option("--taxonomy <csv>", "comma-separated tag list").option("--lang <code>", "output language (BCP 47 or alias)").option("--force", "override existing target / env conflict", false).action(async (opts) => {
+program.command("init").option("--target <dir>", "explicit target directory").requiredOption("--domain <text>", "knowledge domain seed").option("--taxonomy <csv>", "comma-separated tag list").option("--lang <code>", "output language (BCP 47 or alias)").option("--force", "override existing target / env conflict", false).option("--no-env", "skip writing ~/.skillwiki/.env").action(async (opts) => {
   const templates = new URL("../templates/", import.meta.url).pathname;
   const taxonomy = typeof opts.taxonomy === "string" ? opts.taxonomy.split(",").map((s) => s.trim()).filter((s) => s.length > 0) : void 0;
   emit(await runInit({
@@ -1531,7 +1607,8 @@ program.command("init").option("--target <dir>", "explicit target directory").re
     domain: opts.domain,
     taxonomy,
     lang: opts.lang,
-    force: !!opts.force
+    force: !!opts.force,
+    noEnv: opts.env === false
   }));
 });
 async function resolveVaultArg(arg) {
@@ -1593,7 +1670,6 @@ configCmd.command("path").description("print the config file path").action(async
 program.command("doctor").description("diagnose skillwiki setup issues").action(async () => emit(await runDoctor({
   home: process.env.HOME ?? "",
   envValue: process.env.WIKI_PATH,
-  envLang: process.env.WIKI_LANG,
   argv: process.argv
 })));
 program.parseAsync(process.argv).catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.7",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"
@@ -30,6 +30,10 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/karlorz/llm-wiki.git"
+  },
   "engines": {
     "node": ">=20"
   }

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

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

package/skills/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/hooks/run-hook.cmd

@@ -0,0 +1,43 @@
+: << 'CMDBLOCK'
+@echo off
+REM Cross-platform polyglot wrapper for hook scripts.
+REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
+REM On Unix: the shell interprets this as a script (: is a no-op in bash).
+REM
+REM Hook scripts use extensionless filenames (e.g. "session-start" not
+REM "session-start.sh") so Claude Code's Windows auto-detection -- which
+REM prepends "bash" to any command containing .sh -- doesn't interfere.
+
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+
+set "HOOK_DIR=%~dp0"
+
+REM Try Git for Windows bash in standard locations
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM Try bash on PATH
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM No bash found - exit silently
+exit /b 0
+CMDBLOCK
+
+# Unix: run the named script directly
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

package/skills/hooks/session-start

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# SessionStart hook for skillwiki plugin
+# Injects using-skillwiki SKILL.md content into every conversation.
+
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+
+skill_content=$(cat "${PLUGIN_ROOT}/using-skillwiki/SKILL.md" 2>/dev/null || echo "Error reading using-skillwiki skill")
+
+# Escape string for JSON embedding using bash parameter substitution.
+# Each ${s//old/new} is a single C-level pass.
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+skill_escaped=$(escape_for_json "$skill_content")
+session_context="<EXTREMELY_IMPORTANT>\nYou have skillwiki.\n\n**Below is the full content of your 'skillwiki:using-skillwiki' skill - your introduction to the skillwiki skills. For all other skills, use the 'Skill' tool:**\n\n${skill_escaped}\n</EXTREMELY_IMPORTANT>"
+
+# Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
+printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context"
+
+exit 0

package/skills/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.7",
   "private": true,
-  "files": ["wiki-*", "proj-*", ".claude-plugin", "README.md"]
+  "files": [
+    "wiki-*",
+    "proj-*",
+    "using-skillwiki",
+    ".claude-plugin",
+    "hooks",
+    "README.md"
+  ]
 }

package/skills/using-skillwiki/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: using-skillwiki
+description: Invoke at session start or when knowledge-base tasks arise — maps all wiki-*/proj-* skills and teaches the skillwiki CLI workflow
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+# using-skillwiki
+
+You have skillwiki — a project-aware Karpathy-style knowledge base for Claude Code.
+
+## When to Use These Skills
+
+Invoke a skillwiki skill when the user:
+- Wants to create, build, or start a vault/wiki/knowledge base
+- Mentions ingesting sources, reading URLs into notes, converting content
+- Asks to search, query, or find information in their vault
+- Wants a health check or lint on their vault
+- Mentions crystallizing a session into a note
+- Talks about project workspaces, ADRs, or distillation
+- Asks about their skillwiki configuration or setup health
+
+## Skill Map
+
+| Skill | When to Invoke |
+|-------|----------------|
+| `wiki-init` | Bootstrap a new vault — SCHEMA.md, index.md, log.md, ~/.skillwiki/.env |
+| `wiki-ingest` | Convert URLs, files, or pasted text into typed-knowledge pages |
+| `wiki-query` | Search the vault and synthesize an answer with ranked results |
+| `wiki-lint` | Vault health check (stale pages, oversized pages, log rotation) |
+| `wiki-crystallize` | Distill the current working session into a typed-knowledge page |
+| `wiki-audit` | Verify raw provenance references and source frontmatter integrity |
+| `proj-init` | Bootstrap a project workspace (README, requirements, architecture) |
+| `proj-work` | Open or run a work item under a project's work/ directory |
+| `proj-distill` | Distill project compound entries into vault concept pages |
+| `proj-decide` | Write an Architectural Decision Record (ADR) |
+
+## CLI Backbone
+
+All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
+
+Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`.
+
+Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to see current configuration.
+
+## Typical Workflow
+
+1. **Init** (`wiki-init`) — create vault, set domain and taxonomy
+2. **Ingest** (`wiki-ingest`) — add sources, build pages
+3. **Query** (`wiki-query`) — search and synthesize answers
+4. **Lint** (`wiki-lint`) — periodic health checks
+5. **Crystallize** (`wiki-crystallize`) — save session insights as pages
+6. **Audit** (`wiki-audit`) — verify source integrity
+
+For longer-running project work, use `proj-init` → `proj-work` → `proj-distill` / `proj-decide`.