@bartolli/kmd 0.3.0 → 0.5.0

package/dist/kmd.mjs

@@ -15,6 +15,10 @@ var __export = (target, all) => {
 };
 
 // ../db/src/database.ts
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 function openDatabase(dbPath) {
   const db = new DatabaseSync(dbPath);
@@ -23,6 +27,34 @@ function openDatabase(dbPath) {
   db.exec(SCHEMA);
   return db;
 }
+function indexRootDir() {
+  const home = process.env.KMD_HOME ?? join(homedir(), ".kmd");
+  return join(home, "db");
+}
+function canonicalVaultRoot(vaultRoot2) {
+  try {
+    return realpathSync(vaultRoot2);
+  } catch {
+    return resolve(vaultRoot2);
+  }
+}
+function vaultKey(vaultRoot2) {
+  const canonical = canonicalVaultRoot(vaultRoot2);
+  const hash = createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+  return `${basename(canonical)}-${hash}`;
+}
+function resolveIndexPath(vaultRoot2) {
+  return join(indexRootDir(), vaultKey(vaultRoot2), "index.db");
+}
+function getMeta(db, key) {
+  const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+  return row?.value ?? null;
+}
+function setMeta(db, key, value) {
+  db.prepare(
+    "INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value"
+  ).run(key, value);
+}
 var SCHEMA;
 var init_database = __esm({
   "../db/src/database.ts"() {
@@ -73,17 +105,25 @@ CREATE TABLE IF NOT EXISTS events (
 );
 
 CREATE INDEX IF NOT EXISTS events_scope_ts ON events(scope, ts DESC);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
 `;
   }
 });
 
 // ../cli/src/config.ts
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join as join2 } from "node:path";
 import { parse } from "yaml";
 import { z } from "zod";
+function kindName(entry) {
+  return typeof entry === "string" ? entry : entry.name;
+}
 async function loadVaultConfig(vaultRoot2) {
-  const path = join(vaultRoot2, "vault.yaml");
+  const path = join2(vaultRoot2, "vault.yaml");
   let raw;
   try {
     raw = await readFile(path, "utf8");
@@ -98,18 +138,26 @@ ${issues}`);
   }
   return parsed.data;
 }
-var ScopeSchema, VaultConfigSchema;
+var ScopeSchema, KindEntrySchema, VaultConfigSchema, BUILT_IN_KINDS;
 var init_config = __esm({
   "../cli/src/config.ts"() {
     "use strict";
     ScopeSchema = z.object({
       repo: z.string().optional(),
-      methodology: z.enum(["sdd", "tdd", "hybrid"]).optional(),
+      methodology: z.string().optional(),
       status: z.string()
     });
+    KindEntrySchema = z.union([
+      z.string(),
+      z.object({
+        name: z.string(),
+        signal: z.string(),
+        where: z.string()
+      })
+    ]);
     VaultConfigSchema = z.object({
       scopes: z.record(z.string(), ScopeSchema),
-      kinds: z.array(z.string()),
+      kinds: z.array(KindEntrySchema),
       statuses: z.array(z.string()),
       methodologies: z.array(z.string()),
       tags: z.object({
@@ -117,8 +165,34 @@ var init_config = __esm({
         aliases: z.record(z.string(), z.string())
       }),
       authoring_rules: z.string().optional(),
-      sync_protocol: z.string().optional()
+      authoring_rules_extra: z.string().optional(),
+      sync_protocol: z.string().optional(),
+      sync_protocol_extra: z.string().optional()
+    }).superRefine((config, ctx) => {
+      for (const [name, scope] of Object.entries(config.scopes)) {
+        if (scope.methodology !== void 0 && !config.methodologies.includes(scope.methodology)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["scopes", name, "methodology"],
+            message: `"${scope.methodology}" is not in the methodologies list`
+          });
+        }
+      }
     });
+    BUILT_IN_KINDS = /* @__PURE__ */ new Set([
+      "project",
+      "spec",
+      "adr",
+      "plan",
+      "story",
+      "ops",
+      "topic",
+      "article",
+      "src",
+      "note",
+      "artifact",
+      "prompt"
+    ]);
   }
 });
 
@@ -147,11 +221,10 @@ var init_frontmatter = __esm({
 });
 
 // ../cli/src/sync.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { mkdirSync } from "node:fs";
 import { readdir, readFile as readFile2 } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join as join2, relative, sep } from "node:path";
