mova-claude-import 0.1.1

package/test/export_zip_determinism.test.js

@@ -0,0 +1,41 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+async function readExportManifest(outDir) {
+  const p = path.join(outDir, "mova", "claude_import", "v0", "export_manifest_v0.json");
+  const raw = await fs.readFile(p, "utf8");
+  return JSON.parse(raw);
+}
+
+test("zip export is deterministic across runs", async () => {
+  const tmp = path.join(process.cwd(), ".tmp_test_zip");
+  const proj = path.join(tmp, "proj");
+  const out1 = path.join(tmp, "out1");
+  const out2 = path.join(tmp, "out2");
+  await fs.rm(tmp, { recursive: true, force: true });
+  await fs.mkdir(path.join(proj, ".claude", "skills"), { recursive: true });
+
+  await fs.writeFile(path.join(proj, "CLAUDE.md"), "Hello\n", "utf8");
+  await fs.writeFile(path.join(proj, ".mcp.json"), "{\"servers\":[]}", "utf8");
+  await fs.writeFile(path.join(proj, ".claude", "skills", "a.md"), "# skill\n", "utf8");
+
+  await execFileP("node", ["dist/cli.js", "--project", proj, "--out", out1, "--zip"]);
+  await execFileP("node", ["dist/cli.js", "--project", proj, "--out", out2, "--zip"]);
+
+  const manifest1 = await readExportManifest(out1);
+  const manifest2 = await readExportManifest(out2);
+
+  assert.equal(manifest1.zip_sha256, manifest2.zip_sha256);
+
+  const zip1 = path.join(out1, manifest1.zip_rel_path);
+  await fs.stat(zip1);
+
+  assert.ok(manifest1.files.includes("CLAUDE.md"));
+  assert.ok(manifest1.files.includes(".claude/settings.json"));
+});

package/test/import_determinism.test.js

@@ -0,0 +1,53 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+async function listFilesRec(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const e of entries) {
+      const abs = path.join(current, e.name);
+      if (e.isDirectory()) stack.push(abs);
+      else if (e.isFile()) out.push(abs);
+    }
+  }
+  return out;
+}
+
+async function readOutputSnapshot(root) {
+  const files = await listFilesRec(root);
+  const snapshot = {};
+  for (const abs of files) {
+    const rel = path.relative(root, abs).replace(/\\/g, "/");
+    snapshot[rel] = await fs.readFile(abs, "utf8");
+  }
+  return JSON.stringify(snapshot, Object.keys(snapshot).sort(), 2);
+}
+
+test("import is deterministic for same inputs", async () => {
+  const tmp = path.join(process.cwd(), ".tmp_test");
+  const proj = path.join(tmp, "proj");
+  const out = path.join(tmp, "out");
+  await fs.rm(tmp, { recursive: true, force: true });
+  await fs.mkdir(path.join(proj, ".claude", "skills"), { recursive: true });
+
+  await fs.writeFile(path.join(proj, "CLAUDE.md"), "Hello\n", "utf8");
+  await fs.writeFile(path.join(proj, ".mcp.json"), "{\"servers\":[]}", "utf8");
+  await fs.writeFile(path.join(proj, ".claude", "skills", "a.md"), "# skill\n", "utf8");
+
+  await execFileP("node", ["dist/cli.js", "--project", proj, "--out", out]);
+  const snapshot1 = await readOutputSnapshot(out);
+
+  await execFileP("node", ["dist/cli.js", "--project", proj, "--out", out]);
+  const snapshot2 = await readOutputSnapshot(out);
+
+  assert.equal(snapshot1, snapshot2);
+});

package/test/init_v0.test.js

