skillwiki 0.2.0-beta.2 → 0.2.0-beta.4

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { readFileSync } from "fs";
 import { Command } from "commander";
 
 // src/utils/output.ts
@@ -9,9 +10,14 @@ function printJson(r) {
 }
 function printHuman(r) {
   if (r.ok) {
-    process.stdout.write(`OK
+    if (typeof r.data === "object" && r.data !== null && "humanHint" in r.data) {
+      process.stdout.write(`${r.data.humanHint}
+`);
+    } else {
+      process.stdout.write(`OK
 ${formatData(r.data)}
 `);
+    }
   } else {
     process.stdout.write(`ERR ${r.error}
 ${r.detail !== void 0 ? formatData(r.detail) + "\n" : ""}`);
@@ -53,15 +59,19 @@ var ExitCode = {
   LINT_HAS_WARNINGS: 22,
   LINT_HAS_ERRORS: 23,
   ENV_WRITE_CONFLICT: 24,
-  NO_VAULT_CONFIGURED: 25
+  NO_VAULT_CONFIGURED: 25,
+  INVALID_CONFIG_KEY: 26,
+  CONFIG_WRITE_FAILED: 27,
+  DOCTOR_HAS_WARNINGS: 28,
+  DOCTOR_HAS_ERRORS: 29
 };
 
 // ../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 };
+function err(error2, detail) {
+  return detail === void 0 ? { ok: false, error: error2 } : { ok: false, error: error2, detail };
 }
 
 // ../shared/src/schemas.ts
@@ -479,7 +489,8 @@ async function runOverlap(input) {
 import { join as join2 } from "path";
 
 // src/utils/dotenv.ts
-import { readFile as readFile4 } from "fs/promises";
+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;
@@ -502,6 +513,50 @@ async function parseDotenvFile(path) {
   }
   return out;
 }
+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) {
@@ -630,7 +685,7 @@ function simulateRemoval(adj, removed) {
 
 // src/commands/audit.ts
 import { readFile as readFile5, stat as stat2 } from "fs/promises";
-import { dirname as dirname2, resolve, join as join3 } from "path";
+import { dirname as dirname3, resolve, join as join3 } from "path";
 
 // src/parsers/citations.ts
 var FENCE2 = /```[\s\S]*?```/g;
@@ -657,7 +712,7 @@ async function runAudit(input) {
   if (!fm.ok) return { exitCode: ExitCode.INVALID_FRONTMATTER, result: fm };
   const split = splitFrontmatter(text);
   const body = split.ok ? split.data.body : text;
-  const vault = await findVaultRoot(dirname2(resolve(input.file)));
+  const vault = await findVaultRoot(dirname3(resolve(input.file)));
   if (!vault) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID") };
   const markers = extractCitationMarkers(body);
   const resolved = await Promise.all(markers.map(async (m) => {
@@ -688,7 +743,7 @@ async function findVaultRoot(start) {
       return cur;
     } catch {
     }
-    const parent = dirname2(cur);
+    const parent = dirname3(cur);
     if (parent === cur) return null;
     cur = parent;
   }
@@ -700,10 +755,10 @@ import { readdir as readdir2, stat as stat4 } from "fs/promises";
 import { join as join4 } from "path";
 
 // src/utils/install-fs.ts
-import { copyFile, mkdir as mkdir2, rename, writeFile as writeFile2, stat as stat3 } from "fs/promises";
-import { dirname as dirname3 } from "path";
+import { copyFile, mkdir as mkdir3, rename, writeFile as writeFile3, stat as stat3 } from "fs/promises";
+import { dirname as dirname4 } from "path";
 async function atomicCopyWithBackup(src, dst) {
-  await mkdir2(dirname3(dst), { recursive: true });
+  await mkdir3(dirname4(dst), { recursive: true });
   let backupPath = null;
   try {
     await stat3(dst);
@@ -721,9 +776,9 @@ async function atomicCopyWithBackup(src, dst) {
   return ok({ copied: true, backupPath });
 }
 async function writeManifest(path, m) {
-  await mkdir2(dirname3(path), { recursive: true });
+  await mkdir3(dirname4(path), { recursive: true });
   const enriched = { installed_at: (/* @__PURE__ */ new Date()).toISOString(), ...m };
-  await writeFile2(path, JSON.stringify(enriched, null, 2));
+  await writeFile3(path, JSON.stringify(enriched, null, 2));
 }
 
 // src/commands/install.ts
@@ -839,8 +894,8 @@ async function runLang(input) {
 }
 
 // src/commands/init.ts
-import { mkdir as mkdir3, readFile as readFile6, stat as stat5, writeFile as writeFile3 } from "fs/promises";
-import { join as join7, dirname as dirname4 } from "path";
+import { mkdir as mkdir4, readFile as readFile6, stat as stat5, writeFile as writeFile4 } from "fs/promises";
+import { join as join7, dirname as dirname5 } from "path";
 var DEFAULT_TAXONOMY = [
   "research",
   "comparison",
@@ -899,9 +954,9 @@ async function runInit(input) {
   }
   const created = [];
   try {
-    await mkdir3(target, { recursive: true });
+    await mkdir4(target, { recursive: true });
     for (const d of VAULT_DIRS) {
-      await mkdir3(join7(target, d), { recursive: true });
+      await mkdir4(join7(target, d), { recursive: true });
       created.push(d + "/");
     }
   } catch (e) {
@@ -913,7 +968,7 @@ async function runInit(input) {
   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");
+    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) }) };
@@ -921,7 +976,7 @@ async function runInit(input) {
   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");
+    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) }) };
@@ -929,17 +984,17 @@ async function runInit(input) {
   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");
+    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) }) };
   }
   try {
-    await mkdir3(dirname4(envPath), { recursive: true });
+    await mkdir4(dirname5(envPath), { recursive: true });
     const envBody = `WIKI_PATH=${target}
 WIKI_LANG=${canonicalLang}
 `;
-    await writeFile3(envPath, envBody, "utf8");
+    await writeFile4(envPath, envBody, "utf8");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { file: envPath, message: String(e) }) };
   }
@@ -1131,7 +1186,7 @@ async function runPagesize(input) {
 }
 
 // src/commands/log-rotate.ts
-import { readFile as readFile10, rename as rename2, writeFile as writeFile4, stat as stat6 } from "fs/promises";
+import { readFile as readFile10, rename as rename2, writeFile as writeFile5, stat as stat6 } from "fs/promises";
 import { join as join11 } from "path";
 var ENTRY_RE = /^## \[(\d{4})-\d{2}-\d{2}\]/gm;
 async function runLogRotate(input) {
@@ -1172,7 +1227,7 @@ Chronological action log. Newest entries last. Skill writes append entries; lint
 
 - Previous log moved to ${rotatedName}
 `;
-    await writeFile4(logPath, fresh, "utf8");
+    await writeFile5(logPath, fresh, "utf8");
   } catch (e) {
     return { exitCode: ExitCode.WRITE_FAILED, result: err("WRITE_FAILED", { message: String(e) }) };
   }
@@ -1236,9 +1291,195 @@ async function runLint(input) {
   };
 }
 
+// src/commands/config.ts
+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";
+}
+function configPath(home) {
+  return join12(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 readFile11(filePath, "utf8");
+    } catch {
+    }
+    const existing = originalContent !== void 0 ? await parseDotenvFile(filePath) : {};
+    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 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 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 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");
+  }
+  if (argv.length >= 2 && argv[1] === "skillwiki") {
+    return 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");
+  } catch {
+    return warn("cli_on_path", "skillwiki on PATH", "skillwiki not found on PATH");
+  }
+}
+async function checkConfigFile(home) {
+  const cfgPath = join13(home, ".skillwiki", ".env");
+  if (!existsSync2(cfgPath)) {
+    return 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)"}`);
+  } catch (e) {
+    return 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");
+  }
+  if (existsSync2(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+    return 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`);
+}
+function checkVaultStructure(resolvedPath) {
+  if (resolvedPath === void 0) {
+    return 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");
+  }
+  const missing = [];
+  if (!existsSync2(join13(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  for (const dir of ["raw", "entities", "concepts", "meta"]) {
+    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 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`);
+  }
+  const found = findSkillMd(skillsDir);
+  if (found.length > 0) {
+    return 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/");
+}
+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(join13(dir, entry.name));
+    } else if (entry.isDirectory()) {
+      results.push(...findSkillMd(join13(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 wikiPathCheck = await checkWikiPathSet(input);
+  checks.push(wikiPathCheck);
+  const resolved = await resolveRuntimePath({ flag: void 0, envValue: input.envValue, home: input.home });
+  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/cli.ts
+var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
-program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version("0.2.0-beta.2");
+program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
 function emit(r) {
   if (program.opts().human) printHuman(r.result);
@@ -1257,7 +1498,7 @@ program.command("orphans [vault]").action(async (vault) => emit(await runOrphans
 })));
 program.command("audit <file>").action(async (file) => emit(await runAudit({ file })));
 program.command("install").option("--target <dir>", "target install directory", `${process.env.HOME ?? ""}/.claude/skills/`).option("--dry-run", "preview only", false).option("--skills-root <dir>", "source skills directory (defaults to packaged)").action(async (opts) => {
-  const skillsRoot = opts.skillsRoot ?? new URL("../../skills/", import.meta.url).pathname;
+  const skillsRoot = opts.skillsRoot ?? new URL("../skills/", import.meta.url).pathname;
   emit(await runInstall({ skillsRoot, target: opts.target, dryRun: !!opts.dryRun }));
 });
 program.command("path").option("--vault <dir>", "explicit vault override (runtime)").option("--target <dir>", "explicit target override (init-time)").option("--init-time", "use init-time chain instead of runtime", false).option("--explain", "include resolution chain in output", false).action(async (opts) => {
@@ -1344,6 +1585,17 @@ program.command("lint [vault]").option("--days <n>", "stale threshold", (s) => p
     logThreshold: opts.logThreshold
   }));
 });
+var configCmd = program.command("config").description("manage skillwiki configuration");
+configCmd.command("get <key>").description("print the value of a config key").action(async (key) => emit(await runConfigGet({ key, home: process.env.HOME ?? "" })));
+configCmd.command("set <key> <value>").description("set a config key value").action(async (key, value) => emit(await runConfigSet({ key, value, home: process.env.HOME ?? "" })));
+configCmd.command("list").description("list all config key=value pairs").action(async () => emit(await runConfigList({ home: process.env.HOME ?? "" })));
+configCmd.command("path").description("print the config file path").action(async () => emit(await runConfigPath({ home: process.env.HOME ?? "" })));
+program.command("doctor").description("diagnose skillwiki setup issues").action(async () => emit(await runDoctor({
+  home: process.env.HOME ?? "",
+  envValue: process.env.WIKI_PATH,
+  envLang: process.env.WIKI_LANG,
+  argv: process.argv
+})));
 program.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
   process.exit(1);

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "skillwiki",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.4",
   "type": "module",
-  "bin": { "skillwiki": "dist/cli.js" },
-  "files": ["dist", "templates", "README.md"],
+  "bin": {
+    "skillwiki": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "skills",
+    "README.md"
+  ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && rm -rf ./skills && cp -r ../skills ./skills",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"
@@ -23,5 +30,7 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0"
   },
-  "engines": { "node": ">=20" }
+  "engines": {
+    "node": ">=20"
+  }
 }

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

