@khanhcan148/mk 0.1.18 → 0.1.20

package/README.md

@@ -88,7 +88,7 @@ cp -r .claude ~/.claude/
 
 ```
 ├── .claude/
-│   ├── agents/      # 32 agents (5 primary + 27 utility: implementers, quality, docs, specialized, concerns)
+│   ├── agents/      # 36 agents (5 primary + 31 utility: implementers, quality, docs, specialized, concerns, brainstorm critics)
 │   ├── skills/      # 67 skill packages (SKILL.md + scripts/references/assets)
 │   │   ├── mk-*/    # 20 workflow commands (/mk-audit, /mk-brainstorm, /mk-log-analysis, /mk-overview, /mk-wiki, etc.)
 │   │   └── ...      # Domain skills (frontend, backend, testing, browser automation, etc.)

package/bin/mk.js

@@ -7,6 +7,7 @@ import { initAction } from '../src/commands/init.js';
 import { updateAction } from '../src/commands/update.js';
 import { removeAction } from '../src/commands/remove.js';
 import { loginAction, logoutAction, statusAction } from '../src/commands/auth.js';
+import vaultCmd from '../src/commands/vault.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -50,4 +51,6 @@ auth.command('status')
   .description('Show current authentication status')
   .action(() => statusAction());
 
+program.addCommand(vaultCmd);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {

package/src/commands/auth.js

@@ -138,6 +138,17 @@ export async function statusAction(deps = {}) {
     process.stdout.write(chalk.green('Repo access: granted\n'));
   } else {
     process.stdout.write(chalk.red('Repo access: denied\n'));
-    process.stdout.write('Contact the repository owner for collaborator access.\n');
+    const hasRepoScope = access.scopes?.some((s) => s === 'repo');
+    if (access.status === 404 && access.scopes && !hasRepoScope) {
+      // 404 with no 'repo' scope usually means the token can't see the private
+      // KIT_REPO — re-authenticating picks up the new default scope.
+      const current = access.scopes.length ? access.scopes.join(', ') : 'none';
+      process.stdout.write(
+        `Token is missing the 'repo' scope (current scopes: ${current}).\n` +
+        "Run 'mk auth logout && mk auth login' to re-authenticate with the required scope.\n"
+      );
+    } else {
+      process.stdout.write('Contact the repository owner for collaborator access.\n');
+    }
   }
 }

package/src/commands/init.js

@@ -162,6 +162,7 @@ export async function initAction(options = {}, deps = {}) {
         chalk.green(`Installed ${result.fileCount} files (${sizeKB} KB) to ${targetDir}\n`)
       );
       process.stdout.write(`Manifest written to: ${manifestPath}\n`);
+      console.log('\nOptional: enable Obsidian vault context with: mk vault status');
     }
   } catch (err) {
     process.stderr.write(chalk.red(`Error: ${err.message}\n`));

package/src/commands/update.js

@@ -32,7 +32,7 @@ import { isEmptyDir } from '../lib/fs-utils.js';
  * @param {string} str
  * @returns {string}
  */
-function stripTerminalEscapes(str) {
+export function stripTerminalEscapes(str) {
   return str
     .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')         // CSI sequences
     .replace(/\x1b\].*?(\x07|\x1b\\)/gs, '')         // OSC sequences (dotAll for multiline)

package/src/commands/vault.js

@@ -0,0 +1,363 @@
+/**
+ * vault.js
+ * Commander subcommand group for 'mk vault'.
+ *
+ * Subcommands: enable, disable, status, untaint
+ *
+ * Named action exports (enableAction, disableAction, statusAction, untaintAction)
+ * allow direct unit testing without going through Commander.
+ */
+
+import { Command } from 'commander';
+import {
+  existsSync,
+  readdirSync,
+  unlinkSync,
+  mkdirSync,
+  statSync
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import {
+  readProjectBinding,
+  writeProjectBinding,
+  writeUserBinding,
+  resolveActiveBinding
+} from '../lib/vault-binding.js';
+import { appendMkToGitignore } from '../lib/gitignore-helper.js';
+
+// ---------------------------------------------------------------------------
+// CI detection
+// ---------------------------------------------------------------------------
+
+const CI_ENV_VARS = ['CI', 'GITHUB_ACTIONS', 'CIRCLECI', 'BUILDKITE', 'TF_BUILD'];
+
+function isCI() {
+  return CI_ENV_VARS.some(v => !!process.env[v]);
+}
+
+function ciSafeOverride() {
+  return process.env.MK_VAULT_CI_SAFE === 'allow';
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Count .md files recursively under a directory.
+ * Uses withFileTypes:true; symlinks are skipped (entry.isFile() returns false for symlinks).
+ * Exported for testing (H3).
+ */
+export function countMdFiles(dir) {
+  let count = 0;
+  function walk(d) {
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        walk(join(d, entry.name));
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        count++;
+      }
+    }
+  }
+  walk(dir);
+  return count;
+}
+
+/**
+ * Hash a path for safe display (first 8 chars of sha256 hex).
+ */
+function hashPath(p) {
+  return createHash('sha256').update(p).digest('hex').slice(0, 8);
+}
+
+/**
+ * Prompt user for a choice via readline (returns promise resolving to string).
+ */
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// enableAction
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle 'mk vault enable <folder>'.
+ *
+ * opts:
+ *   cwd              - working directory (default: process.cwd())
+ *   _skipGitignore   - skip appendMkToGitignore call (test hook)
+ *   _skipSizeProbe   - skip note count (test hook)
+ *   _noteCount       - inject note count directly (test hook)
+ *   _mode            - inject mode directly, skip stdin prompt (test hook)
+ *   _userConfigPath  - override user config path (test hook)
+ *
+ * @param {string} folder
+ * @param {object} [opts]
+ */
+export async function enableAction(folder, opts = {}) {
+  const {
+    cwd = process.cwd(),
+    _skipGitignore = false,
+    _skipSizeProbe = false,
+    _noteCount,
+    _mode,
+    _userConfigPath
+  } = opts;
+
+  // Resolve absolute path
+  const vaultPath = resolve(folder);
+
+  // Validate folder exists and is accessible
+  try {
+    statSync(vaultPath);
+  } catch {
+    process.stderr.write(`Error: Vault folder not found or not accessible: ${vaultPath}\n`);
+    return;
+  }
+
+  // Append to .gitignore (unless skipped)
+  if (!_skipGitignore) {
+    await appendMkToGitignore(cwd);
+  }
+
+  // Determine note count
+  let noteCount = _noteCount;
+  if (noteCount === undefined && !_skipSizeProbe) {
+    noteCount = countMdFiles(vaultPath);
+  }
+  if (noteCount === undefined) {
+    noteCount = 0;
+  }
+
+  // Determine mode
+  let mode = _mode;
+  if (!mode) {
+    if (noteCount > 200) {
+      // Prompt user to choose mode
+      process.stdout.write(`Vault contains ${noteCount} notes (> 200 threshold).\n`);
+      process.stdout.write('Select mode:\n  1) recursive (index all notes)\n  2) digest (summary only)\n');
+      const answer = await prompt('Enter 1 or 2: ');
+      mode = answer === '2' ? 'digest' : 'recursive';
+    } else {
+      mode = 'recursive';
+    }
+  }
+
+  // Build binding data
+  const { getMachineId } = await import('../lib/vault-binding.js');
+  const binding = {
+    path: vaultPath,
+    version: 1,
+    machine_id: getMachineId(),
+    mode
+  };
+
+  // Write project-level binding
+  const mkDir = join(cwd, '.mk');
+  mkdirSync(mkDir, { recursive: true });
+  await writeProjectBinding(cwd, binding);
+
+  // Write user-level binding (skip in CI unless MK_VAULT_CI_SAFE=allow)
+  if (isCI() && !ciSafeOverride()) {
+    process.stderr.write(
+      `[AM-3] CI environment detected — skipping user-level vault binding write. ` +
+      `Set MK_VAULT_CI_SAFE=allow to override. (refused)\n`
+    );
+  } else {
+    await writeUserBinding(binding, { _userConfigPath });
+  }
+
+  // Print confirmation
+  const pathHash = hashPath(vaultPath);
+  process.stdout.write(`Vault enabled: ${vaultPath} [hash:${pathHash}] (mode:${mode})\n`);
+}
+
+// ---------------------------------------------------------------------------
+// disableAction
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle 'mk vault disable'.
+ *
+ * opts:
+ *   cwd             - working directory (default: process.cwd())
+ *   _userConfigPath - override user config path (test hook)
+ *
+ * @param {object} [opts]
+ */
+export async function disableAction(opts = {}) {
+  const { cwd = process.cwd(), _userConfigPath } = opts;
+
+  const projectBindingFile = join(cwd, '.mk', 'vault.json');
+  const hadProject = existsSync(projectBindingFile);
+
+  if (hadProject) {
+    unlinkSync(projectBindingFile);
+    process.stdout.write('Vault disabled: project-level binding removed.\n');
+  } else {
+    // Try to remove user-level binding if no project binding was found
+    const userPath = _userConfigPath || join(
+      (await import('node:os')).homedir(),
+      '.config', 'mk', 'vault.json'
+    );
+    if (existsSync(userPath)) {
+      unlinkSync(userPath);
+      process.stdout.write('Vault disabled: user-level binding removed.\n');
+    } else {
+      process.stdout.write('No active vault binding found — nothing to disable.\n');
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// statusAction
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle 'mk vault status [--json]'.
+ *
+ * opts:
+ *   cwd             - working directory (default: process.cwd())
+ *   json            - emit JSON output
+ *   _userConfigPath - override user config path (test hook)
+ *   _skipProbe      - skip Obsidian probe (test hook)
+ *
+ * @param {object} [opts]
+ */
+export async function statusAction(opts = {}) {
+  const {
+    cwd = process.cwd(),
+    json: jsonMode = false,
+    _userConfigPath,
+    _skipProbe = false
+  } = opts;
+
+  const binding = resolveActiveBinding(cwd, { _userConfigPath });
+
+  // Probe Obsidian availability (unless skipped in tests)
+  let probe = false;
+  if (!_skipProbe) {
+    try {
+      execSync('obsidian help', { stdio: 'ignore' });
+      probe = true;
+    } catch {
+      probe = false;
+    }
+  }
+
+  const result = {
+    enabled: binding !== null,
+    probe,
+    bound_path: binding ? hashPath(binding.path) : null,
+    mode: binding ? binding.mode : null
+  };
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(result));
+    return;
+  }
+
+  // Human-readable table
+  process.stdout.write(`Vault status:\n`);
+  process.stdout.write(`  enabled:    ${result.enabled}\n`);
+  process.stdout.write(`  probe:      ${result.probe}\n`);
+  process.stdout.write(`  bound_path: ${result.bound_path ?? 'none'}\n`);
+  process.stdout.write(`  mode:       ${result.mode ?? 'none'}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// untaintAction
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle 'mk vault untaint'.
+ *
+ * opts:
+ *   cwd              - working directory (default: process.cwd())
+ *   _nonInteractive  - skip confirmation prompt (test hook)
+ *
+ * @param {object} [opts]
+ */
+export async function untaintAction(opts = {}) {
+  const { cwd = process.cwd(), _nonInteractive = false } = opts;
+
+  const mkDir = join(cwd, '.mk');
+  if (!existsSync(mkDir)) {
+    process.stdout.write('No .mk/ directory found — nothing to untaint.\n');
+    return;
+  }
+
+  let taintFiles;
+  try {
+    taintFiles = readdirSync(mkDir).filter(f => f.startsWith('.taint-session-'));
+  } catch {
+    taintFiles = [];
+  }
+
+  if (taintFiles.length === 0) {
+    process.stdout.write('No taint marker found.\n');
+    return;
+  }
+
+  process.stdout.write(`Found ${taintFiles.length} taint marker(s).\n`);
+
+  // Confirm before deleting (skip in non-interactive / test mode)
+  if (!_nonInteractive) {
+    const answer = await prompt('Delete all taint markers? [y/N] ');
+    if (answer.toLowerCase() !== 'y') {
+      process.stdout.write('Aborted — no taint markers removed.\n');
+      return;
+    }
+  }
+
+  for (const f of taintFiles) {
+    unlinkSync(join(mkDir, f));
+  }
+  process.stdout.write(`Taint markers cleared: ${taintFiles.length} file(s) removed.\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Commander subcommand group
+// ---------------------------------------------------------------------------
+
+const vaultCommand = new Command('vault')
+  .description('Manage Obsidian vault binding for mk-* skill context');
+
+vaultCommand
+  .command('enable <folder>')
+  .description('Bind a vault folder to this project')
+  .action((folder) => enableAction(folder));
+
+vaultCommand
+  .command('disable')
+  .description('Remove vault binding from this project')
+  .action(() => disableAction());
+
+vaultCommand
+  .command('status')
+  .description('Show vault binding status')
+  .option('--json', 'Emit JSON output')
+  .action((options) => statusAction({ json: options.json }));
+
+vaultCommand
+  .command('untaint')
+  .description('Remove .mk/.taint-session-* markers')
+  .action(() => untaintAction());
+
+export default vaultCommand;

package/src/lib/auth.js

@@ -82,8 +82,15 @@ export async function validateToken(token) {
 /**
  * Check whether the token has access to the kit repository.
  *
+ * Returns the HTTP status and any scopes reported via the `x-oauth-scopes`
+ * response header so callers can disambiguate common failure modes:
+ *   - 404 + no 'repo' scope  → token lacks scope (most common for a private KIT_REPO)
+ *   - 404 + has 'repo' scope → authenticated account is not a collaborator
+ *   - 403                    → SSO or rate-limit block
+ *   - 0                      → network error
+ *
  * @param {string} token
- * @returns {Promise<{ accessible: boolean }>}
+ * @returns {Promise<{ accessible: boolean, status: number, scopes: string[] }>}
  */
 export async function checkRepoAccess(token) {
   try {
@@ -93,12 +100,17 @@ export async function checkRepoAccess(token) {
         Accept: 'application/vnd.github.v3+json'
       }
     });
-    return { accessible: res.ok };
+    return { accessible: res.ok, status: res.status, scopes: parseScopes(res) };
   } catch {
-    return { accessible: false };
+    return { accessible: false, status: 0, scopes: [] };
   }
 }
 
+function parseScopes(res) {
+  const raw = res.headers?.get?.('x-oauth-scopes') || '';
+  return raw.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
 // ---------------------------------------------------------------------------
 // OAuth Device Flow
 // ---------------------------------------------------------------------------
@@ -127,9 +139,15 @@ export async function startDeviceFlow(opts = {}) {
       'Content-Type': 'application/x-www-form-urlencoded',
       Accept: 'application/json'
     },
-    // Empty scope sufficient for public repos (5000 req/hr). Set MK_OAUTH_SCOPE=repo for private forks.
+    // KIT_REPO is private, so 'repo' scope is required to read it. Default to 'repo'.
+    // Override with MK_OAUTH_SCOPE for public forks (e.g. MK_OAUTH_SCOPE='' for no scope,
+    // or MK_OAUTH_SCOPE='public_repo' for public-only access).
+    // `??` (not `||`) so an explicit empty string is honored as an opt-out.
     // Use URLSearchParams to prevent parameter injection via env var containing '&' chars.
-    body: new URLSearchParams({ client_id: GITHUB_CLIENT_ID, scope: process.env.MK_OAUTH_SCOPE || '' }).toString()
+    body: new URLSearchParams({
+      client_id: GITHUB_CLIENT_ID,
+      scope: process.env.MK_OAUTH_SCOPE ?? 'repo'
+    }).toString()
   });
 
   if (!codeRes.ok) {

package/src/lib/copy.js

@@ -81,6 +81,14 @@ export function collectDiskFiles(targetDir) {
   return results;
 }
 
+/**
+ * @typedef {Object} FileEntry
+ * @property {string} relativePath - Path relative to the target .claude/ (POSIX separators, e.g. ".claude/agents/foo.md")
+ * @property {string} absolutePath - Destination absolute path under targetDir (where the file is copied to)
+ * @property {string} sourceAbsPath - Source absolute path under sourceDir (where the file is copied from)
+ * @property {number} size - File size in bytes, captured at copy time
+ */
+
 /**
  * Copy kit files from sourceDir (.claude/) to targetDir (.claude/).
  * Only copies KIT_SUBDIRS (agents/, skills/, workflows/).
@@ -88,7 +96,7 @@ export function collectDiskFiles(targetDir) {
  * @param {string} sourceDir - Absolute path to source .claude/
  * @param {string} targetDir - Absolute path to target .claude/
  * @param {{ dryRun: boolean }} options
- * @returns {Array<{ relativePath: string, absolutePath: string, sourceAbsPath: string, size: number }>}
+ * @returns {FileEntry[]}
  * @remarks Naming convention: `absolutePath` is the destination (under targetDir),
  *       `sourceAbsPath` is the source (under sourceDir). The asymmetry is intentional —
  *       renaming would break consumers (update.js). See DEBT-016.

package/src/lib/download.js

@@ -39,6 +39,24 @@ export function assertGitHubHostname(url) {
   } catch {
     throw new Error(`SSRF guard: invalid URL "${url}"`);
   }
+  // H9/H10: block non-TLS schemes. Plain http:// to github.com can be MITM-redirected,
+  // and the kit download path has no reason to accept anything but https.
+  if (parsed.protocol !== 'https:') {
+    // Truncate to guard against log injection via crafted long / newline-containing schemes.
+    const safeScheme = String(parsed.protocol).slice(0, 20);
+    throw new Error(
+      `SSRF guard: scheme "${safeScheme}" is not allowed. ` +
+      `Only https: is permitted for kit downloads.`
+    );
+  }
+  // Block userinfo-prefixed URLs (user:pass@host) — they can mask the true
+  // hostname in server-side url parsers or confuse logging/auditing.
+  if (parsed.username || parsed.password) {
+    throw new Error(
+      `SSRF guard: userinfo-prefixed URL is not allowed. ` +
+      `Credentials in the URL (user:pass@host) are rejected for kit downloads.`
+    );
+  }
   const { hostname } = parsed;
   if (!ALLOWED_HOSTS.has(hostname)) {
     throw new Error(

package/src/lib/gitignore-helper.js

@@ -0,0 +1,110 @@
+/**
+ * gitignore-helper.js
+ * Append .mk/ entries to the nearest .gitignore file.
+ *
+ * Behaviour:
+ * - If _skipGitCheck: true → skip git rev-parse check (used in tests)
+ * - If not inside a git work tree → return { status: 'no-git' } or throw
+ * - Find the nearest .gitignore at cwd (creates it if missing)
+ * - If .mk/ already present → return { status: 'already-present' }
+ * - Append .mk/ and .mk/.taint-session-* → return { status: 'appended', path }
+ * - Monorepo: the test only requires cwd-level .gitignore to be updated
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync
+} from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const MK_LINES = '.mk/\n.mk/.taint-session-*\n';
+
+/**
+ * Append .mk/ entries to the .gitignore nearest to cwd.
+ *
+ * @param {string} cwd - Directory to operate from
+ * @param {object} [opts]
+ * @param {boolean} [opts._skipGitCheck] - Skip git rev-parse check (for tests)
+ * @returns {{ status: string, path?: string, paths?: string[], error?: string }}
+ */
+export async function appendMkToGitignore(cwd, opts = {}) {
+  const { _skipGitCheck = false } = opts;
+
+  // Git check: verify we are inside a git work tree
+  if (!_skipGitCheck) {
+    try {
+      execSync('git rev-parse --show-toplevel', {
+        cwd,
+        stdio: 'pipe',
+        encoding: 'utf8'
+      });
+    } catch {
+      return { status: 'refused', error: 'Not inside a git work tree' };
+    }
+  }
+
+  // Find the nearest .gitignore (at cwd level)
+  const gitignorePath = join(cwd, '.gitignore');
+
+  // Read existing content (or empty string if file does not exist)
+  let existing = '';
+  if (existsSync(gitignorePath)) {
+    existing = readFileSync(gitignorePath, 'utf8');
+  }
+
+  // Idempotency check: if .mk/ line already present, skip
+  const lines = existing.split('\n').map(l => l.trim());
+  if (lines.includes('.mk/')) {
+    return { status: 'already-present', path: gitignorePath };
+  }
+
+  // Append the .mk/ entries
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  writeFileSync(gitignorePath, existing + separator + MK_LINES, 'utf8');
+
+  // Monorepo detection: check if there are other .gitignore files between
+  // cwd and the git root. For now we report the appended file; the test only
+  // requires that the nearest (cwd-level) .gitignore receives the lines.
+  // Return appended-monorepo if a parent .gitignore was also found.
+  let status = 'appended';
+  const paths = [gitignorePath];
+
+  // Try to find a parent .gitignore (best-effort for monorepo reporting)
+  if (!_skipGitCheck) {
+    try {
+      const gitRoot = execSync('git rev-parse --show-toplevel', {
+        cwd,
+        stdio: 'pipe',
+        encoding: 'utf8'
+      }).trim();
+
+      let dir = join(cwd, '..');
+      while (dir !== gitRoot && dir !== join(dir, '..')) {
+        const candidate = join(dir, '.gitignore');
+        if (existsSync(candidate)) {
+          const parentContent = readFileSync(candidate, 'utf8');
+          const parentLines = parentContent.split('\n').map(l => l.trim());
+          if (!parentLines.includes('.mk/')) {
+            const sep = parentContent.length > 0 && !parentContent.endsWith('\n') ? '\n' : '';
+            appendFileSync(candidate, sep + MK_LINES, 'utf8');
+          }
+          paths.push(candidate);
+          status = 'appended-monorepo';
+        }
+        const parent = join(dir, '..');
+        if (parent === dir) break;
+        dir = parent;
+      }
+    } catch {
+      // git rev-parse unavailable — no-op on monorepo detection
+    }
+  }
+
+  if (status === 'appended-monorepo') {
+    return { status, paths };
+  }
+  return { status: 'appended', path: gitignorePath };
+}

package/src/lib/vault-binding.js

@@ -0,0 +1,205 @@
+/**
+ * vault-binding.js
+ * Read and write vault binding files (project-level and user-level).
+ *
+ * Schema v1: { path: string, version: 1, machine_id: string, mode: "recursive" | "digest" }
+ *
+ * Atomic write pattern: write to .tmp then rename — same strategy as mergeSettingsJson.
+ * On read, unknown keys are stripped and the object is validated before returning (H2 + H4).
+ */
+
+import { readFileSync, writeFileSync, existsSync, renameSync, copyFileSync, mkdirSync } from 'node:fs';
+import { join, dirname, isAbsolute } from 'node:path';
+import { homedir, hostname } from 'node:os';
+
+// ---------------------------------------------------------------------------
+// Schema validation (H2 + H4)
+// ---------------------------------------------------------------------------
+
+const VALID_MODES = new Set(['recursive', 'digest']);
+
+/**
+ * Validate a raw parsed binding object and return a new object containing
+ * ONLY the four known keys: { path, version, machine_id, mode }.
+ *
+ * Validation rules:
+ *   - obj must be a non-null plain object
+ *   - path: non-empty string AND isAbsolute
+ *   - mode: "recursive" | "digest"
+ *   - version: strictly equals 1
+ *   - machine_id: non-empty string
+ *
+ * Returns null if any rule fails; otherwise returns a new stripped object.
+ *
+ * @param {unknown} obj
+ * @returns {{ path: string, version: number, machine_id: string, mode: string }|null}
+ */
+export function validateAndStripBinding(obj) {
+  if (obj === null || obj === undefined || typeof obj !== 'object' || Array.isArray(obj)) {
+    return null;
+  }
+  const { path, version, machine_id, mode } = obj;
+
+  if (typeof path !== 'string' || path.length === 0 || !isAbsolute(path)) return null;
+  if (!VALID_MODES.has(mode)) return null;
+  if (version !== 1) return null;
+  if (typeof machine_id !== 'string' || machine_id.length === 0) return null;
+
+  return { path, version, machine_id, mode };
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+/**
+ * Default user-level config path: ~/.config/mk/vault.json
+ * Can be overridden via opts._userConfigPath in tests.
+ */
+function userConfigPath(opts = {}) {
+  return opts._userConfigPath || join(homedir(), '.config', 'mk', 'vault.json');
+}
+
+/**
+ * Project-level binding path: <cwd>/.mk/vault.json
+ */
+function projectBindingPath(cwd) {
+  return join(cwd, '.mk', 'vault.json');
+}
+
+// ---------------------------------------------------------------------------
+// Read helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a JSON binding file safely.
+ * Returns parsed object, or null if file is missing or unparseable.
+ */
+function readJsonSafe(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read project-level binding from <cwd>/.mk/vault.json.
+ * Validates schema and strips unknown keys before returning (H2 + H4).
+ * Returns the validated binding object or null if missing or invalid.
+ *
+ * @param {string} cwd
+ * @returns {{ path: string, version: number, machine_id: string, mode: string }|null}
+ */
+export function readProjectBinding(cwd) {
+  return validateAndStripBinding(readJsonSafe(projectBindingPath(cwd)));
+}
+
+/**
+ * Read user-level binding from ~/.config/mk/vault.json.
+ * Validates schema and strips unknown keys before returning (H2 + H4).
+ * Returns the validated binding object or null if missing or invalid.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts._userConfigPath] - Override path for testing
+ * @returns {{ path: string, version: number, machine_id: string, mode: string }|null}
+ */
+export function readUserBinding(opts = {}) {
+  return validateAndStripBinding(readJsonSafe(userConfigPath(opts)));
+}
+
+// ---------------------------------------------------------------------------
+// Write helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a binding file atomically (write to .tmp then rename).
+ * Creates a timestamped backup of any pre-existing file.
+ * Returns { action: 'created'|'updated', backup?: string }.
+ *
+ * @param {string} filePath - Absolute path to the binding file
+ * @param {object} data - Data to serialize as JSON
+ * @returns {{ action: string, backup?: string }}
+ */
+function writeBindingAtomic(filePath, data) {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+
+  const existed = existsSync(filePath);
+  let backup;
+
+  if (existed) {
+    const ts = Date.now();
+    backup = `${filePath}.${ts}.bak`;
+    copyFileSync(filePath, backup);
+  }
+
+  const tmpPath = `${filePath}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf8');
+  renameSync(tmpPath, filePath);
+
+  return {
+    action: existed ? 'updated' : 'created',
+    ...(backup ? { backup } : {})
+  };
+}
+
+/**
+ * Write project-level binding to <cwd>/.mk/vault.json.
+ *
+ * @param {string} cwd
+ * @param {object} data
+ * @returns {{ action: string, backup?: string }}
+ */
+export async function writeProjectBinding(cwd, data) {
+  return writeBindingAtomic(projectBindingPath(cwd), data);
+}
+
+/**
+ * Write user-level binding to ~/.config/mk/vault.json.
+ *
+ * @param {object} data
+ * @param {object} [opts]
+ * @param {string} [opts._userConfigPath] - Override path for testing
+ * @returns {{ action: string, backup?: string }}
+ */
+export async function writeUserBinding(data, opts = {}) {
+  return writeBindingAtomic(userConfigPath(opts), data);
+}
+
+// ---------------------------------------------------------------------------
+// resolveActiveBinding
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active binding: project-level takes priority, user-level is fallback.
+ * Annotates result with _source: 'project' | 'user'.
+ *
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string} [opts._userConfigPath] - Override user config path for testing
+ * @returns {object|null}
+ */
+export function resolveActiveBinding(cwd, opts = {}) {
+  const project = readProjectBinding(cwd);
+  if (project) {
+    return { ...project, _source: 'project' };
+  }
+  const user = readUserBinding(opts);
+  if (user) {
+    return { ...user, _source: 'user' };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// machine_id helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the current machine identifier (hostname).
+ */
+export function getMachineId() {
+  return hostname();
+}