@@ -0,0 +1,37 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+async function assertExists(p) {
+  try {
+    await fs.stat(p);
+  } catch {
+    assert.fail(`Expected file to exist: ${p}`);
+  }
+}
+
+test("init v0 creates profile scaffold and optional zip", async () => {
+  const tmp = path.join(process.cwd(), ".tmp_test_init");
+  const out = path.join(tmp, "out");
+  await fs.rm(tmp, { recursive: true, force: true });
+  await fs.mkdir(out, { recursive: true });
+
+  await execFileP("node", ["dist/cli.js", "init", "--out", out, "--zip"]);
+
+  await assertExists(path.join(out, "CLAUDE.md"));
+  await assertExists(path.join(out, ".claude", "settings.json"));
+  await assertExists(path.join(out, ".claude", "skills", "mova-layer-v0", "SKILL.md"));
+
+  const initManifestPath = path.join(out, "mova", "claude_import", "v0", "init_manifest_v0.json");
+  const initManifest = JSON.parse(await fs.readFile(initManifestPath, "utf8"));
+  assert.equal(initManifest.profile_version, "v0");
+  assert.ok(initManifest.zip_sha256);
+  assert.ok(initManifest.zip_rel_path);
+
+  await assertExists(path.join(out, initManifest.zip_rel_path));
+});

package/test/overlay_v0_output.test.js

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+async function assertExists(p) {
+  try {
+    await fs.stat(p);
+  } catch {
+    assert.fail(`Expected file to exist: ${p}`);
+  }
+}
+
+test("overlay v0 files are emitted and CLAUDE entry exists", async () => {
+  const tmp = path.join(process.cwd(), ".tmp_test_overlay");
+  const proj = path.join(tmp, "proj");
+  const out = path.join(tmp, "out");
+  await fs.rm(tmp, { recursive: true, force: true });
+  await fs.mkdir(path.join(proj, ".claude", "skills"), { recursive: true });
+
+  await fs.writeFile(path.join(proj, "CLAUDE.md"), "Hello\n", "utf8");
+  await fs.writeFile(path.join(proj, ".mcp.json"), "{\"servers\":[]}", "utf8");
+  await fs.writeFile(path.join(proj, ".claude", "skills", "a.md"), "# skill\n", "utf8");
+
+  await execFileP("node", ["dist/cli.js", "--project", proj, "--out", out]);
+
+  await assertExists(path.join(out, ".claude", "commands", "mova_context.md"));
+  await assertExists(path.join(out, ".claude", "commands", "mova_proof.md"));
+  await assertExists(path.join(out, ".claude", "skills", "mova-control-v0", "SKILL.md"));
+
+  const claudePath = path.join(out, "CLAUDE.md");
+  const claude = await fs.readFile(claudePath, "utf8");
+  assert.ok(claude.includes("MOVA_CONTROL_ENTRY_V0"));
+});

package/test/profile_v0_output.test.js

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+async function assertExists(p) {
+  try {
+    await fs.stat(p);
+  } catch {
+    assert.fail(`Expected file to exist: ${p}`);
+  }
+}
+
+test("profile v0 output includes required files", async () => {
+  const tmp = path.join(process.cwd(), ".tmp_test_profile");
+  const proj = path.join(tmp, "proj");
+  const out = path.join(tmp, "out");
+  await fs.rm(tmp, { recursive: true, force: true });
+  await fs.mkdir(path.join(proj, ".claude", "skills"), { recursive: true });
+
+  await fs.writeFile(path.join(proj, "CLAUDE.md"), "Hello\n", "utf8");
+  await fs.writeFile(path.join(proj, ".mcp.json"), "{\"servers\":[]}", "utf8");
+  await fs.writeFile(path.join(proj, ".claude", "skills", "a.md"), "# skill\n", "utf8");
+
+  await execFileP("node", ["dist/cli.js", "--project", proj, "--out", out]);
+
+  await assertExists(path.join(out, "CLAUDE.md"));
+  await assertExists(path.join(out, "MOVA.md"));
+  await assertExists(path.join(out, ".claude", "settings.json"));
+  await assertExists(path.join(out, ".claude", "commands", "mova_context.md"));
+  await assertExists(path.join(out, ".claude", "commands", "mova_lint.md"));
+  await assertExists(path.join(out, ".claude", "skills", "mova-layer-v0", "SKILL.md"));
+  await assertExists(path.join(out, "mova", "claude_import", "v0", "lint_report_v0.json"));
+  const versionPath = path.join(out, "mova", "claude_import", "v0", "VERSION.json");
+  await assertExists(versionPath);
+  const version = JSON.parse(await fs.readFile(versionPath, "utf8"));
+  assert.equal(version.tool_name, "mova-claude-import");
+  assert.ok(version.tool_version);
+  assert.equal(version.profile_version, "anthropic_profile_v0");
+});