@@ -0,0 +1,23 @@
+{
+  "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).",
+  "author": {
+    "name": "karlorz",
+    "url": "https://github.com/karlorz"
+  },
+  "homepage": "https://github.com/karlorz/llm-wiki",
+  "repository": "https://github.com/karlorz/llm-wiki",
+  "license": "MIT",
+  "keywords": [
+    "knowledge-base",
+    "wiki",
+    "obsidian",
+    "claude-code",
+    "skills",
+    "karpathy",
+    "markdown",
+    "research",
+    "rag-alternative"
+  ]
+}

package/skills/README.md

@@ -0,0 +1,10 @@
+# @skillwiki/skills
+
+Prompt-only Markdown skills for Claude Code. Installed via `skillwiki install`.
+
+| Namespace | Skills |
+|---|---|
+| `wiki-*` | `wiki-init`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `wiki-crystallize`, `wiki-audit` |
+| `proj-*` | `proj-init`, `proj-work`, `proj-distill`, `proj-decide` |
+
+Each subdirectory holds one `SKILL.md`. No build step.

package/skills/package.json

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

package/skills/proj-decide/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: proj-decide
+description: Write an Architectural Decision Record (ADR). If the decision generalizes, also create a concepts/ page.
+---
+
+# proj-decide
+
+## When to invoke
+- User commits to an architectural decision worth recording for future reference.
+
+## Pre-orientation reads
+Standard four + project context.
+
+## Steps
+1. Compose the ADR in `projects/{slug}/architecture/YYYY-MM-DD-{adr-slug}.md`. Frontmatter: kind=decision, status=in-progress or completed, project link.
+2. `npx skillwiki validate <adr>`. If non-zero, STOP.
+3. **Generalization check.** If the decision applies beyond this project, create a `concepts/` page with `provenance: project` (or `mixed` if research-informed).
+4. Apply writes: ADR → (optional) concept page → vault `index.md` → vault `log.md` and project `log.md`.
+
+## Stop conditions
+- `validate` non-zero on either page.
+
+## Forbidden
+- Filing the concept page without explicit `provenance:`.