+import { dirname, join as join3, relative, sep } from "node:path";
 import { z as z2 } from "zod";
 function loadEnv() {
   const parsed = EnvSchema.safeParse({
@@ -172,20 +245,20 @@ async function walkMarkdown(root, domain) {
     for (const entry of entries) {
       if (entry.name.startsWith(".")) continue;
       if (entry.isDirectory()) {
-        await recurse(join2(dir, entry.name));
+        await recurse(join3(dir, entry.name));
       } else if (entry.isFile() && entry.name.endsWith(".md")) {
-        out.push(join2(dir, entry.name));
+        out.push(join3(dir, entry.name));
       }
     }
   }
-  await recurse(join2(root, domain));
+  await recurse(join3(root, domain));
   return out;
 }
 function toRelativePath(root, absolute) {
   return relative(root, absolute).split(sep).join("/");
 }
 function sha256(content) {
-  return createHash("sha256").update(content).digest("hex");
+  return createHash2("sha256").update(content).digest("hex");
 }
 function extractWikilinks(body) {
   const links = [];
@@ -302,12 +375,11 @@ function syncPage(db, fields) {
 }
 async function runSync() {
   const env = loadEnv();
-  const dbDir = join2(homedir(), ".kmd", "db");
-  const dbPath = join2(dbDir, "index.db");
+  const dbPath = resolveIndexPath(env.WIKI_VAULT);
   console.log(`sync: ${env.WIKI_VAULT} \u2192 ${dbPath}`);
   const vaultConfig = await loadVaultConfig(env.WIKI_VAULT);
   const scopes = new Set(Object.keys(vaultConfig.scopes));
-  mkdirSync(dbDir, { recursive: true });
+  mkdirSync(dirname(dbPath), { recursive: true });
   const db = openDatabase(dbPath);
   try {
     const files = [];
@@ -347,6 +419,8 @@ async function runSync() {
       console.warn("no indexable pages found; skipping orphan deletion (safety)");
     }
     db.exec("INSERT INTO pages_fts(pages_fts) VALUES('rebuild')");
+    setMeta(db, "vault_root", canonicalVaultRoot(env.WIKI_VAULT));
+    setMeta(db, "last_synced", (/* @__PURE__ */ new Date()).toISOString());
     console.log(
       `done: ${changed} changed, ${unchanged} unchanged, ${skipped} skipped, ${pagesDeleted} pages deleted, ${linksDeleted} link orphans cleared`
     );
@@ -380,9 +454,13 @@ var init_sync = __esm({
 });
 
 // ../cli/src/validate.ts
-import { readFile as readFile3 } from "node:fs/promises";
+import { readFile as readFile3, stat } from "node:fs/promises";
+import { join as join4 } from "node:path";
+function hasIndexableTitle(data) {
+  return typeof data.title === "string" && data.title.trim() !== "";
+}
 function isIndexed(relPath, data) {
-  if (typeof data.title !== "string" || data.title.trim() === "") return false;
+  if (!hasIndexableTitle(data)) return false;
   if (typeof data.kind === "string" && data.kind !== "") return true;
   return relPath.startsWith("notes/");
 }
@@ -404,6 +482,45 @@ function checkRequiredFields(relPath, data) {
       });
     }
   }
+  if (Object.hasOwn(data, "title") && !hasIndexableTitle(data)) {
+    findings.push({
+      path: relPath,
+      rule: "required-fields",
+      severity: "error",
+      message: `"title" must be a non-empty string for kind "${kind}" \u2014 sync skips the page otherwise`
+    });
+  }
+  return findings;
+}
+function customKindNames(cfg) {
+  const names = /* @__PURE__ */ new Set();
+  for (const entry of cfg.kinds) {
+    if (typeof entry !== "string" && !BUILT_IN_KINDS.has(entry.name)) names.add(entry.name);
+  }
+  return names;
+}
+function checkCustomKindFloor(relPath, data, cfg) {
+  const kind = data.kind;
+  if (typeof kind !== "string" || !customKindNames(cfg).has(kind)) return [];
+  const findings = [];
+  for (const field of UNIVERSAL_FLOOR) {
+    if (!Object.hasOwn(data, field)) {
+      findings.push({
+        path: relPath,
+        rule: "custom-kind-floor",
+        severity: "warning",
+        message: `custom kind "${kind}": missing "${field}" \u2014 the universal floor (title, summary, updated) keeps the page retrievable`
+      });
+    }
+  }
+  if (Object.hasOwn(data, "title") && !hasIndexableTitle(data)) {
+    findings.push({
+      path: relPath,
+      rule: "custom-kind-floor",
+      severity: "warning",
+      message: `custom kind "${kind}": "title" is empty \u2014 sync skips title-less pages; this page will not be indexed`
+    });
+  }
   return findings;
 }
 function checkTagsRequired(relPath, data) {
@@ -435,7 +552,7 @@ function checkFolderSlug(relPath, data) {
 function checkVocabulary(relPath, data, cfg) {
   const findings = [];
   const kind = data.kind;
-  if (typeof kind === "string" && !cfg.kinds.includes(kind)) {
+  if (typeof kind === "string" && !cfg.kinds.some((k) => kindName(k) === kind)) {
     findings.push({
       path: relPath,
       rule: "kind-vocabulary",
@@ -496,7 +613,7 @@ function checkScopePath(relPath, data) {
 function refTarget(value) {
   if (typeof value !== "string") return null;
   const trimmed = value.trim();
-  return trimmed === "" ? null : basename(trimmed);
+  return trimmed === "" ? null : basename2(trimmed);
 }
 function refTargets(value) {
   if (Array.isArray(value)) {
@@ -512,7 +629,7 @@ function checkBodyLinks(relPath, body, refIndex) {
   const findings = [];
   for (const link of extractWikilinks(stripCode(body))) {
     if (!link.target.endsWith(".md")) continue;
-    if (!refIndex.has(basename(link.target))) {
+    if (!refIndex.has(basename2(link.target))) {
       findings.push({
         path: relPath,
         rule: "dangling-link",
@@ -574,7 +691,6 @@ function checkSupersededLink(relPath, data) {
 function checkIndexedPage(relPath, data, body, cfg, refIndex) {
   if (!isIndexed(relPath, data)) return [];
   return [
-    ...checkRequiredFields(relPath, data),
     ...checkTagsRequired(relPath, data),
     ...checkFolderSlug(relPath, data),
     ...checkVocabulary(relPath, data, cfg),
@@ -601,12 +717,16 @@ function validatePage(relPath, raw, cfg, refIndex) {
   if (isPrimer(relPath)) {
     return checkBodyLinks(relPath, parsed.content, refIndex);
   }
-  return checkIndexedPage(relPath, parsed.data, parsed.content, cfg, refIndex);
+  return [
+    ...checkRequiredFields(relPath, parsed.data),
+    ...checkCustomKindFloor(relPath, parsed.data, cfg),
+    ...checkIndexedPage(relPath, parsed.data, parsed.content, cfg, refIndex)
+  ];
 }
 function hasErrors(findings) {
   return findings.some((f) => f.severity === "error");
 }
-function basename(relPath) {
+function basename2(relPath) {
   const last = relPath.split("/").pop() ?? relPath;
   return last.replace(/\.md$/, "");
 }
@@ -614,7 +734,7 @@ function validateSupersession(pages) {
   const adrs = /* @__PURE__ */ new Map();
   for (const { path, data } of pages) {
     if (data.kind !== "adr") continue;
-    adrs.set(basename(path), {
+    adrs.set(basename2(path), {
       path,
       supersedes: refTargets(data.supersedes),
       supersededBy: refTargets(data.superseded_by)
@@ -660,7 +780,7 @@ function validateAmbiguousLinks(pages, basenameToPaths) {
     const here = locationKey(path);
     for (const link of extractWikilinks(stripCode(body))) {
       if (!link.target.endsWith(".md") || link.target.includes("/")) continue;
-      const base = basename(link.target);
+      const base = basename2(link.target);
       const owners = basenameToPaths.get(base);
       if (!owners || owners.length < 2) continue;
       if (here !== null && owners.some((p) => locationKey(p) === here)) continue;
@@ -682,7 +802,7 @@ async function validateVault(root) {
   }));
   const basenameToPaths = /* @__PURE__ */ new Map();
   for (const f of all) {
-    const b = basename(f.relPath);
+    const b = basename2(f.relPath);
     const owners = basenameToPaths.get(b);
     if (owners) owners.push(f.relPath);
     else basenameToPaths.set(b, [f.relPath]);
@@ -704,9 +824,22 @@ async function validateVault(root) {
   }
   findings.push(...validateSupersession(pages));
   findings.push(...validateAmbiguousLinks(linkPages, basenameToPaths));
+  for (const name of customKindNames(cfg)) {
+    const file = `templates/${name}.md`;
+    try {
+      await stat(join4(root, file));
+    } catch {
+      findings.push({
+        path: file,
+        rule: "custom-kind-template",
+        severity: "warning",
+        message: `custom kind "${name}" declared in vault.yaml has no template file`
+      });
+    }
+  }
   return findings;
 }
-var REQUIRED_FIELDS, TAG_OPTIONAL_KINDS, FOLDER_PATTERNS;
+var REQUIRED_FIELDS, TAG_OPTIONAL_KINDS, FOLDER_PATTERNS, UNIVERSAL_FLOOR;
 var init_validate = __esm({
   "../cli/src/validate.ts"() {
     "use strict";
@@ -757,6 +890,7 @@ var init_validate = __esm({
       topic: /^research\/[^/]+\/index\.md$/,
       src: /^research\/[^/]+\/src-[^/]+\.md$/
     };
+    UNIVERSAL_FLOOR = ["title", "summary", "updated"];
   }
 });
 
@@ -765,10 +899,14 @@ var cli_exports = {};
 __export(cli_exports, {
   main: () => main,
   resolveCli: () => resolveCli,
+  runConfig: () => runConfig,
+  runDbReset: () => runDbReset,
   runSyncCommand: () => runSyncCommand,
   runValidate: () => runValidate,
   vaultRoot: () => vaultRoot
 });
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { dirname as dirname2, join as join5 } from "node:path";
 import { parseArgs } from "node:util";
 function resolveCli(argv) {
   const { positionals: positionals2 } = parseArgs({ args: argv, allowPositionals: true, strict: false });
@@ -813,6 +951,76 @@ async function runSyncCommand() {
   }
   await runSync();
 }
+function describeVault(root) {
+  const vault = canonicalVaultRoot(root);
+  const index = resolveIndexPath(vault);
+  let synced = "never";
+  if (existsSync(index)) {
+    const db = openDatabase(index);
+    try {
+      synced = getMeta(db, "last_synced") ?? "never";
+    } finally {
+      db.close();
+    }
+  }
+  return { vault, index, synced };
+}
+function printVault(d) {
+  console.log(`vault: ${d.vault}`);
+  console.log(`index: ${d.index}`);
+  console.log(`synced: ${d.synced}`);
+}
+function knownVaults() {
+  const root = indexRootDir();
+  if (!existsSync(root)) return [];
+  const known = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const index = join5(root, entry.name, "index.db");
+    if (!existsSync(index)) continue;
+    const db = openDatabase(index);
+    try {
+      const vault = getMeta(db, "vault_root");
+      if (vault === null) continue;
+      known.push({ vault, index, synced: getMeta(db, "last_synced") ?? "never" });
+    } finally {
+      db.close();
+    }
+  }
+  return known;
+}
+async function runConfig() {
+  const root = process.env.WIKI_VAULT;
+  if (root) {
+    printVault(describeVault(root));
+    return;
+  }
+  const known = knownVaults();
+  if (known.length === 0) {
+    console.error(
+      "no vault specified and none known \u2014 pass a vault root, set WIKI_VAULT, or run `kmd sync <vault-root>` once"
+    );
+    process.exit(1);
+  }
+  known.forEach((d, i) => {
+    if (i > 0) console.log("");
+    printVault(d);
+  });
+}
+async function runDbReset() {
+  const root = process.env.WIKI_VAULT;
+  if (!root) {
+    console.error("usage: kmd db reset [<vault-root>] (or set WIKI_VAULT)");
+    process.exit(2);
+  }
+  const dir = dirname2(resolveIndexPath(root));
+  if (!existsSync(dir)) {
+    console.log(`${dir} does not exist \u2014 nothing to reset`);
+    return;
+  }
+  rmSync(dir, { recursive: true, force: true });
+  console.log(`deleted ${dir}`);
+}
 async function main() {
   const resolution = resolveCli(process.argv.slice(2));
   if (resolution.kind === "error") {
@@ -828,6 +1036,7 @@ async function main() {
 var init_cli = __esm({
   "../cli/src/cli.ts"() {
     "use strict";
+    init_database();
     init_sync();
     init_validate();
   }
@@ -864,13 +1073,13 @@ var init_config2 = __esm({
 
 // ../mcp/src/db.ts
 import { mkdirSync as mkdirSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { join as join3 } from "node:path";
-function createDatabase() {
-  const dbDir = join3(homedir2(), ".kmd", "db");
-  const dbPath = join3(dbDir, "index.db");
-  mkdirSync2(dbDir, { recursive: true });
-  return openDatabase(dbPath);
+import { dirname as dirname3 } from "node:path";
+function createDatabase(vaultRoot2) {
+  const dbPath = resolveIndexPath(vaultRoot2);
+  mkdirSync2(dirname3(dbPath), { recursive: true });
+  const db = openDatabase(dbPath);
+  setMeta(db, "vault_root", canonicalVaultRoot(vaultRoot2));
+  return db;
 }
 var init_db = __esm({
   "../mcp/src/db.ts"() {
@@ -881,8 +1090,8 @@ var init_db = __esm({
 
 // ../mcp/src/lib/diag.ts
 import { appendFileSync, mkdirSync as mkdirSync3 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { join as join4 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+import { join as join6 } from "node:path";
 function diag(msg, data) {
   try {
     const line = data ? `${(/* @__PURE__ */ new Date()).toISOString()} pid=${process.pid} ${msg} ${JSON.stringify(data)}
@@ -896,8 +1105,8 @@ var DIAG_DIR, DIAG_LOG_PATH;
 var init_diag = __esm({
   "../mcp/src/lib/diag.ts"() {
     "use strict";
-    DIAG_DIR = join4(homedir3(), ".local", "state", "wiki-mcp");
-    DIAG_LOG_PATH = join4(DIAG_DIR, "server.log");
+    DIAG_DIR = join6(homedir2(), ".local", "state", "wiki-mcp");
+    DIAG_LOG_PATH = join6(DIAG_DIR, "server.log");
     try {
       mkdirSync3(DIAG_DIR, { recursive: true });
     } catch {
@@ -924,23 +1133,111 @@ var init_logger = __esm({
   }
 });
 
+// ../mcp/src/vault-config.ts
+import { readFile as readFile4 } from "node:fs/promises";
+import { join as join7 } from "node:path";
+import { parse as parse2 } from "yaml";
+import { z as z4 } from "zod";
+function kindName2(entry) {
+  return typeof entry === "string" ? entry : entry.name;
+}
+async function loadVaultConfig2(vaultRoot2) {
+  const path = join7(vaultRoot2, "vault.yaml");
+  let raw;
+  try {
+    raw = await readFile4(path, "utf8");
+  } catch (err) {
+    throw new Error(`vault.yaml not found at ${path}`, { cause: err });
+  }
+  const parsed = VaultConfigSchema2.safeParse(parse2(raw));
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`Invalid vault.yaml at ${path}:
+${issues}`);
+  }
+  return parsed.data;
+}
+var ScopeSchema2, KindEntrySchema2, VaultConfigSchema2, BUILT_IN_KINDS2;
+var init_vault_config = __esm({
+  "../mcp/src/vault-config.ts"() {
+    "use strict";
+    ScopeSchema2 = z4.object({
+      repo: z4.string().optional(),
+      methodology: z4.string().optional(),
+      status: z4.string()
+    });
+    KindEntrySchema2 = z4.union([
+      z4.string(),
+      z4.object({
+        name: z4.string(),
+        signal: z4.string(),
+        where: z4.string()
+      })
+    ]);
+    VaultConfigSchema2 = z4.object({
+      scopes: z4.record(z4.string(), ScopeSchema2),
+      kinds: z4.array(KindEntrySchema2),
+      statuses: z4.array(z4.string()),
+      methodologies: z4.array(z4.string()),
+      tags: z4.object({
+        canonical: z4.array(z4.string()),
+        aliases: z4.record(z4.string(), z4.string())
+      }),
+      authoring_rules: z4.string().optional(),
+      authoring_rules_extra: z4.string().optional(),
+      sync_protocol: z4.string().optional(),
+      sync_protocol_extra: z4.string().optional()
+    }).superRefine((config, ctx) => {
+      for (const [name, scope] of Object.entries(config.scopes)) {
+        if (scope.methodology !== void 0 && !config.methodologies.includes(scope.methodology)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["scopes", name, "methodology"],
+            message: `"${scope.methodology}" is not in the methodologies list`
+          });
+        }
+      }
+    });
+    BUILT_IN_KINDS2 = /* @__PURE__ */ new Set([
+      "project",
+      "spec",
+      "adr",
+      "plan",
+      "story",
+      "ops",
+      "topic",
+      "article",
+      "src",
+      "note",
+      "artifact",
+      "prompt"
+    ]);
+  }
+});
+
 // ../mcp/src/resources/authoring.ts
 function buildAuthoringRules(config) {
-  return ["## Authoring rules", "", config.authoring_rules ?? DEFAULT_AUTHORING_RULES].join("\n");
+  const parts = [(config.authoring_rules ?? DEFAULT_AUTHORING_RULES).trim()];
+  if (config.authoring_rules_extra) parts.push(config.authoring_rules_extra.trim());
+  return ["## Authoring rules", "", parts.join("\n\n")].join("\n");
 }
 function buildSyncProtocol(config) {
-  return ["## Resync protocol", "", config.sync_protocol ?? DEFAULT_SYNC_PROTOCOL].join("\n");
+  const parts = [(config.sync_protocol ?? DEFAULT_SYNC_PROTOCOL).trim()];
+  if (config.sync_protocol_extra) parts.push(config.sync_protocol_extra.trim());
+  return ["## Resync protocol", "", parts.join("\n\n")].join("\n");
 }
 function buildKindSelector(kinds) {
   const lines = ["## Kind selector", "", "| Signal | Kind | Where |", "|---|---|---|"];
-  for (const kind of kinds) {
-    const pedagogy = KIND_PEDAGOGY.get(kind);
+  for (const entry of kinds) {
+    const name = kindName2(entry);
+    const pedagogy = typeof entry === "string" ? KIND_PEDAGOGY.get(entry) : entry;
     const signal = pedagogy?.signal ?? "\u2014";
     const where = pedagogy?.where ?? "\u2014";
-    lines.push(`| ${signal} | **${kind}** | ${where} |`);
+    lines.push(`| ${signal} | **${name}** | ${where} |`);
   }
-  const hasNote = kinds.includes("note");
-  const hasAdrAndSpec = kinds.includes("adr") && kinds.includes("spec");
+  const names = kinds.map(kindName2);
+  const hasNote = names.includes("note");
+  const hasAdrAndSpec = names.includes("adr") && names.includes("spec");
   if (hasNote || hasAdrAndSpec) {
     const hints = [];
     if (hasNote) hints.push("If none fits \u2192 note.");
@@ -953,12 +1250,16 @@ function buildKindSelector(kinds) {
   }
   return lines.join("\n");
 }
+function buildStatusLine(statuses) {
+  const isCanonical = statuses.length === CANONICAL_STATUS_FLOW.length && statuses.every((s, i) => s === CANONICAL_STATUS_FLOW[i]);
+  return isCanonical ? `**Statuses:** ${statuses.join(" \u2192 ")} (one-directional; superseded requires superseded_by link)` : `**Statuses:** ${statuses.join(", ")}`;
+}
 function buildVocabulary(config) {
   const lines = [
     "## Controlled vocabulary",
     "",
-    `**Kinds:** ${config.kinds.join(", ")}`,
-    `**Statuses:** ${config.statuses.join(" \u2192 ")} (one-directional; superseded requires superseded_by link)`,
+    `**Kinds:** ${config.kinds.map(kindName2).join(", ")}`,
+    buildStatusLine(config.statuses),
     `**Methodologies:** ${config.methodologies.join(", ")}`,
     `**Canonical tags:** ${config.tags.canonical.join(", ")}`
   ];
@@ -968,7 +1269,7 @@ function buildVocabulary(config) {
   }
   return lines.join("\n");
 }
-function registerAuthoringResource(mcp, _vaultRoot, vaultConfig) {
+function registerAuthoringResource(mcp, vaultRoot2, vaultConfig) {
   mcp.registerResource(
     "Authoring guide",
     "wiki://authoring",
@@ -980,6 +1281,8 @@ function registerAuthoringResource(mcp, _vaultRoot, vaultConfig) {
       const sections = [
         "# Wiki authoring guide",
         "",
+        `Vault root: \`${canonicalVaultRoot(vaultRoot2)}\` \u2014 every page path below is relative to it; write files and run \`kmd validate\` / \`kmd sync\` against it.`,
+        "",
         buildKindSelector(vaultConfig.kinds),
         "",
         buildVocabulary(vaultConfig),
@@ -1004,10 +1307,12 @@ function registerAuthoringResource(mcp, _vaultRoot, vaultConfig) {
     }
   );
 }
-var KIND_PEDAGOGY, DEFAULT_AUTHORING_RULES, DEFAULT_SYNC_PROTOCOL;
+var KIND_PEDAGOGY, DEFAULT_AUTHORING_RULES, DEFAULT_SYNC_PROTOCOL, CANONICAL_STATUS_FLOW;
 var init_authoring = __esm({
   "../mcp/src/resources/authoring.ts"() {
     "use strict";
+    init_database();
+    init_vault_config();
     KIND_PEDAGOGY = /* @__PURE__ */ new Map([
       [
         "project",
@@ -1089,33 +1394,73 @@ var init_authoring = __esm({
       ]
     ]);
     DEFAULT_AUTHORING_RULES = [
+      "**Where things go**",
+      "",
       "- **Use the matching template** via `wiki://template/{domain}/{kind}` (MCP) or from `templates/` (filesystem). Don't hand-roll frontmatter.",
-      '- **Quote prose-bearing frontmatter scalars.** `summary: "..."` \u2014 unquoted `Word: phrase` patterns break the YAML parser.',
-      "- **On any edit, update the frontmatter `updated` field.**",
       "- **Folder name = slug prefix in `projects/`.** `spec/spec-x.md`, `adr/adr-y.md`, `plan/plan-z.md`, `ops/ops-w.md`. Stories use `story-` prefix under `plan/{plan-name}/`.",
-      "- **Research is flat.** Articles are `{subject}.md`; sources are `src-{slug}.md`. Avoid generic slugs (`architecture.md`, `notes.md`).",
+      "- **Research is flat.** Articles are `{subject}.md`; sources are `src-{slug}.md`. The topic folder names a *frame*, the article slug names a *subject*. Avoid generic slugs (`architecture.md`, `notes.md`) and slugs that collide with project scopes.",
+      "- **Extend before you split.** Prefer sharpening the existing spec, ADR, or article over creating a near-duplicate page. A new page needs a new subject, not a new session.",
+      "",
+      "**Frontmatter**",
+      "",
+      '- **`summary` is the retrieval contract.** One sentence stating the page\'s decision or claim, not its topic. Search and `prime` rank by it \u2014 "Chose X over Y because Z" surfaces; "About the sync pipeline" sinks.',
+      '- **Quote prose-bearing scalars.** `summary: "..."` \u2014 unquoted `Word: phrase` patterns break the YAML parser.',
+      "- **On any edit, update `updated`.** Never change `created` \u2014 it is write-once.",
       "- **Notes have no `kind` field** \u2014 implied by location. Sync sets `kind: note`.",
       "- **Reuse existing tags** (visible in `prime` response `top_tags`). No synonyms.",
+      "",
+      "**Content**",
+      "",
+      "- **ADR and ops pages are predicate-only.** No definitional preambles for established vocabulary, no narrative, no marketing. The audience is the project team \u2014 assume fluency.",
+      "- **Spec / ADR edits land inline with the change that surfaces them.** Don't queue corrections in plans \u2014 the spec reflects current code at every commit.",
+      "",
+      "**Linking**",
+      "",
+      "- **Cross-reference with `[[wikilinks]]`, and link every mention of another vault page** \u2014 backlinks are the navigation graph for humans and agents alike. Don't link pages that don't exist yet: dangling links fail validation.",
       "- **ADR supersession is bidirectional**: `superseded_by` on the old ADR + `supersedes` on the new one.",
-      "- **Sources convention**: external paths/URLs go inline in body text. Vault-internal `raw/` paths go in frontmatter `sources:` array. Don't mix the two surfaces.",
-      "- **Spec / ADR edits land inline with the slice that surfaces them.** Don't queue corrections in plans. The spec must reflect current code at every commit."
+      "- **Sources convention**: external paths/URLs go inline in body text. Vault-internal `raw/` paths go in frontmatter `sources:` array. Don't mix the two surfaces."
+    ].join("\n");
+    DEFAULT_SYNC_PROTOCOL = [
+      "Edit the smallest set of files that reflects the change. A milestone tick is plan-only; don't cascade to index.md unless phase or status changed. Controlled-vocabulary edits (`vault.yaml`) need explicit user approval.",
+      "After editing wiki pages, run `kmd validate` and fix findings before `kmd sync` \u2014 it checks frontmatter shape, vocabulary membership, and link integrity."
     ].join("\n");
-    DEFAULT_SYNC_PROTOCOL = "Edit the smallest set of files that reflects the change. A milestone tick is plan-only; don't cascade to index.md unless phase or status changed. Controlled-vocabulary edits need explicit user approval.";
+    CANONICAL_STATUS_FLOW = ["draft", "active", "superseded", "archived"];
   }
 });
 
 // ../mcp/src/resources/templates.ts
-import { readFile as readFile4 } from "node:fs/promises";
-import { join as join5 } from "node:path";
-function registerTemplateResources(mcp, vaultRoot2) {
-  const dir = join5(vaultRoot2, "templates");
-  for (const tmpl of TEMPLATES) {
+import { readFile as readFile5 } from "node:fs/promises";
+import { join as join8 } from "node:path";
+function customTemplates(config) {
+  const specs = [];
+  for (const entry of config.kinds) {
+    if (typeof entry === "string" || BUILT_IN_KINDS2.has(entry.name)) continue;
+    specs.push({
+      uri: `wiki://template/${entry.name}`,
+      name: entry.name.charAt(0).toUpperCase() + entry.name.slice(1),
+      file: `${entry.name}.md`,
+      description: entry.signal
+    });
+  }
+  return specs;
+}
+function registerTemplateResources(mcp, vaultRoot2, vaultConfig) {
+  const dir = join8(vaultRoot2, "templates");
+  const templates = [...TEMPLATES, ...customTemplates(vaultConfig)];
+  for (const tmpl of templates) {
     mcp.registerResource(
       tmpl.name,
       tmpl.uri,
       { description: tmpl.description, mimeType: "text/markdown" },
       async (uri) => {
-        const text = await readFile4(join5(dir, tmpl.file), "utf8");
+        let text;
+        try {
+          text = await readFile5(join8(dir, tmpl.file), "utf8");
+        } catch (err) {
+          throw new Error(`template file missing: templates/${tmpl.file} (${tmpl.uri})`, {
+            cause: err
+          });
+        }
         return {
           contents: [
             {
@@ -1129,7 +1474,7 @@ function registerTemplateResources(mcp, vaultRoot2) {
     );
   }
   const indexLines = ["# Wiki Templates", ""];
-  for (const tmpl of TEMPLATES) {
+  for (const tmpl of templates) {
     indexLines.push(`- **${tmpl.name}** \u2014 \`${tmpl.uri}\`  `);
     indexLines.push(`  ${tmpl.description}`);
   }
@@ -1150,6 +1495,7 @@ var TEMPLATES;
 var init_templates = __esm({
   "../mcp/src/resources/templates.ts"() {
     "use strict";
+    init_vault_config();
     TEMPLATES = [
       {
         uri: "wiki://template/project/index",
@@ -1289,15 +1635,15 @@ var init_toolResponse = __esm({
 });
 
 // ../mcp/src/tools/prime.ts
-import { readFile as readFile5 } from "node:fs/promises";
-import { basename as basename2, join as join6 } from "node:path";
-import { z as z4 } from "zod";
+import { readFile as readFile6 } from "node:fs/promises";
+import { basename as basename3, join as join9 } from "node:path";
+import { z as z5 } from "zod";
 function pathSlug(p) {
-  return basename2(p).replace(/\.md$/, "");
+  return basename3(p).replace(/\.md$/, "");
 }
 async function readIndexFm(vaultRoot2, scope) {
   try {
-    const raw = await readFile5(join6(vaultRoot2, "projects", scope, "index.md"), "utf8");
+    const raw = await readFile6(join9(vaultRoot2, "projects", scope, "index.md"), "utf8");
     return parseFrontmatter2(raw).data;
   } catch {
     return {};
@@ -1305,7 +1651,7 @@ async function readIndexFm(vaultRoot2, scope) {
 }
 async function readPrimer(vaultRoot2, scope) {
   try {
-    const raw = await readFile5(join6(vaultRoot2, "projects", scope, "primer.md"), "utf8");
+    const raw = await readFile6(join9(vaultRoot2, "projects", scope, "primer.md"), "utf8");
     return parseFrontmatter2(raw).content.trim().replace(/^#\s+[^\n]+\n+/, "");
   } catch {
     return "";
@@ -1370,6 +1716,7 @@ async function prime(deps, input) {
   for (const row of counts) countsRecord[row.kind] = Number(row.count);
   const data = {
     scope,
+    vault_root: canonicalVaultRoot(vaultRoot2),
     title: fm.title ?? null,
     methodology: fm.methodology ?? null,
     phase: typeof fm.phase === "number" ? fm.phase : null,
@@ -1413,6 +1760,7 @@ function renderMarkdown(d, config, task) {
   const header = phaseLabel ? `${d.scope} \u2014 ${phaseLabel}` : d.scope;
   lines.push(`# ${header}`);
   if (d.summary) lines.push(d.summary);
+  lines.push(`Vault root: \`${d.vault_root}\``);
   if (d.primer) {
     lines.push("", "## Primer", d.primer);
   }
@@ -1432,7 +1780,7 @@ function renderMarkdown(d, config, task) {
     lines.push(countEntries.map(([k, n]) => `${k}: ${n}`).join(" | "));
   }
   lines.push("", "## Vocabulary");
-  lines.push(`kinds: ${config.kinds.join(", ")}`);
+  lines.push(`kinds: ${config.kinds.map(kindName2).join(", ")}`);
   lines.push(`statuses: ${config.statuses.join(", ")}`);
   lines.push(`tags: ${config.tags.canonical.join(", ")}`);
   if (d.top_tags.length > 0) {
@@ -1466,7 +1814,7 @@ function renderMarkdown(d, config, task) {
   lines.push(
     "",
     "---",
-    "Authoring wiki content? Read `wiki://authoring` for kind selector, rules, and templates."
+    "Authoring wiki content? Read `wiki://authoring` for kind selector, rules, and templates. After edits: `kmd validate`, then `kmd sync`."
   );
   return lines.join("\n");
 }
@@ -1492,18 +1840,20 @@ var PrimeInputSchema;
 var init_prime = __esm({
   "../mcp/src/tools/prime.ts"() {
     "use strict";
+    init_database();
     init_frontmatter2();
     init_fts();
     init_toolResponse();
-    PrimeInputSchema = z4.object({
-      scope: z4.string().min(1).describe("Project scope to prime (matches projects/{scope}/ in the vault)."),
-      task: z4.string().optional().describe("Optional task description; surfaces top-3 tsvector-ranked relevant pages.")
+    init_vault_config();
+    PrimeInputSchema = z5.object({
+      scope: z5.string().min(1).describe("Project scope to prime (matches projects/{scope}/ in the vault)."),
+      task: z5.string().optional().describe("Optional task description; surfaces top-3 tsvector-ranked relevant pages.")
     });
   }
 });
 
 // ../mcp/src/tools/search.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 function search(deps, input) {
   const ftsQuery = sanitizeFtsQuery(input.query);
   if (!ftsQuery) return { results: [] };
@@ -1550,15 +1900,15 @@ var init_search = __esm({
     "use strict";
     init_fts();
     init_toolResponse();
-    SearchInputSchema = z5.object({
-      query: z5.string().min(1).describe(
+    SearchInputSchema = z6.object({
+      query: z6.string().min(1).describe(
         "Natural-language search query. Matched against title, summary, and body via SQLite FTS5."
       ),
-      scope: z5.string().optional().describe('Optional: restrict to a project scope (e.g. "ontology", "sotto").'),
-      kind: z5.string().optional().describe(
+      scope: z6.string().optional().describe('Optional: restrict to a project scope (e.g. "ontology", "sotto").'),
+      kind: z6.string().optional().describe(
         "Optional: restrict to a kind. Project kinds: spec, adr, plan, ops. Research kinds: article, src. Misc: note."
       ),
-      limit: z5.number().int().min(1).max(50).default(5).describe("Maximum number of ranked results to return. Default 5.")
+      limit: z6.number().int().min(1).max(50).default(5).describe("Maximum number of ranked results to return. Default 5.")
     });
   }
 });
@@ -1586,7 +1936,7 @@ function buildServer(args) {
       return handleSearch({ db }, input);
     }
   );
-  registerTemplateResources(mcp, vaultRoot2);
+  registerTemplateResources(mcp, vaultRoot2, vaultConfig);
   registerAuthoringResource(mcp, vaultRoot2, vaultConfig);
   return mcp;
 }
@@ -1600,51 +1950,6 @@ var init_server = __esm({
   }
 });
 
-// ../mcp/src/vault-config.ts
-import { readFile as readFile6 } from "node:fs/promises";
-import { join as join7 } from "node:path";
-import { parse as parse2 } from "yaml";
-import { z as z6 } from "zod";
-async function loadVaultConfig2(vaultRoot2) {
-  const path = join7(vaultRoot2, "vault.yaml");
-  let raw;
-  try {
-    raw = await readFile6(path, "utf8");
-  } catch (err) {
-    throw new Error(`vault.yaml not found at ${path}`, { cause: err });
-  }
-  const parsed = VaultConfigSchema2.safeParse(parse2(raw));
-  if (!parsed.success) {
-    const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
-    throw new Error(`Invalid vault.yaml at ${path}:
-${issues}`);
-  }
-  return parsed.data;
-}
-var ScopeSchema2, VaultConfigSchema2;
-var init_vault_config = __esm({
-  "../mcp/src/vault-config.ts"() {
-    "use strict";
-    ScopeSchema2 = z6.object({
-      repo: z6.string().optional(),
-      methodology: z6.enum(["sdd", "tdd", "hybrid"]).optional(),
-      status: z6.string()
-    });
-    VaultConfigSchema2 = z6.object({
-      scopes: z6.record(z6.string(), ScopeSchema2),
-      kinds: z6.array(z6.string()),
-      statuses: z6.array(z6.string()),
-      methodologies: z6.array(z6.string()),
-      tags: z6.object({
-        canonical: z6.array(z6.string()),
-        aliases: z6.record(z6.string(), z6.string())
-      }),
-      authoring_rules: z6.string().optional(),
-      sync_protocol: z6.string().optional()
-    });
-  }
-});
-
 // ../mcp/src/start.ts
 var start_exports = {};
 __export(start_exports, {
@@ -1666,7 +1971,7 @@ async function startMcpServer() {
     { vault: config.wikiVault, serverName: config.serverName, serverVersion: config.serverVersion },
     "starting wiki-mcp on stdio"
   );
-  const db = createDatabase();
+  const db = createDatabase(config.wikiVault);
   diag("database opened");
   const mcp = buildServer({
     name: config.serverName,
@@ -1712,10 +2017,11 @@ import { parseArgs as parseArgs2 } from "node:util";
 var USAGE = `usage: kmd <command> [options]
 
 commands:
-  sync                 vault \u2192 index sync (runs validate first)
-  validate [<path>]    deterministic vault checker (default: $WIKI_VAULT)
-  mcp [<vault-root>]   start the stdio MCP server (default: $WIKI_VAULT)
-  db reset             delete and recreate the index
+  sync                     vault \u2192 index sync (runs validate first)
+  validate [<path>]        deterministic vault checker (default: $WIKI_VAULT)
+  mcp [<vault-root>]       start the stdio MCP server (default: $WIKI_VAULT)
+  config [<vault-root>]    print vault + index resolution; with no vault, list known vaults
+  db reset [<vault-root>]  delete the vault's index (default: $WIKI_VAULT)
 
 options:
   --version   print version
@@ -1755,25 +2061,20 @@ async function run() {
       await startMcpServer2();
       break;
     }
+    case "config": {
+      applyVaultRoot(1);
+      const { runConfig: runConfig2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
+      await runConfig2();
+      break;
+    }
     case "db": {
       const sub = positionals[1];
       if (sub === "reset") {
-        const { homedir: homedir4 } = await import("node:os");
-        const { join: join8 } = await import("node:path");
-        const { unlinkSync } = await import("node:fs");
-        const dbPath = join8(homedir4(), ".kmd", "db", "index.db");
-        let deleted = false;
-        for (const suffix of ["", "-wal", "-shm"]) {
-          try {
-            unlinkSync(dbPath + suffix);
-            deleted = true;
-          } catch (err) {
-            if (err.code !== "ENOENT") throw err;
-          }
-        }
-        console.log(deleted ? `deleted ${dbPath}` : `${dbPath} does not exist \u2014 nothing to reset`);
+        applyVaultRoot(2);
+        const { runDbReset: runDbReset2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
+        await runDbReset2();
       } else {
-        console.error(sub ? `unknown db subcommand: ${sub}` : "usage: kmd db reset");
+        console.error(sub ? `unknown db subcommand: ${sub}` : "usage: kmd db reset [<vault-root>]");
         process.exit(2);
       }
       break;
@@ -1781,10 +2082,10 @@ async function run() {
     case "--version":
     case "-v": {
       const { readFileSync } = await import("node:fs");
-      const { join: join8, dirname } = await import("node:path");
+      const { join: join10, dirname: dirname4 } = await import("node:path");
       const { fileURLToPath } = await import("node:url");
-      const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
-      const pkg = JSON.parse(readFileSync(join8(pkgDir, "package.json"), "utf8"));
+      const pkgDir = dirname4(dirname4(fileURLToPath(import.meta.url)));
+      const pkg = JSON.parse(readFileSync(join10(pkgDir, "package.json"), "utf8"));
       console.log(pkg.version);
       break;
     }