package/test/scaffold_v0_output.test.js

@@ -0,0 +1,64 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+async function assertExists(p) {
+  try {
+    await fs.stat(p);
+  } catch {
+    assert.fail(`Expected file to exist: ${p}`);
+  }
+}
+
+test("init creates full scaffold surfaces", async () => {
+  const tmp = path.join(process.cwd(), ".tmp_test_scaffold");
+  const out = path.join(tmp, "out");
+  await fs.rm(tmp, { recursive: true, force: true });
+  await fs.mkdir(out, { recursive: true });
+
+  await execFileP("node", ["dist/cli.js", "init", "--out", out]);
+
+  await assertExists(path.join(out, "CLAUDE.md"));
+  await assertExists(path.join(out, ".claude", "settings.json"));
+  await assertExists(path.join(out, ".claude", "settings.local.example.json"));
+  await assertExists(path.join(out, ".claude", "commands", "example_command.md"));
+  await assertExists(path.join(out, ".claude", "agents", "example_agent.md"));
+  await assertExists(path.join(out, ".claude", "output-styles", "example_style.md"));
+  await assertExists(path.join(out, ".claude", "hooks", "example_hook.sh"));
+  await assertExists(path.join(out, ".mcp.json"));
+});
+
+test("control apply creates missing surfaces without erasing content", async () => {
+  const tmp = path.join(process.cwd(), ".tmp_test_scaffold_apply");
+  const proj = path.join(tmp, "proj");
+  const out = path.join(tmp, "out");
+  const profile = path.join(process.cwd(), "fixtures", "pos", "control_profile_filled", "claude_control_profile_v0.json");
+  await fs.rm(tmp, { recursive: true, force: true });
+  await fs.mkdir(proj, { recursive: true });
+  await fs.writeFile(path.join(proj, "CLAUDE.md"), "Custom\n", "utf8");
+
+  await execFileP("node", [
+    "dist/cli.js",
+    "control",
+    "apply",
+    "--project",
+    proj,
+    "--profile",
+    profile,
+    "--mode",
+    "apply",
+    "--out",
+    out,
+  ]);
+
+  const claude = await fs.readFile(path.join(proj, "CLAUDE.md"), "utf8");
+  assert.ok(claude.includes("Custom"));
+  assert.ok(claude.includes("MOVA_CONTROL_ENTRY_V0"));
+  await assertExists(path.join(proj, ".claude", "settings.json"));
+  await assertExists(path.join(proj, ".claude", "commands", "example_command.md"));
+});

package/test/strict_input_policy.test.js

@@ -0,0 +1,45 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+async function assertExists(p) {
+  try {
+    await fs.stat(p);
+  } catch {
+    assert.fail(`Expected file to exist: ${p}`);
+  }
+}
+
+test("strict input policy denies local settings and stops rebuild", async () => {
+  const out = path.join(process.cwd(), ".tmp_test_strict");
+  await fs.rm(out, { recursive: true, force: true });
+  await fs.mkdir(out, { recursive: true });
+
+  const proj = path.join(process.cwd(), "fixtures", "neg", "strict_denied_local");
+  let exitCode = 0;
+  try {
+    await execFileP("node", ["dist/cli.js", "--project", proj, "--out", out, "--strict"]);
+  } catch (err) {
+    exitCode = err?.code ?? 1;
+  }
+
+  assert.equal(exitCode, 2);
+
+  const reportPath = path.join(out, "mova", "claude_import", "v0", "input_policy_report_v0.json");
+  await assertExists(reportPath);
+  const report = JSON.parse(await fs.readFile(reportPath, "utf8"));
+  assert.equal(report.ok, false);
+
+  let claudeExists = true;
+  try {
+    await fs.stat(path.join(out, "CLAUDE.md"));
+  } catch {
+    claudeExists = false;
+  }
+  assert.equal(claudeExists, false);
+});

package/tools/demo_v0.mjs

