skillwiki 0.2.0-beta.14 → 0.2.0-beta.19

package/dist/auto-update-bg.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+import {
+  semverGt
+} from "./chunk-XM5IYZX7.js";
+
+// src/auto-update-bg.ts
+import { execSync } from "child_process";
+import { writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+var home = process.argv[2];
+var currentVersion = process.argv[3];
+if (!home || !currentVersion) process.exit(0);
+var cacheFile = join(home, ".skillwiki", ".update-cache.json");
+setTimeout(() => process.exit(0), 3e4);
+try {
+  const latest = execSync("npm view skillwiki@beta version", {
+    encoding: "utf8",
+    timeout: 15e3
+  }).trim();
+  mkdirSync(dirname(cacheFile), { recursive: true });
+  const cache = {
+    lastCheck: Date.now(),
+    latestVersion: latest,
+    currentVersion
+  };
+  if (semverGt(latest, currentVersion)) {
+    execSync("npm install -g skillwiki@beta", {
+      stdio: "ignore",
+      timeout: 6e4
+    });
+    writeFileSync(cacheFile, JSON.stringify({ ...cache, updateAppliedAt: Date.now() }, null, 2));
+  } else {
+    writeFileSync(cacheFile, JSON.stringify(cache, null, 2));
+  }
+} catch {
+  try {
+    mkdirSync(dirname(cacheFile), { recursive: true });
+    writeFileSync(cacheFile, JSON.stringify({ lastCheck: Date.now(), latestVersion: "", currentVersion }, null, 2));
+  } catch {
+  }
+}
+process.exit(0);

package/dist/chunk-XM5IYZX7.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+// src/utils/semver.ts
+function semverGt(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return a > b;
+  if (pa.major !== pb.major) return pa.major > pb.major;
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch;
+  if (!pa.pre && pb.pre) return true;
+  if (pa.pre && !pb.pre) return false;
+  if (!pa.pre && !pb.pre) return false;
+  const aParts = pa.pre.split(".");
+  const bParts = pb.pre.split(".");
+  const len = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < len; i++) {
+    const ai = aParts[i];
+    const bi = bParts[i];
+    if (ai === void 0) return false;
+    if (bi === void 0) return true;
+    const aNum = parseInt(ai, 10);
+    const bNum = parseInt(bi, 10);
+    if (!isNaN(aNum) && !isNaN(bNum)) {
+      if (aNum !== bNum) return aNum > bNum;
+    } else {
+      if (ai !== bi) return ai > bi;
+    }
+  }
+  return false;
+}
+function parseSemver(version) {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+  if (!match) return null;
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10),
+    pre: match[4] ?? null
+  };
+}
+
+export {
+  semverGt
+};

package/dist/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import {
+  semverGt
+} from "./chunk-XM5IYZX7.js";
 
 // src/cli.ts
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { Command } from "commander";
 
 // src/utils/output.ts
