Skip to main content

Consumer Migration & Integration Guide (v3.4+)

Audience: Plugin authors, bridge maintainers (Hermes, OpenClaw, Grok Build, OpenCode), and projects that consume 0xray directly.

Temperament on upgrade (v4.0)​

Existing .xray/features.json without suit_temperament stays guided (full spawn-plan deny). Postinstall merge will not silently frontier a Grok consumer. New installs copy shipped profile: "auto" (Grok → frontier, Hermes/OpenCode → guided). See Suit temperament.

Quick Start for v3 Consumers​

npm install 0xray
npx 0xray wear

Wear writes the consumer suit, including when npm did not run the install script. When that script does run, it symlinks vendored @0xray/repertoire into node_modules and prints npx 0xray wear. Wear then:

StepAction
1AGENTS-consumer.md → project AGENTS.md
2.gitignore.default → .gitignore (if absent)
3Deploy .xray/ (codex.json, features.json, config.json)
4Write project .mcp.json with 7 MCP servers
5Install 4 chat bridges: OpenCode, Grok, Hermes, OpenClaw, plus Cursor .cursor/hooks.json
6Fasten mill plant (mill + inspect). Fasten is foundry-plant/0. "plant": "@0xray/blip" (aliases blip/sound) fastens whatever that mill declares. Nested mill @0xray/foundry@0.1.12. The mill suit also wears every catalog skill and every role file. A blip or sound seat fastens that plant only.
7Optional git pre-commit hook. Factory hangar shops coexist via shopPlant

Manual install (idempotent, same outcome):

npx 0xray opencode install
npx 0xray grok install
npx 0xray hermes install
npx 0xray openclaw install
npx 0xray setup # optional extras

Seven MCP Servers (v3.4.1)​

All consumer MCP servers use npx -y 0xray mcp <cmd> — no dist/ subpath hacks:

ServerCommand
xray-governancemcp governance
xray-skillsmcp skills
xray-orchestratormcp orchestrator
xray-enforcermcp enforcer
xray-researchermcp researcher
xray-code-reviewmcp code-review
xray-architect-toolsmcp architect-tools

Grok plugin MCP config shares the same XRAY_MCP_SERVERS constant as install-bridges.cjs.

Key v3 Consumer Changes​

v3.4.1 — Unified bridge installer​

  • install-bridges.cjs is the single consumer onboarding path (replaces scattered per-platform setup).
  • setup.cjs uses isConsumerInstall() — works for both node_modules/0xray and node_modules/xray.
  • Hermes bridge honors XRAY_ROOT env and xray-consumer-root.txt marker.
  • Grok skills sync to both ~/.grok/plugins/0xray/skills/ and ~/.grok/skills/.

v3.4 — Nucleus exports​

  • 0xray/nucleus and 0xray/nucleus/* are the supported way to reach core surfaces.
  • Internal dist/nucleus/... paths are not part of the public contract.

v3.3 — Memory routing + Repertoire​

  • Repertoire is preferred. Vendored 0.2.9 ships on. Dest is named laws, not hangar repo-*.
  • Pluggable memory_routing block in features.json (validated by features.schema.json).
  • Repertoire (@0xray/repertoire) is the default provider. Station is the compact ticket, not a substitute.
  • MemoryRoutingProvider contract: enrichTasks, getTaskConfidence, resolveThinDispatch, ingestFeedback.
  • External hosts: add repertoire-mcp to .mcp.json (repertoire__get_task_confidence, etc.).
  • See Memory Routing and Repertoire Integration.

v3.3.1 — Confidence gate​

  • Orchestrator execution planning applies a confidence gate before multi-agent dispatch.

v3.2 — Hardening​

  • Typecheck integration for orphan files, SelfProposalEngine, AsideContext.
  • Canonical release.mjs pipeline with consumer smoke gate.

v3.1.1 — Rename + marketplace​

  • StringRay → 0xRay rename complete.
  • Root .mcp.json + .grok-plugin/plugin.json for marketplace discovery.
  • ConfigLoader supports mcpServers format.
  • Removed: hermes bridge CLI (use hermes install), .opencode/xray/ fallback.

Postinstall / setup hygiene​

scripts/node/postinstall.cjs, setup.cjs, and install-bridges.cjs:

  • Walk from node_modules to consumer project root.
  • Legacy xray package name tolerance.
  • Hooks and MCPs placed correctly for node_modules and copy-to-root layouts.
  • Mill target: do not mill npm global prefix or npx _npx cache. Parent of node_modules is the mill target only when it is a real project (package.json). npm i -g mill-skips dogfood (mills the 0xray package itself, not Homebrew lib). Isolated HOME never writes passwd ~/.grok.

Verify gate (term 76)​

Every release passes npm run release:gate (or CI equivalent):

  • npm pack → fresh consumer install
  • ValidatorRegistry load (29 validators)
  • Enforcement gate from tarball
  • Nucleus plugin-registry access
  • Activity log reachability
  • Hook pipeline + MCP packaging
  • 4-bridge consumer smoke (7 MCP servers)
npm run release:gate
npm run release:npm # gate first, then npm publish — do not use a scripts.publish lifecycle

0xray (framework) vs consumer project​

ContextProposals
Framework repo (0xray)source: 'system' | 'metamorphosis', tags: ['0xray'], onChain: true
Consumer projectssource: 'agent', tags: ['<package>'], onChain: false

Automatic in inference-cycle.ts + governance-service.ts.

  • Enforcement: shared gate via plugin injection or 0xray/integration
  • Direct nucleus (advanced): 0xray/nucleus for plugin registry, governance handle
  • Logging: frameworkLogger → logs/framework/activity.log
  • Hooks: rely on postinstall; manual: npx 0xray setup

Removals / deprecations (since 3.1)​

ItemStatus
StringRay / strray-ai brandingRetired (3.1.1)
hermes bridge CLIRemoved — use hermes install
.opencode/xray/ fallbackRemoved (3.1.1)
advanced-features/Removed
PostProcessor defaultSoft-deprecated (enablePostProcessor: false)

No breaking changes for basic users​

If you only use @agent invocations, the CLI/TUI, or default plugin hook injection, v3.4+ changes are transparent.