@@ -0,0 +1,98 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+function sha256(text) {
+  return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+async function exists(p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function run(cmd, args, cwd) {
+  await execFileP(cmd, args, { cwd });
+}
+
+async function main() {
+  const repoRoot = process.cwd();
+  const demoRoot = path.join(repoRoot, ".tmp_demo");
+  const proj = path.join(demoRoot, "proj");
+  const out = path.join(demoRoot, "out");
+
+  await fs.rm(demoRoot, { recursive: true, force: true });
+  await fs.mkdir(demoRoot, { recursive: true });
+
+  const nodeCmd = process.platform === "win32" ? "node.exe" : "node";
+  const cli = path.join(repoRoot, "dist", "cli.js");
+
+  await run(nodeCmd, [cli, "init", "--out", proj], repoRoot);
+  await run(nodeCmd, [cli, "control", "prefill", "--project", proj, "--out", proj], repoRoot);
+
+  const exampleProfile = path.join(repoRoot, "examples", "control_profile_min.json");
+  const profilePath = path.join(proj, "claude_control_profile_v0.json");
+  const exampleRaw = await fs.readFile(exampleProfile, "utf8");
+  await fs.writeFile(profilePath, exampleRaw, "utf8");
+
+  await run(nodeCmd, [cli, "control", "check", "--project", proj, "--profile", profilePath, "--out", proj], repoRoot);
+  await run(nodeCmd, [cli, "control", "apply", "--project", proj, "--profile", profilePath, "--out", proj, "--mode", "apply"], repoRoot);
+  await run(nodeCmd, [cli, "--project", proj, "--out", out, "--zip", "--strict=false"], repoRoot);
+
+  const runsDir = path.join(proj, "mova", "claude_control", "v0", "runs");
+  const runDirs = (await exists(runsDir)) ? await fs.readdir(runsDir) : [];
+  runDirs.sort();
+  let latestCheckSource = "";
+  let latestApplySource = "";
+  for (const dir of runDirs) {
+    const check = path.join(runsDir, dir, "control_summary_v0.json");
+    const apply = path.join(runsDir, dir, "control_apply_report_v0.json");
+    if (await exists(check)) latestCheckSource = check;
+    if (await exists(apply)) latestApplySource = apply;
+  }
+  const latestCheck = path.join(runsDir, "latest_check_summary.json");
+  const latestApply = path.join(runsDir, "latest_apply_report.json");
+  if (latestCheckSource) await fs.writeFile(latestCheck, await fs.readFile(latestCheckSource));
+  if (latestApplySource) await fs.writeFile(latestApply, await fs.readFile(latestApplySource));
+
+  const runId = sha256([proj, out, exampleRaw].join("|")).slice(0, 16);
+  const artifactsDir = path.join(repoRoot, "artifacts", "demo_v0", runId);
+  await fs.mkdir(artifactsDir, { recursive: true });
+
+  const exportManifest = path.join(out, "mova", "claude_import", "v0", "export_manifest_v0.json");
+  let zipPath = "";
+  if (await exists(exportManifest)) {
+    const exportObj = JSON.parse(await fs.readFile(exportManifest, "utf8"));
+    if (exportObj?.zip_rel_path) {
+      zipPath = path.join(out, exportObj.zip_rel_path);
+    }
+  }
+  const controlRunsDir = path.join(proj, "mova", "claude_control", "v0", "runs");
+  const report = {
+    input_project: proj,
+    output_path: out,
+    zip_path: zipPath,
+    refs: {
+      manifest: path.join(out, "mova", "claude_import", "v0", "import_manifest.json"),
+      export_manifest: exportManifest,
+      control_runs_dir: controlRunsDir,
+      control_check_summary: path.join(controlRunsDir, "latest_check_summary.json"),
+      control_apply_report: path.join(controlRunsDir, "latest_apply_report.json"),
+    },
+  };
+
+  await fs.writeFile(path.join(artifactsDir, "demo_report_v0.json"), JSON.stringify(report, null, 2) + "\n", "utf8");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/tools/deps_audit_v0.mjs

@@ -0,0 +1,123 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const TARGET_DEPS = ["@leryk1981/mova-spec", "@leryk1981/mova-core-engine"];
+
+async function listFilesRec(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const e of entries) {
+      const abs = path.join(current, e.name);
+      if (e.isDirectory()) stack.push(abs);
+      else if (e.isFile()) out.push(abs);
+    }
+  }
+  return out;
+}
+
+function sha256Strings(items) {
+  const h = crypto.createHash("sha256");
+  for (const item of items) h.update(item);
+  return h.digest("hex").slice(0, 16);
+}
+
+function importMatches(content, dep) {
+  const variants = [dep, `${dep}/package.json`];
+  return variants.some((variant) => {
+    const esc = variant.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const importRe = new RegExp(`from\\s+["']${esc}["']|import\\s+["']${esc}["']`, "g");
+    const requireRe = new RegExp(`require\\(\\s*["']${esc}["']\\s*\\)`, "g");
+    const resolveRe = new RegExp(`require\\.resolve\\(\\s*["']${esc}["']\\s*\\)`, "g");
+    return importRe.test(content) || requireRe.test(content) || resolveRe.test(content);
+  });
+}
+
+function usageHintsCoreEngine(content) {
+  return /EvidenceWriter|EpisodeWriter|PolicyEngine/.test(content);
+}
+
+function usageHintsSpec(content) {
+  const hasSpec = /mova-spec/.test(content);
+  const hasResolver = /createRequire|require\.resolve|import\.meta\.resolve/.test(content);
+  const hasSchemas = /schemas/.test(content);
+  return hasSpec && (hasResolver || hasSchemas);
+}
+
+async function main() {
+  const repoRoot = process.cwd();
+  const pkg = JSON.parse(await fs.readFile(path.join(repoRoot, "package.json"), "utf8"));
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+
+  const srcRoot = path.join(repoRoot, "src");
+  const files = (await listFilesRec(srcRoot)).filter((p) => p.endsWith(".ts"));
+  files.sort();
+
+  const fileContents = [];
+  const contentByFile = new Map();
+  for (const file of files) {
+    const content = await fs.readFile(file, "utf8");
+    const rel = path.relative(repoRoot, file).replace(/\\/g, "/");
+    contentByFile.set(rel, content);
+    fileContents.push(`${rel}\n${content}\n`);
+  }
+  const runId = sha256Strings(fileContents);
+
+  const foundImports = {};
+  const foundUsageHints = {};
+  const recommendations = [];
+
+  for (const dep of TARGET_DEPS) {
+    const importFiles = [];
+    const usageFiles = [];
+    for (const [rel, content] of contentByFile.entries()) {
+      if (importMatches(content, dep)) importFiles.push(rel);
+      if (dep.endsWith("mova-core-engine") && usageHintsCoreEngine(content)) usageFiles.push(rel);
+      if (dep.endsWith("mova-spec") && usageHintsSpec(content)) usageFiles.push(rel);
+    }
+    importFiles.sort();
+    usageFiles.sort();
+    foundImports[dep] = importFiles;
+    foundUsageHints[dep] = usageFiles;
+
+    if (deps[dep] && importFiles.length === 0) {
+      recommendations.push(`Add import usage for ${dep}.`);
+    }
+    if (deps[dep] && usageFiles.length === 0) {
+      recommendations.push(`Add real usage hints for ${dep}.`);
+    }
+    if (!deps[dep]) {
+      recommendations.push(`Add ${dep} to dependencies.`);
+    }
+  }
+
+  const ok =
+    TARGET_DEPS.every((dep) => deps[dep]) &&
+    TARGET_DEPS.every((dep) => foundImports[dep].length > 0) &&
+    TARGET_DEPS.every((dep) => foundUsageHints[dep].length > 0);
+
+  const report = {
+    ok,
+    found_imports: foundImports,
+    found_usage_hints: foundUsageHints,
+    recommendations,
+  };
+
+  const outDir = path.join(repoRoot, "artifacts", "deps_audit", runId);
+  await fs.mkdir(outDir, { recursive: true });
+  await fs.writeFile(
+    path.join(outDir, "deps_audit_report_v0.json"),
+    JSON.stringify(report, null, 2) + "\n",
+    "utf8"
+  );
+
+  process.exit(ok ? 0 : 2);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(2);
+});

