0xray 3.3.1 → 3.4.1

package/.opencode/enforcer-config.json

@@ -1,7 +1,5 @@
 {
-  "framework": "xray 2.0",
-  "version": "3.1.0",
-  "description": "Codex-compliant framework configuration for Credible UI project",
+  "description": "Codex-compliant framework configuration",
   "thresholds": {
     "bundleSize": {
       "maxSize": "3MB",
@@ -220,7 +218,6 @@
       }
     },
     "codex": {
-      "version": "3.1.0",
       "terms": [
         1,
         2,

package/dist/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://www.conventionalcommits.org/).
 
+## [3.4.1] - 2026-06-17
+
+### ✨ Features
+- Unified 4-platform bridge installer (`install-bridges.cjs`) runs on consumer `npm i 0xray` postinstall — OpenCode, Grok, Hermes, OpenClaw
+- All 7 MCP servers registered via `npx -y 0xray mcp <cmd>` (no brittle `dist/` paths)
+- `npx 0xray grok install` aligned with postinstall: 7 servers via npx, idempotent skill/MCP sync on re-run
+- Grok skills synced to both `~/.grok/plugins/0xray/skills/` and `~/.grok/skills/` (Grok Build / Cursor)
+
+### 🐛 Bug Fixes
+- `setup.cjs` consumer detection uses `isConsumerInstall()` — works for both `node_modules/0xray` and `node_modules/xray`
+- Hermes bridge honors `XRAY_ROOT` env and `xray-consumer-root.txt` marker for correct project root resolution
+
 ## [3.3.0] - 2026-06-18
 
 ### 🔄 Changes

package/dist/analytics/routing-refiner.js

@@ -35,7 +35,6 @@ class RoutingRefiner {
         const optimizations = this.suggestMappingOptimizations(promptAnalysis, performanceReport);
         const warnings = this.generateWarnings(newMappings, optimizations);
         return {
-            version: "3.1.0",
             generatedAt: new Date(),
             summary: {
                 newMappings: newMappings.length,
@@ -247,7 +246,6 @@ class RoutingRefiner {
         lines.push("╚════════════════════════════════════════════════════════════╝");
         lines.push("");
         lines.push(`Generated: ${report.configurationUpdate.generatedAt.toISOString()}`);
-        lines.push(`Version: ${report.configurationUpdate.version}`);
         lines.push("");
         lines.push("=== Summary ===");
         lines.push(`New Mappings: ${report.configurationUpdate.summary.newMappings}`);

package/dist/core/boot-orchestrator.js

@@ -1,6 +1,7 @@
 /**
  * Boot Orchestrator (min documented consumer runtime compat shim from prior 0xRay releases; primary Xray paths + .xray fallbacks only; 1-line per Scope Rule).
  */
+import { readFileSync } from "fs";
 import { XrayContextLoader } from "./context-loader.js";
 import { XrayStateManager } from "../state/state-manager.js";
 import { ProcessorManager } from "../processors/processor-manager.js";
@@ -721,7 +722,14 @@ export class BootOrchestrator {
         try {
             // Consumer runtime compat shim from prior 0xRay releases (1-line min per Scope Rule; primary xray paths + .xray fallbacks)
             const xrayConfig = {
-                version: "3.1.0",
+                version: (() => {
+                    try {
+                        return JSON.parse(readFileSync(path.join(process.cwd(), "package.json"), "utf-8")).version;
+                    }
+                    catch {
+                        return "unknown";
+                    }
+                })(),
                 codex_enabled: true,
                 codex_version: "v1.7.5",
                 codex_terms: [

package/dist/core/features-config.js

@@ -285,7 +285,6 @@ export class FeaturesConfigLoader {
      */
     getDefaultConfig() {
         return {
-            version: "3.1.0",
             description: "0xRay Framework - Unified Feature Configuration",
             token_optimization: {
                 enabled: true,

package/dist/integrations/grok/grok-cli.js

@@ -18,9 +18,44 @@ import { frameworkLogger } from '../../core/framework-logger.js';
 import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
+import { createRequire } from 'module';
 import { syncBuiltinSkills } from '../../cli/commands/skill-install.js';
 // ESM-compatible __dirname (this file is compiled to ESM)
 const __dirname = path.dirname(new URL(import.meta.url).pathname);
+const packageRoot = path.resolve(__dirname, '..', '..', '..');
+const requireCjs = createRequire(import.meta.url);
+const { resolveConsumerTargetDir } = requireCjs(path.join(packageRoot, 'scripts/node/install-bridges.cjs'));
+/** Canonical 7-server MCP surface — matches install-bridges.cjs and package .mcp.json */
+const XRAY_MCP_SERVERS = [
+    { name: 'xray-governance', mcpCmd: 'governance', env: { XRAY_FORCE_MCP_GOVERNANCE: 'true' } },
+    { name: 'xray-skills', mcpCmd: 'skills', env: {} },
+    { name: 'xray-orchestrator', mcpCmd: 'orchestrator', env: {} },
+    { name: 'xray-enforcer', mcpCmd: 'enforcer', env: {} },
+    { name: 'xray-researcher', mcpCmd: 'researcher', env: {} },
+    { name: 'xray-code-review', mcpCmd: 'code-review', env: {} },
+    { name: 'xray-architect-tools', mcpCmd: 'architect-tools', env: {} },
+];
+function registerGrokMcpServers(targetDir) {
+    try {
+        execSync('which grok', { stdio: 'ignore' });
+    }
+    catch {
+        console.log('[Grok] grok CLI not on PATH — plugin .mcp.json still configured');
+        return;
+    }
+    for (const s of XRAY_MCP_SERVERS) {
+        try {
+            const envEntries = { ...s.env, XRAY_ROOT: targetDir };
+            const envFlags = Object.entries(envEntries)
+                .map(([k, v]) => `--env "${k}=${v}"`)
+                .join(' ');
+            execSync(`grok mcp add ${s.name} --command npx --args "-y" "0xray" "mcp" "${s.mcpCmd}" ${envFlags}`, { stdio: 'pipe' });
+        }
+        catch {
+            // already registered or grok config conflict — non-blocking
+        }
+    }
+}
 export async function installForGrokCLI(options = {}) {
     frameworkLogger.log('grok-integration', 'install-start', 'info', { options });
     const home = process.env.HOME || process.env.USERPROFILE || '';
@@ -39,15 +74,18 @@ export async function installForGrokCLI(options = {}) {
         console.log(`[Grok] Dry run: Would copy plugin from ${sourceDir} → ${targetPluginDir}`);
         return;
     }
+    const targetDir = resolveConsumerTargetDir(packageRoot, process.cwd());
     try {
-        if (fs.existsSync(targetPluginDir) && !options.force) {
+        const pluginExists = fs.existsSync(targetPluginDir);
+        if (pluginExists && !options.force) {
             console.log('[Grok] 0xray Grok plugin is already installed.');
-            console.log('Use --force to reinstall.');
-            return;
+            console.log('Use --force to reinstall plugin files.');
+        }
+        else {
+            fs.cpSync(sourceDir, targetPluginDir, { recursive: true, force: true });
+            frameworkLogger.log('grok-integration', 'plugin-copied', 'info', { destination: targetPluginDir });
+            console.log(`\x1b[32m✓ Copied Grok plugin to ${targetPluginDir}\x1b[0m`);
         }
-        fs.cpSync(sourceDir, targetPluginDir, { recursive: true, force: true });
-        frameworkLogger.log('grok-integration', 'plugin-copied', 'info', { destination: targetPluginDir });
-        console.log(`\x1b[32m✓ Copied Grok plugin to ${targetPluginDir}\x1b[0m`);
         // Sync builtin skills to Grok plugin skills dir
         const grokSkillsDir = path.join(targetPluginDir, 'skills');
         const skillsCopied = syncBuiltinSkills(grokSkillsDir);
@@ -70,25 +108,9 @@ export async function installForGrokCLI(options = {}) {
             console.log('\nPlease run this command to fully trust the plugin:');
             console.log(`  grok plugins trust "${targetPluginDir}"`);
         }
-        // Register MCP servers via grok mcp add (most reliable mechanism)
-        const govMcpPath = path.resolve(__dirname, '..', '..', '..', 'dist/mcps/governance.server.js');
-        const skillsMcpPath = path.resolve(__dirname, '..', '..', '..', 'dist/mcps/knowledge-skills/skill-invocation.server.js');
-        const orchMcpPath = path.resolve(__dirname, '..', '..', '..', 'dist/mcps/orchestrator.server.js');
-        const enforcerMcpPath = path.resolve(__dirname, '..', '..', '..', 'dist/mcps/enforcer-tools.server.js');
-        try {
-            execSync(`grok mcp add xray-governance --command node --args "${govMcpPath}" --env "XRAY_FORCE_MCP_GOVERNANCE=true" --env "XRAY_ROOT=${process.cwd()}"`, { stdio: 'pipe' });
-            execSync(`grok mcp add xray-skills --command node --args "${skillsMcpPath}" --env "XRAY_ROOT=${process.cwd()}"`, { stdio: 'pipe' });
-            execSync(`grok mcp add xray-orchestrator --command node --args "${orchMcpPath}" --env "XRAY_ROOT=${process.cwd()}"`, { stdio: 'pipe' });
-            execSync(`grok mcp add xray-enforcer --command node --args "${enforcerMcpPath}" --env "XRAY_ROOT=${process.cwd()}"`, { stdio: 'pipe' });
-            console.log('\x1b[32m✓ Registered xray MCP servers with Grok CLI\x1b[0m');
-        }
-        catch {
-            console.log('\nCould not auto-register MCP servers. Run manually:');
-            console.log(`  grok mcp add xray-governance --command node --args "${govMcpPath}"`);
-            console.log(`  grok mcp add xray-skills --command node --args "${skillsMcpPath}"`);
-            console.log(`  grok mcp add xray-orchestrator --command node --args "${orchMcpPath}"`);
-            console.log(`  grok mcp add xray-enforcer --command node --args "${enforcerMcpPath}"`);
-        }
+        // Register MCP servers via grok mcp add (npx -y 0xray mcp — matches install-bridges)
+        registerGrokMcpServers(targetDir);
+        console.log('\x1b[32m✓ Registered 7 xray MCP servers with Grok CLI (npx)\x1b[0m');
         console.log('\n✅ 0xRay is now installed as a first-class Grok CLI plugin!');
         console.log('Restart Grok or run `grok` to load the new hooks and MCP servers.');
     }

package/dist/integrations/hermes-agent/bridge.mjs

@@ -53,9 +53,19 @@ let frameworkLoadAttempted = false;
 
 // ── Project root detection ───────────────────────────────────
 function findProjectRoot() {
-  const envHome = process.env.XRAY_HOME;
+  const envHome = process.env.XRAY_HOME || process.env.XRAY_ROOT;
   if (envHome && existsSync(join(envHome, "package.json"))) return envHome;
 
+  const consumerMarker = join(__dirname, "xray-consumer-root.txt");
+  if (existsSync(consumerMarker)) {
+    try {
+      const marked = readFileSync(consumerMarker, "utf-8").trim();
+      if (marked && existsSync(join(marked, "package.json"))) return marked;
+    } catch {
+      // fall through
+    }
+  }
+
   const candidates = [
     process.cwd(),
     join(homedir(), "dev", "xray"),

package/dist/mcps/registry.json

@@ -1,5 +1,4 @@
 {
-  "version": "3.1.0",
   "description": "0xRay Community MCPs Registry - curated API-focused MCP servers",
   "sources": [
     {

package/dist/orchestrator/universal-registry-bridge.js

@@ -113,7 +113,7 @@ export class UniversalRegistryBridge {
                 currentAgent = {
                     name: nameMatch[1].trim(),
                     description: "",
-                    version: "3.1.0",
+                    version: "",
                 };
                 inAgent = true;
                 continue;

package/dist/skills/registry.json

@@ -1,5 +1,4 @@
 {
-  "version": "3.1.0",
   "description": "0xRay Skills Registry - recommended skill sources for consumers",
   "sources": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
   "readme": "README.md",
   "license": "MIT",

package/scripts/node/enforce-agents-md.mjs

@@ -1,12 +1,5 @@
 #!/usr/bin/env node
 /**
- * AGENTS.md Enforcement Script
- * 
- * Validates that AGENTS.md exists, is up-to-date, and follows the required format.
- * This script should be run in CI/CD, pre-commit hooks, and local validation.
- * 
- * @version 1.0.0
- * @framework xray v2
  */
 
 import fs from 'fs';
@@ -62,7 +55,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Run all validation checks
    */
   async validate() {
     console.log('🔍 AGENTS.md Enforcement Check');
@@ -148,14 +140,12 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Check if AGENTS.md file exists
    */
   checkFileExists() {
     return fs.existsSync(this.agentsPath);
   }
 
   /**
-   * Check for required sections
    */
   checkRequiredSections(content) {
     const missing = [];
@@ -188,7 +178,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Check for required agent definitions
    */
   checkRequiredAgents(content) {
     // Be flexible - check for agent names with or without @ prefix
@@ -199,7 +188,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Extract version from header
    */
   extractVersion(content) {
     const match = content.match(/\*\*Version\*\*:\s*(\d+\.\d+\.\d+)/);
@@ -207,7 +195,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Extract date from header
    */
   extractDate(content) {
     const match = content.match(/\*\*Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/);
@@ -215,7 +202,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Calculate how many days old the file is
    */
   calculateDaysOld(dateString) {
     const date = new Date(dateString);
@@ -225,18 +211,12 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Calculate content hash
    */
   calculateHash(content) {
     return crypto.createHash('sha256').update(content).digest('hex');
   }
 
   /**
-   * Count codex terms (numbered rules or sections with multiple items)
-   * Looks for patterns like:
-   * - #### 1. Something
-   * - 1. **Something**
-   * - ## CRITICAL RULES (count as one term block)
    */
   countCodexTerms(content) {
     // Count #### numbered items
@@ -257,7 +237,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Log individual check result
    */
   logResult(check, status, message) {
     const icon = status === 'PASS' ? '✅' : status === 'FAIL' ? '❌' : status === 'WARN' ? '⚠️' : 'ℹ️';
@@ -266,7 +245,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Generate and display report
    */
   report(exitCode) {
     console.log('\n================================');
@@ -309,7 +287,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Auto-generate AGENTS.md from current agent configuration
    */
   async generate() {
     console.log('📝 Generating AGENTS.md...\n');
@@ -325,7 +302,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Load template file
    */
   async loadTemplate() {
     const templatePath = path.join(__dirname, '..', '..', '..', 'docs', 'AGENTS_TEMPLATE.md');
@@ -342,7 +318,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Discover agents from configuration
    */
   async discoverAgents() {
     const agents = [];
@@ -366,7 +341,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Populate template with agent data
    */
   populateTemplate(template, agents) {
     const now = new Date().toISOString().split('T')[0];

package/scripts/node/enforce-version-compliance.sh

@@ -7,7 +7,6 @@
 #
 # Usage: ./scripts/node/enforce-version-compliance.sh
 #
-# @version 1.0.0
 # @since 2026-01-15
 
 set -e

package/scripts/node/enforce-version-compliance.ts

@@ -1,15 +1,5 @@
 #!/usr/bin/env node
 /**
- * Version Compliance Enforcement Script
- *
- * Thin CLI wrapper around VersionComplianceProcessor.
- * Called by CI/CD, pre-commit hooks, and manual runs.
- *
- * This script should NOT contain enforcement logic - 
- * all logic lives in src/processors/version-compliance-processor.ts
- *
- * @version 1.0.0
- * @deprecated Use VersionComplianceProcessor directly in new code
  */
 
 import path from 'path';

package/scripts/node/install-bridges.cjs

@@ -10,19 +10,37 @@ const os = require("os");
 const { execSync } = require("child_process");
 
 const SKIP_DIRS = new Set(["node_modules", "logs"]);
-const MERGE_FILES = new Set(["xray/features.json", "enforcer-config.json"]);
+const MERGE_FILES = new Set(["enforcer-config.json"]);
 const KEEP_IF_EXISTS = new Set([".yml", ".yaml", ".md"]);
 
+/** Canonical 7-server MCP surface — matches package .mcp.json and Grok plugin */
+const XRAY_MCP_SERVERS = [
+  { name: "xray-governance", mcpCmd: "governance", env: { XRAY_FORCE_MCP_GOVERNANCE: "true" } },
+  { name: "xray-skills", mcpCmd: "skills", env: {} },
+  { name: "xray-orchestrator", mcpCmd: "orchestrator", env: {} },
+  { name: "xray-enforcer", mcpCmd: "enforcer", env: {} },
+  { name: "xray-researcher", mcpCmd: "researcher", env: {} },
+  { name: "xray-code-review", mcpCmd: "code-review", env: {} },
+  { name: "xray-architect-tools", mcpCmd: "architect-tools", env: {} },
+];
+
 function resolveConsumerTargetDir(packageRoot, fallbackDir) {
-  const resolvedPackage = path.resolve(packageRoot);
-  if (resolvedPackage.includes(`${path.sep}node_modules${path.sep}`)) {
-    let current = resolvedPackage;
-    while (current.includes(`${path.sep}node_modules${path.sep}`)) {
-      current = path.dirname(current);
-    }
-    return current;
+  const resolved = path.resolve(packageRoot);
+  const inNodeModules =
+    resolved.includes(`${path.sep}node_modules${path.sep}`) ||
+    resolved.endsWith(`${path.sep}node_modules`);
+
+  if (!inNodeModules) {
+    return fallbackDir || process.env.PWD || process.cwd();
+  }
+
+  let current = resolved;
+  while (path.basename(current) !== "node_modules") {
+    const parent = path.dirname(current);
+    if (parent === current) return fallbackDir || process.cwd();
+    current = parent;
   }
-  return fallbackDir || process.env.PWD || process.cwd();
+  return path.dirname(current);
 }
 
 function isConsumerInstall(packageRoot, targetDir) {
@@ -108,6 +126,91 @@ function copyPluginDir(src, dest) {
   return true;
 }
 
+function buildConsumerMcpConfig(targetDir) {
+  const mcpServers = {};
+  for (const s of XRAY_MCP_SERVERS) {
+    mcpServers[s.name] = {
+      command: "npx",
+      args: ["-y", "0xray", "mcp", s.mcpCmd],
+      env: { ...s.env, XRAY_ROOT: targetDir },
+    };
+  }
+  return { mcpServers };
+}
+
+function deployProjectMcpJson(targetDir, log) {
+  const destPath = path.join(targetDir, ".mcp.json");
+  const consumerConfig = buildConsumerMcpConfig(targetDir);
+  let existing = { mcpServers: {} };
+  if (fs.existsSync(destPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(destPath, "utf8"));
+    } catch {
+      existing = { mcpServers: {} };
+    }
+  }
+  const merged = {
+    ...existing,
+    mcpServers: { ...(existing.mcpServers || {}), ...consumerConfig.mcpServers },
+  };
+  fs.writeFileSync(destPath, JSON.stringify(merged, null, 2) + "\n");
+  log("mcp-config", "project .mcp.json deployed (7 xray servers)", "info");
+}
+
+function writePluginMcpJson(pluginDir, targetDir, log, label) {
+  if (!fs.existsSync(pluginDir)) return;
+  const dest = path.join(pluginDir, ".mcp.json");
+  fs.writeFileSync(dest, JSON.stringify(buildConsumerMcpConfig(targetDir), null, 2) + "\n");
+  log(label, "plugin .mcp.json patched for consumer", "info");
+}
+
+function mergeOpencodeJson(targetDir, packageRoot, log) {
+  const rootOpencode = path.join(packageRoot, "opencode.json");
+  const userOpencode = path.join(targetDir, "opencode.json");
+  if (!fs.existsSync(rootOpencode)) return;
+
+  try {
+    const srcData = JSON.parse(fs.readFileSync(rootOpencode, "utf8"));
+    if (fs.existsSync(userOpencode)) {
+      const destData = JSON.parse(fs.readFileSync(userOpencode, "utf8"));
+      const merged = { ...destData };
+      if (srcData.agent) merged.agent = srcData.agent;
+      if (srcData.mcp) merged.mcp = { ...destData.mcp, ...srcData.mcp };
+      if (srcData.compaction) merged.compaction = srcData.compaction;
+      fs.writeFileSync(userOpencode, JSON.stringify(merged, null, 2) + "\n");
+    } else {
+      fs.copyFileSync(rootOpencode, userOpencode);
+    }
+    log("opencode-bridge", "opencode.json merged", "info");
+  } catch (e) {
+    log("opencode-bridge", "opencode.json merge failed", "warn", { error: e.message });
+  }
+}
+
+function patchGrokHooks(pluginDir, packageRoot, targetDir, log, label) {
+  const hooksPath = path.join(pluginDir, "hooks", "hooks.json");
+  const hookScript = path.join(packageRoot, "dist", "integrations", "grok", "hooks", "pre-tool-use.js");
+  if (!fs.existsSync(hooksPath)) return;
+
+  try {
+    const hooks = JSON.parse(fs.readFileSync(hooksPath, "utf8"));
+    const preTool = hooks.hooks?.PreToolUse?.[0]?.hooks?.[0];
+    if (preTool && fs.existsSync(hookScript)) {
+      preTool.command = "node";
+      preTool.args = [hookScript];
+      preTool.env = {
+        ...(preTool.env || {}),
+        XRAY_ROOT: targetDir,
+        XRAY_AI_PATH: packageRoot,
+      };
+      fs.writeFileSync(hooksPath, JSON.stringify(hooks, null, 2) + "\n");
+      log(label, "hooks.json patched → enforcement gate", "info");
+    }
+  } catch (e) {
+    log(label, "hooks.json patch failed", "warn", { error: e.message });
+  }
+}
+
 function installOpencodeBridge(targetDir, packageRoot, log) {
   const opencodeSource = path.join(packageRoot, ".opencode");
   const opencodeDest = path.join(targetDir, ".opencode");
@@ -149,37 +252,25 @@ function findGrokPluginSource(packageRoot) {
   return candidates.find((p) => fs.existsSync(p));
 }
 
-function registerGrokMcpServers(packageRoot, targetDir, log) {
+function registerGrokMcpServers(targetDir, log) {
   try {
     execSync("which grok", { stdio: "ignore" });
   } catch {
-    log("grok-bridge", "grok CLI not on PATH — skipped MCP registration", "info");
+    log("grok-bridge", "grok CLI not on PATH — plugin .mcp.json still configured", "info");
     return;
   }
 
-  const govServer = path.join(packageRoot, "dist/mcps/governance.server.js");
-  const skillsServer = path.join(packageRoot, "dist/mcps/knowledge-skills/skill-invocation.server.js");
-  const orchServer = path.join(packageRoot, "dist/mcps/orchestrator.server.js");
-  const enforcerServer = path.join(packageRoot, "dist/mcps/enforcer-tools.server.js");
-
-  const servers = [
-    ["xray-governance", govServer, `XRAY_FORCE_MCP_GOVERNANCE=true`],
-    ["xray-skills", skillsServer, null],
-    ["xray-orchestrator", orchServer, null],
-    ["xray-enforcer", enforcerServer, null],
-  ];
-
-  for (const [name, serverPath, extraEnv] of servers) {
-    if (!fs.existsSync(serverPath)) continue;
+  for (const s of XRAY_MCP_SERVERS) {
     try {
-      const envFlags = extraEnv
-        ? `--env "${extraEnv}" --env "XRAY_ROOT=${targetDir}"`
-        : `--env "XRAY_ROOT=${targetDir}"`;
+      const envEntries = { ...s.env, XRAY_ROOT: targetDir };
+      const envFlags = Object.entries(envEntries)
+        .map(([k, v]) => `--env "${k}=${v}"`)
+        .join(" ");
       execSync(
-        `grok mcp add ${name} --command node --args "${serverPath}" ${envFlags}`,
+        `grok mcp add ${s.name} --command npx --args "-y" "0xray" "mcp" "${s.mcpCmd}" ${envFlags}`,
         { stdio: "pipe" }
       );
-      log("grok-bridge", `registered ${name}`, "info");
+      log("grok-bridge", `registered ${s.name} (npx)`, "info");
     } catch {
       // already registered or grok config conflict — non-blocking
     }
@@ -217,6 +308,8 @@ function installGrokBridge(targetDir, packageRoot, log) {
     if (copyPluginDir(sourceDir, dest)) {
       const rel = dest.startsWith(home) ? dest.replace(home, "~") : path.relative(targetDir, dest);
       log("grok-bridge", "plugin copied", "info", { path: rel || dest });
+      writePluginMcpJson(dest, targetDir, log, "grok-bridge");
+      patchGrokHooks(dest, packageRoot, targetDir, log, "grok-bridge");
       const copied = syncBuiltinSkills(path.join(dest, "skills"), packageRoot);
       if (copied > 0) log("grok-bridge", `plugin skills synced (${copied})`, "info", { path: rel });
     }
@@ -229,10 +322,10 @@ function installGrokBridge(targetDir, packageRoot, log) {
     log("grok-bridge", `global skills synced (${globalCopied})`, "info", { path: "~/.grok/skills/" });
   }
 
-  registerGrokMcpServers(packageRoot, targetDir, log);
+  registerGrokMcpServers(targetDir, log);
 }
 
-function installHermesBridge(packageRoot, log) {
+function installHermesBridge(targetDir, packageRoot, log) {
   const sources = [
     path.join(packageRoot, "dist", "integrations", "hermes-agent"),
     path.join(packageRoot, "src", "integrations", "hermes-agent"),
@@ -256,8 +349,15 @@ function installHermesBridge(packageRoot, log) {
   }
   log("hermes-bridge", "plugin copied", "info", { path: "~/.hermes/plugins/xray-hermes" });
 
+  writePluginMcpJson(targetPluginDir, targetDir, log, "hermes-bridge");
+
   const copied = syncBuiltinSkills(path.join(targetPluginDir, "skills"), packageRoot);
   if (copied > 0) log("hermes-bridge", `skills synced (${copied})`, "info");
+
+  // Marker so bridge.mjs resolves the consumer project on hook invocation
+  const rootMarker = path.join(targetPluginDir, "xray-consumer-root.txt");
+  fs.writeFileSync(rootMarker, targetDir + "\n");
+  log("hermes-bridge", "consumer root marker written", "info");
 }
 
 function installOpenclawBridge(targetDir, packageRoot, log) {
@@ -347,9 +447,11 @@ function installAllBridges(opts) {
   log("install-bridges", "starting 4-platform install", "info");
 
   deployXrayConfig(targetDir, packageRoot, log);
+  deployProjectMcpJson(targetDir, log);
+  mergeOpencodeJson(targetDir, packageRoot, log);
   installOpencodeBridge(targetDir, packageRoot, log);
   installGrokBridge(targetDir, packageRoot, log);
-  installHermesBridge(packageRoot, log);
+  installHermesBridge(targetDir, packageRoot, log);
   installOpenclawBridge(targetDir, packageRoot, log);
   installGitHooks(packageRoot, log);
 

package/scripts/node/pre-publish-guard.js

@@ -92,6 +92,7 @@ function checkGitStatus() {
       'logs/',
       'backups/',
       'Users/',
+      '.xray/inference/',
     ];
     
     const realChanges = lines.filter(l => {
@@ -128,32 +129,35 @@ function checkGitStatus() {
 
 function checkVersionSync() {
   log('Checking version synchronization...', 'step');
-  
-  // Load version manager
+
+  const pkgPath = path.join(rootDir, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  const pkgVersion = pkg.version;
+
   const vmPath = path.join(rootDir, 'scripts/node/universal-version-manager.js');
   const vmContent = fs.readFileSync(vmPath, 'utf-8');
-  const versionMatch = vmContent.match(/version:\s*"([^"]+)"/);
-  
+  const usesPackageSsot =
+    vmContent.includes('readPackageVersion()') &&
+    /version:\s*PACKAGE_VERSION/.test(vmContent);
+
+  if (usesPackageSsot) {
+    log(`Version SSOT: package.json (${pkgVersion})`, 'success');
+    return true;
+  }
+
+  const versionMatch = vmContent.match(/framework:\s*\{[\s\S]*?version:\s*"([^"]+)"/);
   if (!versionMatch) {
-    errors.push('Cannot find version in version manager');
+    errors.push('Cannot find framework version in version manager');
     return false;
   }
-  
+
   const vmVersion = versionMatch[1];
-  
-  // Load package.json
-  const pkgPath = path.join(rootDir, 'package.json');
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  const pkgVersion = pkg.version;
-  
   if (pkgVersion !== vmVersion) {
-    // package.json is often 1 ahead of UVM after npm version patch — non-blocking
     warnings.push(`Version mismatch: package.json (${pkgVersion}) != version manager (${vmVersion})`);
     log(`Version mismatch: package.json=${pkgVersion}, version-manager=${vmVersion}`, 'warn');
-    return true; // non-blocking — matches pre-commit hook behavior
+  } else {
+    log(`Versions aligned: ${pkgVersion}`, 'success');
   }
-  
-  log(`Versions aligned: ${pkgVersion}`, 'success');
   return true;
 }
 

package/scripts/node/setup.cjs

@@ -6,7 +6,7 @@ const path = require("path");
 const packageRoot = path.join(__dirname, "..", "..");
 const homeDir = require("os").homedir();
 
-const { resolveConsumerTargetDir } = require("./install-bridges.cjs");
+const { resolveConsumerTargetDir, isConsumerInstall } = require("./install-bridges.cjs");
 let targetDir = resolveConsumerTargetDir(packageRoot, process.env.PWD || process.cwd());
 
 const resolvedPackage = path.resolve(packageRoot);
@@ -155,8 +155,13 @@ if (fs.existsSync(distSource)) {
 }
 
 // 6. Convert MCP paths in consumer opencode.json
-const isConsumer = fs.existsSync(path.join(targetDir, "node_modules", "xray", "package.json"));
-if (!hasHermes && isConsumer) {
+const isConsumer = isConsumerInstall(packageRoot, targetDir);
+const consumerPkgName = isConsumer
+  ? ["0xray", "xray"].find((name) =>
+      fs.existsSync(path.join(targetDir, "node_modules", name, "package.json"))
+    )
+  : null;
+if (!hasHermes && isConsumer && consumerPkgName) {
   const mainOpencodePath = path.join(targetDir, "opencode.json");
   if (fs.existsSync(mainOpencodePath)) {
     try {
@@ -167,13 +172,13 @@ if (!hasHermes && isConsumer) {
           if (server.command && typeof server.command === "string") {
             const normalized = server.command.replace(
               /^[.]{0,2}\/dist\/mcps\//,
-              "node_modules/xray/dist/mcps/"
+              `node_modules/${consumerPkgName}/dist/mcps/`
             );
             if (normalized !== server.command) { server.command = normalized; modified = true; }
           }
           if (Array.isArray(server.command)) {
             server.command = server.command.map(a =>
-              a.replace(/^[.]{0,2}\/dist\/mcps\//, "node_modules/xray/dist/mcps/")
+              a.replace(/^[.]{0,2}\/dist\/mcps\//, `node_modules/${consumerPkgName}/dist/mcps/`)
             );
             modified = true;
           }

package/scripts/node/universal-version-manager.js

@@ -17,7 +17,6 @@
  * - Historical docs (docs/reflections, docs/archive)
  * - Test files with assertions
  *
- * @version 2.0.0
  * @since 2026-01-15
  * @updated 2026-03-09 - Enhanced with documentation management, validation, and backup
  */
@@ -28,6 +27,19 @@ const require = createRequire(import.meta.url);
 import fs from "fs";
 import path from "path";
 import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "../..");
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf-8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
 
 /**
  * Auto-calculate framework counts from filesystem
@@ -133,12 +145,14 @@ const CALCULATED_COUNTS = calculateCounts();
  * Framework version information - SINGLE SOURCE OF TRUTH
  * Version manager updates this, then propagates to all files
  */
+const PACKAGE_VERSION = readPackageVersion();
+
 const OFFICIAL_VERSIONS = {
-  // Framework version
+  // Framework version — SSOT: package.json
   framework: {
-    version: "3.3.0",
+    version: PACKAGE_VERSION,
       displayName: "xray: Self-Healing AI Governance OS",
-      lastUpdated: "2026-06-18",
+      lastUpdated: "2026-06-17",
     // Counts (auto-calculated, but can be overridden)
     ...CALCULATED_COUNTS,
   },

package/src/mcps/registry.json

@@ -1,5 +1,4 @@
 {
-  "version": "3.1.0",
   "description": "0xRay Community MCPs Registry - curated API-focused MCP servers",
   "sources": [
     {

package/src/opencode/enforcer-config.json

@@ -1,7 +1,5 @@
 {
-  "framework": "xray 2.0",
-  "version": "3.1.0",
-  "description": "Codex-compliant framework configuration for Credible UI project",
+  "description": "Codex-compliant framework configuration",
   "thresholds": {
     "bundleSize": {
       "maxSize": "3MB",
@@ -220,7 +218,6 @@
       }
     },
     "codex": {
-      "version": "3.1.0",
       "terms": [
         1,
         2,

package/src/skills/registry.json

@@ -1,5 +1,4 @@
 {
-  "version": "3.1.0",
   "description": "0xRay Skills Registry - recommended skill sources for consumers",
   "sources": [
     {