0xray 4.0.1 → 4.0.2

package/scripts/foundry/release-gate.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * release-gate.mjs — Single release checkpoint.
+ *
+ * Modes:
+ *   (default)     build + test + consumer smoke (fresh + upgrade merge)
+ *   --verify-only git + reconcile + release docs + consumer smoke — after push, before publish
+ *   --skip-smoke  skip consumer install smoke
+ *   --skip-docs   skip release docs validation (not recommended for publish)
+ *
+ * Usage:
+ *   npx @0xray/foundry gate
+ *   npx @0xray/foundry gate --verify-only
+ */
+
+import { execSync } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+import { isXrayExoRepo, millScript, readRootPackage, resolveMillRoot } from "./mill-root.mjs";
+
+const rootDir = resolveMillRoot();
+const verifyOnly = process.argv.includes("--verify-only");
+const skipSmoke = process.argv.includes("--skip-smoke");
+const skipDocs = process.argv.includes("--skip-docs");
+
+function step(label, cmd) {
+  console.log(`\n${"─".repeat(60)}\n🔄 ${label}\n${"─".repeat(60)}\n`);
+  execSync(cmd, { cwd: rootDir, stdio: "inherit", env: { ...process.env, FOUNDRY_ROOT: rootDir } });
+}
+
+function docsCheckCmd() {
+  return `${JSON.stringify(process.execPath)} ${JSON.stringify(millScript("validate-release-docs.mjs"))}`;
+}
+
+function runLightGate() {
+  const pkg = readRootPackage(rootDir);
+  if (verifyOnly) {
+    if (!skipDocs) step("1/1 Release docs (light)", docsCheckCmd());
+    return;
+  }
+  if (pkg.scripts.build) step("1/3 Build", "npm run build");
+  if (pkg.scripts.test) step("2/3 Tests", "npm test");
+  if (!skipDocs) step("3/3 Release docs (light)", docsCheckCmd());
+}
+
+function main() {
+  const mode = verifyOnly ? "verify" : "full";
+  console.log("\n╔════════════════════════════════════════════════════════╗");
+  console.log(`║        🛡️  0xRay Release Gate (${mode})`.padEnd(57) + "║");
+  console.log("╚════════════════════════════════════════════════════════╝");
+
+  try {
+    if (!isXrayExoRepo(rootDir)) {
+      runLightGate();
+    } else if (verifyOnly) {
+      step("1/5 Git + reconcile", "node scripts/node/pre-publish-guard.js --verify-only");
+      if (!skipDocs) {
+        step("2/5 Release docs", docsCheckCmd());
+      }
+      step(
+        "3/5 Plugin infrastructure",
+        "node scripts/test/validate-plugins-e2e.cjs --structural-only",
+      );
+      if (!skipSmoke) {
+        step("4/5 Consumer install smoke", "node scripts/node/consumer-install-smoke.mjs");
+      }
+    } else {
+      step("1/7 Build", "npm run build");
+      step("2/7 Tests", "npm test");
+      if (!skipDocs) {
+        step("3/7 Release docs", docsCheckCmd());
+      }
+      step(
+        "4/7 Consumer hook verifiers",
+        "npm run verify:pre-commit-diff && npm run verify:pre-push-diff && node scripts/mjs/verify-delegation-gate-core.mjs --host=grok && node scripts/mjs/verify-delegation-gate-core.mjs --host=hermes && node scripts/mjs/verify-delegation-gate-core.mjs --host=opencode && node scripts/mjs/verify-hermes-session-start.mjs && node scripts/mjs/verify-confer-core.mjs && npm run verify:user-aside && npm run build && node scripts/mjs/verify-pipeline-facets.mjs --package-only",
+      );
+      step(
+        "5/7 Plugin infrastructure",
+        "node scripts/test/validate-plugins-e2e.cjs --structural-only",
+      );
+      if (!skipSmoke) {
+        step("6/7 Consumer install smoke (fresh + upgrade)", "node scripts/node/consumer-install-smoke.mjs");
+      }
+    }
+
+    console.log("\n╔════════════════════════════════════════════════════════╗");
+    console.log("║  ✅ RELEASE GATE PASSED                                ║");
+    console.log("╚════════════════════════════════════════════════════════╝\n");
+  } catch {
+    console.error("\n❌ RELEASE GATE FAILED — do not tag or publish\n");
+    process.exit(1);
+  }
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main();
+}