package/tools/write_mova_spec_bindings_v0.mjs

@@ -0,0 +1,122 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const CHECK_MODE = process.argv.includes("--check");
+const REPO_ROOT = process.cwd();
+const BINDINGS_PATH = path.join(REPO_ROOT, "src", "mova_spec_bindings_v0.ts");
+const OUT_MD = path.join(REPO_ROOT, "docs", "MOVA_SPEC_BINDINGS.md");
+const OUT_JSON = path.join(REPO_ROOT, "docs", "MOVA_SPEC_BINDINGS.json");
+
+function parseBindings(source) {
+  const ids = {};
+  const re = /(\w+_id)\s*:\s*["']([^"']+)["']/g;
+  let match;
+  while ((match = re.exec(source))) {
+    ids[match[1]] = match[2];
+  }
+  return ids;
+}
+
+async function listSchemas(specRoot) {
+  const schemasRoot = path.join(specRoot, "schemas");
+  const out = [];
+  const stack = [schemasRoot];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const e of entries) {
+      const abs = path.join(current, e.name);
+      if (e.isDirectory()) stack.push(abs);
+      else if (e.isFile() && e.name.endsWith(".json")) out.push(abs);
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const require = createRequire(import.meta.url);
+  const specPkgPath = require.resolve("@leryk1981/mova-spec/package.json");
+  const specRoot = path.dirname(specPkgPath);
+  const specPkg = JSON.parse(await fs.readFile(specPkgPath, "utf8"));
+  const specVersion = specPkg.version ?? "unknown";
+
+  const bindingsSource = await fs.readFile(BINDINGS_PATH, "utf8");
+  const bindings = parseBindings(bindingsSource);
+  const categories = [
+    ["instruction_profile", "instruction_profile_id"],
+    ["mcp_servers", "mcp_servers_id"],
+    ["core_schema", "core_schema_id"],
+  ];
+
+  const selected = {};
+  for (const [label, key] of categories) {
+    const id = bindings[key];
+    if (!id) {
+      console.error(`Missing binding key: ${key}`);
+      process.exit(2);
+    }
+    selected[label] = id;
+  }
+
+  const schemaFiles = await listSchemas(specRoot);
+  const idToPath = new Map();
+  for (const file of schemaFiles) {
+    const raw = await fs.readFile(file, "utf8");
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed?.$id) {
+        const rel = path.relative(specRoot, file).replace(/\\/g, "/");
+        idToPath.set(parsed.$id, rel);
+      }
+    } catch {
+      // ignore invalid schema files
+    }
+  }
+
+  const rows = categories.map(([label]) => {
+    const id = selected[label];
+    const filePath = idToPath.get(id) ?? "UNRESOLVED";
+    return { category: label, schema_id: id, file_path: filePath };
+  });
+
+  const jsonOut = {
+    spec_version: specVersion,
+    bindings: rows,
+    selection_rule: "Bound to MOVA_SPEC_BINDINGS_V0 used by run_import.ts",
+  };
+
+  const mdLines = [
+    "# MOVA Spec Bindings v0",
+    "",
+    `Spec version: ${specVersion}`,
+    "",
+    "| Category | Chosen schema $id | File path |",
+    "| --- | --- | --- |",
+    ...rows.map((r) => `| ${r.category} | ${r.schema_id} | ${r.file_path} |`),
+    "",
+    "Selection rule: Bound to `MOVA_SPEC_BINDINGS_V0` used by `src/run_import.ts`.",
+    "",
+  ];
+
+  if (CHECK_MODE) {
+    const currentMd = await fs.readFile(OUT_MD, "utf8");
+    const currentJson = await fs.readFile(OUT_JSON, "utf8");
+    const nextMd = mdLines.join("\n");
+    const nextJson = JSON.stringify(jsonOut, null, 2) + "\n";
+    if (currentMd !== nextMd || currentJson !== nextJson) {
+      console.error("Bindings docs are out of date.");
+      process.exit(2);
+    }
+    process.exit(0);
+  }
+
+  await fs.mkdir(path.dirname(OUT_MD), { recursive: true });
+  await fs.writeFile(OUT_MD, mdLines.join("\n"), "utf8");
+  await fs.writeFile(OUT_JSON, JSON.stringify(jsonOut, null, 2) + "\n", "utf8");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(2);
+});