package/skills/proj-distill/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: proj-distill
+description: 2-step distillation (E4) — analyze project compound entry, then generate a vault concept page with provenance.
+---
+
+# proj-distill
+
+## When to invoke
+- A project compound entry captures a pattern that generalizes beyond the project.
+
+## Pre-orientation reads
+Standard four + project context.
+
+## Steps (E4 — 2-step pattern)
+1. **Step 1 — Analyze.** Read the source compound entry + linked work items. Output a candidate concept outline. STOP if no clear universal pattern is found — surface the reasoning instead of forcing a page.
+2. **Step 2 — Generate.** Compose the vault concept page with `provenance: project` and `provenance_projects: ["[[slug]]"]`. Validate with `npx skillwiki validate`.
+3. **Backlink.** Set `promoted_to: "[[concept-slug]]"` on the source compound entry.
+4. **Apply writes in order.** Vault concept page → backlink update → project `log.md` → vault `index.md` → vault `log.md`.
+
+## Stop conditions
+- No clear universal pattern.
+- `validate` non-zero on either page.
+
+## Forbidden
+- Skipping Step 1 (no direct generation).
+- Updating index/logs before `validate` passes.

package/skills/proj-init/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: proj-init
+description: Bootstrap a project workspace at projects/{slug}/ with README, requirements/, architecture/, work/, compound/.
+---
+
+# proj-init
+
+## When to invoke
+- User starts a new project that should live inside the vault.
+
+## Pre-orientation reads
+Standard four reads (vault SCHEMA, index, log) — no project context yet.
+
+## Inputs
+- Slug (lowercase, hyphenated).
+- One-line intent.
+
+## Steps
+1. Verify `projects/{slug}/` does not exist.
+2. Create folders: `projects/{slug}/{requirements,architecture,work,compound}/`.
+3. Render `projects/{slug}/README.md` from `project-README.md` template, filling `{{slug}}` and `{{date}}`.
+4. Update vault `index.md` "Projects" section: add `- [[projects/{slug}]]`.
+5. Append vault `log.md` entry: "Project {slug} initialized."
+
+## Stop conditions
+- `projects/{slug}/` already exists.
+
+## Forbidden
+- Modifying any other project's files.

