@bartolli/kmd 0.10.0 → 0.12.0

package/dist/kmd.mjs

@@ -16,9 +16,9 @@ var __export = (target, all) => {
 
 // ../db/src/database.ts
 import { createHash } from "node:crypto";
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 function openDatabase(dbPath) {
   const db = new DatabaseSync(dbPath);
@@ -33,20 +33,35 @@ function kmdHome() {
 function indexRootDir() {
   return join(kmdHome(), "db");
 }
-function canonicalVaultRoot(vaultRoot2) {
+function canonicalVaultRoot(vaultRoot) {
   try {
-    return realpathSync(vaultRoot2);
+    return realpathSync(vaultRoot);
   } catch {
-    return resolve(vaultRoot2);
+    return resolve(vaultRoot);
   }
 }
-function vaultKey(vaultRoot2) {
-  const canonical = canonicalVaultRoot(vaultRoot2);
+function vaultKey(vaultRoot) {
+  const canonical = canonicalVaultRoot(vaultRoot);
   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 tierKmdDir(canonical) {
+  for (const stateHome of [join(canonical, ".kmd"), join(dirname(canonical), ".kmd")]) {
+    if (existsSync(stateHome)) return stateHome;
+  }
+  return null;
+}
+function resolveIndexPath(vaultRoot) {
+  const canonical = canonicalVaultRoot(vaultRoot);
+  const tier = tierKmdDir(canonical);
+  if (tier !== null) return join(tier, "db", "index.db");
+  return join(indexRootDir(), vaultKey(canonical), "index.db");
+}
+function resolveStateDir(vaultRoot) {
+  const canonical = canonicalVaultRoot(vaultRoot);
+  const tier = tierKmdDir(canonical);
+  if (tier !== null) return join(tier, "state", "hook");
+  return join(kmdHome(), "state", "hook");
 }
 function getMeta(db, key) {
   const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
@@ -116,11 +131,159 @@ CREATE TABLE IF NOT EXISTS meta (
   }
 });
 
+// ../db/src/kmd-config.ts
+var kmd_config_exports = {};
+__export(kmd_config_exports, {
+  expandVars: () => expandVars,
+  findProjectTier: () => findProjectTier,
+  globalConfigPath: () => globalConfigPath,
+  loadGlobalConfig: () => loadGlobalConfig,
+  resolveVaultRoot: () => resolveVaultRoot,
+  setGlobalConfigValue: () => setGlobalConfigValue,
+  unsetGlobalConfigValue: () => unsetGlobalConfigValue
+});
+import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, isAbsolute, join as join2, resolve as resolve2 } from "node:path";
+import { Document, parse, parseDocument } from "yaml";
+import { z } from "zod";
+function expandVars(value, env = process.env) {
+  return value.replace(
+    /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g,
+    (_match, name, fallback) => {
+      const resolved = env[name];
+      if (resolved !== void 0 && resolved !== "") return resolved;
+      if (fallback !== void 0) return fallback;
+      throw new Error(`unresolved \${${name}} (variable unset, no :-default)`);
+    }
+  );
+}
+function expandHome(value) {
+  if (value === "~" || value.startsWith("~/")) return join2(homedir2(), value.slice(1));
+  return value;
+}
+function loadYamlFile(path, schema) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  const parsed = schema.safeParse(parse(raw) ?? {});
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`invalid config: ${path}
+${issues}`);
+  }
+  return parsed.data;
+}
+function globalConfigPath() {
+  return join2(kmdHome(), "config.yaml");
+}
+function loadGlobalConfig(env = process.env) {
+  const config = loadYamlFile(globalConfigPath(), GlobalConfigSchema);
+  if (config === null || config.default_vault === void 0) return {};
+  const expanded = expandHome(expandVars(config.default_vault, env));
+  if (!isAbsolute(expanded)) {
+    throw new Error(
+      `invalid config: ${globalConfigPath()}
+  - default_vault: must be absolute or ~/ (got "${config.default_vault}")`
+    );
+  }
+  return { default_vault: expanded };
+}
+function loadGlobalDocument() {
+  try {
+    return parseDocument(readFileSync(globalConfigPath(), "utf8"));
+  } catch {
+    return new Document({});
+  }
+}
+function flushGlobalDocument(doc) {
+  mkdirSync(kmdHome(), { recursive: true });
+  writeFileSync(globalConfigPath(), doc.toString());
+}
+function setGlobalConfigValue(key, value) {
+  const doc = loadGlobalDocument();
+  doc.set(key, value);
+  flushGlobalDocument(doc);
+}
+function unsetGlobalConfigValue(key) {
+  const doc = loadGlobalDocument();
+  if (!doc.has(key)) return false;
+  doc.delete(key);
+  flushGlobalDocument(doc);
+  return true;
+}
+function projectVaultAt(level, env, onSkip) {
+  for (const [file, via] of TIER_CONFIG_FILES) {
+    const path = join2(level, ".kmd", file);
+    const config = loadYamlFile(path, ProjectConfigSchema);
+    if (config === null || config.vault === void 0) continue;
+    const expanded = expandHome(expandVars(config.vault, env));
+    return {
+      tierRoot: level,
+      vaultRoot: isAbsolute(expanded) ? expanded : resolve2(level, expanded),
+      via
+    };
+  }
+  if (existsSync2(join2(level, "vault", "vault.yaml"))) {
+    return { tierRoot: level, vaultRoot: join2(level, "vault"), via: "convention" };
+  }
+  if (existsSync2(join2(level, "vault.yaml"))) {
+    if (existsSync2(join2(level, ".kmd"))) {
+      return { tierRoot: level, vaultRoot: level, via: "convention" };
+    }
+    onSkip?.(join2(level, "vault.yaml"));
+  }
+  return null;
+}
+function findProjectTier(fromDir, env = process.env, onSkip) {
+  let level = canonicalVaultRoot(fromDir);
+  for (; ; ) {
+    const hit = projectVaultAt(level, env, onSkip);
+    if (hit !== null) return hit;
+    const parent = dirname2(level);
+    if (parent === level) return null;
+    level = parent;
+  }
+}
+function resolveVaultRoot(input) {
+  if (input.positional) return { root: input.positional, source: "positional" };
+  if (input.projectDir) {
+    const tier = findProjectTier(input.projectDir, input.env ?? process.env, input.onSkip);
+    if (tier !== null) {
+      return { root: tier.vaultRoot, source: `project-${tier.via}`, tierRoot: tier.tierRoot };
+    }
+  }
+  if (input.defaultRoot) return { root: input.defaultRoot, source: "default-root" };
+  if (input.envVault) return { root: input.envVault, source: "env" };
+  if (input.globalDefault) return { root: input.globalDefault, source: "global-config" };
+  return { root: null, source: "none" };
+}
+var GlobalConfigSchema, ProjectConfigSchema, TIER_CONFIG_FILES;
+var init_kmd_config = __esm({
+  "../db/src/kmd-config.ts"() {
+    "use strict";
+    init_database();
+    GlobalConfigSchema = z.strictObject({
+      default_vault: z.string().min(1).optional()
+    });
+    ProjectConfigSchema = z.strictObject({
+      vault: z.string().min(1).optional()
+    });
+    TIER_CONFIG_FILES = [
+      ["config.local.yaml", "local-config"],
+      ["config.yaml", "config"]
+    ];
+  }
+});
+
 // ../db/src/vault-config.ts
 import { readFile } from "node:fs/promises";
-import { join as join2 } from "node:path";
-import { parse } from "yaml";
-import { z } from "zod";
+import { join as join3 } from "node:path";
+import { parse as parse2 } from "yaml";
+import { z as z2 } from "zod";
 function isValidRegex(pattern) {
   try {
     return Boolean(new RegExp(pattern));
@@ -132,17 +295,17 @@ function kindName(entry) {
   return typeof entry === "string" ? entry : entry.name;
 }
 function configJsonSchema() {
-  return z.toJSONSchema(VaultConfigSchema, { target: "draft-7" });
+  return z2.toJSONSchema(VaultConfigSchema, { target: "draft-7" });
 }
-async function loadVaultConfig(vaultRoot2) {
-  const path = join2(vaultRoot2, "vault.yaml");
+async function loadVaultConfig(vaultRoot) {
+  const path = join3(vaultRoot, "vault.yaml");
   let raw;
   try {
     raw = await readFile(path, "utf8");
   } catch (err) {
     throw new Error(`vault.yaml not found at ${path}`, { cause: err });
   }
-  const parsed = VaultConfigSchema.safeParse(parse(raw));
+  const parsed = VaultConfigSchema.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}:
@@ -154,47 +317,47 @@ var ScopeSchema, KindEntrySchema, WhenSchema, DedupSchema, TriggerSchema, Trigge
 var init_vault_config = __esm({
   "../db/src/vault-config.ts"() {
     "use strict";
-    ScopeSchema = z.strictObject({
-      repo: z.string().optional().describe(
+    ScopeSchema = z2.strictObject({
+      repo: z2.string().optional().describe(
         "Consumer repo path (~ expands). Load-bearing for kmd hook: the active scope resolves by matching the session cwd against it."
       ),
-      methodology: z.string().optional().describe("Must appear in the methodologies list."),
-      status: z.string().describe("Free string; keep within statuses by convention.")
+      methodology: z2.string().optional().describe("Must appear in the methodologies list."),
+      status: z2.string().describe("Free string; keep within statuses by convention.")
     });
-    KindEntrySchema = z.union([
-      z.string(),
-      z.strictObject({
-        name: z.string(),
-        signal: z.string().describe("When to pick this kind."),
-        where: z.string().describe("Path pattern pages of this kind follow.")
+    KindEntrySchema = z2.union([
+      z2.string(),
+      z2.strictObject({
+        name: z2.string(),
+        signal: z2.string().describe("When to pick this kind."),
+        where: z2.string().describe("Path pattern pages of this kind follow.")
       })
     ]);
-    WhenSchema = z.union([
-      z.string(),
-      z.strictObject({
-        name: z.enum(["newer-than"]),
-        fresh: z.array(z.string().min(1)).min(1),
-        than: z.array(z.string().min(1)).min(1)
+    WhenSchema = z2.union([
+      z2.string(),
+      z2.strictObject({
+        name: z2.enum(["newer-than"]),
+        fresh: z2.array(z2.string().min(1)).min(1),
+        than: z2.array(z2.string().min(1)).min(1)
       })
     ]);
-    DedupSchema = z.union([
-      z.enum(["session", "never"]),
-      z.strictObject({ minutes: z.number().int().positive() })
+    DedupSchema = z2.union([
+      z2.enum(["session", "never"]),
+      z2.strictObject({ minutes: z2.number().int().positive() })
     ]);
-    TriggerSchema = z.strictObject({
-      id: z.string().min(1).describe("Unique per scope list; duplicates keep the first occurrence."),
-      on: z.enum(["prompt", "pretool"]),
-      enforce: z.enum(["inject", "warn", "block"]).describe("inject: context line \xB7 warn: stderr \xB7 block: deny with reason."),
-      keywords: z.array(z.string().min(1)).optional().describe("Word-boundary, porter-stemmed match. Prompt triggers need keywords or intent."),
-      intent: z.array(z.string()).optional().describe("Case-insensitive regexes over the raw prompt \u2014 the stemming escape hatch."),
-      tool: z.string().optional().describe("Exact tool name; pretool matchers AND-compose."),
-      args_match: z.string().optional().describe("Regex over the serialized tool input."),
-      files: z.array(z.string().min(1)).optional().describe("Globs against the paths the tool touches; pretool triggers only."),
+    TriggerSchema = z2.strictObject({
+      id: z2.string().min(1).describe("Unique per scope list; duplicates keep the first occurrence."),
+      on: z2.enum(["prompt", "pretool"]),
+      enforce: z2.enum(["inject", "warn", "block"]).describe("inject: context line \xB7 warn: stderr \xB7 block: deny with reason."),
+      keywords: z2.array(z2.string().min(1)).optional().describe("Word-boundary, porter-stemmed match. Prompt triggers need keywords or intent."),
+      intent: z2.array(z2.string()).optional().describe("Case-insensitive regexes over the raw prompt \u2014 the stemming escape hatch."),
+      tool: z2.string().optional().describe("Exact tool name; pretool matchers AND-compose."),
+      args_match: z2.string().optional().describe("Regex over the serialized tool input."),
+      files: z2.array(z2.string().min(1)).optional().describe("Globs against the paths the tool touches; pretool triggers only."),
       when: WhenSchema.optional().describe(
         "Precondition \u2014 the gate fires only when it is UNMET. newer-than: the newest page matching fresh must carry frontmatter updated at or after the newest matching than."
       ),
-      text: z.string().optional().describe("Required for inject and warn \u2014 the line emitted."),
-      reason: z.string().optional().describe("Required for block \u2014 the denial the agent reads."),
+      text: z2.string().optional().describe("Required for inject and warn \u2014 the line emitted."),
+      reason: z2.string().optional().describe("Required for block \u2014 the denial the agent reads."),
       dedup: DedupSchema.optional().describe(
         "Re-fire policy: session (default, once per session), never, or {minutes: N} for at most once per bucket. Rejected on block triggers \u2014 blocks are dedup-exempt."
       )
@@ -240,36 +403,42 @@ var init_vault_config = __esm({
         }
       }
     });
-    TriggersSchema = z.record(z.string(), z.array(TriggerSchema));
-    BuiltinHooksSchema = z.strictObject({
-      resync: z.strictObject({
-        reason: z.string().min(1).optional().describe("Validate-errors preamble; the engine appends the error lines."),
-        text: z.string().min(1).optional().describe("Sync-failed note.")
+    TriggersSchema = z2.record(z2.string(), z2.array(TriggerSchema));
+    BuiltinHooksSchema = z2.strictObject({
+      resync: z2.strictObject({
+        reason: z2.string().min(1).optional().describe("Validate-errors preamble; the engine appends the error lines."),
+        text: z2.string().min(1).optional().describe("Sync-failed note.")
       }).optional(),
-      "handoff-gate": z.strictObject({
-        reason: z.string().min(1).optional().describe("Stop-block preamble; the engine appends the error lines.")
+      "handoff-gate": z2.strictObject({
+        reason: z2.string().min(1).optional().describe("Stop-block preamble; the engine appends the error lines.")
+      }).optional(),
+      orient: z2.strictObject({
+        text: z2.string().min(1).optional().describe("Session-start prime instruction; the engine prepends the resolved scope.")
+      }).optional(),
+      reorient: z2.strictObject({
+        text: z2.string().min(1).optional().describe("Post-compaction re-orientation; the engine prepends the resolved scope.")
       }).optional()
     });
-    VaultConfigSchema = z.strictObject({
-      scopes: z.record(z.string(), ScopeSchema).describe("Scope name \u2192 entry; key = directory name under projects/."),
-      kinds: z.array(KindEntrySchema).describe(
+    VaultConfigSchema = z2.strictObject({
+      scopes: z2.record(z2.string(), ScopeSchema).describe("Scope name \u2192 entry; key = directory name under projects/."),
+      kinds: z2.array(KindEntrySchema).describe(
         "Page kind vocabulary; validate-enforced. Object form adds a kind-selector row to wiki://authoring."
       ),
-      statuses: z.array(z.string()).describe("Page status vocabulary; validate-enforced."),
-      methodologies: z.array(z.string()).describe("Methodology vocabulary for pages and scope entries."),
-      tags: z.strictObject({
-        canonical: z.array(z.string()).describe("Approved tags."),
-        aliases: z.record(z.string(), z.string()).describe("Alias \u2192 canonical; validate warns on alias use.")
+      statuses: z2.array(z2.string()).describe("Page status vocabulary; validate-enforced."),
+      methodologies: z2.array(z2.string()).describe("Methodology vocabulary for pages and scope entries."),
+      tags: z2.strictObject({
+        canonical: z2.array(z2.string()).describe("Approved tags."),
+        aliases: z2.record(z2.string(), z2.string()).describe("Alias \u2192 canonical; validate warns on alias use.")
       }),
-      authoring_rules: z.string().optional().describe("Replaces the served \xA7 Authoring rules entirely \u2014 escape hatch."),
-      authoring_rules_extra: z.string().optional().describe("Appended after the served \xA7 Authoring rules."),
-      sync_protocol: z.string().optional().describe("Replaces the served \xA7 Resync protocol entirely \u2014 escape hatch."),
-      sync_protocol_extra: z.string().optional().describe("Appended after the served \xA7 Resync protocol."),
+      authoring_rules: z2.string().optional().describe("Replaces the served \xA7 Authoring rules entirely \u2014 escape hatch."),
+      authoring_rules_extra: z2.string().optional().describe("Appended after the served \xA7 Authoring rules."),
+      sync_protocol: z2.string().optional().describe("Replaces the served \xA7 Resync protocol entirely \u2014 escape hatch."),
+      sync_protocol_extra: z2.string().optional().describe("Appended after the served \xA7 Resync protocol."),
       triggers: TriggersSchema.optional().describe(
         'Full-replace of the trigger base per scope \u2014 escape hatch. "_all" is reserved for triggers_extra.'
       ),
       builtin_hooks: BuiltinHooksSchema.optional().describe(
-        "Message overrides for the fixed-function hooks (resync, handoff-gate) by public id."
+        "Message overrides for the fixed-function hooks (resync, handoff-gate, orient, reorient) by public id."
       ),
       triggers_extra: TriggersSchema.optional().describe(
         'Appended per scope after the engine defaults; the reserved "_all" key fires in every session.'
@@ -515,11 +684,12 @@ and must match current code at every commit.
 });
 
 // ../cli/src/init.ts
+import { existsSync as existsSync3 } from "node:fs";
 import { mkdir, readdir, readFile as readFile2, writeFile } from "node:fs/promises";
-import { join as join3, resolve as resolve2 } from "node:path";
+import { dirname as dirname3, join as join4, resolve as resolve3 } from "node:path";
 import { stringify } from "yaml";
 async function refreshSchemaFile(root) {
-  const path = join3(root, SCHEMA_FILE);
+  const path = join4(root, SCHEMA_FILE);
   const next = `${JSON.stringify(configJsonSchema(), null, 2)}
 `;
   try {
@@ -530,7 +700,7 @@ async function refreshSchemaFile(root) {
   return true;
 }
 async function scaffoldVault(dir) {
-  const root = resolve2(dir);
+  const root = resolve3(dir);
   let entries = [];
   try {
     entries = await readdir(root);
@@ -548,33 +718,97 @@ async function scaffoldVault(dir) {
     );
   }
   for (const domain of DOMAIN_DIRS) {
-    await mkdir(join3(root, domain), { recursive: true });
+    await mkdir(join4(root, domain), { recursive: true });
   }
-  await mkdir(join3(root, "templates"), { recursive: true });
+  await mkdir(join4(root, "templates"), { recursive: true });
   for (const [file, content] of Object.entries(VAULT_TEMPLATES)) {
-    await writeFile(join3(root, "templates", file), content);
+    await writeFile(join4(root, "templates", file), content);
   }
   await refreshSchemaFile(root);
-  await writeFile(join3(root, "vault.yaml"), SCHEMA_MODELINE + stringify(STARTER_CONFIG));
+  await writeFile(join4(root, "vault.yaml"), SCHEMA_MODELINE + stringify(STARTER_CONFIG));
   return root;
 }
-async function promptYesNo(question, input = process.stdin, output = process.stderr) {
+async function promptYesNo(question, input = process.stdin, output = process.stderr, defaultYes = false) {
   const { createInterface } = await import("node:readline/promises");
   const rl = createInterface({ input, output });
   try {
-    const answer = await rl.question(question);
-    return /^y(es)?$/i.test(answer.trim());
+    const answer = (await rl.question(question)).trim();
+    if (answer === "") return defaultYes;
+    return /^y(es)?$/i.test(answer);
   } finally {
     rl.close();
   }
 }
-async function runInit(dir, yes = false) {
+function findGitRoot(from) {
+  let level = resolve3(from);
+  for (; ; ) {
+    if (existsSync3(join4(level, ".git"))) return level;
+    const parent = dirname3(level);
+    if (parent === level) return null;
+    level = parent;
+  }
+}
+async function runInitLocal(yes) {
+  const root = findGitRoot(process.cwd()) ?? process.cwd();
+  const vaultTarget = join4(root, "vault");
+  const kmdDir = join4(root, ".kmd");
+  if (!yes) {
+    if (process.stdin.isTTY) {
+      const ok = await promptYesNo(
+        `initialize project vault at ${vaultTarget} (state in ${kmdDir})? [Y/n] `,
+        process.stdin,
+        process.stderr,
+        true
+      );
+      if (!ok) {
+        console.error("init: aborted");
+        process.exit(1);
+      }
+    } else {
+      console.error("usage: kmd init --local -y  (piped stdin cannot confirm the target)");
+      process.exit(2);
+    }
+  }
+  let vaultRoot;
+  try {
+    vaultRoot = await scaffoldVault(vaultTarget);
+  } catch (err) {
+    console.error(`init: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+  await mkdir(kmdDir, { recursive: true });
+  const gitignore = join4(kmdDir, ".gitignore");
+  if (!existsSync3(gitignore)) await writeFile(gitignore, TIER_GITIGNORE);
+  console.log(`initialized project vault at ${vaultRoot}
+
+  ${kmdDir}/            state home \u2014 index and hook state live with the repo
+  ${kmdDir}/.gitignore  db/, state/, config.local.yaml stay untracked
+
+every kmd command run inside ${root} now resolves this vault (project tier).
+next steps:
+  kmd sync    # builds the index at .kmd/db/index.db`);
+}
+async function runInit(dir, yes = false, local = false, setDefaultFlag = false) {
+  if (local) {
+    if (dir !== void 0) {
+      console.error("usage: kmd init --local  (the root is the nearest .git ancestor, not chosen)");
+      process.exit(2);
+    }
+    if (setDefaultFlag) {
+      console.error(
+        "kmd init: --set-default applies to global init only (a project vault resolves by location)"
+      );
+      process.exit(2);
+    }
+    await runInitLocal(yes);
+    return;
+  }
   let target = dir;
   if (!target) {
     if (yes) {
       target = ".";
     } else if (process.stdin.isTTY) {
-      const ok = await promptYesNo(`initialize a vault in ${resolve2(".")}? [y/N] `);
+      const ok = await promptYesNo(`initialize a vault in ${resolve3(".")}? [y/N] `);
       if (!ok) {
         console.error("init: aborted");
         process.exit(1);
@@ -598,16 +832,34 @@ async function runInit(dir, yes = false) {
   vault.yaml           starter vocabulary \u2014 add your first scope under scopes:
   vault.schema.json    IDE validation via the yaml-language-server modeline
   templates/           ${templateCount} built-in templates (served at wiki://template/...)
-  projects/  research/  notes/
-
+  projects/  research/  notes/`);
+  let setDefault = setDefaultFlag;
+  if (!setDefault && !yes && process.stdin.isTTY) {
+    setDefault = await promptYesNo(
+      `set as default vault in ~/.kmd/config.yaml? [Y/n] `,
+      process.stdin,
+      process.stderr,
+      true
+    );
+  }
+  if (setDefault) {
+    setGlobalConfigValue("default_vault", root);
+    console.log(`
+default_vault: ${root}
 next steps:
-  export WIKI_VAULT=${root}
+  kmd mcp    # stdio MCP server (prime, search) \u2014 resolves the default`);
+  } else {
+    console.log(`
+next steps:
+  kmd config set default_vault ${root}    # make it the machine default
   kmd mcp ${root}    # stdio MCP server (prime, search)`);
+  }
 }
-var SCHEMA_FILE, SCHEMA_MODELINE, STARTER_CONFIG, DOMAIN_DIRS;
+var SCHEMA_FILE, SCHEMA_MODELINE, STARTER_CONFIG, DOMAIN_DIRS, TIER_GITIGNORE;
 var init_init = __esm({
   "../cli/src/init.ts"() {
     "use strict";
+    init_kmd_config();
     init_vault_config();
     init_init_templates();
     SCHEMA_FILE = "vault.schema.json";
@@ -621,15 +873,16 @@ var init_init = __esm({
       tags: { canonical: [], aliases: {} }
     };
     DOMAIN_DIRS = ["projects", "research", "notes"];
+    TIER_GITIGNORE = "db/\nstate/\nconfig.local.yaml\n";
   }
 });
 
 // ../cli/src/sync.ts
 import { createHash as createHash2 } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { mkdirSync as mkdirSync2 } from "node:fs";
 import { readdir as readdir2, readFile as readFile3 } from "node:fs/promises";
-import { dirname, join as join4, relative, sep } from "node:path";
-import { z as z2 } from "zod";
+import { dirname as dirname4, join as join5, relative, sep } from "node:path";
+import { z as z3 } from "zod";
 function loadEnv() {
   const parsed = EnvSchema.safeParse({
     WIKI_VAULT: process.env.WIKI_VAULT
@@ -649,13 +902,13 @@ async function walkMarkdown(root, domain) {
     for (const entry of entries) {
       if (entry.name.startsWith(".")) continue;
       if (entry.isDirectory()) {
-        await recurse(join4(dir, entry.name));
+        await recurse(join5(dir, entry.name));
       } else if (entry.isFile() && entry.name.endsWith(".md")) {
-        out.push(join4(dir, entry.name));
+        out.push(join5(dir, entry.name));
       }
     }
   }
-  await recurse(join4(root, domain));
+  await recurse(join5(root, domain));
   return out;
 }
 function toRelativePath(root, absolute) {
@@ -777,23 +1030,23 @@ function syncPage(db, fields) {
   }
   return "changed";
 }
-async function syncVault(vaultRoot2) {
-  const dbPath = resolveIndexPath(vaultRoot2);
-  const vaultConfig = await loadVaultConfig(vaultRoot2);
+async function syncVault(vaultRoot) {
+  const dbPath = resolveIndexPath(vaultRoot);
+  const vaultConfig = await loadVaultConfig(vaultRoot);
   const scopes = new Set(Object.keys(vaultConfig.scopes));
-  mkdirSync(dirname(dbPath), { recursive: true });
+  mkdirSync2(dirname4(dbPath), { recursive: true });
   const db = openDatabase(dbPath);
   try {
     const files = [];
     for (const domain of SCAN_DOMAINS) {
-      files.push(...await walkMarkdown(vaultRoot2, domain));
+      files.push(...await walkMarkdown(vaultRoot, domain));
     }
     const indexedPaths = [];
     let changed = 0;
     let unchanged = 0;
     let skipped = 0;
     for (const file of files) {
-      const path = toRelativePath(vaultRoot2, file);
+      const path = toRelativePath(vaultRoot, file);
       const raw = await readFile3(file, "utf8");
       const parsed = parseFrontmatter(raw);
       const fields = buildPageFields(path, raw, parsed, scopes);
@@ -815,9 +1068,9 @@ async function syncVault(vaultRoot2) {
     const linkResult = db.prepare("DELETE FROM links WHERE source_path NOT IN (SELECT path FROM pages)").run();
     const linksDeleted = Number(linkResult.changes);
     db.exec("INSERT INTO pages_fts(pages_fts) VALUES('rebuild')");
-    setMeta(db, "vault_root", canonicalVaultRoot(vaultRoot2));
+    setMeta(db, "vault_root", canonicalVaultRoot(vaultRoot));
     setMeta(db, "last_synced", (/* @__PURE__ */ new Date()).toISOString());
-    if (await refreshSchemaFile(vaultRoot2)) {
+    if (await refreshSchemaFile(vaultRoot)) {
       console.error("sync: vault.schema.json refreshed to the running engine");
     }
     return {
@@ -851,8 +1104,8 @@ var init_sync = __esm({
     init_vault_config();
     init_frontmatter();
     init_init();
-    EnvSchema = z2.object({
-      WIKI_VAULT: z2.string().min(1)
+    EnvSchema = z3.object({
+      WIKI_VAULT: z3.string().min(1)
     });
     SCAN_DOMAINS = ["projects", "research", "notes"];
     WIKILINK_RE = /\[\[([^\]|#^]+)(?:[#^][^\]|]*)?(?:\|([^\]]+))?\]\]/g;
@@ -871,7 +1124,7 @@ var init_sync = __esm({
 
 // ../cli/src/validate.ts
 import { readFile as readFile4, stat } from "node:fs/promises";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 function hasIndexableTitle(data) {
   return typeof data.title === "string" && data.title.trim() !== "";
 }
@@ -1243,7 +1496,7 @@ async function validateVault(root) {
   for (const name of customKindNames(cfg)) {
     const file = `templates/${name}.md`;
     try {
-      await stat(join5(root, file));
+      await stat(join6(root, file));
     } catch {
       findings.push({
         path: file,
@@ -1315,15 +1568,18 @@ var cli_exports = {};
 __export(cli_exports, {
   main: () => main,
   resolveCli: () => resolveCli,
+  resolveCliVault: () => resolveCliVault,
   runConfig: () => runConfig,
+  runConfigGet: () => runConfigGet,
+  runConfigSet: () => runConfigSet,
+  runConfigUnset: () => runConfigUnset,
   runDbReset: () => runDbReset,
   runInit: () => runInit,
   runSyncCommand: () => runSyncCommand,
-  runValidate: () => runValidate,
-  vaultRoot: () => vaultRoot
+  runValidate: () => runValidate
 });
-import { existsSync, readdirSync, rmSync } from "node:fs";
-import { dirname as dirname2, join as join6 } from "node:path";
+import { existsSync as existsSync4, readdirSync, rmSync } from "node:fs";
+import { dirname as dirname5, join as join7, resolve as resolve4 } from "node:path";
 import { parseArgs } from "node:util";
 function resolveCli(argv) {
   const { positionals: positionals2 } = parseArgs({ args: argv, allowPositionals: true, strict: false });
@@ -1339,27 +1595,42 @@ function resolveCli(argv) {
   }
   return { kind: "error", message: `unknown command: ${command2}` };
 }
-function vaultRoot() {
-  const root = process.env.WIKI_VAULT;
-  if (!root) {
-    console.error("WIKI_VAULT is not set");
+function resolveCliVault(positional, defaultRoot) {
+  return resolveVaultRoot({
+    positional,
+    defaultRoot,
+    projectDir: process.env.KMD_PROJECT_DIR ?? process.cwd(),
+    envVault: process.env.WIKI_VAULT,
+    globalDefault: loadGlobalConfig().default_vault,
+    onSkip: (candidate) => console.error(
+      `kmd: ignoring ${candidate} \u2014 no .kmd marker beside it; mkdir ${dirname5(candidate)}/.kmd to bind it as the project vault`
+    )
+  });
+}
+function requireCliVault(positional) {
+  const resolution = resolveCliVault(positional);
+  if (resolution.root === null) {
+    console.error(NO_VAULT_HINT);
     process.exit(1);
   }
-  return root;
+  process.env.WIKI_VAULT = resolution.root;
+  return { root: resolution.root, resolution };
 }
 function reportFindings(findings) {
   for (const f of findings) {
     console.error(`${f.severity}: ${f.path} [${f.rule}] ${f.message}`);
   }
 }
-async function runValidate() {
-  const findings = await validateVault(vaultRoot());
+async function runValidate(positional) {
+  const { root } = requireCliVault(positional);
+  const findings = await validateVault(root);
   reportFindings(findings);
   console.log(`validate: ${findings.length} finding(s)`);
   process.exit(hasErrors(findings) ? 1 : 0);
 }
-async function runSyncCommand() {
-  const findings = await validateVault(vaultRoot());
+async function runSyncCommand(positional) {
+  const { root } = requireCliVault(positional);
+  const findings = await validateVault(root);
   reportFindings(findings);
   if (hasErrors(findings)) {
     const errors = findings.filter((f) => f.severity === "error").length;
@@ -1372,7 +1643,7 @@ function describeVault(root) {
   const vault = canonicalVaultRoot(root);
   const index = resolveIndexPath(vault);
   let synced = "never";
-  if (existsSync(index)) {
+  if (existsSync4(index)) {
     const db = openDatabase(index);
     try {
       synced = getMeta(db, "last_synced") ?? "never";
@@ -1389,12 +1660,12 @@ function printVault(d) {
 }
 function knownVaults() {
   const root = indexRootDir();
-  if (!existsSync(root)) return [];
+  if (!existsSync4(root)) return [];
   const known = [];
   for (const entry of readdirSync(root, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
-    const index = join6(root, entry.name, "index.db");
-    if (!existsSync(index)) continue;
+    const index = join7(root, entry.name, "index.db");
+    if (!existsSync4(index)) continue;
     const db = openDatabase(index);
     try {
       const vault = getMeta(db, "vault_root");
@@ -1406,17 +1677,16 @@ function knownVaults() {
   }
   return known;
 }
-async function runConfig() {
-  const root = process.env.WIKI_VAULT;
-  if (root) {
-    printVault(describeVault(root));
+async function runConfig(positional) {
+  const resolution = resolveCliVault(positional);
+  if (resolution.root !== null) {
+    printVault(describeVault(resolution.root));
+    console.log(`source: ${SOURCE_LABELS[resolution.source]}`);
     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"
-    );
+    console.error(NO_VAULT_HINT);
     process.exit(1);
   }
   known.forEach((d, i) => {
@@ -1424,14 +1694,44 @@ async function runConfig() {
     printVault(d);
   });
 }
-async function runDbReset() {
-  const root = process.env.WIKI_VAULT;
-  if (!root) {
+async function runConfigSet(key, value) {
+  if (key !== "default_vault" || !value) {
+    console.error("usage: kmd config set default_vault <path>");
+    process.exit(2);
+  }
+  const vault = resolve4(value);
+  await loadVaultConfig(vault);
+  setGlobalConfigValue("default_vault", vault);
+  console.log(`default_vault: ${vault}`);
+}
+async function runConfigGet(key) {
+  if (key !== "default_vault") {
+    console.error("usage: kmd config get default_vault");
+    process.exit(2);
+  }
+  const value = loadGlobalConfig().default_vault;
+  if (value === void 0) process.exit(1);
+  console.log(value);
+}
+async function runConfigUnset(key) {
+  if (key !== "default_vault") {
+    console.error("usage: kmd config unset default_vault");
+    process.exit(2);
+  }
+  if (!unsetGlobalConfigValue("default_vault")) {
+    console.error("default_vault is not set");
+    process.exit(1);
+  }
+  console.log("default_vault unset");
+}
+async function runDbReset(positional) {
+  const resolution = resolveCliVault(positional);
+  if (resolution.root === null) {
     console.error("usage: kmd db reset [<vault-root>] (or set WIKI_VAULT)");
     process.exit(2);
   }
-  const dir = dirname2(resolveIndexPath(root));
-  if (!existsSync(dir)) {
+  const dir = dirname5(resolveIndexPath(resolution.root));
+  if (!existsSync4(dir)) {
     console.log(`${dir} does not exist \u2014 nothing to reset`);
     return;
   }
@@ -1450,53 +1750,126 @@ async function main() {
     await runValidate();
   }
 }
+var SOURCE_LABELS, NO_VAULT_HINT;
 var init_cli = __esm({
   "../cli/src/cli.ts"() {
     "use strict";
     init_database();
+    init_kmd_config();
+    init_vault_config();
     init_sync();
     init_validate();
     init_init();
+    SOURCE_LABELS = {
+      positional: "positional",
+      "project-local-config": "project tier (local config)",
+      "project-config": "project tier (config)",
+      "project-convention": "project tier (convention)",
+      "default-root": "--default-root",
+      env: "$WIKI_VAULT",
+      "global-config": "global config (default_vault)",
+      none: "none"
+    };
+    NO_VAULT_HINT = "no vault resolvable \u2014 pass a vault root, run inside a project vault, set WIKI_VAULT, or `kmd config set default_vault <path>`";
+  }
+});
+
+// ../mcp/src/binding.ts
+import { fileURLToPath } from "node:url";
+function projectDirsFromRoots(roots) {
+  const dirs = [];
+  for (const root of roots) {
+    if (!root.uri.startsWith("file://")) continue;
+    try {
+      dirs.push(fileURLToPath(root.uri));
+    } catch {
+    }
+  }
+  return dirs;
+}
+function resolveDeferredVault(input) {
+  const env = input.env ?? process.env;
+  if (input.rootDirs === null) {
+    return resolveVaultRoot({
+      projectDir: input.cwd,
+      defaultRoot: input.defaultRoot,
+      envVault: input.envVault,
+      globalDefault: input.globalDefault,
+      env,
+      onSkip: input.onSkip
+    });
+  }
+  for (const dir of input.rootDirs) {
+    const tier = findProjectTier(dir, env, input.onSkip);
+    if (tier !== null) {
+      return { root: tier.vaultRoot, source: `project-${tier.via}`, tierRoot: tier.tierRoot };
+    }
+  }
+  return resolveVaultRoot({
+    defaultRoot: input.defaultRoot,
+    envVault: input.envVault,
+    globalDefault: input.globalDefault,
+    env
+  });
+}
+var init_binding = __esm({
+  "../mcp/src/binding.ts"() {
+    "use strict";
+    init_kmd_config();
   }
 });
 
 // ../mcp/src/config.ts
-import { z as z3 } from "zod";
-function loadConfig(env = process.env) {
-  const parsed = EnvSchema2.safeParse(env);
+import { z as z4 } from "zod";
+function parseEnv(schema, env) {
+  const parsed = schema.safeParse(env);
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
     throw new Error(`Invalid environment configuration:
 ${issues}`);
   }
+  return parsed.data;
+}
+function loadConfig(env = process.env) {
+  const data = parseEnv(EnvSchema2, env);
+  return {
+    wikiVault: data.WIKI_VAULT,
+    logLevel: data.LOG_LEVEL,
+    serverName: data.SERVER_NAME,
+    serverVersion: data.SERVER_VERSION
+  };
+}
+function loadServerEnv(env = process.env) {
+  const data = parseEnv(BaseEnvSchema, env);
   return {
-    wikiVault: parsed.data.WIKI_VAULT,
-    logLevel: parsed.data.LOG_LEVEL,
-    serverName: parsed.data.SERVER_NAME,
-    serverVersion: parsed.data.SERVER_VERSION
+    logLevel: data.LOG_LEVEL,
+    serverName: data.SERVER_NAME,
+    serverVersion: data.SERVER_VERSION
   };
 }
-var EnvSchema2;
+var BaseEnvSchema, EnvSchema2;
 var init_config = __esm({
   "../mcp/src/config.ts"() {
     "use strict";
-    EnvSchema2 = z3.object({
-      WIKI_VAULT: z3.string().min(1).describe("Absolute path to the Obsidian vault root"),
-      LOG_LEVEL: z3.enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"]).default("info").describe("Pino log level. Logs go to stderr to keep the stdio JSON-RPC stream clean."),
-      SERVER_NAME: z3.string().default("wiki-mcp"),
-      SERVER_VERSION: z3.string().default("0.0.0")
+    BaseEnvSchema = z4.object({
+      LOG_LEVEL: z4.enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"]).default("info").describe("Pino log level. Logs go to stderr to keep the stdio JSON-RPC stream clean."),
+      SERVER_NAME: z4.string().default("wiki-mcp"),
+      SERVER_VERSION: z4.string().default("0.0.0")
+    });
+    EnvSchema2 = BaseEnvSchema.extend({
+      WIKI_VAULT: z4.string().min(1).describe("Absolute path to the Obsidian vault root")
     });
   }
 });
 
 // ../mcp/src/db.ts
-import { mkdirSync as mkdirSync2 } from "node:fs";
-import { dirname as dirname3 } from "node:path";
-function createDatabase(vaultRoot2) {
-  const dbPath = resolveIndexPath(vaultRoot2);
-  mkdirSync2(dirname3(dbPath), { recursive: true });
+import { mkdirSync as mkdirSync3 } from "node:fs";
+import { dirname as dirname6 } from "node:path";
+function createDatabase(vaultRoot) {
+  const dbPath = resolveIndexPath(vaultRoot);
+  mkdirSync3(dirname6(dbPath), { recursive: true });
   const db = openDatabase(dbPath);
-  setMeta(db, "vault_root", canonicalVaultRoot(vaultRoot2));
+  setMeta(db, "vault_root", canonicalVaultRoot(vaultRoot));
   return db;
 }
 var init_db = __esm({
@@ -1507,9 +1880,9 @@ var init_db = __esm({
 });
 
 // ../mcp/src/lib/diag.ts
-import { appendFileSync, mkdirSync as mkdirSync3 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { join as join7 } from "node:path";
+import { appendFileSync, mkdirSync as mkdirSync4 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join8 } from "node:path";
 function diag(msg, data) {
   try {
     const line = data ? `${(/* @__PURE__ */ new Date()).toISOString()} pid=${process.pid} ${msg} ${JSON.stringify(data)}
@@ -1523,10 +1896,10 @@ var DIAG_DIR, DIAG_LOG_PATH;
 var init_diag = __esm({
   "../mcp/src/lib/diag.ts"() {
     "use strict";
-    DIAG_DIR = join7(homedir2(), ".local", "state", "wiki-mcp");
-    DIAG_LOG_PATH = join7(DIAG_DIR, "server.log");
+    DIAG_DIR = join8(homedir3(), ".local", "state", "wiki-mcp");
+    DIAG_LOG_PATH = join8(DIAG_DIR, "server.log");
     try {
-      mkdirSync3(DIAG_DIR, { recursive: true });
+      mkdirSync4(DIAG_DIR, { recursive: true });
     } catch {
     }
   }
@@ -1605,7 +1978,7 @@ function buildVocabulary(config) {
   }
   return lines.join("\n");
 }
-function registerAuthoringResource(mcp, vaultRoot2, vaultConfig) {
+function registerAuthoringResource(mcp, binding) {
   mcp.registerResource(
     "Authoring guide",
     "wiki://authoring",
@@ -1614,10 +1987,11 @@ function registerAuthoringResource(mcp, vaultRoot2, vaultConfig) {
       mimeType: "text/markdown"
     },
     async (uri) => {
+      const { vaultRoot, vaultConfig } = await binding;
       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.`,
+        `Vault root: \`${canonicalVaultRoot(vaultRoot)}\` \u2014 every page path below is relative to it; write files and run \`kmd validate\` / \`kmd sync\` against it.`,
         "",
         buildKindSelector(vaultConfig.kinds),
         "",
@@ -1766,7 +2140,7 @@ var init_authoring = __esm({
 
 // ../mcp/src/resources/templates.ts
 import { readFile as readFile5 } from "node:fs/promises";
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 function customTemplates(config) {
   const specs = [];
   for (const entry of config.kinds) {
@@ -1780,41 +2154,52 @@ function customTemplates(config) {
   }
   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) => {
-        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: [
-            {
-              uri: uri.toString(),
-              mimeType: "text/markdown",
-              text
-            }
-          ]
-        };
+function registerTemplate(mcp, tmpl, binding) {
+  mcp.registerResource(
+    tmpl.name,
+    tmpl.uri,
+    { description: tmpl.description, mimeType: "text/markdown" },
+    async (uri) => {
+      const { vaultRoot } = await binding;
+      let text;
+      try {
+        text = await readFile5(join9(vaultRoot, "templates", tmpl.file), "utf8");
+      } catch (err) {
+        throw new Error(`template file missing: templates/${tmpl.file} (${tmpl.uri})`, {
+          cause: err
+        });
       }
-    );
-  }
+      return {
+        contents: [
+          {
+            uri: uri.toString(),
+            mimeType: "text/markdown",
+            text
+          }
+        ]
+      };
+    }
+  );
+}
+function buildIndexText(vaultConfig) {
   const indexLines = ["# Wiki Templates", ""];
-  for (const tmpl of templates) {
+  for (const tmpl of [...TEMPLATES, ...customTemplates(vaultConfig)]) {
     indexLines.push(`- **${tmpl.name}** \u2014 \`${tmpl.uri}\`  `);
     indexLines.push(`  ${tmpl.description}`);
   }
-  const indexText = indexLines.join("\n");
+  return indexLines.join("\n");
+}
+function registerTemplateResources(mcp, binding) {
+  for (const tmpl of TEMPLATES) {
+    registerTemplate(mcp, tmpl, binding);
+  }
+  const registerCustom = (bound) => {
+    for (const tmpl of customTemplates(bound.vaultConfig)) {
+      registerTemplate(mcp, tmpl, binding);
+    }
+  };
+  if (binding instanceof Promise) void binding.then(registerCustom);
+  else registerCustom(binding);
   mcp.registerResource(
     "Template index",
     "wiki://templates",
@@ -1822,9 +2207,18 @@ function registerTemplateResources(mcp, vaultRoot2, vaultConfig) {
       description: "Index of all wiki templates with URIs and descriptions. Read a specific template via its URI.",
       mimeType: "text/markdown"
     },
-    async (uri) => ({
-      contents: [{ uri: uri.toString(), mimeType: "text/markdown", text: indexText }]
-    })
+    async (uri) => {
+      const { vaultConfig } = await binding;
+      return {
+        contents: [
+          {
+            uri: uri.toString(),
+            mimeType: "text/markdown",
+            text: buildIndexText(vaultConfig)
+          }
+        ]
+      };
+    }
   );
 }
 var TEMPLATES;
@@ -1971,7 +2365,7 @@ var init_toolResponse = __esm({
 });
 
 // ../mcp/src/tools/search.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 function search(deps, input) {
   const ftsQuery = sanitizeFtsQuery(input.query);
   if (!ftsQuery) return { results: [] };
@@ -2018,15 +2412,15 @@ var init_search = __esm({
     "use strict";
     init_fts();
     init_toolResponse();
-    SearchInputSchema = z4.object({
-      query: z4.string().min(1).describe(
+    SearchInputSchema = z5.object({
+      query: z5.string().min(1).describe(
         "Natural-language search query. Matched against title, summary, and body via SQLite FTS5."
       ),
-      scope: z4.string().optional().describe('Optional: restrict to a project scope (e.g. "ontology", "sotto").'),
-      kind: z4.string().optional().describe(
+      scope: z5.string().optional().describe('Optional: restrict to a project scope (e.g. "ontology", "sotto").'),
+      kind: z5.string().optional().describe(
         "Optional: restrict to a kind. Project kinds: spec, adr, plan, ops. Research kinds: article, src. Misc: note."
       ),
-      limit: z4.number().int().min(1).max(50).default(5).describe("Maximum number of ranked results to return. Default 5.")
+      limit: z5.number().int().min(1).max(50).default(5).describe("Maximum number of ranked results to return. Default 5.")
     });
     FTS_RANK = "bm25(pages_fts, 10.0, 5.0, 1.0)";
   }
@@ -2034,33 +2428,33 @@ var init_search = __esm({
 
 // ../mcp/src/tools/prime.ts
 import { readFile as readFile6 } from "node:fs/promises";
-import { basename as basename3, join as join9 } from "node:path";
-import { z as z5 } from "zod";
+import { basename as basename3, join as join10 } from "node:path";
+import { z as z6 } from "zod";
 function pathSlug(p) {
   return basename3(p).replace(/\.md$/, "");
 }
-async function readIndexFm(vaultRoot2, scope) {
+async function readIndexFm(vaultRoot, scope) {
   try {
-    const raw = await readFile6(join9(vaultRoot2, "projects", scope, "index.md"), "utf8");
+    const raw = await readFile6(join10(vaultRoot, "projects", scope, "index.md"), "utf8");
     return parseFrontmatter2(raw).data;
   } catch {
     return {};
   }
 }
-async function readPrimer(vaultRoot2, scope) {
+async function readPrimer(vaultRoot, scope) {
   try {
-    const raw = await readFile6(join9(vaultRoot2, "projects", scope, "primer.md"), "utf8");
+    const raw = await readFile6(join10(vaultRoot, "projects", scope, "primer.md"), "utf8");
     return parseFrontmatter2(raw).content.trim().replace(/^#\s+[^\n]+\n+/, "");
   } catch {
     return "";
   }
 }
 async function prime(deps, input) {
-  const { db, vaultRoot: vaultRoot2, vaultConfig } = deps;
+  const { db, vaultRoot, vaultConfig } = deps;
   const { scope, task } = input;
   const [fm, primer] = await Promise.all([
-    readIndexFm(vaultRoot2, scope),
-    readPrimer(vaultRoot2, scope)
+    readIndexFm(vaultRoot, scope),
+    readPrimer(vaultRoot, scope)
   ]);
   const counts = db.prepare("SELECT kind, count(*) AS count FROM pages WHERE scope = ? GROUP BY kind").all(scope);
   const adrs = db.prepare(
@@ -2114,7 +2508,7 @@ async function prime(deps, input) {
   for (const row of counts) countsRecord[row.kind] = Number(row.count);
   const data = {
     scope,
-    vault_root: canonicalVaultRoot(vaultRoot2),
+    vault_root: canonicalVaultRoot(vaultRoot),
     title: fm.title ?? null,
     methodology: fm.methodology ?? null,
     phase: typeof fm.phase === "number" ? fm.phase : null,
@@ -2244,9 +2638,9 @@ var init_prime = __esm({
     init_fts();
     init_toolResponse();
     init_search();
-    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.")
+    PrimeInputSchema = z6.object({
+      scope: z6.string().min(1).describe("Project scope to prime (matches projects/{scope}/ in the vault)."),
+      task: z6.string().optional().describe("Optional task description; surfaces top-3 tsvector-ranked relevant pages.")
     });
   }
 });
@@ -2254,15 +2648,20 @@ var init_prime = __esm({
 // ../mcp/src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 function buildServer(args) {
-  const { name, version, vaultRoot: vaultRoot2, db, logger, vaultConfig } = args;
-  const mcp = new McpServer({ name, version }, { capabilities: { tools: {}, resources: {} } });
+  const { name, version, logger, binding } = args;
+  const deferred = binding instanceof Promise;
+  const mcp = new McpServer(
+    { name, version },
+    { capabilities: { tools: {}, resources: deferred ? { listChanged: true } : {} } }
+  );
   mcp.tool(
     "prime",
     "Orient on a project. Returns a markdown briefing with: identity (scope, phase, methodology, summary), the human-authored primer.md inlined, active ADRs, current plan, page counts, top tags, hub pages (most-linked-to), recent events, cross-scope references, and \u2014 when `task` is provided \u2014 the top 3 tsvector-ranked relevant pages. Call once at session start. Empty sections are omitted to keep the surface lean.",
     PrimeInputSchema.shape,
     async (input) => {
       logger.debug({ tool: "prime", input }, "tool call");
-      return handlePrime({ db, vaultRoot: vaultRoot2, vaultConfig }, input);
+      const { db, vaultRoot, vaultConfig } = await binding;
+      return handlePrime({ db, vaultRoot, vaultConfig }, input);
     }
   );
   mcp.tool(
@@ -2271,11 +2670,12 @@ function buildServer(args) {
     SearchInputSchema.shape,
     async (input) => {
       logger.debug({ tool: "search", input }, "tool call");
+      const { db } = await binding;
       return handleSearch({ db }, input);
     }
   );
-  registerTemplateResources(mcp, vaultRoot2, vaultConfig);
-  registerAuthoringResource(mcp, vaultRoot2, vaultConfig);
+  registerTemplateResources(mcp, binding);
+  registerAuthoringResource(mcp, binding);
   return mcp;
 }
 var init_server = __esm({
@@ -2294,8 +2694,25 @@ __export(start_exports, {
   startMcpServer: () => startMcpServer
 });
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-async function startMcpServer() {
+import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+function installShutdown(mcp, logger, getDb) {
+  const shutdown = async (signal) => {
+    logger.info({ signal }, "shutting down");
+    diag("shutting down", { signal });
+    try {
+      await mcp.close();
+      getDb()?.close();
+    } catch (err) {
+      logger.error({ err }, "error during shutdown");
+    }
+    process.exit(0);
+  };
+  process.once("SIGINT", (s) => void shutdown(s));
+  process.once("SIGTERM", (s) => void shutdown(s));
+}
+async function startMcpServer(deferred) {
   diag("main entered");
+  if (deferred) return startDeferred(deferred);
   const config = loadConfig();
   diag("config loaded", { vault: config.wikiVault, level: config.logLevel });
   const vaultConfig = await loadVaultConfig(config.wikiVault);
@@ -2314,34 +2731,89 @@ async function startMcpServer() {
   const mcp = buildServer({
     name: config.serverName,
     version: config.serverVersion,
-    vaultRoot: config.wikiVault,
-    db,
     logger,
-    vaultConfig
+    binding: { vaultRoot: config.wikiVault, db, vaultConfig }
   });
   diag("server built");
-  const shutdown = async (signal) => {
-    logger.info({ signal }, "shutting down");
-    diag("shutting down", { signal });
-    try {
-      await mcp.close();
-      db.close();
-    } catch (err) {
-      logger.error({ err }, "error during shutdown");
-    }
-    process.exit(0);
-  };
-  process.once("SIGINT", (s) => void shutdown(s));
-  process.once("SIGTERM", (s) => void shutdown(s));
+  installShutdown(mcp, logger, () => db);
   const transport = new StdioServerTransport();
   await mcp.connect(transport);
   logger.info("wiki-mcp ready");
   diag("ready and connected to transport");
 }
+async function startDeferred(input) {
+  const env = loadServerEnv();
+  diag("config loaded, vault binding deferred", { level: env.logLevel, cwd: input.cwd });
+  const logger = createLogger(env.logLevel, env.serverName);
+  logger.info(
+    { serverName: env.serverName, serverVersion: env.serverVersion },
+    "starting wiki-mcp on stdio; vault binding deferred to after initialization"
+  );
+  let resolveBinding;
+  const binding = new Promise((resolve6) => {
+    resolveBinding = resolve6;
+  });
+  const mcp = buildServer({
+    name: env.serverName,
+    version: env.serverVersion,
+    logger,
+    binding
+  });
+  diag("server built (deferred binding)");
+  let bound = null;
+  const bind = async () => {
+    let rootDirs = null;
+    if (mcp.server.getClientCapabilities()?.roots) {
+      const { roots } = await mcp.server.listRoots();
+      rootDirs = projectDirsFromRoots(roots);
+      diag("client roots received", { uris: roots.map((r) => r.uri), dirs: rootDirs });
+    } else {
+      diag("client declares no roots capability; falling back to the cwd-fed chain");
+    }
+    const resolution = resolveDeferredVault({
+      rootDirs,
+      cwd: input.cwd,
+      defaultRoot: input.defaultRoot,
+      envVault: input.envVault,
+      globalDefault: input.globalDefault,
+      onSkip: (candidate) => logger.warn({ candidate }, "ignoring unmarked vault.yaml \u2014 no .kmd sibling")
+    });
+    if (resolution.root === null) {
+      throw new Error(
+        "no vault resolvable \u2014 no client root maps to a vault; pass <vault-root>, set KMD_PROJECT_DIR or WIKI_VAULT, use --default-root, or `kmd config set default_vault <path>`"
+      );
+    }
+    process.env.WIKI_VAULT = resolution.root;
+    const vaultConfig = await loadVaultConfig(resolution.root);
+    const db = createDatabase(resolution.root);
+    bound = { vaultRoot: resolution.root, db, vaultConfig };
+    diag("vault bound", { vault: resolution.root, source: resolution.source });
+    logger.info({ vault: resolution.root, source: resolution.source }, "vault bound");
+    resolveBinding(bound);
+  };
+  mcp.server.oninitialized = () => {
+    void bind().catch((err) => {
+      const msg = err instanceof Error ? err.stack ?? err.message : String(err);
+      diag("FATAL at vault bind", { err: msg });
+      process.stderr.write(`fatal: vault bind failed: ${msg}
+`);
+      process.exit(1);
+    });
+  };
+  mcp.server.setNotificationHandler(RootsListChangedNotificationSchema, () => {
+    logger.debug("roots/list_changed received; rebinding declined \u2014 vault binds once per server");
+  });
+  installShutdown(mcp, logger, () => bound?.db ?? null);
+  const transport = new StdioServerTransport();
+  await mcp.connect(transport);
+  logger.info("wiki-mcp ready; awaiting initialization to bind the vault");
+  diag("ready and connected to transport; vault binds after initialize");
+}
 var init_start = __esm({
   "../mcp/src/start.ts"() {
     "use strict";
     init_vault_config();
+    init_binding();
     init_config();
     init_db();
     init_diag();
@@ -2366,25 +2838,28 @@ __export(hook_exports, {
   matchPromptTriggers: () => matchPromptTriggers,
   parsePretoolEvent: () => parsePretoolEvent,
   parsePromptEvent: () => parsePromptEvent,
+  parseSessionStartEvent: () => parseSessionStartEvent,
   parseStopEvent: () => parseStopEvent,
   renderPosttool: () => renderPosttool,
   renderPretool: () => renderPretool,
   renderPrompt: () => renderPrompt,
+  renderSessionStart: () => renderSessionStart,
   renderStop: () => renderStop,
   resolveScope: () => resolveScope,
   runHookPosttool: () => runHookPosttool,
   runHookPretool: () => runHookPretool,
   runHookPrompt: () => runHookPrompt,
+  runHookSessionStart: () => runHookSessionStart,
   runHookStop: () => runHookStop,
   vaultPathTouched: () => vaultPathTouched
 });
-import { mkdirSync as mkdirSync4, readdirSync as readdirSync2, readFileSync, rmSync as rmSync2, statSync, writeFileSync } from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { join as join10, resolve as resolve3, sep as sep2 } from "node:path";
+import { mkdirSync as mkdirSync5, readdirSync as readdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { join as join11, resolve as resolve5, sep as sep2 } from "node:path";
 import { DatabaseSync as DatabaseSync2 } from "node:sqlite";
 import { parseArgs as parseArgs2 } from "node:util";
 import { parse as parseYaml3 } from "yaml";
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 function eventFields(raw) {
   let data;
   try {
@@ -2410,7 +2885,7 @@ function kiroIdePromptEvent(now = Date.now()) {
 }
 function loadTriggerFile(path) {
   try {
-    const result = z6.array(TriggerSchema).safeParse(parseYaml3(readFileSync(path, "utf8")));
+    const result = z7.array(TriggerSchema).safeParse(parseYaml3(readFileSync2(path, "utf8")));
     return result.success ? result.data : null;
   } catch {
     return null;
@@ -2434,9 +2909,9 @@ function effectiveTriggers(config, scope, fileTriggers = []) {
   }
   return { triggers, duplicates };
 }
-function expandHome(path) {
-  if (path === "~") return homedir3();
-  return path.startsWith("~/") ? join10(homedir3(), path.slice(2)) : path;
+function expandHome2(path) {
+  if (path === "~") return homedir4();
+  return path.startsWith("~/") ? join11(homedir4(), path.slice(2)) : path;
 }
 function resolveScope(config, cwd) {
   if (cwd === void 0 || cwd === "") return void 0;
@@ -2444,7 +2919,7 @@ function resolveScope(config, cwd) {
   let bestLength = -1;
   for (const [name, scope] of Object.entries(config.scopes)) {
     if (scope.repo === void 0) continue;
-    const repo = expandHome(scope.repo).replace(/\/+$/, "");
+    const repo = expandHome2(scope.repo).replace(/\/+$/, "");
     if (!repo.startsWith("/")) continue;
     if (cwd !== repo && !cwd.startsWith(`${repo}/`)) continue;
     if (repo.length > bestLength) {
@@ -2593,7 +3068,7 @@ function matchPretoolTriggers(toolName, toolInput, triggers, cwd) {
   }
   return matches;
 }
-function evaluateMatches(matches, vaultRoot2) {
+function evaluateMatches(matches, vaultRoot) {
   const fired = [];
   const skipped = [];
   for (const match of matches) {
@@ -2601,38 +3076,38 @@ function evaluateMatches(matches, vaultRoot2) {
       fired.push(match);
       continue;
     }
-    const verdict = evaluateWhen(match.when, vaultRoot2);
+    const verdict = evaluateWhen(match.when, vaultRoot);
     if (verdict === null) skipped.push(match.id);
     else if (!verdict) fired.push(match);
   }
   return { fired, skipped };
 }
-function evaluateWhenVerdict(when, vaultRoot2) {
+function evaluateWhenVerdict(when, vaultRoot) {
   if (typeof when === "string") return "unknown";
   try {
-    const than = newestUpdated(vaultRoot2, when.than);
+    const than = newestUpdated(vaultRoot, when.than);
     if (than === null) return "vacuous";
-    const fresh = newestUpdated(vaultRoot2, when.fresh);
+    const fresh = newestUpdated(vaultRoot, when.fresh);
     if (fresh === null) return "unmet";
     return fresh >= than ? "satisfied" : "unmet";
   } catch {
     return "unknown";
   }
 }
-function evaluateWhen(when, vaultRoot2) {
-  const verdict = evaluateWhenVerdict(when, vaultRoot2);
+function evaluateWhen(when, vaultRoot) {
+  const verdict = evaluateWhenVerdict(when, vaultRoot);
   if (verdict === "unknown") return null;
   return verdict !== "unmet";
 }
-function newestUpdated(vaultRoot2, globs) {
+function newestUpdated(vaultRoot, globs) {
   const regexes = globs.map(globToRegExp);
   let newest = null;
-  for (const entry of readdirSync2(vaultRoot2, { recursive: true })) {
+  for (const entry of readdirSync2(vaultRoot, { recursive: true })) {
     const rel = entry.split(sep2).join("/");
     if (!rel.endsWith(".md")) continue;
     if (rel.startsWith(".") || rel.includes("/.")) continue;
     if (!regexes.some((regex) => regex.test(rel))) continue;
-    const updated = readUpdated(join10(vaultRoot2, entry));
+    const updated = readUpdated(join11(vaultRoot, entry));
     if (updated !== null && (newest === null || updated > newest)) {
       newest = updated;
     }
@@ -2641,7 +3116,7 @@ function newestUpdated(vaultRoot2, globs) {
 }
 function readUpdated(path) {
   try {
-    const { data } = parseFrontmatter(readFileSync(path, "utf8"));
+    const { data } = parseFrontmatter(readFileSync2(path, "utf8"));
     const updated = data.updated;
     if (typeof updated === "string") return updated;
     if (updated instanceof Date) return updated.toISOString().slice(0, 10);
@@ -2704,15 +3179,15 @@ function commandPaths(toolInput) {
   }
   return paths;
 }
-function vaultPathTouched(toolInput, vaultRoot2, cwd) {
-  const root = resolve3(vaultRoot2);
+function vaultPathTouched(toolInput, vaultRoot, cwd) {
+  const root = resolve5(vaultRoot);
   const candidates = [
     ...pathCandidates(toolInput, cwd),
     ...patchPaths(toolInput),
     ...commandPaths(toolInput)
   ];
   return candidates.some((candidate) => {
-    const absolute = resolve3(cwd ?? ".", candidate);
+    const absolute = resolve5(cwd ?? ".", candidate);
     return absolute === root || absolute.startsWith(`${root}/`);
   });
 }
@@ -2762,12 +3237,12 @@ function dedupePretoolMatches(stateDir, sessionId, matches, persist = true) {
   const fresh = dedupeMatches(stateDir, sessionId, rest, Date.now(), persist);
   return matches.filter((match) => blocks.includes(match) || fresh.includes(match));
 }
-function hookStateDir() {
-  return join10(kmdHome(), "state", "hook");
+function hookStateDir(vaultRoot) {
+  return resolveStateDir(vaultRoot);
 }
 function explainPrompt(options) {
   const now = options.now ?? Date.now();
-  const fired = readFired(join10(options.stateDir, safeName(options.sessionId)));
+  const fired = readFired(join11(options.stateDir, safeName(options.sessionId)));
   const entries = [];
   const rendered = [];
   const state = { db: null };
@@ -2804,7 +3279,7 @@ function explainPrompt(options) {
 }
 function explainPretool(options) {
   const now = options.now ?? Date.now();
-  const fired = readFired(join10(options.stateDir, safeName(options.sessionId)));
+  const fired = readFired(join11(options.stateDir, safeName(options.sessionId)));
   const entries = [];
   const rendered = [];
   for (const trigger of options.triggers) {
@@ -2845,7 +3320,7 @@ function explainPretool(options) {
 }
 function dedupeMatches(stateDir, sessionId, matches, now = Date.now(), persist = true) {
   if (matches.length === 0) return [];
-  const dir = join10(stateDir, safeName(sessionId));
+  const dir = join11(stateDir, safeName(sessionId));
   const fired = readFired(dir);
   const fresh = [];
   const record = [];
@@ -2861,10 +3336,10 @@ function dedupeMatches(stateDir, sessionId, matches, now = Date.now(), persist =
   }
   if (persist && record.length > 0) {
     try {
-      mkdirSync4(dir, { recursive: true });
+      mkdirSync5(dir, { recursive: true });
       for (const key of record) {
         try {
-          writeFileSync(join10(dir, key), "", { flag: "wx" });
+          writeFileSync2(join11(dir, key), "", { flag: "wx" });
         } catch (err) {
           if (err.code !== "EEXIST") throw err;
         }
@@ -2896,7 +3371,7 @@ function pruneStale(stateDir, keep) {
   try {
     const cutoff = Date.now() - SESSION_STATE_MAX_AGE_MS;
     for (const entry of readdirSync2(stateDir)) {
-      const path = join10(stateDir, entry);
+      const path = join11(stateDir, entry);
       if (path !== keep && statSync(path).mtimeMs < cutoff) {
         rmSync2(path, { recursive: true, force: true });
       }
@@ -2913,17 +3388,14 @@ function hookInvocation() {
       scope: { type: "string" },
       harness: { type: "string" },
       triggers: { type: "string" },
+      "default-root": { type: "string" },
       "dry-run": { type: "boolean" },
       explain: { type: "boolean" }
     }
   });
-  const vaultRoot2 = positionals2[2] ?? process.env.WIKI_VAULT;
-  if (vaultRoot2 === void 0 || vaultRoot2 === "") {
-    diag2("no vault root (positional or $WIKI_VAULT)");
-    return null;
-  }
   return {
-    vaultRoot: vaultRoot2,
+    positional: positionals2[2],
+    defaultRoot: typeof values2["default-root"] === "string" ? values2["default-root"] : void 0,
     scope: typeof values2.scope === "string" ? values2.scope : process.env.WIKI_SCOPE,
     harness: values2.harness,
     triggersFile: values2.triggers,
@@ -2931,6 +3403,28 @@ function hookInvocation() {
     explain: values2.explain === true
   };
 }
+function resolveHookVault(invocation, eventCwd) {
+  if (invocation.positional !== void 0 && invocation.defaultRoot !== void 0) {
+    diag2("<vault-root> and --default-root are mutually exclusive \u2014 using the positional");
+  }
+  try {
+    const resolution = resolveVaultRoot({
+      positional: invocation.positional,
+      projectDir: eventCwd,
+      defaultRoot: invocation.defaultRoot,
+      envVault: process.env.WIKI_VAULT,
+      globalDefault: loadGlobalConfig().default_vault
+    });
+    if (resolution.root === null) {
+      diag2("no vault root resolvable (positional, event cwd, --default-root, or $WIKI_VAULT)");
+      return null;
+    }
+    return resolution.root;
+  } catch (err) {
+    diag2(`vault resolution failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
 function resolveFileTriggers(invocation) {
   if (typeof invocation.triggersFile !== "string") return [];
   const loaded = loadTriggerFile(invocation.triggersFile);
@@ -2943,8 +3437,6 @@ function resolveFileTriggers(invocation) {
 async function runHookPrompt() {
   try {
     const invocation = hookInvocation();
-    if (invocation === null) return;
-    const { vaultRoot: vaultRoot2 } = invocation;
     let event = null;
     if (invocation.harness === "kiro-ide") {
       event = kiroIdePromptEvent();
@@ -2956,7 +3448,9 @@ async function runHookPrompt() {
       diag2("stdin is not a prompt event ({session_id, prompt})");
       return;
     }
-    const config = await loadVaultConfig(vaultRoot2);
+    const vaultRoot = resolveHookVault(invocation, event.cwd);
+    if (vaultRoot === null) return;
+    const config = await loadVaultConfig(vaultRoot);
     const scope = invocation.scope ?? resolveScope(config, event.cwd);
     const { triggers, duplicates } = effectiveTriggers(
       config,
@@ -2970,7 +3464,7 @@ async function runHookPrompt() {
       const trace = explainPrompt({
         prompt: event.prompt,
         triggers,
-        stateDir: hookStateDir(),
+        stateDir: hookStateDir(vaultRoot),
         sessionId: event.session_id
       });
       console.log(JSON.stringify({ event: "prompt", scope: scope ?? null, duplicates, ...trace }));
@@ -2978,7 +3472,7 @@ async function runHookPrompt() {
     }
     const matches = matchPromptTriggers(event.prompt, triggers);
     const fresh = dedupeMatches(
-      hookStateDir(),
+      hookStateDir(vaultRoot),
       event.session_id,
       matches,
       Date.now(),
@@ -2994,8 +3488,6 @@ async function runHookPrompt() {
 async function runHookPretool() {
   try {
     const invocation = hookInvocation();
-    if (invocation === null) return;
-    const { vaultRoot: vaultRoot2 } = invocation;
     let format = "neutral";
     if (invocation.harness === "claude") {
       format = "claude";
@@ -3007,7 +3499,9 @@ async function runHookPretool() {
       diag2("stdin is not a pretool event ({session_id, tool_name})");
       return;
     }
-    const config = await loadVaultConfig(vaultRoot2);
+    const vaultRoot = resolveHookVault(invocation, event.cwd);
+    if (vaultRoot === null) return;
+    const config = await loadVaultConfig(vaultRoot);
     const scope = invocation.scope ?? resolveScope(config, event.cwd);
     const { triggers, duplicates } = effectiveTriggers(
       config,
@@ -3022,8 +3516,8 @@ async function runHookPretool() {
         toolName: event.tool_name,
         toolInput: event.tool_input,
         triggers,
-        vaultRoot: vaultRoot2,
-        stateDir: hookStateDir(),
+        vaultRoot,
+        stateDir: hookStateDir(vaultRoot),
         sessionId: event.session_id,
         ...event.cwd !== void 0 && { cwd: event.cwd },
         format
@@ -3032,12 +3526,12 @@ async function runHookPretool() {
       return;
     }
     const matches = matchPretoolTriggers(event.tool_name, event.tool_input, triggers, event.cwd);
-    const { fired, skipped } = evaluateMatches(matches, vaultRoot2);
+    const { fired, skipped } = evaluateMatches(matches, vaultRoot);
     for (const id of skipped) {
       diag2(`trigger "${id}": unknown or unevaluable predicate \u2014 skipped`);
     }
     const rendered = renderPretool(
-      dedupePretoolMatches(hookStateDir(), event.session_id, fired, !invocation.dryRun),
+      dedupePretoolMatches(hookStateDir(vaultRoot), event.session_id, fired, !invocation.dryRun),
       format
     );
     for (const line of rendered.stderr) {
@@ -3053,7 +3547,6 @@ async function runHookPretool() {
 async function runHookPosttool() {
   try {
     const invocation = hookInvocation();
-    if (invocation === null) return;
     if (invocation.dryRun) {
       diag2("--dry-run/--explain support prompt and pretool events only");
       return;
@@ -3069,13 +3562,15 @@ async function runHookPosttool() {
       diag2("stdin is not a posttool event ({session_id, tool_name})");
       return;
     }
-    if (!vaultPathTouched(event.tool_input, invocation.vaultRoot, event.cwd)) return;
-    const config = await loadVaultConfig(invocation.vaultRoot);
-    const findings = await validateVault(invocation.vaultRoot);
+    const vaultRoot = resolveHookVault(invocation, event.cwd);
+    if (vaultRoot === null) return;
+    if (!vaultPathTouched(event.tool_input, vaultRoot, event.cwd)) return;
+    const config = await loadVaultConfig(vaultRoot);
+    const findings = await validateVault(vaultRoot);
     let synced = false;
     if (!hasErrors(findings)) {
       try {
-        await syncVault(invocation.vaultRoot);
+        await syncVault(vaultRoot);
         synced = true;
       } catch (err) {
         diag2(`sync failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -3092,7 +3587,6 @@ async function runHookPosttool() {
 async function runHookStop() {
   try {
     const invocation = hookInvocation();
-    if (invocation === null) return;
     if (invocation.dryRun) {
       diag2("--dry-run/--explain support prompt and pretool events only");
       return;
@@ -3103,21 +3597,62 @@ async function runHookStop() {
       return;
     }
     if (event.stop_hook_active === true) return;
-    const config = await loadVaultConfig(invocation.vaultRoot);
+    const vaultRoot = resolveHookVault(invocation, event.cwd);
+    if (vaultRoot === null) return;
+    const config = await loadVaultConfig(vaultRoot);
     const scope = invocation.scope ?? resolveScope(config, event.cwd);
     if (scope === void 0) return;
     const rendered = renderStop(
-      await validateVault(invocation.vaultRoot),
+      await validateVault(vaultRoot),
       config.builtin_hooks?.["handoff-gate"]?.reason
     );
     if (rendered === null) return;
-    const fired = dedupeMatches(hookStateDir(), event.session_id, [{ id: "handoff-gate" }]);
+    const fired = dedupeMatches(hookStateDir(vaultRoot), event.session_id, [
+      { id: "handoff-gate" }
+    ]);
     if (fired.length === 0) return;
     console.log(rendered);
   } catch (err) {
     diag2(err instanceof Error ? err.message : String(err));
   }
 }
+function parseSessionStartEvent(raw) {
+  const fields = eventFields(raw);
+  if (fields === null) return null;
+  const { session_id, cwd, source } = fields;
+  if (typeof session_id !== "string") return null;
+  return {
+    session_id,
+    ...typeof cwd === "string" && { cwd },
+    ...typeof source === "string" && { source }
+  };
+}
+function renderSessionStart(scope, source, messages = {}) {
+  const text = source === "compact" ? messages.reorient?.text ?? REORIENT_TEXT : messages.orient?.text ?? ORIENT_TEXT;
+  return `Wiki scope "${scope}": ${text}`;
+}
+async function runHookSessionStart() {
+  try {
+    const invocation = hookInvocation();
+    if (invocation.dryRun) {
+      diag2("--dry-run/--explain support prompt and pretool events only");
+      return;
+    }
+    const event = parseSessionStartEvent(await readStdin());
+    if (event === null) {
+      diag2("stdin is not a session-start event ({session_id})");
+      return;
+    }
+    const vaultRoot = resolveHookVault(invocation, event.cwd);
+    if (vaultRoot === null) return;
+    const config = await loadVaultConfig(vaultRoot);
+    const scope = invocation.scope ?? resolveScope(config, event.cwd);
+    if (scope === void 0) return;
+    console.log(renderSessionStart(scope, event.source, config.builtin_hooks ?? {}));
+  } catch (err) {
+    diag2(err instanceof Error ? err.message : String(err));
+  }
+}
 async function readStdin() {
   process.stdin.setEncoding("utf8");
   let input = "";
@@ -3129,11 +3664,12 @@ async function readStdin() {
 function diag2(message) {
   console.error(`kmd hook: ${message}`);
 }
-var DEFAULT_TRIGGERS, SESSION_STATE_MAX_AGE_MS, KIRO_IDE_BUCKET_MS, ALL_SCOPES_KEY, PATCH_FILE_RE, COMMAND_TOKEN_RE, PATHISH_RE, RESYNC_REASON, RESYNC_TEXT, HANDOFF_GATE_REASON;
+var DEFAULT_TRIGGERS, SESSION_STATE_MAX_AGE_MS, KIRO_IDE_BUCKET_MS, ALL_SCOPES_KEY, PATCH_FILE_RE, COMMAND_TOKEN_RE, PATHISH_RE, RESYNC_REASON, RESYNC_TEXT, HANDOFF_GATE_REASON, ORIENT_TEXT, REORIENT_TEXT;
 var init_hook = __esm({
   "../cli/src/hook.ts"() {
     "use strict";
     init_database();
+    init_kmd_config();
     init_vault_config();
     init_frontmatter();
     init_sync();
@@ -3148,6 +3684,8 @@ var init_hook = __esm({
     RESYNC_REASON = "Edit landed; the index sync is held until these validate errors are fixed";
     RESYNC_TEXT = "kmd sync failed \u2014 index not updated; see hook stderr";
     HANDOFF_GATE_REASON = "Validate errors are outstanding and the index sync is held \u2014 fix them, let the resync run, then finish";
+    ORIENT_TEXT = "prime via the wiki MCP prime tool before substantive work \u2014 the primer carries current focus, book of work, and invariants.";
+    REORIENT_TEXT = "context was compacted and transcript detail is lost \u2014 re-read the primer via the wiki MCP prime tool and route uncaptured findings into the wiki before continuing.";
   }
 });
 
@@ -3161,16 +3699,33 @@ process.on("warning", (warning) => {
 });
 var USAGE = `usage: kmd <command> [options]
 
+vault resolution (every command): positional > project tier (.kmd/config.local.yaml >
+.kmd/config.yaml > vault/vault.yaml > vault.yaml with a .kmd marker beside it,
+nearest ancestor of $KMD_PROJECT_DIR or cwd) > --default-root > $WIKI_VAULT >
+~/.kmd/config.yaml default_vault
+
 commands:
-  init [<dir>] [-y]        scaffold a fresh vault (no dir: current directory \u2014 TTY prompt, or -y)
-  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)
-  hook <prompt|pretool|posttool|stop> [<vault-root>] [--scope <s>] [--harness <claude|kiro-ide>] [--triggers <file>]
+  init [<dir>] [-y] [--set-default]
+                           scaffold a fresh vault (no dir: current directory \u2014 TTY prompt, or -y);
+                           TTY offers to record it as default_vault, --set-default records it
+                           without asking (-y alone never touches the machine default)
+  init --local [-y]        scaffold a project vault: <git-root>/vault + <git-root>/.kmd state home
+  sync [<vault-root>]      vault \u2192 index sync (runs validate first)
+  validate [<path>]        deterministic vault checker
+  mcp [<vault-root>] [--default-root <path>]
+                           start the stdio MCP server; --default-root is the plugin form
+                           (config default the project tier may beat); flags are mutually exclusive;
+                           no positional and no $KMD_PROJECT_DIR: the vault binds after
+                           initialization, from the client's roots/list when it declares the
+                           roots capability
+  config [<vault-root>]    print resolved vault + winning source; with nothing resolvable, list known vaults
+  config <set|get|unset> default_vault [<path>]
+                           read/write the global default in ~/.kmd/config.yaml
+  db reset [<vault-root>]  delete the vault's index
+  hook <prompt|pretool|posttool|stop|session-start> [<vault-root>] [--default-root <path>] [--scope <s>] [--harness <claude|kiro-ide>] [--triggers <file>]
                            harness gate engine: JSON event on stdin, decision/context on stdout;
-                           posttool auto-runs validate + sync after a vault write;
+                           the vault resolves through the chain with the event cwd as project
+                           signal; posttool auto-runs validate + sync after a vault write;
                            stop blocks the handoff once while validate errors hold the sync
 
 options:
@@ -3183,52 +3738,79 @@ var { positionals, values } = parseArgs3({
   options: {
     version: { type: "boolean", short: "v" },
     help: { type: "boolean", short: "h" },
-    yes: { type: "boolean", short: "y" }
+    yes: { type: "boolean", short: "y" },
+    "default-root": { type: "string" },
+    "set-default": { type: "boolean" },
+    local: { type: "boolean" }
   }
 });
 var command = values.version ? "--version" : values.help ? "--help" : positionals[0];
-function applyVaultRoot(positionalIndex) {
-  const arg = positionals[positionalIndex];
-  if (arg) {
-    process.env.WIKI_VAULT = arg;
-  }
-}
 async function run() {
   switch (command) {
     case "init": {
       const { runInit: runInit2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
-      await runInit2(positionals[1], Boolean(values.yes));
+      await runInit2(
+        positionals[1],
+        Boolean(values.yes),
+        Boolean(values.local),
+        Boolean(values["set-default"])
+      );
       break;
     }
     case "sync": {
       const { runSyncCommand: runSyncCommand2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
-      await runSyncCommand2();
+      await runSyncCommand2(positionals[1]);
       break;
     }
     case "validate": {
-      applyVaultRoot(1);
       const { runValidate: runValidate2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
-      await runValidate2();
+      await runValidate2(positionals[1]);
       break;
     }
     case "mcp": {
-      applyVaultRoot(1);
+      const positional = positionals[1];
+      const defaultRoot = typeof values["default-root"] === "string" ? values["default-root"] : void 0;
+      if (positional && defaultRoot !== void 0) {
+        console.error("kmd mcp: <vault-root> and --default-root are mutually exclusive");
+        process.exit(2);
+      }
       const { startMcpServer: startMcpServer2 } = await Promise.resolve().then(() => (init_start(), start_exports));
+      if (!positional && !process.env.KMD_PROJECT_DIR) {
+        const { loadGlobalConfig: loadGlobalConfig2 } = await Promise.resolve().then(() => (init_kmd_config(), kmd_config_exports));
+        await startMcpServer2({
+          cwd: process.cwd(),
+          defaultRoot,
+          envVault: process.env.WIKI_VAULT,
+          globalDefault: loadGlobalConfig2().default_vault
+        });
+        break;
+      }
+      const { resolveCliVault: resolveCliVault2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
+      const resolved = resolveCliVault2(positional, defaultRoot);
+      if (resolved.root === null) {
+        console.error(
+          "kmd mcp: no vault resolvable \u2014 pass <vault-root>, run inside a project vault, set WIKI_VAULT, or `kmd config set default_vault <path>`"
+        );
+        process.exit(1);
+      }
+      process.env.WIKI_VAULT = resolved.root;
       await startMcpServer2();
       break;
     }
     case "config": {
-      applyVaultRoot(1);
-      const { runConfig: runConfig2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
-      await runConfig2();
+      const sub = positionals[1];
+      const { runConfig: runConfig2, runConfigGet: runConfigGet2, runConfigSet: runConfigSet2, runConfigUnset: runConfigUnset2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
+      if (sub === "set") await runConfigSet2(positionals[2], positionals[3]);
+      else if (sub === "get") await runConfigGet2(positionals[2]);
+      else if (sub === "unset") await runConfigUnset2(positionals[2]);
+      else await runConfig2(sub);
       break;
     }
     case "db": {
       const sub = positionals[1];
       if (sub === "reset") {
-        applyVaultRoot(2);
         const { runDbReset: runDbReset2 } = await Promise.resolve().then(() => (init_cli(), cli_exports));
-        await runDbReset2();
+        await runDbReset2(positionals[2]);
       } else {
         console.error(sub ? `unknown db subcommand: ${sub}` : "usage: kmd db reset [<vault-root>]");
         process.exit(2);
@@ -3249,11 +3831,14 @@ async function run() {
       } else if (sub === "stop") {
         const { runHookStop: runHookStop2 } = await Promise.resolve().then(() => (init_hook(), hook_exports));
         await runHookStop2();
+      } else if (sub === "session-start") {
+        const { runHookSessionStart: runHookSessionStart2 } = await Promise.resolve().then(() => (init_hook(), hook_exports));
+        await runHookSessionStart2();
       } else if (sub) {
         console.error(`kmd hook: unknown event: ${sub}`);
       } else {
         console.error(
-          "usage: kmd hook <prompt|pretool|posttool|stop> [<vault-root>] [--scope <scope>] [--harness <claude|kiro-ide>]"
+          "usage: kmd hook <prompt|pretool|posttool|stop|session-start> [<vault-root>] [--scope <scope>] [--harness <claude|kiro-ide>]"
         );
         process.exit(2);
       }
@@ -3261,11 +3846,11 @@ async function run() {
     }
     case "--version":
     case "-v": {
-      const { readFileSync: readFileSync2 } = await import("node:fs");
-      const { join: join11, dirname: dirname4 } = await import("node:path");
-      const { fileURLToPath } = await import("node:url");
-      const pkgDir = dirname4(dirname4(fileURLToPath(import.meta.url)));
-      const pkg = JSON.parse(readFileSync2(join11(pkgDir, "package.json"), "utf8"));
+      const { readFileSync: readFileSync3 } = await import("node:fs");
+      const { join: join12, dirname: dirname7 } = await import("node:path");
+      const { fileURLToPath: fileURLToPath2 } = await import("node:url");
+      const pkgDir = dirname7(dirname7(fileURLToPath2(import.meta.url)));
+      const pkg = JSON.parse(readFileSync3(join12(pkgDir, "package.json"), "utf8"));
       console.log(pkg.version);
       break;
     }