0xray 4.0.27 → 4.0.29

package/.gitignore.default

@@ -21,6 +21,7 @@ credentials.json
 *.key
 
 # 0xray suit artifacts (postinstall / bridge install)
+.xray/state/cursor-hook-wear/
 .grok/
 .mcp.json
 opencode.json

package/.grok-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "0xray",
-  "version": "4.0.27",
+  "version": "4.0.29",
   "description": "0xRay suit for Grok, Hermes, OpenClaw, OpenCode: mill+inspect, Codex, 7 MCP servers. Costume 45/42 is opt-in foundry, not the default wear.",
   "author": {
     "name": "0xRay AI",

package/.xray/features.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./features.schema.json",
-  "version": "4.0.27",
+  "version": "4.0.29",
   "description": "0xRay Framework - Unified Feature Configuration",
   "suit_temperament": {
     "profile": "auto",

package/README.md

@@ -52,7 +52,9 @@ Docs: [guides/autonomy-command](docs-site/docs/guides/autonomy-command.md) · Sk
 | Version | Highlights |
 |---------|------------|
 | **Unreleased** | Fasten is **foundry-plant/0**: builtin plant is mill+inspect only. `foundry.json` `"plant": "@0xray/blip"` (aliases `"plant": "blip"` / `"plant": "sound"`) fastens whatever that mill declares (looker / vibe / mixer live in the mill). Nested mill `@0xray/foundry@0.1.12`. CLI shims `foundry blip\|sound` remain (0.1.11+). Shop plant first-class (`shop-extract`, `shop-witness`, `shop-pin` + `foundry.json` `shopPlant`). |
-| **4.0.27** | Host compact proof needs a generation id and a numeric usage percent, and the same preCompact receipt is mirrored to nested consumer wear roots. Memory scoring: [docs/memory-scoring.md](docs/memory-scoring.md) (orchestrator links it). Companion `@0xray/grok-bot` 0.1.6: general page vs `house/` overlay, `templates/house/`, `grok-bot house init`, doctor `GROK_BOT_HOUSE` or walk-up. Not published. |
+| **4.0.29** | `npm install` only creates the relative `node_modules/@0xray/repertoire` link to the vendored repertoire and prints `npx 0xray wear`. Run `npx 0xray wear` after install. Wear writes only the consumer project's `.cursor/hooks.json` (installed dist hooks, beside user entries); `npx 0xray unwear` restores the snapshot. Companion `@0xray/grok-bot` 0.1.8. Released 2026-09-28. |
+| **4.0.28** | MCP servers start through `scripts/node/mcp-launch.cjs` and only see PATH, HOME, XRAY_ROOT, plus names on their keep list. Tokens such as NPM_TOKEN are not inherited. User env values stay out of argv. Postinstall keeps user edits to AGENTS.md, .mcp.json, and opencode.json. `house init` does not copy EXAMPLE.md; doctor FAILs while `house/EXAMPLE.md` exists. Inspect adds a machinePlugin check. The Cursor hook defaults XRAY_ROOT to the suit. Companion `@0xray/grok-bot` 0.1.7. Released 2026-09-27. |
+| **4.0.27** | Host compact proof needs a generation id and a numeric usage percent, and the same preCompact receipt is mirrored to nested consumer wear roots. Memory scoring: [docs/memory-scoring.md](docs/memory-scoring.md) (orchestrator links it). Companion `@0xray/grok-bot` 0.1.6: general page vs `house/` overlay, `templates/house/`, `grok-bot house init`, doctor `GROK_BOT_HOUSE` or walk-up. Released 2026-09-26. |
 | **4.0.9** | Mill target: postinstall does not mill npm global prefix or `_npx` as a consumer. Isolated HOME skips machine `~/.grok`. |
 | **4.0.0** | Exo + temperament. Constitution always on; ceremony by host. Repertoire organ on (vendored 0.2). Station card survives compact/host-swap. **On npm.** [vision](docs-site/docs/architecture/v4-vision.md) · [now](docs-site/docs/architecture/v4-now.md) |
 | **3.4.1** | Unified `install-bridges.cjs` on postinstall — OpenCode, Grok, Hermes, OpenClaw in one pass. All 7 MCPs servers via `npx -y 0xray mcp <cmd>` (no `dist/` paths). Canonical `release.mjs` pipeline. |
@@ -64,7 +66,7 @@ Docs: [guides/autonomy-command](docs-site/docs/guides/autonomy-command.md) · Sk
 
 ### Consolidations
 
-- **One consumer install path** — `postinstall.cjs` → `installAllBridges()` replaces scattered per-platform setup. Mill target is the consumer project, not npm global prefix or `_npx`.
+- **Install, then wear, then setup where needed** — `npm install` runs `postinstall.cjs`, which writes nothing and prints one line: `npx 0xray wear`. `wear` and `unwear` set up or remove the Cursor suit. `npx 0xray setup` writes `.mcp.json` and the OpenCode, Grok, Hermes, and OpenClaw bridges (`install-bridges.cjs`); git hooks only with `--git-hooks`. Mill target is the consumer project, not npm global prefix or `_npx`.
 - **7-server MCP surface** — `.mcp.json` SSOT; Grok plugin and all bridges share `XRAY_MCP_SERVERS`.
 - **Dev vs consumer AGENTS** — `AGENTS.md` (framework) vs `AGENTS-consumer.md` (copied to consumer projects on install).
 - **Release pipeline** — `npm run release:patch|minor|major` → reconcile → gate → artifacts → tag → publish.

package/dist/.gitignore.default

@@ -21,6 +21,7 @@ credentials.json
 *.key
 
 # 0xray suit artifacts (postinstall / bridge install)
+.xray/state/cursor-hook-wear/
 .grok/
 .mcp.json
 opencode.json

package/dist/CHANGELOG.md

@@ -41,6 +41,22 @@ The format is based on [Conventional Commits](https://www.conventionalcommits.or
 - Archive root `integrations/` costume SKILL dump → `docs/archive/integrations-costume/`. Live wear is `src/integrations`.
 - Archive root `commands/` stale copy → `docs/archive/commands-copy/`. Live wear is `src/opencode/commands`.
 
+## [4.0.29] - 2026-09-28
+
+Next patch after npm `4.0.28`. Released 2026-09-28.
+
+`npm install` now only creates the relative `node_modules/@0xray/repertoire` link to the vendored repertoire and prints one line: `npx 0xray wear`. It no longer writes the suit. Run `npx 0xray wear` after install. Wear writes only the consumer project's `.cursor/hooks.json`, pointing at the installed package's dist hooks, and adds them beside existing user entries. It snapshots the pre-wear file under `.xray/state/cursor-hook-wear/`, and `npx 0xray unwear` restores it. `npx 0xray setup` writes `.mcp.json` and the OpenCode, Grok, Hermes, and OpenClaw bridges. Companion package `@0xray/grok-bot` is unchanged at 0.1.8.
+
+---
+
+## [4.0.28] - 2026-09-26
+
+Next patch after npm `4.0.27`. Released 2026-09-27.
+
+MCP servers start through `scripts/node/mcp-launch.cjs` and only see PATH, HOME, and XRAY_ROOT, plus the names on their keep list. Tokens such as NPM_TOKEN are no longer inherited. User env values stay out of argv. Postinstall keeps user edits to AGENTS.md, .mcp.json, and opencode.json. `house init` no longer copies EXAMPLE.md, and doctor FAILs while `house/EXAMPLE.md` exists. Inspect has a new machinePlugin check. The Cursor hook defaults XRAY_ROOT to the suit directory. Companion package `@0xray/grok-bot@0.1.7`.
+
+---
+
 ## [4.0.27] - 2026-09-25
 
 Next patch after npm `4.0.26`. Released 2026-09-26.

package/dist/README.md

@@ -52,7 +52,9 @@ Docs: [guides/autonomy-command](docs-site/docs/guides/autonomy-command.md) · Sk
 | Version | Highlights |
 |---------|------------|
 | **Unreleased** | Fasten is **foundry-plant/0**: builtin plant is mill+inspect only. `foundry.json` `"plant": "@0xray/blip"` (aliases `"plant": "blip"` / `"plant": "sound"`) fastens whatever that mill declares (looker / vibe / mixer live in the mill). Nested mill `@0xray/foundry@0.1.12`. CLI shims `foundry blip\|sound` remain (0.1.11+). Shop plant first-class (`shop-extract`, `shop-witness`, `shop-pin` + `foundry.json` `shopPlant`). |
-| **4.0.27** | Host compact proof needs a generation id and a numeric usage percent, and the same preCompact receipt is mirrored to nested consumer wear roots. Memory scoring: [docs/memory-scoring.md](docs/memory-scoring.md) (orchestrator links it). Companion `@0xray/grok-bot` 0.1.6: general page vs `house/` overlay, `templates/house/`, `grok-bot house init`, doctor `GROK_BOT_HOUSE` or walk-up. Not published. |
+| **4.0.29** | `npm install` only creates the relative `node_modules/@0xray/repertoire` link to the vendored repertoire and prints `npx 0xray wear`. Run `npx 0xray wear` after install. Wear writes only the consumer project's `.cursor/hooks.json` (installed dist hooks, beside user entries); `npx 0xray unwear` restores the snapshot. Companion `@0xray/grok-bot` 0.1.8. Released 2026-09-28. |
+| **4.0.28** | MCP servers start through `scripts/node/mcp-launch.cjs` and only see PATH, HOME, XRAY_ROOT, plus names on their keep list. Tokens such as NPM_TOKEN are not inherited. User env values stay out of argv. Postinstall keeps user edits to AGENTS.md, .mcp.json, and opencode.json. `house init` does not copy EXAMPLE.md; doctor FAILs while `house/EXAMPLE.md` exists. Inspect adds a machinePlugin check. The Cursor hook defaults XRAY_ROOT to the suit. Companion `@0xray/grok-bot` 0.1.7. Released 2026-09-27. |
+| **4.0.27** | Host compact proof needs a generation id and a numeric usage percent, and the same preCompact receipt is mirrored to nested consumer wear roots. Memory scoring: [docs/memory-scoring.md](docs/memory-scoring.md) (orchestrator links it). Companion `@0xray/grok-bot` 0.1.6: general page vs `house/` overlay, `templates/house/`, `grok-bot house init`, doctor `GROK_BOT_HOUSE` or walk-up. Released 2026-09-26. |
 | **4.0.9** | Mill target: postinstall does not mill npm global prefix or `_npx` as a consumer. Isolated HOME skips machine `~/.grok`. |
 | **4.0.0** | Exo + temperament. Constitution always on; ceremony by host. Repertoire organ on (vendored 0.2). Station card survives compact/host-swap. **On npm.** [vision](docs-site/docs/architecture/v4-vision.md) · [now](docs-site/docs/architecture/v4-now.md) |
 | **3.4.1** | Unified `install-bridges.cjs` on postinstall — OpenCode, Grok, Hermes, OpenClaw in one pass. All 7 MCPs servers via `npx -y 0xray mcp <cmd>` (no `dist/` paths). Canonical `release.mjs` pipeline. |
@@ -64,7 +66,7 @@ Docs: [guides/autonomy-command](docs-site/docs/guides/autonomy-command.md) · Sk
 
 ### Consolidations
 
-- **One consumer install path** — `postinstall.cjs` → `installAllBridges()` replaces scattered per-platform setup. Mill target is the consumer project, not npm global prefix or `_npx`.
+- **Install, then wear, then setup where needed** — `npm install` runs `postinstall.cjs`, which writes nothing and prints one line: `npx 0xray wear`. `wear` and `unwear` set up or remove the Cursor suit. `npx 0xray setup` writes `.mcp.json` and the OpenCode, Grok, Hermes, and OpenClaw bridges (`install-bridges.cjs`); git hooks only with `--git-hooks`. Mill target is the consumer project, not npm global prefix or `_npx`.
 - **7-server MCP surface** — `.mcp.json` SSOT; Grok plugin and all bridges share `XRAY_MCP_SERVERS`.
 - **Dev vs consumer AGENTS** — `AGENTS.md` (framework) vs `AGENTS-consumer.md` (copied to consumer projects on install).
 - **Release pipeline** — `npm run release:patch|minor|major` → reconcile → gate → artifacts → tag → publish.

package/dist/cli/index.js

@@ -45,52 +45,71 @@ program
     .name("0xray")
     .description("xray: Bulletproof AI orchestration with systematic error prevention")
     .version(version);
-function runSetup() {
-    const setupScript = join(packageRoot, "scripts", "node", "setup.cjs");
-    validateScriptPath(setupScript, "setup script");
-    execSync(`node "${setupScript}"`, { stdio: "inherit", cwd: process.cwd() });
+function runNodeScript(scriptName, args = []) {
+    const script = join(packageRoot, "scripts", "node", scriptName);
+    validateScriptPath(script, scriptName);
+    const quoted = [script, ...args].map((part) => `"${part}"`).join(" ");
+    execSync(`node ${quoted}`, { stdio: "inherit", cwd: process.cwd() });
 }
 program
     .command("install")
     .description("Install xray framework in the current project")
-    .action(async () => {
-    frameworkLogger.log('cli', 'install-start', 'info', { message: 'Installing xray framework...' });
+    .action(() => {
+    frameworkLogger.log('cli', 'install', 'info', { message: 'nothing written' });
+    process.stdout.write("nothing written\n");
+});
+program
+    .command("setup")
+    .description("Set up .mcp.json and the OpenCode, Grok, Hermes, and OpenClaw bridges")
+    .option("--git-hooks", "also install git hooks")
+    .action((opts) => {
+    const args = ["setup"];
+    if (opts.gitHooks)
+        args.push("--git-hooks");
     try {
-        const postinstallScript = join(packageRoot, "scripts", "node", "postinstall.cjs");
-        validateScriptPath(postinstallScript, "postinstall script");
-        execSync(`node "${postinstallScript}"`, { stdio: "inherit", cwd: process.cwd() });
-        frameworkLogger.log('cli', 'install-success', 'info', { message: 'xray framework installed' });
-        // UX banner kept for user visibility post-install (non-removable per exception)
-        console.log("✅ xray framework installed!");
-        console.log("💡 Run 'npx xray setup' for full configuration (hooks, Hermes, symlinks)");
+        runNodeScript("install-bridges.cjs", args);
     }
     catch (error) {
-        frameworkLogger.log('cli', 'install-error', 'error', { error: error instanceof Error ? error.message : String(error) });
-        console.error("❌ Installation failed:", error instanceof Error ? error.message : String(error));
+        frameworkLogger.log("cli", "setup-error", "error", {
+            error: error instanceof Error ? error.message : String(error),
+        });
         process.exit(1);
     }
 });
 program
-    .command("setup")
-    .description("Full framework setup: hooks, Hermes integration, symlinks, MCP paths")
-    .action(runSetup);
+    .command("wear")
+    .description("Wear the 0xray suit in this git checkout")
+    .action(() => {
+    try {
+        runNodeScript("wear-cursor-hooks.cjs");
+    }
+    catch (error) {
+        frameworkLogger.log('cli', 'wear-error', 'error', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+    }
+});
 program
-    .command("init")
-    .description("Initialize xray configuration in the current project")
-    .action(async () => {
-    console.log("🚀 xray CLI: Initializing configuration...");
+    .command("unwear")
+    .description("Remove the 0xray suit and restore the pre-wear hooks file")
+    .action(() => {
     try {
-        const postinstallScript = join(packageRoot, "scripts", "node", "postinstall.cjs");
-        validateScriptPath(postinstallScript, "postinstall script");
-        execSync(`node "${postinstallScript}"`, { stdio: "inherit", cwd: process.cwd() });
-        runSetup();
-        console.log("✅ xray configuration initialized!");
+        runNodeScript("unwear-cursor-hooks.cjs");
     }
     catch (error) {
-        console.error("❌ Initialization failed:", error instanceof Error ? error.message : String(error));
+        frameworkLogger.log('cli', 'unwear-error', 'error', {
+            error: error instanceof Error ? error.message : String(error),
+        });
         process.exit(1);
     }
 });
+program
+    .command("init")
+    .description("Initialize xray configuration in the current project")
+    .action(() => {
+    process.stdout.write("nothing written\n");
+});
 program
     .command("status")
     .description("Show comprehensive xray framework status")
@@ -341,22 +360,7 @@ program
     console.log("===========================");
     console.log("");
     try {
-        console.log("Running postinstall setup to restore configuration...");
-        // Run the postinstaller script (same as install command)
-        const postinstallScript = join(packageRoot, "scripts", "node", "postinstall.cjs");
-        // SECURITY: Validate script path before execution
-        validateScriptPath(postinstallScript, "postinstall script");
-        execSync(`node "${postinstallScript}"`, {
-            stdio: "inherit",
-            cwd: process.cwd(),
-        });
-        console.log("");
-        console.log("🎉 Framework configuration restored successfully!");
-        console.log("");
-        console.log("💡 Next steps:");
-        console.log("  • Restart OpenCode to load the restored configuration");
-        console.log("  • Run: npx xray health (to verify everything works)");
-        console.log("  • Try: @security-auditor scan this project");
+        process.stdout.write("nothing written\n");
     }
     catch (error) {
         console.error("❌ Fix command failed:", error instanceof Error ? error.message : String(error));
@@ -451,6 +455,10 @@ program
         }
         // Check configuration - check for opencode.json or .xray/ (min compat .xray/ fallback for prior 0xRay consumer runtime per Scope Rule; plain xray primary)
         const cwd = process.cwd();
+        const wearMeta = path.join(cwd, ".xray", "state", "cursor-hook-wear", "meta.json");
+        if (!fs.existsSync(wearMeta)) {
+            process.stdout.write("not worn\n");
+        }
         const opencodeConfigPath = path.join(cwd, "opencode.json");
         const xrayDir = getConfigDir(cwd);
         const opencodeExists = fs.existsSync(opencodeConfigPath);

package/dist/integrations/cursor/README.md

@@ -10,10 +10,25 @@ Repertoire is preferred (vendored, dest = named laws). Station + Codex gates sti
 2. Cursor Cloud Agent clones the repo and loads **project** hooks. Desktop Agent Chat does the same when the folder is the workspace.
 3. Hook names are camelCase: `preToolUse`, `preCompact`, `afterFileEdit`, plus Cloud `beforeShellExecution` / `beforeReadFile`. Command is a **relative** `.cursor/hooks/*.sh` — Cloud execs argv[0] without a shell. Do not put `XRAY_AI_PATH=` in `hooks.json`. Stdin is JSON; stdout is JSON.
 4. First `preToolUse` or `afterFileEdit` writes `.xray/state/session-boot.json` + `.xray/state/STATION.md`. After a compact, **Read STATION.md**. The host does not inject it. A multi-repo Cloud wrapper (`/agent` with `repos/xray`) is not a dest heat root, even if a leftover wrapper card exists. Heat the mill under `repos/` and the Read path. Dest `EACCES` fail-opens — a wired hook must not deny every tool.
-5. `install-bridges` also fastens the daemon workspace root when it can see `repos/xray` above the checkout, then pokes local `ReloadAgentSkills` so a mid-session wear binds this daemon. Command stays a relative `.cursor/hooks/*.sh`.
+5. When the package has no dist hook scripts yet, `install-bridges` fastens the daemon workspace root if it can see `repos/xray` above the checkout. A consumer install that already has dist scripts writes only that consumer project directory. `ReloadAgentSkills` still runs so a mid-session wear can bind this daemon. Dogfood commands stay a relative `.cursor/hooks/*.sh`.
 6. `preCompact` is observational (cannot block). Cloud **does** fire it ([hooks.md](https://cursor.com/docs/hooks.md) support matrix: Yes) once hooks are bound and the host actually compacts. Stdout is only `{ "user_message": "…" }` — that is a notice, not a spawn. The spawn id is stdin `conversation_id` (same `bc-`) plus Task's returned agent id. Resume that id. Do not cold-start a twin. Station merge keeps ticket / seed / Durable / unfinished keys.
 
-Copy the consumer template from `src/integrations/cursor/hooks/hooks.json` and the sibling `.sh` runners. `xray-cloud-hook.sh` finds mill JS at `XRAY_AI_PATH`, `../xray`, or `node_modules/0xray` (dist then src). This exo repo wears `src/integrations/cursor/hooks/*.js` so a cloud can run before `npm run build`.
+Copy the consumer template from `src/integrations/cursor/hooks/hooks.json` and the sibling `.sh` runners. This exo repo's own `.cursor/hooks.json` stays on `.cursor/hooks/*.sh` so dogfood can run `src/integrations/cursor/hooks/*.js` before `npm run build`.
+
+Consumer wear (`installCursorBridge` / `wearCursorHooks`, including `npm run wear` in a suited bench) writes only that consumer project's `.cursor/hooks.json`. It does not rewrite a parent checkout's committed hooks, `CURSOR_PROJECT_DIR`, or a `repos/xray` directory above the project. Those outer paths are written only when `wearCursorHooks` is called with `{ outerRoots: true }`, and each one is printed as `cursor-wear: wrote outer hooks at <path>`. The five shipped events (`preToolUse`, `preCompact`, `afterFileEdit`, `beforeShellExecution`, `beforeReadFile`) are added beside existing user entries, unless that event already runs `xray-cloud-hook.sh` (the committed `.cursor/hooks/*.sh` runners). A suited bench that already commits those runners is left byte for byte. The new command, when one is added, is a relative path to the installed package:
+
+`node_modules/0xray/dist/integrations/cursor/hooks/<event>.sh`
+
+Wear does not copy scripts into `.cursor/hooks/`. A user's `.cursor/hooks/<name>.sh` stays as it is, including when the name matches a shipped script, and wear adds the dist command beside it. A `hooks.json` that contains `//` comments is merged in place. A duplicate `hooks` key, or any other file that cannot be parsed safely, makes wear stop and write nothing.
+
+Install the package first (`npm install`), then `npx 0xray wear`. Postinstall writes nothing. Wearing again writes the same bytes and takes a fresh snapshot every time. The pre-wear copy is `<project>/.xray/state/cursor-hook-wear/` (gitignored, and left out of the npm package), so removing `node_modules` does not delete it. When wear creates that folder and the path is not already ignored, it appends the path to `$GIT_DIR/info/exclude`. Wear stores the user bytes, never an already-worn `hooks.json`. Restore with `npx 0xray unwear` (or `node node_modules/0xray/scripts/node/unwear-cursor-hooks.cjs`). Unwear prints `restored` only when the file bytes match that snapshot exactly. If the file changed or cannot be parsed, unwear exits non-zero, says what differs, and leaves the snapshot in place. Wear refuses, and writes nothing, when git is missing, the directory is not a work tree, `GIT_DIR` is bare, or `hooks.json` cannot be parsed.
+
+`xray-cloud-hook.sh` resolution order (first file that exists wins). Each run appends one `cursor-hook-invoke.log` line with `js=` set to the absolute path it executes:
+
+1. Consumer `node_modules/0xray/dist/integrations/cursor/hooks/${JS}`, walking upward from the script directory, then from cwd. A directory whose `package.json` name is `0xray` is skipped, so a factory checkout does not prefer its own `node_modules` or a nested example over `src/`.
+2. Sibling `${JS}` when the runner itself lives under `node_modules/0xray`.
+3. `$XRAY_AI_PATH` `src/` then `dist/` (explicit mill).
+4. Dogfood `src/` at cwd, `../xray`, `repos/xray`, and `$CURSOR_PROJECT_DIR/repos/xray`, then dist at cwd, then `cwd/node_modules/0xray`.
 
 ## Contracts
 
@@ -64,3 +79,7 @@ echo '{"hook_event_name":"preCompact","trigger":"auto","context_tokens":1}' \
 ```
 
 Path C seed + receipt: `examples/cursor-cloud-compact/`. Suited Arm S (real usage, no FILL): `examples/killer-dual/`.
+
+## Known limits
+
+`findLocalExecDaemon` reads the local exec-daemon auth token from `/proc/<pid>/cmdline` (`scripts/node/install-bridges.cjs:927`–`:935`). That read needs a separate security review. Wear does not change it.

package/dist/integrations/cursor/hooks/xray-cloud-hook.sh

@@ -1,6 +1,19 @@
 #!/bin/sh
 # Cloud-safe Cursor hook runner. Command in hooks.json must be a relative path.
 # Do not put env-assignment in hooks.json — Cloud execs argv[0] without a shell.
+#
+# Resolution order (first existing file wins):
+# 1. Consumer install. Walk upward from this script's directory, then from cwd.
+#    Use node_modules/0xray/dist/integrations/cursor/hooks/${JS}.
+#    Skip a directory whose package.json "name" is "0xray" (the factory repo).
+#    That keeps dogfood on src/ and prefers a consumer install over a parent src/.
+# 2. Sibling ${JS} when this runner lives under node_modules/0xray (installed dist).
+# 3. XRAY_AI_PATH, if set: src then dist (explicit mill, dogfood path shape).
+# 4. Dogfood repo source: cwd/src, cwd/../xray/src, cwd/repos/xray/src,
+#    ${CURSOR_PROJECT_DIR}/repos/xray/src, then those roots' dist/, then
+#    cwd/node_modules/0xray (dist then src).
+# Consumer wear points hooks.json at the installed dist *.sh so step 1/2 run
+# even when Cursor's cwd is a parent factory checkout.
 set -eu
 
 EVENT="${1:-preToolUse}"
@@ -11,7 +24,7 @@ REL=""
 pick_mill() {
   mill="$1"
   rel="$2"
-  if [ -f "${mill}/${rel}" ]; then
+  if [ -n "$mill" ] && [ -f "${mill}/${rel}" ]; then
     MILL="$mill"
     REL="$rel"
     return 0
@@ -19,15 +32,54 @@ pick_mill() {
   return 1
 }
 
-if [ -n "${XRAY_AI_PATH:-}" ]; then
+is_xray_package() {
+  pkg="$1/package.json"
+  [ -f "$pkg" ] || return 1
+  grep -q '"name"[[:space:]]*:[[:space:]]*"0xray"' "$pkg" 2>/dev/null || return 1
+  return 0
+}
+
+pick_consumer_from() {
+  dir="$1"
+  [ -n "$dir" ] || return 1
+  while [ -n "$dir" ]; do
+    if ! is_xray_package "$dir"; then
+      if pick_mill "$dir/node_modules/0xray" "dist/integrations/cursor/hooks/${JS}"; then
+        return 0
+      fi
+    fi
+    parent="$(dirname -- "$dir")"
+    if [ "$parent" = "$dir" ]; then
+      break
+    fi
+    dir="$parent"
+  done
+  return 1
+}
+
+HERE="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+
+pick_consumer_from "$HERE" || pick_consumer_from "$(pwd)" || true
+
+if [ -z "$MILL" ]; then
+  case "$HERE" in
+    */node_modules/0xray/*)
+      pick_mill "$HERE" "${JS}" || true
+      ;;
+  esac
+fi
+
+if [ -z "$MILL" ] && [ -n "${XRAY_AI_PATH:-}" ]; then
   pick_mill "${XRAY_AI_PATH}" "src/integrations/cursor/hooks/${JS}" || \
     pick_mill "${XRAY_AI_PATH}" "dist/integrations/cursor/hooks/${JS}" || true
 fi
+
 if [ -z "$MILL" ]; then
   pick_mill "$(pwd)" "src/integrations/cursor/hooks/${JS}" || \
     pick_mill "$(pwd)/../xray" "src/integrations/cursor/hooks/${JS}" || \
     pick_mill "$(pwd)/repos/xray" "src/integrations/cursor/hooks/${JS}" || \
     pick_mill "${CURSOR_PROJECT_DIR:-}/repos/xray" "src/integrations/cursor/hooks/${JS}" || \
+    pick_mill "$(pwd)" "dist/integrations/cursor/hooks/${JS}" || \
     pick_mill "$(pwd)/node_modules/0xray" "dist/integrations/cursor/hooks/${JS}" || \
     pick_mill "$(pwd)/node_modules/0xray" "src/integrations/cursor/hooks/${JS}" || true
 fi
@@ -36,14 +88,19 @@ if [ -n "$MILL" ] && [ -d "$MILL" ]; then
   MILL="$(cd "$MILL" && pwd)"
 fi
 
+JS_ABS=""
+if [ -n "$MILL" ] && [ -n "$REL" ] && [ -f "${MILL}/${REL}" ]; then
+  JS_ABS="$(CDPATH= cd -- "$(dirname -- "${MILL}/${REL}")" && pwd)/$(basename -- "${REL}")"
+fi
+
 NODE_BIN="$(command -v node 2>/dev/null || true)"
 
 log_invoke() {
   dest="$1"
   mkdir -p "${dest}/.xray/state" 2>/dev/null || true
   {
-    printf 'ts=%s event=%s cwd=%s mill=%s node=%s\n' \
-      "$(date -Iseconds)" "$EVENT" "$(pwd)" "${MILL:-MISSING}" "${NODE_BIN:-MISSING}"
+    printf 'ts=%s event=%s cwd=%s mill=%s node=%s js=%s\n' \
+      "$(date -Iseconds)" "$EVENT" "$(pwd)" "${MILL:-MISSING}" "${NODE_BIN:-MISSING}" "${JS_ABS:-MISSING}"
   } >> "${dest}/.xray/state/cursor-hook-invoke.log" 2>/dev/null || true
 }
 
@@ -59,5 +116,5 @@ fi
 
 export XRAY_HOOK_EVENT="$EVENT"
 export XRAY_AI_PATH="$MILL"
-export XRAY_ROOT="$MILL"
+export XRAY_ROOT="${XRAY_ROOT:-$(pwd)}"
 exec "$NODE_BIN" "${MILL}/${REL}"

package/dist/integrations/hooks/plates.cjs

@@ -14,6 +14,7 @@ const PLATE_IDS = Object.freeze([
   "processor",
   "reporting",
   "memory-recall",
+  "house",
 ]);
 
 /** Id token, then extra phrases. Equal top scores recall nothing. */
@@ -61,6 +62,12 @@ const CUES = {
     [/recall(?:s|ed|ing)?\s+(?:a\s+|one\s+|the\s+)?plate/i, 5],
     [/stamp(?:ed|ing)?\s+plates?/i, 4],
   ],
+  house: [
+    [/house init/i, 4],
+    [/HOUSE\.md/i, 4],
+    [/GROK_BOT_HOUSE/i, 4],
+    [/setup-house/i, 4],
+  ],
 };
 
 function platesDir() {

package/dist/integrations/openclaw/plugin/xray-pre-tool/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray-pre-tool",
-  "version": "4.0.27",
+  "version": "4.0.29",
   "private": true,
   "type": "module",
   "description": "0xRay constitution + temperament PreToolUse for OpenClaw",

package/dist/memory-routing/plates.d.ts

@@ -1,4 +1,4 @@
-export declare const PLATE_IDS: readonly ["routing", "governance", "boot", "orchestration", "processor", "reporting", "memory-recall"];
+export declare const PLATE_IDS: readonly ["routing", "governance", "boot", "orchestration", "processor", "reporting", "memory-recall", "house"];
 export type PlateId = (typeof PLATE_IDS)[number];
 export interface PlateStamp {
     id: PlateId;

package/dist/memory-routing/plates.js

@@ -13,6 +13,7 @@ export const PLATE_IDS = [
     'processor',
     'reporting',
     'memory-recall',
+    'house',
 ];
 function isPlateId(value) {
     return PLATE_IDS.includes(value);

package/docs-site/docs/plates/house.md

@@ -0,0 +1,50 @@
+---
+title: House
+sidebar_label: House
+---
+
+# House
+
+One team, one folder. `grok-bot house init` copies `HOUSE.md`, `WAVEBOARD.md`, and `ATTENTION_STATE.md` into `./house`. It does not copy `EXAMPLE.md`. It refuses when a target file is already there. Doctor reads `HOUSE.md` through `GROK_BOT_HOUSE`, or by walking up when that variable is unset, and FAILs with `house/EXAMPLE.md exists — delete it` when that file is present. A wake reads the station, then the board files in `house/`.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ INPUT LAYER                                                  │
+│                                                              │
+│   npx @0xray/grok-bot house init                             │
+│   copies HOUSE.md, WAVEBOARD.md, ATTENTION_STATE.md only     │
+│   refuses if a target file is already there                  │
+└──────────────────────────────┬───────────────────────────────┘
+                               v
+┌──────────────────────────────┼───────────────────────────────┐
+│ PROCESSING LAYER             v                               │
+│                                                              │
+│   ┌──────────────────────────────────────────────────────┐   │
+│   │ HOUSE.md — six headings                              │   │
+│   │ owner · seats · public voice · allowed · ask first   │   │
+│   │ board: WAVEBOARD.md + ATTENTION_STATE.md             │   │
+│   │ the owner approves Allowed before it counts          │   │
+│   └───────────────────────────┬──────────────────────────┘   │
+│                                v                             │
+│   ┌──────────────────────────────────────────────────────┐   │
+│   │ grok-bot doctor                                      │   │
+│   │ GROK_BOT_HOUSE, or walk up for house/HOUSE.md        │   │
+│   │ a set path that is missing warns and does not walk   │   │
+│   │ a line that starts with (example) fails              │   │
+│   │ house/EXAMPLE.md exists — delete it                  │   │
+│   └───────────────────────────┬──────────────────────────┘   │
+└──────────────────────────────┼───────────────────────────────┘
+                               v
+┌──────────────────────────────┼───────────────────────────────┐
+│ OUTPUT LAYER                 v                               │
+│                                                              │
+│   read the station, then house/WAVEBOARD.md                  │
+│   and house/ATTENTION_STATE.md                               │
+│   a missing board file uses templates/house/                 │
+│   one card, one owner                                        │
+│   change the house when the owner says a rule twice          │
+└──────────────────────────────────────────────────────────────┘
+
+```
+
+stamped · 0xray · @0xray/grok-bot 0.1.7

package/docs-site/docs/plates/index.md

@@ -13,4 +13,4 @@ The station card stays the short subsystem table. That table is the index still
 
 The markdown file is the source of truth for that stamp. When the pipeline changes, edit the plate. A worn project may hold a copy at `.xray/state/plates/<id>.md`. The copy is written only when that file is missing, so a local edit stays.
 
-[Routing](./routing.md) · [Governance](./governance.md) · [Boot](./boot.md) · [Orchestration](./orchestration.md) · [Processor](./processor.md) · [Reporting](./reporting.md) · [Memory recall](./memory-recall.md)
+[Routing](./routing.md) · [Governance](./governance.md) · [Boot](./boot.md) · [Orchestration](./orchestration.md) · [Processor](./processor.md) · [Reporting](./reporting.md) · [Memory recall](./memory-recall.md) · [House](./house.md)

package/llms.txt

@@ -12,6 +12,8 @@ Default consumer wear is **mill plant** (`mill` + `inspect`), not a 45-skill / 4
 - Memory scoring rules: [docs/memory-scoring.md](docs/memory-scoring.md). The orchestrator links that file. It does not copy the rules.
 - Host `preCompact` writes the hook line and per-session receipt on the suit mill and on nested consumer wear roots (a bench with local `node_modules/0xray`). A counted cut needs a non-empty generation id and a numeric usage percent.
 - `@0xray/grok-bot`: the general page is `grok-bot/OP-PROC.md`. The team overlay is `house/` and is not in that npm pack. `templates/house/` ships. `grok-bot house init` copies the template and refuses to overwrite. Doctor uses `GROK_BOT_HOUSE` when set, otherwise walks up from the working directory for `house/HOUSE.md`.
+- MCP servers start through `scripts/node/mcp-launch.cjs`. They see PATH, HOME, and XRAY_ROOT, plus the names on their keep list. Tokens such as NPM_TOKEN are not inherited. User env values stay out of argv. Postinstall keeps user edits to AGENTS.md, `.mcp.json`, and `opencode.json`. `house init` does not copy EXAMPLE.md. Doctor FAILs while `house/EXAMPLE.md` exists. Inspect has a machinePlugin check. The Cursor hook defaults XRAY_ROOT to the suit directory.
+- `npm install` only creates the relative `node_modules/@0xray/repertoire` link to the vendored repertoire and prints `npx 0xray wear`. Run `npx 0xray wear` after install; it writes only the consumer project's `.cursor/hooks.json`. `npx 0xray unwear` restores the pre-wear snapshot.
 
 - `npx @0xray/foundry mint --skip-live` — re-fasten mill plant, then inspect.
 - `npx @0xray/foundry inspect --skip-live` — plant-vs-worn, receipt, CI. Chat is not a receipt.

package/package.json

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

package/scripts/foundry/inspect.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Mill inspect organ. Runs the six plant checks plus observational harness.
+ * Mill inspect organ. Runs the plant checks, a machinePlugin check, and observational harness.
  * Not an 8th MCP. Not PPE. Does not fasten hooks or Repertoire.
  *
  *   npx @0xray/foundry inspect [--skip-live] [--go] [--go-out PATH]
@@ -515,7 +515,7 @@ export function packagesToProbe(root) {
   });
 }
 
-function checkIsolatedHome(root, env = process.env, machine = mint.machineHome()) {
+export function checkIsolatedHome(root, env = process.env, machine = mint.machineHome()) {
   const isolated = isIsolatedHome(env, machine);
   const machinePlugin = machineGrokPluginDir(machine);
   const dests = mint.resolveGrokPluginDests(root, env, machine);
@@ -542,6 +542,50 @@ function checkIsolatedHome(root, env = process.env, machine = mint.machineHome()
   };
 }
 
+function isXrayPluginName(name) {
+  return name === "0xray" || name.startsWith("0xray");
+}
+
+/** 0xray plugin dirs under the machine HOME's grok plugin folder. */
+export function machineXrayPluginPaths(machine = mint.machineHome()) {
+  const pluginsDir = path.join(machine, ".grok", "plugins");
+  if (!fs.existsSync(pluginsDir)) return [];
+  let names;
+  try {
+    names = fs.readdirSync(pluginsDir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((name) => isXrayPluginName(name))
+    .sort()
+    .map((name) => path.join(pluginsDir, name));
+}
+
+/**
+ * `isolated` stays HOME != machine home. This check is whether a machine-level
+ * 0xray Grok plugin exists. Overall inspect ok is false when this check fails.
+ */
+export function checkMachinePlugin(machine = mint.machineHome()) {
+  const machinePlugin = machineGrokPluginDir(machine);
+  const hits = machineXrayPluginPaths(machine);
+  if (hits.length > 0) {
+    return {
+      id: "machinePlugin",
+      ok: false,
+      machinePlugin,
+      hits,
+      detail: `machine-level ${hits.join(", ")} exists — delete it`,
+    };
+  }
+  return {
+    id: "machinePlugin",
+    ok: true,
+    machinePlugin,
+    hits: [],
+  };
+}
+
 export async function inspectSuit(root, opts = {}) {
   const millRoot = opts.millRoot || millPackageDir();
   const fetchFn = opts.fetch || fetch;
@@ -584,6 +628,7 @@ export async function inspectSuit(root, opts = {}) {
   }
 
   checks.push(checkIsolatedHome(root, env, machineHome));
+  checks.push(checkMachinePlugin(machineHome));
   checks.push(checkHarness(root, requireHarness));
 
   const failed = checks.filter((c) => c.ok === false);