package/skills/proj-work/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: proj-work
+description: Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug}/. Redirects brainstorming/writing-plans output paths.
+---
+
+# proj-work
+
+## When to invoke
+- User starts a feature, issue, refactor, or decision inside an existing project.
+- Brainstorming or writing-plans skills would otherwise default-write outside the project tree.
+
+## Pre-orientation reads
+Standard four + project context (project README, last ~5 work logs).
+
+## Steps
+1. Determine `kind:` (feature | issue | refactor | decision) and slug.
+2. Create folder `projects/{slug}/work/YYYY-MM-DD-{work-slug}/`.
+3. Override default output paths for any nested skill: `spec.md`, `plan.md`, and `log.md` are written here, not at vault root.
+4. Validate work-item frontmatter via `npx skillwiki validate <spec.md>`. If non-zero, STOP.
+5. Manage status transitions: `planned` → `in-progress` → `completed` (set `completed:` date) or `abandoned`.
+6. Append vault `log.md` entry on creation and on each status transition.
+
+## Stop conditions
+- `validate` non-zero.
+- Conflicting work folder name.
+
+## Forbidden
+- Writing spec/plan files outside the work folder.
+- Marking `status: completed` without a `completed:` date.

package/skills/wiki-audit/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: wiki-audit
+description: Verify per-page that every ^[raw/...] resolves and sources frontmatter matches the body.
+---
+
+# wiki-audit
+
+## When This Skill Activates
+
+- User asks for a per-page audit or invokes a pre-merge gate.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate audit narrative and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
+
+## Pre-orientation reads
+Standard four reads.
+
+## Steps
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
+1. `npx skillwiki audit <page>`. Read the JSON report.
+2. Reason over the report:
+   - For each unresolved marker: suggest ingesting the missing source or correcting the path.
+   - For each `unused_sources` entry: suggest adding a body marker or removing from `sources:`.
+   - For each `missing_from_sources` entry: suggest adding to `sources:`.
+3. Append one `log.md` entry summarizing the audit and any suggested follow-ups.
+
+## Stop conditions
+None — audit always completes.
+
+## Forbidden
+- Auto-applying suggested fixes (audit is observation-only).

