@khanhcan148/mk 0.1.32 → 0.1.34

package/README.md

@@ -6,7 +6,7 @@
 
 Modular packages that extend Claude Code with specialized knowledge, workflows, and tool integrations.
 
-**Quick Navigation:** [Quick Reference](docs/quick-reference.md) | [Common Workflows](docs/common-workflows.md) | [Skill Index](docs/skill-index.md)
+**Quick Navigation:** [Usage Guides](docs/guides/index.md) | [Quick Reference](docs/quick-reference.md) | [Common Workflows](docs/common-workflows.md) | [Skill Index](docs/skill-index.md)
 
 
 ## Quick Start
@@ -39,6 +39,9 @@ mk update            Update kit files (preserves your edits by default); auto-sy
 mk update --force    Update and overwrite user-modified files
 mk codex             Mirror .claude/ to .codex/ for OpenAI Codex CLI (see docs/codex/COMMAND.md)
 mk codex --cwd DIR   Convert a project at a different path
+mk env               List all MK_* environment variables grouped by scope
+mk env <NAME>        Show full details for a single variable (scope, type, default, current value)
+mk env --format json Output all variables as JSON
 mk remove            Remove all kit files tracked by manifest
 mk --version         Show installed CLI version
 mk --help            Show help
@@ -90,8 +93,8 @@ cp -r .claude ~/.claude/
 
 ```
 ├── .claude/
-│   ├── agents/      # 36 agents (5 primary + 31 utility: implementers, quality, docs, specialized, concerns, brainstorm critics)
-│   ├── skills/      # 62 skill packages (SKILL.md + scripts/references/assets)
+│   ├── agents/      # 38 agents (5 primary + 33 utility: implementers, quality, docs, specialized, concerns, brainstorm critics)
+│   ├── skills/      # 61 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.)
 │   └── workflows/   # Development protocols
@@ -228,6 +231,7 @@ python .claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-fold
 
 | Document | Description |
 |----------|-------------|
+| [mk-* Usage Guides](docs/guides/index.md) | Human how-to guides for all 20 /mk-* commands: when to use, flags, phase flow, pitfalls |
 | [Skill Index](docs/skill-index.md) | Categorized list of all skills and workflows |
 | [mk-* Workflows & Agents](docs/mk-workflow-agents.md) | How each /mk-* command works and which agents it uses |
 | [`mk codex` Command Guide](docs/codex/COMMAND.md) | Convert .claude/ to .codex/ for OpenAI Codex CLI; auto-sync on mk update |
@@ -240,6 +244,7 @@ python .claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-fold
 | [Product Domain Glossary](docs/product-domain-glossary.md) | Core domain concepts, terminology, and ecosystem definitions |
 | [Quick Reference](docs/quick-reference.md) | Common commands and quick lookup |
 | [Common Workflows](docs/common-workflows.md) | Practical workflow examples |
+| [Environment Variables](.claude/env-vars.md) | All MK_* env vars with type, default, and description; run `mk env` for live values, or `mk env --markdown` to regenerate this table |
 
 ## Core Principles
 

package/bin/mk.js

@@ -8,6 +8,7 @@ import { updateAction } from '../src/commands/update.js';
 import { removeAction } from '../src/commands/remove.js';
 import { loginAction, logoutAction, statusAction } from '../src/commands/auth.js';
 import { codexAction } from '../src/commands/codex.js';
+import { envAction } from '../src/commands/env.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -60,4 +61,11 @@ auth.command('status')
   .description('Show current authentication status')
   .action(() => statusAction());
 
+program.command('env [name]')
+  .description('List or describe MK_* environment variables')
+  .option('--format <fmt>', 'Output format: text (default) or json')
+  .option('--markdown', 'Emit the full env-vars table as markdown (same as .claude/env-vars.md)')
+  .option('--all', 'Include internal/testing variables (hidden by default)')
+  .action((name, options) => envAction(name, options));
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "test": "node --test test/lib/*.test.js test/commands/*.test.js test/scripts/*.test.js test/integration/*.test.js test/characterization/*.characterization.test.js .claude/hooks/tests/*.test.cjs",
     "lint": "node --check src/**/*.js bin/**/*.js 2>/dev/null",
     "selftest": "python3 .claude/skills/mk-selftest/scripts/validate_kit.py",
+    "gen:env-docs": "node scripts/gen-env-docs.js",
     "codex:convert": "node bin/mk.js codex",
     "codex:convert-and-diff": "node scripts/codex-diff-check.js"
   },

package/scripts/gen-env-docs.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * gen-env-docs.js — Generate .claude/env-vars.md from the env registry.
+ *
+ * Usage: node scripts/gen-env-docs.js
+ * npm script: npm run gen:env-docs
+ *
+ * Output is deterministic: entries sorted by scope then name.
+ *
+ * Output lives under .claude/ because that is the only directory shipped to
+ * user projects by `mk init`/`mk update` (the GitHub tarball extractor filters
+ * to paths containing `.claude/`). Anything under `docs/` is repo-only and
+ * never reaches users — see src/lib/download.js TarExtractor.
+ *
+ * The markdown-building logic is exported as `renderMarkdown(entries)` so the
+ * CLI can serve `mk env --markdown` from the same source — no static-file drift.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { ENTRIES } from '../src/lib/env-registry.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = resolve(__dirname, '..');
+const OUT_FILE = resolve(KIT_ROOT, '.claude', 'env-vars.md');
+
+// ---------------------------------------------------------------------------
+// Scope labels (single source of truth for grouping)
+// ---------------------------------------------------------------------------
+
+export const SCOPE_LABELS = {
+  'sql-guard': 'SQL Guard',
+  vault: 'Vault Knowledge',
+  cli: 'CLI',
+  auth: 'Auth',
+  team: 'Team Mode',
+  codex: 'Codex',
+};
+
+export function scopeLabel(scope) {
+  return SCOPE_LABELS[scope] ?? scope;
+}
+
+// ---------------------------------------------------------------------------
+// renderMarkdown — pure function. Used by both the file writer below AND
+// by `mk env --markdown` (src/commands/env.js).
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the env-vars registry as a markdown document.
+ * @param {ReadonlyArray<object>} entries — the env-registry ENTRIES array
+ * @returns {string} markdown content (newline-terminated)
+ */
+export function renderMarkdown(entries) {
+  const sorted = [...entries].sort((a, b) => {
+    if (a.scope < b.scope) return -1;
+    if (a.scope > b.scope) return 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+
+  // User-facing vars are grouped by scope; internal/testing vars (hook *_TEST
+  // bypasses, *_MAX_STDIN_BYTES caps) are collected into a single trailing
+  // section so the everyday reference stays uncluttered.
+  const userFacing = sorted.filter((e) => !e.internal);
+  const internal = sorted.filter((e) => e.internal);
+
+  const groups = new Map();
+  for (const entry of userFacing) {
+    if (!groups.has(entry.scope)) groups.set(entry.scope, []);
+    groups.get(entry.scope).push(entry);
+  }
+
+  const lines = [];
+  lines.push('# MK_* Environment Variables');
+  lines.push('');
+  lines.push(
+    '> Auto-generated by `npm run gen:env-docs` (or `mk env --markdown`). Do not edit manually.'
+  );
+  lines.push('');
+  lines.push(
+    'All `MK_*` environment variables recognized by the kit. ' +
+    'Run `mk env` for an interactive overview, or `mk env <NAME>` for details on a single variable.'
+  );
+  lines.push('');
+
+  const renderTable = (rows) => {
+    lines.push('| Name | Type | Default | Description |');
+    lines.push('|------|------|---------|-------------|');
+    for (const entry of rows) {
+      const def = entry.default !== undefined ? `\`${entry.default}\`` : '—';
+      const desc = entry.description.replace(/\|/g, '\\|');
+      lines.push(`| \`${entry.name}\` | ${entry.type} | ${def} | ${desc} |`);
+    }
+    lines.push('');
+  };
+
+  for (const [scope, scopeEntries] of groups) {
+    lines.push(`## ${scopeLabel(scope)}`);
+    lines.push('');
+    renderTable(scopeEntries);
+  }
+
+  if (internal.length > 0) {
+    lines.push('## Internal / testing');
+    lines.push('');
+    lines.push(
+      '> These are plumbing knobs a normal user never sets (hook test bypasses and ' +
+      'defensive stdin caps). `mk env` hides them by default — use `mk env --all`.'
+    );
+    lines.push('');
+    renderTable(internal);
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push(`_${entries.length} variables documented (${internal.length} internal). Run \`mk env\` for live values._`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point: write to disk
+// ---------------------------------------------------------------------------
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const content = renderMarkdown(ENTRIES);
+  writeFileSync(OUT_FILE, content, 'utf8');
+  process.stdout.write(`Written: .claude/env-vars.md (${ENTRIES.length} entries)\n`);
+}

package/src/commands/env.js

@@ -0,0 +1,189 @@
+import { ENTRIES, findByName } from '../lib/env-registry.js';
+import { renderMarkdown } from '../../scripts/gen-env-docs.js';
+
+// ---------------------------------------------------------------------------
+// Scope display labels
+// ---------------------------------------------------------------------------
+
+const SCOPE_LABELS = {
+  'sql-guard': 'SQL Guard',
+  vault: 'Vault Knowledge',
+  cli: 'CLI',
+  auth: 'Auth',
+  team: 'Team Mode',
+  codex: 'Codex',
+};
+
+function scopeLabel(scope) {
+  return SCOPE_LABELS[scope] ?? scope;
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the current runtime value of an env var, or '(unset)'.
+ * If the entry has { secret: true }, redact the value.
+ *
+ * @param {object} entry
+ * @returns {string}
+ */
+function currentValue(entry) {
+  const raw = process.env[entry.name];
+  if (raw === undefined) return '(unset)';
+  if (entry.secret) return '(set — redacted)';
+  return raw;
+}
+
+/**
+ * Format a default value for display.
+ *
+ * @param {string|undefined} def
+ * @param {string} description
+ * @returns {string}
+ */
+function displayDefault(def) {
+  if (def === undefined) return '(none)';
+  return def;
+}
+
+// Column widths for list mode
+const COL_NAME = 32;
+const COL_VALUE = 16;
+
+function padRight(str, width) {
+  return str.length >= width ? str : str + ' '.repeat(width - str.length);
+}
+
+// ---------------------------------------------------------------------------
+// List mode — grouped by scope
+// ---------------------------------------------------------------------------
+
+function listMode(format, showInternal = false) {
+  // By default hide internal/testing vars (hook *_TEST bypasses, *_MAX_STDIN_BYTES
+  // caps) — they are plumbing a user never sets. `--all` shows them.
+  const visible = showInternal ? [...ENTRIES] : ENTRIES.filter((e) => !e.internal);
+  const hiddenCount = ENTRIES.length - visible.length;
+
+  // Group entries by scope, preserving insertion order of first occurrence
+  const groups = new Map();
+  for (const entry of visible) {
+    if (!groups.has(entry.scope)) groups.set(entry.scope, []);
+    groups.get(entry.scope).push(entry);
+  }
+
+  if (format === 'json') {
+    const enriched = visible.map((e) => ({ ...e, current: currentValue(e) }));
+    process.stdout.write(JSON.stringify({ entries: enriched }, null, 2) + '\n');
+    return;
+  }
+
+  // Text mode — sorted scopes for deterministic output
+  const sortedScopes = [...groups.keys()].sort();
+
+  for (const scope of sortedScopes) {
+    const entries = groups.get(scope);
+    process.stdout.write(`${scopeLabel(scope)}\n`);
+
+    for (const entry of entries) {
+      const namePad = padRight(entry.name, COL_NAME);
+      const val = currentValue(entry);
+      const valPad = padRight(val, COL_VALUE);
+      const firstLine = `  ${namePad} ${valPad} ${entry.description}\n`;
+      process.stdout.write(firstLine);
+
+      // Show default on second line if there is one
+      if (entry.default !== undefined) {
+        const indent = ' '.repeat(2 + COL_NAME + 1 + COL_VALUE + 1);
+        process.stdout.write(`${indent}Default: ${entry.default}\n`);
+      }
+    }
+    process.stdout.write('\n');
+  }
+
+  const scopeCount = sortedScopes.length;
+  process.stdout.write(`Run \`mk env <NAME>\` for full details on a single variable.\n`);
+  process.stdout.write(`${visible.length} variables across ${scopeCount} scope${scopeCount === 1 ? '' : 's'}.\n`);
+  if (hiddenCount > 0) {
+    process.stdout.write(`${hiddenCount} internal/testing variable${hiddenCount === 1 ? '' : 's'} hidden — run \`mk env --all\` to show.\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detail mode — single entry
+// ---------------------------------------------------------------------------
+
+function detailMode(name) {
+  const entry = findByName(name);
+  if (!entry) {
+    process.stderr.write(`Unknown env var: ${name}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const val = currentValue(entry);
+  const def = entry.default !== undefined
+    ? entry.default
+    : '(none)';
+
+  process.stdout.write(`${entry.name}\n\n`);
+  process.stdout.write(`  Scope:       ${entry.scope}\n`);
+  process.stdout.write(`  Type:        ${entry.type}\n`);
+  process.stdout.write(`  Applies to:  ${entry.applies_to}\n`);
+  process.stdout.write(`  Default:     ${def}\n`);
+  process.stdout.write(`  Current:     ${val}\n`);
+  if (entry.since) {
+    process.stdout.write(`  Since:       ${entry.since}\n`);
+  }
+  if (entry.internal) {
+    process.stdout.write(`  Internal:    yes (testing/tuning plumbing — not a user setting)\n`);
+  }
+  process.stdout.write(`\n  ${entry.description}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Detail mode with JSON format
+// ---------------------------------------------------------------------------
+
+function detailModeJson(name) {
+  const entry = findByName(name);
+  if (!entry) {
+    process.stderr.write(`Unknown env var: ${name}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(JSON.stringify({ entries: [{ ...entry, current: currentValue(entry) }] }, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// envAction — exported for bin/mk.js and tests
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle 'mk env [name]'.
+ *
+ * @param {string|undefined} name  - Optional env var name for detail mode
+ * @param {{ format?: string }} options
+ */
+export function envAction(name, options = {}) {
+  const format = options.format ?? 'text';
+
+  // --markdown emits the same markdown that `npm run gen:env-docs` writes to disk.
+  // Useful for piping to a file in a user project: `mk env --markdown > ENV.md`.
+  // List mode only — ignores any name argument (markdown is always the full table).
+  if (options.markdown) {
+    process.stdout.write(renderMarkdown(ENTRIES));
+    return;
+  }
+
+  if (name) {
+    if (format === 'json') {
+      detailModeJson(name);
+    } else {
+      detailMode(name);
+    }
+  } else {
+    listMode(format, options.all === true);
+  }
+}

package/src/commands/update.js

@@ -80,9 +80,18 @@ export function redactSecrets(message, ctx = {}) {
     out = out.split(ctx.storedToken).join('[REDACTED-TOKEN]');
   }
 
-  // S3: Redact any GitHub token-shaped substring (belt-and-braces)
+  // S3b: Redact any GitHub token-shaped substring (belt-and-braces)
   out = out.replace(/gh[pousr]_[A-Za-z0-9_]{30,}/g, '[REDACTED-TOKEN]');
 
+  // S5: Redact SQL Server / MSSQL Password= and ODBC Pwd= alias in connection strings
+  out = out.replace(/((?:Password|Pwd)\s*=\s*)([^;]+?)(\s*;|\s*$)/gi, '$1[REDACTED-PASSWORD]$3');
+
+  // S6: Redact PostgreSQL DSN user:pass@ credentials
+  out = out.replace(/(postgres(?:ql)?:\/\/)([^:@/]+):([^@/]+)@/gi, '$1[REDACTED-USER]:[REDACTED-PASSWORD]@');
+
+  // S7: Redact Azure Storage / CosmosDB AccountKey= in connection strings
+  out = out.replace(/(AccountKey\s*=\s*)([^;]+?)(\s*;|\s*$)/gi, '$1[REDACTED-KEY]$3');
+
   return out;
 }
 

package/src/lib/env-registry.js

@@ -0,0 +1,255 @@
+/**
+ * Central registry of all MK_* environment variables recognized by the kit.
+ *
+ * Each entry is frozen and the array itself is frozen.
+ * Consumers: `mk env` CLI subcommand, gen-env-docs.js, selftest drift detector.
+ *
+ * Deliberate omissions:
+ * - MK_VAULT_AUDIT_FLOOR and MK_VAULT_RELAXED are *forbidden* vars (validators_vault.py
+ *   actively rejects any kit file that references them). Documenting them as supported
+ *   configuration would be misleading.
+ * - MK_COMMAND_RE, MK_FM_SCHEMA_*, MK_INIT_RE, MK_PLAN_SKILL_MD, MK_SKILLS, MK_TIER are
+ *   Python module-level constants in selftest scripts, not environment variables.
+ *
+ * If a var is secret-like (e.g. MK_*_TOKEN, MK_*_KEY, MK_*_SECRET) it should carry
+ * { secret: true } and `mk env` will redact its current value. None of the current
+ * vars are secret.
+ *
+ * { internal: true } marks a var as test-only or defensive-tuning plumbing that a
+ * normal user never sets (e.g. hook *_TEST bypasses, *_MAX_STDIN_BYTES caps). These
+ * stay in the registry so drift detection has a complete catalog, but `mk env` hides
+ * them by default (show with `mk env --all`) and the generated doc lists them in a
+ * separate "Internal / testing" section. They remain addressable via `mk env <NAME>`.
+ */
+
+const _RAW = [
+  {
+    name: 'MK_CACHE_DIR',
+    scope: 'vault',
+    default: undefined,
+    description:
+      'Override the cache directory used by vault_probe.py. ' +
+      'Resolution order: MK_CACHE_DIR → $XDG_CACHE_HOME/mk → ~/.cache/mk → OS tempdir.',
+    type: 'path',
+    applies_to: 'skill',
+    since: '0.1.21',
+  },
+  {
+    name: 'MK_DAB_AUDIT_DIR',
+    scope: 'data-api-builder',
+    default: 'docs/dab-audit',
+    description:
+      'Override the directory where dab_audit_writer.py appends the data-api-builder ' +
+      'preflight audit log (dab-audit-YYYY-MM-DD.jsonl). Defaults to docs/dab-audit, ' +
+      'relative to invocation cwd. Set to redirect logs to an artefact store in CI. ' +
+      'Mirrors MK_SECURITY_AUDIT_DIR.',
+    type: 'path',
+    applies_to: 'skill',
+    since: '0.1.33',
+  },
+  {
+    name: 'MK_DAB_BASH_GUARD_MAX_STDIN_BYTES',
+    internal: true,
+    scope: 'data-api-builder',
+    default: '1048576',
+    description:
+      'Maximum stdin bytes the dab-bash-guard hook (Gate 4) reads before failing open ' +
+      '(allowing the command to proceed). Default is 1 048 576 bytes (1 MB).',
+    type: 'integer',
+    applies_to: 'hook',
+    since: '0.1.34',
+  },
+  {
+    name: 'MK_DAB_BASH_GUARD_TEST',
+    internal: true,
+    scope: 'data-api-builder',
+    default: undefined,
+    description:
+      'When set to "1", dab-bash-guard.cjs returns early at module load without executing the ' +
+      'stdin pipeline. Used exclusively by hook unit tests; do not set in production.',
+    type: 'boolean',
+    applies_to: 'hook',
+    since: '0.1.34',
+  },
+  {
+    name: 'MK_DAB_BASH_OK',
+    scope: 'data-api-builder',
+    default: undefined,
+    description:
+      'Opt-out override: when set to "1", allows Bash invocations of a DB CLI ' +
+      '(sqlcmd/psql/mysql/mssql-cli/mongosh/bcp/cqlsh) with query intent that the dab-bash-guard ' +
+      'hook (Gate 4) otherwise blocks. Set only for deliberate DB administration; prefer the ' +
+      'data-api-builder MCP tools.',
+    type: 'boolean',
+    applies_to: 'hook',
+    since: '0.1.34',
+  },
+  {
+    name: 'MK_DAB_MCP_GUARD_MAX_STDIN_BYTES',
+    internal: true,
+    scope: 'data-api-builder',
+    default: '1048576',
+    description:
+      'Maximum stdin bytes the dab-mcp-guard hook (Gate 1) reads before failing open ' +
+      '(allowing the call to proceed). Default is 1 048 576 bytes (1 MB).',
+    type: 'integer',
+    applies_to: 'hook',
+    since: '0.1.34',
+  },
+  {
+    name: 'MK_DAB_MCP_GUARD_TEST',
+    internal: true,
+    scope: 'data-api-builder',
+    default: undefined,
+    description:
+      'When set to "1", dab-mcp-guard.cjs skips main() at module load. Used exclusively by hook ' +
+      'unit tests; do not set in production.',
+    type: 'boolean',
+    applies_to: 'hook',
+    since: '0.1.34',
+  },
+  {
+    name: 'MK_DAB_WRITES_OK',
+    scope: 'data-api-builder',
+    default: undefined,
+    description:
+      'Opt-out override: when set to "1", allows the four write-capable data-api-builder MCP ' +
+      'calls (create_record/update_record/delete_record/execute_entity) that the dab-mcp-guard ' +
+      'hook (Gate 1) otherwise blocks. Set only for deliberate writes; DAB role config remains ' +
+      'as defence-in-depth.',
+    type: 'boolean',
+    applies_to: 'hook',
+    since: '0.1.34',
+  },
+  {
+    name: 'MK_FORCE_NO_TOOL_DIR',
+    internal: true,
+    scope: 'codex',
+    default: undefined,
+    description:
+      'When set to "1", convert-agents-to-codex.js aborts with exit 1 (simulates a missing ' +
+      'TOOL_DIR_NAME constant). Used exclusively in integration tests; do not set in production.',
+    type: 'boolean',
+    applies_to: 'cli',
+    since: '0.1.22',
+  },
+  {
+    name: 'MK_INTROSPECT_MAX_NOTES',
+    scope: 'vault',
+    default: undefined,
+    description:
+      'Maximum number of vault notes vault_introspect.py will enumerate before stopping. ' +
+      'Prevents runaway scanning on large vaults. Must be a positive integer.',
+    type: 'integer',
+    applies_to: 'skill',
+    since: '0.1.21',
+  },
+  {
+    name: 'MK_OAUTH_SCOPE',
+    scope: 'auth',
+    default: 'repo',
+    description:
+      'GitHub OAuth scope requested during the device flow. Defaults to "repo" (required to ' +
+      'access the private kit repository). Override only for testing or alternative scopes.',
+    type: 'string',
+    applies_to: 'cli',
+    since: '0.1.0',
+  },
+  {
+    name: 'MK_SQL_GUARD_ALLOWLIST',
+    scope: 'sql-guard',
+    default: '.claude/sql-guard.allowlist',
+    description:
+      'Path to the SQL guard allowlist file (kit-root-relative or absolute). ' +
+      'Used by sql-allowlist.cjs to load the list of approved SQL patterns.',
+    type: 'path',
+    applies_to: 'hook',
+    since: '0.1.26',
+  },
+  {
+    name: 'MK_SQL_GUARD_MAX_STDIN_BYTES',
+    internal: true,
+    scope: 'sql-guard',
+    default: '1048576',
+    description:
+      'Maximum stdin bytes the sql-guard hook will read before failing open (allowing the ' +
+      'command to proceed). Default is 1 048 576 bytes (1 MB). Increase for large queries.',
+    type: 'integer',
+    applies_to: 'hook',
+    since: '0.1.26',
+  },
+  {
+    name: 'MK_SQL_GUARD_TEST',
+    internal: true,
+    scope: 'sql-guard',
+    default: undefined,
+    description:
+      'When set to "1", sql-guard.cjs returns early at module load without executing the ' +
+      'stdin pipeline. Used exclusively by hook unit tests; do not set in production.',
+    type: 'boolean',
+    applies_to: 'hook',
+    since: '0.1.26',
+  },
+  {
+    name: 'MK_TEAM_MAX_ITERATIONS',
+    scope: 'team',
+    default: '8',
+    description:
+      'Maximum agent-team loop iterations enforced by loop-detector.js before the loop is ' +
+      'terminated. Applies to --team mode in mk-implement and mk-review.',
+    type: 'integer',
+    applies_to: 'skill',
+    since: '0.1.15',
+  },
+  {
+    name: 'MK_VAULT_CACHE_REBUILD',
+    scope: 'vault',
+    default: undefined,
+    description:
+      'When set to "1", vault_retrieval_plan.py ignores any cached retrieval plan and ' +
+      'rebuilds it from scratch. Useful after vault restructuring.',
+    type: 'boolean',
+    applies_to: 'skill',
+    since: '0.1.21',
+  },
+  {
+    name: 'MK_VAULT_ENABLED',
+    scope: 'vault',
+    default: undefined,
+    description:
+      'Privacy-by-default opt-in gate. Set to "1" to enable Obsidian vault consultation ' +
+      'across mk-* skills and agents. Any other value (or unset) means vault access is disabled.',
+    type: 'boolean',
+    applies_to: 'skill',
+    since: '0.1.21',
+  },
+  {
+    name: 'MK_VERBOSE',
+    scope: 'cli',
+    default: undefined,
+    description:
+      'When set to "1", enables verbose output in mk update and the Codex converters ' +
+      '(per-file change enumeration, routine warnings, long-path warnings). ' +
+      'Equivalent to passing --verbose on mk update.',
+    type: 'boolean',
+    applies_to: 'cli',
+    since: '0.1.25',
+  },
+];
+
+/**
+ * Frozen array of all known MK_* environment variables.
+ * @type {ReadonlyArray<{name:string,scope:string,default:string|undefined,description:string,type:string,applies_to:string,since?:string}>}
+ */
+export const ENTRIES = Object.freeze(_RAW.map(Object.freeze));
+
+/**
+ * Look up a registry entry by exact variable name.
+ *
+ * @param {string|undefined} name
+ * @returns {{ name:string, scope:string, default:string|undefined, description:string, type:string, applies_to:string, since?:string } | undefined}
+ */
+export function findByName(name) {
+  if (typeof name !== 'string') return undefined;
+  return ENTRIES.find((e) => e.name === name);
+}