@@ -108,10 +111,10 @@ var TypedKnowledgeSchema = z.object({
 });
 var sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
 var RawSourceSchema = z.object({
-  title: z.string().min(1),
-  source_url: z.string().url().nullable(),
+  title: z.string().min(1).optional(),
+  source_url: z.string().nullable(),
   ingested: isoDate,
-  ingested_by: z.enum(["wiki-ingest", "proj-work", "manual"]),
+  ingested_by: z.enum(["wiki-ingest", "proj-work", "manual"]).optional(),
   sha256: sha256Hex,
   project: wikilink.optional(),
   work_item: wikilink.optional(),
@@ -745,6 +748,48 @@ function isLegacyCitationStyle(body) {
   }
   return false;
 }
+function hasOrphanedCitations(body) {
+  const stripped = stripFences(body);
+  const lines = stripped.split("\n");
+  let inSources = false;
+  let sourcesEnded = false;
+  let sourcesStartLine = -1;
+  let lastNonBlankInSources = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (/^## Sources\b/.test(trimmed)) {
+      inSources = true;
+      sourcesStartLine = i;
+      continue;
+    }
+    if (!inSources || sourcesEnded) continue;
+    if (trimmed.length === 0) {
+      if (lastNonBlankInSources >= 0) {
+        sourcesEnded = true;
+      }
+      continue;
+    }
+    const isListItem = /^\s*[-*]\s+/.test(line);
+    const hasMarker = /\^\[raw\//.test(line);
+    if (isListItem && hasMarker) {
+      lastNonBlankInSources = i;
+    } else if (hasMarker && !isListItem) {
+      return true;
+    } else {
+      sourcesEnded = true;
+    }
+  }
+  if (sourcesStartLine === -1) return false;
+  if (sourcesEnded) {
+    for (let i = lastNonBlankInSources + 1; i < lines.length; i++) {
+      if (/\^\[raw\//.test(lines[i])) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 
 // src/commands/audit.ts
 async function runAudit(input) {
@@ -1475,9 +1520,11 @@ async function runDedup(input) {
 }
 
 // src/commands/lint.ts
+var STRUCT_MIN_BODY_LINES = 60;
+var STRUCT_MIN_SECTIONS = 3;
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "contested", "orphans", "legacy_citation_style"];
-var INFO_ORDER = ["bridges", "low_confidence_single_source", "topic_map_recommended"];
+var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "contested", "orphans", "legacy_citation_style", "orphaned_citations"];
+var INFO_ORDER = ["bridges", "low_confidence_single_source", "page_structure", "topic_map_recommended"];
 async function runLint(input) {
   const buckets = {};
   const links = await runLinks({ vault: input.vault });
@@ -1523,13 +1570,32 @@ async function runLint(input) {
   const scan = await scanVault(input.vault);
   if (scan.ok) {
     const legacyPages = [];
+    const orphanedPages = [];
+    const structFlags = [];
     for (const page of scan.data.typedKnowledge) {
       const text = await readPage(page);
       const split = splitFrontmatter(text);
       if (!split.ok) continue;
-      if (isLegacyCitationStyle(split.data.body)) legacyPages.push(page.relPath);
+      const body = split.data.body;
+      if (isLegacyCitationStyle(body)) legacyPages.push(page.relPath);
+      if (hasOrphanedCitations(body)) orphanedPages.push(page.relPath);
+      const bodyLines = body.split("\n").filter((l) => l.trim().length > 0).length;
+      if (bodyLines < STRUCT_MIN_BODY_LINES) {
+        const hasOverview = /^## Overview/m.test(body);
+        const hasRelated = /^## (Related|Relationships)/m.test(body);
+        const sectionCount = (body.match(/^## /gm) ?? []).length;
+        if (!hasOverview || !hasRelated || sectionCount < STRUCT_MIN_SECTIONS) {
+          const reasons = [];
+          if (!hasOverview) reasons.push("no Overview");
+          if (!hasRelated) reasons.push("no Related or Relationships");
+          if (sectionCount < STRUCT_MIN_SECTIONS) reasons.push(`only ${sectionCount} sections`);
+          structFlags.push(`${page.relPath}: ${bodyLines} lines, ${reasons.join(", ")}`);
+        }
+      }
     }
     if (legacyPages.length > 0) buckets.legacy_citation_style = legacyPages;
+    if (orphanedPages.length > 0) buckets.orphaned_citations = orphanedPages;
+    if (structFlags.length > 0) buckets.page_structure = structFlags;
   }
   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] }] : []);
@@ -1610,9 +1676,72 @@ async function runConfigPath(input) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync2, readdirSync, statSync } from "fs";
-import { join as join14 } from "path";
+import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync2, statSync } from "fs";
+import { join as join15 } from "path";
 import { execSync } from "child_process";
+
+// src/utils/auto-update.ts
+import { readFileSync, writeFileSync, existsSync as existsSync2, mkdirSync } from "fs";
+import { join as join14, dirname as dirname6 } from "path";
+import { spawn } from "child_process";
+
+// src/utils/update-consts.ts
+var CACHE_FILENAME = ".update-cache.json";
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var ENV_DISABLE_KEY = "NO_UPDATE_NOTIFIER";
+var CLI_DISABLE_FLAG = "--no-update-notifier";
+
+// src/utils/auto-update.ts
+function cachePath(home) {
+  return join14(home, ".skillwiki", CACHE_FILENAME);
+}
+function readCacheRaw(home) {
+  try {
+    const raw = readFileSync(cachePath(home), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function readCache(home) {
+  const cache = readCacheRaw(home);
+  if (!cache) return { cache: null, hasUpdate: false, isStale: true };
+  const isStale = Date.now() - cache.lastCheck >= CHECK_INTERVAL_MS;
+  const hasUpdate = !!cache.latestVersion && semverGt(cache.latestVersion, cache.currentVersion);
+  return { cache, hasUpdate, isStale };
+}
+function writeCache(home, cache) {
+  const p = cachePath(home);
+  mkdirSync(dirname6(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(cache, null, 2));
+}
+function latestFromCache(home, currentVersion) {
+  const { cache } = readCache(home);
+  if (!cache || !cache.latestVersion) return { hasUpdate: false, latest: null };
+  return {
+    hasUpdate: semverGt(cache.latestVersion, currentVersion),
+    latest: cache.latestVersion
+  };
+}
+function isDisabled() {
+  return !!(process.env[ENV_DISABLE_KEY] || process.env.NODE_ENV === "test" || process.argv.includes(CLI_DISABLE_FLAG));
+}
+function triggerAutoUpdate(home, currentVersion) {
+  if (isDisabled()) return;
+  const { isStale } = readCache(home);
+  if (!isStale) return;
+  const bgScript = new URL("../auto-update-bg.js", import.meta.url).pathname;
+  if (!existsSync2(bgScript)) return;
+  const child = spawn(process.execPath, [bgScript, home, currentVersion], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.on("error", () => {
+  });
+  child.unref();
+}
+
+// src/commands/doctor.ts
 function check(status, id, label, detail) {
   return { id, label, status, detail };
 }
@@ -1639,7 +1768,7 @@ function checkCliOnPath(argv) {
 }
 async function checkConfigFile(home) {
   const cfgPath = configPath(home);
-  if (!existsSync2(cfgPath)) {
+  if (!existsSync3(cfgPath)) {
     return check("warn", "config_file", "Config file exists", `${cfgPath} not found`);
   }
   try {
@@ -1654,7 +1783,7 @@ function checkWikiPathExists(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "wiki_path_exists", "Vault directory exists", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (existsSync2(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+  if (existsSync3(resolvedPath) && statSync(resolvedPath).isDirectory()) {
     return check("pass", "wiki_path_exists", "Vault directory exists", resolvedPath);
   }
   return check("error", "wiki_path_exists", "Vault directory exists", `${resolvedPath} does not exist or is not a directory`);
@@ -1663,13 +1792,13 @@ function checkVaultStructure(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync2(resolvedPath)) {
+  if (!existsSync3(resolvedPath)) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
   }
   const missing = [];
-  if (!existsSync2(join14(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  if (!existsSync3(join15(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
   for (const dir of ["raw", "entities", "concepts", "meta"]) {
-    if (!existsSync2(join14(resolvedPath, dir))) missing.push(dir + "/");
+    if (!existsSync3(join15(resolvedPath, dir))) missing.push(dir + "/");
   }
   if (missing.length === 0) {
     return check("pass", "vault_structure", "Vault structure valid", "All required files and directories present");
@@ -1677,8 +1806,8 @@ function checkVaultStructure(resolvedPath) {
   return check("error", "vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")}`);
 }
 function checkSkillsInstalled(home) {
-  const skillsDir = join14(home, ".claude", "skills");
-  if (!existsSync2(skillsDir)) {
+  const skillsDir = join15(home, ".claude", "skills");
+  if (!existsSync3(skillsDir)) {
     return check("warn", "skills_installed", "Skills installed", `${skillsDir} not found`);
   }
   const found = findSkillMd(skillsDir);
@@ -1687,6 +1816,42 @@ function checkSkillsInstalled(home) {
   }
   return check("warn", "skills_installed", "Skills installed", "No SKILL.md files found in ~/.claude/skills/");
 }
+function checkNpmUpdate(home, currentVersion) {
+  const { hasUpdate, latest } = latestFromCache(home, currentVersion);
+  if (!latest) {
+    return check("pass", "npm_update", "npm CLI version", `v${currentVersion} (no cache yet)`);
+  }
+  if (hasUpdate) {
+    return check("warn", "npm_update", "npm CLI version", `v${currentVersion} \u2014 update available: v${latest}. Run \`skillwiki update\`.`);
+  }
+  return check("pass", "npm_update", "npm CLI version", `v${currentVersion} (latest: v${latest})`);
+}
+function checkPluginVersionDrift(home, currentVersion) {
+  const pluginJsonPath = join15(home, ".claude", "plugins", "cache", "llm-wiki", "plugin.json");
+  if (!existsSync3(pluginJsonPath)) {
+    return check("pass", "plugin_version_drift", "Plugin/CLI version", "Plugin cache not found \u2014 plugin not installed");
+  }
+  try {
+    const content = readFileSync2(pluginJsonPath, { encoding: "utf8" });
+    const pluginData = JSON.parse(content);
+    const pluginVersion = pluginData.version;
+    if (!pluginVersion) {
+      return check("pass", "plugin_version_drift", "Plugin/CLI version", "Plugin version not found in cache");
+    }
+    if (pluginVersion === currentVersion) {
+      return check("pass", "plugin_version_drift", "Plugin/CLI version", `Both at v${currentVersion}`);
+    }
+    const updateCmd = semverGt(pluginVersion, currentVersion) ? "npm install -g skillwiki@beta" : "claude plugin update skillwiki@llm-wiki";
+    return check(
+      "warn",
+      "plugin_version_drift",
+      "Plugin/CLI version",
+      `Plugin v${pluginVersion} \u2260 CLI v${currentVersion} \u2014 run \`${updateCmd}\``
+    );
+  } catch {
+    return check("pass", "plugin_version_drift", "Plugin/CLI version", "Could not read plugin cache");
+  }
+}
 function findSkillMd(dir) {
   const results = [];
   let entries;
@@ -1697,9 +1862,9 @@ function findSkillMd(dir) {
   }
   for (const entry of entries) {
     if (entry.isFile() && entry.name === "SKILL.md") {
-      results.push(join14(dir, entry.name));
+      results.push(join15(dir, entry.name));
     } else if (entry.isDirectory()) {
-      results.push(...findSkillMd(join14(dir, entry.name)));
+      results.push(...findSkillMd(join15(dir, entry.name)));
     }
   }
   return results;
@@ -1719,6 +1884,8 @@ async function runDoctor(input) {
   checks.push(checkWikiPathExists(resolvedPath));
   checks.push(checkVaultStructure(resolvedPath));
   checks.push(checkSkillsInstalled(input.home));
+  checks.push(checkNpmUpdate(input.home, input.currentVersion));
+  checks.push(checkPluginVersionDrift(input.home, input.currentVersion));
   const summary = {
     pass: checks.filter((c) => c.status === "pass").length,
     warn: checks.filter((c) => c.status === "warn").length,
@@ -1739,7 +1906,7 @@ async function runDoctor(input) {
 
 // src/commands/archive.ts
 import { rename as rename3, mkdir as mkdir5, readFile as readFile13, writeFile as writeFile6 } from "fs/promises";
-import { join as join15, dirname as dirname6 } from "path";
+import { join as join16, dirname as dirname7 } from "path";
 async function runArchive(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -1751,10 +1918,10 @@ async function runArchive(input) {
   }
   if (!relPath) return { exitCode: ExitCode.ARCHIVE_TARGET_NOT_FOUND, result: err("ARCHIVE_TARGET_NOT_FOUND", { page: input.page }) };
   if (relPath.startsWith("_archive/")) return { exitCode: ExitCode.ARCHIVE_ALREADY_ARCHIVED, result: err("ARCHIVE_ALREADY_ARCHIVED", { page: relPath }) };
-  const archivePath = join15("_archive", relPath);
-  await mkdir5(dirname6(join15(input.vault, archivePath)), { recursive: true });
+  const archivePath = join16("_archive", relPath);
+  await mkdir5(dirname7(join16(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
-  const indexPath = join15(input.vault, "index.md");
+  const indexPath = join16(input.vault, "index.md");
   try {
     const idx = await readFile13(indexPath, "utf8");
     const slug = relPath.replace(/\.md$/, "").split("/").pop();
@@ -1767,7 +1934,7 @@ async function runArchive(input) {
   } catch (e) {
     if (e?.code !== "ENOENT") throw e;
   }
-  await rename3(join15(input.vault, relPath), join15(input.vault, archivePath));
+  await rename3(join16(input.vault, relPath), join16(input.vault, archivePath));
   return { exitCode: ExitCode.OK, result: ok({ archived_from: relPath, archived_to: archivePath, index_updated: indexUpdated, humanHint: `${relPath} -> ${archivePath}${indexUpdated ? " (index updated)" : ""}` }) };
 }
 
@@ -1999,8 +2166,69 @@ ${migratedBody}${newFooter}`;
   };
 }
 
+// src/commands/update.ts
+import { execSync as execSync2 } from "child_process";
+import { readFileSync as readFileSync3 } from "fs";
+async function runUpdate(input) {
+  const pkg2 = JSON.parse(
+    readFileSync3(new URL("../../package.json", import.meta.url), "utf8")
+  );
+  const currentVersion = pkg2.version;
+  const tag = input.distTag ?? "beta";
+  let latest;
+  try {
+    latest = execSync2(`npm view skillwiki@${tag} version`, {
+      encoding: "utf8",
+      timeout: 15e3
+    }).trim();
+  } catch (e) {
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err("PREFLIGHT_FAILED", { message: `Failed to query npm registry: ${String(e)}` })
+    };
+  }
+  const cache = {
+    lastCheck: Date.now(),
+    latestVersion: latest,
+    currentVersion
+  };
+  if (latest === currentVersion) {
+    writeCache(input.home, cache);
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        previousVersion: currentVersion,
+        newVersion: null,
+        wasAlreadyLatest: true,
+        humanHint: `Already on latest ${tag}: v${currentVersion}`
+      })
+    };
+  }
+  try {
+    execSync2(`npm install -g skillwiki@${tag}`, {
+      stdio: "pipe",
+      timeout: 6e4
+    });
+  } catch (e) {
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err("PREFLIGHT_FAILED", { message: `npm install failed: ${String(e)}` })
+    };
+  }
+  writeCache(input.home, { ...cache, updateAppliedAt: Date.now() });
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      previousVersion: currentVersion,
+      newVersion: latest,
+      wasAlreadyLatest: false,
+      humanHint: `Updated skillwiki ${currentVersion} \u2192 ${latest}`
+    })
+  };
+}
+
 // src/cli.ts
-var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+var pkg = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
 program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
@@ -2117,7 +2345,8 @@ 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,
-  argv: process.argv
+  argv: process.argv,
+  currentVersion: pkg.version
 })));
 program.command("archive <page> [vault]").description("archive a typed-knowledge page").action(async (page, vault) => {
   const v = await resolveVaultArg(vault);
@@ -2139,6 +2368,11 @@ program.command("migrate-citations [vault]").description("migrate ^[raw/...] mar
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runMigrateCitations({ vault: v.vault, dryRun: !!opts.dryRun }));
 });
+program.command("update").description("update skillwiki CLI to the latest version").option("--tag <tag>", "npm dist-tag", "beta").action(async (opts) => emit(await runUpdate({
+  home: process.env.HOME ?? "",
+  distTag: opts.tag
+})));
+triggerAutoUpdate(process.env.HOME ?? "", pkg.version);
 program.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
   process.exit(1);

package/package.json

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

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

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

package/skills/package.json

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

package/skills/using-skillwiki/SKILL.md

@@ -25,6 +25,31 @@ Invoke a skillwiki skill when the user:
 - Has a spec/plan in a non-skillwiki format (CodeStable, RFC, AIDE)
 - Asks about their skillwiki configuration or setup health
 
+## Vault Structure
+
+A skillwiki vault has two layers:
+
+**Layer 1 — Raw (`raw/`):** Immutable source material. Never modify after ingest.
+
+```
+raw/
+├── articles/    # Web articles, clippings
+├── papers/      # PDFs, arxiv papers
+├── transcripts/ # Meeting notes, interviews
+└── assets/      # Images, diagrams referenced by sources
+```
+
+Raw frontmatter:
+```yaml
+---
+source_url: https://…
+ingested: YYYY-MM-DD
+sha256:          # computed by skillwiki hash over body bytes after closing ---
+---
+```
+
+**Layer 2 — Agent-owned pages:** `entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`, `projects/`. Citations use `^[raw/articles/source-file.md]` markers at paragraph-end.
+
 ## Skill Map
 
 | Skill | When to Invoke |