package/scripts/foundry/release.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+
+/**
+ * Canonical 0xRay release script.
+ *
+ * 1. Bump version from npm registry baseline (reconcile-version)
+ * 2. Release artifacts (CHANGELOG / README / AGENTS / docs) — before gate so docs tests pass
+ * 3. Release gate (build + test + consumer smoke)
+ * 4. Commit release artifacts → push
+ * 5. Verify gate (reconcile + git + release docs + smoke)
+ * 6. npm publish (idempotent — skip if version already on registry)
+ * 7. Tag → push tag (only after successful publish)
+ *
+ * Usage:
+ *   npx @0xray/foundry release [patch|minor|major] --dry-run
+ *   npx @0xray/foundry release [patch|minor|major] --i-mean-it
+ *   npx @0xray/foundry release --publish-only --dry-run
+ *   npx @0xray/foundry release --publish-only --i-mean-it
+ *
+ * Live bump/commit/push/publish requires --i-mean-it or FOUNDRY_RELEASE=1.
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { getReleaseArtifactPaths } from "./version-manager.mjs";
+import {
+  isXrayExoRepo,
+  millScript,
+  readRootPackage,
+  resolveMillRoot,
+} from "./mill-root.mjs";
+
+const rootDir = resolveMillRoot();
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const publishOnly = args.includes("--publish-only");
+const releaseType = args.find((a) => ["major", "minor", "patch"].includes(a));
+const optedIn = args.includes("--i-mean-it") || process.env.FOUNDRY_RELEASE === "1";
+
+function writeReleaseTrap() {
+  process.stderr.write(
+    "npx @0xray/foundry release bumps, commits, pushes, and publishes the milled cwd.\n" +
+      "Pass --i-mean-it or set FOUNDRY_RELEASE=1. Preview with --dry-run.\n",
+  );
+}
+
+function run(cmd, label) {
+  console.log(`\n> ${cmd}`);
+  if (dryRun) {
+    console.log(`  (dry-run skip: ${label})`);
+    return;
+  }
+  execSync(cmd, {
+    cwd: rootDir,
+    stdio: "inherit",
+    encoding: "utf-8",
+    env: { ...process.env, FOUNDRY_ROOT: rootDir },
+  });
+}
+
+function runMill(script, extraArgs, label) {
+  const quoted = [millScript(script), ...extraArgs].map((a) => JSON.stringify(a)).join(" ");
+  run(`${JSON.stringify(process.execPath)} ${quoted}`, label);
+}
+
+function readVersion() {
+  return JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf-8")).version;
+}
+
+function packageName() {
+  const name = readRootPackage(rootDir).name;
+  if (!name) {
+    process.stderr.write("package.json name is required to mill publish\n");
+    process.exit(1);
+  }
+  return name;
+}
+
+function npmPublishCmd() {
+  const pkg = readRootPackage(rootDir);
+  if (isXrayExoRepo(rootDir) || pkg.name === "@0xray/foundry") {
+    return "npm publish --access public";
+  }
+  return "npm publish";
+}
+
+function currentBranch() {
+  return execSync("git rev-parse --abbrev-ref HEAD", { cwd: rootDir, encoding: "utf-8" }).trim();
+}
+
+function npmVersionPublished(version) {
+  try {
+    const out = execSync(`npm view ${packageName()}@${version} version`, {
+      cwd: rootDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return out === version;
+  } catch {
+    return false;
+  }
+}
+
+function publishIdempotent(version) {
+  if (dryRun) {
+    console.log(`  would: ${npmPublishCmd()} (check ${packageName()}@${version} first)`);
+    return;
+  }
+  if (npmVersionPublished(version)) {
+    console.log(`ℹ️  ${packageName()}@${version} already on npm — skipping publish`);
+    return;
+  }
+  execSync(npmPublishCmd(), { cwd: rootDir, stdio: "inherit", encoding: "utf-8" });
+  console.log(`✅ Published ${packageName()}@${version}`);
+}
+
+async function main() {
+  const live = (publishOnly || Boolean(releaseType)) && !dryRun;
+  if (live && !optedIn) {
+    writeReleaseTrap();
+    process.exit(1);
+  }
+
+  if (publishOnly) {
+    packageName();
+    const version = readVersion();
+    runMill("release-gate.mjs", [], "release gate");
+    if (isXrayExoRepo(rootDir)) {
+      run("npm run prepare-consumer && npm run build", "safe-publish");
+    } else if (readRootPackage(rootDir).scripts.build) {
+      run("npm run build", "build");
+    }
+    publishIdempotent(version);
+    if (!dryRun) {
+      try {
+        execSync(`git tag -a v${version} -m "Release v${version}"`, {
+          cwd: rootDir,
+          stdio: "inherit",
+        });
+      } catch (e) {
+        const msg = String(e.stderr || e.message || "");
+        if (!msg.includes("already exists")) throw e;
+      }
+    }
+    run(`git push origin v${version}`, "push tag");
+    return;
+  }
+
+  if (!releaseType || !["major", "minor", "patch"].includes(releaseType)) {
+    process.stderr.write(
+      "Usage: npx @0xray/foundry release [patch|minor|major] [--dry-run|--i-mean-it]\n",
+    );
+    process.stderr.write(
+      "       npx @0xray/foundry release --publish-only [--dry-run|--i-mean-it]\n",
+    );
+    process.exit(1);
+  }
+
+  console.log("╔════════════════════════════════════════════════════════╗");
+  console.log("║        🚀 0xRay Release (canonical)                   ║");
+  console.log("╚════════════════════════════════════════════════════════╝");
+  if (dryRun) console.log("\n⚠️  DRY RUN — no writes, commits, tags, or publish\n");
+
+  // 1. Version bump from npm SSOT
+  console.log(`\n📦 Step 1: Bump ${releaseType} from npm baseline`);
+  if (dryRun) {
+    runMill("reconcile-version.mjs", [releaseType], "version bump (dry)");
+  } else {
+    runMill("reconcile-version.mjs", [releaseType, "--apply"], "version bump");
+  }
+  const newVersion = dryRun
+    ? execSync(
+        `${JSON.stringify(process.execPath)} ${JSON.stringify(millScript("reconcile-version.mjs"))} ${JSON.stringify(releaseType)} --print-target`,
+        {
+          cwd: rootDir,
+          encoding: "utf-8",
+          env: { ...process.env, FOUNDRY_ROOT: rootDir },
+        },
+      ).trim()
+    : readVersion();
+  console.log(`📌 Release version: ${newVersion}`);
+
+  // 2. Artifacts BEFORE gate (docs vitest matches package.json version)
+  console.log("\n📦 Step 2: Release artifacts (CHANGELOG, README, AGENTS, docs)");
+  runMill("version-manager.mjs", ["--artifacts-only"], "release artifacts");
+
+  // 3. Gate
+  console.log("\n📦 Step 3: Release gate (build + test + smoke)");
+  runMill("release-gate.mjs", [], "release gate");
+
+  // 4. Commit + push
+  console.log("\n📦 Step 4: Commit & push");
+  const releaseFiles = getReleaseArtifactPaths();
+  if (!dryRun) {
+    run(`git add ${releaseFiles.join(" ")}`, "git add");
+    try {
+      execSync(`git commit --no-verify -m "release: v${newVersion}"`, { cwd: rootDir, stdio: "inherit" });
+    } catch (e) {
+      const out = String(e.stdout || e.stderr || "");
+      if (!out.includes("nothing to commit")) throw e;
+      console.log("ℹ️  Nothing to commit (release files unchanged)");
+    }
+  } else {
+    console.log(`  would: git add ${releaseFiles.join(" ")} && git commit -m "release: v${newVersion}"`);
+  }
+
+  const branch = currentBranch();
+  run(`git push origin ${branch}`, "git push");
+
+  // 5. Post-push verify before publish
+  console.log("\n📦 Step 5: Verify gate (reconcile + git + docs + smoke)");
+  runMill("release-gate.mjs", ["--verify-only"], "verify gate");
+
+  // 6. Publish (idempotent)
+  console.log("\n📦 Step 6: npm publish");
+  publishIdempotent(newVersion); // name from package.json via packageName()
+
+  // 7. Tag after publish
+  console.log("\n📦 Step 7: Tag");
+  if (!dryRun) {
+    try {
+      execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, { cwd: rootDir, stdio: "inherit" });
+      console.log(`✅ Created tag v${newVersion}`);
+    } catch (e) {
+      const msg = String(e.stderr || e.message || "");
+      if (msg.includes("already exists")) {
+        console.log(`ℹ️  Tag v${newVersion} already exists`);
+      } else {
+        throw e;
+      }
+    }
+  } else {
+    console.log(`  would: git tag -a v${newVersion}`);
+  }
+  run(`git push origin v${newVersion}`, "push tag");
+
+  console.log("\n╔════════════════════════════════════════════════════════╗");
+  console.log("║        ✅ Release Complete!                            ║");
+  console.log("╚════════════════════════════════════════════════════════╝");
+  if (!dryRun) {
+    process.stdout.write(`\n📦 ${packageName()}@${newVersion}  🏷  v${newVersion}\n`);
+    if (isXrayExoRepo(rootDir)) {
+      const tweetPath = path.join(rootDir, "tweets", `v${newVersion}.md`);
+      if (!fs.existsSync(tweetPath)) {
+        fs.mkdirSync(path.join(rootDir, "tweets"), { recursive: true });
+        fs.writeFileSync(
+          tweetPath,
+          `🎉 0xRay v${newVersion} is LIVE - consumer-safe upgrades!\n...\n\`\`\`\nnpm install 0xray@latest\n\`\`\`\n`,
+        );
+        process.stdout.write(`📝 Tweet template: tweets/v${newVersion}.md\n`);
+      }
+    }
+  }
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`\n❌ Release failed: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/scripts/foundry/validate-release-docs.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/**
+ * validate-release-docs.mjs — Blocking guard for release doc freshness.
+ *
+ * Ensures README, AGENTS, SKILLS, CHANGELOG, Docusaurus headers, and required
+ * guides match package.json version and live framework counts before tag/publish.
+ *
+ * Usage:
+ *   npx @0xray/foundry docs-check
+ *   npx @0xray/foundry docs-check --json
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import {
+  buildDocsHeader,
+  DOCS_SITE_HEADER_FILES,
+  getFrameworkCounts,
+  getReleaseArtifactPaths,
+} from './version-manager.mjs';
+import { isXrayExoRepo, resolveMillRoot } from './mill-root.mjs';
+
+const STANDARD_HEADER_RE =
+  /\*{0,2}\d+\.\d+\*{0,2}\s*—\s*a suit that survives the context window/;
+
+/** Patch stamps belong in CHANGELOG, not kernel headers. */
+function kernelLineHasPatchStamp(content) {
+  return /^\*\*v?\d+\.\d+\.\d+\*\*/m.test(content);
+}
+
+/** Guides that must exist and reference the current release (body or header). */
+const REQUIRED_GUIDES = [
+  'docs-site/docs/guides/features-since-3.1.md',
+  'docs-site/docs/guides/features-json.md',
+  'docs-site/docs/guides/memory-routing.md',
+  'docs-site/docs/guides/aside-context.md',
+  'docs-site/docs/guides/repertoire.md',
+  'docs-site/docs/guides/integrations.md',
+  'docs-site/docs/guides/consumer-migration.md',
+  'docs-site/docs/mcp/README.md',
+  'docs-site/docs/agents/README.md',
+];
+
+const ROOT_DOC_CHECKS = [
+  {
+    rel: 'README.md',
+    validate: (content, _version, _counts, header) => {
+      const errors = [];
+      if (!content.includes(header) && !STANDARD_HEADER_RE.test(content)) {
+        errors.push(`missing kernel header (expected substring: ${header})`);
+      }
+      if (kernelLineHasPatchStamp(content)) {
+        errors.push('kernel header must be era (major.minor), not a patch stamp');
+      }
+      if (!content.includes('survive the context window') && !content.includes('survives the context window')) {
+        errors.push('missing context-window / exo kernel copy');
+      }
+      if (!content.includes('SKILLS.md')) {
+        errors.push('missing SKILLS.md reference in postinstall/docs section');
+      }
+      if (!content.includes('install-bridges') && !content.includes('installAllBridges')) {
+        errors.push('missing install-bridges / installAllBridges reference');
+      }
+      return errors;
+    },
+  },
+  {
+    rel: 'AGENTS.md',
+    validate: (content, _version) => {
+      const errors = [];
+      if (kernelLineHasPatchStamp(content)) {
+        errors.push('kernel header must be era (major.minor), not a patch stamp');
+      }
+      if (!content.includes('survive the context window') && !content.includes('survives the context window') && !content.includes('Exo, not catalog')) {
+        errors.push('missing exo / context-window kernel copy');
+      }
+      if (!content.includes('aside-context.md') && !content.includes('AsideContext')) {
+        errors.push('missing AsideContext documentation reference');
+      }
+      if (!content.includes('SKILLS.md')) {
+        errors.push('missing SKILLS.md link');
+      }
+      return errors;
+    },
+  },
+  {
+    rel: 'AGENTS-consumer.md',
+    validate: (content) => {
+      const errors = [];
+      if (kernelLineHasPatchStamp(content)) {
+        errors.push('kernel header must be era (major.minor), not a patch stamp');
+      }
+      if (!content.includes('survive the context window') && !content.includes('survives the context window')) {
+        errors.push('consumer header missing context-window kernel copy');
+      }
+      if (!content.includes('SKILLS.md')) {
+        errors.push('missing SKILLS.md in postinstall section');
+      }
+      if (!content.includes('AsideContext')) {
+        errors.push('missing AsideContext section');
+      }
+      return errors;
+    },
+  },
+  {
+    rel: 'SKILLS.md',
+    validate: (content, _version, counts) => {
+      const errors = [];
+      if (kernelLineHasPatchStamp(content)) {
+        errors.push('kernel header must be era (major.minor), not a patch stamp');
+      }
+      if (!content.includes(`**${counts.skills} skills**`)) {
+        errors.push(`skill count stale (expected **${counts.skills} skills**)`);
+      }
+      return errors;
+    },
+  },
+];
+
+function readFile(rootDir, rel) {
+  const full = path.join(rootDir, rel);
+  if (!fs.existsSync(full)) return null;
+  return fs.readFileSync(full, 'utf-8');
+}
+
+function getPackageVersion(rootDir) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf-8'));
+  return pkg.version;
+}
+
+function getCodexTermCount(rootDir) {
+  const codexPath = path.join(rootDir, '.xray/codex.json');
+  if (!fs.existsSync(codexPath)) return null;
+  const codex = JSON.parse(fs.readFileSync(codexPath, 'utf-8'));
+  return Object.keys(codex.terms || {}).length;
+}
+
+function validateChangelog(content, version) {
+  const errors = [];
+  const headings = [...content.matchAll(/^## \[([^\]]+)\]/gm)].map((m) => m[1]);
+  if (headings.length === 0) {
+    errors.push('no version sections found');
+    return errors;
+  }
+  if (headings[0] === 'Unreleased') {
+    if (headings[1] !== version) {
+      errors.push(`after [Unreleased], expected [${version}], found [${headings[1] || 'none'}]`);
+    }
+  } else if (headings[0] !== version) {
+    errors.push(`top CHANGELOG entry is [${headings[0]}], expected [${version}] or [Unreleased]`);
+  }
+  if (!content.includes(`## [${version}]`)) {
+    errors.push(`missing ## [${version}] section`);
+  }
+  return errors;
+}
+
+function validateStandardHeader(content, expectedHeader, label) {
+  if (!content.includes(expectedHeader) && !STANDARD_HEADER_RE.test(content)) {
+    return [`${label}: missing kernel header (expected substring: ${expectedHeader})`];
+  }
+  return [];
+}
+
+function validateDocusaurusTagline(content) {
+  const errors = [];
+  if (!content.includes('survive the context window') && !content.includes('survives the context window')) {
+    errors.push('docusaurus.config.ts tagline missing context-window kernel copy');
+  }
+  return errors;
+}
+
+/**
+ * @param {string} [rootDir]
+ * @returns {{ ok: boolean; version: string; counts: object; errors: string[]; warnings: string[]; mode?: 'full'|'light' }}
+ */
+export function validateReleaseDocs(rootDir = resolveMillRoot()) {
+  const errors = [];
+  const warnings = [];
+  const version = getPackageVersion(rootDir);
+  const counts = getFrameworkCounts(rootDir);
+  const expectedHeader = buildDocsHeader(counts, version);
+  const codexTerms = getCodexTermCount(rootDir);
+  const full = isXrayExoRepo(rootDir);
+
+  if (codexTerms !== null && counts.codexTerms && codexTerms !== counts.codexTerms) {
+    warnings.push(`codex.json has ${codexTerms} terms (counts.codexTerms is ${counts.codexTerms})`);
+  }
+
+  const changelog = readFile(rootDir, 'CHANGELOG.md');
+  if (!changelog) {
+    if (full) {
+      errors.push('CHANGELOG.md missing');
+    } else {
+      warnings.push('CHANGELOG.md missing (light mill)');
+    }
+  } else {
+    errors.push(...validateChangelog(changelog, version).map((e) => `CHANGELOG.md: ${e}`));
+  }
+
+  if (!full) {
+    return {
+      ok: errors.length === 0,
+      version,
+      counts,
+      errors,
+      warnings,
+      mode: 'light',
+    };
+  }
+
+  for (const check of ROOT_DOC_CHECKS) {
+    const content = readFile(rootDir, check.rel);
+    if (!content) {
+      errors.push(`${check.rel}: file missing`);
+      continue;
+    }
+    const relErrors = check.validate(content, version, counts, expectedHeader);
+    for (const e of relErrors) {
+      errors.push(`${check.rel}: ${e}`);
+    }
+  }
+
+  for (const rel of DOCS_SITE_HEADER_FILES) {
+    const content = readFile(rootDir, rel);
+    if (!content) {
+      errors.push(`${rel}: file missing`);
+      continue;
+    }
+    errors.push(...validateStandardHeader(content, expectedHeader, rel));
+    if (kernelLineHasPatchStamp(content)) {
+      errors.push(`${rel}: kernel header must be era (major.minor), not a patch stamp`);
+    }
+  }
+
+  for (const rel of REQUIRED_GUIDES) {
+    const content = readFile(rootDir, rel);
+    if (!content) {
+      errors.push(`${rel}: required guide missing`);
+      continue;
+    }
+    if (content.trim().length < 200) {
+      errors.push(`${rel}: guide too short — likely stub`);
+    }
+
+  }
+
+  const docusaurus = readFile(rootDir, 'docs-site/docusaurus.config.ts');
+  if (!docusaurus) {
+    errors.push('docs-site/docusaurus.config.ts: missing');
+  } else {
+    errors.push(...validateDocusaurusTagline(docusaurus));
+  }
+
+  for (const rel of getReleaseArtifactPaths(rootDir)) {
+    if (!fs.existsSync(path.join(rootDir, rel))) {
+      errors.push(`release artifact path missing: ${rel}`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    version,
+    counts,
+    errors,
+    warnings,
+    mode: 'full',
+  };
+}
+
+function main() {
+  const jsonOut = process.argv.includes('--json');
+  const result = validateReleaseDocs();
+
+  if (!jsonOut) {
+    console.log('\n╔════════════════════════════════════════════════════════╗');
+    console.log('║        📚 Release Docs Validation                      ║');
+    console.log('╚════════════════════════════════════════════════════════╝');
+    console.log(`\n📌 package.json version: v${result.version}`);
+    console.log(
+      `📊 counts: ${result.counts.agents} agents · ${result.counts.skills} skills · ${result.counts.mcps} MCP servers\n`,
+    );
+  }
+
+  if (result.warnings.length > 0 && !jsonOut) {
+    console.log('⚠️  Warnings:');
+    for (const w of result.warnings) console.log(`   - ${w}`);
+    console.log();
+  }
+
+  if (!result.ok) {
+    if (jsonOut) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error('❌ Release docs validation FAILED:\n');
+      for (const e of result.errors) console.error(`   • ${e}`);
+      console.error('\nFix docs then run: npm run version:sync');
+      console.error('Or: npx @0xray/foundry docs-check\n');
+    }
+    process.exit(1);
+  }
+
+  if (jsonOut) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log('✅ Release docs validation passed\n');
+  }
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main();
+}