0xray 4.0.1 → 4.0.2

package/dist/processors/implementations/version-compliance-processor.js

@@ -5,10 +5,9 @@
  * commits or publishes. Integrates with 0xRay's processor pipeline.
  *
  * Rules Enforced:
- * 1. Universal Version Manager MUST be 1 ahead of NPM published version
- * 2. package.json SHOULD match UVM (warning if not)
- * 3. Source files MUST be synchronized to UVM version
- * 4. README SHOULD reference current version
+ * 1. package.json version is the SSOT (semver)
+ * 2. Mill SSOT is package.json via scripts/foundry/reconcile-version.mjs
+ * 3. Do not bump or publish from this processor (foundry mill ships)
  *
  * @processor_type pre
  * @priority 25 (high - runs early, after preValidate, before errorBoundary)
@@ -100,53 +99,13 @@ export class VersionComplianceProcessor {
         this.errors = [];
         this.warnings = [];
         this.fixes = [];
-        // Get all versions
         const npmVersion = await this.getNpmVersion();
-        const uvmVersion = this.getUvmVersion();
         const pkgVersion = this.getPackageVersion();
-        // Rule 1: UVM MUST be 1 ahead of NPM
-        if (npmVersion !== "NOT_PUBLISHED" && npmVersion !== "ERROR") {
-            const npmParsed = this.parseVersion(npmVersion);
-            const uvmParsed = this.parseVersion(uvmVersion);
-            const expectedUvm = this.incrementPatch(npmParsed);
-            if (uvmVersion !== this.formatVersion(expectedUvm)) {
-                this.errors.push(`Version manager not 1 ahead of npm (NPM: ${npmVersion}, UVM: ${uvmVersion}, Expected: ${this.formatVersion(expectedUvm)})`);
-                this.fixes.push({
-                    type: "update-uvm",
-                    description: `Update UVM to ${this.formatVersion(expectedUvm)}`,
-                    command: "node scripts/node/universal-version-manager.js",
-                    autoFixable: false, // Requires manual edit
-                });
-            }
-        }
-        // Rule 2: package.json SHOULD match UVM
-        if (pkgVersion !== uvmVersion) {
-            this.warnings.push(`package.json version (${pkgVersion}) doesn't match UVM (${uvmVersion}) - run "npm version [patch|minor|major]" to sync`);
-        }
-        // Rule 3: Source files MUST be synchronized
-        const sourceVersion = this.getSourceVersion();
-        if (sourceVersion && sourceVersion !== uvmVersion) {
-            this.errors.push(`Source files not synchronized to UVM version (${sourceVersion} vs ${uvmVersion})`);
-            this.fixes.push({
-                type: "sync-source",
-                description: "Synchronize source files to UVM version",
-                command: "node scripts/node/universal-version-manager.js",
-                autoFixable: true,
-            });
-        }
-        // Rule 4: README SHOULD reference current version
-        const readmeVersion = this.getReadmeVersion();
-        if (readmeVersion &&
-            readmeVersion !== uvmVersion &&
-            readmeVersion !== pkgVersion) {
-            this.warnings.push(`README version (${readmeVersion}) may be outdated (UVM: ${uvmVersion}, package: ${pkgVersion})`);
-            this.fixes.push({
-                type: "update-readme",
-                description: "Update README version references",
-                command: "node scripts/node/universal-version-manager.js",
-                autoFixable: true,
-            });
+        const uvmVersion = "FROZEN";
+        if (!/^\d+\.\d+\.\d+/.test(pkgVersion)) {
+            this.errors.push(`package.json version is not semver (${pkgVersion})`);
         }
+        this.warnings.push("SSOT is package.json via scripts/foundry/reconcile-version.mjs");
         return {
             compliant: this.errors.length === 0,
             npmVersion,
@@ -172,29 +131,6 @@ export class VersionComplianceProcessor {
             return "NOT_PUBLISHED";
         }
     }
-    /**
-     * Get Universal Version Manager version
-     */
-    getUvmVersion() {
-        try {
-            const uvmPath = path.join(this.projectRoot, "scripts", "node", "universal-version-manager.js");
-            if (!fs.existsSync(uvmPath)) {
-                return "NOT_FOUND";
-            }
-            const content = fs.readFileSync(uvmPath, "utf-8");
-            // Match version in OFFICIAL_VERSIONS.framework.version format
-            const match = content.match(/OFFICIAL_VERSIONS\s*=\s*\{[\s\S]*?framework:\s*\{[\s\S]*?version:\s*["']([^"']+)["']/);
-            if (match && match[1]) {
-                return match[1];
-            }
-            // Fallback: grep for version pattern
-            const fallbackMatch = content.match(/version:\s*["'](\d+\.\d+\.\d+)["']/);
-            return fallbackMatch && fallbackMatch[1] ? fallbackMatch[1] : "NOT_FOUND";
-        }
-        catch {
-            return "ERROR";
-        }
-    }
     /**
      * Get package.json version
      */
@@ -211,69 +147,6 @@ export class VersionComplianceProcessor {
             return "ERROR";
         }
     }
-    /**
-     * Get version from source files
-     */
-    getSourceVersion() {
-        try {
-            const cliPath = path.join(this.projectRoot, "src", "cli", "index.ts");
-            if (!fs.existsSync(cliPath)) {
-                return null;
-            }
-            const content = fs.readFileSync(cliPath, "utf-8");
-            const match = content.match(/\.version\(["']([^"']+)["']\)/);
-            return match && match[1] ? match[1] : null;
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * Get version from README
-     */
-    getReadmeVersion() {
-        try {
-            const readmePath = path.join(this.projectRoot, "README.md");
-            if (!fs.existsSync(readmePath)) {
-                return null;
-            }
-            const content = fs.readFileSync(readmePath, "utf-8");
-            // Match vX.Y.Z or X.Y.Z patterns - but exclude IP addresses (127.x.x)
-            // Look for version in badges, headers, or specific patterns
-            const match = content.match(/v?(1\.\d+\.\d+)/);
-            return match && match[1] ? match[1] : null;
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * Parse version string into components
-     */
-    parseVersion(version) {
-        const parts = version.split(".");
-        return {
-            major: parseInt(parts[0] || "0", 10),
-            minor: parseInt(parts[1] || "0", 10),
-            patch: parseInt(parts[2] || "0", 10),
-            raw: version,
-        };
-    }
-    /**
-     * Format version components back to string
-     */
-    formatVersion(version) {
-        return `${version.major}.${version.minor}.${version.patch}`;
-    }
-    /**
-     * Increment patch version
-     */
-    incrementPatch(version) {
-        return {
-            ...version,
-            patch: version.patch + 1,
-        };
-    }
     /**
      * Auto-fix version compliance issues
      */
@@ -318,7 +191,7 @@ export class VersionComplianceProcessor {
             "============================",
             "",
             `NPM Published: ${result.npmVersion}`,
-            `Version Manager: ${result.uvmVersion}`,
+            `UVM: ${result.uvmVersion}`,
             `package.json: ${result.pkgVersion}`,
             "",
             result.compliant ? "✅ COMPLIANT" : "❌ NON-COMPLIANT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
   "readme": "README.md",
   "license": "MIT",
@@ -61,8 +61,8 @@
   },
   "scripts": {
     "prepublishOnly": "node scripts/node/reconcile-version.mjs --check && npm run prepare-consumer && npm run build:all && find dist -name '*.js.map' -o -name '*.d.ts.map' | xargs rm -f 2>/dev/null || true",
-    "version:bump": "node scripts/node/version-manager.mjs",
-    "version": "node scripts/node/version-manager.mjs",
+    "version:bump": "node scripts/foundry/reconcile-version.mjs",
+    "version": "node scripts/foundry/version-manager.mjs",
     "prebuild": "rm -rf dist tsconfig.tsbuildinfo tsconfig.*.tsbuildinfo",
     "build": "tsc && chmod +x dist/cli/index.js && mkdir -p dist/public dist/scripts && cp -r public/* dist/public/ && cp scripts/hooks/pre-command dist/scripts/ && cp scripts/hooks/pre-command.mjs dist/scripts/ && cp README.md AGENTS.md SKILLS.md CHANGELOG.md LICENSE .gitignore.default dist/ && find src -name '*.mjs' ! -path '*/__tests__/*' | while read f; do tgt=\"dist/${f#src/}\"; mkdir -p \"$(dirname $tgt)\"; cp \"$f\" \"$tgt\"; done && for dir in skills integrations mcps; do find src/$dir -type f ! -name '*.ts' ! -path '*/.pytest_cache/*' | while read f; do tgt=\"dist/${f#src/}\"; mkdir -p \"$(dirname $tgt)\"; cp \"$f\" \"$tgt\"; done; done && mkdir -p dist/plugin && (find dist/plugin -name '*codex-injection*.js' -exec cp {} dist/plugin/xray-codex-injection.js \\; 2>/dev/null || true) && cp -r src/opencode/ .opencode/ && mkdir -p .opencode/skills && cp -R src/skills/. .opencode/skills/ && mkdir -p .xray && for f in codex.json features.json features.schema.json config.json; do cp xray/$f .xray/$f 2>/dev/null || true; done",
     "build:all": "npm run build",
@@ -112,20 +112,20 @@
     "build:run": "node scripts/build/utils.js build",
     "build:clean": "node scripts/build/utils.js clean",
     "build:verify": "node scripts/build/utils.js verify",
-    "enforce:versions": "bash scripts/node/enforce-version-compliance.sh",
-    "version:sync": "node scripts/node/version-manager.mjs --artifacts-only",
-    "release": "node scripts/node/release.mjs patch",
-    "release:minor": "node scripts/node/release.mjs minor",
-    "release:major": "node scripts/node/release.mjs major",
-    "release:dry": "node scripts/node/release.mjs patch --dry-run",
-    "version:reconcile": "node scripts/node/reconcile-version.mjs",
+    "enforce:versions": "node scripts/foundry/validate-release-docs.mjs",
+    "version:sync": "node scripts/foundry/version-manager.mjs --artifacts-only",
+    "release": "node scripts/foundry/release.mjs patch",
+    "release:minor": "node scripts/foundry/release.mjs minor",
+    "release:major": "node scripts/foundry/release.mjs major",
+    "release:dry": "node scripts/foundry/release.mjs patch --dry-run",
+    "version:reconcile": "node scripts/foundry/reconcile-version.mjs",
     "consumer:smoke": "node scripts/node/consumer-install-smoke.mjs",
-    "release:gate": "node scripts/node/release-gate.mjs",
-    "release:docs-check": "node scripts/node/validate-release-docs.mjs",
+    "release:gate": "node scripts/foundry/release-gate.mjs",
+    "release:docs-check": "node scripts/foundry/validate-release-docs.mjs",
     "pre-publish-guard": "node scripts/node/pre-publish-guard.js",
     "safe-publish": "npm run prepare-consumer && npm run build",
-    "release:npm": "npm run release:gate && npm run safe-publish && npm publish --access public",
-    "release:patch": "node scripts/node/release.mjs patch",
+    "release:npm": "node scripts/foundry/release.mjs --publish-only",
+    "release:patch": "node scripts/foundry/release.mjs patch",
     "verify:orchestrator-behavior": "npm run build && node scripts/mjs/verify-orchestrator-behavior.mjs",
     "verify:grok-delegation-gate": "npm run build && node scripts/mjs/verify-grok-delegation-gate.mjs && node scripts/mjs/verify-grok-synthesis-gate.mjs",
     "verify:grok-synthesis-gate": "npm run build && node scripts/mjs/verify-grok-synthesis-gate.mjs",
@@ -146,6 +146,7 @@
   "files": [
     "dist/",
     "scripts/node/",
+    "scripts/foundry/",
     "scripts/integrations/",
     "scripts/helpers/",
     "scripts/hooks/",

package/scripts/foundry/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## [0.1.4] - 2026-09-04
+
+`npx @0xray/foundry hooks` on a published mill uses the worn garment
+`node_modules/0xray/scripts/hooks/install-hooks.cjs`. Dogfood still uses
+`scripts/hooks` next to `scripts/foundry`. Missing installer fails honestly
+(no spawn of `node_modules/@0xray/hooks/...`).
+
+## [0.1.3] - 2026-09-04
+
+Pages homepage is a baseUrl meta refresh to `/docs/`, not a client redirect to `/docs/introduction` (org-root 404).
+
+Docusaurus is mill: `npx @0xray/foundry docs-build` (exo only). GitHub Pages no longer clobbers the generated homepage with a stale 3.x `static/index.html`.
+
+## [0.1.2] - 2026-09-04
+
+Mill owns GitHub CI, git hooks, and CI report. `npx @0xray/foundry ci` reports Actions (no auto-push). `npx @0xray/foundry hooks` installs pre/post git hooks. `0xRay CI/CD` is the mill gate on main.
+
+## [0.1.1] - 2026-09-04
+
+Live `release` (bump/commit/push/publish of the milled cwd) requires `--i-mean-it` or `FOUNDRY_RELEASE=1`. `--dry-run` stays free. Packed mill tarball mints overlay. Stamp keeps `[Unreleased]` and inserts the version under it.
+
+## [0.1.0] - 2026-09-03
+
+First mill package. Overlay their constitution, features, skills, and agents onto **project** hangers. Stamp/gate/docs-check mill `FOUNDRY_ROOT` or cwd. Not the worn exo.
+
+Publish this package from this directory:
+
+```bash
+cd scripts/foundry && npm publish --access public
+```
+
+Do not `npm publish` from the 0xray repo root (that is `0xray@4.0.1`).

package/scripts/foundry/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xray Framework Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/scripts/foundry/README.md

@@ -0,0 +1,67 @@
+# @0xray/foundry
+
+The **mill**, not the worn exo. Reconcile, stamp JSON/CHANGELOG, verify docs, gate, publish, overlay their suit params.
+
+PPE (`evaluatePreToolGate`) stays worn. The mill plants **their** constitution, features, skills, and agents onto the hanger. It is not a fifth MCP. The suit is [`0xray`](https://www.npmjs.com/package/0xray).
+
+## Install
+
+```bash
+npm i -D @0xray/foundry
+```
+
+## Commands
+
+```bash
+npx @0xray/foundry reconcile [patch|minor|major] [--apply] [--check]
+npx @0xray/foundry stamp
+npx @0xray/foundry docs-check
+npx @0xray/foundry docs-build
+npx @0xray/foundry gate [--verify-only]
+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
+npx @0xray/foundry mint
+npx @0xray/foundry ci [--commit SHA] [--report]
+npx @0xray/foundry hooks
+```
+
+`release` without `--dry-run` requires `--i-mean-it` or `FOUNDRY_RELEASE=1`. It is a bump/commit/push/publish bot for the **milled cwd**, not a casual command.
+
+`FOUNDRY_ROOT` overrides cwd (the repo being milled).
+
+`gate` is build + test + docs-check. `docs-build` runs Docusaurus on the 0xray exo (`docs-site/`); stranger mills skip. `ci` reports GitHub Actions (no auto-push). `hooks` installs git pre/post hooks. GitHub `0xRay CI/CD` is the mill gate on `main`. `Deploy Docs` is the mill Pages put.
+
+`docs-check` and `gate` run **full** 0xRay corpus only when the milled `package.json` name is `0xray` and `docs-site/` exists. Otherwise **light**: `package.json` + CHANGELOG.
+
+`hooks` installs git hooks via `scripts/hooks/install-hooks.cjs` (dogfood) or `node_modules/0xray/scripts/hooks/install-hooks.cjs` (published mill + worn garment). It does not look for `@0xray/hooks`.
+
+## Suit params (`mint`)
+
+After the garment is on the hanger, overlay their plant (defaults; remap in `foundry.json` or `.xray/foundry.json`):
+
+| Facet | Default plant | Hanger |
+|---|---|---|
+| Constitution | `xray/codex.json` | `.xray/codex.json` |
+| Features / temperament | `xray/features.json` | `.xray/features.json` |
+| Config | `xray/config.json` | `.xray/config.json` |
+| Skills | `src/skills/<name>/SKILL.md` | `.opencode/skills/` and project `.grok/plugins/0xray/skills` if that dir exists |
+| Agents | `src/opencode/agents/*.yml` | `.opencode/agents/` (OpenCode hangar; other floors do not read mill YML agents) |
+| Agents card | `xray/AGENTS.md` | `AGENTS.md` if mill-managed |
+
+**Mill-fill is law:** their keys/files win; mill names they did not plant stay unless they overlay the same name. JSON facets always merge. Skill overlay is project hangers only. CLI re-wear calls mint **once** after mill copies.
+
+## Publish this mill
+
+From **this directory**, not the 0xray repo root:
+
+```bash
+cd scripts/foundry && npm publish --access public
+```
+
+Repo-root `npm publish` is `0xray`. `npx @0xray/foundry release --i-mean-it` publishes the **milled cwd** package (their `publishConfig`; `--access public` only for `0xray` and `@0xray/foundry`).
+
+## 0xRay exo
+
+The mill lives in `scripts/foundry/` inside [0xRayAI/xray](https://github.com/0xRayAI/xray). `scripts/node/*.mjs` wrappers are shims onto this package.

package/scripts/foundry/ci-monitor.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Mill CI monitor. Reports GitHub Actions for the milled cwd.
+ * Not PPE. Not an auto-push bot.
+ *
+ *   npx @0xray/foundry ci [--commit SHA] [--report]
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveMillRoot } from "./mill-root.mjs";
+
+const args = process.argv.slice(2);
+const commitIdx = args.indexOf("--commit");
+const shaArg = commitIdx >= 0 ? args[commitIdx + 1] : "";
+const sha = (shaArg && !shaArg.startsWith("-") ? shaArg : process.env.GITHUB_SHA || "").trim();
+const root = resolveMillRoot();
+const reportPath = path.join(root, ".opencode", "logs", "ci-cd-monitor-report.json");
+
+function writeReport(report) {
+  fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+  fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+}
+
+function emptyReport(status, reason) {
+  return {
+    ci_status: status,
+    health_score: status === "healthy" || status === "unknown" ? 100 : 0,
+    issues: [],
+    reason,
+    sha: sha || null,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+async function main() {
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
+  const repo = process.env.GITHUB_REPOSITORY || "";
+  if (!token || !repo.includes("/")) {
+    const report = emptyReport(
+      "unknown",
+      "no GITHUB_TOKEN or GITHUB_REPOSITORY — mill CI monitor skipped",
+    );
+    writeReport(report);
+    process.stdout.write("SUCCESS: mill CI monitor skipped (no GitHub token)\n");
+    process.stdout.write("No failed jobs\n");
+    return 0;
+  }
+
+  const url = new URL(`https://api.github.com/repos/${repo}/actions/runs`);
+  url.searchParams.set("per_page", "50");
+  if (sha) url.searchParams.set("head_sha", sha);
+
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "User-Agent": "0xray-foundry-ci-monitor",
+    },
+  });
+  if (!res.ok) {
+    const report = emptyReport("warning", `GitHub API ${res.status}`);
+    writeReport(report);
+    process.stderr.write(`mill ci: GitHub API ${res.status}\n`);
+    return 1;
+  }
+  const body = await res.json();
+  const runs = Array.isArray(body.workflow_runs) ? body.workflow_runs : [];
+  const failed = runs.filter((run) => {
+    const conclusion = String(run.conclusion || "");
+    return conclusion === "failure" || conclusion === "timed_out" || conclusion === "startup_failure";
+  });
+  const issues = failed.map((run) => ({
+    name: run.name || run.display_title || "workflow",
+    conclusion: run.conclusion,
+    html_url: run.html_url,
+    head_sha: run.head_sha,
+  }));
+  const uniqueFails = new Set(issues.map((i) => i.name)).size;
+  const health = Math.max(0, 100 - uniqueFails * 20);
+  const ci_status = uniqueFails === 0 ? "healthy" : uniqueFails >= 3 ? "critical" : "warning";
+  const report = {
+    ci_status,
+    health_score: health,
+    issues,
+    sha: sha || null,
+    run_count: runs.length,
+    generatedAt: new Date().toISOString(),
+  };
+  writeReport(report);
+
+  if (uniqueFails === 0) {
+    process.stdout.write("SUCCESS: All workflows passed\n");
+    process.stdout.write("No failed jobs\n");
+    return 0;
+  }
+  process.stdout.write(`FAILURE: ${issues.map((i) => i.name).join(", ")}\n`);
+  return 1;
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    });
+}
+
+export { main };

package/scripts/foundry/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./cli.mjs";

package/scripts/foundry/cli.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * @0xray/foundry CLI — mill, not exo. No fifth MCP.
+ *
+ *   npx @0xray/foundry <reconcile|stamp|gate|release|docs-check|docs-build|mint|ci|hooks> [...args]
+ */
+
+import { spawnSync } from "node:child_process";
+import { millScript, resolveMillRoot } from "./mill-root.mjs";
+
+const COMMANDS = {
+  reconcile: { script: "reconcile-version.mjs", preset: [] },
+  stamp: { script: "version-manager.mjs", preset: ["--artifacts-only"] },
+  gate: { script: "release-gate.mjs", preset: [] },
+  release: { script: "release.mjs", preset: [] },
+  "docs-check": { script: "validate-release-docs.mjs", preset: [] },
+  "docs-build": { script: "docs-build.mjs", preset: [] },
+  mint: { script: "mint.mjs", preset: [] },
+  ci: { script: "ci-monitor.mjs", preset: [] },
+  hooks: { script: "hooks.mjs", preset: [] },
+};
+
+const HELP =
+  "Usage: npx @0xray/foundry <reconcile|stamp|gate|release|docs-check|docs-build|mint|ci|hooks> [...args]\n" +
+  "\n" +
+  "Mill, not exo. FOUNDRY_ROOT overrides cwd (the repo being milled).\n" +
+  "release bumps/commits/pushes/publishes the milled cwd — pass --dry-run or --i-mean-it (or FOUNDRY_RELEASE=1).\n" +
+  "Mint overlays their plant onto project hangers (mill-fill). PPE stays worn.\n" +
+  "gate is build+test. docs-build is Docusaurus on the 0xray exo. ci reports GitHub Actions (no auto-push). hooks installs git pre/post hooks.\n";
+
+const cmd = process.argv[2];
+const rest = process.argv.slice(3);
+
+if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+if (!cmd || !COMMANDS[cmd]) {
+  process.stderr.write(HELP);
+  process.exit(1);
+}
+
+const spec = COMMANDS[cmd];
+const root = resolveMillRoot();
+const result = spawnSync(
+  process.execPath,
+  [millScript(spec.script), ...spec.preset, ...rest],
+  {
+    stdio: "inherit",
+    cwd: root,
+    env: { ...process.env, FOUNDRY_ROOT: root },
+  },
+);
+process.exit(result.status === null ? 1 : result.status);

package/scripts/foundry/docs-build.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * Mill Docusaurus build. Full corpus only on the 0xray exo (docs-site/).
+ * Stranger mills skip. Not PPE. Not an 8th MCP.
+ *
+ *   npx @0xray/foundry docs-build
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isXrayExoRepo, resolveMillRoot } from "./mill-root.mjs";
+
+function run(cmd, args, cwd) {
+  const result = spawnSync(cmd, args, { cwd, stdio: "inherit", env: process.env });
+  return result.status === null ? 1 : result.status;
+}
+
+function main() {
+  const root = resolveMillRoot();
+  if (!isXrayExoRepo(root)) {
+    process.stdout.write("docs-build: skipped (not 0xray exo with docs-site)\n");
+    process.exit(0);
+  }
+  const docs = path.join(root, "docs-site");
+  if (!fs.existsSync(path.join(docs, "node_modules"))) {
+    const install = run("npm", ["ci"], docs);
+    if (install !== 0) process.exit(install);
+  }
+  process.exit(run("npm", ["run", "build"], docs));
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main();
+}

package/scripts/foundry/hooks.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Mill git hooks: install pre-commit / post-commit / pre-push / post-push.
+ * Wear-time installer lives at scripts/hooks/install-hooks.cjs (dogfood)
+ * or node_modules/0xray/scripts/hooks/install-hooks.cjs (published mill).
+ *
+ *   npx @0xray/foundry hooks
+ */
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveHookInstaller, resolveMillRoot } from "./mill-root.mjs";
+
+function main() {
+  const root = resolveMillRoot();
+  const installer = resolveHookInstaller(root);
+  if (!installer) {
+    process.stderr.write(
+      "mill hooks: no install-hooks.cjs (dogfood scripts/hooks or node_modules/0xray/scripts/hooks)\n",
+    );
+    process.exit(1);
+  }
+  const result = spawnSync(process.execPath, [installer, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    cwd: root,
+    env: { ...process.env, FOUNDRY_ROOT: root },
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main();
+}