package/skills/wiki-crystallize/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: wiki-crystallize
+description: Distill the current working session into a typed-knowledge page with provenance.
+---
+
+# wiki-crystallize
+
+## When This Skill Activates
+
+- User asks to crystallize, consolidate, or promote draft material into typed-knowledge pages.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate consolidated page prose and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
+
+## Pre-orientation reads
+Standard four reads. If cwd is inside `projects/{slug}/`, also read project README and recent work logs.
+
+## Steps
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
+1. Identify type: entity / concept / comparison / query / summary.
+2. Set `provenance:`. Default `research`. If in project context: `project` with `provenance_projects: ["[[slug]]"]`.
+3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible.
+4. `npx skillwiki validate <page>`. If non-zero, STOP.
+5. Apply writes: page → `index.md` → `log.md`.
+
+## Stop conditions
+- `validate` non-zero.
+- Missing `provenance:` for project-context runs.
+
+## Forbidden
+- Filing without explicit `provenance:`.
+- Updating `index.md` before `validate` passes.

package/skills/wiki-ingest/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: wiki-ingest
+description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Single-pass v1.
+---
+
+# wiki-ingest
+
+## When This Skill Activates
+
+- User shares a URL, paste, or local file to capture in the vault.
+- The output target is `entities/`, `concepts/`, `comparisons/`, or `queries/`.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate page-body prose, narrative sections, and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
+
+## Pre-orientation reads (mandatory before any write)
+1. `SCHEMA.md`
+2. `index.md`
+3. Last 20–30 entries of `log.md`
+4. (Project context only) `projects/{slug}/README.md` and last ~5 work-item logs.
+
+## Steps (in order — N6, N7, N8)
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
+1. **Guard.** For each URL: run `npx skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
+2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
+3. **Hash.** Write the raw file (frontmatter + body). Run `npx skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
+4. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers).
+5. **Validate.** For each generated page: run `npx skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
+6. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.
+7. **Confidence flag.** If only one source is cited, set `confidence: low`.
+
+## Provenance defaults
+- Default `provenance: research`.
+- If cwd is inside `projects/{slug}/`, set `provenance: project` and add `provenance_projects: ["[[slug]]"]`.
+
+## Stop conditions
+- `fetch-guard` non-zero.
+- Fetch timeout / size limit exceeded.
+- `validate` non-zero on any page.
+- sha256 already exists in vault for the same source.
+
+## Forbidden
+- Skipping `fetch-guard`.
+- Updating `index.md` or `log.md` before all pages validate.
+- Modifying any existing file in `raw/`.

package/skills/wiki-init/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: wiki-init
+description: Bootstrap a CodeWiki vault — domain-aware SCHEMA.md, index.md, log.md, and ~/.skillwiki/.env binding. Use when starting a fresh vault.
+---
+
+# wiki-init
+
+## When This Skill Activates
+
+- User asks to create, build, or start a vault, wiki, or knowledge base.
+- The resolved vault path (see step 0) does not yet contain SCHEMA.md.
+
+## Pre-orientation reads
+
+None for the first run.
+
+## Steps
+
+0. **Resolve target.** Run `skillwiki path --init-time` to see what target the CLI will pick. Confirm with the user, or override with `--target <dir>`.
+1. Verify target is empty or has no SCHEMA.md.
+2. Ask the domain question: "What knowledge domain will this vault cover? Be specific."
+3. Propose a 10–15 tag taxonomy tailored to the domain. Confirm or accept the user's revision.
+4. Ask the language question: "What language should generated page prose use? Default is `en`. Aliases like `chinese-traditional` or `zh-Hant` are accepted."
+5. Run `skillwiki init --target <dir> --domain "<answer>" --taxonomy "<comma list>" --lang "<lang>"`.
+6. **Suggest first sources.** Propose 3–5 initial sources (URLs, papers, articles) appropriate to the domain. Prompt the user to provide the first one to ingest, then hand off to wiki-ingest.
+
+## Stop conditions
+
+- Target non-empty and `--force` not consented.
+- `~/.skillwiki/.env` already binds a different vault or language and `--force` not consented.
+
+## Forbidden
+
+- Modifying anything outside the target directory or `~/.skillwiki/.env`.
+- Writing to `~/.hermes/.env` (read-only fallback).
+- Running any LLM-driven content generation in this skill.

package/skills/wiki-lint/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: wiki-lint
+description: Vault health check via the umbrella `skillwiki lint` subcommand. Read-only by default; rotation requires explicit user consent.
+---
+
+# wiki-lint
+
+## When This Skill Activates
+
+- User asks for a vault health report, lint, or audit.
+- Periodic maintenance.
+
+## Pre-orientation reads
+
+Standard four reads.
+
+## Steps
+
+0. Resolve vault: `skillwiki path` (record source for context).
+1. Run `skillwiki lint <vault>`. Read the JSON.
+2. Reason over findings; present grouped by severity with concrete suggested actions per kind.
+3. If `log_rotate_needed` is present and the user consents, run `skillwiki log-rotate <vault> --apply`. Otherwise leave alone.
+4. Append one `log.md` entry summarizing the lint counts (errors/warnings/info).
+
+## Stop conditions
+
+None — lint reports all findings even on per-page errors.
+
+## Forbidden
+
+- Auto-rotating logs.
+- Auto-updating sha256 fields.
+- Modifying any page beyond the lint summary entry in `log.md`.

package/skills/wiki-query/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: wiki-query
+description: Search the vault and synthesize an answer with E2 4-signal ranking. Optional file to queries/ or comparisons/.
+---
+
+# wiki-query
+
+## When This Skill Activates
+
+- User asks a question that should be answered from vault contents.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate query-result prose and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
+
+## Pre-orientation reads
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Steps
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
+1. **Determine scope.** Ask the user once if ambiguous: vault | current project | project+concepts.
+2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `npx skillwiki graph build <vault>`.
+3. **Compute overlap.** `npx skillwiki overlap <vault>`.
+4. **Score candidates** in prompt using the 4 signals:
+   - Direct wikilink: 3.0×
+   - Source overlap: 4.0× (read from overlap output)
+   - Adamic-Adar: 1.5× (read from graph output)
+   - Type affinity: 1.0×
+5. **Read top candidates** in full (frontmatter + body).
+6. **Synthesize answer** with explicit citations to the candidate pages.
+7. **Optional file.** If user accepts: write to `queries/<slug>.md` or `comparisons/<slug>.md` with full frontmatter, validate, then update `index.md` then `log.md`.
+
+## Stop conditions
+- Zero matching pages.
+- User declines to file.
+
+## Forbidden
+- Filing without `validate` passing.
+- Skipping the orientation reads even for "quick" queries.